llm

Documentation

Overview

Package llm is the thin off-gate LLM provider layer for archfit's enrich and explain commands. It is NEVER part of the check gate: the arch ring test forbids any internal package from importing it — only cmd may.

The interface is one method deep. Classify/explain prompt construction and response parsing are archfit-side concerns (cmd/enrich), not provider methods. Determinism of the enrich workflow comes from the content-hash cache (cache.go) and the human-reviewed pinned labels — never from sampling parameters: current Anthropic Opus-tier models reject temperature outright.

Index

• type AnthropicProvider
  • func NewAnthropic(model string) (*AnthropicProvider, error)
  • func (p *AnthropicProvider) Complete(ctx context.Context, req Request) (Response, error)
  • func (p *AnthropicProvider) Name() string
• type Cache
  • func NewCache(inner Provider, dir string) *Cache
  • func (c *Cache) Complete(ctx context.Context, req Request) (Response, error)
  • func (c *Cache) Name() string
• type NotConfiguredError
  • func (e *NotConfiguredError) Error() string
• type OpenAIProvider
  • func NewOllama(baseURL, model string) *OpenAIProvider
  • func NewOpenAI(model string) (*OpenAIProvider, error)
  • func (p *OpenAIProvider) Complete(ctx context.Context, req Request) (Response, error)
  • func (p *OpenAIProvider) Name() string
• type Provider
• type Request
• type Response

Types

type AnthropicProvider

type AnthropicProvider struct {
	// contains filtered or unexported fields
}

AnthropicProvider completes requests via the official anthropic-sdk-go Messages API. Auth comes from the standard ANTHROPIC_API_KEY env var (the SDK reads it); archfit never stores keys in config.

No temperature is sent: current Opus-tier models reject sampling parameters (400), and enrich determinism comes from the cache + reviewed labels anyway.

func NewAnthropic

func NewAnthropic(model string) (*AnthropicProvider, error)

NewAnthropic returns a provider for the given model id (e.g. "claude-opus-4-8"). Returns NotConfiguredError when ANTHROPIC_API_KEY is not set — fail at construction, not on the first network call.

func (*AnthropicProvider) Complete

func (p *AnthropicProvider) Complete(ctx context.Context, req Request) (Response, error)

Complete executes one non-streaming Messages call and concatenates the response text blocks.

func (*AnthropicProvider) Name

func (p *AnthropicProvider) Name() string

Name returns "anthropic/<model>".

type Cache

type Cache struct {
	// contains filtered or unexported fields
}

Cache is a content-addressed Provider decorator. A hit skips the network entirely, which is what makes `enrich` replay deterministic: same provider, model, prompts → same cache key → byte-identical response. The cache directory is committable — a committed cache replays identically across machines. Corrupt entries are refetched, never fatal.

func NewCache

func NewCache(inner Provider, dir string) *Cache

NewCache wraps inner with a file cache rooted at dir (e.g. <repo>/.archfit-cache/llm). The directory is created lazily.

func (*Cache) Complete

func (c *Cache) Complete(ctx context.Context, req Request) (Response, error)

Complete returns the cached response when present, otherwise calls the inner provider and stores the result (atomic temp+rename write).

func (*Cache) Name

func (c *Cache) Name() string

Name returns the inner provider's name (the cache is transparent).

type NotConfiguredError

type NotConfiguredError struct {
	Provider string
	Reason   string
}

NotConfiguredError reports a provider that cannot run in this environment (missing API key, unknown provider name). Commands turn it into exit 3 with a setup hint; it must never be silently swallowed.

func (*NotConfiguredError) Error

func (e *NotConfiguredError) Error() string

type OpenAIProvider

type OpenAIProvider struct {
	// contains filtered or unexported fields
}

OpenAIProvider completes requests via the official openai-go Chat Completions API. It also serves Ollama through its OpenAI-compatible endpoint (NewOllama) — base-URL swap, no separate SDK.

func NewOllama

func NewOllama(baseURL, model string) *OpenAIProvider

NewOllama returns a provider talking to a local (or remote) Ollama via its OpenAI-compatible endpoint. No API key required; baseURL defaults to http://localhost:11434/v1 when empty.

func NewOpenAI

func NewOpenAI(model string) (*OpenAIProvider, error)

NewOpenAI returns a provider for the given model id. Returns NotConfiguredError when OPENAI_API_KEY is not set.

func (*OpenAIProvider) Complete

func (p *OpenAIProvider) Complete(ctx context.Context, req Request) (Response, error)

Complete executes one non-streaming chat completion.

func (*OpenAIProvider) Name

func (p *OpenAIProvider) Name() string

Name returns "<tag>/<model>" (e.g. "ollama/qwen2.5-coder").

type Provider

type Provider interface {
	// Name identifies provider+model (e.g. "anthropic/claude-opus-4-8");
	// part of the cache key, so it must be stable.
	Name() string

	// Complete executes the request and returns the text response.
	Complete(ctx context.Context, req Request) (Response, error)
}

Provider executes one completion. Implementations: Anthropic, OpenAI, Ollama (OpenAI-compatible), and the content-hash Cache decorator.

type Request

type Request struct {
	// System is the system prompt; empty means none.
	System string
	// User is the user-turn content.
	User string
	// MaxTokens caps the response; 0 uses the provider default (4096).
	MaxTokens int
}

Request is a single non-streaming completion request.

type Response

type Response struct {
	Text string
}

Response is the provider's text answer.