tensorcost 0.4.0__py3-none-any.whl

tensorcost/__init__.py

@@ -0,0 +1,61 @@
+"""TensorCost Python SDK — one-line wrapper for OpenAI and Anthropic clients.
+
+Usage:
+
+    from openai import OpenAI
+    from tensorcost import wrap
+
+    client = wrap(OpenAI(api_key="..."))
+    # use `client` exactly like a normal OpenAI client; observations
+    # are sent fire-and-forget to TensorCost in the background.
+
+The SDK fails open by default: if TensorCost is unreachable, the
+underlying provider call still completes normally.
+"""
+
+from ._wrap import wrap
+from ._config import MissingConfigError
+from ._providers._detect import UnsupportedClientError
+from ._errors import (
+    TensorCostError,
+    TensorCostNetworkError,
+    TensorCostTimeoutError,
+    TensorCostProxyError,
+    TensorCostQuotaError,
+    TensorCostProviderError,
+)
+from ._telemetry import (
+    LifecycleEvent,
+    BeforeRequestEvent,
+    AfterResponseEvent,
+    OnRetryEvent,
+    OnErrorEvent,
+    OnFallbackEvent,
+    LifecycleEventCallback,
+)
+from ._retry import RetryConfig
+
+__version__ = "0.4.0"
+__all__ = [
+    "wrap",
+    "MissingConfigError",
+    "UnsupportedClientError",
+    # Error hierarchy
+    "TensorCostError",
+    "TensorCostNetworkError",
+    "TensorCostTimeoutError",
+    "TensorCostProxyError",
+    "TensorCostQuotaError",
+    "TensorCostProviderError",
+    # Telemetry types
+    "LifecycleEvent",
+    "BeforeRequestEvent",
+    "AfterResponseEvent",
+    "OnRetryEvent",
+    "OnErrorEvent",
+    "OnFallbackEvent",
+    "LifecycleEventCallback",
+    # Config types
+    "RetryConfig",
+    "__version__",
+]

tensorcost/_applied_mode.py

