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.

18.5 KB
Raw Blame
"""Shared shipped api-key vendor catalog for Model Hub observation."""

from __future__ import annotations

import json
from dataclasses import dataclass
from functools import lru_cache
from pathlib import Path
from typing import Any, Mapping
from urllib.parse import urlsplit

from config.v2_config import normalize_model_hub_base_url, normalize_model_hub_vendor_id


_SUPPORTED_PROTOCOLS = {"anthropic", "openai_responses", "openai_chat", "google", "search"}
_LEGACY_OFFICIAL_BASE_URLS = {
    # ``codex`` remains a supported legacy vendor alias outside the shipped
    # api-key vendor preset catalog. Runtime official-URL fallback must keep
    # treating it like OpenAI for persisted Sources that omit ``base_url``.
    "codex": "https://api.openai.com/v1",
}


def google_api_base_url(base_url: str | None) -> str:
    """CPA's Gemini executor appends /v1beta itself, including on custom roots."""
    normalized = normalize_model_hub_base_url(base_url)
    if normalized is None:
        raise ValueError("Google source requires a base URL")
    if urlsplit(normalized).query:
        raise ValueError("Google source Base URL cannot contain a query")
    return normalized.removesuffix("/v1beta")


def _validated_cpa_anthropic_origin(base_url: str | None) -> bool:
    """Share CPA's authority gate, rejecting ambiguous HTTP URL spellings."""
    if not isinstance(base_url, str) or any(ord(char) <= 32 or ord(char) == 127 for char in base_url):
        raise ValueError
    normalized = normalize_model_hub_base_url(base_url)
    if normalized is None:
        raise ValueError
    parsed = urlsplit(normalized)
    hostname = parsed.hostname
    if not hostname or "%" in parsed.netloc or "\\" in parsed.netloc or parsed.port == 0:
        raise ValueError
    ascii_hostname = hostname.encode("idna").decode("ascii").lower()
    if ascii_hostname == "api.anthropic.com" and hostname.lower() != ascii_hostname:
        # Python's HTTP client can normalize these to the official host while
        # Go's URL authority gate sees the original spelling. Admit neither.
        raise ValueError
    return (
        parsed.scheme == "https"
        and hostname.lower() == "api.anthropic.com"
        # CPA compares URL.Port() as text: :0443 is not its official origin.
        and (parsed.port is None or parsed.netloc.rsplit(":", 1)[-1] == "443")
    )


def anthropic_api_key_header(base_url: str, secret: str) -> dict[str, str]:
    """The header the pinned engine sends a static Anthropic key in.

    Observation authenticates exactly as the engine will, so a verdict at add
    predicts every later call. CPA (``applyClaudeHeadersWithNativeProfile``)
    sends ``x-api-key`` only to its official origin, and Bearer to every other
    origin and for any key its ``sk-ant-oat`` heuristic takes as OAuth.
    """
    if _validated_cpa_anthropic_origin(base_url) and "sk-ant-oat" not in secret:
        return {"x-api-key": secret}
    return {"Authorization": f"Bearer {secret}"}


def validate_api_key_auth_scheme(
    vendor: str,
    protocol: str | None,
    base_url: str | None,
    secret: str | None,
    auth_scheme: str | None,
) -> str | None:
    """Validate explicit static transport without reinterpreting legacy keys.

    A missing protocol is only for an unbound observation credential. A missing
    secret is only for the credentialless contrast of an already validated
    transport. Bearer is the Anthropic interface's custom-origin header, for any
    vendor not pinned to another protocol. The pinned CPA sends ordinary custom
    Claude keys as Bearer, but interprets ``sk-ant-oat`` anywhere in a key as
    OAuth independently of kind.
    """
    if auth_scheme is None:
        return None
    try:
        if (
            auth_scheme != "bearer"
            or not isinstance(vendor, str)
            or not vendor.strip()
            # Any Anthropic interface: custom relays and Anthropic-pinned vendors.
            or pinned_api_key_protocol(vendor) not in (None, "anthropic")
            or protocol not in (None, "anthropic")
        ):
            raise ValueError
        if _validated_cpa_anthropic_origin(base_url):
            raise ValueError
        if secret is not None and (
            not isinstance(secret, str)
            or not secret.strip()
            or "sk-ant-oat" in secret
            or any(ord(char) < 32 or ord(char) == 127 for char in secret)
        ):
            raise ValueError
    except (TypeError, ValueError):
        raise ValueError("unsupported API key authentication scheme") from None
    return "bearer"


