go-llm-agent — Documentación

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

📐 Arquitectura

┌────────────────────────────────────────────────────────────────┐
│                     go-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 los design docs de los proyectos que la consumen:

VictorVargas/harness/docs/architecture.md — Define los requirements
VictorVargas/harness/docs/phase2.md — Features avanzadas

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

4.7 KiB Raw Blame History