@@ -0,0 +1,148 @@
+"""Applied-mode (Layer 2) HTTP routing helpers.
+
+When applied_mode=True, chat/completions calls are forwarded through the
+TensorCost inference-proxy rather than going straight to the upstream
+provider. The proxy decides per-request whether to route or pass through;
+the SDK is not involved in that decision.
+
+The two required proxy headers:
+  x-tc-provider-url   The original provider's base URL (e.g. "https://api.openai.com").
+  x-tc-provider-auth  The auth header value the SDK would have sent to the provider
+                      (e.g. "Bearer sk-..." for OpenAI, "sk-ant-..." for Anthropic).
+
+The proxy is OpenAI-API-compatible — the request body is forwarded verbatim,
+and the response body is returned verbatim to the caller. The customer's
+parsing code sees no difference.
+
+This module is an internal helper; nothing here is part of the public API.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+# Proxy path appended to proxy_url when routing chat/completions.
+PROXY_CHAT_PATH = "/api/inference-proxy/v1/chat/completions"
+
+
+def build_proxy_headers(
+    provider_url: str,
+    provider_auth: str,
+    correlation_id: str | None = None,
+    environment: str | None = None,
+) -> dict[str, str]:
+    """Return the custom headers the proxy controller requires.
+
+    Only x-tc-provider-url and x-tc-provider-auth are mandatory; the
+    correlation and environment headers are added when present so the
+    proxy can tie the request to the observation record and use the
+    environment for policy matching.
+    """
+    headers: dict[str, str] = {
+        "x-tc-provider-url": provider_url,
+        "x-tc-provider-auth": provider_auth,
+    }
+    if correlation_id:
+        headers["x-tc-correlation-id"] = correlation_id
+    if environment:
+        headers["x-tc-environment"] = environment
+    return headers
+
+
+def openai_provider_auth(client: Any) -> str:
+    """Extract the Authorization header value for an OpenAI-style client.
+
+    OpenAI uses "Bearer <api_key>" as the Authorization header.  We
+    read the key from the client object rather than re-capturing a
+    closure variable so that key rotation on the client instance is
+    respected automatically.
+    """
+    # openai.OpenAI stores the key as client.api_key.
+    api_key = getattr(client, "api_key", None)
+    if api_key:
+        return f"Bearer {api_key}"
+    # Fallback: return empty string; the proxy will 400 on an absent auth.
+    return ""
+
+
+def openai_provider_base_url(client: Any) -> str:
+    """Return the upstream base URL for an OpenAI-style client.
+
+    openai.OpenAI stores it as client.base_url (an httpx.URL).  We
+    coerce to str and strip trailing slash so the proxy gets a clean URL.
+    """
+    base = getattr(client, "base_url", None)
+    if base is not None:
+        url = str(base).rstrip("/")
+        # openai-python sets base_url to "https://api.openai.com/v1" by
+        # default. The proxy expects the provider's plain base (no path),
+        # because the proxy appends "/v1/chat/completions" itself.
+        # Strip any trailing path component that looks like an API version
+        # (i.e. ends with /v1, /v2, etc.) so x-tc-provider-url is always
+        # the scheme+host portion. The proxy will receive
+        # "https://api.openai.com" and know what path to append.
+        import re
+        url = re.sub(r"/v\d+$", "", url)
+        return url
+    return "https://api.openai.com"
+
+
+def anthropic_provider_auth(client: Any) -> str:
+    """Extract the x-api-key value for an Anthropic client.
+
+    Anthropic's SDK uses "x-api-key: <key>" rather than Bearer.
+    The proxy is responsible for forwarding this in the right header;
+    the SDK just surfaces the raw key.  We prefix with the literal
+    header name so the proxy can reconstruct the Authorization shape.
+    """
+    api_key = getattr(client, "api_key", None)
+    if api_key:
+        # Encode as "x-api-key <key>" so the proxy can distinguish this
+        # from OpenAI-style Bearer tokens and set the right header on the
+        # upstream call.
+        return f"x-api-key {api_key}"
+    return ""
+
+
+def anthropic_provider_base_url(client: Any) -> str:
+    """Return the upstream base URL for an Anthropic client."""
+    base = getattr(client, "base_url", None)
+    if base is not None:
+        return str(base).rstrip("/")
+    return "https://api.anthropic.com"
+
+
+def route_via_proxy(
+    proxy_url: str,
+    bearer_token: str,
+    provider_url: str,
+    provider_auth: str,
+    body: dict[str, Any],
+    timeout_s: float = 30.0,
+    correlation_id: str | None = None,
+    environment: str | None = None,
+) -> httpx.Response:
+    """POST *body* to the inference-proxy and return the raw httpx.Response.
+
+    This is a synchronous blocking call — it runs on the customer's
+    calling thread, same as the original provider call would have.
+
+    The caller is responsible for forwarding the response status and body
+    back to the customer's code.
+    """
+    url = proxy_url.rstrip("/") + PROXY_CHAT_PATH
+    headers = {
+        "Authorization": f"Bearer {bearer_token}",
+        "Content-Type": "application/json",
+        **build_proxy_headers(
+            provider_url=provider_url,
+            provider_auth=provider_auth,
+            correlation_id=correlation_id,
+            environment=environment,
+        ),
+    }
+    with httpx.Client(timeout=timeout_s) as client:
+        return client.post(url, json=body, headers=headers)

tensorcost/_circuit.py

@@ -0,0 +1,99 @@
+"""Circuit breaker for the fail-open proxy fallback.
+
+Tracks consecutive proxy failures.  When the failure count reaches
+``open_threshold``, the circuit opens and subsequent requests go directly to
+the provider instead of through the proxy.  The circuit closes again after
+``close_threshold`` consecutive successful probe calls.
+
+State machine::
+
+    CLOSED ──(failures >= open_threshold)──> OPEN
+    OPEN   ──(next call, probes)───────────> HALF_OPEN
+    HALF_OPEN ──(proxy 2xx)────────────────> probe_successes++
+               ──(proxy 5xx/err)───────────> back to OPEN
+    HALF_OPEN ──(probe_successes >= close_threshold)──> CLOSED
+
+This is intentionally simple and synchronous — the circuit lives on the SDK
+client instance and is not shared across threads.  The transport layer already
+serialises token exchange with a lock; no additional locking is needed here
+because apply-mode proxy calls run on the calling thread.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+CircuitState = Literal["CLOSED", "OPEN", "HALF_OPEN"]
+
+
+@dataclass(frozen=True)
+class CircuitBreakerConfig:
+    """Configuration for the proxy circuit breaker."""
+
+    #: Consecutive proxy failures before the circuit opens.
+    open_threshold: int = 3
+    #: Consecutive probe successes before the circuit closes again.
+    close_threshold: int = 5
+
+
+DEFAULT_CIRCUIT_CONFIG = CircuitBreakerConfig()
+
+
+class CircuitBreaker:
+    """Simple synchronous circuit breaker."""
+
+    def __init__(self, config: CircuitBreakerConfig = DEFAULT_CIRCUIT_CONFIG) -> None:
+        self.config = config
+        self._state: CircuitState = "CLOSED"
+        self._consecutive_failures: int = 0
+        self._probe_successes: int = 0
+
+    @property
+    def state(self) -> CircuitState:
+        return self._state
+
+    @property
+    def failures(self) -> int:
+        return self._consecutive_failures
+
+    def should_bypass(self) -> bool:
+        """Return True when calls should skip the proxy entirely."""
+        return self._state == "OPEN"
+
+    def should_probe(self) -> bool:
+        """Return True when the next call should be a proxy probe.
+
+        Transitions OPEN → HALF_OPEN as a side effect.
+        """
+        if self._state == "OPEN":
+            self._state = "HALF_OPEN"
+            return True
+        return False
+
+    def record_success(self) -> None:
+        """Call after a proxy request succeeds."""
+        if self._state == "HALF_OPEN":
+            self._probe_successes += 1
+            if self._probe_successes >= self.config.close_threshold:
+                self._reset()
+        elif self._state == "CLOSED":
+            self._consecutive_failures = 0
+
+    def record_failure(self) -> None:
+        """Call after a proxy request fails (5xx or network error)."""
+        if self._state == "HALF_OPEN":
+            # Probe failed — go back to fully open.
+            self._state = "OPEN"
+            self._probe_successes = 0
+        elif self._state == "CLOSED":
+            self._consecutive_failures += 1
+            if self._consecutive_failures >= self.config.open_threshold:
+                self._state = "OPEN"
+        # OPEN + another failure: stay open.
+
+    def _reset(self) -> None:
+        self._state = "CLOSED"
+        self._consecutive_failures = 0
+        self._probe_successes = 0

