routing

type Classifier ¶ added in v0.2.1

type Classifier interface {
	Score(f Features) float64
}

Classifier evaluates a feature set and returns a complexity score in [0, 1]. A higher score indicates a more complex task that benefits from a heavy model. The score is compared against the configured threshold: score >= threshold selects the primary (heavy) model; score < threshold selects the light model.

Classifier is an interface so that future implementations (ML-based, embedding-based, or any other approach) can be swapped in without changing routing infrastructure.

type DMScope ¶

type DMScope string

DMScope controls DM session isolation granularity.

const (
	DMScopeMain                  DMScope = "main"
	DMScopePerPeer               DMScope = "per-peer"
	DMScopePerChannelPeer        DMScope = "per-channel-peer"
	DMScopePerAccountChannelPeer DMScope = "per-account-channel-peer"
)

type Features ¶ added in v0.2.1

type Features struct {
	// TokenEstimate is a proxy for token count.
	// CJK runes count as 1 token each; non-CJK runes as 0.25 tokens each.
	// This avoids API calls while giving accurate estimates for all scripts.
	TokenEstimate int

	// CodeBlockCount is the number of fenced code blocks (“` pairs) in the message.
	// Coding tasks almost always require the heavy model.
	CodeBlockCount int

	// RecentToolCalls is the count of tool_call messages in the last lookbackWindow
	// history entries. A high density indicates an active agentic workflow.
	RecentToolCalls int

	// ConversationDepth is the total number of messages in the session history.
	// Deep sessions tend to carry implicit complexity built up over many turns.
	ConversationDepth int

	// HasAttachments is true when the message appears to contain media (images,
	// audio, video). Multi-modal inputs require vision-capable heavy models.
	HasAttachments bool
}

Features holds the structural signals extracted from a message and its session context. Every dimension is language-agnostic by construction — no keyword or pattern matching against natural-language content. This ensures consistent routing for all locales.

func ExtractFeatures(msg string, history []providers.Message) Features

type ParsedSessionKey ¶

type ParsedSessionKey struct {
	AgentID string
	Rest    string
}

ParsedSessionKey is the result of parsing an agent-scoped session key.

func ParseAgentSessionKey(sessionKey string) *ParsedSessionKey

type ResolvedRoute ¶

type ResolvedRoute struct {
	AgentID        string
	Channel        string
	AccountID      string
	SessionKey     string
	MainSessionKey string
	MatchedBy      string // "binding.peer", "binding.peer.parent", "binding.guild", "binding.team", "binding.account", "binding.channel", "default"
}

ResolvedRoute is the result of agent routing.

type RouteInput ¶

type RouteInput struct {
	Channel    string
	AccountID  string
	Peer       *RoutePeer
	ParentPeer *RoutePeer
	GuildID    string
	TeamID     string
}

RouteInput contains the routing context from an inbound message.

type RoutePeer ¶

type RoutePeer struct {
	Kind string // "direct", "group", "channel"
	ID   string
}

RoutePeer represents a chat peer with kind and ID.

type RouteResolver ¶

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

RouteResolver determines which agent handles a message based on config bindings.

func NewRouteResolver(cfg *config.Config) *RouteResolver

func (r *RouteResolver) ResolveRoute(input RouteInput) ResolvedRoute

type Router ¶ added in v0.2.1

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

Router selects the appropriate model tier for each incoming message. It is safe for concurrent use from multiple goroutines.

func New(cfg RouterConfig) *Router

func (r *Router) LightModel() string

func (r *Router) SelectModel(
	msg string,
	history []providers.Message,
	primaryModel string,
) (model string, usedLight bool, score float64)

func (r *Router) Threshold() float64

type RouterConfig ¶ added in v0.2.1

type RouterConfig struct {
	// LightModel is the model_name (from model_list) used for simple tasks.
	LightModel string

	// Threshold is the complexity score cutoff in [0, 1].
	// score >= Threshold → primary (heavy) model.
	// score <  Threshold → light model.
	Threshold float64
}

RouterConfig holds the validated model routing settings. It mirrors config.RoutingConfig but lives in pkg/routing to keep the dependency graph simple: pkg/agent resolves config → routing, not the reverse.

type RuleClassifier ¶ added in v0.2.1

type RuleClassifier struct{}

RuleClassifier is the v1 implementation. It uses a weighted sum of structural signals with no external dependencies, no API calls, and sub-microsecond latency. The raw sum is capped at 1.0 so that the returned score always falls within the [0, 1] contract.

Individual weights (multiple signals can fire simultaneously):

token > 200 (≈600 chars): 0.35  — very long prompts are almost always complex
token 50-200:             0.15  — medium length; may or may not be complex
code block present:       0.40  — coding tasks need the heavy model
tool calls > 3 (recent):  0.25  — dense tool usage signals an agentic workflow
tool calls 1-3 (recent):  0.10  — some tool activity
conversation depth > 10:  0.10  — long sessions carry implicit complexity
attachments present:      1.00  — hard gate; multi-modal always needs heavy model

Default threshold is 0.35, so:

• Pure greetings / trivial Q&A: 0.00 → light ✓
• Medium prose message (50–200 tokens): 0.15 → light ✓
• Message with code block: 0.40 → heavy ✓
• Long message (>200 tokens): 0.35 → heavy ✓
• Active tool session + medium message: 0.25 → light (acceptable)
• Any message with an image/audio attachment: 1.00 → heavy ✓

func (c *RuleClassifier) Score(f Features) float64

type SessionKeyParams ¶

type SessionKeyParams struct {
	AgentID       string
	Channel       string
	AccountID     string
	Peer          *RoutePeer
	DMScope       DMScope
	IdentityLinks map[string][]string
}

SessionKeyParams holds all inputs for session key construction.