# 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.