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/agent/README.md) |
| `pkg/llm` | `LLMClient` interface, streaming, providers | [`pkg/llm/README.md`](../pkg/llm/README.md) |
| `pkg/tools` | Tool registry, JSON Schema, sandbox | [`pkg/tools/README.md`](../pkg/tools/README.md) |
| `pkg/persona` | Persona system, AGENTS.md discovery | [`pkg/persona/README.md`](../pkg/persona/README.md) |
| `pkg/rag` | Memory, embeddings, vector DB | [`pkg/rag/README.md`](../pkg/rag/README.md) |
| `pkg/config` | YAML loading, precedence | [`pkg/config/README.md`](../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

```go
// 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/`](../../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**

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

```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.md) — Architecture and core interfaces
- [`phase2.md`](./phase2.md) — Advanced features (MCP, full RAG, Skills, etc.)
- [Products that use this library](https://github.com/VictorVargas)