Choose & configure a provider¶

This guide covers the chat.Config fields, how each provider is activated and credentialed, and the two providers that need extra setup: openai-compatible (a required BaseURL and Model) and claude-local (a local CLI binary).

The Config fields¶

chat.Config carries provider behaviour. It is passed inside chat.Settings to chat.New. Only Provider is effectively required (and even that defaults); everything else has a sane zero value.

See the pkg.go.dev reference for the full field list, including the test-only exec/genai override hooks.

Activate a provider by blank import¶

Each API provider lives in its own module. Blank-import it once (typically in main) to register it with the core; then reference it by its Provider constant.

The openai and openai-compatible providers are both registered by the single chat-openai import.

Resolve a credential¶

Every API provider resolves its key through one shared five-step cascade (chat.ResolveAPIKey). The first non-empty source wins; each step is trimmed so a half-configured value cannot mask a fully-configured one below it:

1. Direct token — Config.Token.
2. Env-var reference — Config.Credentials.Env names an env var; the value is read with os.Getenv. The secret stays out of any config file.
3. Keychain reference — Config.Credentials.Keychain is a "service/account" pair resolved through the host-injected Config.Credentials.Lookup func. With no lookup wired, this step is skipped.
4. Literal — Config.Credentials.Key, an inline value (legacy; least preferred).
5. Well-known env var — ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY, the ecosystem fallback used by most SDKs and CI platforms.

The simplest path is to export the well-known env var and leave Token and Credentials empty:

import (
    "gitlab.com/phpboyscout/go/chat"
    _ "gitlab.com/phpboyscout/go/chat-anthropic"
)

// ANTHROPIC_API_KEY is set in the environment; nothing else needed.
client, err := chat.New(ctx, chat.Settings{
    Config: chat.Config{Provider: chat.ProviderClaude},
})

A host that keeps secrets in a config file or keychain populates Config.Credentials instead — see credential security.

Using go-tool-base? Its adapter maps the framework's ai.provider, AI_PROVIDER, and provider api config sections onto these fields for you; that adapter lives in go-tool-base, not this module.

OpenAI-compatible endpoints¶

ProviderOpenAICompatible targets any backend that speaks the OpenAI API — Ollama, Groq, Fireworks AI, Together AI, LM Studio, vLLM, and others. It is registered by the chat-openai import. Both BaseURL and Model are required (there is no default model — names are backend-specific), and the BaseURL must pass endpoint validation.

import (
    "gitlab.com/phpboyscout/go/chat"
    _ "gitlab.com/phpboyscout/go/chat-openai"
)

// Ollama (local)
ollama, err := chat.New(ctx, chat.Settings{Config: chat.Config{
    Provider: chat.ProviderOpenAICompatible,
    BaseURL:  "http://localhost:11434/v1",
    Model:    "llama3.2",
    Token:    "ollama", // Ollama ignores the token; any non-empty value works

    // A localhost HTTP endpoint is non-HTTPS; permitted only in tests.
    AllowInsecureBaseURL: true,
}})

// Groq (cloud, HTTPS)
groq, err := chat.New(ctx, chat.Settings{Config: chat.Config{
    Provider: chat.ProviderOpenAICompatible,
    BaseURL:  "https://api.groq.com/openai/v1",
    Model:    "llama-3.3-70b-versatile",
    Token:    os.Getenv("GROQ_API_KEY"),
}})

Non-HTTPS endpoints. ValidateBaseURL rejects http:// unless AllowInsecureBaseURL is set, which is intended for httptest.Server targets only. For a plaintext local model, prefer an HTTPS proxy in production; the flag exists so tests can point at a local server, not as a way to disable TLS generally.

Token chunking falls back to the cl100k_base encoding for model names the tokenizer does not recognise, so Ollama and other non-OpenAI model names are handled gracefully.

Claude Local (the claude CLI)¶

ProviderClaudeLocal routes requests through a locally installed, pre-authenticated claude CLI binary instead of the Anthropic API. It is valuable in secure or air-gapped environments where outbound HTTPS to api.anthropic.com is blocked but the binary is permitted. It ships in the core — no blank import and no API key required.

Requirements:

• The claude CLI installed and on PATH.
• Authenticated once (claude login).

npm install -g @anthropic-ai/claude-code
claude login

import "gitlab.com/phpboyscout/go/chat" // no provider import needed

client, err := chat.New(ctx, chat.Settings{Config: chat.Config{
    Provider:     chat.ProviderClaudeLocal,
    Model:        "claude-sonnet-4-6", // optional; uses claude's default if empty
    SystemPrompt: "You are a helpful assistant.",
}})

Multi-turn continuity is maintained via session IDs captured from the CLI's JSON output and passed back with --resume. Two limitations set claude-local apart: it does not support tool calling (SetTools returns an error; MCP-based tools are planned) and it does not stream. It also reports no reliable token usage — see Providers.

Related¶

• Architecture & the seams — how chat.New dispatches to a provider.
• Providers — the full capability matrix and per-provider notes.
• Provider-endpoint & credential security — BaseURL validation and credential handling.