provider

Documentation

Overview

Package provider resolves a "provider:model" string to a concrete llm.Model. It is the small boundary where the agent's configured model name becomes a backend, resolving the provider's API key through a secret.Source (the vault interface) and an optional base-URL override for compatible endpoints. The key is carried as a secret.Text and never as a bare string, and a plaintext remote base URL is refused so a credential is never sent over an unencrypted transport. It is the place the README's cost-aware router grows from: today it dispatches on the provider name; later it can choose per step.

Index

• Variables
• func CanonicalSpec(spec string) string
• func CredentialEnvVars() []string
• func DefaultModelID(name string) (string, bool)
• func KeyRef(name string) (string, bool)
• func Providers() []string
• func Resolve(spec string) (llm.Model, error)
• func ResolveWith(ctx context.Context, spec string, src secret.Source) (llm.Model, error)

Variables

var ErrCredentialNotSet = errors.New("provider: credential not set")

ErrCredentialNotSet reports that a provider's API key was found in neither the vault nor the environment. It is wrapped (not replaced) so the precise variable name still shows in the message, and a caller can detect the case with errors.Is to start an interactive setup prompt instead of failing outright.

Functions

func CanonicalSpec

func CanonicalSpec(spec string) string

CanonicalSpec expands a bare provider name to "<provider>:<default model>" and leaves a full "provider:model" spec (or anything it does not recognise, such as a local model id) unchanged. A caller that resolves a bare provider can record and display the concrete model it actually uses instead of the provider name alone.

func CredentialEnvVars

func CredentialEnvVars() []string

CredentialEnvVars are the environment variables the default Resolve reads a provider API key from. A binary can unset these once a model is resolved so the process stops carrying the raw key in its environment, defense in depth on top of the sandbox already withholding the parent environment from commands.

func DefaultModelID

func DefaultModelID(name string) (string, bool)

DefaultModelID returns the model id a bare provider name resolves to, and whether the provider is known. A keyless local server (llamacpp) has no default id. The values match the defaults ResolveWith hands each adapter.

func KeyRef

func KeyRef(name string) (string, bool)

KeyRef returns the reference a provider's API key is stored under, the same name in the environment and in the vault, and whether the provider is known. The auth command uses it to seal a key under the name Resolve will look it up by.

func Providers

func Providers() []string

Providers lists the supported provider names.

func Resolve

func Resolve(spec string) (llm.Model, error)

Resolve turns a "provider:model" string (e.g. "anthropic:claude-opus-4-8", "openai:gpt-5.5") into an llm.Model, resolving credentials from the process environment. It is the zero-config entry point; ResolveWith supplies a custom secret.Source (a keychain, a file vault, a remote broker).

func ResolveWith

func ResolveWith(ctx context.Context, spec string, src secret.Source) (llm.Model, error)

ResolveWith turns a "provider:model" string into an llm.Model, resolving the provider's API key through src. A bare provider name uses that provider's default model. The key reference and the optional base-URL override are the provider's standard environment-variable names; with a non-env Source the same names address the vault. A configured base URL that is not safe to send a credential to (plaintext http to a non-loopback host) is rejected.