def validate_migration_api_key_transport(
    vendor: str,
    protocol: str,
    base_url: str | None,
    secret: str | None,
    auth_scheme: str | None,
) -> None:
    """Admit native static auth only when proof and pinned CPA preserve it.

    This is a migration gate, not a new default for public Sources or legacy
    credential metadata. Anthropic SDK/API_KEY inputs mean x-api-key; CPA uses
    that header only at its official origin. Static keys matching its OAuth
    heuristic are unsafe at either origin, regardless of successful proof.
    """
    try:
        validate_api_key_auth_scheme(vendor, protocol, base_url, secret, auth_scheme)
        if protocol != "anthropic":
            return
        if not isinstance(secret, str) or not secret.strip() or "sk-ant-oat" in secret:
            raise ValueError
        if auth_scheme is None and not _validated_cpa_anthropic_origin(
            base_url if base_url is not None else official_api_key_base_url(vendor)
        ):
            raise ValueError
    except (TypeError, ValueError):
        raise ValueError("unsupported native API key transport") from None


@dataclass(frozen=True)
class APIKeyVendorCatalogEntry:
    id: str
    label: str
    official_base_url: str
    protocol: str
    # The models.dev provider whose entries describe what this vendor's
    # official endpoint accepts; ``None`` when no mapping has been verified.
    models_dev_provider: str | None = None
    # Built-ins are catalog rows, not addable API-key vendors.
    built_in: bool = False
    # Bundled wire metadata, never supplied by a caller or a remote catalog.
    search: dict | None = None


def _catalog_path() -> Path:
    return Path(__file__).resolve().parents[1] / "data" / "api_key_vendors.json"


def _validate_search_catalog(item: object, *, protocol: str, built_in: bool = False) -> dict[str, Any] | None:
    if item is None:
        return None
    if not isinstance(item, dict):
        raise ValueError("api-key vendor search catalog is invalid")
    required = {"service_id", "endpoint", "auth", "request", "result", "limits", "price", "free_check", "service_refused_statuses", "outcomes", "billing", "tool_only"}
    if protocol != "search":
        required.add("auto_enroll")
    if set(item) != required:
        raise ValueError("api-key vendor search catalog is invalid")
    endpoint = normalize_model_hub_base_url(item.get("endpoint"))
    if endpoint is None or urlsplit(endpoint).scheme != "https":
        raise ValueError("api-key vendor search catalog endpoint is invalid")
    if not isinstance(item.get("service_id"), str) or not item["service_id"].strip():
        raise ValueError("api-key vendor search catalog service id is invalid")
    if item.get("auth") not in {"bearer", "x-api-key", "none"} or (item.get("auth") == "none" and not built_in) or not isinstance(item.get("request"), dict) or not isinstance(item.get("result"), dict) or not isinstance(item.get("limits"), dict):
        raise ValueError("api-key vendor search catalog mapping is invalid")
    if "reported_cost" in item["result"]:
        reported_cost = item["result"]["reported_cost"]
        if (
            not isinstance(reported_cost, dict)
            or set(reported_cost) != {"path", "estimate"}
            or not isinstance(reported_cost.get("path"), str)
            or not reported_cost["path"]
            or not isinstance(reported_cost.get("estimate"), bool)
        ):
            raise ValueError("api-key vendor search catalog reported cost is invalid")
    results_max = item["limits"].get("results_max")
    # Keep a fixed per-request results ceiling across catalog updates.
    if isinstance(results_max, bool) or not isinstance(results_max, int) or not 1 <= results_max <= 100:
        raise ValueError("api-key vendor search catalog results maximum is invalid")
    price = item.get("price")
    if not isinstance(price, dict) or set(price) != {"unit", "usd_per_1k", "extra", "as_of", "url"} or price.get("unit") != "search":
        raise ValueError("api-key vendor search catalog price is invalid")
    if not isinstance(price.get("usd_per_1k"), (int, float)) or isinstance(price.get("usd_per_1k"), bool) or price["usd_per_1k"] < 0:
        raise ValueError("api-key vendor search catalog price is invalid")
    if price.get("extra") != [] or not isinstance(price.get("as_of"), str) or not isinstance(price.get("url"), str):
        raise ValueError("api-key vendor search catalog price is invalid")
    if not isinstance(item.get("tool_only"), bool) or item["tool_only"] != (protocol == "search"):
        raise ValueError("api-key vendor search catalog protocol is invalid")
    if protocol != "search" and not isinstance(item.get("auto_enroll"), bool):
        raise ValueError("api-key vendor search catalog auto-enroll flag is invalid")
    if not isinstance(item.get("service_refused_statuses"), list) or any(
        isinstance(status, bool) or not isinstance(status, int) or status < 400 or status >= 500
        for status in item["service_refused_statuses"]
    ) or len(set(item["service_refused_statuses"])) != len(item["service_refused_statuses"]):
        raise ValueError("api-key vendor search catalog refusal statuses are invalid")
    outcomes, billing = item.get("outcomes"), item.get("billing")
    if not isinstance(outcomes, dict) or set(outcomes) - {"credential", "balance", "limit", "tag_overrides"} or any(
        not isinstance(statuses, list) or any(type(status) is not int or not 400 <= status < 500 for status in statuses)
        or len(set(statuses)) != len(statuses) for statuses in (outcomes.get(key) for key in ("credential", "balance", "limit"))
    ):
        raise ValueError("api-key vendor search outcome statuses are invalid")
    overrides = outcomes.get("tag_overrides", [])
    if not isinstance(overrides, list) or any(
        not isinstance(rule, dict) or set(rule) != {"status", "tag", "code"}
        or type(rule["status"]) is not int or not 400 <= rule["status"] < 500
        or not isinstance(rule["tag"], str) or not rule["tag"]
        or rule["code"] not in {"service_limit", "service_refused"} for rule in overrides
    ):
        raise ValueError("api-key vendor search outcome tag overrides are invalid")
    if (
        not isinstance(billing, dict) or set(billing) != {"nonempty_only", "unbilled_errors"}
        or not isinstance(billing["nonempty_only"], bool)
        or not isinstance(billing["unbilled_errors"], list)
        or any(error != "timeout" for error in billing["unbilled_errors"])
        or len(set(billing["unbilled_errors"])) != len(billing["unbilled_errors"])
    ):
        raise ValueError("api-key vendor search billing rule is invalid")
    free_check = item.get("free_check")
    if free_check is not None:
        if not isinstance(free_check, dict):
            raise ValueError("api-key vendor search catalog free check is invalid")
        limit_rule = free_check.get("limit")
        if limit_rule is not None:
            pairs = limit_rule.get("pairs") if isinstance(limit_rule, dict) else None
            if not isinstance(pairs, list) or any(
                not isinstance(pair, dict)
                or not isinstance(pair.get("usage"), str)
                or not isinstance(pair.get("limit"), str)
                for pair in pairs
            ):
                raise ValueError("api-key vendor search catalog free check is invalid")
    return dict(item)

