tensorcost 1.3.2__tar.gz → 1.4.0__tar.gz

{tensorcost-1.3.2 → tensorcost-1.4.0}/CHANGELOG.md

@@ -3,7 +3,17 @@
 All notable changes to the `tensorcost` Python SDK are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
-## Unreleased
+## 1.4.0 — 2026-10-25
+
+### Added
+
+**`TensorCostRunStoppedError`** — maps proxy `403` / `RUN_STOPPED` (an operator
+stopped the agent run), on the applied-mode chat path and on the govern-layer
+`/v1/admit`. Carries `workflow_id`, `stopped_by`, `stopped_at` and `reason`.
+Terminal: `should_fall_back_to_provider()` returns False for it, so with
+`fail_open_enabled` (the default) a stopped run no longer goes to the
+provider directly. Before this, the 403 surfaced as a generic provider error
+and fail-open called the provider anyway.
 
 ## 1.3.0 — 2026-09-26
 

{tensorcost-1.3.2 → tensorcost-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tensorcost
-Version: 1.3.2
+Version: 1.4.0
 Summary: One-line wrapper SDK for TensorCost — LLM observability and control-layer inference routing for OpenAI, Anthropic, Bedrock, and Vertex clients.
 Project-URL: Homepage, https://tensorcost.com
 Project-URL: Documentation, https://docs.tensorcost.com

{tensorcost-1.3.2 → tensorcost-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tensorcost"
-version = "1.3.2"
+version = "1.4.0"
 description = "One-line wrapper SDK for TensorCost — LLM observability and control-layer inference routing for OpenAI, Anthropic, Bedrock, and Vertex clients."
 readme = "README.md"
 requires-python = ">=3.9"

{tensorcost-1.3.2 → tensorcost-1.4.0}/src/tensorcost/__init__.py

@@ -29,6 +29,7 @@ from ._errors import (
     TensorCostQuotaError,
     TensorCostProviderError,
     TensorCostRunBudgetExceededError,
+    TensorCostRunStoppedError,
     TensorCostPeriodBudgetExceededError,
     TensorCostComplianceDeniedError,
     TensorCostComplianceTeamMismatchError,
@@ -44,7 +45,7 @@ from ._telemetry import (
 )
 from ._retry import RetryConfig
 
-__version__ = "1.3.0"
+__version__ = "1.4.0"
 __all__ = [
     "wrap",
     "prewarm",
@@ -59,6 +60,7 @@ __all__ = [
     "TensorCostQuotaError",
     "TensorCostProviderError",
     "TensorCostRunBudgetExceededError",
+    "TensorCostRunStoppedError",
     "TensorCostPeriodBudgetExceededError",
     "TensorCostComplianceDeniedError",
     "TensorCostComplianceTeamMismatchError",

{tensorcost-1.3.2 → tensorcost-1.4.0}/src/tensorcost/_admit_client.py

@@ -1,4 +1,9 @@
-"""Govern-layer admit — metadata-only POST /api/inference-proxy/v1/admit."""
+"""Govern-layer admit — metadata-only POST /api/inference-proxy/v1/admit.
+
+Fail-open on transport errors. A 403 is a refusal, never a transport error;
+when its body says RUN_STOPPED this raises TensorCostRunStoppedError so the
+caller gets who stopped the run and why instead of a generic govern refusal.
+"""
 
 from __future__ import annotations
 
@@ -7,6 +12,7 @@ from typing import Any, Callable, Optional
 
 import httpx
 
+from ._errors import TensorCostRunStoppedError
 from ._layer import ADMIT_PATH, ADMIT_TIMEOUT_S, ControlLayer
 from ._transport import ObservationTransport
 from ._version import SDK_VERSION, sdk_capability_header
@@ -27,7 +33,10 @@ def admit_request(
     timeout_s: float = ADMIT_TIMEOUT_S,
     http_client: Optional[httpx.Client] = None,
 ) -> tuple[bool, Optional[str]]:
-    """Returns (allowed, decision_header). Fail-open on transport errors."""
+    """Returns (allowed, decision_header). Fail-open on transport errors.
+
+    Raises TensorCostRunStoppedError for a RUN_STOPPED 403.
+    """
     url = base_url.rstrip("/") + ADMIT_PATH
     headers = {
         "Authorization": f"Bearer {bearer_token}",
@@ -39,18 +48,23 @@ def admit_request(
 
     own_client = http_client is None
     client = http_client or httpx.Client(timeout=timeout_s)
+    # Raised after the try below: inside it, fail-open would swallow it.
+    stopped: Optional[TensorCostRunStoppedError] = None
     try:
         resp = client.post(url, headers=headers, json=metadata)
         decision_header = resp.headers.get("x-tc-decision")
         if resp.status_code == 403:
-            return False, decision_header
-        if resp.status_code >= 400:
+            stopped = _run_stopped_from(resp)
+            if stopped is None:
+                return False, decision_header
+        elif resp.status_code >= 400:
             raise httpx.HTTPStatusError(
                 f"admit POST failed status={resp.status_code}",
                 request=resp.request,
                 response=resp,
             )
-        return True, decision_header
+        else:
+            return True, decision_header
     except Exception as exc:
         if fail_open:
             if transport is not None:
@@ -82,3 +96,18 @@ def admit_request(
     finally:
         if own_client:
             client.close()
+    assert stopped is not None
+    raise stopped
+
+
+def _run_stopped_from(resp: httpx.Response) -> Optional[TensorCostRunStoppedError]:
+    try:
+        body = resp.json()
+    except Exception:
+        return None
+    err = body.get("error") if isinstance(body, dict) else None
+    if isinstance(err, dict) and err.get("code") == "RUN_STOPPED":
+        return TensorCostRunStoppedError.from_proxy_detail(
+            err, request_id=resp.headers.get("x-tc-request-id")
+        )
+    return None

{tensorcost-1.3.2 → tensorcost-1.4.0}/src/tensorcost/_errors.py

@@ -152,6 +152,65 @@ class TensorCostRunBudgetExceededError(TensorCostError):
         self.spent_cents = spent_cents
 
 
+class TensorCostRunStoppedError(TensorCostError):
+    """An operator stopped this agent run (HTTP 403, ``code: RUN_STOPPED``).
+
+    Terminal for the same reason as the budget refusals: the stop comes from
+    a healthy proxy, so falling back to the provider would undo it. Carries
+    the who / when / why the proxy recorded.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        workflow_id: Optional[str] = None,
+        stopped_by: Optional[str] = None,
+        stopped_at: Optional[str] = None,
+        reason: Optional[str] = None,
+        *,
+        root_cause: Optional[Exception] = None,
+        status: int = 403,
+        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.workflow_id = workflow_id
+        self.stopped_by = stopped_by
+        self.stopped_at = stopped_at
+        self.reason = reason
+
+    @classmethod
+    def from_proxy_detail(
+        cls,
+        detail: dict,
+        *,
+        request_id: Optional[str] = None,
+        attempt: int = 1,
+    ) -> "TensorCostRunStoppedError":
+        """Build from the proxy's 403 ``error`` object (chat path and /admit)."""
+
+        def _s(key: str) -> Optional[str]:
+            v = detail.get(key)
+            return v if isinstance(v, str) else None
+
+        return cls(
+            _s("message") or "tensorcost: agent run was stopped",
+            workflow_id=_s("workflow_id"),
+            stopped_by=_s("stopped_by"),
+            stopped_at=_s("stopped_at"),
+            reason=_s("reason"),
+            status=403,
+            request_id=request_id,
+            attempt=attempt,
+        )
+
+
 class TensorCostPeriodBudgetExceededError(TensorCostError):
     """Daily/monthly agent or team cap reached (HTTP 403,
     ``code: PERIOD_BUDGET_EXCEEDED``). Terminal — must not fail-open.

{tensorcost-1.3.2 → tensorcost-1.4.0}/src/tensorcost/_proxy_client.py

@@ -34,6 +34,7 @@ from ._errors import (
     TensorCostQuotaError,
     TensorCostPeriodBudgetExceededError,
     TensorCostRunBudgetExceededError,
+    TensorCostRunStoppedError,
     TensorCostTimeoutError,
 )
 from ._retry import (
@@ -583,6 +584,10 @@ def _terminal_proxy_refusal_error(
 ) -> Optional[BaseException]:
     """Map a 403 proxy body to a terminal refusal error, or None if not ours."""
     code, detail = _extract_proxy_refusal_code(content)
+    if code == "RUN_STOPPED":
+        return TensorCostRunStoppedError.from_proxy_detail(
+            detail, request_id=request_id, attempt=attempt
+        )
     if code in ("RUN_BUDGET_EXCEEDED", "PERIOD_BUDGET_EXCEEDED"):
         if code == "PERIOD_BUDGET_EXCEEDED":
             return TensorCostPeriodBudgetExceededError(
@@ -797,6 +802,7 @@ def should_fall_back_to_provider(err: BaseException) -> bool:
         err,
         (
             TensorCostRunBudgetExceededError,
+            TensorCostRunStoppedError,
             TensorCostPeriodBudgetExceededError,
             TensorCostModelGovernanceDeniedError,
             TensorCostGuardrailHardStopError,

{tensorcost-1.3.2 → tensorcost-1.4.0}/src/tensorcost/_version.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-SDK_VERSION = "tensorcost-python/1.3.0"
+SDK_VERSION = "tensorcost-python/1.4.0"
 
 # Advertise only capabilities this build implements (non-streaming v1).
 SDK_CAPABILITIES: tuple[str, ...] = ("refusal-v1",)

{tensorcost-1.3.2 → tensorcost-1.4.0}/tests/test_providers/test_anthropic.py

@@ -36,7 +36,7 @@ def test_messages_observation_shape(anthropic_client, recording_transport):
     assert obs["input_tokens"] == 21
     assert obs["output_tokens"] == 43
     assert "tenant_id" not in obs
-    assert obs["sdk_version"] == "tensorcost-python/1.3.0"
+    assert obs["sdk_version"] == "tensorcost-python/1.4.0"
     assert obs["correlation_id"]
     assert "connection_id" not in obs
 

{tensorcost-1.3.2 → tensorcost-1.4.0}/tests/test_providers/test_bedrock.py

@@ -34,7 +34,7 @@ def test_invoke_model_anthropic_shape_observation(bedrock_client, recording_tran
     assert obs["input_tokens"] == 15
     assert obs["output_tokens"] == 30
     assert "tenant_id" not in obs
-    assert obs["sdk_version"] == "tensorcost-python/1.3.0"
+    assert obs["sdk_version"] == "tensorcost-python/1.4.0"
     assert obs["correlation_id"]
     assert "connection_id" not in obs
 

{tensorcost-1.3.2 → tensorcost-1.4.0}/tests/test_providers/test_openai.py

@@ -33,7 +33,7 @@ def test_chat_completions_observation_shape(openai_client, recording_transport):
     assert obs["input_tokens"] == 12
     assert obs["output_tokens"] == 34
     assert "tenant_id" not in obs
-    assert obs["sdk_version"] == "tensorcost-python/1.3.0"
+    assert obs["sdk_version"] == "tensorcost-python/1.4.0"
     # Phase A4 batch 4 — connection_id absent when wrap() got no
     # connection_id; backend then resolves env via the SDK envelope's
     # `environment` field or falls back to 'production'.

{tensorcost-1.3.2 → tensorcost-1.4.0}/tests/test_providers/test_vertex.py

@@ -27,7 +27,7 @@ def test_generate_content_observation_shape(vertex_client, recording_transport):
     assert obs["status"] == "success"
     assert obs["input_tokens"] == 42
     assert obs["output_tokens"] == 17
-    assert obs["sdk_version"] == "tensorcost-python/1.3.0"
+    assert obs["sdk_version"] == "tensorcost-python/1.4.0"
     assert obs["correlation_id"]
 
 

tensorcost-1.4.0/tests/test_run_stopped.py

@@ -0,0 +1,157 @@
+"""An operator stop is terminal in the Python SDK.
+
+The proxy answers a stopped run with 403 RUN_STOPPED, on the chat path and on
+the govern-layer /v1/admit. Before these tests the SDK did not know the code:
+on the chat path the 403 became a generic TensorCostProviderError, which
+should_fall_back_to_provider() allows, so with fail_open_enabled (the default)
+the wrapper called the provider directly and the stop did nothing. On /admit
+the refusal lost who stopped the run and why.
+"""
+
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+
+from tensorcost import TensorCostRunStoppedError
+from tensorcost._admit_client import admit_request
+from tensorcost._errors import TensorCostProviderError
+from tensorcost._proxy_client import (
+    _terminal_proxy_refusal_error,
+    proxy_request,
+    should_fall_back_to_provider,
+)
+from tensorcost._retry import RetryConfig
+
+STOPPED_BODY = {
+    "error": {
+        "code": "RUN_STOPPED",
+        "message": "Agent run run-abc was stopped by ops@example.test at 2026-10-25T10:00:00.000Z: runaway",
+        "workflow_id": "run-abc",
+        "stopped_by": "ops@example.test",
+        "stopped_at": "2026-10-25T10:00:00.000Z",
+        "reason": "runaway",
+    }
+}
+
+
+def _resp(status: int, body, headers: dict | None = None) -> httpx.Response:
+    content = body if isinstance(body, bytes) else json.dumps(body).encode()
+    return httpx.Response(
+        status_code=status,
+        headers={"Content-Type": "application/json", **(headers or {})},
+        content=content,
+    )
+
+
+def _client(handler) -> httpx.Client:
+    return httpx.Client(transport=httpx.MockTransport(handler))
+
+
+def _assert_stop_detail(err: TensorCostRunStoppedError) -> None:
+    assert err.workflow_id == "run-abc"
+    assert err.stopped_by == "ops@example.test"
+    assert err.stopped_at == "2026-10-25T10:00:00.000Z"
+    assert err.reason == "runaway"
+    assert err.status == 403
+
+
+def test_terminal_refusal_maps_run_stopped_with_its_detail():
+    err = _terminal_proxy_refusal_error(
+        json.dumps(STOPPED_BODY).encode(), request_id="req-1", attempt=2
+    )
+    assert isinstance(err, TensorCostRunStoppedError)
+    _assert_stop_detail(err)
+    assert err.request_id == "req-1"
+    assert err.attempt == 2
+
+
+def test_run_stopped_does_not_fall_back_to_provider():
+    assert should_fall_back_to_provider(TensorCostRunStoppedError("stopped")) is False
+
+
+def test_proxy_request_raises_run_stopped_and_does_not_retry():
+    calls = [0]
+
+    def handler(_req: httpx.Request) -> httpx.Response:
+        calls[0] += 1
+        return _resp(403, STOPPED_BODY)
+
+    with pytest.raises(TensorCostRunStoppedError) as info:
+        proxy_request(
+            proxy_url="https://proxy.example.com",
+            bearer_token="jwt",
+            provider_url="https://api.openai.com",
+            provider_auth="Bearer sk-test",
+            body={"model": "gpt-4o-mini", "messages": []},
+            model="gpt-4o-mini",
+            provider="openai",
+            operation="chat.completions",
+            correlation_id="c-1",
+            environment=None,
+            retry=RetryConfig(max_attempts=3),
+            http_client=_client(handler),
+        )
+    _assert_stop_detail(info.value)
+    assert calls[0] == 1
+
+
+def _admit(handler, **kw):
+    return admit_request(
+        base_url="https://proxy.example.com",
+        bearer_token="jwt",
+        max_layer="govern",
+        metadata={"provider": "openai", "model": "gpt-4o-mini", "workflow_id": "run-abc"},
+        http_client=_client(handler),
+        **kw,
+    )
+
+
+def test_admit_raises_run_stopped_even_with_fail_open():
+    with pytest.raises(TensorCostRunStoppedError) as info:
+        _admit(lambda _r: _resp(403, STOPPED_BODY, {"x-tc-request-id": "req-9"}), fail_open=True)
+    _assert_stop_detail(info.value)
+    assert info.value.request_id == "req-9"
+
+
+def test_admit_other_403_is_still_a_plain_refusal():
+    allowed, header = _admit(
+        lambda _r: _resp(
+            403,
+            {"error": {"code": "MODEL_GOVERNANCE_DENIED"}},
+            {"x-tc-decision": "layer=govern; action=refuse"},
+        )
+    )
+    assert allowed is False
+    assert header == "layer=govern; action=refuse"
+
+
+def test_admit_403_with_non_json_body_is_a_plain_refusal():
+    allowed, _ = _admit(lambda _r: _resp(403, b"<html>403</html>"))
+    assert allowed is False
+
+
+def test_admit_still_fails_open_on_transport_error_and_5xx():
+    def boom(_r):
+        raise httpx.ConnectError("refused")
+
+    assert _admit(boom) == (True, None)
+    assert _admit(lambda _r: _resp(503, {})) == (True, None)
+    assert _admit(lambda _r: _resp(204, b"", {"x-tc-decision": "action=allow"}))[0] is True
+
+
+def test_admit_5xx_raises_when_fail_open_is_off():
+    with pytest.raises(httpx.HTTPStatusError):
+        _admit(lambda _r: _resp(503, {}), fail_open=False)
+
+
+def test_unrelated_403_on_the_chat_path_stays_a_provider_error():
+    assert (
+        _terminal_proxy_refusal_error(
+            json.dumps({"error": {"code": "FORBIDDEN"}}).encode(), request_id=None, attempt=1
+        )
+        is None
+    )
+    assert should_fall_back_to_provider(TensorCostProviderError("403")) is True

{tensorcost-1.3.2 → tensorcost-1.4.0}/tests/test_wrap.py

@@ -5,7 +5,7 @@ from tensorcost._providers._detect import UnsupportedClientError
 
 
 def test_version_string():
-    assert __version__ == "1.3.0"
+    assert __version__ == "1.4.0"
 
 
 def test_wrap_returns_same_object(openai_client):