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

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

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

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

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

// 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

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

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

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