@lru_cache(maxsize=1)
def api_key_vendor_catalog() -> tuple[APIKeyVendorCatalogEntry, ...]:
    payload = json.loads(_catalog_path().read_text(encoding="utf-8"))
    if not isinstance(payload, list):
        raise ValueError("api-key vendor catalog is invalid")

    entries: list[APIKeyVendorCatalogEntry] = []
    seen_ids: set[str] = set()
    seen_service_ids: set[str] = set()
    for item in payload:
        if not isinstance(item, dict):
            raise ValueError("api-key vendor catalog is invalid")
        vendor_id = normalize_model_hub_vendor_id(item.get("id"))
        label = item.get("label")
        protocol = item.get("protocol")
        official_base_url = normalize_model_hub_base_url(item.get("official_base_url"))
        models_dev_provider = item.get("models_dev_provider")
        if (
            vendor_id == "custom"
            or vendor_id in seen_ids
            or not isinstance(label, str)
            or not label.strip()
            or not isinstance(protocol, str)
            or protocol not in _SUPPORTED_PROTOCOLS
            or official_base_url is None
            or (
                models_dev_provider is not None
                and (not isinstance(models_dev_provider, str) or not models_dev_provider.strip())
            )
        ):
            raise ValueError("api-key vendor catalog is invalid")
        built_in = item.get("built_in", False)
        if not isinstance(built_in, bool) or (built_in and protocol != "search"):
            raise ValueError("api-key vendor catalog is invalid")
        search = _validate_search_catalog(item.get("search"), protocol=protocol, built_in=built_in)
        if search is not None and search["service_id"] in seen_service_ids:
            raise ValueError("api-key vendor catalog is invalid")
        entries.append(
            APIKeyVendorCatalogEntry(
                id=vendor_id,
                label=label.strip(),
                official_base_url=official_base_url,
                protocol=protocol,
                models_dev_provider=models_dev_provider.strip() if models_dev_provider else None,
                search=search,
                built_in=built_in,
            )
        )
        seen_ids.add(vendor_id)
        if search is not None:
            seen_service_ids.add(search["service_id"])
    return tuple(entries)