tensorcost/_config.py

@@ -0,0 +1,156 @@
+"""Configuration resolution for the SDK.
+
+Resolution order:
+  1. Explicit kwargs to ``wrap()``
+  2. Environment variables (TENSORCOST_API_KEY, TENSORCOST_BASE_URL,
+     TENSORCOST_TENANT_ID, TENSORCOST_PROXY_URL)
+  3. Defaults (only for base_url)
+
+If ``api_key`` is still missing after resolution, ``MissingConfigError``
+is raised. This is the *one* case the SDK does not fail open: it means
+the SDK was never configured at all.
+
+If ``applied_mode=True`` but no proxy URL is available (from kwarg or
+``TENSORCOST_PROXY_URL``), ``MissingConfigError`` is raised at wrap time
+rather than on the first request — misconfigured applied-mode fails
+loudly so the problem surfaces in development, not in production.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+
+from ._retry import RetryConfig, DEFAULT_RETRY_CONFIG
+from ._telemetry import LifecycleEventCallback
+
+
+DEFAULT_BASE_URL = "https://api.tensorcost.com"
+
+
+class MissingConfigError(RuntimeError):
+    """Raised when required configuration (api_key or proxy_url) is missing."""
+
+
+@dataclass(frozen=True)
+class ResolvedConfig:
+    api_key: str
+    base_url: str
+    tenant_id: Optional[str]
+    # Phase A4 batch 3 — resolved environment tag. ``None`` when the
+    # customer did not configure one; the SDK omits the ``environment``
+    # field from the envelope in that case so the backend's default
+    # ('production') applies.
+    environment: Optional[str]
+    # Phase A4 batch 4 — resolved provider-connection identifier.
+    # ``None`` when the customer did not configure one; the SDK omits
+    # the ``connection_id`` field from the envelope in that case.
+    connection_id: Optional[str]
+    fail_open: bool
+    # Applied-mode (Layer 2). When True, wrap functions route chat/completions
+    # calls through the TensorCost inference-proxy instead of directly to the
+    # upstream provider. Observe-only telemetry still fires on every request.
+    applied_mode: bool
+    # Resolved proxy base URL. Only meaningful when applied_mode is True.
+    # Points to the TensorCost deployment (e.g. "https://api.my-instance.tensorcost.com").
+    # The SDK appends /api/inference-proxy/v1/chat/completions to form the target URL.
+    proxy_url: Optional[str]
+
+    # Hardening fields — all have safe defaults in resolve_config().
+    retry: RetryConfig = field(default_factory=lambda: DEFAULT_RETRY_CONFIG)
+    timeout_s: float = 60.0
+    idle_timeout_s: float = 30.0
+    on_lifecycle_event: Optional[LifecycleEventCallback] = None
+    fail_open_enabled: bool = True
+    provider_api_key: Optional[str] = None
+
+
+def resolve_config(
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    tenant_id: Optional[str] = None,
+    environment: Optional[str] = None,
+    connection_id: Optional[str] = None,
+    fail_open: bool = True,
+    applied_mode: bool = False,
+    proxy_url: Optional[str] = None,
+    # Hardening options.
+    retry: Optional[RetryConfig] = None,
+    timeout_s: float = 60.0,
+    idle_timeout_s: float = 30.0,
+    on_lifecycle_event: Optional[LifecycleEventCallback] = None,
+    fail_open_enabled: bool = True,
+    provider_api_key: Optional[str] = None,
+) -> ResolvedConfig:
+    """Resolve final config values, env vars filling in any blanks."""
+    final_api_key = api_key or os.environ.get("TENSORCOST_API_KEY")
+    final_base_url = (
+        base_url
+        or os.environ.get("TENSORCOST_BASE_URL")
+        or DEFAULT_BASE_URL
+    )
+    final_tenant_id = tenant_id or os.environ.get("TENSORCOST_TENANT_ID")
+
+    # Phase A4 batch 3 — environment tag. Trimmed; capped at 64 chars
+    # per project_environment_scoping.md. An empty / whitespace-only
+    # value collapses to None so the SDK omits the field from the
+    # envelope and the backend's column default ('production') applies.
+    raw_env = environment or os.environ.get("TENSORCOST_ENVIRONMENT")
+    final_environment: Optional[str] = None
+    if raw_env is not None:
+        trimmed = raw_env.strip()
+        if len(trimmed) > 64:
+            raise MissingConfigError(
+                "TensorCost environment must be 64 characters or fewer."
+            )
+        final_environment = trimmed if trimmed else None
+
+    # Phase A4 batch 4 — provider-connection id. Same trim+cap rules as
+    # environment; collapsing blank to ``None`` so the SDK omits the
+    # field when not configured.
+    raw_conn = connection_id or os.environ.get("TENSORCOST_CONNECTION_ID")
+    final_connection_id: Optional[str] = None
+    if raw_conn is not None:
+        trimmed = raw_conn.strip()
+        if len(trimmed) > 64:
+            raise MissingConfigError(
+                "TensorCost connection_id must be 64 characters or fewer."
+            )
+        final_connection_id = trimmed if trimmed else None
+
+    if not final_api_key:
+        raise MissingConfigError(
+            "TensorCost api_key not found. Pass api_key=... to wrap() or "
+            "set the TENSORCOST_API_KEY environment variable."
+        )
+
+    # Resolve proxy_url. Only required when applied_mode is True.
+    final_proxy_url = (
+        proxy_url or os.environ.get("TENSORCOST_PROXY_URL") or None
+    )
+    if final_proxy_url is not None:
+        final_proxy_url = final_proxy_url.rstrip("/")
+
+    if applied_mode and not final_proxy_url:
+        raise MissingConfigError(
+            "applied_mode=True requires a proxy URL. Pass proxy_url=... to wrap() or "
+            "set the TENSORCOST_PROXY_URL environment variable."
+        )
+
+    return ResolvedConfig(
+        api_key=final_api_key,
+        base_url=final_base_url.rstrip("/"),
+        tenant_id=final_tenant_id,
+        environment=final_environment,
+        connection_id=final_connection_id,
+        fail_open=fail_open,
+        applied_mode=applied_mode,
+        proxy_url=final_proxy_url,
+        retry=retry if retry is not None else DEFAULT_RETRY_CONFIG,
+        timeout_s=timeout_s,
+        idle_timeout_s=idle_timeout_s,
+        on_lifecycle_event=on_lifecycle_event,
+        fail_open_enabled=fail_open_enabled,
+        provider_api_key=provider_api_key,
+    )

tensorcost/_errors.py

@@ -0,0 +1,122 @@
+"""Typed error hierarchy for the TensorCost Python SDK.
+
+Every error thrown by the SDK's applied-mode request path is a subclass of
+``TensorCostError``.  Customer code can ``isinstance``-branch on any of them
+without importing raw exception types from the underlying HTTP layer.
+
+Hierarchy::
+
+    TensorCostError (base)
+    ├── TensorCostNetworkError    couldn't reach the proxy at all
+    ├── TensorCostTimeoutError    request or idle window exceeded limit
+    ├── TensorCostProxyError      proxy responded with 5xx
+    ├── TensorCostQuotaError      proxy responded with 429
+    └── TensorCostProviderError   proxy forwarded an upstream provider error
+
+All subclasses carry:
+
+* ``root_cause``  — the underlying Exception, if any (avoids clash with
+                    ``Exception.__cause__`` semantics)
+* ``status``      — HTTP status code (None when the request never completed)
+* ``request_id``  — value of the X-TC-Request-ID header the proxy stamps
+* ``attempt``     — 1-based attempt number at the time the error occurred
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class TensorCostError(Exception):
+    """Base class for all TensorCost SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        root_cause: Optional[Exception] = None,
+        status: Optional[int] = None,
+        request_id: Optional[str] = None,
+        attempt: int = 1,
+    ) -> None:
+        super().__init__(message)
+        self.root_cause = root_cause
+        self.status = status
+        self.request_id = request_id
+        self.attempt = attempt
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"message={str(self)!r}, "
+            f"status={self.status!r}, "
+            f"attempt={self.attempt!r})"
+        )
+
+
+class TensorCostNetworkError(TensorCostError):
+    """The SDK could not establish a connection to the proxy at all."""
+
+
+class TensorCostTimeoutError(TensorCostError):
+    """A request or idle-window timeout fired before the operation completed.
+
+    ``timeout_kind`` is ``"total"`` for a wall-clock limit or ``"idle"`` for
+    a streaming idle window.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        timeout_kind: str,
+        *,
+        root_cause: Optional[Exception] = None,
+        status: Optional[int] = None,
+        request_id: Optional[str] = None,
+        attempt: int = 1,
+    ) -> None:
+        super().__init__(
+            message,
+            root_cause=root_cause,
+            status=status,
+            request_id=request_id,
+            attempt=attempt,
+        )
+        self.timeout_kind = timeout_kind  # "total" | "idle"
+
+
+class TensorCostProxyError(TensorCostError):
+    """The proxy returned a 5xx response (TensorCost infrastructure error)."""
+
+
+class TensorCostQuotaError(TensorCostError):
+    """The proxy returned 429 Too Many Requests.
+
+    ``retry_after_ms`` is set when the response included a ``Retry-After``
+    header (in milliseconds).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        retry_after_ms: Optional[int] = None,
+        *,
+        root_cause: Optional[Exception] = None,
+        status: int = 429,
+        request_id: Optional[str] = None,
+        attempt: int = 1,
+    ) -> None:
+        super().__init__(
+            message,
+            root_cause=root_cause,
+            status=status,
+            request_id=request_id,
+            attempt=attempt,
+        )
+        self.retry_after_ms = retry_after_ms
+
+
+class TensorCostProviderError(TensorCostError):
+    """The proxy reached the upstream provider, but the provider returned an
+    error (4xx / 5xx from OpenAI, Anthropic, etc.).  ``status`` reflects the
+    provider's HTTP status code."""

