routeplane 0.1.0__py3-none-any.whl

routeplane/__init__.py

@@ -0,0 +1,27 @@
+"""Official Python SDK for the Routeplane AI Gateway.
+
+Three ways in, smallest to largest:
+
+1. Change nothing but ``base_url`` on the stock ``openai`` client.
+2. Splat :func:`headers` into ``extra_headers`` on any OpenAI-compatible client.
+3. Use :class:`Routeplane` / :class:`AsyncRouteplane` for auth + defaults +
+   typed response metadata (:class:`RouteplaneMeta`), the ``*_with_meta``
+   convenience, and the non-OpenAI resource namespaces.
+"""
+
+from ._streaming import AsyncRouteplaneStream, RouteplaneStream
+from ._version import __version__
+from .async_client import AsyncRouteplane
+from .client import Routeplane
+from .headers import headers
+from .meta import RouteplaneMeta
+
+__all__ = [
+    "Routeplane",
+    "AsyncRouteplane",
+    "RouteplaneStream",
+    "AsyncRouteplaneStream",
+    "headers",
+    "RouteplaneMeta",
+    "__version__",
+]

routeplane/_streaming.py

@@ -0,0 +1,87 @@
+"""Thin wrappers that pair an OpenAI stream with its gateway metadata.
+
+The OpenAI SDK's ``Stream`` exposes chunks but not the response headers, and the
+``x-routeplane-*`` headers arrive on the response *before* the first chunk. These
+wrappers capture that header snapshot as a :class:`RouteplaneMeta` while
+delegating iteration straight through to the underlying stream.
+"""
+
+from __future__ import annotations
+
+from typing import AsyncIterator, Generic, Iterator, Mapping, TypeVar
+
+from .meta import RouteplaneMeta
+
+__all__ = ["RouteplaneStream", "AsyncRouteplaneStream"]
+
+_T = TypeVar("_T")
+
+
+class RouteplaneStream(Generic[_T]):
+    """Iterable wrapper over a sync OpenAI ``Stream`` that also carries ``meta``.
+
+    Use it exactly like the underlying stream::
+
+        stream = client.stream_with_meta(model="gpt-4o", messages=[...])
+        print(stream.meta.provider)  # available before the first chunk
+        for chunk in stream:
+            ...
+    """
+
+    meta: RouteplaneMeta
+
+    def __init__(self, stream: Iterator[_T], headers: Mapping[str, str]) -> None:
+        self._stream = stream
+        self.meta = RouteplaneMeta.from_headers(headers)
+
+    def __iter__(self) -> Iterator[_T]:
+        return self._stream
+
+    def __next__(self) -> _T:
+        return next(self._stream)
+
+    def __enter__(self) -> "RouteplaneStream[_T]":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        close = getattr(self._stream, "close", None)
+        if callable(close):
+            close()
+
+
+class AsyncRouteplaneStream(Generic[_T]):
+    """Async twin of :class:`RouteplaneStream` for ``AsyncRouteplane``.
+
+    ::
+
+        stream = await client.stream_with_meta(model="gpt-4o", messages=[...])
+        print(stream.meta.provider)
+        async for chunk in stream:
+            ...
+    """
+
+    meta: RouteplaneMeta
+
+    def __init__(self, stream: AsyncIterator[_T], headers: Mapping[str, str]) -> None:
+        self._stream = stream
+        self.meta = RouteplaneMeta.from_headers(headers)
+
+    def __aiter__(self) -> AsyncIterator[_T]:
+        return self._stream
+
+    async def __anext__(self) -> _T:
+        return await self._stream.__anext__()
+
+    async def __aenter__(self) -> "AsyncRouteplaneStream[_T]":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        close = getattr(self._stream, "close", None)
+        if callable(close):
+            await close()

routeplane/_types.py

