93 lines
4.7 KiB
Markdown
93 lines
4.7 KiB
Markdown
|
# 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/agent/README.md) |
|
||
|
|
| `pkg/llm` | `LLMClient` interface, streaming, providers | [Ver](../pkg/llm/README.md) |
|
||
|
|
| `pkg/rag` | Memoria, embeddings, búsqueda semántica | [Ver](../pkg/rag/README.md) |
|
||
|
|
| `pkg/persona` | System prompts, AGENTS.md, few-shot examples | [Ver](../pkg/persona/README.md) |
|
||
|
|
| `pkg/tools` | Tool registry, JSON Schema, sandboxing | [Ver](../pkg/tools/README.md) |
|
||
|
|
| `pkg/config` | YAML loading, precedence, env override | [Ver](../pkg/config/README.md) |
|
||
|
|
|
||
|
|
## 🎯 Principios de diseño
|
||
|
|
|
||
|
|
### 1. Streaming-first
|
||
|
|
Usa `iter.Seq2[T, error]` de Go 1.23+ para streaming natural:
|
||
|
|
|
||
|
|
```go
|
||
|
|
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:
|
||
|
|
|
||
|
|
```go
|
||
|
|
// 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`](https://github.com/VictorVargas/harness/blob/main/docs/architecture.md) — Define los requirements
|
||
|
|
- [`VictorVargas/harness/docs/phase2.md`](https://github.com/VictorVargas/harness/blob/main/docs/phase2.md) — Features avanzadas
|
||
|
|
|
||
|
|
Una vez que `harness/` esté implementado, esta librería se extraerá como código real.
|