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/llm	LLMClient interface, streaming, providers	pkg/llm/README.md
pkg/tools	Tool registry, JSON Schema, sandbox	pkg/tools/README.md
pkg/persona	Persona system, AGENTS.md discovery	pkg/persona/README.md
pkg/rag	Memoria, embeddings, vector DB	pkg/rag/README.md
pkg/config	YAML loading, precedencia	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

// 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/ — 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

mkdir -p pkg/llm/providers/myprovider
touch pkg/llm/providers/myprovider/client.go
touch pkg/llm/providers/myprovider/client_test.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 — Arquitectura y core interfaces
• phase2.md — Features avanzadas (MCP, RAG completo, Skills, etc.)
• Productos que usan esta librería