Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

23.5 KB
Raw Blame
"""Pure Model Hub routing from explicit overrides and backend defaults."""

from __future__ import annotations

import re
from dataclasses import dataclass, replace
from datetime import datetime, timezone
from typing import Literal, Mapping

from config.v2_config import (
    MODEL_HUB_BACKENDS,
    ModelHubConfig,
    ModelHubRouteConfig,
    ModelHubRouteHopConfig,
    ModelHubSourceConfig,
    normalized_model_hub_override,
)


from modules.agents.catalog import AgentBackend

BackendName = AgentBackend
ResolutionChannel = Literal["direct", "native_cli", "hub", "unavailable"]
SupplyStatus = Literal["ok", "degraded", "waiting", "interrupted"]
RouteOrigin = Literal["automatic", "manual", "passthrough"]
CacheTtl = Literal["5m", "30m", "1h", "12h"]
_CACHE_TTL_VALUES = frozenset(("5m", "30m", "1h", "12h"))
_GPT_MODEL = re.compile(
    r"gpt-(?P<major>\d+)(?:\.(?P<minor>\d+))?(?:-[a-z0-9]+(?:[.-][a-z0-9]+)*)?",
    re.ASCII,
)


@dataclass(frozen=True)
class EffectiveModelRoute:
    manual_override: ModelHubRouteConfig | None
    route_origin: RouteOrigin | None
    hops: tuple[ModelHubRouteHopConfig, ...]
    cache_ttl: CacheTtl | None = None


@dataclass(frozen=True)
class SourceRecoveryAnnotation:
    reason: str
    retry_at: str | None = None
    in_flight: bool = False
    # Recovery retires only this exact old disk observation, never a later
    # cooldown in a fresh config or a draft with the same Source identity.
    retired_cooldown: tuple[str | None, str | None] | None = None


@dataclass(frozen=True)
class ExactHopInspection:
    """Canonical identity and live eligibility for one effective Route hop."""

    backend: BackendName
    menu_model: str
    source_id: str | None
    model_id: str | None
    source: ModelHubSourceConfig | None
    configuration_eligible: bool
    inventory_member: bool
    supply_eligible: bool
    runnable: bool
    structural_blocker: bool
    reason: str | None
    retry_at: str | None
    backoff: bool = False
    recovery: Literal["eligible", "in_flight"] | None = None
    cooldown: bool = False
    cooldown_reason: str | None = None

    @property
    def temporary_blocker(self) -> bool:
        return (
            self.source is not None and self.supply_eligible
            and not self.structural_blocker
            and self.source.state.status not in {"needs_action", "error"}
            and (self.backoff or self.cooldown or self.recovery == "in_flight")
        )

    @property
    def identity(self) -> tuple[BackendName, str, str | None, str | None]:
        return self.backend, self.menu_model, self.source_id, self.model_id


@dataclass(frozen=True)
class ModelHubTurnResolution:
    backend: BackendName
    channel: ResolutionChannel
    requested_model: str
    target_model: str
    source: ModelHubSourceConfig | None
    manual_override: ModelHubRouteConfig | None = None
    route_origin: RouteOrigin | None = None
    cache_ttl: CacheTtl | None = None
    cache_ttl_wire: bool = False
    matching_sources: tuple[ModelHubSourceConfig, ...] = ()
    candidates: tuple[ModelHubSourceConfig, ...] = ()
    candidate_hops: tuple[ExactHopInspection, ...] = ()
    projectable_hops: tuple[ExactHopInspection, ...] = ()
    source_model_ids: tuple[tuple[str, str], ...] = ()
    inspected_hops: tuple[ExactHopInspection, ...] = ()
    unsupported_source_ids: tuple[str, ...] = ()
    route_unconfigured: bool = False
    route_reason: str | None = None
    provider: str | None = None
    recoverable_source_ids: tuple[str, ...] = ()
    supply_status: SupplyStatus | None = None

    def self_healing_hops(self, supply_channel: str | None) -> tuple[ExactHopInspection, ...]:
        """Blocked hops that may become runnable unattended, for recovery control.

        ``supply_status`` answers whether the user owes an action, so one revoked
        key makes a chain ``interrupted``. Whether a request may wait is a
        different question: any of these hops lets it wait for recovery.
        """

        return tuple(
            hop for hop in self.inspected_hops
            if hop.temporary_blocker
            and (supply_channel is None or hop.source.supply_channel == supply_channel)
        )

    @property
    def structural_blocker_reason(self) -> str | None:
        if self.route_reason == "route_unconfigured":
            return self.route_reason
        return next(
            (
                inspection.reason
                for inspection in self.inspected_hops
                if inspection.structural_blocker
            ),
            None,
        )


