multi-forge 0.2.0__py3-none-any.whl

forge/core/reactive/routing.py

@@ -0,0 +1,622 @@
+"""Shared subprocess routing primitives.
+
+Defines ``ModelRoute`` and ``RoutingResult`` used by all subprocess
+types (workflow workers, supervisor, handoff agent). The resolution
+chain in ``resolve_subprocess_routing()`` replaces ad-hoc resolution
+in each subprocess launcher.
+
+Dependency boundary: this module imports from ``core.auth``,
+``core.reactive.proxy``, ``proxy.proxies``, and ``config.loader``.
+It must never import from ``forge.review.*``.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from forge.core.reactive.env import (
+    FORGE_LAUNCH_MODE_VAR,
+    FORGE_SIDECAR_VAR,
+    FORGE_SUBPROCESS_BASE_URL_VAR,
+    FORGE_SUBPROCESS_PROXY_ID_VAR,
+    FORGE_SUBPROCESS_PROXY_VAR,
+    FORGE_SUBPROCESS_TEMPLATE_VAR,
+)
+from forge.proxy.proxies import ProxyEntry
+
+_log = logging.getLogger(__name__)
+
+RoutingSource = Literal[
+    "explicit",
+    "subprocess_proxy",
+    "preferred_proxy",
+    "route_scan",
+    "session_proxy",
+    "direct",
+    "unresolved",
+]
+
+
+@dataclass(frozen=True)
+class ModelRoute:
+    """Derived routing option for a model through a specific provider/template.
+
+    Generated by ``derive_model_routes()`` in ``forge.review.routing``,
+    consumed by ``resolve_subprocess_routing()`` here for route scan
+    and compatibility validation.
+    """
+
+    provider: str
+    credential: str
+    family: str
+    template_id: str | None
+    template_family: str | None
+    model_ref: str
+
+
+@dataclass(frozen=True)
+class RoutingResult:
+    """Outcome of the subprocess routing resolution chain.
+
+    ``route=None`` means unresolved fallback -- NOT valid direct execution.
+    Direct-capable models get a real ``ModelRoute(provider="direct")``.
+    """
+
+    base_url: str | None
+    proxy_id: str | None
+    template: str | None
+    source: RoutingSource
+    route: ModelRoute | None
+    credential: str | None
+    warning: str | None = None
+
+
+# ── Proxy entry helpers ──────────────────────────────────────────
+
+
+def _is_sidecar_mode() -> bool:
+    return bool(os.environ.get(FORGE_SIDECAR_VAR)) or os.environ.get(FORGE_LAUNCH_MODE_VAR) == "sidecar"
+
+
+def lookup_proxy_entry(proxy: str) -> "ProxyEntry | None":
+    """Resolve a proxy name to a full registry entry (soft, returns None)."""
+    from forge.proxy.proxies import ProxyRegistryStore, resolve_proxy_optional
+
+    try:
+        registry = ProxyRegistryStore().read()
+        return resolve_proxy_optional(registry, proxy)
+    except Exception as e:
+        _log.debug("Proxy lookup failed for '%s': %s", proxy, e)
+        return None
+
+
+def lookup_proxy_entry_strict(proxy: str) -> ProxyEntry:
+    """Resolve a proxy name to a full registry entry (strict, raises)."""
+    from forge.proxy.proxies import ProxyRegistryStore, resolve_proxy
+
+    registry = ProxyRegistryStore().read()
+    return resolve_proxy(registry, proxy)
+
+
+def _check_proxy_reachable(entry: ProxyEntry, timeout_s: float = 1.0) -> bool:
+    """HTTP health check on a proxy entry."""
+    from forge.proxy.proxy_orchestrator import check_proxy_health
+
+    return check_proxy_health(
+        base_url=entry.base_url,
+        expected_template=entry.template,
+        expected_proxy_id=entry.proxy_id,
+        timeout_s=timeout_s,
+    )
+
+
+def _probe_proxy_metadata(base_url: str, timeout_s: float = 1.0) -> dict[str, Any] | None:
+    """Live GET / probe for Forge proxy metadata.
+
+    Returns {"template": ..., "proxy_id": ...} if the endpoint is a
+    Forge proxy, or None if unreachable or not a Forge proxy.
+    """
+    try:
+        import httpx
+
+        with httpx.Client(timeout=httpx.Timeout(timeout_s)) as client:
+            resp = client.get(f"{base_url}/")
+        if resp.status_code != 200:
+            return None
+        data = resp.json()
+        if data.get("is_proxy") is not True:
+            return None
+        result: dict[str, Any] = {}
+        if data.get("template"):
+            result["template"] = str(data["template"])
+        proxy_block = data.get("proxy", {})
+        if isinstance(proxy_block, dict) and proxy_block.get("proxy_id"):
+            result["proxy_id"] = str(proxy_block["proxy_id"])
+        if isinstance(proxy_block, dict) and not result.get("template") and proxy_block.get("template"):
+            result["template"] = str(proxy_block["template"])
+
+        advertised_models = _extract_advertised_models(data)
+        if advertised_models:
+            result["advertised_models"] = tuple(sorted(advertised_models))
+        return result if result else None
+    except Exception as e:
+        _log.debug("Session proxy GET / probe failed for %s: %s", base_url, e)
+        return None
+
+
+def _extract_advertised_models(data: dict[str, Any]) -> set[str]:
+    """Extract model refs advertised by GET / tier mappings."""
+    models: set[str] = set()
+
+    def collect(mapping: Any) -> None:
+        if not isinstance(mapping, dict):
+            return
+        for value in mapping.values():
+            if isinstance(value, str) and value:
+                models.add(value)
+            elif isinstance(value, dict):
+                model = value.get("model")
+                if isinstance(model, str) and model:
+                    models.add(model)
+
+    collect(data.get("tiers"))
+    runtime = data.get("runtime")
+    if isinstance(runtime, dict):
+        collect(runtime.get("tier_mappings"))
+
+    return models
+
+
+# ── Compatibility validation ─────────────────────────────────────
+
+
+def _find_matching_route(
+    template: str,
+    routes: tuple[ModelRoute, ...],
+) -> ModelRoute | None:
+    """Find the first route whose template_id matches the proxy's template.
+
+    Exact template_id match only. Cross-family routing (e.g., gpt-5.5
+    through openrouter-anthropic) works because derive_model_routes()
+    already emits routes with those cross-family template_ids. Credential
+    matching alone is insufficient: litellm-gemini and litellm-openai
+    share litellm-remote but serve different model families.
+    """
+    for route in routes:
+        if route.template_id == template:
+            return route
+    return None
+
+
+def _make_result_from_entry(
+    entry: ProxyEntry,
+    route: ModelRoute | None,
+    source: RoutingSource,
+    warning: str | None = None,
+    *,
+    advisory_check: bool = False,
+) -> RoutingResult:
+    """Build a RoutingResult from a ProxyEntry."""
+    return RoutingResult(
+        base_url=entry.base_url,
+        proxy_id=entry.proxy_id,
+        template=entry.template,
+        source=source,
+        route=route,
+        credential=route.credential if route else None,
+        warning=_route_warning(
+            route,
+            base_url=entry.base_url,
+            advisory_check=advisory_check,
+            warning=warning,
+        ),
+    )
+
+
+def _join_warnings(*warnings: str | None) -> str | None:
+    parts = [warning.strip() for warning in warnings if warning and warning.strip()]
+    return " ".join(parts) or None
+
+
+def _cross_family_warning(route: ModelRoute | None) -> str | None:
+    if route is None or route.template_id is None or route.template_family is None:
+        return None
+    if route.template_family == route.family:
+        return None
+    return (
+        f"Model family '{route.family}' is routed through template '{route.template_id}' "
+        f"({route.template_family}); tier overrides may differ."
+    )
+
+
+def _live_advisory_warning(
+    base_url: str,
+    route: ModelRoute | None,
+    metadata: dict[str, Any] | None = None,
+) -> str | None:
+    if route is None:
+        return None
+
+    metadata = metadata or _probe_proxy_metadata(base_url)
+    if not metadata:
+        return None
+
+    advertised = metadata.get("advertised_models")
+    if not isinstance(advertised, (tuple, list, set, frozenset)):
+        return None
+
+    advertised_models = {str(model) for model in advertised if model}
+    if advertised_models and route.model_ref not in advertised_models:
+        return (
+            f"Proxy tier mappings do not advertise model '{route.model_ref}'; "
+            "request routing may still work, but tier overrides may not apply."
+        )
+    return None
+
+
+def _route_warning(
+    route: ModelRoute | None,
+    *,
+    base_url: str | None = None,
+    metadata: dict[str, Any] | None = None,
+    advisory_check: bool = False,
+    warning: str | None = None,
+) -> str | None:
+    live_warning = _live_advisory_warning(base_url, route, metadata) if advisory_check and base_url else None
+    return _join_warnings(warning, _cross_family_warning(route), live_warning)
+
+
+# ── Resolution chain ─────────────────────────────────────────────
+
+
+class ProxyRoutingError(ValueError):
+    """Raised when a proxy fails strict validation during routing."""
+
+
+def resolve_subprocess_routing(
+    explicit_base_url: str | None = None,
+    explicit_proxy: str | None = None,
+    preferred_proxy: str | None = None,
+    routes: tuple[ModelRoute, ...] = (),
+    *,
+    require_route: bool = False,
+    use_environment: bool = True,
+    advisory_check: bool = False,
+) -> RoutingResult:
+    """Unified routing resolution for all Forge subprocesses.
+
+    Walks the resolution chain and returns a structured route/proxy decision.
+    Callers decide fail-open vs fail-closed based on ``source`` and their
+    use case.
+
+    Args:
+        explicit_base_url: Highest-priority URL override (supervisor's
+            ``config.base_url``). Opaque -- no compatibility check.
+        explicit_proxy: User-chosen proxy (``--proxy``, ``--supervisor-proxy``).
+            Strict: hard error if missing, unreachable, or incompatible.
+        preferred_proxy: Catalog hint (``ModelSpec.preferred_proxy``).
+            Soft: warn and continue if missing.
+        routes: Derived model routes for compatibility and route scan.
+        require_route: When True (workflows), opaque session proxy without
+            a matching route is treated as unresolved. When False
+            (supervisor, handoff), it is accepted as-is.
+        use_environment: When False, skip ambient FORGE_SUBPROCESS_PROXY
+            and ANTHROPIC_BASE_URL lookups. Useful for callers that need
+            to preserve their own explicit fallback ordering.
+        advisory_check: When True, perform non-blocking live GET / checks
+            on selected proxies to surface tier-mapping compatibility warnings.
+    """
+    sidecar = _is_sidecar_mode()
+
+    # Step 1: Explicit base URL (highest priority, opaque)
+    if explicit_base_url:
+        return RoutingResult(
+            base_url=explicit_base_url,
+            proxy_id=None,
+            template=None,
+            source="explicit",
+            route=None,
+            credential=None,
+        )
+
+    # Step 2: Explicit proxy (strict)
+    if explicit_proxy:
+        if sidecar:
+            injected = _resolve_injected_subprocess_proxy(
+                expected_proxy=explicit_proxy,
+                routes=routes,
+                source="explicit",
+                require_route=require_route,
+                advisory_check=advisory_check,
+            )
+            if injected is not None:
+                return injected
+            raise ProxyRoutingError(
+                f"Proxy '{explicit_proxy}' cannot be resolved inside sidecar.\n"
+                "Tip: Start the session with '--subprocess-proxy' or run the workflow on the host."
+            )
+        return _resolve_strict_proxy(explicit_proxy, routes, "explicit", advisory_check=advisory_check)
+
+    # Step 3: Subprocess proxy (strict)
+    subprocess_proxy = os.environ.get(FORGE_SUBPROCESS_PROXY_VAR) if use_environment else None
+    if subprocess_proxy:
+        if sidecar:
+            injected = _resolve_injected_subprocess_proxy(
+                expected_proxy=subprocess_proxy,
+                routes=routes,
+                source="subprocess_proxy",
+                require_route=require_route,
+                advisory_check=advisory_check,
+            )
+            if injected is not None:
+                return injected
+            raise ProxyRoutingError(
+                f"Subprocess proxy '{subprocess_proxy}' configured but not resolvable inside sidecar.\n"
+                "Tip: Ensure the host injects FORGE_SUBPROCESS_BASE_URL into the sidecar environment."
+            )
+        else:
+            return _resolve_strict_proxy(subprocess_proxy, routes, "subprocess_proxy", advisory_check=advisory_check)
+    elif sidecar:
+        injected = _resolve_injected_subprocess_proxy(
+            expected_proxy=None,
+            routes=routes,
+            source="subprocess_proxy",
+            require_route=require_route,
+            advisory_check=advisory_check,
+        )
+        if injected is not None:
+            return injected
+
+    # Step 4: Preferred proxy (soft)
+    if preferred_proxy and not sidecar:
+        result = _resolve_soft_proxy(preferred_proxy, routes, advisory_check=advisory_check)
+        if result is not None:
+            return result
+
+    # Step 5: Route scan (registry-based)
+    if routes and not sidecar:
+        result = _scan_routes_for_proxy(routes, advisory_check=advisory_check)
+        if result is not None:
+            return result
+
+    # Step 6: Session proxy (inherited ANTHROPIC_BASE_URL)
+    session_base_url = os.environ.get("ANTHROPIC_BASE_URL") if use_environment else None
+    if session_base_url:
+        return _resolve_session_proxy(session_base_url, routes, require_route, advisory_check=advisory_check)
+
+    # Step 7: Unresolved
+    return RoutingResult(
+        base_url=None,
+        proxy_id=None,
+        template=None,
+        source="unresolved",
+        route=None,
+        credential=None,
+    )
+
+
+def _resolve_strict_proxy(
+    proxy: str,
+    routes: tuple[ModelRoute, ...],
+    source: RoutingSource,
+    *,
+    advisory_check: bool = False,
+) -> RoutingResult:
+    """Resolve a user-chosen proxy with strict validation."""
+    entry = lookup_proxy_entry_strict(proxy)
+
+    if not _check_proxy_reachable(entry):
+        raise ProxyRoutingError(
+            f"Proxy '{proxy}' is not reachable at {entry.base_url}.\n"
+            f"Tip: Run 'forge proxy start {proxy}' or check if the process is running."
+        )
+
+    route = _find_matching_route(entry.template, routes)
+    if routes and route is None:
+        template_desc = entry.template
+        route_desc = ", ".join(f"{r.template_id}/{r.credential}" for r in routes if r.template_id)
+        raise ProxyRoutingError(
+            f"Proxy '{proxy}' (template: {template_desc}) is not compatible with this model.\n"
+            f"  Compatible routes: {route_desc or '(direct only)'}\n"
+            f"Tip: Use '--proxy' with a compatible proxy, or 'forge proxy create <template>'."
+        )
+
+    return _make_result_from_entry(entry, route, source, advisory_check=advisory_check)
+
+
+def _resolve_soft_proxy(
+    proxy: str,
+    routes: tuple[ModelRoute, ...],
+    *,
+    advisory_check: bool = False,
+) -> RoutingResult | None:
+    """Resolve a catalog-recommended proxy (warn and skip on failure)."""
+    entry = lookup_proxy_entry(proxy)
+    if entry is None:
+        _log.debug("Preferred proxy '%s' not found in registry; skipping", proxy)
+        return None
+
+    if not _check_proxy_reachable(entry):
+        _log.debug("Preferred proxy '%s' not reachable; skipping", proxy)
+        return None
+
+    route = _find_matching_route(entry.template, routes)
+    if routes and route is None:
+        _log.debug("Preferred proxy '%s' not compatible with model routes; skipping", proxy)
+        return None
+
+    return _make_result_from_entry(entry, route, "preferred_proxy", advisory_check=advisory_check)
+
+
+def _scan_routes_for_proxy(
+    routes: tuple[ModelRoute, ...],
+    *,
+    advisory_check: bool = False,
+) -> RoutingResult | None:
+    """Find a running proxy that matches one of the model's derived routes.
+
+    Only returns reachable proxies (HTTP health check). Ranking:
+    1. Route preference order (from derive_model_routes)
+    2. Alphabetical proxy_id tiebreaker
+    """
+    from forge.proxy.proxies import ROUTABLE_STATUSES, ProxyRegistryStore
+
+    try:
+        registry = ProxyRegistryStore().read()
+    except Exception as e:
+        _log.debug("Route scan: registry read failed: %s", e)
+        return None
+
+    template_to_routes: dict[str, ModelRoute] = {}
+    for route in routes:
+        if route.template_id and route.template_id not in template_to_routes:
+            template_to_routes[route.template_id] = route
+
+    if not template_to_routes:
+        return None
+
+    candidates: list[tuple[int, str, ProxyEntry, ModelRoute]] = []
+
+    for entry in registry.proxies.values():
+        if entry.status not in ROUTABLE_STATUSES:
+            continue
+
+        matched_route = template_to_routes.get(entry.template)
+        if matched_route is None:
+            continue
+
+        if not _check_proxy_reachable(entry, timeout_s=1.0):
+            _log.debug("Route scan: proxy '%s' matches but is not reachable", entry.proxy_id)
+            continue
+
+        route_rank = next(
+            (i for i, r in enumerate(routes) if r.template_id == entry.template),
+            len(routes),
+        )
+        candidates.append((route_rank, entry.proxy_id, entry, matched_route))
+
+    if not candidates:
+        return None
+
+    candidates.sort(key=lambda c: (c[0], c[1]))
+    _, _, best_entry, best_route = candidates[0]
+
+    return _make_result_from_entry(best_entry, best_route, "route_scan", advisory_check=advisory_check)
+
+
+def _resolve_injected_subprocess_proxy(
+    *,
+    expected_proxy: str | None,
+    routes: tuple[ModelRoute, ...],
+    source: RoutingSource,
+    require_route: bool,
+    advisory_check: bool,
+) -> RoutingResult | None:
+    """Resolve host-injected subprocess proxy metadata inside sidecar mode."""
+    base_url = os.environ.get(FORGE_SUBPROCESS_BASE_URL_VAR)
+    if not base_url:
+        return None
+
+    proxy_id = os.environ.get(FORGE_SUBPROCESS_PROXY_ID_VAR) or None
+    template = os.environ.get(FORGE_SUBPROCESS_TEMPLATE_VAR) or None
+    if expected_proxy and expected_proxy not in {value for value in (proxy_id, template) if value}:
+        return None
+
+    route = _find_matching_route(template, routes) if template and routes else None
+    if require_route and routes and route is None:
+        route_desc = ", ".join(f"{r.template_id}/{r.credential}" for r in routes if r.template_id)
+        raise ProxyRoutingError(
+            "Injected subprocess proxy metadata is not compatible with this model.\n"
+            f"  Proxy: {proxy_id or expected_proxy or '(unknown)'}"
+            f"{f' (template: {template})' if template else ''}\n"
+            f"  Compatible routes: {route_desc or '(direct only)'}"
+        )
+
+    return RoutingResult(
+        base_url=base_url,
+        proxy_id=proxy_id,
+        template=template,
+        source=source,
+        route=route,
+        credential=route.credential if route else None,
+        warning=_route_warning(route, base_url=base_url, advisory_check=advisory_check),
+    )
+
+
+def _resolve_session_proxy(
+    base_url: str,
+    routes: tuple[ModelRoute, ...],
+    require_route: bool,
+    *,
+    advisory_check: bool = False,
+) -> RoutingResult:
+    """Resolve inherited ANTHROPIC_BASE_URL with registry + live metadata probe."""
+    from forge.proxy.proxies import ProxyRegistryStore, lookup_proxy_by_base_url
+
+    proxy_id: str | None = None
+    template: str | None = None
+    route: ModelRoute | None = None
+    warning: str | None = None
+    probed: dict[str, Any] | None = None
+
+    # Try registry lookup first (cheapest)
+    try:
+        registry = ProxyRegistryStore().read()
+        entry = lookup_proxy_by_base_url(registry, base_url)
+        if entry:
+            if require_route and not _check_proxy_reachable(entry):
+                warning = (
+                    f"Session proxy registry match '{entry.proxy_id}' at {base_url} did not pass health validation; "
+                    "treating as unresolved unless live metadata matches."
+                )
+                _log.debug("Session proxy registry match '%s' not reachable; probing live metadata", entry.proxy_id)
+            else:
+                proxy_id = entry.proxy_id
+                template = entry.template
+                route = _find_matching_route(entry.template, routes)
+    except Exception as e:
+        _log.debug("Session proxy registry lookup failed: %s", e)
+
+    # If registry miss, try live GET / probe for Forge proxy metadata
+    if template is None:
+        probed = _probe_proxy_metadata(base_url)
+        if probed:
+            probed_template = probed.get("template")
+            probed_proxy_id = probed.get("proxy_id")
+            template = probed_template if isinstance(probed_template, str) else None
+            proxy_id = proxy_id or (probed_proxy_id if isinstance(probed_proxy_id, str) else None)
+            if template and routes:
+                route = _find_matching_route(template, routes)
+
+    if require_route and route is None:
+        return RoutingResult(
+            base_url=None,
+            proxy_id=None,
+            template=None,
+            source="unresolved",
+            route=None,
+            credential=None,
+            warning=_join_warnings(
+                warning,
+                f"Session proxy at {base_url} has no matching route; treating as unresolved.",
+            ),
+        )
+
+    return RoutingResult(
+        base_url=base_url,
+        proxy_id=proxy_id,
+        template=template,
+        source="session_proxy",
+        route=route,
+        credential=route.credential if route else None,
+        warning=_route_warning(
+            route,
+            base_url=base_url,
+            metadata=probed,
+            advisory_check=advisory_check,
+            warning=warning,
+        ),
+    )