tensorcost/_models.py

@@ -0,0 +1,40 @@
+"""Internal type definitions for observation payloads."""
+
+from __future__ import annotations
+
+from typing import Optional, TypedDict
+
+
+class Observation(TypedDict, total=False):
+    """The wire shape posted to /api/proxy/observation.
+
+    Per TIER-2-SDK-PLAN §6. Fields are flat strings/ints to keep the
+    backend ingestion fast.
+    """
+
+    sdk_version: str
+    provider: str  # "openai" | "anthropic"
+    model: str
+    operation: str  # "chat.completions" | "completions" | "messages"
+    request_at: str  # ISO-8601
+    response_at: str  # ISO-8601
+    input_tokens: Optional[int]
+    output_tokens: Optional[int]
+    cost_usd_cents: Optional[int]  # SDK doesn't compute; backend fills
+    status: str  # "success" | "error"
+    error_message: Optional[str]
+    correlation_id: str  # uuid4
+    tenant_id: Optional[str]
+    # Phase A4 batch 3 — per-environment data scoping. Optional; the
+    # SDK omits the field when ``wrap()`` was not given an
+    # ``environment`` kwarg, and the backend then falls back to the
+    # column default ('production'). Free-text per
+    # project_environment_scoping.md (1..64 chars).
+    environment: Optional[str]
+    # Phase A4 batch 4 — provider-connection identifier. Optional; the
+    # SDK omits the field when ``wrap()`` was not given a
+    # ``connection_id`` kwarg. When present, ai-service uses it as the
+    # second tier of its env-resolution chain (look up
+    # `integration.cloud_account.environment` for the row whose `id`
+    # matches, behind a per-process 60s LRU cache).
+    connection_id: Optional[str]

tensorcost/_providers/__init__.py

@@ -0,0 +1 @@
+"""Provider-specific wrappers."""