modelrouter

Documentation

Overview

Package modelrouter resolves explicit model-provider selections into validated, secret-free route plans.

Applications construct a Registry from their route catalog at startup. A route identifies a serving provider, logical model, wire protocol, exact provider model ID, provider attribution, and explicit capability allow-set. Resolution intersects route, model-family, and protocol support. It does not construct provider clients or load credentials; those responsibilities belong to protocol adapters.

Providers are extensible validated identifiers. Protocols are controlled because each protocol corresponds to executor behavior implemented by DriftlessAF.

Example

package main

import (
	"fmt"

	"chainguard.dev/driftlessaf/agents/effort"
	"chainguard.dev/driftlessaf/agents/modelrouter"
)

func main() {
	selection := modelrouter.Selection{
		Provider:     modelrouter.ProviderAWSBedrock,
		LogicalModel: "claude-sonnet-5",
	}
	registry, err := modelrouter.NewRegistry(modelrouter.Route{
		Selection:       selection,
		Protocol:        modelrouter.ProtocolAnthropicMessages,
		ProviderModelID: "anthropic.claude-sonnet-5",
		Attribution: modelrouter.Attribution{
			ProviderName: "aws.bedrock",
			LegacySystem: "aws.bedrock",
		},
		Capabilities: modelrouter.Capabilities{
			Efforts:            []effort.Level{effort.High},
			ToolCalling:        true,
			TerminalSubmission: true,
		},
	})
	if err != nil {
		panic(err)
	}

	plan, err := registry.Resolve(selection)
	if err != nil {
		panic(err)
	}
	if err := plan.ValidateRequirements(modelrouter.Requirements{
		Effort:             effort.High,
		ToolCalling:        true,
		TerminalSubmission: true,
	}); err != nil {
		panic(err)
	}

	fmt.Printf("%s uses %s through %s\n", plan.LogicalModel(), plan.Provider(), plan.Protocol())
}

Output:
claude-sonnet-5 uses bedrock through anthropic-messages

Index

• Variables
• type Attribution
  • func (a Attribution) Validate() error
• type Capabilities
  • func (c Capabilities) SupportsEffort(level effort.Level) bool
• type Plan
  • func (p Plan) Attribution() Attribution
  • func (p Plan) Capabilities() Capabilities
  • func (p Plan) LogicalModel() string
  • func (p Plan) Protocol() Protocol
  • func (p Plan) Provider() Provider
  • func (p Plan) ProviderModelID() string
  • func (p Plan) SameResolution(other Plan) bool
  • func (p Plan) Selection() Selection
  • func (p Plan) Validate() error
  • func (p Plan) ValidateRequirements(requirements Requirements) error
• type Protocol
  • func (p Protocol) Validate() error
• type Provider
  • func (p Provider) Validate() error
• type Registry
  • func NewRegistry(routes ...Route) (*Registry, error)
  • func (r *Registry) Resolve(selection Selection) (Plan, error)
• type Requirements
• type Route
• type Selection
  • func (s Selection) Validate() error

Examples

• Package

Variables

var (
	// ErrInvalidRoute identifies an invalid route declaration.
	ErrInvalidRoute = errors.New("invalid route")
	// ErrInvalidSelection identifies an invalid route selection.
	ErrInvalidSelection = errors.New("invalid route selection")
	// ErrDuplicateRoute identifies two declarations for the same selection.
	ErrDuplicateRoute = errors.New("duplicate route")
	// ErrRouteNotFound identifies a valid selection that has no declaration.
	ErrRouteNotFound = errors.New("route not found")
	// ErrUnsupportedCapability identifies requirements that a route cannot
	// satisfy.
	ErrUnsupportedCapability = errors.New("unsupported route capability")
	// ErrInvalidPlan identifies a zero or otherwise unresolved plan.
	ErrInvalidPlan = errors.New("invalid route plan")
)

var ErrInvalidAttribution = errors.New("invalid route attribution")

ErrInvalidAttribution identifies empty or malformed route attribution.

Types

type Attribution

type Attribution struct {
	ProviderName string
	LegacySystem string
}

Attribution declares the two provider-controlled telemetry identities for a route. ProviderName is the canonical gen_ai.provider.name value. LegacySystem is the deprecated gen_ai.system compatibility value retained while telemetry consumers migrate.

Logical model, protocol, and exact provider model ID remain authoritative on Plan and are intentionally not duplicated here.

func (Attribution) Validate

func (a Attribution) Validate() error

Validate verifies that a contains usable, secret-free provider identifiers.

type Capabilities

type Capabilities struct {
	// Efforts lists the provider-neutral effort levels the route accepts.
	Efforts []effort.Level
	// ExplicitThinkingBudget reports whether the route accepts an explicit
	// token budget instead of provider-neutral effort.
	ExplicitThinkingBudget bool
	// SamplingParameters reports whether the route accepts caller-configured
	// temperature, top-p, or top-k values.
	SamplingParameters bool
	// PromptCaching reports whether the executor implements explicit prompt
	// cache-boundary semantics. Merely concatenating a prompt suffix or relying
	// on provider-managed implicit caching doesn't satisfy this capability.
	PromptCaching bool
	// ToolCalling reports whether the executor implements nonterminal tools.
	ToolCalling bool
	// TerminalSubmission reports whether the executor implements the terminal
	// submit-result tool.
	TerminalSubmission bool
	// SuspendResume reports whether the executor can suspend and later resume a
	// conversation.
	SuspendResume bool
	// MaximumOutputTokens reports whether the executor accepts an explicit
	// output-token limit.
	MaximumOutputTokens bool
	// RefusalRecovery reports whether the executor implements refusal nudges.
	RefusalRecovery bool
}

