rony-llm-agent/docs/README.md

rony-llm-agent — Documentation

🌐 Language: English | Español

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/llm	LLMClient interface, streaming, providers	View
pkg/rag	Memory, embeddings, semantic search	View
pkg/persona	System prompts, AGENTS.md, few-shot examples	View
pkg/tools	Tool registry, JSON Schema, sandboxing	View
pkg/config	YAML loading, precedence, env override	View

🎯 Design principles

1. Streaming-first

Uses iter.Seq2[T, error] from Go 1.23+ for natural streaming:

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:

// 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 — Core architecture (interfaces, agent loop, sandbox, security)
• ./components.md — Reference per package
• ./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.