@lru_cache(maxsize=1)
def _catalog_by_id() -> dict[str, APIKeyVendorCatalogEntry]:
    return {entry.id: entry for entry in api_key_vendor_catalog()}


def api_key_vendor_entry(vendor: str) -> APIKeyVendorCatalogEntry | None:
    return _catalog_by_id().get(vendor.strip().lower())


def search_service(vendor: str, protocol: str, base_url: str | None = None) -> dict | None:
    """The catalog search API this Source can use, never a relay or an OAuth grant.

    Callers also require kind=api_key. This pure predicate deliberately has no
    health or enabled checks: those belong to admission, not catalog identity.
    """
    entry = api_key_vendor_entry(vendor)
    if entry is None or entry.search is None:
        return None
    if entry.search["tool_only"]:
        return entry.search if protocol == "search" and base_url is None else None
    if protocol == "search" or (base_url is not None and not is_official_api_key_endpoint(vendor, base_url)):
        return None
    return entry.search


def pinned_api_key_protocol(vendor: str) -> str | None:
    entry = api_key_vendor_entry(vendor)
    return entry.protocol if entry is not None else None


def catalog_api_key_vendor_label(vendor: str) -> str | None:
    entry = api_key_vendor_entry(vendor)
    return entry.label if entry is not None else None


def official_api_key_base_url(vendor: str) -> str | None:
    normalized_vendor = vendor.strip().lower()
    entry = _catalog_by_id().get(normalized_vendor)
    if entry is not None:
        return entry.official_base_url
    return _LEGACY_OFFICIAL_BASE_URLS.get(normalized_vendor)


def openai_compatible_endpoint(base_url: str) -> str:
    """The API root the engine calls for an ``openai_chat`` Source's base URL.

    CLIProxyAPI appends ``/chat/completions``; a Source origin without a path
    uses the standard ``/v1`` root that discovery and probes use.
    """
    endpoint = normalize_model_hub_base_url(base_url)
    assert endpoint is not None
    if not urlsplit(endpoint).path.rstrip("/"):
        endpoint = normalize_model_hub_base_url(endpoint, append_path="/v1")
        assert endpoint is not None
    return endpoint


def _endpoint_identity(base_url: str, protocol: str | None = None) -> tuple[str, str, int | None, str, str] | None:
    try:
        # The root a Google Source's engine entry calls, and the API root every other protocol's does.
        root = google_api_base_url(base_url) if protocol == "google" else openai_compatible_endpoint(base_url)
    except ValueError:
        return None
    parts = urlsplit(root)
    try:
        port = parts.port or {"http": 80, "https": 443}.get(parts.scheme)
    except ValueError:
        # A stored URL may carry a port no connection can use; it names no
        # official endpoint.
        return None
    return parts.scheme, parts.hostname or "", port, parts.path, parts.query


def official_models_dev_provider(vendor: str, base_url: str | None) -> str | None:
    """The models.dev provider describing a Source's upstream, or ``None``.

    Only a Source on its vendor's official endpoint is described by that
    vendor's models.dev entries: a custom URL may front any deployment. The
    endpoint is the one the engine calls, so spellings of one URL that differ
    only by host case, a default port, or the implied ``/v1`` root agree.
    """
    entry = api_key_vendor_entry(vendor)
    if entry is None or entry.models_dev_provider is None:
        return None
    if base_url is not None and (
        _endpoint_identity(base_url, entry.protocol) is None
        or _endpoint_identity(base_url, entry.protocol) != _endpoint_identity(entry.official_base_url, entry.protocol)
    ):
        return None
    return entry.models_dev_provider


def is_official_api_key_endpoint(vendor: str, base_url: str) -> bool:
    """Whether a base URL is its vendor's official endpoint, by the engine's endpoint identity.

    Spellings that differ only by host case, a default port, or the implied ``/v1`` root are the same endpoint.
    """

    official = official_api_key_base_url(vendor)
    if official is None:
        return False
    protocol = pinned_api_key_protocol(vendor)
    identity = _endpoint_identity(base_url, protocol)
    return identity is not None and identity == _endpoint_identity(official, protocol)


def official_api_key_base_urls() -> dict[str, str]:
    return {
        **{entry.id: entry.official_base_url for entry in api_key_vendor_catalog()},
        **_LEGACY_OFFICIAL_BASE_URLS,
    }