# go-llm-agent

> 🌐 **Language:** [English](./README.md) | [Español](./README.es.md)
>
> 🔑 **Reusable core library** for building LLM agents in Go.

This library is the heart of several Victor Vargas projects:

- [`harness`](https://github.com/VictorVargas/rony-harness) — AI agent harness for software development (TUI)
- [`chat-bot`](https://github.com/VictorVargas/rony-chat-bot) — HTTP chatbot for portfolios and websites

It provides all the **generic** logic of an LLM agent:

| Component | Location | Responsibility |
|---|---|---|
| **Agent loop** | `pkg/agent/` | Iterative loop with guardrails |
| **LLM clients** | `pkg/llm/` | Multi-provider abstraction (OpenAI, Anthropic, Ollama) |
| **RAG / memory** | `pkg/rag/` | Short and long-term memory with semantic search |
| **Persona system** | `pkg/persona/` | Configurable system prompts + AGENTS.md discovery |
| **Tool registry** | `pkg/tools/` | JSON Schema + execution sandbox |
| **Config loading** | `pkg/config/` | YAML loading with hierarchical precedence |

## 🎯 Philosophy

- **Reusable, not opinionated.** Does not force a UI type, deployment, or use case.
- **Pure Hexagonal.** Ports & adapters — every external dependency is behind an interface.
- **Streaming-first.** Uses `iter.Seq2` from Go 1.23+ for natural streaming without callbacks.
- **Secure by default.** Filesystem path sandbox with `os.Root` (Go 1.24+).
- **Zero magic.** No reflection, no codegen, no DSLs. Idiomatic and explicit Go.
- **YAML configurable.** Everything that affects behavior is declarative.

## 📦 Installation

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

## 🚀 Basic usage

```go
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. Create LLM client
    llmClient, _ := llm.NewAnthropicClient(llm.AnthropicConfig{
        APIKey: os.Getenv("ANTHROPIC_API_KEY"),
        Model:  "claude-sonnet-4.5",
    })

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

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

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

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

## 🔌 Included adapters

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

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

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

| Backend | Status |
|---|---|
| ChromaDB embedded | ✅ Stable |
| Qdrant embedded | 🚧 In development |
| SQLite + sqlite-vec | 📋 Planned |

### 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/
```

Includes `MockLLMClient` for deterministic tests without burning API calls.

## 📐 Versions

- **Go minimum:** 1.26 (uses `os.Root`, `iter.Seq`, `unique.Handle`, container-aware GOMAXPROCS)
- **Versioning policy:** Strict semver. API breaking changes only on MAJOR.

## 📄 License

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

## 🔗 Projects that use this library

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

## 📚 Additional documentation

- [Architecture overview](./docs/README.md)
- [Architecture (core)](./docs/architecture.md)
- [Components reference](./docs/components.md)
- [Phase 2 features](./docs/phase2.md)