Capabilities is an explicit allow-set of route features. The zero value supports no optional features, so adding a field fails closed until a route declares it. Nil and empty Efforts both mean that effort isn't supported. The Efforts slice returned by a Plan is a copy and can be modified by the caller.

func (Capabilities) SupportsEffort

func (c Capabilities) SupportsEffort(level effort.Level) bool

SupportsEffort reports whether c supports level.

type Plan

type Plan struct {
	// contains filtered or unexported fields
}

Plan is the immutable, validated, and secret-free result of resolving a route. Its private fields can be inspected only through copy-returning accessors.

func (Plan) Attribution

func (p Plan) Attribution() Attribution

Attribution returns the route's secret-free provider attribution.

func (Plan) Capabilities

func (p Plan) Capabilities() Capabilities

Capabilities returns a copy of the route's effective capabilities.

func (Plan) LogicalModel

func (p Plan) LogicalModel() string

LogicalModel returns the application-selected logical model ID.

func (Plan) Protocol

func (p Plan) Protocol() Protocol

Protocol returns the executor wire protocol.

func (Plan) Provider

func (p Plan) Provider() Provider

Provider returns the serving provider.

func (Plan) ProviderModelID

func (p Plan) ProviderModelID() string

ProviderModelID returns the exact model ID to send to the provider.

func (Plan) SameResolution

func (p Plan) SameResolution(other Plan) bool

SameResolution reports whether p and other are copies of the exact same route resolution. Separately constructed registries receive distinct identities even when their declarations have equal field values. Adapters use this to prove they returned the Plan they were given.

func (Plan) Selection

func (p Plan) Selection() Selection

Selection returns the provider and logical model used to resolve p.

func (Plan) Validate

func (p Plan) Validate() error

Validate verifies that p was produced by successful route resolution.

func (Plan) ValidateRequirements

func (p Plan) ValidateRequirements(requirements Requirements) error

ValidateRequirements verifies that p supports every requested feature. A caller can run this before invoking an adapter or constructing a provider client.

type Protocol

type Protocol string

Protocol identifies a request and response contract implemented by a DriftlessAF executor. Unlike providers, protocols are a controlled set.

const (
	// ProtocolGoogleGenAI uses the Google Gen AI request and response contract.
	ProtocolGoogleGenAI Protocol = "google-gen-ai"
	// ProtocolAnthropicMessages uses the Anthropic Messages request and
	// response contract.
	ProtocolAnthropicMessages Protocol = "anthropic-messages"
	// ProtocolOpenAIChatCompletions uses the OpenAI Chat Completions request and
	// response contract.
	ProtocolOpenAIChatCompletions Protocol = "openai-chat-completions"
)

func (Protocol) Validate

func (p Protocol) Validate() error

Validate returns an error unless p identifies a protocol implemented by a DriftlessAF executor.

type Provider

type Provider string

Provider identifies a serving, authentication, billing, and availability boundary. Provider is extensible: applications can use any value accepted by Validate without changing this package.

const (
	// ProviderVertexAI serves models through Google Vertex AI.
	ProviderVertexAI Provider = "vertex"
	// ProviderAnthropic serves models through Anthropic's first-party API.
	ProviderAnthropic Provider = "anthropic"
	// ProviderAWSBedrock serves models through Amazon Bedrock.
	ProviderAWSBedrock Provider = "bedrock"
)

func (Provider) Validate

func (p Provider) Validate() error

Validate returns an error unless p is a lowercase identifier. Provider identifiers may contain ASCII letters, digits, dots, underscores, and hyphens, and must start and end with a letter or digit.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry is an immutable collection of validated routes. Construct one explicitly with NewRegistry; the package has no global registry state.

func NewRegistry

func NewRegistry(routes ...Route) (*Registry, error)

NewRegistry validates routes and returns an immutable registry. Validation follows declaration order so errors are deterministic.

func (*Registry) Resolve

func (r *Registry) Resolve(selection Selection) (Plan, error)

Resolve returns the plan declared for selection. It doesn't construct a client or load credentials.

type Requirements

type Requirements struct {
	Effort                 effort.Level
	ExplicitThinkingBudget bool
	SamplingParameters     bool
	PromptCaching          bool
	ToolCalling            bool
	TerminalSubmission     bool
	SuspendResume          bool
	MaximumOutputTokens    bool
	RefusalRecovery        bool
}

Requirements describes application features that a route must support. The zero value requests no optional capability. An empty Effort leaves the provider's model default in place.

type Route

type Route struct {
	Selection       Selection
	Protocol        Protocol
	ProviderModelID string
	Attribution     Attribution
	Capabilities    Capabilities
}

Route declares how one selection runs and the exact capabilities that route allows. The effective plan intersects this allow-set with model-family and protocol support. Route values are copied by NewRegistry and remain safe for the caller to reuse or mutate.

type Selection

type Selection struct {
	Provider     Provider
	LogicalModel string
}

Selection identifies one provider and logical model. It deliberately contains neither protocol nor provider model ID: those values come from the application's validated route catalog.

func (Selection) Validate

func (s Selection) Validate() error

Validate verifies that s can be used as a route lookup key.