abto 0.0.1__py3-none-any.whl

abto/__init__.py

@@ -0,0 +1,35 @@
+"""`abto` — ABTO server-side SDK for Python.
+
+Thin gateway header helper: carries x-abto-* identifiers via contextvars and
+injects them into outbound provider calls (httpx event hooks). The gateway owns
+token, cost, latency, request_id, and variant assignment.
+"""
+
+from .client import Abto, abto_request_hook, create_abto
+from .context import (
+    ABTO_HEADER,
+    AbtoContext,
+    create_trace_id,
+    create_traceparent,
+    get_context,
+    get_headers,
+    set_context,
+    with_context,
+)
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "Abto",
+    "create_abto",
+    "abto_request_hook",
+    "AbtoContext",
+    "ABTO_HEADER",
+    "with_context",
+    "get_context",
+    "set_context",
+    "get_headers",
+    "create_trace_id",
+    "create_traceparent",
+    "__version__",
+]

abto/client.py

@@ -0,0 +1,62 @@
+"""Thin server facade: gateway baseURL + ABTO header injection.
+
+It does not compute token/cost/latency. It routes provider SDK calls through the
+ABTO Gateway and carries the x-abto-* identifiers from the current context.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional
+
+from .context import AbtoContext, create_trace_id, get_headers, with_context
+
+
+def abto_request_hook() -> Callable[[Any], None]:
+    """httpx request event hook: inject ABTO headers from the current context."""
+
+    def hook(request: Any) -> None:
+        for key, value in get_headers().items():
+            request.headers.setdefault(key, value)
+
+    return hook
+
+
+class Abto:
+    def __init__(self, api_key: Optional[str] = None, gateway_base_url: Optional[str] = None) -> None:
+        self.api_key = api_key
+        self.gateway_base_url = gateway_base_url
+
+    def get_headers(self, ctx: Optional[AbtoContext] = None) -> Dict[str, str]:
+        return get_headers(ctx)
+
+    def with_context(self, **kwargs: Optional[str]):
+        return with_context(**kwargs)
+
+    def create_trace_id(self) -> str:
+        return create_trace_id()
+
+    def httpx_event_hooks(self) -> Dict[str, List[Callable[[Any], None]]]:
+        return {"request": [abto_request_hook()]}
+
+    def openai(self, **client_kwargs: Any) -> Any:
+        """Construct an OpenAI client pointed at the gateway with header injection.
+
+        Requires the optional `openai` and `httpx` extras.
+        """
+        try:
+            import httpx
+            from openai import OpenAI
+        except ImportError as exc:  # pragma: no cover - optional dependency
+            raise ImportError("abto.openai() requires the 'openai' extra: pip install 'abto[openai]'") from exc
+
+        http_client = httpx.Client(event_hooks=self.httpx_event_hooks())
+        return OpenAI(
+            api_key=self.api_key,
+            base_url=self.gateway_base_url,
+            http_client=http_client,
+            **client_kwargs,
+        )
+
+
+def create_abto(api_key: Optional[str] = None, gateway_base_url: Optional[str] = None) -> Abto:
+    return Abto(api_key=api_key, gateway_base_url=gateway_base_url)

abto/context.py

@@ -0,0 +1,83 @@
+"""Request-scoped ABTO identifier context for the `abto` Python package.
+
+Mirrors @abto-app/sdk/server: carries the gateway identifier headers via
+contextvars so outbound provider calls can attach them. The gateway remains the
+source of truth for token, cost, latency, request_id, and variant assignment.
+"""
+
+from __future__ import annotations
+
+import contextvars
+import secrets
+from contextlib import contextmanager
+from dataclasses import dataclass, replace
+from typing import Dict, Iterator, Optional
+
+ABTO_HEADER = {
+    "user_id": "x-abto-device-id",
+    "node_id": "x-abto-node-key",
+    "traceparent": "traceparent",
+}
+
+
+@dataclass(frozen=True)
+class AbtoContext:
+    """End-user id, "feature.node" node id, and end-user action trace id."""
+
+    user_id: Optional[str] = None
+    node_id: Optional[str] = None
+    trace_id: Optional[str] = None
+
+
+_current: contextvars.ContextVar[AbtoContext] = contextvars.ContextVar(
+    "abto_context", default=AbtoContext()
+)
+
+
+def get_context() -> AbtoContext:
+    return _current.get()
+
+
+def set_context(
+    user_id: Optional[str] = None,
+    node_id: Optional[str] = None,
+    trace_id: Optional[str] = None,
+) -> None:
+    patch = {k: v for k, v in dict(user_id=user_id, node_id=node_id, trace_id=trace_id).items() if v is not None}
+    _current.set(replace(_current.get(), **patch))
+
+
+@contextmanager
+def with_context(
+    user_id: Optional[str] = None,
+    node_id: Optional[str] = None,
+    trace_id: Optional[str] = None,
+) -> Iterator[AbtoContext]:
+    patch = {k: v for k, v in dict(user_id=user_id, node_id=node_id, trace_id=trace_id).items() if v is not None}
+    merged = replace(_current.get(), **patch)
+    token = _current.set(merged)
+    try:
+        yield merged
+    finally:
+        _current.reset(token)
+
+
+def create_trace_id() -> str:
+    """32-hex-char trace id, per W3C trace-context."""
+    return secrets.token_hex(16)
+
+
+def create_traceparent(trace_id: str) -> str:
+    return f"00-{trace_id}-{secrets.token_hex(8)}-01"
+
+
+def get_headers(ctx: Optional[AbtoContext] = None) -> Dict[str, str]:
+    c = ctx if ctx is not None else _current.get()
+    headers: Dict[str, str] = {}
+    if c.user_id:
+        headers[ABTO_HEADER["user_id"]] = c.user_id
+    if c.node_id:
+        headers[ABTO_HEADER["node_id"]] = c.node_id
+    if c.trace_id:
+        headers[ABTO_HEADER["traceparent"]] = create_traceparent(c.trace_id)
+    return headers