arbr-client 0.1.0__py3-none-any.whl

arbr_client/__init__.py

@@ -0,0 +1,481 @@
+"""Official Python client for the AI control-plane gateway.
+
+Zero dependencies — Python >= 3.11, stdlib only (urllib for HTTP; async via
+``asyncio.to_thread``). The gateway owns provider keys, routing policy, logging
+and cost attribution; this client is a thin, robust pipe to it:
+
+    from arbr_client import create_client
+
+    arbr = create_client(base_url="http://localhost:4100", application="my-app")
+    res = arbr.chat("Summarise this ticket: ...")          # sync
+    res = await arbr.achat("Summarise this ticket: ...")   # async
+    # res.text, res.model, res.routing_decision ("explicit" | "rule" | "ai" | ...)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import random
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, AsyncIterator, Iterator, Optional
+
+__all__ = [
+    "create_client",
+    "Client",
+    "ChatResponse",
+    "Usage",
+    "GatewayError",
+    "as_langchain_model",
+]
+
+_RETRY_BASE_S = 0.25
+_RETRY_CAP_S = 4.0
+_STREAM_CHUNK_CHARS = 24
+
+
+# ── errors ────────────────────────────────────────────────────────────────────
+
+
+class GatewayError(Exception):
+    """Typed gateway error.
+
+    code: "invalid_input" | "bad_request" | "demo_mode" | "provider_error"
+        | "http_error" | "network" | "timeout"
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 0,
+        code: str = "http_error",
+        request_id: Optional[str] = None,
+        retryable: bool = False,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.retryable = retryable
+
+
+def _invalid(message: str) -> GatewayError:
+    return GatewayError(message, code="invalid_input", status=0, retryable=False)
+
+
+# ── response shapes ───────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class Usage:
+    input_tokens: int = 0
+    output_tokens: int = 0
+    total_tokens: int = 0
+
+
+@dataclass(frozen=True)
+class ChatResponse:
+    """The gateway's routed completion.
+
+    model is what actually served the call; model_requested is what you asked
+    for ("auto" when you deferred); routing_decision says why
+    ("explicit" | "passthrough" | "rule" | "auto" | "ai" | "cache" | "fallback");
+    classified_by says how the task type was determined ("provided" | "keyword" | "ai").
+    """
+
+    text: str
+    model: str
+    model_requested: str
+    provider: str
+    routing_decision: str
+    classified_by: str
+    cache_hit: bool
+    request_id: str
+    usage: Optional[Usage] = None
+    raw: dict = field(repr=False, default_factory=dict)
+
+    @staticmethod
+    def _from_dict(d: dict) -> "ChatResponse":
+        u = d.get("usage") or None
+        usage = (
+            Usage(
+                input_tokens=int(u.get("inputTokens") or 0),
+                output_tokens=int(u.get("outputTokens") or 0),
+                total_tokens=int(u.get("totalTokens") or 0),
+            )
+            if isinstance(u, dict)
+            else None
+        )
+        return ChatResponse(
+            text=d.get("text") or "",
+            model=d.get("model") or "",
+            model_requested=d.get("modelRequested") or "",
+            provider=d.get("provider") or "",
+            routing_decision=d.get("routingDecision") or "",
+            classified_by=d.get("classifiedBy") or "",
+            cache_hit=bool(d.get("cacheHit")),
+            request_id=d.get("requestId") or "",
+            usage=usage,
+            raw=d,
+        )
+
+
+# ── message normalization ─────────────────────────────────────────────────────
+
+
+def _content_to_str(content: Any) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, (list, tuple)):
+        parts = []
+        for c in content:
+            if isinstance(c, str):
+                parts.append(c)
+            elif isinstance(c, dict) and c.get("text"):
+                parts.append(str(c["text"]))
+            elif getattr(c, "text", None):
+                parts.append(str(c.text))
+        return "".join(parts)
+    return "" if content is None else str(content)
+
+
+def _normalize_messages(messages: Any) -> list[dict]:
+    """Accepts a bare string, ``{"role","content"}`` dicts, or duck-typed
+    LangChain messages (objects with ``.type`` and ``.content``)."""
+    if isinstance(messages, str):
+        return [{"role": "user", "content": messages}]
+    if not isinstance(messages, (list, tuple)):
+        messages = [messages]
+    if len(messages) == 0:
+        raise _invalid("`messages` must not be empty")
+    out: list[dict] = []
+    for i, m in enumerate(messages):
+        if m is None:
+            raise _invalid(f"message at index {i} is None")
+        if isinstance(m, str):
+            out.append({"role": "user", "content": m})
+        elif isinstance(m, dict):
+            out.append({"role": m.get("role") or "user", "content": _content_to_str(m.get("content"))})
+        elif hasattr(m, "type") and hasattr(m, "content"):
+            t = str(getattr(m, "type"))
+            role = "system" if t == "system" else "assistant" if t == "ai" else "user"
+            out.append({"role": role, "content": _content_to_str(m.content)})
+        else:
+            raise _invalid(f"message at index {i} is not a str, dict, or LangChain-style message")
+    return out
+
+
+# ── HTTP plumbing (stdlib) ────────────────────────────────────────────────────
+
+
+def _http_once(
+    url: str, *, method: str, body: Optional[dict], timeout_s: float, headers: Optional[dict] = None
+) -> tuple[int, Optional[dict]]:
+    data = json.dumps(body).encode("utf-8") if body is not None else None
+    req = urllib.request.Request(
+        url,
+        data=data,
+        method=method,
+        headers={"Content-Type": "application/json", "Accept": "application/json", **(headers or {})},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout_s) as res:
+            payload = res.read()
+            try:
+                return res.status, json.loads(payload) if payload else None
+            except (json.JSONDecodeError, ValueError):
+                return res.status, None
+    except urllib.error.HTTPError as err:  # non-2xx WITH a response
+        payload = err.read()
+        try:
+            parsed = json.loads(payload) if payload else None
+        except (json.JSONDecodeError, ValueError):
+            parsed = None
+        return err.code, parsed
+    except (TimeoutError, urllib.error.URLError, OSError) as err:
+        reason = getattr(err, "reason", err)
+        if isinstance(err, TimeoutError) or isinstance(reason, TimeoutError) or "timed out" in str(reason).lower():
+            raise GatewayError(
+                f"request timed out after {timeout_s}s", code="timeout", retryable=True
+            ) from err
+        raise GatewayError(f"network error: {reason}", code="network", retryable=True) from err
+
+
+def _error_from_response(status: int, body: Optional[dict]) -> GatewayError:
+    message = (body or {}).get("message") or (body or {}).get("error") or f"gateway responded {status}"
+    code = "http_error"
+    err_field = (body or {}).get("error")
+    if err_field == "demo_mode":
+        code = "demo_mode"
+    elif err_field == "provider_error":
+        code = "provider_error"
+    elif err_field == "invalid_api_key":
+        code = "invalid_api_key"
+    elif err_field == "budget_exceeded":
+        code = "budget_exceeded"
+    elif err_field == "rate_limited":
+        code = "rate_limited"
+    elif status == 400:
+        code = "bad_request"
+    # budget_exceeded is a 429, but retrying won't help until the window rolls past.
+    retryable = code != "budget_exceeded" and (status == 429 or status >= 500)
+    return GatewayError(
+        str(message),
+        status=status,
+        code=code,
+        request_id=(body or {}).get("requestId"),
+        retryable=retryable,
+    )
+
+
+def _request_with_retries(
+    url: str, *, method: str, body: Optional[dict], timeout_s: float, retries: int,
+    headers: Optional[dict] = None,
+) -> dict:
+    last_err: Optional[GatewayError] = None
+    for attempt in range(retries + 1):
+        if attempt > 0:
+            exp = min(_RETRY_CAP_S, _RETRY_BASE_S * (2 ** (attempt - 1)))
+            time.sleep(exp / 2 + random.random() * (exp / 2))
+        try:
+            status, parsed = _http_once(url, method=method, body=body, timeout_s=timeout_s, headers=headers)
+        except GatewayError as err:  # network / timeout
+            last_err = err
+            if err.retryable and attempt < retries:
+                continue
+            raise
+        if 200 <= status < 300:
+            return parsed or {}
+        gerr = _error_from_response(status, parsed)
+        last_err = gerr
+        if gerr.retryable and attempt < retries:
+            continue
+        raise gerr
+    raise last_err if last_err else GatewayError("request failed")  # pragma: no cover
+
+
+# ── the client ────────────────────────────────────────────────────────────────
+
+
+class Client:
+    """Gateway client. Create via :func:`create_client`."""
+
+    def __init__(
+        self,
+        *,
+        base_url: Optional[str] = None,
+        application: Optional[str] = None,
+        workflow: Optional[str] = None,
+        department: Optional[str] = None,
+        user_id: Optional[str] = None,
+        api_key: Optional[str] = None,
+        timeout_s: float = 60.0,
+        retries: int = 2,
+    ) -> None:
+        url = (base_url or os.environ.get("ARBR_GATEWAY_URL") or "").rstrip("/")
+        if not url:
+            raise _invalid("`base_url` is required (or set ARBR_GATEWAY_URL)")
+        self.base_url = url
+        self._defaults = {
+            "application": application,
+            "workflow": workflow,
+            "department": department,
+            "userId": user_id,
+        }
+        # Gateway API key ("ka_…", Settings → API keys). Binds attribution server-side.
+        key = api_key or os.environ.get("ARBR_API_KEY")
+        self._headers = {"Authorization": f"Bearer {key}"} if key else {}
+        self._timeout_s = timeout_s
+        self._retries = max(0, retries)
+
+    # — chat —
+
+    def chat(
+        self,
+        messages: Any,
+        *,
+        model: Optional[str] = None,
+        provider: Optional[str] = None,
+        task_type: Optional[str] = None,
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        application: Optional[str] = None,
+        workflow: Optional[str] = None,
+        department: Optional[str] = None,
+        user_id: Optional[str] = None,
+        timeout_s: Optional[float] = None,
+        retries: Optional[int] = None,
+    ) -> ChatResponse:
+        """One routed completion. ``model=None`` or ``"auto"`` → the gateway's
+        router decides (rules → automated routing → default); an explicit model
+        whose provider is connected is honored as-is."""
+        if messages is None:
+            raise _invalid("`messages` is required")
+        body: dict[str, Any] = {k: v for k, v in self._defaults.items() if v is not None}
+        overrides = {
+            "application": application,
+            "workflow": workflow,
+            "department": department,
+            "userId": user_id,
+            "model": model,
+            "provider": provider,
+            "taskType": task_type,
+            "temperature": temperature,
+            "maxTokens": max_tokens,
+        }
+        body.update({k: v for k, v in overrides.items() if v is not None})
+        body["messages"] = _normalize_messages(messages)
+        raw = _request_with_retries(
+            f"{self.base_url}/v1/chat",
+            method="POST",
+            body=body,
+            timeout_s=timeout_s if timeout_s is not None else self._timeout_s,
+            retries=retries if retries is not None else self._retries,
+            headers=self._headers,
+        )
+        return ChatResponse._from_dict(raw)
+
+    async def achat(self, messages: Any, **kwargs: Any) -> ChatResponse:
+        """Async :meth:`chat` (runs the blocking call in a worker thread)."""
+        return await asyncio.to_thread(self.chat, messages, **kwargs)
+
+    # — stream (honest shim) —
+
+    def stream(self, messages: Any, **kwargs: Any) -> Iterator[str]:
+        """Yield the answer in small text chunks.
+
+        NOTE: the gateway is non-streaming today — this makes ONE buffered
+        :meth:`chat` call and chunks the text out (near-streaming UX, not
+        token-by-token). Use :meth:`chat` when you need the full metadata."""
+        res = self.chat(messages, **kwargs)
+        text = res.text
+        for i in range(0, len(text), _STREAM_CHUNK_CHARS):
+            yield text[i : i + _STREAM_CHUNK_CHARS]
+
+    async def astream(self, messages: Any, **kwargs: Any) -> AsyncIterator[str]:
+        """Async :meth:`stream` (same buffered-shim caveat)."""
+        res = await self.achat(messages, **kwargs)
+        text = res.text
+        for i in range(0, len(text), _STREAM_CHUNK_CHARS):
+            yield text[i : i + _STREAM_CHUNK_CHARS]
+
+    # — status —
+
+    def status(self) -> dict:
+        """Gateway healthcheck — GET /api/status."""
+        return _request_with_retries(
+            f"{self.base_url}/api/status",
+            method="GET",
+            body=None,
+            timeout_s=self._timeout_s,
+            retries=self._retries,
+            headers=self._headers,
+        )
+
+    async def astatus(self) -> dict:
+        return await asyncio.to_thread(self.status)
+
+
+def create_client(
+    base_url: Optional[str] = None,
+    *,
+    application: Optional[str] = None,
+    workflow: Optional[str] = None,
+    department: Optional[str] = None,
+    user_id: Optional[str] = None,
+    api_key: Optional[str] = None,
+    timeout_s: float = 60.0,
+    retries: int = 2,
+) -> Client:
+    """Create a gateway client. ``base_url`` falls back to $ARBR_GATEWAY_URL,
+    ``api_key`` to $ARBR_API_KEY."""
+    return Client(
+        base_url=base_url,
+        application=application,
+        workflow=workflow,
+        department=department,
+        user_id=user_id,
+        api_key=api_key,
+        timeout_s=timeout_s,
+        retries=retries,
+    )
+
+
+# ── LangChain-style adapter (duck-typed; no LangChain dependency) ─────────────
+
+
+class _AiMessageShape:
+    """AIMessage-shaped result: .content, .usage_metadata, .response_metadata,
+    .type == "ai". Attribute access only — not a real LangChain object."""
+
+    def __init__(self, res: ChatResponse) -> None:
+        u = res.usage or Usage()
+        self.content = res.text
+        self.usage_metadata = {
+            "input_tokens": u.input_tokens,
+            "output_tokens": u.output_tokens,
+            "total_tokens": u.total_tokens,
+        }
+        self.response_metadata = {
+            "model": res.model,
+            "provider": res.provider,
+            "routingDecision": res.routing_decision,
+            "classifiedBy": res.classified_by,
+            "modelRequested": res.model_requested,
+            "requestId": res.request_id,
+            "gateway": True,
+        }
+        self.additional_kwargs: dict = {}
+        self.type = "ai"
+
+
+def _coerce_lc_input(value: Any) -> Any:
+    # A LangChain PromptValue (from `prompt | model` chains) → messages.
+    if hasattr(value, "to_messages"):
+        return value.to_messages()
+    return value
+
+
+class _LangChainishModel:
+    """Minimal LangChain-style chat model backed by the gateway (duck-typed).
+
+    Supports .invoke() / .ainvoke() and is itself callable, so simple
+    `prompt | model` chains coerce it via RunnableLambda. For FULL Runnable
+    compatibility (callbacks, batch, with_structured_output), wrap the client
+    in a real BaseChatModel subclass in your app instead."""
+
+    def __init__(self, client: Client, meta: dict) -> None:
+        self._client = client
+        self._meta = meta
+
+    def invoke(self, messages: Any, _config: Any = None, **_: Any) -> _AiMessageShape:
+        res = self._client.chat(_coerce_lc_input(messages), **self._meta)
+        return _AiMessageShape(res)
+
+    async def ainvoke(self, messages: Any, _config: Any = None, **_: Any) -> _AiMessageShape:
+        res = await self._client.achat(_coerce_lc_input(messages), **self._meta)
+        return _AiMessageShape(res)
+
+    # Callable → coercible to RunnableLambda in `prompt | model` chains.
+    def __call__(self, messages: Any, **_: Any) -> _AiMessageShape:
+        return self.invoke(messages)
+
+    def stream(self, messages: Any, **_: Any) -> Iterator[_AiMessageShape]:
+        res = self._client.chat(_coerce_lc_input(messages), **self._meta)
+        text = res.text
+        for i in range(0, len(text), _STREAM_CHUNK_CHARS):
+            chunk = _AiMessageShape(res)
+            chunk.content = text[i : i + _STREAM_CHUNK_CHARS]
+            yield chunk
+
+
+def as_langchain_model(client: Client, **meta: Any) -> _LangChainishModel:
+    """Wrap a client as a minimal LangChain-style chat model (no LangChain
+    dependency). ``meta`` (workflow, task_type, model, temperature,
+    max_tokens, ...) is merged into every call."""
+    return _LangChainishModel(client, meta)

