apsimo 1.3.0__py3-none-any.whl

apsimo/router/complexity_scorer.py

@@ -0,0 +1,148 @@
+"""Complexity scorer — heuristic prompt analysis for tier selection.
+
+Scores range 0.0–1.0:
+  0.00–0.30  → SMALL  (simple Q&A, factual lookups, short summaries)
+  0.30–0.65  → MEDIUM (multi-step reasoning, code generation, analysis)
+  0.65–1.00  → LARGE  (complex architecture, deep research, critical tasks)
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from apsimo.router.tiers import ModelTier
+
+
+@dataclass
+class ComplexitySignals:
+    token_count: int
+    has_code: bool
+    has_math: bool
+    has_multi_step: bool        # "first... then... finally..."
+    has_reasoning_required: bool  # "why", "explain", "analyze"
+    has_tool_use: bool
+    conversation_depth: int     # number of prior turns
+    user_tier: str              # "standard" | "power" | "developer"
+
+
+# Keyword sets for signal extraction
+_MULTI_STEP_PATTERNS = re.compile(
+    r"\b(first|step \d|then|after that|finally|next|followed by|subsequently)\b",
+    re.IGNORECASE,
+)
+_REASONING_PATTERNS = re.compile(
+    r"\b(why|explain|analyze|analyse|compare|contrast|evaluate|assess|critique|"
+    r"debate|argue|justify|prove|derive|infer|reason|think through|walk me through)\b",
+    re.IGNORECASE,
+)
+_CODE_PATTERNS = re.compile(
+    r"(```|\bdef \b|\bclass \b|\bimport \b|\bfunction\b|\bvoid \b|\bpublic \b|"
+    r"\bprivate \b|<code>|<script)",
+    re.IGNORECASE,
+)
+_MATH_PATTERNS = re.compile(
+    r"(\$\$?|\\\(|\bintegral\b|\bderivative\b|\bmatrix\b|\bequation\b|"
+    r"\balgebra\b|\bcalculus\b|\bstatistics\b|\bprobability\b)",
+    re.IGNORECASE,
+)
+
+# Signal weights for the final score.
+# Weights are intentionally skewed toward reasoning/multi-step signals
+# because those are the strongest predictors of tasks that genuinely need
+# a larger model (architecture analysis, complex debugging, etc.).
+_WEIGHTS = {
+    "token_count": 0.12,
+    "has_code": 0.12,
+    "has_math": 0.08,
+    "has_multi_step": 0.18,
+    "has_reasoning_required": 0.22,
+    "has_tool_use": 0.08,
+    "conversation_depth": 0.06,
+    "user_tier": 0.05,
+    # Bonus applied when BOTH multi-step AND reasoning are detected.
+    # A prompt that requires step-by-step thinking AND analytical reasoning
+    # is reliably in the LARGE tier regardless of token count.
+    "combined_reasoning_bonus": 0.20,
+}
+
+_TOKEN_SCALE = 500  # tokens above which token_count score saturates at 1.0
+_DEPTH_SCALE = 10   # turns above which depth score saturates at 1.0
+
+
+class ComplexityScorer:
+    """Score prompt complexity to select an appropriate model tier."""
+
+    def score(self, prompt: str, context: dict | None = None) -> float:
+        """Return a complexity score in [0.0, 1.0]."""
+        signals = self._extract_signals(prompt, context or {})
+        return self._compute_score(signals)
+
+    def select_tier(self, prompt: str, context: dict | None = None) -> ModelTier:
+        """Return the cheapest model tier appropriate for this prompt."""
+        score = self.score(prompt, context)
+        if score < 0.3:
+            return ModelTier.SMALL
+        elif score < 0.65:
+            return ModelTier.MEDIUM
+        else:
+            return ModelTier.LARGE
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _extract_signals(self, prompt: str, context: dict) -> ComplexitySignals:
+        # Rough token estimate: ~4 chars per token
+        token_count = max(1, len(prompt) // 4)
+
+        messages = context.get("messages", [])
+        depth = len(messages) if isinstance(messages, list) else 0
+
+        tools = context.get("tools", [])
+        has_tool_use = bool(tools) or "tool" in prompt.lower() or "function" in prompt.lower()
+
+        user_tier = context.get("user_tier", "standard")
+
+        return ComplexitySignals(
+            token_count=token_count,
+            has_code=bool(_CODE_PATTERNS.search(prompt)),
+            has_math=bool(_MATH_PATTERNS.search(prompt)),
+            has_multi_step=bool(_MULTI_STEP_PATTERNS.search(prompt)),
+            has_reasoning_required=bool(_REASONING_PATTERNS.search(prompt)),
+            has_tool_use=has_tool_use,
+            conversation_depth=depth,
+            user_tier=user_tier,
+        )
+
+    def _compute_score(self, signals: ComplexitySignals) -> float:
+        w = _WEIGHTS
+
+        # Normalise continuous signals to [0, 1]
+        token_score = min(1.0, signals.token_count / _TOKEN_SCALE)
+        depth_score = min(1.0, signals.conversation_depth / _DEPTH_SCALE)
+        tier_score = {"standard": 0.0, "power": 0.5, "developer": 1.0}.get(
+            signals.user_tier, 0.0
+        )
+
+        # Bonus: a prompt that requires BOTH step-by-step structure AND analytical
+        # reasoning is reliably complex enough to warrant the LARGE tier.
+        # 0.25 ensures reasoning + multi_step clears the 0.65 LARGE threshold.
+        combined_bonus = (
+            0.25
+            if signals.has_multi_step and signals.has_reasoning_required
+            else 0.0
+        )
+
+        raw = (
+            token_score * w["token_count"]
+            + float(signals.has_code) * w["has_code"]
+            + float(signals.has_math) * w["has_math"]
+            + float(signals.has_multi_step) * w["has_multi_step"]
+            + float(signals.has_reasoning_required) * w["has_reasoning_required"]
+            + float(signals.has_tool_use) * w["has_tool_use"]
+            + depth_score * w["conversation_depth"]
+            + tier_score * w["user_tier"]
+            + combined_bonus
+        )
+        return min(1.0, max(0.0, raw))

apsimo/router/endpoints.py

@@ -0,0 +1,153 @@
+"""Bounded observations of configured endpoints, separate from capabilities.
+
+A model listing can omit a working request alias. Only completion outcomes
+change routing availability; advertised metadata never grants tools or vision.
+"""
+import asyncio
+from collections import OrderedDict
+import hashlib
+import threading
+import time
+
+
+def models_url(base_url):
+    base = base_url.rstrip('/')
+    return base + ('/models' if base.endswith('/v1') else '/v1/models')
+
+
+class EndpointRuntime:
+    def __init__(self, *, cooldown=15, ttl=30, clock=time.monotonic, wall=time.time):
+        self.cooldown, self.ttl, self.clock, self.wall = cooldown, ttl, clock, wall
+        self._calls, self._listings = OrderedDict(), OrderedDict()
+        self._probing = set()
+        self._lock = threading.RLock()
+
+    @staticmethod
+    def call_key(snapshot, binding):
+        return (snapshot.revision, binding.config.base_url, binding.config.model_id, binding.weight_revision)
+
+    @staticmethod
+    def listing_key(snapshot, binding):
+        credential = hashlib.sha256(binding.config.api_key.encode()).hexdigest()
+        return (snapshot.revision, binding.config.base_url, credential)
+
+    @staticmethod
+    def _put(cache, key, value):
+        cache[key] = value
+        cache.move_to_end(key)
+        while len(cache) > 256:
+            cache.popitem(last=False)
+
+    def acquire(self, snapshot, binding, request_id):
+        """Healthy calls are unrestricted; one call tests an expired cooldown."""
+        key = self.call_key(snapshot, binding)
+        with self._lock:
+            state = self._calls.get(key)
+            if not state or not state.get('failed'):
+                return True
+            if state['retry_at'] > self.clock() or state.get('recovering'):
+                return False
+            state['recovering'] = request_id
+            return True
+
+    def release(self, snapshot, binding, request_id):
+        # Cancellation must not leave the single recovery attempt occupied.
+        with self._lock:
+            state = self._calls.get(self.call_key(snapshot, binding))
+            if state and state.get('recovering') == request_id:
+                state['recovering'] = False
+
+    def failure(self, snapshot, binding, error):
+        with self._lock:
+            self._put(self._calls, self.call_key(snapshot, binding), {
+                'failed': True, 'retry_at': self.clock() + self.cooldown,
+                'checked': self.clock(),
+                'observed_at': self.wall(), 'error_type': type(error).__name__,
+                'status_code': getattr(error, 'status_code', None), 'recovering': False})
+
+    def success(self, snapshot, binding, response):
+        served = getattr(response.raw, 'model', None)
+        with self._lock:
+            self._put(self._calls, self.call_key(snapshot, binding), {
+                'failed': False, 'observed_at': self.wall(),
+                'checked': self.clock(),
+                'served_model': served[:256] if isinstance(served, str) else None,
+                'latency_ms': response.latency_ms})
+
+    async def refresh(self, snapshot, probe):
+        """At most four concurrent reads, only when /models is requested.
+
+        Later reads cover remaining endpoints. No queue, scan or background task
+        survives the request. Cached entries retain their actual observation age.
+        """
+        selected = []
+        with self._lock:
+            # Unknown and oldest observations go first, so infrequent reads
+            # still cover a pool larger than the four concurrent probe slots.
+            ordered = sorted(snapshot.bindings.values(), key=lambda binding:
+                self._listings.get(self.listing_key(snapshot, binding), {}).get('checked', float('-inf')))
+            for binding in ordered:
+                key = self.listing_key(snapshot, binding)
+                old = self._listings.get(key)
+                if key in self._probing or (old and self.clock() - old['checked'] < self.ttl):
+                    continue
+                if len(self._probing) >= 4:
+                    break
+                self._probing.add(key)
+                selected.append((key, binding))
+
+        async def observe(key, binding):
+            try:
+                models = await asyncio.wait_for(probe(snapshot, binding), timeout=2)
+                value = {'available': True, 'models': models, 'observed_at': self.wall()}
+            except Exception as error:
+                value = {'available': False, 'models': [], 'observed_at': self.wall(),
+                         'error_type': type(error).__name__}
+            else:
+                value['error_type'] = None
+            finally:
+                with self._lock:
+                    self._probing.discard(key)
+            value['checked'] = self.clock()
+            with self._lock:
+                self._put(self._listings, key, value)
+
+        try:
+            await asyncio.gather(*(observe(key, binding) for key, binding in selected))
+        finally:
+            # Cancellation can precede a child's first instruction and its
+            # own finally block. Release every slot reserved by this request.
+            with self._lock:
+                self._probing.difference_update(key for key, _ in selected)
+
+    def status(self, snapshot):
+        now, wall = self.clock(), self.wall()
+        bindings, inventories = {}, {}
+        with self._lock:
+            for name, binding in snapshot.bindings.items():
+                state = self._calls.get(self.call_key(snapshot, binding))
+                if state:
+                    failed = state.get('failed')
+                    phase = ('recovering' if state.get('recovering') else
+                             'cooldown' if state.get('retry_at', 0) > now else 'retry_due') if failed else 'available'
+                    bindings[name] = {k: v for k, v in state.items() if k not in {'failed', 'retry_at', 'recovering', 'checked'}}
+                    bindings[name].update(state=phase,
+                        stale=now-state['checked'] >= self.ttl,
+                        age_seconds=round(max(0, wall-state['observed_at']), 1),
+                        retry_after_seconds=round(max(0, state.get('retry_at', 0)-now), 2))
+                else:
+                    bindings[name] = {'state': 'unknown', 'stale': True}
+                key = self.listing_key(snapshot, binding)
+                if key not in inventories:
+                    listing = self._listings.get(key)
+                    item = {'bindings': [], 'available': False, 'models': [], 'stale': True}
+                    if listing:
+                        item.update({k: v for k, v in listing.items() if k != 'checked'})
+                        item['age_seconds'] = round(max(0, wall-listing['observed_at']), 1)
+                        item['stale'] = now-listing['checked'] >= self.ttl
+                    inventories[key] = item
+                inventories[key]['bindings'].append(name)
+        return {'completion_observations': bindings, 'model_inventory': list(inventories.values()),
+                'inventory_complete': all(not row['stale'] for row in inventories.values()),
+                'observation_ttl_seconds': self.ttl, 'retry_cooldown_seconds': self.cooldown,
+                'observation_basis': 'endpoint advertisements and actual completion outcomes; declarations remain authoritative'}

apsimo/router/fallback.py

@@ -0,0 +1,58 @@
+"""FallbackHandler — escalate to a higher tier when a lower tier fails.
+
+When a model call raises a rate-limit, context-length, or capability error,
+the handler promotes the request to the next tier and retries once.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from apsimo.router.tiers import ModelTier
+
+if TYPE_CHECKING:
+    pass
+
+logger = logging.getLogger(__name__)
+
+# Errors that warrant a tier upgrade (substrings matched in error messages)
+_UPGRADE_TRIGGERS = (
+    "context_length_exceeded",
+    "context window",
+    "maximum context",
+    "rate limit",
+    "rate_limit_exceeded",
+    "overloaded",
+    "too many tokens",
+    "insufficient capability",
+)
+
+_TIER_PROMOTION: dict[ModelTier, ModelTier] = {
+    ModelTier.SMALL: ModelTier.MEDIUM,
+    ModelTier.MEDIUM: ModelTier.LARGE,
+    # LARGE has no higher tier — callers must handle this
+}
+
+
+class FallbackHandler:
+    """Decide whether to escalate a failed request to the next model tier."""
+
+    def should_escalate(self, error: Exception, current_tier: ModelTier) -> bool:
+        """Return True if the error warrants a tier upgrade."""
+        if current_tier not in _TIER_PROMOTION:
+            return False  # No escalation for the top tier or explicit roles.
+
+        msg = str(error).lower()
+        triggered = any(trigger in msg for trigger in _UPGRADE_TRIGGERS)
+        if triggered:
+            logger.warning(
+                "FallbackHandler: escalating from %s due to: %s",
+                current_tier.value,
+                type(error).__name__,
+            )
+        return triggered
+
+    def next_tier(self, current_tier: ModelTier) -> ModelTier | None:
+        """Return the next tier to try, or None if already at LARGE."""
+        return _TIER_PROMOTION.get(current_tier)

