modelmeld 0.1.0__py3-none-any.whl

modelmeld/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 ModelMeld.
+
+"""Gateway core engine."""
+
+__version__ = "0.0.1"

modelmeld/__main__.py

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 ModelMeld.
+
+"""Run the gateway server: `python -m modelmeld`."""
+
+from __future__ import annotations
+
+
+def main() -> None:
+    import uvicorn
+
+    from modelmeld.config import GatewaySettings
+
+    settings = GatewaySettings()
+    uvicorn.run(
+        "modelmeld.api.server:app",
+        host=settings.host,
+        port=settings.port,
+        log_level=settings.log_level.lower(),
+    )
+
+
+if __name__ == "__main__":
+    main()

modelmeld/adapters/__init__.py

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 ModelMeld.
+
+"""Provider adapters. See base.py for the contract."""
+
+from __future__ import annotations
+
+from modelmeld.adapters.base import AdapterError, ProviderAdapter
+from modelmeld.adapters.stub import StubAdapter
+
+__all__ = ["AdapterError", "ProviderAdapter", "StubAdapter"]

modelmeld/adapters/anthropic_adapter.py

@@ -0,0 +1,165 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 ModelMeld.
+
+"""AnthropicAdapter — pass-through to Anthropic Messages API with schema translation."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator
+
+from modelmeld.adapters.base import AdapterError, ProviderAdapter
+from modelmeld.adapters.retry import (
+    RetryConfig,
+    retry_async,
+    wrap_as_adapter_error,
+)
+from modelmeld.api.schemas import (
+    ChatCompletion,
+    ChatCompletionChunk,
+    ChatCompletionRequest,
+)
+from modelmeld.api.schemas_anthropic import AnthropicMessagesRequest
+from modelmeld.translation import (
+    AnthropicStreamTranslator,
+    from_anthropic_response,
+    to_anthropic_params,
+)
+
+
+class AnthropicAdapter(ProviderAdapter):
+    name = "anthropic"
+    is_egress = True
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        retry_config: RetryConfig | None = None,
+        served_model: str | None = None,
+    ) -> None:
+        try:
+            from anthropic import AsyncAnthropic
+        except ImportError as e:
+            raise AdapterError(
+                "AnthropicAdapter requires the `anthropic` package. "
+                "Install with: pip install 'modelmeld[anthropic]'"
+            ) from e
+
+        key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+        if not key:
+            raise AdapterError(
+                "AnthropicAdapter requires an API key "
+                "(pass api_key= or set ANTHROPIC_API_KEY / MODELMELD_ANTHROPIC_API_KEY)."
+            )
+
+        # Disable the SDK's built-in retry; we own retry policy via retry_async.
+        # Stacking SDK retries on top of ours wastes time and rate limit.
+        kwargs: dict = {"api_key": key, "max_retries": 0}
+        if base_url:
+            kwargs["base_url"] = base_url
+        self._client = AsyncAnthropic(**kwargs)
+        self._retry_config = retry_config or RetryConfig()
+        # F-8: operator-pinned upstream model (overrides request.model).
+        self.served_model = served_model
+
+    async def chat(
+        self,
+        request: ChatCompletionRequest,
+        *,
+        native_request: object | None = None,
+        extra_headers: dict[str, str] | None = None,
+    ) -> ChatCompletion:
+        """Non-streaming chat.
+
+        `extra_headers` is the optional /v1/messages escape hatch for
+        forwarding caller-supplied Anthropic protocol headers
+        (`anthropic-beta`, `anthropic-version`, etc.) verbatim to the
+        upstream. Without this, beta features the customer activates
+        silently fall back at our gateway.
+        """
+        params = self._build_params(request, native_request)
+        if extra_headers:
+            params["extra_headers"] = dict(extra_headers)
+
+        async def _call():
+            return await self._client.messages.create(**params)
+
+        try:
+            sdk_message = await retry_async(
+                _call, self._retry_config, label="anthropic.chat",
+            )
+        except Exception as e:
+            raise wrap_as_adapter_error(e, "Anthropic chat call failed") from e
+        return from_anthropic_response(sdk_message.model_dump())
+
+    async def stream_chat(
+        self,
+        request: ChatCompletionRequest,
+        *,
+        native_request: object | None = None,
+        extra_headers: dict[str, str] | None = None,
+    ) -> AsyncIterator[ChatCompletionChunk]:
+        params = self._build_params(request, native_request)
+        params["stream"] = True
+        if extra_headers:
+            params["extra_headers"] = dict(extra_headers)
+
+        async def _open_stream():
+            return await self._client.messages.create(**params)
+
+        try:
+            stream = await retry_async(
+                _open_stream, self._retry_config, label="anthropic.stream_chat",
+            )
+        except Exception as e:
+            raise wrap_as_adapter_error(
+                e, "Anthropic stream_chat call failed",
+            ) from e
+
+        translator = AnthropicStreamTranslator()
+        async for event in stream:
+            chunk = translator.translate_event(event.model_dump())
+            if chunk is not None:
+                yield chunk
+
+    def _build_params(
+        self,
+        request: ChatCompletionRequest,
+        native_request: object | None,
+    ) -> dict:
+        """Construct the Anthropic SDK params from either the native
+        Anthropic request (preserving cache_control + tool schemas +
+        image content blocks intact) or, when not available, by
+        round-tripping through the OpenAI internal shape.
+
+        Native-passthrough is the path /v1/messages takes when routing
+        to an Anthropic upstream — without it, cache_control breakpoints
+        get silently dropped and customers pay ~5x more on what would
+        otherwise be cache hits (the failure mode musistudio/claude-code-router
+        ships today). /v1/chat/completions callers don't supply
+        native_request and use the translation path.
+        """
+        if isinstance(native_request, AnthropicMessagesRequest):
+            # Native passthrough — preserve the customer's exact request
+            # shape. Apply F-8 served_model substitution at this layer so
+            # operators can still pin the upstream model regardless of
+            # what the customer asked for.
+            params = native_request.model_dump(exclude_none=True)
+            if self.served_model is not None:
+                params["model"] = self.served_model
+            elif params.get("model") is None:
+                # Defense in depth — Anthropic SDK requires `model`.
+                params["model"] = request.model
+            return params
+        # Translation path (the existing /v1/chat/completions behavior).
+        request = self._apply_served_model(request)
+        return to_anthropic_params(request)
+
+    async def health(self) -> bool:
+        # Anthropic has no cheap public health endpoint; consider the client
+        # configured-and-imported as healthy. Real check happens on first call.
+        return True
+
+    async def close(self) -> None:
+        await self._client.close()

modelmeld/adapters/base.py

@@ -0,0 +1,116 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 ModelMeld.
+
+"""Provider adapter abstract base class.
+
+`ProviderAdapter` is the extension point through which the gateway forwards
+OpenAI-shaped requests to a concrete upstream (OpenAI cloud, Anthropic cloud,
+local vLLM, etc.). Implementations live in sibling modules.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+
+from modelmeld.api.schemas import (
+    ChatCompletion,
+    ChatCompletionChunk,
+    ChatCompletionRequest,
+)
+
+
+class AdapterError(Exception):
+    """Raised when an adapter fails to fulfill a request.
+
+    Network failures, upstream 5xx responses, schema-translation errors, and
+    misconfiguration (missing API key, etc.) all surface as this exception.
+
+    Subclasses `TransientAdapterError` and `PermanentAdapterError` carry the
+    retry-ability signal so the TieredRouter can decide whether to fail over
+    to the other tier or bubble the error up to the caller.
+    """
+
+
+class TransientAdapterError(AdapterError):
+    """Adapter failed in a way that may succeed on retry / failover.
+
+    Examples: HTTP 5xx, 429 rate limit, 529 overloaded, network blip,
+    timeout. Routers should attempt the other tier; callers should treat
+    repeated occurrences as a real outage.
+    """
+
+
+class PermanentAdapterError(AdapterError):
+    """Adapter failed in a way that retry won't fix.
+
+    Examples: HTTP 401/403 auth failure, HTTP 404 model-not-found,
+    schema-translation errors, misconfiguration. Routers should NOT fail
+    over — surface the error so the caller sees the real cause instead of
+    a misleading fallback response.
+    """
+
+
+class ProviderAdapter(ABC):
+    """Translate an OpenAI-shaped request to a concrete upstream provider."""
+
+    name: str
+    # True when this adapter sends traffic outside the customer's network.
+    # Used by the chat route to gate PII scrubbing.
+    is_egress: bool = False
+    # F-8: operator-configured model this adapter actually serves upstream.
+    # When set, the adapter substitutes `request.model` with this value on
+    # outbound calls — the client can send any model name (or none) and the
+    # gateway routes them based on the scout's tier decision while the
+    # adapter uses its configured upstream model.
+    # When None, the adapter passes the client's model name through unchanged
+    # (default for adapters that proxy to multi-model providers).
+    served_model: str | None = None
+
+    @abstractmethod
+    async def chat(self, request: ChatCompletionRequest) -> ChatCompletion:
+        """Non-streaming chat completion."""
+
+    @abstractmethod
+    def stream_chat(
+        self, request: ChatCompletionRequest
+    ) -> AsyncIterator[ChatCompletionChunk]:
+        """Streaming chat completion. Implementations are async generators."""
+
+    @abstractmethod
+    async def health(self) -> bool:
+        """Cheap upstream reachability check. Returns False on failure."""
+
+    def serves_model(self, model_id: str) -> bool:  # noqa: ARG002 — base default
+        """Whether this adapter can serve the given model id (F-8).
+
+        Default returns True for both pinned and pass-through configurations:
+        - `served_model=None` → pass-through; we don't know what upstream
+          supports, so we assume failover is safe.
+        - `served_model="X"`  → substitution; `_apply_served_model()` will
+          rewrite `request.model` to X on the outbound call, so the
+          adapter will serve any request regardless of the client's
+          model id. Setting `served_model` is opting into substitution.
+
+        TieredRouter consults this before failover. Subclasses can
+        override for stricter behavior (e.g. compliance-mode adapter
+        that rejects non-matching model ids outright).
+        """
+        return True
+
+    def _apply_served_model(
+        self, request: ChatCompletionRequest,
+    ) -> ChatCompletionRequest:
+        """Return a request with `model` substituted to `served_model` if set.
+
+        Returns the original request when `served_model` is None — no copy
+        on the hot path for the pass-through case. Adapters call this at
+        the top of `chat()` / `stream_chat()` before delegating upstream.
+        """
+        if self.served_model is None or request.model == self.served_model:
+            return request
+        # Pydantic model_copy is shallow + cheap; preserves all other fields.
+        return request.model_copy(update={"model": self.served_model})
+
+    async def close(self) -> None:
+        """Release any held resources. Default no-op; override if needed."""

