97 lines
4.8 KiB
Markdown
97 lines
4.8 KiB
Markdown
|
# rony-llm-agent — Documentación
|
||
|
|
|
||
|
|
> 🌐 **Idioma:** [English](README.md) | [Español](README.es.md)
|
||
|
|
|
||
|
|
|
||
|
|
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/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 estos docs (propios de la librería):
|
||
|
|
|
||
|
|
- [`./architecture.md`](./architecture.md) — Arquitectura core (interfaces, agent loop, sandbox, seguridad)
|
||
|
|
- [`./components.md`](./components.md) — Referencia por paquete
|
||
|
|
- [`./phase2.md`](./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.
|