Help us shape the future of Go! Take the 2026 Go Developer Survey

chat

package
v0.49.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 25, 2026 License: MIT Imports: 15 Imported by: 2

README

Chat (go-tool-base adapter)

This package is go-tool-base's thin adapter over the standalone multi-provider AI chat client, gitlab.com/phpboyscout/go/chat.

The client itself — the ChatClient API, ReAct tool-calling loop, streaming, cross-provider fallback, persistence, and multimodal input — lives in the module and its per-provider modules (chat-anthropic, chat-openai, chat-gemini). Full docs: chat.go.phpboyscout.uk.

This adapter adds go-tool-base's framework integration:

  • SettingsFromProps / NewFromProps / NewWithFallbackFromProps — map a Props instance and its go/config store into the module's typed Settings, taking the caller's gochat.Config as the starting point.
  • the GTB config-key schema (ConfigKeyClaudeKey, ConfigKeyAIProvider, …), CredentialKeysFor and the credential-resolution precedence, declared to credentialposture so doctor reports them.
  • the hardened go/httpclient transport and the go/credentials keychain lookup, injected into the module via its seams.
  • the provider-to-module table (ProviderModule, ProviderModules) and LinkedProviders, which reads what the binary declares it links.

It registers no provider. A provider is a blank import in the binary that ships it (spec 0194): cli/cmd/gtb/providers.go links every module, and a generated tool links the ones its manifest selects. Nothing is re-exported: call sites import gitlab.com/phpboyscout/go/chat for the client types and this package for the GTB glue. See docs/explanation/components/chat/index.md and the migration note at docs/reference/migration/v0.x-chat-extracted.md.

Documentation

Overview

Package chat is go-tool-base's framework-integration layer over the standalone multi-provider chat client gitlab.com/phpboyscout/go/chat.

It maps GTB's Props configuration into the module's typed Settings (see config_adapter.go via SettingsFromProps, NewFromProps and NewWithFallbackFromProps) and owns the GTB config-key schema (see constants.go). It registers no provider: the binary that ships one blank-imports its module (see ProviderModule). The adapter names go/chat types (chat.Config, chat.New, …) directly; they are no longer re-exported from this package.

Code that wants the pure chat client API without the GTB config container imports gitlab.com/phpboyscout/go/chat directly.

Index

Constants

View Source 
const (
	// ConfigKeyAIBaseURL overrides the API endpoint; required by
	// openai-compatible and azure-openai.
	ConfigKeyAIBaseURL = "ai.base_url"
	// ConfigKeyAIAPIVersion is the dated API version azure-openai requires.
	ConfigKeyAIAPIVersion = "ai.api_version"
	// ConfigKeyAIProject is the cloud project gemini-vertex addresses.
	ConfigKeyAIProject = "ai.project"
	// ConfigKeyAILocation is the region gemini-vertex and bedrock address.
	ConfigKeyAILocation = "ai.location"
)

The addressing keys a few providers need. They apply to ai.provider only; a fallback member resolves its own endpoint (spec 0196 D6).

View Source 
const (
	ConfigKeyOpenAIKey      = configRootOpenAI + ".key"
	ConfigKeyOpenAIEnv      = configRootOpenAI + ".env"
	ConfigKeyOpenAIKeychain = configRootOpenAI + ".keychain"
	EnvOpenAIKey            = "OPENAI_API_KEY"

	ConfigKeyClaudeKey      = configRootClaude + ".key"
	ConfigKeyClaudeEnv      = configRootClaude + ".env"
	ConfigKeyClaudeKeychain = configRootClaude + ".keychain"
	EnvClaudeKey            = "ANTHROPIC_API_KEY"

	ConfigKeyGeminiKey      = configRootGemini + ".key"
	ConfigKeyGeminiEnv      = configRootGemini + ".env"
	ConfigKeyGeminiKeychain = configRootGemini + ".keychain"
	EnvGeminiKey            = "GEMINI_API_KEY"

	ConfigKeyAzureKey      = configRootAzure + ".key"
	ConfigKeyAzureEnv      = configRootAzure + ".env"
	ConfigKeyAzureKeychain = configRootAzure + ".keychain"
	EnvAzureKey            = "AZURE_OPENAI_API_KEY"
)