def allowed_origins(source: ModelHubSourceConfig) -> tuple[str, ...]:
    if source.kind == "api_key":
        return ()
    if source.supply_channel == "hub":
        return tuple(MODEL_HUB_BACKENDS)
    if source.vendor == "anthropic":
        return ("claude",)
    if source.vendor == "openai":
        return ("codex",)
    return ()


def source_eligible_for_backend(source: ModelHubSourceConfig, backend: str) -> bool:
    return ModelHubConfig.source_eligible_for_backend(source, backend)


def parse_model_hub_timestamp(value: str) -> datetime:
    """Compare ISO instants, interpreting older naive records as UTC."""

    parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
    return parsed.replace(tzinfo=timezone.utc) if parsed.tzinfo is None else parsed


def source_retry_ready(source: ModelHubSourceConfig, now: datetime | None) -> bool:
    if source.state.status != "cooldown" or now is None:
        return False
    try:
        retry_at = parse_model_hub_timestamp(source.state.retry_at or "")
    except ValueError:
        return False
    return retry_at <= now


def source_after_cooldown_recovery(
    source: ModelHubSourceConfig,
    now: datetime | None,
) -> ModelHubSourceConfig:
    if not source_retry_ready(source, now):
        return source
    return replace(
        source,
        state=replace(
            source.state,
            status=("active" if source.supply_channel == "native_cli" else "standby"),
            retry_at=None,
            detail_key=None,
        ),
    )


def source_runnable(
    source: ModelHubSourceConfig,
    *,
    now: datetime | None,
    unavailable_source_ids: frozenset[str] = frozenset(),
    model_supported: bool = True,
) -> bool:
    if not model_supported:
        return False
    if source.id in unavailable_source_ids:
        return False
    if source.state.status in {"active", "standby"}:
        return True
    return source_retry_ready(source, now)


_CLAUDE_FAMILY_ALIASES = {
    "opus": "opus",
    "opus[1m]": "opus",
    "sonnet": "sonnet",
    "sonnet[1m]": "sonnet",
    "haiku": "haiku",
}
_CLAUDE_MODEL_ID = re.compile(
    r"^claude-(?P<family>opus|sonnet|haiku|fable)-(?P<version>\d+(?:-\d+)*?)(?:-(?P<date>\d{8}))?$"
)


def _parsed_claude_model_id(model_id: str) -> tuple[str, tuple[int, ...], int | None] | None:
    match = _CLAUDE_MODEL_ID.fullmatch(model_id)
    if match is None:
        return None
    return (
        match.group("family"),
        tuple(int(part) for part in match.group("version").split("-")),
        int(match.group("date")) if match.group("date") else None,
    )


def matching_v1_model_id(
    *,
    backend: BackendName,
    requested_model: str,
    source: ModelHubSourceConfig,
    include_manual: bool = False,
) -> str | None:
    """Match one inventory id using the established literal/native Claude policy."""

    observed_models = tuple(
        model
        for model in source.models
        if (include_manual or model.provenance == "discovered") and not model.retired
    )

    if (
        backend == "claude"
        and source.vendor == "anthropic"
        and source.supply_channel == "native_cli"
    ):
        family = _CLAUDE_FAMILY_ALIASES.get(requested_model)
        requested_version: tuple[int, ...] | None = None
        parsed_request = _parsed_claude_model_id(requested_model)
        if family is None and parsed_request is not None:
            family, requested_version, requested_date = parsed_request
            if requested_date is not None:
                return next(
                    (model.id for model in observed_models if model.id == requested_model),
                    None,
                )
        if family is not None:
            matches: list[tuple[tuple[int, ...], int, str]] = []
            for model in observed_models:
                parsed = _parsed_claude_model_id(model.id)
                if parsed is None:
                    continue
                candidate_family, candidate_version, candidate_date = parsed
                if candidate_family != family:
                    continue
                if requested_version is not None and candidate_version != requested_version:
                    continue
                matches.append((candidate_version, candidate_date or 0, model.id))
            return max(matches)[2] if matches else None

    return next(
        (model.id for model in observed_models if model.id == requested_model),
        None,
    )


