steve
4522310f5a
Introduces llm.Parse(spec) backed by an extensible Registry that resolves model strings like "openai/gpt-4o", aliases like "fast", and named targets like "m5/qwen3:30b" (via LLM_M5 env var DSNs) into ready-to-use *Model objects. Extension points: RegisterProvider, RegisterAlias, RegisterResolver. Adds Foreman constructor and sentinel errors ErrAliasLoop, ErrUnknownProvider, ErrInvalidDSN. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
47 lines
2.9 KiB
Markdown
47 lines
2.9 KiB
Markdown
# 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.
|