rony-llm-agent/README.md

# go-llm-agent

> 🔑 **Librería core reutilizable** para construir agentes LLM en Go.

Esta librería es el corazón de varios proyectos de Victor Vargas:
- [`harness`](https://github.com/VictorVargas/harness) — AI agent harness para desarrollo de software (TUI)
- [`chat-bot`](https://github.com/VictorVargas/chat-bot) — Chatbot HTTP para portfolios y sitios web

Provee toda la lógica **genérica** de un agente LLM:

| Componente | Ubicación | Responsabilidad |
|---|---|---|
| **Agent loop** | `pkg/agent/` | Bucle iterativo con guardrails |
| **LLM clients** | `pkg/llm/` | Abstracción multi-provider (OpenAI, Anthropic, Ollama) |
| **RAG / memoria** | `pkg/rag/` | Memoria de corto y largo plazo con búsqueda semántica |
| **Persona system** | `pkg/persona/` | System prompts configurables + AGENTS.md discovery |
| **Tool registry** | `pkg/tools/` | JSON Schema + execution sandbox |
| **Config loading** | `pkg/config/` | Carga de YAML con precedencia jerárquica |

## 🎯 Filosofía

- **Reusable, no opinionated.** No fuerza un tipo de UI, deployment, ni use case.
- **Hexagonal.** Ports & adapters permiten sustituir cualquier pieza.
- **Streaming-first.** Usa `iter.Seq2` de Go 1.23+ para streaming sin boilerplate.
- **Seguridad por defecto.** Sandbox de paths con `os.Root` (Go 1.24+).

## 📦 Instalación

```bash
go get github.com/VictorVargas/go-llm-agent
```

## 🔧 Setup del proyecto (si vas a contribuir)

```bash
git clone https://github.com/VictorVargas/go-llm-agent.git
cd go-llm-agent

# El go.mod ya existe con module + go version
# Las dependencias se agregan automáticamente cuando escribes código:

# 1. Escribe tu código importando paquetes
# 2. Ejecuta:
go mod tidy    # resuelve imports → actualiza go.mod + crea go.sum
```

## 🚀 Uso básico

```go
package main

import (
    "context"
    "fmt"
    "github.com/VictorVargas/go-llm-agent/pkg/agent"
    "github.com/VictorVargas/go-llm-agent/pkg/llm"
    "github.com/VictorVargas/go-llm-agent/pkg/persona"
)

func main() {
    // 1. Crear cliente LLM
    llmClient, _ := llm.NewAnthropicClient(llm.AnthropicConfig{
        APIKey: os.Getenv("ANTHROPIC_API_KEY"),
        Model:  "claude-sonnet-4.5",
    })

    // 2. Cargar persona
    p := persona.Load("./persona.yaml")

    // 3. Crear agent loop
    loop := agent.New(agent.Config{
        LLM:         llmClient,
        Persona:     p,
        MaxIters:    50,
        Sandbox:     agent.NewSandbox("./workspace"),
    })

    // 4. Ejecutar
    resp, err := loop.Run(context.Background(), "Refactoriza auth.go")
    if err != nil { panic(err) }

    fmt.Println(resp.Content)
}
```

## 🔌 Adapters incluidos

### LLM Providers (`pkg/llm/providers/`)

| Provider | Import | Modelos |
|---|---|---|
| OpenAI | `llm/providers/openai` | gpt-4o, gpt-4o-mini, gpt-4-turbo |
| Anthropic | `llm/providers/anthropic` | claude-sonnet-4.5, claude-haiku-4 |
| Ollama | `llm/providers/ollama` | llama3.1, qwen2.5, mistral, etc. |
| llama.cpp | `llm/providers/llamacpp` | Custom GGUF models |

### Vector DBs (`pkg/rag/backends/`)

| Backend | Estado |
|---|---|
| ChromaDB embedded | ✅ Estable |
| Qdrant embedded | 🚧 En desarrollo |
| SQLite + sqlite-vec | 📋 Planeado |

### Embeddings (`pkg/rag/embeddings/`)

- Ollama embeddings (nomic-embed-text, bge-m3, etc.)
- Local sentence-transformers via ONNX

## 🧪 Testing

```bash
go test ./...
go test -race ./...
go test -bench=. ./pkg/agent/
```

Incluye `MockLLMClient` para tests deterministas sin gastar API calls.

## 📐 Versiones

- **Go mínimo:** 1.26 (usa `os.Root`, `iter.Seq`, `unique.Handle`, container-aware GOMAXPROCS)
- **Política de versionado:** Semver estricto. API breaking changes solo en MAJOR.

## 📄 Licencia

MIT — ver [`LICENSE`](./LICENSE).

## 🔗 Proyectos que usan esta librería

- [`VictorVargas/harness`](https://github.com/VictorVargas/harness) — TUI agent para software dev
- [`VictorVargas/chat-bot`](https://github.com/VictorVargas/chat-bot) — HTTP chatbot

## 📚 Documentación adicional

- [Architecture overview](./docs/README.md)
- [Design decisions](./docs/architecture.md) (próximamente)