def source_model_retired(source: ModelHubSourceConfig, model_id: str) -> bool:
    return any(model.id == model_id and model.retired for model in source.models)


def source_supports_passthrough(source: ModelHubSourceConfig) -> bool:
    return source.kind == "api_key" and source.supply_channel == "hub" and source.protocol != "search"


def is_official_openai_responses_route(
    config: ModelHubConfig,
    backend: BackendName,
    route: ModelHubRouteConfig,
) -> bool:
    """Whether every hop is the official OpenAI Responses GPT-5.6+ route.

    A missing/custom endpoint is deliberately not treated as official: an
    OpenAI-compatible relay may speak the same wire protocol without honoring
    OpenAI's prompt-cache retention option.
    """

    if backend != "vibey" or not route.hops:
        return False
    sources = {source.id: source for source in config.sources}
    for hop in route.hops:
        source = sources.get(hop.source_id)
        match = _GPT_MODEL.fullmatch(hop.model_id)
        if (
            source is None
            or source.vendor != "openai"
            or source.protocol != "openai_responses"
            or source.base_url is not None
            or match is None
            or (int(match.group("major")), int(match.group("minor") or 0)) < (5, 6)
        ):
            return False
    return True


def validate_cache_ttl_override(
    config: ModelHubConfig,
    backend: BackendName,
    route: ModelHubRouteConfig,
) -> None:
    """Validate route-local cache lifetime without granting relay OpenAI semantics."""

    ttl = route.cache_ttl
    if ttl is None:
        return
    if backend != "vibey":
        raise ValueError("cache_ttl is supported only for Vibey routes")
    if not isinstance(ttl, str) or ttl not in _CACHE_TTL_VALUES or not route.hops:
        raise ValueError("cache_ttl is not supported for this route")
    official_openai = is_official_openai_responses_route(config, backend, route)
    if ttl == "12h" and not official_openai:
        raise ValueError("12h is supported only by an official OpenAI Responses GPT-5.6+ route")
    if official_openai and ttl not in {"30m", "12h"}:
        raise ValueError("official OpenAI Responses routes support only 30m or 12h")
    if (
        backend == "vibey"
        and all(
            (source := next((item for item in config.sources if item.id == hop.source_id), None)) is not None
            and source.vendor == "anthropic"
            and source.protocol == "anthropic"
            and source.base_url is None
            for hop in route.hops
        )
        and ttl != "1h"
    ):
        raise ValueError("official Anthropic Claude routes support only 1h")


def effective_model_route(
    config: ModelHubConfig,
    backend: BackendName,
    requested_model: str,
) -> EffectiveModelRoute:
    """Choose one route tier before live health or transport restriction."""

    agent = config.agents[backend]
    override = normalized_model_hub_override(agent.routes.get(requested_model))
    if override is not None:
        return EffectiveModelRoute(override, "manual", override.hops, override.cache_ttl)
    if not requested_model or not any(model.id == requested_model for model in agent.models):
        return EffectiveModelRoute(None, None, ())
    by_id = {source.id: source for source in config.sources}
    sources = [
        by_id[source_id]
        for source_id in agent.sources.order
        if source_id in by_id and source_eligible_for_backend(by_id[source_id], backend)
    ]
    matches = tuple(
        ModelHubRouteHopConfig(source.id, matched)
        for source in sources
        if (matched := matching_v1_model_id(
            backend=backend,
            requested_model=requested_model,
            source=source,
            include_manual=True,
        )) is not None
    )
    if matches:
        return EffectiveModelRoute(None, "automatic", matches)
    hops = tuple(
        ModelHubRouteHopConfig(source.id, requested_model)
        for source in sources
        if source_supports_passthrough(source) and not source_model_retired(source, requested_model)
    )
    return EffectiveModelRoute(None, "passthrough" if hops else None, hops)


