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.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
"""Model routing for Vibey over Model Hub hop resolution (C-2, C-6).
Model Hub answers "how should the ``vibey`` backend call model M now" with a
``HopResolution`` (``ModelHubRuntimeRouter.resolve_hop``). ``selection_from_hop``
turns it into the loop's ``ModelEndpoint`` and ``ModelCapabilities`` and keeps
unknown capabilities ``None``; the loop applies the conservative defaults.
Transport is the provider adapter registered for the endpoint's protocol.
A ``google`` hop is called natively, at the gateway's ``/v1beta`` Gemini
surface (``vibey-gemini-native.md``). The served origin comes from
``x-avibe-served-hop`` on every protocol.
Each enabled hosted tool's route rides on the endpoint as Model Hub resolved it
(``hosted_tools``): an adapter declares a tool natively exactly where its mode
is ``native``, and pins that request to the hop's Source
(``vibey-hosted-tools.md`` §3.5, §4.1). The agent never decides nativity.
"""
from __future__ import annotations
import logging
from dataclasses import replace
import re
from typing import Any, Awaitable, Callable, Mapping, Optional
from core.agent_core.agent.models import ModelSelection
from core.agent_core.ai.provider import (
HostedToolRoute,
ImageModel,
ImageModels,
ModelCapabilities,
ModelEndpoint,
ProviderAdapter,
)
from core.agent_core.messages import HOSTED_TOOLS, PROTOCOLS, ProtocolName
logger = logging.getLogger(__name__)
SelectionResolver = Callable[[], Awaitable[ModelSelection]]
ProviderFactory = Callable[[ProtocolName], ProviderAdapter]
class HopResolutionError(ValueError):
"""Model Hub returned a hop the agent cannot call."""
def _optional(value: Any, kind: type, what: str) -> Any:
if value is None:
return None
if not isinstance(value, kind) or (isinstance(value, bool) and kind is not bool):
raise HopResolutionError(f"hop capability {what} must be {kind.__name__} or null")
return value
#: The facts of one search tool's ``hosted_tools`` entry, exactly (hop-resolution.schema.json): the declaration and
#: include values are present exactly when the tool is assumed to run natively.
_FACTS = ("assumed", "unsupported")
_SEARCH_KEYS = {"assumed": {"native", "replay", "declaration", "include"}, "unsupported": {"native", "replay"}}
#: A key an ``unsupported`` entry may carry: the hop's own Source refused the tool (C-6 ``refused``).
_REFUSED_KEY = "refused"
_IMAGE_KEYS = {"source_id", "model_id", "description", "params", "size_forms"}
_IMAGE_PARAMS = {"size", "images", "n"}
_SIZE_FORMS = {"pixels", "ratio"}
_SOURCE_ID = re.compile(r"src_[a-z0-9]{8,}")
def _hosted_routes(raw: Any) -> tuple[dict[str, HostedToolRoute], Optional[ImageModels]]:
"""``HopResolution.hosted_tools``: each enabled search tool's facts as its route, and ``image_generate``'s models."""
if not isinstance(raw, Mapping):
raise HopResolutionError("hop has no hosted_tools")
routes: dict[str, HostedToolRoute] = {}
images: Optional[ImageModels] = None
for tool, entry in raw.items():
try:
if tool == "image_generate":
images = _image_models(entry)
else:
routes[tool] = _hosted_route(tool, entry)
except (TypeError, ValueError, KeyError) as error:
# Every malformed entry fails here, whatever the parse raised on it.
raise HopResolutionError(f"hop hosted tool {tool!r} is invalid: {error}") from None
return routes, images
def _hosted_route(tool: Any, entry: Any) -> HostedToolRoute:
"""One search tool's facts, exactly as the hop schema allows them: declared natively exactly when ``native`` is
``assumed`` (§3.4, §4.1)."""
if tool == "web_fetch":
if entry != {"native": "unsupported", "replay": "unsupported"}:
raise ValueError("web_fetch is function-only, with no native replay")
return HostedToolRoute(mode="proxy", replay=False)
if tool not in HOSTED_TOOLS or not isinstance(entry, Mapping):
raise ValueError("not a search tool entry")
native, replay = entry.get("native"), entry.get("replay")
if native not in _FACTS or replay not in _FACTS:
raise ValueError("native and replay are each assumed or unsupported")
refused = _REFUSED_KEY in entry
if refused and (native != "unsupported" or entry[_REFUSED_KEY] is not True):
raise ValueError("refused is true, and only on an unsupported entry")
if set(entry) - {_REFUSED_KEY} != _SEARCH_KEYS[native]:
raise ValueError(f"a {native} entry has exactly {', '.join(sorted(_SEARCH_KEYS[native]))}")
include = entry.get("include", [])
if not isinstance(include, list):
raise ValueError("include must be a list")
return HostedToolRoute(
mode="native" if native == "assumed" else "proxy",
replay=replay == "assumed",
declaration=entry.get("declaration"),
include=tuple(include),
refused=refused,
)
def _image_models(entry: Any) -> ImageModels:
"""``image_generate``'s models, default first, exactly as the hop schema allows them (§7.2)."""
if not isinstance(entry, Mapping) or set(entry) != {"models", "default"}:
raise ValueError("an image_generate entry has exactly models and default")
raw_models, default = entry["models"], entry["default"]
if not isinstance(raw_models, list) or not raw_models:
raise ValueError("models is a non-empty list")
models = []
for item in raw_models:
if not isinstance(item, Mapping) or set(item) != _IMAGE_KEYS:
raise ValueError(f"an image model has exactly {', '.join(sorted(_IMAGE_KEYS))}")
if not isinstance(item["source_id"], str) or not _SOURCE_ID.fullmatch(item["source_id"]):
raise ValueError("an image model names its Source")
for name in ("model_id", "description"):
if not isinstance(item[name], str) or not item[name]:
raise ValueError(f"an image model has a {name}")
params, forms = item["params"], item["size_forms"]
if not isinstance(params, list) or not set(params) <= _IMAGE_PARAMS or len(set(params)) != len(params):
raise ValueError("params lists distinct size, images and n")
if not isinstance(forms, list) or not set(forms) <= _SIZE_FORMS or len(set(forms)) != len(forms):
raise ValueError("size_forms lists distinct pixels and ratio")
models.append(
ImageModel(item["source_id"], item["model_id"], item["description"], tuple(params), tuple(forms))
)
if not isinstance(default, Mapping) or set(default) != {"source_id", "model_id"}:
raise ValueError("default is a Source id and a model id")
if (models[0].source_id, models[0].model_id) != (default["source_id"], default["model_id"]):
raise ValueError("the default is the first model")
return ImageModels(tuple(models))
def selection_from_hop(hop: Mapping[str, Any]) -> ModelSelection:
"""Build the loop's selection from one ``HopResolution`` (hop-resolution.schema.json)."""
if hop.get("backend") != "vibey":
raise HopResolutionError(f"hop resolved for backend {hop.get('backend')!r}, not vibey")
protocol = hop.get("protocol")
if protocol not in PROTOCOLS:
raise HopResolutionError(f"hop protocol {protocol!r} is not supported")
for name in ("base_url", "token", "runtime_model", "provider", "source_id", "source_identity"):
if not isinstance(hop.get(name), str) or not hop[name]:
raise HopResolutionError(f"hop has no {name}")
headers = hop.get("request_headers")
if not isinstance(headers, Mapping) or not all(
isinstance(key, str) and isinstance(value, str) for key, value in headers.items()
):
raise HopResolutionError("hop request_headers must map strings to strings")
hosted_tools, image_models = _hosted_routes(hop.get("hosted_tools"))
raw = hop.get("capabilities")
if not isinstance(raw, Mapping):
raise HopResolutionError("hop has no capabilities")
efforts = raw.get("reasoning_efforts") or []
if not isinstance(efforts, (list, tuple)) or not all(isinstance(item, str) for item in efforts):
raise HopResolutionError("hop capability reasoning_efforts must be a list of strings")
steps = raw.get("context_price_steps") or []
if not isinstance(steps, (list, tuple)) or not all(
isinstance(size, int) and not isinstance(size, bool) and size > 0 for size in steps
):
raise HopResolutionError("hop capability context_price_steps must be a list of positive integers")
capabilities = ModelCapabilities(
context_window=_optional(raw.get("context_window"), int, "context_window"),
input_limit=_optional(raw.get("input_limit"), int, "input_limit"),
max_output_tokens=_optional(raw.get("max_output_tokens"), int, "max_output_tokens"),
supports_tools=_optional(raw.get("supports_tools"), bool, "supports_tools"),
supports_images=_optional(raw.get("supports_images"), bool, "supports_images"),
supports_reasoning=_optional(raw.get("supports_reasoning"), bool, "supports_reasoning"),
reasoning_efforts=tuple(efforts),
context_price_steps=tuple(sorted(steps)),
)
base_url = hop["base_url"]
raw_cache_ttl = hop.get("cache_ttl")
if raw_cache_ttl is not None and (
not isinstance(raw_cache_ttl, str)
or raw_cache_ttl not in {"5m", "30m", "1h", "12h"}
):
raise HopResolutionError("hop cache_ttl is invalid")
cache_ttl = raw_cache_ttl
raw_cache_ttl_wire = hop.get("cache_ttl_wire", False)
if not isinstance(raw_cache_ttl_wire, bool):
raise HopResolutionError("hop cache_ttl_wire is invalid")
cache_ttl_wire = raw_cache_ttl_wire
if cache_ttl_wire and cache_ttl not in {"30m", "12h"}:
raise HopResolutionError("hop cache_ttl_wire requires 30m or 12h")
endpoint = ModelEndpoint(
protocol=protocol,
base_url=base_url,
model_id=hop["runtime_model"],
token=hop["token"],
request_headers=dict(headers),
provider=hop["provider"],
cache_ttl=cache_ttl,
cache_ttl_wire=cache_ttl_wire,
source_id=hop["source_id"],
source_identity=hop["source_identity"],
hosted_tools=hosted_tools,
image_models=image_models,
)
return ModelSelection(endpoint=endpoint, capabilities=capabilities)
class HubModelRouter:
"""``ModelRouter`` for one run: a fresh hop for every model attempt (C-6 item 3).
``first`` is the selection the adapter already resolved during preflight; the
loop's first attempt reuses it, so a run resolves once and again only after a
retryable error or a refusal (``vibey-hosted-tools.md`` §3.5).
"""
def __init__(
self,
resolve: SelectionResolver,
providers: ProviderFactory,
*,
first: Optional[ModelSelection] = None,
) -> None:
self._resolve = resolve
self._providers = providers
self._first = first
#: The route preflight resolved; the Turn's tool list is fixed from it.
self.preflight = first
#: The hop the Turn runs on now, its latest resolution. The gateway answers the Turn's requests only on that
#: hop's credential (C-6 item 3), so the Turn's hosted calls go out on it too.
self.current = first
self.prefix_declarations: tuple[tuple[str, ...], Mapping[str, Any]] | None = None
self._adapters: dict[str, ProviderAdapter] = {}
async def resolve(self) -> ModelSelection:
if self._first is not None:
selection, self._first = self._first, None
else:
selection = await self._resolve()
selection = self.prompt_route(selection)
self.current = selection
return selection
def prompt_route(self, selection: ModelSelection) -> ModelSelection:
"""Only the saved route's declarations are cached; fallbacks and live refusals remain authoritative."""
from modules.agents.vibey.prompt_snapshot import frozen_hosted, route_identity
if self.prefix_declarations is not None:
route, hosted = self.prefix_declarations
if route_identity(selection.endpoint) == route:
selection = replace(selection, endpoint=replace(selection.endpoint, hosted_tools=frozen_hosted(selection.endpoint, hosted)))
return selection
def provider_for(self, protocol: ProtocolName) -> ProviderAdapter:
adapter = self._adapters.get(protocol)
if adapter is None:
adapter = self._adapters[protocol] = self._providers(protocol)
return adapter
async def aclose(self) -> None:
"""Close every adapter, best effort: run cleanup never changes the Turn's outcome."""
adapters, self._adapters = list(self._adapters.items()), {}
for protocol, adapter in adapters:
close = getattr(adapter, "aclose", None)
if close is None:
continue
try:
await close()
except Exception:
logger.warning("Vibey could not close its %s provider adapter", protocol, exc_info=True)
def registry_providers(*, media_loader: Any, client: Any = None) -> ProviderFactory:
"""Provider adapters from the ``ai`` registry, speaking to the Model Hub gateway.
In gateway mode each adapter reads the served origin from ``x-avibe-served-hop``
with the engine's own resolver, the one owner of that C-6 rule.
"""
def create(protocol: ProtocolName) -> ProviderAdapter:
from core.agent_core.ai.registry import create_adapter
return create_adapter(protocol, client=client, media_loader=media_loader, gateway=True)
return create