Documentation
¶
Overview ¶
Package routing plans deterministic provider attempts from immutable inputs. It owns no connectors, network operations, clocks, randomness, or mutable health state.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNoCandidate reports that policy rejected every requested route. ErrNoCandidate = errors.New("no route candidate satisfies the request") // ErrInvalidRequest reports invalid route-planning input. ErrInvalidRequest = errors.New("invalid route-planning request") // ErrInvalidSnapshot reports invalid or generation-inconsistent candidates. ErrInvalidSnapshot = errors.New("invalid route-planning snapshot") // ErrInvalidPlan reports incomplete or duplicate attempt identities. ErrInvalidPlan = errors.New("invalid route plan") )
Functions ¶
This section is empty.
Types ¶
type Attempt ¶
type Attempt struct {
Route Route
Evidence SelectionEvidence
}
Attempt is one ordered provider attempt in a route plan.
type Candidate ¶
type Candidate struct {
Route Route
Operations []Operation
Endpoints map[Operation]Endpoint
PromptCache *bool
Capabilities []string
ContextWindow int
Cost *TokenCost
Latency *time.Duration
Unhealthy bool
}
Candidate contains facts and runtime measurements for one route. The planner does not change this value.
type Operation ¶
type Operation string
Operation is one provider inference operation selected from catalog facts.
type OptimizationPolicy ¶
OptimizationPolicy defines deterministic soft preferences.
type Plan ¶
type Plan struct {
// contains filtered or unexported fields
}
Plan is an immutable ordered attempt list with rejection evidence.
func NewPlan ¶
func NewPlan( catalogGenerationID string, availabilityRevision uint64, attempts []Attempt, rejections []Rejection, ) (*Plan, error)
NewPlan creates an immutable plan from an already ordered attempt set. Composition adapters use it when no catalog-backed planner is available.
func (*Plan) AvailabilityRevision ¶
AvailabilityRevision returns the runtime revision used for this plan.
func (*Plan) CatalogGenerationID ¶
CatalogGenerationID returns the generation that supplied every planned route.
func (*Plan) Rejections ¶
Rejections returns a caller-owned copy in stable route order.
type Planner ¶
type Planner struct{}
Planner deterministically converts one request and snapshot into a route plan.
type ProviderPolicy ¶
ProviderPolicy defines request-scoped provider constraints and order.
type Rejection ¶
type Rejection struct {
Route Route
Code RejectionCode
Detail string
}
Rejection records why one considered route was not planned.
type RejectionCode ¶
type RejectionCode string
RejectionCode is a stable reason that excluded one route.
const ( RejectionUnavailable RejectionCode = "unavailable" // RejectionUnhealthy means runtime health disabled the offering. RejectionUnhealthy RejectionCode = "unhealthy" // RejectionTenantModel means tenant policy denied the model. RejectionTenantModel RejectionCode = "tenant_model" // RejectionTenantProvider means tenant policy denied the provider. RejectionTenantProvider RejectionCode = "tenant_provider" // RejectionProviderPolicy means request provider policy denied the route. RejectionProviderPolicy RejectionCode = "provider_policy" // RejectionMissingCapability means the route lacks a required capability. RejectionMissingCapability RejectionCode = "missing_capability" // RejectionMissingOperation means the exact offering or adapter cannot perform the request. RejectionMissingOperation RejectionCode = "missing_operation" // RejectionMissingEndpoint means the exact offering has no usable operation endpoint. RejectionMissingEndpoint RejectionCode = "missing_endpoint" // RejectionInsufficientContext means the route cannot accept the required context. RejectionInsufficientContext RejectionCode = "insufficient_context" )
type Request ¶
type Request struct {
Models []string
Operation Operation
AllowModelFallbacks bool
AllowAnyModelFallback bool
RequiredCapabilities []string
RequiredContextTokens int
EstimatedInputTokens int
EstimatedOutputTokens int
Tenant TenantPolicy
Providers ProviderPolicy
AffinityProvider string
Optimization OptimizationPolicy
}
Request contains all policy and requirements used by the pure planner.
type Route ¶
type Route struct {
CatalogGenerationID string
ModelID string
ProviderID string
ProviderModelID string
Operation Operation
Endpoint Endpoint
PromptCacheKnown bool
PromptCache bool
}
Route identifies one provider offering in one immutable catalog generation.
type SelectionEvidence ¶
type SelectionEvidence struct {
ModelRank int
ProviderRank int
AffinityMatched bool
EstimatedCost float64
HasCost bool
EstimatedLatency time.Duration
HasLatency bool
}
SelectionEvidence records the pure ranks and measurements used to order an attempt.
type Snapshot ¶
type Snapshot struct {
CatalogGenerationID string
AvailabilityRevision uint64
Candidates []Candidate
}
Snapshot binds all planning candidates to one catalog generation and one runtime availability revision.
Source Files