provider

Documentation

Overview

Package provider builds and dispatches to LLM provider clients.

The package is organised across several files:

• provider.go (this file): the public Provider interfaces and the entry points New and NewWithModels that callers use to construct a provider from a model config.
• aliases.go: the built-in provider alias table (OpenAI-compatible gateways such as ollama, mistral, xai, ...) and the helpers that expose it to other packages without leaking the underlying map.
• defaults.go: pure config-merging logic that fills in defaults from custom providers, built-in aliases, and model-specific rules (thinking budget, interleaved thinking, ...).
• factory.go: shared dispatch from a resolved provider type to the concrete client constructor, plus the always-available dmr provider and the rule-based router.
• factory_<name>.go: one file per optional provider (openai, anthropic, google, amazon-bedrock); each registers itself with the dispatch table and is gated by a build tag (see "Build tags" below).

Build tags

The openai, anthropic, google and amazon-bedrock providers are optional. Each lives behind a negative build tag so a project embedding docker-agent can compile a provider out — together with its transitive SDK dependencies — to shrink the binary and dependency graph. All providers are included by default; pass the relevant tag(s) to opt out.

Build tags are global to a build, not scoped per module: a tag set by the top-level project applies to every dependency too. The tags are therefore prefixed with "docker_agent_" so an embedding project can use its own build tags (even a plain "no_openai") without accidentally toggling these providers.

The available tags are:

• docker_agent_no_openai: drop the OpenAI provider (github.com/openai/openai-go).
• docker_agent_no_anthropic: drop the Anthropic provider (github.com/anthropics/anthropic-sdk-go). The google provider's Vertex Model Garden support also imports the anthropic package, so the dependency is only fully removed when combined with docker_agent_no_google.
• docker_agent_no_google: drop the Google provider (google.golang.org/genai, the Vertex AI / cloud auth stack, and — via Vertex Model Garden — the anthropic and openai SDKs). Vertex AI is unsupported either way under js/wasm.
• docker_agent_no_bedrock: drop the Amazon Bedrock provider (the github.com/aws/aws-sdk-go-v2 stack), the largest provider-specific dependency tree.

For example, to build without Bedrock and OpenAI:

go build -tags 'docker_agent_no_bedrock docker_agent_no_openai' ...

Requesting a model whose provider was compiled out fails at construction time with a clear "not compiled into this build" error rather than at compile time. The dmr provider and the rule-based router are always compiled in (except under js/wasm, which has its own slim factory).

Index

• Variables
• func AllProviders() []string
• func CatalogProviders() []string
• func EachAlias() iter.Seq2[string, Alias]
• func IsCatalogProvider(name string) bool
• func IsKnownProvider(name string) bool
• type Alias
  • func LookupAlias(name string) (Alias, bool)
• type BatchEmbeddingProvider
• type EmbeddingProvider
• type Provider
  • func CloneWithOptions(ctx context.Context, baseProvider Provider, opts ...options.Opt) Provider
  • func New(ctx context.Context, cfg *latest.ModelConfig, env environment.Provider, ...) (Provider, error)
  • func NewWithModels(ctx context.Context, cfg *latest.ModelConfig, ...) (Provider, error)
• type RerankingProvider

Variables

var Aliases = map[string]Alias{
	"requesty": {
		APIType:     "openai",
		BaseURL:     "https://router.requesty.ai/v1",
		TokenEnvVar: "REQUESTY_API_KEY",
	},
	"azure": {
		APIType:     "openai",
		TokenEnvVar: "AZURE_API_KEY",
	},
	"xai": {
		APIType:     "openai",
		BaseURL:     "https://api.x.ai/v1",
		TokenEnvVar: "XAI_API_KEY",
	},
	"nebius": {
		APIType:     "openai",
		BaseURL:     "https://api.studio.nebius.com/v1",
		TokenEnvVar: "NEBIUS_API_KEY",
	},
	"mistral": {
		APIType:     "openai",
		BaseURL:     "https://api.mistral.ai/v1",
		TokenEnvVar: "MISTRAL_API_KEY",
	},
	"ollama": {
		APIType: "openai",
		BaseURL: "http://localhost:11434/v1",
	},
	"minimax": {
		APIType:     "openai",
		BaseURL:     "https://api.minimax.io/v1",
		TokenEnvVar: "MINIMAX_API_KEY",
	},
	"github-copilot": {
		APIType:     "openai",
		BaseURL:     "https://api.githubcopilot.com",
		TokenEnvVar: "GITHUB_TOKEN",
	},
}

Aliases maps provider names to their corresponding configurations.