Per-provider credential config keys.

  • ConfigKey<Provider>Key — full config path for the literal API key.
  • ConfigKey<Provider>Env — full config path for an env-var reference (the value stored is the NAME of an env var holding the secret).
  • ConfigKey<Provider>Keychain — full config path for an OS-keychain reference.
  • Env<Provider>Key — well-known unprefixed environment variable used as the ecosystem fallback when no config is present.
View Source 
const ConfigKeyAIClaudeLocal = "ai.claude.local"

ConfigKeyAIClaudeLocal is the legacy switch that routes generation through the local claude CLI.

View Source 
const ConfigKeyAIFallback = "ai.fallback"

ConfigKeyAIFallback is the config section holding the fallback-provider chain.

View Source 
const ConfigKeyAIModel = "ai.model"

ConfigKeyAIModel is the config key for the default model name.

View Source 
const ConfigKeyAIProvider = configSectionAI + ".provider"

ConfigKeyAIProvider is the config key for the AI provider.

View Source 
const ConfigKeyAIRequestTimeout = "ai.request_timeout"

ConfigKeyAIRequestTimeout is the config key for the per-request AI timeout (a duration like "8m"). Overrides DefaultChatRequestTimeout.

View Source 
const EnvAIProvider = "AI_PROVIDER"

EnvAIProvider is the environment variable for overriding the AI provider.

View Source 
const ToolServerModule = "gitlab.com/phpboyscout/go/chat-mcptools"

ToolServerModule is the module whose blank import serves a local-CLI provider its tools over MCP. Without it claude-local and codex-local refuse any tool (chat-anthropic and chat-openai v0.17.0).

Variables

View Source 
var ErrProviderUnset = errors.NewSentinel("gtb.chat.provider_unset", "no AI provider is configured")

ErrProviderUnset is a chat client asked for with no provider anywhere: not the caller's Config, not ai.provider, not AI_PROVIDER. The framework names no vendor as its default (spec 0196 D5); a tool's author does, through its embedded defaults, and an end user does through init ai.

Functions

func IsLocalCLI added in v0.42.0 

func IsLocalCLI(provider gochat.Provider) bool

IsLocalCLI reports whether a provider drives a locally installed CLI, which authenticates on its own and so carries no credential in GTB's config.

func LinkedProviders added in v0.43.0 

func LinkedProviders(set features.Set) (linked, unregistered []gochat.Provider)

