llm-connect/contracts/functional/routing-policy.md

Contract: RoutingPolicy

layer: Functional
maturity: Beta
module: llm_connect.routing
since: WP-0003

Purpose

Route logical task types to concrete LLMAdapter instances based on a prioritised rule list, with optional per-rule cost-cap fallback.

Public surface

@dataclass
class RoutingRule:
    task_type: str
    prefer: LLMAdapter
    max_cost_per_1k: Optional[float] = None   # USD per 1 000 tokens
    fallback: Optional[LLMAdapter] = None

@dataclass
class RoutingPolicy:
    rules: List[RoutingRule] = field(default_factory=list)
    default: Optional[LLMAdapter] = None

    def resolve(
        self,
        task_type: str,
        estimated_cost_per_1k: Optional[float] = None,
    ) -> LLMAdapter: ...

Invariants

1. Rules are evaluated in list order; the first rule whose task_type matches wins.
2. When estimated_cost_per_1k is supplied and a matching rule has max_cost_per_1k set:
   • If estimated_cost_per_1k > max_cost_per_1k and fallback is not None → return fallback.
   • Otherwise → return prefer (no fallback configured or cost within cap).
3. When no rule matches and default is not None → return default.
4. When no rule matches and default is None → raise LookupError.
5. resolve() never mutates policy state.

Error contract

Condition	Exception
No matching rule, no default	LookupError

Known consumers

• inter-hub (IHUB-WP-0012 Phase 11): uses RoutingPolicy to select federation adapters per task class.