rony-llm-agent/docs/components.md

# 📦 Components Reference

> **Referencia detallada por paquete.** Cada paquete tiene su README en `pkg/<name>/README.md` — este documento es el overview de alto nivel y cómo se conectan entre sí.

## 📚 Tabla de paquetes

| Paquete | Responsabilidad | README |
|---|---|---|
| `pkg/agent` | Bucle iterativo, termination, approval hooks | [`pkg/agent/README.md`](../pkg/agent/README.md) |
| `pkg/llm` | `LLMClient` interface, streaming, providers | [`pkg/llm/README.md`](../pkg/llm/README.md) |
| `pkg/tools` | Tool registry, JSON Schema, sandbox | [`pkg/tools/README.md`](../pkg/tools/README.md) |
| `pkg/persona` | Persona system, AGENTS.md discovery | [`pkg/persona/README.md`](../pkg/persona/README.md) |
| `pkg/rag` | Memoria, embeddings, vector DB | [`pkg/rag/README.md`](../pkg/rag/README.md) |
| `pkg/config` | YAML loading, precedencia | [`pkg/config/README.md`](../pkg/config/README.md) |

## 🗺️ Cómo se conectan

```
                    ┌──────────────────┐
                    │   pkg/agent      │  ← Orquesta todo
                    │   (Loop)         │
                    └────────┬─────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
        ▼                    ▼                    ▼
   ┌─────────┐         ┌──────────┐         ┌──────────┐
   │ pkg/llm │         │pkg/tools │         │pkg/persona│
   │ (LLM    │         │ (Tools + │         │ (Persona)│
   │ Client) │         │ Registry)│         │          │
   └────┬────┘         └────┬─────┘         └──────────┘
        │                   │
        │ providers         │ sandbox
        ▼                   ▼
   ┌──────────┐       ┌────────────┐
   │ adapters │       │ os.Root    │
   │ (OpenAI, │       │ (kernel)   │
   │ Anthropic│       └────────────┘
   │ Ollama...)│
   └──────────┘

   ┌─────────┐  ┌─────────┐  ┌──────────┐
   │ pkg/rag │  │pkg/config│  │ examples │
   │ (Memory)│  │ (YAML)   │  │ (demo)  │
   └─────────┘  └─────────┘  └──────────┘
```

## 🔄 Flujo típico de uso

```go
// 1. Cargar config
cfg, _ := config.Load(ctx, workdir)

// 2. Crear LLM client desde config
llmClient, _ := llm.NewFromConfig(cfg.Provider)

// 3. Cargar persona (descubre AGENTS.md automáticamente)
p, _ := persona.Discover(ctx, workdir)

// 4. Crear tool registry y registrar tools del producto
registry := tools.NewRegistry()
// (producto registra sus tools específicas aquí)

// 5. Crear memory (si el producto lo usa)
memory, _ := rag.NewFromConfig(cfg.RAG)

// 6. Crear agent loop
loop := agent.New(agent.Config{
    LLM:     llmClient,
    Persona: p,
    Tools:   registry,
    Memory:  memory,
    Sandbox: tools.NewSandbox(workdir),
})

// 7. Ejecutar
resp, _ := loop.Run(ctx, "Refactoriza auth.go")
```

## 🎯 Decisión: ¿qué paquete usar para qué?

| Necesito... | Usar... |
|---|---|
| Llamar a un LLM | `pkg/llm/` |
| Permitir que el LLM invoque funciones | `pkg/tools/` |
| Construir el system prompt | `pkg/persona/` |
| Recordar contexto entre sesiones | `pkg/rag/` |
| Configurar el comportamiento desde YAML | `pkg/config/` |
| Ejecutar el bucle completo (LLM + tools + memoria) | `pkg/agent/` |
| Validar paths de forma segura | `pkg/tools/sandbox/` |

## 📝 Ejemplos completos

Ver [`examples/`](../../examples/) — ejemplos standalone que muestran casos de uso comunes.

| Ejemplo | Demuestra |
|---|---|
| `examples/simple_chat/` | Chat básico sin tools |
| `examples/chat_with_tools/` | Chat con tools custom |
| `examples/rag_qa/` | Q&A sobre documentos |
| `examples/multi_agent/` | Orquestación de sub-agents |
| `examples/streaming_ui/` | Integración con TUI |

> 📌 Los ejemplos se crean cuando el código base está implementado. Por ahora cada `pkg/*/README.md` tiene un snippet mínimo de uso.

## 🔌 Adapters incluidos

### LLM Providers (`pkg/llm/providers/`)

| Provider | Import | Modelos |
|---|---|---|
| OpenAI | `providers/openai` | gpt-4o, gpt-4o-mini, gpt-4-turbo |
| Anthropic | `providers/anthropic` | claude-sonnet-4.5, claude-haiku-4 |
| Ollama | `providers/ollama` | llama3.1, qwen2.5, mistral |
| llama.cpp | `providers/llamacpp` | Custom GGUF models |

### Vector DBs (`pkg/rag/backends/`)

| Backend | Estado | Notas |
|---|---|---|
| ChromaDB embedded | ✅ Estable | Default, simple API |
| Qdrant embedded | 🚧 En desarrollo | Para >100k docs |
| SQLite + sqlite-vec | 📋 Planeado | Zero-deps |

### Embeddings (`pkg/rag/embeddings/`)

| Provider | Modelos |
|---|---|
| Ollama | nomic-embed-text, bge-m3, mxbai-embed-large |
| Local ONNX | all-MiniLM-L6-v2 (fallback) |

## 🛠️ Cómo añadir un componente nuevo

**Ejemplo: añadir un nuevo LLM provider**

```bash
mkdir -p pkg/llm/providers/myprovider
touch pkg/llm/providers/myprovider/client.go
touch pkg/llm/providers/myprovider/client_test.go
```

```go
// pkg/llm/providers/myprovider/client.go
package myprovider

import (
    "context"
    "github.com/VictorVargas/go-llm-agent/pkg/llm"
)

type Client struct {
    apiKey string
    model  string
}

func New(cfg Config) (*Client, error) {
    return &Client{apiKey: cfg.APIKey, model: cfg.Model}, nil
}

func (c *Client) Generate(ctx context.Context, req llm.CompletionRequest) (llm.CompletionResponse, error) {
    // implement against MyProvider API
}

func (c *Client) Stream(ctx context.Context, req llm.CompletionRequest) iter.Seq2[llm.StreamChunk, error] {
    // implement
}

func (c *Client) Name() string { return "myprovider" }
func (c *Client) Capabilities() llm.ProviderCapabilities { /* ... */ }
```

Reglas:
- ✅ Implementar `LLMClient` interface completa
- ✅ Tests con `httptest.NewServer` para mockear la API
- ✅ Documentar en `pkg/llm/providers/myprovider/README.md` (opcional pero recomendado)
- ✅ Registrar en `llm.NewFromConfig()` para que sea elegible via YAML

## 📖 Documentos relacionados

- [`architecture.md`](./architecture.md) — Arquitectura y core interfaces
- [`phase2.md`](./phase2.md) — Features avanzadas (MCP, RAG completo, Skills, etc.)
- [Productos que usan esta librería](https://github.com/VictorVargas)