@@ -0,0 +1,36 @@
+"""Typed models for Routeplane's non-OpenAI endpoints.
+
+:class:`Status` (the model behind ``GET /status``) is the one endpoint that
+parses into a dataclass. The other resource namespaces return permissive
+``dict`` / ``list[dict]`` payloads straight from the gateway, so a gateway that
+grows a field never breaks an older SDK.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+__all__ = ["Status"]
+
+
+@dataclass(frozen=True)
+class Status:
+    """Response of ``GET /status`` — gateway liveness/build metadata.
+
+    Fields mirror the gateway's status payload but stay permissive: unknown keys
+    are preserved in :attr:`raw` so a gateway that grows a field does not break
+    older SDKs.
+    """
+
+    status: Optional[str] = None
+    version: Optional[str] = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Status":
+        return cls(
+            status=data.get("status"),
+            version=data.get("version"),
+            raw=dict(data),
+        )

routeplane/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

routeplane/async_client.py

@@ -0,0 +1,173 @@
+"""The :class:`AsyncRouteplane` client — a thin subclass of ``openai.AsyncOpenAI``.
+
+Async twin of :class:`routeplane.Routeplane`; same header injection, the same
+resource namespaces, and async-native ``create_with_meta`` / ``stream_with_meta``.
+
+The REST resource namespaces (``prompts``, ``finops``, …) are the same synchronous
+``httpx``-backed objects the sync client exposes — they cover low-frequency
+admin/analytics endpoints, so they block briefly rather than dragging a second
+async HTTP stack into the SDK. The chat/embeddings hot path stays fully async via
+the inherited ``openai`` client.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, Tuple, cast
+
+import httpx
+import openai
+from openai.types.chat import ChatCompletion, ChatCompletionChunk
+
+from ._streaming import AsyncRouteplaneStream
+from .client import DEFAULT_BASE_URL
+from .headers import headers as build_headers
+from .meta import RouteplaneMeta
+from .resources import (
+    AnalyticsResource,
+    CacheResource,
+    FeedbackResource,
+    FinopsResource,
+    LogsResource,
+    McpResource,
+    ModelsResource,
+    PromptsResource,
+    ProvidersResource,
+    ResidencyResource,
+    StatusResource,
+)
+
+__all__ = ["AsyncRouteplane"]
+
+
+class AsyncRouteplane(openai.AsyncOpenAI):
+    """Drop-in ``openai.AsyncOpenAI`` pointed at the Routeplane gateway.
+
+    See :class:`routeplane.Routeplane` for the auth/header semantics — this is
+    the ``async``/``await`` variant.
+    """
+
+    _rp_defaults: dict[str, Any]
+    _rp_http: httpx.Client
+
+    prompts: PromptsResource
+    logs: LogsResource
+    finops: FinopsResource
+    cache: CacheResource
+    feedback: FeedbackResource
+    residency: ResidencyResource
+    mcp_security: McpResource
+    rp_models: ModelsResource
+    rp_providers: ProvidersResource
+    analytics: AnalyticsResource
+    status: StatusResource
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        provider: Optional[str] = None,
+        strategy: Optional[str] = None,
+        residency: Optional[str] = None,
+        use_case: Optional[str] = None,
+        timeout_ms: Optional[int] = None,
+        **kwargs: Any,
+    ) -> None:
+        self._rp_defaults = {
+            "provider": provider,
+            "strategy": strategy,
+            "residency": residency,
+            "use_case": use_case,
+            "timeout_ms": timeout_ms,
+        }
+
+        default_hdrs = build_headers(
+            provider=provider,
+            strategy=strategy,  # type: ignore[arg-type]
+            residency=residency,
+            use_case=use_case,
+            timeout_ms=timeout_ms,
+        )
+
+        caller_headers = dict(kwargs.pop("default_headers", None) or {})
+        merged = {
+            "x-routeplane-api-key": api_key,
+            **default_hdrs,
+            **caller_headers,
+        }
+
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            default_headers=merged,
+            **kwargs,
+        )
+
+        self._rp_http = httpx.Client()
+        self._install_resources(api_key=api_key, base_url=base_url, routing=default_hdrs)
+
+    def _install_resources(
+        self, *, api_key: str, base_url: str, routing: Mapping[str, str]
+    ) -> None:
+        common: dict[str, Any] = {
+            "api_key": api_key,
+            "base_url": base_url,
+            "http_client": self._rp_http,
+            "default_headers": routing,
+        }
+        self.prompts = PromptsResource(**common)
+        self.logs = LogsResource(**common)
+        self.finops = FinopsResource(**common)
+        self.cache = CacheResource(**common)
+        self.feedback = FeedbackResource(**common)
+        self.residency = ResidencyResource(**common)
+        self.mcp_security = McpResource(**common)
+        self.rp_models = ModelsResource(**common)
+        self.rp_providers = ProvidersResource(**common)
+        self.analytics = AnalyticsResource(**common)
+        self.status = StatusResource(**common)
+
+    @staticmethod
+    def meta_from_headers(headers: Mapping[str, str]) -> RouteplaneMeta:
+        """Parse ``x-routeplane-*`` response headers into a :class:`RouteplaneMeta`.
+
+        Pair with the OpenAI SDK's async ``with_raw_response``::
+
+            raw = await client.chat.completions.with_raw_response.create(...)
+            meta = client.meta_from_headers(raw.headers)
+            completion = raw.parse()
+        """
+        return RouteplaneMeta.from_headers(headers)
+
+    async def create_with_meta(self, **kwargs: Any) -> Tuple[ChatCompletion, RouteplaneMeta]:
+        """Chat completion that also returns the gateway :class:`RouteplaneMeta`.
+
+        ::
+
+            completion, meta = await client.create_with_meta(model="gpt-4o", messages=[...])
+        """
+        raw = await self.chat.completions.with_raw_response.create(**kwargs)
+        completion = cast(ChatCompletion, raw.parse())
+        return completion, RouteplaneMeta.from_headers(raw.headers)
+
+    async def stream_with_meta(self, **kwargs: Any) -> AsyncRouteplaneStream[ChatCompletionChunk]:
+        """Streaming chat completion that also exposes ``meta`` on the stream.
+
+        ::
+
+            stream = await client.stream_with_meta(model="gpt-4o", messages=[...])
+            print(stream.meta.provider)
+            async for chunk in stream:
+                ...
+        """
+        kwargs["stream"] = True
+        raw = await self.chat.completions.with_raw_response.create(**kwargs)
+        stream: Any = raw.parse()
+        return AsyncRouteplaneStream(stream, raw.headers)
+
+    async def close(self) -> None:
+        """Close the OpenAI transport *and* the shared Routeplane httpx client."""
+        try:
+            self._rp_http.close()
+        finally:
+            await super().close()

