cli/docs/pkg-batch5-analysis.md

# Package Analysis — Batch 5

Generated by: gemini-batch-runner.sh
Models: gemini-2.5-flash-lite → gemini-3-flash-preview → gemini-3-pro-preview
Date: 2026-02-09
Packages: agentci agentic ai rag
Total tokens: 78402

---

Here is the detailed documentation for the framework's AI and Agent capabilities.

# Host-UK Core Framework: AI & Agent Packages

This document outlines the architecture, API, and design patterns for the AI automation subsystem within the Core framework. These packages provide the foundation for LLM-assisted development, task management, and RAG (Retrieval Augmented Generation) context.

---

## Package: `pkg/agentci`

### 1. Overview
`pkg/agentci` serves as the configuration bridge between the Core config system and the Agent CI dispatch logic. Its primary purpose is to manage the definitions of "Agent Targets"—machines or environments capable of running AI workloads (e.g., specific GPU nodes or cloud runners)—allowing the job runner to dynamically load and dispatch tasks to active agents.

### 2. Public API

```go
type AgentConfig struct {
    Host        string `yaml:"host" mapstructure:"host"`
    QueueDir    string `yaml:"queue_dir" mapstructure:"queue_dir"`
    ForgejoUser string `yaml:"forgejo_user" mapstructure:"forgejo_user"`
    Model       string `yaml:"model" mapstructure:"model"`
    Runner      string `yaml:"runner" mapstructure:"runner"`
    Active      bool   `yaml:"active" mapstructure:"active"`
}

// LoadAgents reads agent targets from config and returns a map suitable for the dispatch handler.
func LoadAgents(cfg *config.Config) (map[string]handlers.AgentTarget, error)

// SaveAgent writes an agent config entry to the config file.
func SaveAgent(cfg *config.Config, name string, ac AgentConfig) error

// RemoveAgent removes an agent from the config file.
func RemoveAgent(cfg *config.Config, name string) error

// ListAgents returns all configured agents (active and inactive).
func ListAgents(cfg *config.Config) (map[string]AgentConfig, error)
```

### 3. Internal Design
*   **Configuration Mapping**: The package acts as a Data Transfer Object (DTO) layer. It maps raw YAML/MapStructure data into the strictly typed `handlers.AgentTarget` struct required by the job runner.
*   **Defaults Handling**: `LoadAgents` applies specific logic defaults (e.g., default queue directories, default models like "sonnet") to ensure the system works with minimal configuration.

### 4. Dependencies
*   `forge.lthn.ai/core/cli/pkg/config`: For reading/writing the persistent configuration state.
*   `forge.lthn.ai/core/cli/pkg/jobrunner/handlers`: To map local config structs to the runtime types used by the job dispatch system.

### 5. Test Coverage Notes
*   **Configuration Persistence**: Tests should verify that `SaveAgent` correctly updates the underlying config file and that `LoadAgents` retrieves it accurately.
*   **Validation**: Edge cases where `Host` is empty or defaults are applied need unit testing.

### 6. Integration Points
*   **Job Runner**: The main dispatch loop calls `LoadAgents` to determine where AI jobs can be sent.
*   **CLI Tools**: CLI commands for managing build agents (e.g., `core agent add`) would use `SaveAgent` and `ListAgents`.

---

## Package: `pkg/agentic`

### 1. Overview
`pkg/agentic` is the heavy-lifting package for AI-assisted task management. It provides both a REST client for the `core-agentic` backend service and a Core Framework Service implementation to execute local AI operations (Git automation, context gathering, and Claude invocations).

### 2. Public API

**Client & API Types**
```go
type Client struct { /* ... */ }
type Task struct { /* ID, Title, Priority, Status, etc. */ }
type TaskContext struct { /* Task, Files, GitStatus, RAGContext, etc. */ }

// Client Factory
func NewClient(baseURL, token string) *Client
func NewClientFromConfig(cfg *Config) *Client

// API Operations
func (c *Client) ListTasks(ctx context.Context, opts ListOptions) ([]Task, error)
func (c *Client) GetTask(ctx context.Context, id string) (*Task, error)
func (c *Client) ClaimTask(ctx context.Context, id string) (*Task, error)
func (c *Client) UpdateTask(ctx context.Context, id string, update TaskUpdate) error
func (c *Client) CompleteTask(ctx context.Context, id string, result TaskResult) error
func (c *Client) Ping(ctx context.Context) error
```

**Git & Automation Ops**
```go
func AutoCommit(ctx context.Context, task *Task, dir string, message string) error
func CreatePR(ctx context.Context, task *Task, dir string, opts PROptions) (string, error)
func CreateBranch(ctx context.Context, task *Task, dir string) (string, error)
func CommitAndSync(ctx context.Context, client *Client, task *Task, dir string, message string, progress int) error
func BuildTaskContext(task *Task, dir string) (*TaskContext, error)
```