LinkedProviders is what this binary says it links, in the order the author chose: the chat providers declared as link features (a generated tool declares one per provider in cmd/<name>/chat.go, #81), or, for a tool that declared none, every provider the linked modules register. The two differ when a module carries more providers than the author selected; doctor and the init wizard speak about the author's choice.

Declared is the set's answer, Unregistered the declared providers whose module is not in the binary: a build mistake, never a configuration one.

func LinkedProvidersIn added in v0.43.0 

func LinkedProvidersIn(set features.Set, registered []gochat.Provider) (linked, unregistered []gochat.Provider)

LinkedProvidersIn is LinkedProviders over an explicit registry listing, so a test states what is registered rather than registering it.

func NeedsCredential added in v0.43.0 

func NeedsCredential(provider gochat.Provider) bool

NeedsCredential reports whether GTB holds a credential for the provider: a local CLI authenticates on its own, bedrock through the AWS chain and gemini-vertex through application default credentials, so none of them has a credential root in GTB's config.

func NeedsToolServer added in v0.46.0 

func NeedsToolServer(provider gochat.Provider) bool

NeedsToolServer reports whether a binary linking the provider needs ToolServerModule for the provider to accept tools.

func NewFromProps added in v0.30.0 

func NewFromProps(ctx context.Context, p *props.Props, cfg gochat.Config) (gochat.ChatClient, error)

NewFromProps adapts GTB props into typed chat settings, then constructs a provider client with the reusable package constructor.

func NewWithFallback added in v0.22.0 

func NewWithFallback(ctx context.Context, p *props.Props, cfg gochat.Config, opts ...gochat.FallbackOption) (gochat.ChatClient, error)

NewWithFallback adapts GTB props and framework config before constructing a chat client with optional provider failover.

func NewWithFallbackFromProps added in v0.30.0 

func NewWithFallbackFromProps(ctx context.Context, p *props.Props, cfg gochat.Config, opts ...gochat.FallbackOption) (gochat.ChatClient, error)

NewWithFallbackFromProps adapts GTB props into package-owned chat settings, then constructs either a single provider client or a fallback composite.

The chain itself is the module's: NewWithFallbackSettings keeps the primary's model and addressing and lets every other member self-resolve, and the credential resolver below is how each member finds GTB's credential for it. GTB used to derive the per-member configs itself with a denylist that cleared the primary's model and would have carried addressing fields to every member (spec 0196 D6).

func ProviderKeyOptional added in v0.49.0 

func ProviderKeyOptional(provider gochat.Provider) bool

ProviderKeyOptional reports whether provider runs without a key: openai-compatible sends none, for a host that needs no authentication.

func ProviderKeyResolves added in v0.49.0 

func ProviderKeyResolves(ctx context.Context, cfg credentialposture.Reader, provider gochat.Provider) (bool, error)

ProviderKeyResolves reports whether provider's key resolves through the walk chat.New reads, so doctor can say what the client will find. A provider GTB holds no key for reports true, and a configured rung that cannot be read is the error.

func ProviderModule added in v0.41.0 

func ProviderModule(provider gochat.Provider) (string, bool)

ProviderModule returns the module path whose blank import registers the provider, and reports whether the provider is one this adapter knows.

func SettingsFromProps added in v0.30.0 

func SettingsFromProps(p *props.Props, cfg gochat.Config) (gochat.Settings, error)

SettingsFromProps adapts GTB props and framework config into package-owned chat settings while preserving the existing config key layout and precedence.

Types

type CredentialKeys added in v0.43.0 

type CredentialKeys struct {
	Root, Env, Keychain, Literal, FallbackEnv string
}

CredentialKeys is where GTB keeps a provider's credential: the config root and the three storage-mode keys under it, plus the well-known environment variable the resolver falls back to.

func CredentialKeysFor added in v0.43.0 

func CredentialKeysFor(provider gochat.Provider) (CredentialKeys, bool)

CredentialKeysFor derives a provider's credential keys from its root, and reports false for a provider that carries no GTB credential. Every list of these keys (init ai, config migrate, the posture descriptors) reads this one derivation.

func ProviderCredentialKeys added in v0.43.0 

func ProviderCredentialKeys() []CredentialKeys

ProviderCredentialKeys is every credential GTB keeps for a chat provider, one per config root in the order the wizard offers them. The migration and the project-trust list read it rather than naming the roots again.

type ProviderDisplay added in v0.43.0 

type ProviderDisplay struct {
	ID    gochat.Provider
	Label string
	// Gloss says what the provider is and what it needs, in a few words.
	Gloss string
}

ProviderDisplay is how a provider is shown to a person: init ai's select, the generator's wizard and the --provider help all read this one table.

func DisplayFor added in v0.43.0 

func DisplayFor(provider gochat.Provider) (ProviderDisplay, bool)

DisplayFor returns a provider's display, and whether the provider is known.

func ProviderDisplays added in v0.43.0 

func ProviderDisplays() []ProviderDisplay

ProviderDisplays returns every known provider's display, in module-table order.

type ProviderModuleEntry added in v0.41.0 

type ProviderModuleEntry struct {
	Provider gochat.Provider
	Module   string
}

ProviderModuleEntry pairs a chat provider with the module whose blank import registers it.

func ProviderModules added in v0.41.0 

func ProviderModules() []ProviderModuleEntry

ProviderModules returns every provider this adapter knows with its module, in a stable order.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.