routeplane/client.py

@@ -0,0 +1,189 @@
+"""The :class:`Routeplane` client — a thin subclass of ``openai.OpenAI``.
+
+Everything the OpenAI SDK can do works unchanged (``client.chat.completions``,
+``client.embeddings``, streaming, retries). The subclass adds three things:
+
+1. gateway auth + default ``x-routeplane-*`` routing headers, so callers don't
+   repeat them on every request;
+2. ``create_with_meta`` / ``stream_with_meta`` convenience that returns the
+   parsed completion *and* the :class:`RouteplaneMeta` gateway metadata;
+3. the non-OpenAI resource namespaces (prompts, logs, finops, cache, feedback,
+   residency, mcp, models, providers, analytics, status).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, Tuple, cast
+
+import httpx
+import openai
+from openai.types.chat import ChatCompletion, ChatCompletionChunk
+
+from ._streaming import RouteplaneStream
+from .headers import headers as build_headers
+from .meta import RouteplaneMeta
+from .resources import (
+    AnalyticsResource,
+    CacheResource,
+    FeedbackResource,
+    FinopsResource,
+    LogsResource,
+    McpResource,
+    ModelsResource,
+    PromptsResource,
+    ProvidersResource,
+    ResidencyResource,
+    StatusResource,
+)
+
+__all__ = ["Routeplane"]
+
+DEFAULT_BASE_URL = "https://api.routeplane.ai/v1"
+
+
+class Routeplane(openai.OpenAI):
+    """Drop-in ``openai.OpenAI`` pointed at the Routeplane gateway.
+
+    Auth is sent as the native ``x-routeplane-api-key`` header. The OpenAI SDK
+    additionally sets ``Authorization: Bearer <api_key>`` from ``api_key``; the
+    gateway accepts both and the native header takes precedence, so passing the
+    same value to both is intentional and harmless.
+
+    Per-request routing headers still win over the client defaults set here — use
+    :func:`routeplane.headers` with ``extra_headers=`` on any individual call.
+    """
+
+    _rp_defaults: dict[str, Any]
+    _rp_http: httpx.Client
+
+    # Routeplane-only resource namespaces (the OpenAI-shaped surfaces stay on the
+    # inherited attributes; these carry the ``rp_``/``_security`` prefixes only
+    # where the plain name is already taken by the OpenAI SDK).
+    prompts: PromptsResource
+    logs: LogsResource
+    finops: FinopsResource
+    cache: CacheResource
+    feedback: FeedbackResource
+    residency: ResidencyResource
+    mcp_security: McpResource
+    rp_models: ModelsResource
+    rp_providers: ProvidersResource
+    analytics: AnalyticsResource
+    status: StatusResource
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        provider: Optional[str] = None,
+        strategy: Optional[str] = None,
+        residency: Optional[str] = None,
+        use_case: Optional[str] = None,
+        timeout_ms: Optional[int] = None,
+        **kwargs: Any,
+    ) -> None:
+        self._rp_defaults = {
+            "provider": provider,
+            "strategy": strategy,
+            "residency": residency,
+            "use_case": use_case,
+            "timeout_ms": timeout_ms,
+        }
+
+        default_hdrs = build_headers(
+            provider=provider,
+            strategy=strategy,  # type: ignore[arg-type]
+            residency=residency,
+            use_case=use_case,
+            timeout_ms=timeout_ms,
+        )
+
+        # Merge, never clobber, any default_headers the caller passed through.
+        caller_headers = dict(kwargs.pop("default_headers", None) or {})
+        merged = {
+            "x-routeplane-api-key": api_key,
+            **default_hdrs,
+            **caller_headers,
+        }
+
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            default_headers=merged,
+            **kwargs,
+        )
+
+        # One shared httpx client for every REST-shaped namespace; the routing
+        # defaults ride along so prompt completions honour them too.
+        self._rp_http = httpx.Client()
+        self._install_resources(api_key=api_key, base_url=base_url, routing=default_hdrs)
+
+    def _install_resources(
+        self, *, api_key: str, base_url: str, routing: Mapping[str, str]
+    ) -> None:
+        common: dict[str, Any] = {
+            "api_key": api_key,
+            "base_url": base_url,
+            "http_client": self._rp_http,
+            "default_headers": routing,
+        }
+        self.prompts = PromptsResource(**common)
+        self.logs = LogsResource(**common)
+        self.finops = FinopsResource(**common)
+        self.cache = CacheResource(**common)
+        self.feedback = FeedbackResource(**common)
+        self.residency = ResidencyResource(**common)
+        self.mcp_security = McpResource(**common)
+        self.rp_models = ModelsResource(**common)
+        self.rp_providers = ProvidersResource(**common)
+        self.analytics = AnalyticsResource(**common)
+        self.status = StatusResource(**common)
+
+    @staticmethod
+    def meta_from_headers(headers: Mapping[str, str]) -> RouteplaneMeta:
+        """Parse ``x-routeplane-*`` response headers into a :class:`RouteplaneMeta`.
+
+        Pair with the OpenAI SDK's ``with_raw_response`` to inspect what the
+        gateway did::
+
+            raw = client.chat.completions.with_raw_response.create(...)
+            meta = client.meta_from_headers(raw.headers)
+            completion = raw.parse()
+        """
+        return RouteplaneMeta.from_headers(headers)
+
+    def create_with_meta(self, **kwargs: Any) -> Tuple[ChatCompletion, RouteplaneMeta]:
+        """Chat completion that also returns the gateway :class:`RouteplaneMeta`.
+
+        ::
+
+            completion, meta = client.create_with_meta(model="gpt-4o", messages=[...])
+            print(meta.provider, meta.cache)
+        """
+        raw = self.chat.completions.with_raw_response.create(**kwargs)
+        completion = cast(ChatCompletion, raw.parse())
+        return completion, RouteplaneMeta.from_headers(raw.headers)
+
+    def stream_with_meta(self, **kwargs: Any) -> RouteplaneStream[ChatCompletionChunk]:
+        """Streaming chat completion that also exposes ``meta`` on the stream.
+
+        ``meta`` is populated from the response headers, which arrive before the
+        first chunk, so it can be read immediately::
+
+            stream = client.stream_with_meta(model="gpt-4o", messages=[...])
+            print(stream.meta.provider)
+            for chunk in stream:
+                ...
+        """
+        kwargs["stream"] = True
+        raw = self.chat.completions.with_raw_response.create(**kwargs)
+        stream: Any = raw.parse()
+        return RouteplaneStream(stream, raw.headers)
+
+    def close(self) -> None:
+        """Close the OpenAI transport *and* the shared Routeplane httpx client."""
+        try:
+            self._rp_http.close()
+        finally:
+            super().close()

routeplane/headers.py

@@ -0,0 +1,131 @@
+"""Typed builder for the ``x-routeplane-*`` request headers.
+
+The gateway is configured entirely through request headers, so this builder is
+the single most reusable piece of the SDK: it works with *any* OpenAI-compatible
+client (stock ``openai``, LangChain, LlamaIndex, a raw ``httpx`` call) via that
+client's ``extra_headers`` / ``default_headers`` escape hatch.
+
+Only headers with non-``None`` values are emitted. Dict-valued options
+(``config``, ``metadata``) are JSON-serialized; integers are stringified.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Literal
+
+__all__ = ["headers", "HEADER_NAMES"]
+
+# Maps each keyword argument to its wire header name. Keeping this as data (not
+# branches) means the omit-None / serialize logic below stays uniform.
+HEADER_NAMES: dict[str, str] = {
+    "provider": "x-routeplane-provider",
+    "residency": "x-routeplane-residency",
+    "strategy": "x-routeplane-strategy",
+    "config": "x-routeplane-config",
+    "timeout_ms": "x-routeplane-timeout-ms",
+    "use_case": "x-routeplane-use-case",
+    "log_level": "x-routeplane-log-level",
+    "conversation_id": "x-routeplane-conversation-id",
+    "currency": "x-routeplane-currency",
+    "metadata": "x-routeplane-metadata",
+    "pii_mode": "x-routeplane-pii-mode",
+    "output_mask": "x-routeplane-output-mask",
+    "cache_control": "x-routeplane-cache-control",
+    "idempotency_key": "x-routeplane-idempotency-key",
+    "cohort": "x-routeplane-cohort",
+    "batch": "x-routeplane-batch",
+    "trace_id": "x-routeplane-trace-id",
+}
+
+
+def headers(
+    *,
+    provider: str | None = None,
+    residency: str | None = None,
+    strategy: Literal["priority", "weighted", "cost", "latency"] | None = None,
+    config: dict[str, Any] | None = None,
+    timeout_ms: int | None = None,
+    use_case: str | None = None,
+    log_level: Literal["metadata", "none", "full"] | None = None,
+    conversation_id: str | None = None,
+    currency: str | None = None,
+    metadata: dict[str, str] | None = None,
+    pii_mode: Literal["tokenize"] | None = None,
+    output_mask: str | None = None,
+    cache_control: Literal["no-store"] | None = None,
+    idempotency_key: str | None = None,
+    cohort: str | None = None,
+    batch: str | None = None,
+    trace_id: str | None = None,
+) -> dict[str, str]:
+    """Build a dict of ``x-routeplane-*`` headers for any OpenAI-compatible client.
+
+    Only includes headers whose value is non-``None``. Dict values (``config``,
+    ``metadata``) are JSON-serialized; ``timeout_ms`` is stringified.
+
+    Works with ``extra_headers=headers(...)`` on the stock OpenAI SDK,
+    ``default_headers=headers(...)`` on LangChain, and any client that forwards
+    extra headers to the underlying HTTP request.
+
+    Args:
+        provider: Provider or comma-separated fallback chain (e.g. ``"openai"``
+            or ``"openai,anthropic"``). Overridden by sovereign routing when the
+            request carries personal data and a residency region.
+        residency: Requested data-residency region (e.g. ``"IN"``). Only enforced
+            when the request also carries personal data.
+        strategy: Provider-ordering strategy.
+        config: Inline routing/policy config, JSON-serialized onto the wire.
+        timeout_ms: Per-request upstream timeout in milliseconds.
+        use_case: Free-form use-case label for analytics/FinOps attribution.
+        log_level: Per-request logging verbosity.
+        conversation_id: Groups requests into one logical conversation.
+        currency: Preferred currency for cost reporting (e.g. ``"INR"``).
+        metadata: Arbitrary key/value tags, JSON-serialized onto the wire.
+        pii_mode: PII handling mode.
+        output_mask: Output masking policy reference.
+        cache_control: Response-cache directive.
+        idempotency_key: Client-supplied idempotency key for safe retries.
+        cohort: Experiment/cohort label.
+        batch: Batch identifier.
+        trace_id: Client-supplied distributed-trace id (echoed back on the response).
+
+    Returns:
+        A ``dict[str, str]`` of header name to value, suitable to splat into any
+        client's extra/default headers.
+    """
+    values: dict[str, Any] = {
+        "provider": provider,
+        "residency": residency,
+        "strategy": strategy,
+        "config": config,
+        "timeout_ms": timeout_ms,
+        "use_case": use_case,
+        "log_level": log_level,
+        "conversation_id": conversation_id,
+        "currency": currency,
+        "metadata": metadata,
+        "pii_mode": pii_mode,
+        "output_mask": output_mask,
+        "cache_control": cache_control,
+        "idempotency_key": idempotency_key,
+        "cohort": cohort,
+        "batch": batch,
+        "trace_id": trace_id,
+    }
+
+    out: dict[str, str] = {}
+    for key, value in values.items():
+        if value is None:
+            continue
+        header_name = HEADER_NAMES[key]
+        if isinstance(value, dict):
+            out[header_name] = json.dumps(value, separators=(",", ":"))
+        elif isinstance(value, bool):
+            # Guard before int: bool is a subclass of int in Python.
+            out[header_name] = "true" if value else "false"
+        elif isinstance(value, int):
+            out[header_name] = str(value)
+        else:
+            out[header_name] = str(value)
+    return out