apsimo/router/functions.py

@@ -0,0 +1,243 @@
+"""Declared function bindings and immutable per-call routing snapshots.
+
+No machine discovery or model-name capability inference. Hosts update the same
+configuration when endpoints move; measurements remain labelled declarations.
+"""
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass, replace
+import hashlib
+import ipaddress
+import json
+import re
+from urllib.parse import urlsplit
+
+from .tiers import ModelTier, TierConfig, _has_litellm_prefix
+
+FUNCTIONS = {'chat', 'reasoning', 'planning', 'extraction', 'judging', 'vision', 'coding'}
+DEFAULT_ROLES = {
+    'chat': ['small'], 'reasoning': ['large', 'medium', 'small'],
+    'planning': ['large', 'medium', 'small'], 'extraction': ['small', 'medium'],
+    'judging': ['large', 'medium'], 'vision': ['vision'], 'coding': ['large', 'medium'],
+}
+DEFAULT_NETWORKS = ('127.0.0.0/8', '10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16', '::1/128', 'fc00::/7')
+TASK_ROLES = {
+    'source_claim_extraction': 'extraction', 'source_image_description': 'vision',
+    'source_appraisal': 'extraction', 'self_judgment': 'reasoning',
+    'project_planning': 'planning', 'thought_job': 'reasoning',
+    'tom_affect_extraction': 'extraction', 'tom_belief_extraction': 'extraction',
+    'tom_intention_extraction': 'extraction',
+    'tom_fact_extraction': 'extraction', 'tom_engagement_extraction': 'extraction',
+    'context_compression': 'extraction',
+    'workspace_thinking': 'reasoning', 'internal_thinking': 'reasoning',
+    'toolsmith_draft': 'coding', 'skill_distillation': 'judging',
+}
+
+
+@dataclass(frozen=True)
+class Binding:
+    name: str
+    config: TierConfig
+    context_tokens: int = 0
+    supports_tools: bool | None = None
+    latency_ms: int = 0
+    tokens_per_second: float = 0
+    concurrency: int = 0
+    weight_revision: str = 'unknown'
+    legacy: bool = False
+    supports_json_schema: bool = False
+
+
+@dataclass(frozen=True)
+class FunctionRole:
+    candidates: tuple[str, ...]
+    timeout_seconds: float = 20
+    deadline_seconds: float = 40
+    min_context_tokens: int = 0
+    max_latency_ms: int = 0
+    min_tokens_per_second: float = 0
+    min_concurrency: int = 0
+
+
+@dataclass(frozen=True)
+class RoutingSnapshot:
+    revision: str
+    tiers: dict
+    bindings: dict[str, Binding]
+    roles: dict[str, FunctionRole]
+    networks: tuple
+    declared_hosts: frozenset[str]
+    task_roles: dict[str, str]
+    provider: str = ''
+    base_url: str = ''
+
+    def status(self):
+        return {'config_revision': self.revision, 'capability_basis': 'deployment declarations, not measured by this router',
+                'roles': {key: list(value.candidates) for key, value in self.roles.items()},
+                'task_roles': dict(self.task_roles),
+                'models': {name: {'model_id': b.config.model_id, 'weight_revision': b.weight_revision,
+                    'context_tokens': b.context_tokens, 'supports_vision': b.config.supports_vision,
+                    'supports_tools': b.supports_tools, 'latency_ms': b.latency_ms,
+                    'supports_json_schema': b.supports_json_schema,
+                    'tokens_per_second': b.tokens_per_second, 'concurrency': b.concurrency,
+                    'legacy_unknown_tools_allowed': b.legacy and b.supports_tools is None}
+                    for name, b in self.bindings.items()}}
+
+
+def number(value, *, minimum=0, maximum=10**9):
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not minimum <= value <= maximum:
+        raise ValueError('Invalid routing capability or limit')
+    return value
+
+
+def _binding(name, config, spec, *, legacy=False):
+    tools = spec.get('supportsTools')
+    if tools is not None and type(tools) is not bool:
+        raise ValueError('supportsTools must be an explicit boolean')
+    structured = spec.get('supportsJsonSchema', False)
+    if type(structured) is not bool:
+        raise ValueError('supportsJsonSchema must be an explicit boolean')
+    return Binding(name, config,
+        int(number(spec.get('contextTokens', config.useful_context_tokens))), tools,
+        int(number(spec.get('latencyMs', 0))), float(number(spec.get('tokensPerSecond', 0))),
+        int(number(spec.get('concurrency', 0))), str(spec.get('weightRevision') or 'unknown')[:160], legacy, structured)
+
+
+def _transport(config, host, spec):
+    protocol = spec.get('protocol', host.get('protocol'))
+    if protocol not in {None, 'openai-chat'}:
+        raise ValueError('Function routing requires the openai-chat protocol')
+    if config.model_id.startswith('ollama/') and protocol == 'openai-chat':
+        if not config.base_url.rstrip('/').endswith('/v1'):
+            raise ValueError('Declared Ollama OpenAI compatibility requires an explicit /v1 base URL')
+        config = replace(config, model_id='openai/' + config.model_id.removeprefix('ollama/'))
+    if not config.model_id.startswith('openai/'):
+        raise ValueError('Function routing requires an explicit OpenAI-compatible endpoint; declare protocol openai-chat for compatible Ollama /v1 endpoints')
+    return config
+
+
+def build_snapshot(host: dict, tiers: dict) -> RoutingSnapshot:
+    """Build privately, then replace one router reference after validation."""
+    bindings, materialized = {}, {}
+    for tier, original in tiers.items():
+        # Pin inherited endpoint/key into this snapshot. Later provider env
+        # changes cannot redirect a request that already selected this config.
+        spec = host.get('models', {}).get(tier.value, {})
+        spec = spec if isinstance(spec, dict) else {}
+        cfg = replace(deepcopy(original),
+            base_url=original.base_url or host.get('baseUrl', ''),
+            api_key=original.api_key or host.get('apiKey', ''))
+        cfg = _transport(cfg, host, spec)
+        materialized[tier] = cfg
+        bindings[tier.value] = _binding(tier.value, cfg, spec, legacy=True)
+    pool = host.get('modelPool', {})
+    if not isinstance(pool, dict) or len(pool) > 64:
+        raise ValueError('modelPool must contain at most 64 explicit bindings')
+    for name, spec in pool.items():
+        if not isinstance(name, str) or not re.fullmatch(r'[a-zA-Z0-9_.-]{1,80}', name) or name in bindings:
+            raise ValueError('Invalid or duplicate modelPool binding')
+        if not isinstance(spec, dict) or not isinstance(spec.get('model'), str) or not spec['model']:
+            raise ValueError('Every modelPool binding requires a model')
+        model = spec['model']
+        provider = str(spec.get('provider', host.get('provider', 'vllm')))
+        if not _has_litellm_prefix(model):
+            if provider == 'ollama': model = 'ollama/' + model
+            elif provider in {'local', 'custom', 'lmstudio', 'vllm', 'openai'}: model = 'openai/' + model
+        cfg = TierConfig(tier=ModelTier(spec.get('tier', 'medium')), model_id=model,
+            max_tokens=int(number(spec.get('maxTokens', 8192), minimum=1)),
+            cost_per_1k_input=0, cost_per_1k_output=0, latency_p50_ms=0,
+            base_url=spec.get('baseUrl', host.get('baseUrl', '')),
+            api_key=spec.get('apiKey', host.get('apiKey', '')),
+            extra_body=deepcopy(spec.get('extraBody')),
+            useful_context_tokens=int(number(spec.get('contextTokens', 0))),
+            supports_vision=spec.get('supportsVision') is True)
+        if not isinstance(cfg.base_url, str) or not isinstance(cfg.api_key, str):
+            raise ValueError('Invalid model endpoint configuration')
+        cfg = _transport(cfg, host, spec)
+        bindings[name] = _binding(name, cfg, spec)
+    if not bindings:
+        raise ValueError('At least one deployed model must be declared explicitly')
+    role_config = host.get('functionRoles', {})
+    if not isinstance(role_config, dict) or set(role_config) - FUNCTIONS:
+        raise ValueError('Unknown function role; speech/embedding/rerank use their own transports')
+    task_roles = host.get('taskRoles', {})
+    if (not isinstance(task_roles, dict) or set(task_roles) - TASK_ROLES.keys()
+            or any(not isinstance(role, str) or role not in FUNCTIONS for role in task_roles.values())):
+        raise ValueError('taskRoles must map supported task names to existing function roles')
+    roles = {}
+    for name, defaults in DEFAULT_ROLES.items():
+        raw = role_config.get(name, [key for key in defaults if key in bindings])
+        raw = {'candidates': raw} if isinstance(raw, list) else raw
+        if not isinstance(raw, dict): raise ValueError('Invalid function role')
+        if set(raw) - {'candidates', 'timeoutSeconds', 'deadlineSeconds', 'minContextTokens', 'maxLatencyMs', 'minTokensPerSecond', 'minConcurrency'}:
+            raise ValueError('Unknown function role constraint')
+        candidates = raw.get('candidates', [])
+        if not isinstance(candidates, list) or len(candidates) > 8 or any(not isinstance(key, str) or key not in bindings for key in candidates):
+            raise ValueError('Role candidates must name at most eight configured bindings')
+        slow = name in {'reasoning', 'planning', 'judging', 'coding'}
+        roles[name] = FunctionRole(tuple(dict.fromkeys(candidates)),
+            float(number(raw.get('timeoutSeconds', 120 if slow else 20), minimum=.05, maximum=300)),
+            float(number(raw.get('deadlineSeconds', 180 if slow else 40), minimum=.05, maximum=600)),
+            int(number(raw.get('minContextTokens', 0))), int(number(raw.get('maxLatencyMs', 0))),
+            float(number(raw.get('minTokensPerSecond', 0))), int(number(raw.get('minConcurrency', 0))))
+    raw_networks = host.get('localNetworks', DEFAULT_NETWORKS)
+    if not isinstance(raw_networks, (list, tuple)) or len(raw_networks) > 64:
+        raise ValueError('localNetworks must be a bounded list of CIDRs')
+    networks = tuple(ipaddress.ip_network(value, strict=False) for value in raw_networks)
+    if any(n.prefixlen == 0 for n in networks): raise ValueError('A default route cannot declare the whole internet local')
+    hosts = host.get('localHosts', ['localhost'])
+    if not isinstance(hosts, list) or any(not isinstance(h, str) or len(h) > 253 for h in hosts):
+        raise ValueError('localHosts must list deployment hostnames')
+    revision = hashlib.sha256(json.dumps(host, sort_keys=True, separators=(',', ':')).encode()).hexdigest()[:20]
+    return RoutingSnapshot(revision, materialized, bindings, roles, networks, frozenset(h.casefold() for h in hosts),
+                           task_roles=dict(task_roles),
+                           provider=str(host.get('provider') or ''), base_url=str(host.get('baseUrl') or ''))
+
+
+def select_role(snapshot, context):
+    """The same selection governs capability hints, deadlines and dispatch."""
+    task = context.get('task')
+    return (context.get('function_role')
+            or (snapshot.task_roles.get(task) if snapshot else None)
+            or TASK_ROLES.get(task, 'reasoning'))
+
+
+def endpoint_host(binding, snapshot):
+    """Return literal eligible IP or declared hostname needing DNS verification.
+
+    No suffix such as .local is trusted. Every resolved address must be inside
+    deployment networks; endpoints with URL credentials or query strings fail.
+    """
+    parsed = urlsplit(binding.config.base_url)
+    if parsed.scheme not in {'http', 'https'} or parsed.username or parsed.password or parsed.query or parsed.fragment:
+        return None
+    host = (parsed.hostname or '').casefold()
+    try:
+        address = ipaddress.ip_address(host)
+        return host if any(address in net for net in snapshot.networks) else None
+    except ValueError:
+        return host if host in snapshot.declared_hosts else None
+
+
+def candidates(snapshot, role_name, context, *, has_images, has_tools):
+    role = snapshot.roles[role_name]
+    minimum = max(role.min_context_tokens, int(context.get('required_context_tokens', 0)))
+    output = []
+    for name in role.candidates:
+        b = snapshot.bindings[name]
+        if (has_images or role_name == 'vision') and not b.config.supports_vision: continue
+        if has_tools and b.supports_tools is not True and not (b.legacy and b.supports_tools is None): continue
+        if minimum and b.context_tokens < minimum: continue
+        # Reuse the existing text estimator to avoid an obviously undersized
+        # fallback. Image token accounting is model-specific and remains unknown.
+        requested_output = context.get('max_output_tokens', context.get('max_tokens', b.config.max_tokens))
+        input_tokens = context.get('estimated_input_tokens', 0)
+        if b.supports_json_schema:
+            input_tokens += context.get('response_schema_tokens', 0)
+        if b.context_tokens and input_tokens + min(b.config.max_tokens, int(requested_output)) > b.context_tokens: continue
+        if role.max_latency_ms and (not b.latency_ms or b.latency_ms > role.max_latency_ms): continue
+        if b.tokens_per_second < role.min_tokens_per_second or b.concurrency < role.min_concurrency: continue
+        if endpoint_host(b, snapshot) is None: continue
+        output.append(b)
+    return output