arbr_client/langchain.py

@@ -0,0 +1,119 @@
+"""Optional LangChain integration: the gateway as a real ``BaseChatModel``.
+
+Requires ``langchain-core`` (install via ``pip install arbr-client[langchain]``).
+The core ``arbr_client`` package stays zero-dependency; this module imports
+LangChain lazily and fails with a clear message if it's missing.
+
+    from arbr_client import create_client
+    from arbr_client.langchain import ArbrChatModel
+
+    client = create_client("http://localhost:4100", application="my-app")
+    llm = ArbrChatModel(client=client, model_name="auto")   # or a pinned model id
+    # Full Runnable compatibility: prompt | llm, .ainvoke(), batching, callbacks.
+
+For apps that should NOT take a langchain-core dependency, use the zero-dep
+duck-typed adapter instead: ``arbr_client.as_langchain_model(client, ...)``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+try:
+    from langchain_core.callbacks import (
+        AsyncCallbackManagerForLLMRun,
+        CallbackManagerForLLMRun,
+    )
+    from langchain_core.language_models.chat_models import BaseChatModel
+    from langchain_core.messages import AIMessage, BaseMessage
+    from langchain_core.outputs import ChatGeneration, ChatResult
+except ImportError as _err:  # pragma: no cover
+    raise ImportError(
+        "arbr_client.langchain requires langchain-core — "
+        "install it with: pip install arbr-client[langchain]"
+    ) from _err
+
+__all__ = ["ArbrChatModel", "KaryaChatModel"]
+
+
+class ArbrChatModel(BaseChatModel):
+    """A LangChain chat model that routes completions through the gateway.
+
+    ``model_name`` follows the gateway's semantics: an explicit model id is
+    honored as-is when its provider is connected; ``"auto"`` (or ``None``)
+    lets the gateway's router decide (rules → automated routing → default).
+
+    Out of gateway scope (keep on direct provider SDKs): tool calling /
+    ``with_structured_output``, embeddings, token-level streaming.
+    """
+
+    client: Any  # arbr_client.Client
+    model_name: Optional[str] = None
+    temperature: Optional[float] = None
+    max_tokens: Optional[int] = None
+    workflow: Optional[str] = None
+    task_type: Optional[str] = None
+
+    @property
+    def _llm_type(self) -> str:
+        return "arbr-gateway"
+
+    @property
+    def _identifying_params(self) -> dict:
+        return {"model_name": self.model_name, "gateway": self.client.base_url}
+
+    def _call_kwargs(self) -> dict:
+        return {
+            "model": self.model_name,
+            "temperature": self.temperature,
+            "max_tokens": self.max_tokens,
+            "workflow": self.workflow,
+            "task_type": self.task_type,
+        }
+
+    def _to_result(self, res: Any) -> ChatResult:
+        usage = None
+        if res.usage is not None:
+            usage = {
+                "input_tokens": res.usage.input_tokens,
+                "output_tokens": res.usage.output_tokens,
+                "total_tokens": res.usage.total_tokens,
+            }
+        message = AIMessage(
+            content=res.text,
+            usage_metadata=usage,
+            response_metadata={
+                "model": res.model,
+                "provider": res.provider,
+                "routingDecision": res.routing_decision,
+                "classifiedBy": res.classified_by,
+                "modelRequested": res.model_requested,
+                "requestId": res.request_id,
+                "gateway": True,
+            },
+        )
+        return ChatResult(generations=[ChatGeneration(message=message)])
+
+    def _generate(
+        self,
+        messages: List[BaseMessage],
+        stop: Optional[List[str]] = None,
+        run_manager: Optional[CallbackManagerForLLMRun] = None,
+        **kwargs: Any,
+    ) -> ChatResult:
+        res = self.client.chat(messages, **self._call_kwargs())
+        return self._to_result(res)
+
+    async def _agenerate(
+        self,
+        messages: List[BaseMessage],
+        stop: Optional[List[str]] = None,
+        run_manager: Optional[AsyncCallbackManagerForLLMRun] = None,
+        **kwargs: Any,
+    ) -> ChatResult:
+        res = await self.client.achat(messages, **self._call_kwargs())
+        return self._to_result(res)
+
+
+# Backward-compatibility alias (Karya → Arbr rename).
+KaryaChatModel = ArbrChatModel

arbr_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: arbr-client
+Version: 0.1.0
+Summary: Official Python client for the Arbr AI control-plane gateway — one function to route, observe, and govern every LLM call.
+Author: Gyde
+License: MIT
+Keywords: llm,ai,gateway,routing,control-plane,openai,anthropic,gemini,bedrock,cost
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == "langchain"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Dynamic: license-file
+
+# arbr-client (Python)
+
+Official Python client for the **Arbr AI control plane** — one function to route, observe,
+and govern every LLM call your app makes.
+
+Your app calls the gateway instead of provider SDKs. The gateway holds the provider keys,
+honors the model you pin (or picks one when you say `"auto"`), applies human-approved routing
+rules and cost policies, and logs every call with full cost attribution — visible in the dashboard.
+
+- **Zero dependencies** — Python ≥ 3.11, stdlib only. Sync *and* async (`achat`/`astream`).
+- **One function for the 90% case** — `chat()`.
+- **Robust by default** — per-attempt timeouts, retries with exponential backoff + jitter on
+  network errors / 429 / 5xx, typed errors.
+- **Optional LangChain integration** — a real `BaseChatModel` via `arbr-client[langchain]`.
+
+## Install
+
+```sh
+pip install arbr-client                # core (zero deps)
+pip install "arbr-client[langchain]"   # + the LangChain BaseChatModel adapter
+# (pre-release: pip install /path/to/arbr_client-0.1.0-py3-none-any.whl)
+```
+
+## 60-second quickstart
+
+```python
+from arbr_client import create_client
+
+arbr = create_client(
+    "http://localhost:4100",      # or set ARBR_GATEWAY_URL
+    application="my-app",         # attribution — shows up in the dashboard
+)
+
+res = arbr.chat("Summarise this support ticket: ...", model="auto", max_tokens=300)
+print(res.text)
+print(res.model, res.routing_decision)   # e.g. "gpt-4o-mini", "ai"
+```
+
+Async (FastAPI, LangGraph, etc.):
+
+```python
+res = await arbr.achat("Summarise this ticket: ...", model="auto")
+```
+
+That's a complete integration. No provider keys in your app, and every call is logged,
+costed, and governable from the dashboard.
+
+## How model choice works
+
+| You send | What happens |
+|---|---|
+| `model="gpt-4o"` (provider connected) | Honored **as-is** — all routing policies skipped. `routing_decision == "explicit"` |
+| `model="auto"` or omitted | The gateway decides: cache → operator rules → automated routing (cost guardrail or AI policy) → default model |
+| a model whose provider isn't connected | Falls back to the router (same as `"auto"`) |
+
+`res.model_requested` shows what you asked for, `res.model` what served it, `res.routing_decision`
+why (`explicit / rule / auto / ai / cache / fallback / passthrough`), and `res.classified_by` how
+the task type was determined (`provided / keyword / ai`).
+
+## API
+
+### `create_client(base_url=None, *, application=None, workflow=None, department=None, user_id=None, api_key=None, timeout_s=60, retries=2) → Client`
+
+`base_url` falls back to `$ARBR_GATEWAY_URL`; `api_key` to `$ARBR_API_KEY`. A gateway API key
+(`ab_…`, dashboard → Settings → API keys) is sent as `Authorization: Bearer` and binds attribution
+server-side — required once the gateway has *Require API keys* on. The metadata kwargs are defaults
+merged into every call (per-call kwargs override them).
+
+### `Client.chat(messages, *, model=None, provider=None, task_type=None, temperature=None, max_tokens=None, ...) → ChatResponse`
+
+`messages` accepts a bare string, `{"role", "content"}` dicts, or LangChain message objects.
+`ChatResponse` is a frozen dataclass: `text`, `usage` (`input_tokens/output_tokens/total_tokens`),
+`model`, `model_requested`, `provider`, `routing_decision`, `classified_by`, `cache_hit`,
+`request_id`, plus `.raw` (the unmodified gateway payload).
+
+### `Client.achat(...)` / `Client.astream(...)` / `Client.astatus()`
+
+Async counterparts (the blocking call runs in a worker thread via `asyncio.to_thread`).
+
+### Streaming
+
+The gateway supports two streaming modes:
+
+**Real SSE (token-by-token)** — use the OpenAI-compatible endpoint at `POST /v1/chat/completions`
+with `stream=True`. Works with the OpenAI Python SDK, any chat UI, or a raw `httpx`/`requests` call:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(api_key="ab_…", base_url="http://localhost:4100")
+stream = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "Tell me a joke"}],
+    stream=True,
+)
+for chunk in stream:
+    print(chunk.choices[0].delta.content or "", end="", flush=True)
+```
+
+**`Client.stream(messages, ...) → Iterator[str]`** — makes one buffered `chat()` call and yields
+the text in small chunks. Useful when you want full routing metadata (`res.model`,
+`res.routing_decision`, etc.) alongside a streaming-style emit:
+
+```python
+for chunk in arbr.stream("Explain quantum entanglement simply"):
+    print(chunk, end="", flush=True)
+```
+
+Use the OpenAI-compat endpoint when you need real token-by-token delivery or are integrating with
+chat UIs. Use `stream()` when you want the routing metadata the OpenAI endpoint doesn't expose.
+
+### `Client.status() → dict`
+
+Healthcheck against `GET /api/status` — `demoMode`, `liveProviders`, `defaultProvider`,
+`defaultModel`, `routingMode`, `breachedCaps`.
+When the gateway has admin auth enabled (`ARBR_ADMIN_KEY` set server-side), this endpoint
+requires a credential — your gateway `api_key` is accepted, so set it and `status()` keeps working.
+
+## Error handling
+
+All failures raise `GatewayError` with `.status`, `.code`, `.retryable`, `.request_id`:
+
+| `code` | Meaning | Retried automatically? |
+|---|---|---|
+| `invalid_input` | Bad arguments (caught before any network call) | no |
+| `bad_request` | Gateway rejected the request (HTTP 400) | no |
+| `demo_mode` | Gateway has no provider keys configured (HTTP 503) | no |
+| `provider_error` | All providers failed for this call (HTTP 502) | yes (5xx) |
+| `http_error` | Other non-2xx | 429/5xx only |
+| `invalid_api_key` | Missing/unknown/revoked gateway API key (HTTP 401) | no |
+| `budget_exceeded` | A budget cap with action *Block* is breached for your scope (HTTP 429) | no — retrying won't help until the window rolls past |
+| `rate_limited` | Your API key is over its requests/minute limit (HTTP 429) | yes |
+| `network` | Connection failed | yes |
+| `timeout` | Per-attempt timeout elapsed | yes |
+
+## LangChain integration
+
+Two options, by how deep your LangChain usage goes:
+
+**1. Full `BaseChatModel` (recommended for LangChain/LangGraph apps)** — requires the extra:
+
+```python
+from arbr_client import create_client
+from arbr_client.langchain import ArbrChatModel
+
+client = create_client("http://localhost:4100", application="my-app")
+llm = ArbrChatModel(client=client, model_name="auto", max_tokens=1024)
+
+chain = my_prompt | llm           # full Runnable compatibility:
+await chain.ainvoke({...})        # pipes, async, batching, callbacks
+```
+
+**2. Zero-dep duck-typed adapter** — when you don't want a langchain-core dependency:
+
+```python
+from arbr_client import as_langchain_model
+llm = as_langchain_model(client, workflow="answer-drafting")
+msg = llm.invoke(messages)        # .invoke()/.ainvoke(); AIMessage-shaped result
+```
+
+Out of gateway scope either way: tool calling / `with_structured_output`, embeddings, and
+token-level streaming — keep those on direct provider SDKs.
+
+## Gradual rollout pattern
+
+Gate the swap at your app's LLM factory so nothing else changes:
+
+```python
+def get_llm():
+    if os.environ.get("ARBR_GATEWAY_URL"):
+        return ArbrChatModel(client=_arbr_client(), model_name=settings.llm_model)
+    return build_direct_provider_model()   # unchanged path
+```
+
+Unset `ARBR_GATEWAY_URL` to revert instantly.
+
+## License
+
+MIT

arbr_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+arbr_client/__init__.py,sha256=xt9PY_j7ZqGAXic4hcTDx5ckVVk-p_11-85FNkcd45Q,17786
+arbr_client/langchain.py,sha256=KxcoAH8pbVj4kOKGiWDYgWUje7A9kfC_474IMGga7bI,4262
+arbr_client-0.1.0.dist-info/licenses/LICENSE,sha256=JldKhrRTw7NX0Ez2qqITMbeIJ1bOJJlDmUK-U0ZW94M,1061
+arbr_client-0.1.0.dist-info/METADATA,sha256=B5I308M42eIxFfHUWbdO8fIOwpMBfIeDI9EL4lLG_jc,8278
+arbr_client-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+arbr_client-0.1.0.dist-info/top_level.txt,sha256=fyVHSgqGkJcdvCsgqfFKUiuUz6qqida3lD3jqXLwAXk,12
+arbr_client-0.1.0.dist-info/RECORD,,

arbr_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

arbr_client-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gyde
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

arbr_client-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+arbr_client