rony-llm-agent/docs

rony-llm-agent — Documentación

Documentación técnica detallada de la librería.

📐 Arquitectura

┌────────────────────────────────────────────────────────────────┐
│                     rony-llm-agent (pkg/)                       │
│                                                                │
│   ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐    │
│   │   agent      │  │   persona    │  │      tools       │    │
│   │              │  │              │  │                  │    │
│   │  Agent loop  │◄─┤  Persona     │  │  Tool registry   │    │
│   │  con guard-  │  │  + AGENTS.md │  │  + JSON Schema   │    │
│   │  rails       │  │  discovery   │  │  + execution     │    │
│   └──────┬───────┘  └──────────────┘  └────────┬─────────┘    │
│          │                                      │              │
│          ▼                                      ▼              │
│   ┌──────────────┐                      ┌──────────────┐      │
│   │     llm      │                      │     rag      │      │
│   │              │                      │              │      │
│   │  LLMClient   │                      │  Memory +    │      │
│   │  interface + │                      │  Embeddings  │      │
│   │  providers   │                      │  + VectorDB  │      │
│   └──────────────┘                      └──────────────┘      │
│                                                                │
└────────────────────────────────────────────────────────────────┘

📦 Paquetes

Paquete	Responsabilidad	Docs
pkg/agent	Bucle iterativo, termination conditions, approval gates	Ver
pkg/llm	LLMClient interface, streaming, providers	Ver
pkg/rag	Memoria, embeddings, búsqueda semántica	Ver
pkg/persona	System prompts, AGENTS.md, few-shot examples	Ver
pkg/tools	Tool registry, JSON Schema, sandboxing	Ver
pkg/config	YAML loading, precedence, env override	Ver

🎯 Principios de diseño

1. Streaming-first

Usa iter.Seq2[T, error] de Go 1.23+ para streaming natural:

for token, err := range llmClient.StreamTokens(ctx, req) {
    if err != nil { return err }
    fmt.Print(token)
}

2. Hexagonal puro

Cada paquete expone interfaces, las implementaciones concretas están separadas:

// pkg/rag/rag.go (puerto)
type VectorDB interface {
    Search(ctx context.Context, embedding []float32, topK int) ([]Document, error)
}

// pkg/rag/backends/chroma/chroma.go (adapter)
type ChromaDB struct { ... }
func (c *ChromaDB) Search(...) { ... }

3. Seguridad por defecto

• os.Root para sandbox de filesystem (Go 1.24+)
• Approval gates antes de tools destructivos
• Bash sandbox con denylist + timeout
• Network egress control opcional

4. Zero magic

No hay reflection, no hay code generation, no hay DSLs. Todo es Go idiomático y explícito.

🔄 Versionado

• Semver estricto (vMAJOR.MINOR.PATCH)
• MAJOR: breaking changes en pkg/ (interfaces, signatures, tipos públicos)
• MINOR: nuevas features, nuevos paquetes, nuevos adapters
• PATCH: bugfixes

Los adapters privados (pkg/llm/providers/openai/) pueden cambiar sin bump de MAJOR si la interfaz LLMClient no cambia.

🚧 Estado actual

⚠️ Esta librería está en diseño activo. El código todavía no está implementado. La especificación completa está en estos docs (propios de la librería):

• ./architecture.md — Arquitectura core (interfaces, agent loop, sandbox, seguridad)
• ./components.md — Referencia por paquete
• ./phase2.md — Features avanzadas (MCP, RAG completo, Skills, Sub-agents, Observability)

Una vez que harness/ esté implementado, esta librería se extraerá como código real, siguiendo estas specs.