def inspect_exact_hop(
    config: ModelHubConfig,
    backend: BackendName,
    menu_model: str,
    hop: ModelHubRouteHopConfig | None,
    *,
    now: datetime | None = None,
    unavailable_source_ids: frozenset[str] = frozenset(),
    supply_channel: Literal["hub"] | None = None,
    live_recovery: Mapping[str, SourceRecoveryAnnotation] | None = None,
) -> ExactHopInspection:
    """Inspect one exact hop without matching, substituting, or reordering it."""

    if hop is None:
        return ExactHopInspection(
            backend=backend,
            menu_model=menu_model,
            source_id=None,
            model_id=None,
            source=None,
            configuration_eligible=False,
            inventory_member=False,
            supply_eligible=False,
            runnable=False,
            structural_blocker=True,
            reason="route_unconfigured",
            retry_at=None,
        )

    source = next((item for item in config.sources if item.id == hop.source_id), None)
    if source is None:
        return ExactHopInspection(
            backend=backend,
            menu_model=menu_model,
            source_id=hop.source_id,
            model_id=hop.model_id,
            source=None,
            configuration_eligible=False,
            inventory_member=False,
            supply_eligible=False,
            runnable=False,
            structural_blocker=True,
            reason="source_missing",
            retry_at=None,
        )

    configuration_eligible = source_eligible_for_backend(source, backend)
    inventory_member = any(
        model.id == hop.model_id and not model.retired
        for model in source.models
    )
    channel_eligible = supply_channel is None or source.supply_channel == supply_channel
    model_supported = inventory_member or (
        source_supports_passthrough(source) and not source_model_retired(source, hop.model_id)
    )
    supply_eligible = configuration_eligible and model_supported and channel_eligible
    runnable = supply_eligible and source_runnable(
        source,
        now=now,
        unavailable_source_ids=unavailable_source_ids,
        model_supported=model_supported,
    )
    reason: str | None = None
    structural_blocker = False
    if not model_supported or not configuration_eligible:
        reason = "model_unsupported"
        structural_blocker = True
    elif source.id in unavailable_source_ids:
        reason = "native_cli_unavailable"
        structural_blocker = True
    elif source.state.status in {"needs_action", "error"}:
        reason = source.state.detail_key
    annotation = (live_recovery or {}).get(source.id) if source.supply_channel == "hub" else None
    backoff = False
    recovery = None
    cooldown = source.state.status == "cooldown"
    cooldown_reason = None
    retry_at = source.state.retry_at if source.state.status == "cooldown" else None
    if annotation is not None and supply_eligible and source.state.status not in {"needs_action", "error"}:
        if not structural_blocker:
            retired = (
                cooldown and annotation.retired_cooldown is not None
                and annotation.retired_cooldown == (source.state.retry_at, source.state.detail_key)
            )
            if retired:
                cooldown = False
            if annotation.reason != "recovery" and (annotation.reason != "network" or not cooldown):
                cooldown_reason = annotation.reason
            if annotation.reason == "recovery":
                if retired:
                    runnable = True
                    retry_at = None
            elif annotation.retry_at is not None:
                runnable = False
                retry_at = annotation.retry_at
                backoff = annotation.reason == "network" and not cooldown
                cooldown = not backoff
                if backoff:
                    reason = "models.source.backoff.connection_failed"
            else:
                recovery = "in_flight" if annotation.in_flight else "eligible"
                runnable = not annotation.in_flight
                cooldown = False
                retry_at = None
    return ExactHopInspection(
        backend=backend,
        menu_model=menu_model,
        source_id=source.id,
        model_id=hop.model_id,
        source=source,
        configuration_eligible=configuration_eligible,
        inventory_member=inventory_member,
        supply_eligible=supply_eligible,
        runnable=runnable,
        structural_blocker=structural_blocker,
        reason=reason,
        retry_at=retry_at,
        backoff=backoff,
        recovery=recovery,
        cooldown=cooldown,
        cooldown_reason=cooldown_reason,
    )


def _supply_status(
    inspections: tuple[ExactHopInspection, ...],
    *,
    now: datetime | None,
    unavailable_source_ids: frozenset[str],
) -> SupplyStatus:
    if not inspections:
        return "interrupted"
    if any(inspection.runnable for inspection in inspections):
        return "ok" if all(inspection.runnable for inspection in inspections) else "degraded"
    if all(
        inspection.temporary_blocker
        for inspection in inspections
    ):
        return "waiting"
    return "interrupted"