**Framework Service**
```go
type Service struct { /* ... */ }
type TaskCommit struct { Path, Name string; CanEdit bool }
type TaskPrompt struct { Prompt, WorkDir string; AllowedTools []string }

func NewService(opts ServiceOptions) func(*framework.Core) (any, error)
```

### 3. Internal Design
*   **Service Runtime**: Implements the `framework.ServiceRuntime` pattern, registering task handlers (`TaskCommit`, `TaskPrompt`) allowing other parts of the Core framework to request AI actions via the event bus.
*   **Heuristic Context Gathering**: `BuildTaskContext` uses a mix of git commands (`git grep`, `git status`) and file reading to assemble a prompt context for the LLM automatically.
*   **Tooling Integration**: Wraps the `claude` CLI binary directly via `os/exec` to perform actual inference, exposing tool capabilities (Bash, Read, Write) based on permissions.
*   **Embeds**: Uses Go embed (`//go:embed`) to store system prompts (e.g., `prompts/commit.md`) within the binary.

### 4. Dependencies
*   `pkg/framework`: To integrate as a background service.
*   `pkg/ai`: Uses `ai.QueryRAGForTask` to inject documentation context into task execution.
*   `pkg/config` & `pkg/io`: For loading credentials and file operations.
*   `pkg/log`: Structured logging.

### 5. Test Coverage Notes
*   **HTTP Client**: Requires mocking `http.Client` to verify request payload serialization and error handling for 4xx/5xx responses.
*   **Git Operations**: Needs integration tests with a temporary git repository to verify `AutoCommit` and branch creation logic.
*   **Context Building**: Unit tests should verify `extractKeywords` and `GatherRelatedFiles` logic on a known file structure.

### 6. Integration Points
*   **Developer CLI**: The `core` CLI uses this package to fetch tasks (`core task list`) and start work (`core task start`).
*   **Agents**: Autonomous agents use the `Client` to claim work and the `Service` to execute the necessary code changes.

---

## Package: `pkg/ai`

### 1. Overview
`pkg/ai` is the canonical entry point and facade for the framework's AI capabilities. It unifies RAG (from `pkg/rag`) and metrics collection, providing a simplified interface for other packages to consume AI features without managing low-level clients.

### 2. Public API

```go
// Metrics
type Event struct { /* Type, Timestamp, AgentID, etc. */ }
func Record(event Event) (err error)
func ReadEvents(since time.Time) ([]Event, error)
func Summary(events []Event) map[string]any

// RAG Facade
type TaskInfo struct { Title, Description string }
func QueryRAGForTask(task TaskInfo) string
```

### 3. Internal Design
*   **Facade Pattern**: Hides the initialization complexity of `rag.QdrantClient` and `rag.OllamaClient`. `QueryRAGForTask` instantiates these on demand with sensible defaults, ensuring graceful degradation (returns empty string) if services aren't running.
*   **Dependency Inversion**: It defines `TaskInfo` locally to accept task data from `pkg/agentic` without importing `pkg/agentic` directly, breaking potential circular dependencies.
*   **Local Metrics Store**: Implements a lightweight, file-based (JSONL) telemetry system stored in `~/.core/ai/metrics`.

### 4. Dependencies
*   `pkg/rag`: For vector database and embedding operations.
*   `pkg/agentic`: (Conceptually composed, though `ai` is the higher-level import).

### 5. Test Coverage Notes
*   **Metrics I/O**: Tests for `Record` and `ReadEvents` to ensure concurrent writes to the JSONL file do not corrupt data and dates are filtered correctly.
*   **Graceful Failure**: `QueryRAGForTask` must be tested to ensure it does not panic if Qdrant/Ollama are offline.

### 6. Integration Points
*   **Agentic Context**: `pkg/agentic` calls `QueryRAGForTask` to enhance prompts.
*   **Dashboard**: A UI or CLI dashboard would consume `Summary` to show AI usage stats.

---

## Package: `pkg/rag`

### 1. Overview
`pkg/rag` implements the Retrieval Augmented Generation pipeline. It handles the full lifecycle of document processing: reading Markdown files, chunking them intelligently, generating embeddings via Ollama, storing them in Qdrant, and performing semantic search.

### 2. Public API

**Ingestion & Chunking**
```go
type IngestConfig struct { /* Directory, Collection, ChunkConfig */ }
type Chunk struct { Text, Section string; Index int }

func DefaultIngestConfig() IngestConfig
func Ingest(ctx context.Context, qdrant *QdrantClient, ollama *OllamaClient, cfg IngestConfig, progress IngestProgress) (*IngestStats, error)
func ChunkMarkdown(text string, cfg ChunkConfig) []Chunk
```

**Querying**
```go
type QueryConfig struct { /* Collection, Limit, Threshold */ }
type QueryResult struct { Text, Source, Score float32 /* ... */ }

func Query(ctx context.Context, qdrant *QdrantClient, ollama *OllamaClient, query string, cfg QueryConfig) ([]QueryResult, error)
func FormatResultsContext(results []QueryResult) string
```