modelmeld/adapters/openai_adapter.py

@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 ModelMeld.
+
+"""OpenAIAdapter — pass-through to OpenAI's cloud API via the official SDK.
+
+Named `openai_adapter` (not `openai`) to avoid shadowing the upstream package
+when read by humans.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator
+from typing import Any
+
+import httpx
+
+from modelmeld.adapters.base import AdapterError, ProviderAdapter
+from modelmeld.adapters.retry import (
+    RetryConfig,
+    retry_async,
+    wrap_as_adapter_error,
+)
+from modelmeld.api.schemas import (
+    ChatCompletion,
+    ChatCompletionChunk,
+    ChatCompletionRequest,
+)
+
+
+class OpenAIAdapter(ProviderAdapter):
+    name = "openai"
+    is_egress = True
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        http_client: httpx.AsyncClient | None = None,
+        retry_config: RetryConfig | None = None,
+        served_model: str | None = None,
+    ) -> None:
+        try:
+            from openai import AsyncOpenAI
+        except ImportError as e:
+            raise AdapterError(
+                "OpenAIAdapter requires the `openai` package. "
+                "Install with: pip install 'modelmeld[openai]'"
+            ) from e
+
+        key = api_key or os.environ.get("OPENAI_API_KEY")
+        if not key:
+            raise AdapterError(
+                "OpenAIAdapter requires an API key "
+                "(pass api_key= or set OPENAI_API_KEY / MODELMELD_OPENAI_API_KEY)."
+            )
+        # Disable the SDK's built-in retry; retry policy lives in retry_async.
+        self._client = AsyncOpenAI(
+            api_key=key,
+            base_url=base_url,
+            http_client=http_client,
+            max_retries=0,
+        )
+        self._retry_config = retry_config or RetryConfig()
+        # F-8: operator-pinned upstream model (overrides request.model).
+        self.served_model = served_model
+
+    def _to_params(
+        self, request: ChatCompletionRequest, *, stream: bool
+    ) -> dict[str, Any]:
+        # exclude_none keeps optional fields off the wire so we don't override the
+        # upstream's defaults; we set `stream` explicitly per call.
+        excluded: set[str] = {"stream"}
+        if not stream:
+            excluded.add("stream_options")
+        params = request.model_dump(exclude_none=True, exclude=excluded)
+        params["stream"] = stream
+        return params
+
+    async def chat(self, request: ChatCompletionRequest) -> ChatCompletion:
+        request = self._apply_served_model(request)
+
+        async def _call():
+            return await self._client.chat.completions.create(
+                **self._to_params(request, stream=False)
+            )
+
+        try:
+            sdk_response = await retry_async(
+                _call, self._retry_config, label="openai.chat",
+            )
+        except Exception as e:
+            raise wrap_as_adapter_error(e, "OpenAI chat call failed") from e
+        return ChatCompletion.model_validate(sdk_response.model_dump())
+
+    async def stream_chat(
+        self, request: ChatCompletionRequest
+    ) -> AsyncIterator[ChatCompletionChunk]:
+        request = self._apply_served_model(request)
+
+        async def _open_stream():
+            return await self._client.chat.completions.create(
+                **self._to_params(request, stream=True)
+            )
+
+        try:
+            stream = await retry_async(
+                _open_stream, self._retry_config, label="openai.stream_chat",
+            )
+        except Exception as e:
+            raise wrap_as_adapter_error(
+                e, "OpenAI stream_chat call failed",
+            ) from e
+        async for chunk in stream:
+            yield ChatCompletionChunk.model_validate(chunk.model_dump())
+
+    async def health(self) -> bool:
+        try:
+            await self._client.models.list()
+            return True
+        except Exception:
+            return False
+
+    async def close(self) -> None:
+        await self._client.close()

modelmeld/adapters/retry.py

@@ -0,0 +1,181 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 ModelMeld.
+
+"""Retry-with-backoff utility for adapter calls (F-5).
+
+Wraps an async adapter call with exponential backoff retry on transient
+errors. Permanent errors (auth failure, config mismatch, schema errors)
+raise immediately - retrying them just wastes time and exhausts the
+provider's rate limit.
+
+Used by `AnthropicAdapter` and `OpenAIAdapter` to absorb provider
+throttling and 5xx blips before they reach the `TieredRouter`. With this
+in place, the router's failover logic only triggers on outages that
+genuinely persist across retries.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import random
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import TypeVar
+
+from modelmeld.adapters.base import (
+    AdapterError,
+    PermanentAdapterError,
+    TransientAdapterError,
+)
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+# HTTP status codes that justify a retry. Anything else is treated as
+# permanent - retrying a 401 won't make the credentials valid.
+TRANSIENT_STATUS_CODES: frozenset[int] = frozenset({
+    408,  # Request Timeout
+    409,  # Conflict (some APIs use for "operation in progress")
+    425,  # Too Early
+    429,  # Too Many Requests
+    500, 502, 503, 504,  # Server-side failures
+    529,  # Anthropic-specific Overloaded
+})
+
+# Class-name fragments that indicate transience when status_code isn't
+# available on the exception (some SDKs raise network errors that wrap
+# the underlying httpx/aiohttp exception).
+TRANSIENT_CLASS_HINTS: tuple[str, ...] = (
+    "ratelimit",
+    "overloaded",
+    "timeout",
+    "connection",
+    "apiconnection",
+    "internalservererror",
+    "serviceunavailable",
+)
+
+
+@dataclass(frozen=True)
+class RetryConfig:
+    """Retry policy. Defaults aim for ~7 seconds of total backoff over 3 tries.
+
+    max_attempts=3, base_delay=1s, jitter=20% → waits ~1s, ~2s between
+    attempts, with up to 20% randomization to avoid thundering herd.
+    """
+
+    max_attempts: int = 3
+    base_delay_sec: float = 1.0
+    max_delay_sec: float = 30.0
+    jitter: float = 0.2          # ±20% randomization of the computed delay
+
+
+def is_transient_error(exc: BaseException) -> bool:
+    """Classify whether an exception should trigger retry.
+
+    Inspects, in order:
+      1. Network-level exception types (asyncio.TimeoutError, ConnectionError)
+      2. HTTP status code on the exception (.status_code attribute)
+      3. Class-name fragments (fallback for SDKs without status_code)
+    """
+    if isinstance(exc, (asyncio.TimeoutError, ConnectionError)):
+        return True
+
+    status = getattr(exc, "status_code", None)
+    if isinstance(status, int):
+        return status in TRANSIENT_STATUS_CODES
+
+    cls_name = type(exc).__name__.lower()
+    return any(hint in cls_name for hint in TRANSIENT_CLASS_HINTS)
+
+
+def _compute_backoff(
+    attempt: int, config: RetryConfig, rng: random.Random | None = None,
+) -> float:
+    """Exponential backoff with optional ±jitter."""
+    raw = config.base_delay_sec * (2 ** (attempt - 1))
+    capped = min(raw, config.max_delay_sec)
+    if config.jitter > 0:
+        r = (rng or random).uniform(-config.jitter, config.jitter)
+        capped = capped * (1.0 + r)
+    return max(capped, 0.0)
+
+
+async def retry_async(
+    func: Callable[[], Awaitable[T]],
+    config: RetryConfig | None = None,
+    *,
+    label: str = "adapter call",
+    sleep: Callable[[float], Awaitable[None]] | None = None,
+    rng: random.Random | None = None,
+) -> T:
+    """Run an async callable with exponential-backoff retry.
+
+    Args:
+        func: zero-arg async callable to invoke. Wrap your call in a lambda
+              or nested coroutine def.
+        config: retry policy. Defaults to `RetryConfig()`.
+        label: human-readable label for log lines (e.g. "anthropic.chat").
+        sleep: injectable async sleep. Defaults to `asyncio.sleep`. Tests
+               override this to avoid real wall-clock waits.
+        rng: injectable RNG for jitter. Tests pass a seeded `random.Random`
+             for deterministic backoff timing.
+
+    Returns:
+        Whatever `func()` returns on success.
+
+    Raises:
+        The last exception, unmodified, after all attempts exhausted.
+        Non-transient errors raise immediately (no retry).
+    """
+    cfg = config or RetryConfig()
+    _sleep = sleep or asyncio.sleep
+    last_exc: BaseException | None = None
+
+    for attempt in range(1, cfg.max_attempts + 1):
+        try:
+            return await func()
+        except BaseException as e:
+            last_exc = e
+            if not is_transient_error(e):
+                # Permanent error - bail immediately, no retry.
+                raise
+            if attempt >= cfg.max_attempts:
+                # Out of retries - re-raise the last error.
+                raise
+            delay = _compute_backoff(attempt, cfg, rng)
+            logger.info(
+                "[%s] attempt %d/%d failed (%s: %s); retrying in %.2fs",
+                label, attempt, cfg.max_attempts,
+                type(e).__name__, str(e)[:120], delay,
+            )
+            await _sleep(delay)
+
+    # Unreachable in practice, but satisfies type checkers.
+    assert last_exc is not None
+    raise last_exc
+
+
+def wrap_as_adapter_error(exc: BaseException, prefix: str) -> AdapterError:
+    """Wrap an upstream exception in the appropriate AdapterError subclass.
+
+    `TieredRouter` (Sprint 2.6 / F-2) branches on the subclass:
+      - `TransientAdapterError` → safe to fail over to the other tier
+      - `PermanentAdapterError` → bubble up so the caller sees the real error
+
+    Detection mirrors `is_transient_error`. The string carries enough
+    detail to debug from logs without exposing the underlying exception
+    type leak.
+    """
+    msg = f"{prefix}: {exc}"
+    if is_transient_error(exc):
+        return TransientAdapterError(msg)
+    return PermanentAdapterError(msg)
+
+
+# Backward-compat alias for the underscore-prefixed call site in
+# anthropic_adapter / openai_adapter. Both spellings are part of the
+# adapter-internal contract; tests should prefer `wrap_as_adapter_error`.
+_wrap_as_adapter_error = wrap_as_adapter_error