router

type Complexity int

type Config struct {
	Models       []Model // Available models
	DefaultModel string  // Fallback if no rules match
	LocalFirst   bool    // Prefer local models when possible
	MaxAuditLog  int     // How many decisions to keep in memory
}

type Decision struct {
	RequestID string    `json:"request_id"`
	Timestamp time.Time `json:"timestamp"`

	// Input analysis
	QueryLength    int        `json:"query_length"`
	ContextSize    int        `json:"context_size"`
	NeedsTools     bool       `json:"needs_tools"`
	NeedsStreaming bool       `json:"needs_streaming,omitempty"`
	NeedsImages    bool       `json:"needs_images,omitempty"`
	Priority       string     `json:"priority"`
	DetectedIntent string     `json:"detected_intent,omitempty"`
	Complexity     Complexity `json:"complexity"`

	// Decision process
	RulesEvaluated []string            `json:"rules_evaluated"`
	RulesMatched   []string            `json:"rules_matched"`
	RejectedModels map[string][]string `json:"rejected_models,omitempty"`
	Scores         map[string]int      `json:"scores,omitempty"`
	NoEligible     bool                `json:"no_eligible,omitempty"`

	// Outcome
	ModelSelected         string `json:"model_selected"`
	UpstreamModelSelected string `json:"upstream_model_selected,omitempty"`
	ProviderSelected      string `json:"provider_selected,omitempty"`
	ResourceSelected      string `json:"resource_selected,omitempty"`
	Reasoning             string `json:"reasoning"`

	// Post-execution (filled in later)
	LatencyMs  int64 `json:"latency_ms,omitempty"`
	TokensUsed int   `json:"tokens_used,omitempty"`
	Success    *bool `json:"success,omitempty"`
}

type DeploymentStats struct {
	Provider      string `json:"provider"`
	Resource      string `json:"resource,omitempty"`
	UpstreamModel string `json:"upstream_model,omitempty"`
	Requests      int64  `json:"requests"`
	Successes     int64  `json:"successes"`
	Failures      int64  `json:"failures"`
	AvgLatencyMs  int64  `json:"avg_latency_ms,omitempty"`
	AvgTokensUsed int64  `json:"avg_tokens_used,omitempty"`
}

type LoopProfile struct {
	// Model sets an explicit model, bypassing the router. When empty,
	// the router selects based on the other hint fields.
	Model string `yaml:"model,omitempty" json:"model,omitempty"`

	// QualityFloor is the minimum model quality rating (1–10). Maps
	// to [HintQualityFloor].
	QualityFloor string `yaml:"quality_floor,omitempty" json:"quality_floor,omitempty"`

	// Mission describes the task context for routing. Maps to
	// [HintMission]. Common values: "conversation", "automation",
	// "device_control", "background".
	Mission string `yaml:"mission,omitempty" json:"mission,omitempty"`

	// LocalOnly restricts routing to free/local models when "true".
	// Maps to [HintLocalOnly].
	LocalOnly string `yaml:"local_only,omitempty" json:"local_only,omitempty"`

	// DelegationGating controls delegation-first tool gating. Set to
	// "disabled" for direct tool access. Maps to [HintDelegationGating].
	DelegationGating string `yaml:"delegation_gating,omitempty" json:"delegation_gating,omitempty"`

	// PreferSpeed favours faster models when "true". Maps to
	// [HintPreferSpeed].
	PreferSpeed string `yaml:"prefer_speed,omitempty" json:"prefer_speed,omitempty"`

	// ExcludeTools lists tool names to filter out of the agent run.
	ExcludeTools []string `yaml:"exclude_tools,omitempty" json:"exclude_tools,omitempty"`

	// ExtraHints carries arbitrary key-value routing hints that are
	// merged last, allowing callers to override or extend the typed
	// fields above.
	ExtraHints map[string]string `yaml:"extra_hints,omitempty" json:"extra_hints,omitempty"`

	// Instructions is extra text injected into the user message to
	// guide the agent's behaviour for this wake context.
	Instructions string `yaml:"instructions,omitempty" json:"instructions,omitempty"`
}

type Model struct {
	Name                  string     // Route/deployment identifier (e.g., "qwen3:4b" or "spark/qwen3:32b")
	UpstreamModel         string     // Provider-native model name (e.g., "qwen3:32b")
	Provider              string     // "ollama" or "anthropic" etc
	ResourceID            string     // Provider resource identity (e.g., server name)
	Server                string     // Configured server name when applicable
	SupportsTools         bool       // Deployment is configured for tool calling
	ProviderSupportsTools bool       // Underlying provider supports tool calling
	SupportsStreaming     bool       // Deployment/provider can stream
	SupportsImages        bool       // Deployment/provider accepts image input
	ContextWindow         int        // Max tokens
	Speed                 int        // Relative speed (1-10, 10=fastest)
	Quality               int        // Relative quality (1-10, 10=best)
	CostTier              int        // 0=free/local, 1=cheap, 2=moderate, 3=expensive
	MinComplexity         Complexity // Don't use for simpler than this
}

type Priority int

type Request struct {
	Query          string            // The user's input
	ContextSize    int               // Estimated tokens of context (talents, history)
	NeedsTools     bool              // Whether tool calling is required
	NeedsStreaming bool              // Whether a streaming response is required
	NeedsImages    bool              // Whether image/multimodal input is required
	ToolCount      int               // Number of tools available
	Priority       Priority          // Latency requirements
	Hints          map[string]string // Caller-supplied routing hints (see HintXxx constants)
}

type RequestOptions struct {
	Model        string
	Hints        map[string]string
	ExcludeTools []string
}

type ResourceHealth struct {
	CooldownUntil  time.Time `json:"cooldown_until,omitempty"`
	CooldownReason string    `json:"cooldown_reason,omitempty"`
}

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

type Stats struct {
	TotalRequests    int64                      `json:"total_requests"`
	ModelCounts      map[string]int64           `json:"model_counts"`
	AvgLatencyMs     map[string]int64           `json:"avg_latency_ms"`
	ComplexityCounts map[string]int64           `json:"complexity_counts"`
	SuccessCount     int64                      `json:"success_count"`
	FailureCount     int64                      `json:"failure_count"`
	ProviderCounts   map[string]int64           `json:"provider_counts,omitempty"`
	ResourceCounts   map[string]int64           `json:"resource_counts,omitempty"`
	ResourceHealth   map[string]ResourceHealth  `json:"resource_health,omitempty"`
	DeploymentStats  map[string]DeploymentStats `json:"deployment_stats,omitempty"`
}

type VirtualModel struct {
	Name        string
	Description string
	Exposed     bool
	Aliases     []string
	TopLevel    LoopProfile
	Delegate    LoopProfile
}

type VirtualModelRuntime struct {
	PremiumQualityFloor string
}

type VirtualModelSelection struct {
	RequestedName string
	CanonicalName string
	Description   string
	Known         bool
	Model         string
	Hints         map[string]string
}