**Clients**
```go
type QdrantClient struct { /* ... */ }
func NewQdrantClient(cfg QdrantConfig) (*QdrantClient, error)

type OllamaClient struct { /* ... */ }
func NewOllamaClient(cfg OllamaConfig) (*OllamaClient, error)
func (o *OllamaClient) Embed(ctx context.Context, text string) ([]float32, error)
```

### 3. Internal Design
*   **Pipeline Architecture**: Separation of concerns between `Ingest` (Crawler/Loader), `Chunk` (Processor), `Embed` (Transformation), and `Qdrant` (Storage).
*   **Semantic Chunking**: `ChunkMarkdown` is designed specifically for documentation, splitting by H2 (`##`) headers first, then by paragraphs, maintaining overlap to preserve context.
*   **Adapter Pattern**: Wraps external libraries (`qdrant-go-client`, `ollama/api`) to strictly define the interface required by the Core framework.

### 4. Dependencies
*   `github.com/qdrant/go-client/qdrant`: Vector database driver.
*   `github.com/ollama/ollama/api`: Embedding model API.
*   `pkg/log`: Error reporting.

### 5. Test Coverage Notes
*   **Chunking Logic**: Critical to test `ChunkMarkdown` with various markdown structures (headers, lists, code blocks) to ensure chunks don't break mid-sentence or lose header context.
*   **Embed Dimensions**: Tests should verify that the vector size created by the Ollama client matches the collection configuration in Qdrant.
*   **Integration**: Requires running Qdrant and Ollama containers for full integration testing.

### 6. Integration Points
*   **CLI Admin**: An ingestion command (e.g., `core docs ingest`) would trigger the `Ingest` function.
*   **AI Package**: `pkg/ai` consumes `Query` to augment prompts.

---

## Quick Reference (Flash Summary)

### Package: `pkg/agentci`
**Description**: Manages configuration and lifecycle for AgentCI dispatch targets and remote runner machines.

**Key Exported Types and Functions**:
- `AgentConfig`: Struct representing an agent's host, queue directory, model, and runner type.
- `LoadAgents`: Reads agent configurations from the global config and maps them to dispatch targets.
- `SaveAgent`: Adds or updates a specific agent entry in the configuration file.
- `RemoveAgent`: Deletes an agent configuration entry by name.
- `ListAgents`: Retrieves all configured agents, including inactive ones.

**Dependencies**:
- `pkg/config`
- `pkg/jobrunner/handlers`

**Complexity**: Simple

---

### Package: `pkg/agentic`
**Description**: Provides an API client and automation tools for AI-assisted task management, git operations, and context gathering.

**Key Exported Types and Functions**:
- `Client`: API client for interacting with the core-agentic task service.
- `Task` / `TaskUpdate`: Data structures representing development tasks and their status updates.
- `BuildTaskContext`: Aggregates task details, relevant file contents, git status, and RAG data for AI consumption.
- `AutoCommit`: Automatically stages changes and creates a git commit with a task reference.
- `CreatePR`: Uses the `gh` CLI to create a pull request based on task metadata.
- `Service`: A framework-compatible service for handling asynchronous AI tasks like automated commits and prompts.
- `LoadConfig`: Multi-source configuration loader (Env, `.env` files, YAML) for API credentials.

**Dependencies**:
- `pkg/log`
- `pkg/config`
- `pkg/io`
- `pkg/ai`
- `pkg/framework`

**Complexity**: Complex

---

### Package: `pkg/ai`
**Description**: Unified entry point for AI features, orchestrating vector search, task context, and usage metrics.

**Key Exported Types and Functions**:
- `Event`: Represents a recorded AI or security metric event for telemetry.
- `Record`: Persists metric events to daily JSONL files in the user's home directory.
- `ReadEvents` / `Summary`: Retrieves and aggregates stored metrics for reporting.
- `QueryRAGForTask`: High-level helper that queries the vector database for documentation relevant to a specific task.
- `TaskInfo`: A minimal structure used to pass task data to the RAG system without circular dependencies.

**Dependencies**:
- `pkg/rag`

**Complexity**: Moderate

---

### Package: `pkg/rag`
**Description**: Implements Retrieval-Augmented Generation (RAG) using Qdrant for vector storage and Ollama for embeddings.

**Key Exported Types and Functions**:
- `QdrantClient`: Wrapper for the Qdrant database providing collection management and vector search.
- `OllamaClient`: Client for generating text embeddings using local models (e.g., `nomic-embed-text`).
- `ChunkMarkdown`: Semantically splits markdown text into smaller chunks based on headers and paragraphs.
- `Ingest`: Processes a directory of markdown files, generates embeddings, and stores them in Qdrant.
- `Query`: Performs vector similarity searches and filters results by score thresholds.
- `FormatResultsContext`: Formats retrieved document chunks into XML-style tags for LLM prompt injection.

**Dependencies**:
- `pkg/log`

**Complexity**: Moderate