def resolve_model_hub_turn(
    config: ModelHubConfig,
    backend: BackendName,
    requested_model: str,
    *,
    now: datetime | None = None,
    unavailable_source_ids: frozenset[str] = frozenset(),
    supply_channel: Literal["hub"] | None = None,
    live_recovery: Mapping[str, SourceRecoveryAnnotation] | None = None,
) -> ModelHubTurnResolution:
    """Annotate the effective route without changing its membership or tier."""

    requested_model = str(requested_model or "").strip()
    agent = config.agents[backend]
    if agent.mode == "direct":
        return ModelHubTurnResolution(
            backend=backend,
            channel="direct",
            requested_model=requested_model,
            target_model=requested_model,
            source=None,
        )

    if backend == "opencode":
        if not requested_model:
            return ModelHubTurnResolution(
                backend=backend,
                channel="unavailable",
                requested_model=requested_model,
                target_model=requested_model,
                source=None,
                supply_status="interrupted",
            )

    route = effective_model_route(config, backend, requested_model)

    inspected_hops = tuple(
        inspect_exact_hop(
            config,
            backend,
            requested_model,
            hop,
            now=now,
            unavailable_source_ids=unavailable_source_ids,
            supply_channel=supply_channel,
            live_recovery=live_recovery,
        )
        for hop in route.hops
    )
    route_reason = (
        inspect_exact_hop(
            config,
            backend,
            requested_model,
            None,
            now=now,
            unavailable_source_ids=unavailable_source_ids,
            supply_channel=supply_channel,
            live_recovery=live_recovery,
        ).reason
        if not route.hops
        else None
    )
    matching_inspections = tuple(
        inspection
        for inspection in inspected_hops
        if inspection.source is not None
    )
    matching_sources = tuple(
        inspection.source
        for inspection in matching_inspections
        if inspection.source is not None
    )
    source_model_ids = tuple(
        (inspection.source_id, inspection.model_id)
        for inspection in matching_inspections
        if inspection.source_id is not None and inspection.model_id is not None
    )
    unsupported_source_ids = frozenset(
        inspection.source_id
        for inspection in matching_inspections
        if inspection.reason == "model_unsupported"
        and inspection.source_id is not None
    )
    runnable_inspections = tuple(
        inspection
        for inspection in matching_inspections
        if inspection.runnable
    )
    candidates = tuple(
        inspection.source
        for inspection in runnable_inspections
        if inspection.source is not None
    )
    projectable_hops = tuple(
        inspection
        for inspection in matching_inspections
        if inspection.configuration_eligible
        and (
            supply_channel is None
            or (
                inspection.source is not None
                and inspection.source.supply_channel == supply_channel
            )
        )
    )
    recoverable = tuple(
        source.id
        for source in matching_sources
        if source.state.status == "cooldown" and source_retry_ready(source, now)
    )
    first_inspection = runnable_inspections[0] if runnable_inspections else None
    target_model = (
        first_inspection.model_id
        if first_inspection is not None
        else inspected_hops[0].model_id
        if inspected_hops
        else requested_model
    )
    channel: ResolutionChannel = "unavailable"
    first = first_inspection.source if first_inspection is not None else None
    if first is not None:
        channel = first.supply_channel
    cache_ttl = route.cache_ttl
    if route.manual_override is not None:
        try:
            validate_cache_ttl_override(config, backend, route.manual_override)
        except ValueError:
            cache_ttl = None
    return ModelHubTurnResolution(
        backend=backend,
        channel=channel,
        requested_model=requested_model,
        target_model=target_model or requested_model,
        source=first,
        manual_override=route.manual_override,
        route_origin=route.route_origin,
        cache_ttl=cache_ttl,
        cache_ttl_wire=(
            cache_ttl in {"30m", "12h"}
            and is_official_openai_responses_route(config, backend, route)
        ),
        matching_sources=matching_sources,
        candidates=candidates,
        candidate_hops=runnable_inspections,
        projectable_hops=projectable_hops,
        source_model_ids=source_model_ids,
        inspected_hops=inspected_hops,
        unsupported_source_ids=tuple(unsupported_source_ids),
        route_unconfigured=route_reason == "route_unconfigured",
        route_reason=route_reason,
        recoverable_source_ids=recoverable,
        supply_status=_supply_status(
            tuple(
                hop for hop in inspected_hops
                if supply_channel is None or hop.source is None
                or hop.source.supply_channel == supply_channel
                or hop.structural_blocker or hop.source.state.status in {"needs_action", "error"}
            ),
            now=now,
            unavailable_source_ids=unavailable_source_ids,
        ),
    )