tensorcost 0.4.0__py3-none-any.whl

tensorcost/_providers/_anthropic.py

@@ -0,0 +1,266 @@
+"""Anthropic client wrapping.
+
+Intercepts ``client.messages.create``. Same shape and guarantees as the
+OpenAI wrapper: metadata-only capture, fail-open on observation errors.
+
+Applied-mode hardening (v0.4.0): messages.create calls route through the
+proxy-client module, which handles retries, timeouts, typed errors,
+telemetry hooks, and the fail-open circuit breaker.
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from .._applied_mode import (
+    anthropic_provider_auth,
+    anthropic_provider_base_url,
+)
+from .._circuit import CircuitBreaker
+from .._errors import TensorCostProxyError
+from .._models import Observation
+from .._proxy_client import proxy_request
+from .._retry import DEFAULT_RETRY_CONFIG, RetryConfig
+from .._telemetry import LifecycleEventCallback, OnFallbackEvent, emit_event
+from .._transport import ObservationTransport
+
+_SDK_VERSION = "tensorcost-python/0.4.0"
+_log = logging.getLogger("tensorcost")
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _extract_usage(response: Any) -> tuple[int | None, int | None]:
+    usage = getattr(response, "usage", None)
+    if usage is None and isinstance(response, dict):
+        usage = response.get("usage")
+    if usage is None:
+        return None, None
+    if isinstance(usage, dict):
+        return usage.get("input_tokens"), usage.get("output_tokens")
+    return (
+        getattr(usage, "input_tokens", None),
+        getattr(usage, "output_tokens", None),
+    )
+
+
+def _post_obs(
+    transport: ObservationTransport,
+    model: str,
+    tenant_id: str | None,
+    environment: str | None,
+    connection_id: str | None,
+    correlation_id: str,
+    request_at: str,
+    input_tokens: int | None,
+    output_tokens: int | None,
+    status: str,
+    error_message: str | None,
+) -> None:
+    obs: dict = {
+        "sdk_version": _SDK_VERSION,
+        "provider": "anthropic",
+        "model": model,
+        "operation": "messages",
+        "request_at": request_at,
+        "response_at": _now_iso(),
+        "input_tokens": input_tokens,
+        "output_tokens": output_tokens,
+        "cost_usd_cents": None,
+        "status": status,
+        "error_message": error_message,
+        "correlation_id": correlation_id,
+        "tenant_id": tenant_id,
+        **({"environment": environment} if environment is not None else {}),
+        **({"connection_id": connection_id} if connection_id is not None else {}),
+    }
+    try:
+        transport.post(obs)
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def _wrap_method(
+    bound_method: Any,
+    *,
+    transport: ObservationTransport,
+    tenant_id: str | None,
+    environment: str | None,
+    connection_id: str | None,
+    applied_mode: bool = False,
+    proxy_url: Optional[str] = None,
+    client_ref: Optional[Any] = None,
+    retry: RetryConfig = DEFAULT_RETRY_CONFIG,
+    timeout_s: float = 60.0,
+    on_lifecycle_event: Optional[LifecycleEventCallback] = None,
+    fail_open_enabled: bool = True,
+    circuit: Optional[CircuitBreaker] = None,
+) -> Any:
+    @functools.wraps(bound_method)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        request_at = _now_iso()
+        model = kwargs.get("model") or (args[0] if args else "unknown")
+        correlation_id = str(uuid.uuid4())
+
+        # Applied-mode path.
+        if applied_mode and proxy_url:
+            provider_url = anthropic_provider_base_url(client_ref) if client_ref else "https://api.anthropic.com"
+            provider_auth = anthropic_provider_auth(client_ref) if client_ref else ""
+
+            body: dict[str, Any] = dict(kwargs)
+            body["model"] = str(model)
+
+            circuit_was_open = circuit is not None and circuit.should_bypass()
+            proxy_failed = False
+            proxy_error: Optional[Exception] = None
+            proxy_result: Optional[Any] = None
+
+            if not circuit_was_open:
+                try:
+                    bearer_token = transport._get_token()
+                    proxy_result = proxy_request(
+                        proxy_url=proxy_url,
+                        bearer_token=bearer_token,
+                        provider_url=provider_url,
+                        provider_auth=provider_auth,
+                        body=body,
+                        model=str(model),
+                        provider="anthropic",
+                        operation="messages",
+                        correlation_id=correlation_id,
+                        environment=environment,
+                        retry=retry,
+                        timeout_s=timeout_s,
+                        on_lifecycle_event=on_lifecycle_event,
+                        circuit=circuit,
+                    )
+                except Exception as exc:  # noqa: BLE001
+                    proxy_failed = True
+                    proxy_error = exc
+            else:
+                proxy_failed = True
+
+            if proxy_failed or circuit_was_open:
+                if not fail_open_enabled:
+                    tc_err = (
+                        proxy_error
+                        if isinstance(proxy_error, TensorCostProxyError)
+                        else TensorCostProxyError(
+                            str(proxy_error) if proxy_error else "proxy unavailable",
+                            root_cause=proxy_error if isinstance(proxy_error, Exception) else None,
+                            attempt=1,
+                        )
+                    )
+                    _post_obs(
+                        transport, str(model), tenant_id, environment,
+                        connection_id, correlation_id, request_at, None, None,
+                        "error", f"{type(tc_err).__name__}: {tc_err}",
+                    )
+                    raise tc_err
+
+                emit_event(
+                    on_lifecycle_event,
+                    OnFallbackEvent(
+                        kind="on_fallback",
+                        provider="anthropic",
+                        model=str(model),
+                        operation="messages",
+                        attempt_number=1,
+                        elapsed_ms=0.0,
+                        consecutive_failures=circuit.failures if circuit else 0,
+                    ),
+                )
+                try:
+                    direct_response = bound_method(*args, **kwargs)
+                    input_tokens, output_tokens = _extract_usage(direct_response)
+                    _post_obs(
+                        transport, str(model), tenant_id, environment,
+                        connection_id, correlation_id, request_at, input_tokens,
+                        output_tokens, "success", None,
+                    )
+                    return direct_response
+                except Exception as exc:
+                    _post_obs(
+                        transport, str(model), tenant_id, environment,
+                        connection_id, correlation_id, request_at, None, None,
+                        "error", f"{type(exc).__name__}: {exc}",
+                    )
+                    raise
+
+            # Proxy success.
+            resp_dict = proxy_result if isinstance(proxy_result, dict) else {}
+            usage = resp_dict.get("usage") if isinstance(resp_dict, dict) else None
+            input_tokens = usage.get("input_tokens") if isinstance(usage, dict) else None
+            output_tokens = usage.get("output_tokens") if isinstance(usage, dict) else None
+            _post_obs(
+                transport, str(model), tenant_id, environment,
+                connection_id, correlation_id, request_at, input_tokens,
+                output_tokens, "success", None,
+            )
+            return proxy_result
+
+        # Observe-only path.
+        try:
+            response = bound_method(*args, **kwargs)
+        except Exception as exc:
+            _post_obs(
+                transport, str(model), tenant_id, environment,
+                connection_id, correlation_id, request_at, None, None,
+                "error", f"{type(exc).__name__}: {exc}",
+            )
+            raise
+
+        input_tokens, output_tokens = _extract_usage(response)
+        _post_obs(
+            transport, str(model), tenant_id, environment,
+            connection_id, correlation_id, request_at, input_tokens,
+            output_tokens, "success", None,
+        )
+        return response
+
+    setattr(wrapper, "__tensorcost_wrapped__", True)
+    return wrapper
+
+
+def install(
+    client: Any,
+    transport: ObservationTransport,
+    tenant_id: str | None,
+    environment: str | None,
+    connection_id: str | None,
+    applied_mode: bool = False,
+    proxy_url: Optional[str] = None,
+    retry: RetryConfig = DEFAULT_RETRY_CONFIG,
+    timeout_s: float = 60.0,
+    on_lifecycle_event: Optional[LifecycleEventCallback] = None,
+    fail_open_enabled: bool = True,
+    circuit: Optional[CircuitBreaker] = None,
+) -> None:
+    """Monkey-patch ``client.messages.create`` in place."""
+    messages = getattr(client, "messages", None)
+    if messages is None or not callable(getattr(messages, "create", None)):
+        return
+    original = messages.create
+    if getattr(original, "__tensorcost_wrapped__", False):
+        return
+    messages.create = _wrap_method(
+        original,
+        transport=transport,
+        tenant_id=tenant_id,
+        environment=environment,
+        connection_id=connection_id,
+        applied_mode=applied_mode,
+        proxy_url=proxy_url,
+        client_ref=client,
+        retry=retry,
+        timeout_s=timeout_s,
+        on_lifecycle_event=on_lifecycle_event,
+        fail_open_enabled=fail_open_enabled,
+        circuit=circuit,
+    )

tensorcost/_providers/_detect.py

@@ -0,0 +1,46 @@
+"""Provider detection via duck-typing.
+
+We deliberately avoid ``isinstance`` checks against the OpenAI /
+Anthropic SDK classes so that the SDK has zero hard imports of those
+packages. A customer who uses only OpenAI shouldn't need ``anthropic``
+installed (and vice versa).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class UnsupportedClientError(TypeError):
+    """Raised by :func:`detect_provider` when the client shape is not
+    recognized as either an OpenAI or Anthropic client."""
+
+
+def _looks_like_openai(client: Any) -> bool:
+    chat = getattr(client, "chat", None)
+    completions = getattr(chat, "completions", None) if chat is not None else None
+    return callable(getattr(completions, "create", None))
+
+
+def _looks_like_anthropic(client: Any) -> bool:
+    # Anthropic clients expose ``client.messages.create``; we additionally
+    # require the *absence* of ``client.chat`` to disambiguate from OpenAI.
+    if getattr(client, "chat", None) is not None:
+        return False
+    messages = getattr(client, "messages", None)
+    return callable(getattr(messages, "create", None))
+
+
+def detect_provider(client: Any) -> str:
+    """Return ``"openai"`` or ``"anthropic"`` based on duck-typing.
+
+    Raises :class:`UnsupportedClientError` if neither shape matches.
+    """
+    if _looks_like_openai(client):
+        return "openai"
+    if _looks_like_anthropic(client):
+        return "anthropic"
+    raise UnsupportedClientError(
+        "tensorcost.wrap(): client does not look like an OpenAI or Anthropic "
+        "client. Supported in v0.1.0: openai>=1.0, anthropic>=0.20."
+    )

