rony-llm-agent/docs/components.md

📦 Components Reference

Detailed reference per package. Each package has its README in pkg/<name>/README.md — this document is the high-level overview and how they connect.

📚 Packages table

Package	Responsibility	README
pkg/agent	Iterative loop, termination, approval hooks	pkg/agent/README.md
pkg/llm	LLMClient interface, streaming, providers	pkg/llm/README.md
pkg/tools	Tool registry, JSON Schema, sandbox	pkg/tools/README.md
pkg/persona	Persona system, AGENTS.md discovery	pkg/persona/README.md
pkg/rag	Memory, embeddings, vector DB	pkg/rag/README.md
pkg/config	YAML loading, precedence	pkg/config/README.md

🗺️ How they connect

                    ┌──────────────────┐
                    │   pkg/agent      │  ← Orchestrates everything
                    │   (Loop)         │
                    └────────┬─────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
        ▼                    ▼                    ▼
   ┌─────────┐         ┌──────────┐         ┌──────────┐
   │ pkg/llm │         │pkg/tools │         │pkg/persona│
   │ (LLM    │         │ (Tools + │         │ (Persona)│
   │ Client) │         │ Registry)│         │          │
   └────┬────┘         └────┬─────┘         └──────────┘
        │                   │
        │ providers         │ sandbox
        ▼                   ▼
   ┌──────────┐       ┌────────────┐
   │ adapters │       │ os.Root    │
   │ (OpenAI, │       │ (kernel)   │
   │ Anthropic│       └────────────┘
   │ Ollama...)│
   └──────────┘

   ┌─────────┐  ┌─────────┐  ┌──────────┐
   │ pkg/rag │  │pkg/config│  │ examples │
   │ (Memory)│  │ (YAML)   │  │ (demo)  │
   └─────────┘  └─────────┘  └──────────┘

🔄 Typical usage flow

// 1. Load config
cfg, _ := config.Load(ctx, workdir)

// 2. Create LLM client from config
llmClient, _ := llm.NewFromConfig(cfg.Provider)

// 3. Load persona (auto-discovers AGENTS.md)
p, _ := persona.Discover(ctx, workdir)

// 4. Create tool registry and register product-specific tools
registry := tools.NewRegistry()
// (product registers its specific tools here)

// 5. Create memory (if product uses it)
memory, _ := rag.NewFromConfig(cfg.RAG)

// 6. Create agent loop
loop := agent.New(agent.Config{
    LLM:     llmClient,
    Persona: p,
    Tools:   registry,
    Memory:  memory,
    Sandbox: tools.NewSandbox(workdir),
})

// 7. Run
resp, _ := loop.Run(ctx, "Refactor auth.go")

🎯 Decision: which package to use for what

I need...	Use...
To call an LLM	pkg/llm/
To let the LLM invoke functions	pkg/tools/
To build the system prompt	pkg/persona/
To remember context between sessions	pkg/rag/
To configure behavior from YAML	pkg/config/
To run the complete loop (LLM + tools + memory)	pkg/agent/
To validate paths securely	pkg/tools/sandbox/

📝 Complete examples

See examples/ — standalone examples that show common use cases.

Example	Demonstrates
examples/simple_chat/	Basic chat without tools
examples/chat_with_tools/	Chat with custom tools
examples/rag_qa/	Q&A over documents
examples/multi_agent/	Sub-agent orchestration
examples/streaming_ui/	TUI integration

📌 Examples are created when the codebase is implemented. For now each pkg/*/README.md has a minimal usage snippet.

🔌 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
llama.cpp	providers/llamacpp	Custom GGUF models

Vector DBs (pkg/rag/backends/)

Backend	Status	Notes
ChromaDB embedded	✅ Stable	Default, simple API
Qdrant embedded	🚧 In development	For >100k docs
SQLite + sqlite-vec	📋 Planned	Zero-deps

Embeddings (pkg/rag/embeddings/)

Provider	Models
Ollama	nomic-embed-text, bge-m3, mxbai-embed-large
Local ONNX	all-MiniLM-L6-v2 (fallback)

🛠️ How to add a new component

Example: add a new LLM provider

mkdir -p pkg/llm/providers/myprovider
touch pkg/llm/providers/myprovider/client.go
touch pkg/llm/providers/myprovider/client_test.go

// pkg/llm/providers/myprovider/client.go
package myprovider

import (
    "context"
    "github.com/VictorVargas/rony-llm-agent/pkg/llm"
)

type Client struct {
    apiKey string
    model  string
}

func New(cfg Config) (*Client, error) {
    return &Client{apiKey: cfg.APIKey, model: cfg.Model}, nil
}

func (c *Client) Generate(ctx context.Context, req llm.CompletionRequest) (llm.CompletionResponse, error) {
    // implement against MyProvider API
}

func (c *Client) Stream(ctx context.Context, req llm.CompletionRequest) iter.Seq2[llm.StreamChunk, error] {
    // implement
}

func (c *Client) Name() string { return "myprovider" }
func (c *Client) Capabilities() llm.ProviderCapabilities { /* ... */ }

Rules:

• ✅ Implement the complete LLMClient interface
• ✅ Tests with httptest.NewServer to mock the API
• ✅ Document in pkg/llm/providers/myprovider/README.md (optional but recommended)
• ✅ Register in llm.NewFromConfig() to be eligible via YAML

📖 Related documents

• architecture.md — Architecture and core interfaces
• phase2.md — Advanced features (MCP, full RAG, Skills, etc.)
• Products that use this library