go-llm/v2/CLAUDE.md

CLAUDE.md for go-llm v2

Build and Test Commands

• Build project: cd v2 && go build ./...
• Run all tests: cd v2 && go test ./...
• Run specific test: cd v2 && go test -v -run <TestName> ./...
• Tidy dependencies: cd v2 && go mod tidy
• Vet: cd v2 && go vet ./...

Code Style Guidelines

• Indentation: Standard Go tabs
• Naming: camelCase for unexported, PascalCase for exported
• Error Handling: Always check and handle errors immediately. Wrap with fmt.Errorf("%w: ...", err)
• Imports: Standard library first, then third-party, then internal packages

Package Structure

• Root package llm — public API (Client, Model, Chat, ToolBox, Message types)
• provider/ — Provider interface that backends implement
• openai/, anthropic/, google/ — Provider implementations
• ollama/ — Native /api/chat provider, used by both llm.Ollama() (local) and llm.OllamaCloud(apiKey) (cloud).
• tools/ — Ready-to-use sample tools (WebSearch, Browser, Exec, ReadFile, WriteFile, HTTP)
• sandbox/ — Isolated Linux container environments via Proxmox LXC + SSH
• internal/schema/ — JSON Schema generation from Go structs
• internal/imageutil/ — Image compression utilities

Key Design Decisions

1. Unified Message type instead of marker interfaces
2. map[string]any JSON Schema (no provider coupling)
3. Tool functions return (string, error), use standard context.Context
4. Chat.Send() auto-loops tool calls; Chat.SendRaw() for manual control
5. MCP one-call connect: MCPStdioServer(ctx, cmd, args...)
6. Streaming via pull-based StreamReader.Next()
7. Middleware for logging, retry, timeout, usage tracking
8. Ollama uses the native /api/chat API rather than the OpenAI-compat /v1 endpoint. Native API supports think: false for thinking-capable models, has more reliable tool calling, and is approximately 15-20% lower latency. Both local and cloud share the same provider; only the apiKey/baseURL differ. llm.Ollama() targets http://localhost:11434 with no Authorization header; llm.OllamaCloud(key) targets https://ollama.com with Authorization: Bearer <key>.

DD#9 — Parse() function and extensible Registry (2026-05-23)

Context: mort's ParseModelRequest resolves "provider/model" strings but is mort-specific. Multi-instance providers (foreman) need named targets. Decision: Add llm.Parse(spec) backed by an extensible Registry. Supports aliases, dynamic resolvers, and LLM_X env var DSNs for named targets. Provider/model syntax: "openai/gpt-4o", aliases: "fast", named targets: "m5/qwen3:30b" (reads LLM_M5 env var). Registry is extensible via RegisterProvider, RegisterAlias, RegisterResolver. Consequence: Any go-llm consumer gets model-string parsing. mort migrates by registering its tier aliases as resolvers. Foreman instances are addressed via LLM_X DSN env vars without code changes.