tensorcost/_providers/_openai.py

@@ -0,0 +1,295 @@
+"""OpenAI client wrapping.
+
+Intercepts:
+  * ``client.chat.completions.create``
+  * ``client.completions.create`` (legacy text completions; v0 still ships)
+
+We capture only metadata (model, message count, token usage) — never
+prompt content. Customers' prompts stay on their machine.
+
+Applied-mode hardening (v0.4.0): chat/completions calls route through the
+proxy-client module, which handles retries, timeouts, typed errors,
+telemetry hooks, and the fail-open circuit breaker.
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from .._applied_mode import (
+    openai_provider_auth,
+    openai_provider_base_url,
+)
+from .._circuit import CircuitBreaker
+from .._errors import TensorCostProxyError
+from .._models import Observation
+from .._proxy_client import proxy_request
+from .._retry import DEFAULT_RETRY_CONFIG, RetryConfig
+from .._telemetry import LifecycleEventCallback, OnFallbackEvent, emit_event
+from .._transport import ObservationTransport
+
+_SDK_VERSION = "tensorcost-python/0.4.0"
+_log = logging.getLogger("tensorcost")
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _extract_usage(response: Any) -> tuple[int | None, int | None]:
+    usage = getattr(response, "usage", None)
+    if usage is None and isinstance(response, dict):
+        usage = response.get("usage")
+    if usage is None:
+        return None, None
+    if isinstance(usage, dict):
+        return usage.get("prompt_tokens"), usage.get("completion_tokens")
+    return (
+        getattr(usage, "prompt_tokens", None),
+        getattr(usage, "completion_tokens", None),
+    )
+
+
+def _post_obs(
+    transport: ObservationTransport,
+    model: str,
+    operation: str,
+    tenant_id: str | None,
+    environment: str | None,
+    connection_id: str | None,
+    correlation_id: str,
+    request_at: str,
+    input_tokens: int | None,
+    output_tokens: int | None,
+    status: str,
+    error_message: str | None,
+) -> None:
+    obs: dict = {
+        "sdk_version": _SDK_VERSION,
+        "provider": "openai",
+        "model": model,
+        "operation": operation,
+        "request_at": request_at,
+        "response_at": _now_iso(),
+        "input_tokens": input_tokens,
+        "output_tokens": output_tokens,
+        "cost_usd_cents": None,
+        "status": status,
+        "error_message": error_message,
+        "correlation_id": correlation_id,
+        "tenant_id": tenant_id,
+        **({"environment": environment} if environment is not None else {}),
+        **({"connection_id": connection_id} if connection_id is not None else {}),
+    }
+    try:
+        transport.post(obs)
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def _wrap_method(
+    bound_method: Any,
+    *,
+    operation: str,
+    transport: ObservationTransport,
+    tenant_id: str | None,
+    environment: str | None,
+    connection_id: str | None,
+    applied_mode: bool = False,
+    proxy_url: Optional[str] = None,
+    client_ref: Optional[Any] = None,
+    retry: RetryConfig = DEFAULT_RETRY_CONFIG,
+    timeout_s: float = 60.0,
+    on_lifecycle_event: Optional[LifecycleEventCallback] = None,
+    fail_open_enabled: bool = True,
+    circuit: Optional[CircuitBreaker] = None,
+) -> Any:
+    @functools.wraps(bound_method)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        request_at = _now_iso()
+        model = kwargs.get("model") or (args[0] if args else "unknown")
+        correlation_id = str(uuid.uuid4())
+
+        # Applied-mode path: route chat/completions through the proxy-client.
+        if applied_mode and proxy_url and operation == "chat.completions":
+            provider_url = openai_provider_base_url(client_ref) if client_ref else "https://api.openai.com"
+            provider_auth = openai_provider_auth(client_ref) if client_ref else ""
+
+            body: dict[str, Any] = dict(kwargs)
+            body["model"] = str(model)
+
+            circuit_was_open = circuit is not None and circuit.should_bypass()
+            proxy_failed = False
+            proxy_error: Optional[Exception] = None
+            proxy_result: Optional[Any] = None
+
+            if not circuit_was_open:
+                try:
+                    bearer_token = transport._get_token()
+                    proxy_result = proxy_request(
+                        proxy_url=proxy_url,
+                        bearer_token=bearer_token,
+                        provider_url=provider_url,
+                        provider_auth=provider_auth,
+                        body=body,
+                        model=str(model),
+                        provider="openai",
+                        operation=operation,
+                        correlation_id=correlation_id,
+                        environment=environment,
+                        retry=retry,
+                        timeout_s=timeout_s,
+                        on_lifecycle_event=on_lifecycle_event,
+                        circuit=circuit,
+                    )
+                except Exception as exc:  # noqa: BLE001
+                    proxy_failed = True
+                    proxy_error = exc
+            else:
+                proxy_failed = True
+
+            if proxy_failed or circuit_was_open:
+                if not fail_open_enabled:
+                    tc_err = (
+                        proxy_error
+                        if isinstance(proxy_error, TensorCostProxyError)
+                        else TensorCostProxyError(
+                            str(proxy_error) if proxy_error else "proxy unavailable",
+                            root_cause=proxy_error if isinstance(proxy_error, Exception) else None,
+                            attempt=1,
+                        )
+                    )
+                    _post_obs(
+                        transport, str(model), operation, tenant_id, environment,
+                        connection_id, correlation_id, request_at, None, None,
+                        "error", f"{type(tc_err).__name__}: {tc_err}",
+                    )
+                    raise tc_err
+
+                # Fail-open: emit fallback event and call provider directly.
+                emit_event(
+                    on_lifecycle_event,
+                    OnFallbackEvent(
+                        kind="on_fallback",
+                        provider="openai",
+                        model=str(model),
+                        operation=operation,
+                        attempt_number=1,
+                        elapsed_ms=0.0,
+                        consecutive_failures=circuit.failures if circuit else 0,
+                    ),
+                )
+                try:
+                    direct_response = bound_method(*args, **kwargs)
+                    input_tokens, output_tokens = _extract_usage(direct_response)
+                    _post_obs(
+                        transport, str(model), operation, tenant_id, environment,
+                        connection_id, correlation_id, request_at, input_tokens,
+                        output_tokens, "success", None,
+                    )
+                    return direct_response
+                except Exception as exc:
+                    _post_obs(
+                        transport, str(model), operation, tenant_id, environment,
+                        connection_id, correlation_id, request_at, None, None,
+                        "error", f"{type(exc).__name__}: {exc}",
+                    )
+                    raise
+
+            # Proxy success.
+            resp_dict = proxy_result if isinstance(proxy_result, dict) else {}
+            usage = resp_dict.get("usage") if isinstance(resp_dict, dict) else None
+            input_tokens = usage.get("prompt_tokens") if isinstance(usage, dict) else None
+            output_tokens = usage.get("completion_tokens") if isinstance(usage, dict) else None
+            _post_obs(
+                transport, str(model), operation, tenant_id, environment,
+                connection_id, correlation_id, request_at, input_tokens,
+                output_tokens, "success", None,
+            )
+            return proxy_result
+
+        # Observe-only path (applied_mode=False or non-chat operation).
+        try:
+            response = bound_method(*args, **kwargs)
+        except Exception as exc:
+            _post_obs(
+                transport, str(model), operation, tenant_id, environment,
+                connection_id, correlation_id, request_at, None, None,
+                "error", f"{type(exc).__name__}: {exc}",
+            )
+            raise
+
+        input_tokens, output_tokens = _extract_usage(response)
+        _post_obs(
+            transport, str(model), operation, tenant_id, environment,
+            connection_id, correlation_id, request_at, input_tokens,
+            output_tokens, "success", None,
+        )
+        return response
+
+    setattr(wrapper, "__tensorcost_wrapped__", True)
+    return wrapper
+
+
+def install(
+    client: Any,
+    transport: ObservationTransport,
+    tenant_id: str | None,
+    environment: str | None,
+    connection_id: str | None,
+    applied_mode: bool = False,
+    proxy_url: Optional[str] = None,
+    retry: RetryConfig = DEFAULT_RETRY_CONFIG,
+    timeout_s: float = 60.0,
+    on_lifecycle_event: Optional[LifecycleEventCallback] = None,
+    fail_open_enabled: bool = True,
+    circuit: Optional[CircuitBreaker] = None,
+) -> None:
+    """Monkey-patch the OpenAI client's ``create`` methods in place."""
+    chat = getattr(client, "chat", None)
+    completions = getattr(chat, "completions", None) if chat is not None else None
+    if completions is not None and callable(getattr(completions, "create", None)):
+        original = completions.create
+        if not getattr(original, "__tensorcost_wrapped__", False):
+            completions.create = _wrap_method(
+                original,
+                operation="chat.completions",
+                transport=transport,
+                tenant_id=tenant_id,
+                environment=environment,
+                connection_id=connection_id,
+                applied_mode=applied_mode,
+                proxy_url=proxy_url,
+                client_ref=client,
+                retry=retry,
+                timeout_s=timeout_s,
+                on_lifecycle_event=on_lifecycle_event,
+                fail_open_enabled=fail_open_enabled,
+                circuit=circuit,
+            )
+
+    legacy = getattr(client, "completions", None)
+    if legacy is not None and callable(getattr(legacy, "create", None)):
+        original = legacy.create
+        if not getattr(original, "__tensorcost_wrapped__", False):
+            legacy.create = _wrap_method(
+                original,
+                operation="completions",
+                transport=transport,
+                tenant_id=tenant_id,
+                environment=environment,
+                connection_id=connection_id,
+                # Legacy completions endpoint not in scope for applied-mode v1.
+                applied_mode=False,
+                proxy_url=None,
+                client_ref=client,
+                retry=retry,
+                timeout_s=timeout_s,
+                on_lifecycle_event=on_lifecycle_event,
+                fail_open_enabled=fail_open_enabled,
+                circuit=circuit,
+            )