apsimo/router/native_policy.py

@@ -0,0 +1,52 @@
+"""Resolve a local function binding for a native Hermes caller.
+
+This runs in the sidecar interpreter. The caller captures the private JSON pipe;
+Hermes retains its own dependencies, agent loop, fallback and execution identity.
+"""
+import argparse
+import asyncio
+import json
+from pathlib import Path
+
+from .functions import candidates
+from .router import LLMRouter
+
+
+async def planning(configuration):
+    if 'planning' not in configuration.get('functionRoles', {}):
+        raise ValueError('An explicit planning role is required')
+    router = LLMRouter(tiers={}, self_learner=object())
+    router.configure(configuration)
+    snapshot = router._snapshot
+    selected = candidates(snapshot, 'planning', {}, has_images=False, has_tools=True)
+    if not selected:
+        raise ValueError('No tool-capable local planning binding is available')
+    for binding in selected:
+        if not await router._local_addresses(snapshot, binding):
+            raise ValueError('Planning endpoint has no eligible local address')
+    if any(binding.config.extra_body != selected[0].config.extra_body for binding in selected):
+        raise ValueError('Planning candidates require different native request overrides')
+    role = snapshot.roles['planning']
+    entries = [dict(provider='openai', model=b.config.model_id.removeprefix('openai/'),
+                    base_url=b.config.base_url, api_key=b.config.api_key or 'local-no-key',
+                    api_mode='chat_completions') for b in selected]
+    maximum = min(binding.config.max_tokens for binding in selected)
+    options = {**entries[0], 'requested_provider':'openai', 'fallback_model':entries[1:] or None,
+               'max_tokens':maximum, 'request_overrides':{'extra_body':selected[0].config.extra_body or {}}}
+    policy = {'role':'planning', 'configuration_revision':snapshot.revision,
+              'candidates':[{'binding':b.name, 'model':b.config.model_id, 'weight_revision':b.weight_revision} for b in selected],
+              'max_output_tokens':maximum, 'request_timeout_seconds':role.timeout_seconds,
+              'run_deadline_seconds':role.deadline_seconds,
+              'fallback_owner':'Hermes native runtime'}
+    return options, policy
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--config', type=Path, required=True)
+    args = parser.parse_args()
+    print(json.dumps(asyncio.run(planning(json.loads(args.config.read_text())))))
+
+
+if __name__ == '__main__':
+    main()