Most consumers should call LookupAlias for a single lookup or EachAlias to iterate, both of which keep the rest of the codebase decoupled from this concrete map. Direct mutation of Aliases is not supported.

var CoreProviders = []string{
	"openai",
	"anthropic",
	"google",
	"dmr",
	"amazon-bedrock",
}

CoreProviders lists all natively implemented provider types. These are the provider types that have direct implementations (not aliases).

Functions

func AllProviders

func AllProviders() []string

AllProviders returns all known provider names (core providers + aliases), sorted for deterministic output.

func CatalogProviders

func CatalogProviders() []string

CatalogProviders returns the list of provider names that should be shown in the model catalog. This includes core providers and aliases that have a defined BaseURL (self-contained endpoints). Aliases without a BaseURL (like azure) require user configuration and are excluded.

func EachAlias

func EachAlias() iter.Seq2[string, Alias]

EachAlias returns an iterator over every registered (name, Alias) pair. Iteration order is not guaranteed; callers that need a deterministic order should sort by name.

func IsCatalogProvider

func IsCatalogProvider(name string) bool

IsCatalogProvider returns true if the provider name is valid for the model catalog.

func IsKnownProvider

func IsKnownProvider(name string) bool

IsKnownProvider returns true if the provider name is a core provider or an alias.

Types

type Alias

type Alias struct {
	APIType     string // The actual API type to use (openai, anthropic, etc.)
	BaseURL     string // Default base URL for the provider
	TokenEnvVar string // Environment variable name for the API token
}

Alias defines the configuration for a provider alias.

func LookupAlias

func LookupAlias(name string) (Alias, bool)

LookupAlias returns the Alias registered for the given name (if any). Lookup is case-sensitive; callers that need case-insensitive matching should normalise the name first (e.g. strings.ToLower).

type BatchEmbeddingProvider

type BatchEmbeddingProvider interface {
	EmbeddingProvider
	// CreateBatchEmbedding generates embedding vectors for multiple texts with usage tracking.
	// Returns embeddings in the same order as input texts.
	CreateBatchEmbedding(ctx context.Context, texts []string) (*base.BatchEmbeddingResult, error)
}

BatchEmbeddingProvider defines the interface for providers that support batch embeddings.

type EmbeddingProvider

type EmbeddingProvider interface {
	Provider
	// CreateEmbedding generates an embedding vector for the given text with usage tracking.
	CreateEmbedding(ctx context.Context, text string) (*base.EmbeddingResult, error)
}

EmbeddingProvider defines the interface for providers that support embeddings.

type Provider

type Provider interface {
	// ID returns the provider-qualified model identity. Returning a
	// [modelsdev.ID] (rather than a bare string) prevents callers from
	// silently forgetting to namespace the model when it crosses an API
	// boundary; use [modelsdev.ID.String] when a textual representation
	// is required.
	ID() modelsdev.ID
	// CreateChatCompletionStream creates a streaming chat completion request.
	// It returns a stream that can be iterated over to get completion chunks.
	CreateChatCompletionStream(
		ctx context.Context,
		messages []chat.Message,
		tools []tools.Tool,
	) (chat.MessageStream, error)
	// BaseConfig returns the base configuration of this provider.
	BaseConfig() base.Config
}

Provider defines the interface for model providers.

func CloneWithOptions

func CloneWithOptions(ctx context.Context, baseProvider Provider, opts ...options.Opt) Provider

CloneWithOptions returns a new Provider instance using the same provider/model as the base provider, applying the provided options. If cloning fails, the original base provider is returned.

func New

func New(ctx context.Context, cfg *latest.ModelConfig, env environment.Provider, opts ...options.Opt) (Provider, error)

New creates a new provider from a model config. This is a convenience wrapper for NewWithModels with no models map.

func NewWithModels

func NewWithModels(ctx context.Context, cfg *latest.ModelConfig, models map[string]latest.ModelConfig, env environment.Provider, opts ...options.Opt) (Provider, error)

NewWithModels creates a new provider from a model config with access to the full models map. The models map is used to resolve model references in routing rules.

type RerankingProvider

type RerankingProvider interface {
	Provider
	// Rerank scores documents by relevance to the query.
	// Returns relevance scores in the same order as input documents.
	// Scores are typically in [0, 1] range where higher means more relevant.
	// criteria: Optional domain-specific guidance for relevance scoring (appended to base prompt)
	// documents: Array of types.Document with content and metadata
	Rerank(ctx context.Context, query string, documents []types.Document, criteria string) ([]float64, error)
}

RerankingProvider defines the interface for providers that support reranking. Reranking models score query-document pairs to assess relevance.