rony-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 — AI agent harness para desarrollo de software (TUI)
• 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

go get github.com/VictorVargas/rony-llm-agent

🔧 Setup del proyecto (si vas a contribuir)

git clone https://github.com/VictorVargas/rony-llm-agent.git
cd rony-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

package main

import (
    "context"
    "fmt"
    "github.com/VictorVargas/rony-llm-agent/pkg/agent"
    "github.com/VictorVargas/rony-llm-agent/pkg/llm"
    "github.com/VictorVargas/rony-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

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.

🔗 Proyectos que usan esta librería

• VictorVargas/rony-harness — TUI agent para software dev
• VictorVargas/rony-chat-bot — HTTP chatbot

📚 Documentación adicional

• Architecture overview
• Architecture (core)
• Components reference
• Phase 2 features