rony-llm-agent/docs/README.md

# rony-llm-agent — Documentation

> 🌐 **Language:** [English](./README.md) | [Español](./README.es.md)

Technical documentation for the library.

## 📐 Architecture

```
┌────────────────────────────────────────────────────────────────┐
│                     rony-llm-agent (pkg/)                       │
│                                                                │
│   ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐    │
│   │   agent      │  │   persona    │  │      tools       │    │
│   │              │  │              │  │                  │    │
│   │  Agent loop  │◄─┤  Persona     │  │  Tool registry   │    │
│   │  with guard- │  │  + AGENTS.md │  │  + JSON Schema   │    │
│   │  rails       │  │  discovery   │  │  + execution     │    │
│   └──────┬───────┘  └──────────────┘  └────────┬─────────┘    │
│          │                                      │              │
│          ▼                                      ▼              │
│   ┌──────────────┐                      ┌──────────────┐      │
│   │     llm      │                      │     rag      │      │
│   │              │                      │              │      │
│   │  LLMClient   │                      │  Memory +    │      │
│   │  interface + │                      │  Embeddings  │      │
│   │  providers   │                      │  + VectorDB  │      │
│   └──────────────┘                      └──────────────┘      │
│                                                                │
└────────────────────────────────────────────────────────────────┘
```

## 📦 Packages

| Package | Responsibility | Docs |
|---|---|---|
| `pkg/agent` | Iterative loop, termination conditions, approval gates | [View](../pkg/agent/README.md) |
| `pkg/llm` | `LLMClient` interface, streaming, providers | [View](../pkg/llm/README.md) |
| `pkg/rag` | Memory, embeddings, semantic search | [View](../pkg/rag/README.md) |
| `pkg/persona` | System prompts, AGENTS.md, few-shot examples | [View](../pkg/persona/README.md) |
| `pkg/tools` | Tool registry, JSON Schema, sandboxing | [View](../pkg/tools/README.md) |
| `pkg/config` | YAML loading, precedence, env override | [View](../pkg/config/README.md) |

## 🎯 Design principles

### 1. Streaming-first
Uses `iter.Seq2[T, error]` from Go 1.23+ for natural streaming:

```go
for token, err := range llmClient.StreamTokens(ctx, req) {
    if err != nil { return err }
    fmt.Print(token)
}
```

### 2. Pure Hexagonal
Each package exposes interfaces, concrete implementations are separated:

```go
// pkg/rag/rag.go (port)
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. Secure by default
- `os.Root` for filesystem sandbox (Go 1.24+)
- Approval gates before destructive tools
- Bash sandbox with denylist + timeout
- Optional network egress control

### 4. Zero magic
No reflection, no code generation, no DSLs. Everything is idiomatic and explicit Go.

## 🔄 Versioning

- **Strict semver** (`vMAJOR.MINOR.PATCH`)
- **MAJOR**: breaking changes in `pkg/` (interfaces, signatures, public types)
- **MINOR**: new features, new packages, new adapters
- **PATCH**: bugfixes

Private adapters (`pkg/llm/providers/openai/`) can change without a MAJOR bump if the `LLMClient` interface doesn't change.

## 🚧 Current status

⚠️ **This library is in active design.** The code is not implemented yet. The complete specification is in these docs (own of the library):

- [`./architecture.md`](./architecture.md) — Core architecture (interfaces, agent loop, sandbox, security)
- [`./components.md`](./components.md) — Reference per package
- [`./phase2.md`](./phase2.md) — Advanced features (MCP, full RAG, Skills, Sub-agents, Observability)

Once `rony-harness/` is implemented, this library will be extracted as real code, following these specs.