spendwall 0.0.6__py3-none-any.whl

spendwall/__init__.py

@@ -0,0 +1,11 @@
+"""Spendwall — local-first agent spending firewall."""
+__version__ = "0.0.2"
+
+from spendwall.client import SpendwallClient  # noqa: F401
+from spendwall.errors import (  # noqa: F401
+    ApprovalRequiredError,
+    BlockedError,
+    SpendwallError,
+    SpendwallVersionMismatch,
+)
+from spendwall.modes import Mode  # noqa: F401

spendwall/anthropic.py

@@ -0,0 +1,88 @@
+"""Wrapper for ``anthropic.Anthropic`` clients.
+
+Patches ``client.messages.create`` in-place so every upstream call is
+observed by spendwalld. In ``enforce`` mode, the wrapper consults policy
+*before* dispatching to the upstream and raises
+``BlockedError``/``ApprovalRequiredError`` when the daemon refuses.
+"""
+
+from __future__ import annotations
+
+import json as _json
+from typing import Any, Optional
+
+from spendwall.client import SpendwallClient
+from spendwall.modes import Mode, resolve as resolve_mode
+
+
+def _estimate_tokens(messages_or_input: Any) -> int:
+    try:
+        return max(1, len(_json.dumps(messages_or_input)) // 4)
+    except (TypeError, ValueError):
+        return 1
+
+
+def wrap(
+    anthropic_client: Any,
+    *,
+    sw_client: Optional[SpendwallClient] = None,
+    agent_id: str = "anonymous",
+    mode: Optional[Mode] = None,
+    tags: Optional[dict[str, str]] = None,
+) -> Any:
+    """Patch ``anthropic_client.messages.create`` to call into spendwall
+    before/after the upstream request.
+
+    Mutates the supplied client in-place AND returns it for ergonomic chaining:
+
+        client = wrap(anthropic.Anthropic(...), agent_id="x")
+    """
+    sw = sw_client or SpendwallClient()
+    configured_mode = mode
+
+    original = anthropic_client.messages.create
+
+    def patched(*args: Any, **kwargs: Any) -> Any:
+        call_mode = resolve_mode(configured=configured_mode)
+        model = kwargs.get("model", "unknown")
+        est_input_tokens = _estimate_tokens(kwargs.get("messages"))
+
+        if call_mode == "enforce":
+            sw.policy_check_strict(
+                agent_id=agent_id, provider="anthropic", model=model,
+                estimated_cost_cents=0, tags=tags or {},
+            )
+        elif call_mode == "advisory":
+            sw.policy_check(
+                agent_id=agent_id, provider="anthropic", model=model,
+                estimated_cost_cents=0, tags=tags or {},
+            )
+        # observe-mode skips policy_check entirely.
+        try:
+            result = original(*args, **kwargs)
+        except Exception:
+            sw.observe({
+                "agent_id": agent_id, "provider": "anthropic", "model": model,
+                "source": "sdk_python", "input_tokens": est_input_tokens,
+                "output_tokens": None, "estimated_cost_cents": 0,
+                "actual_cost_cents": None, "decision_str": "allowed",
+                "binding_caps": [], "tags": tags or {},
+                "outcome": "upstream_error",
+            })
+            raise
+
+        usage = getattr(result, "usage", None)
+        input_tokens = getattr(usage, "input_tokens", None) if usage else None
+        output_tokens = getattr(usage, "output_tokens", None) if usage else None
+        sw.observe({
+            "agent_id": agent_id, "provider": "anthropic", "model": model,
+            "source": "sdk_python", "input_tokens": input_tokens,
+            "output_tokens": output_tokens, "estimated_cost_cents": 0,
+            "actual_cost_cents": None, "decision_str": "allowed",
+            "binding_caps": [], "tags": tags or {},
+            "outcome": "success",
+        })
+        return result
+
+    anthropic_client.messages.create = patched
+    return anthropic_client

spendwall/client.py

@@ -0,0 +1,118 @@
+"""UDS HTTP client for spendwalld."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+from urllib.parse import quote
+
+import requests
+import requests_unixsocket
+
+from spendwall.errors import ApprovalRequiredError, BlockedError
+
+
+def _default_socket_path() -> str:
+    return os.environ.get(
+        "SPENDWALL_SOCKET",
+        os.path.expanduser("~/.spendwall/spendwall.sock"),
+    )
+
+
+def _default_bearer() -> Optional[str]:
+    return os.environ.get("SPENDWALL_TOKEN")
+
+
+class SpendwallClient:
+    """Talks to the spendwall daemon over its UDS HTTP API.
+
+    Fail-open: when ``fail_open=True`` and the socket is unreachable, ``observe()``
+    is silently dropped and ``policy_check()`` returns a synthetic "allowed"
+    decision. Default is ``fail_open=True`` because a spending firewall MUST NOT
+    bring down user agents when the daemon is down.
+    """
+
+    def __init__(
+        self,
+        socket_path: Optional[str] = None,
+        bearer: Optional[str] = None,
+        timeout_seconds: float = 2.0,
+        fail_open: bool = True,
+    ):
+        self.socket_path = socket_path or _default_socket_path()
+        self.bearer = bearer or _default_bearer()
+        self.timeout_seconds = timeout_seconds
+        self.fail_open = fail_open
+        self._session = requests_unixsocket.Session()
+        self._base = f"http+unix://{quote(self.socket_path, safe='')}"
+
+    def _headers(self) -> dict[str, str]:
+        h = {"content-type": "application/json"}
+        if self.bearer:
+            h["authorization"] = f"Bearer {self.bearer}"
+        return h
+
+    def policy_check(
+        self,
+        *,
+        agent_id: str,
+        provider: str,
+        model: str,
+        estimated_cost_cents: int,
+        tags: Optional[dict[str, str]] = None,
+    ) -> dict[str, Any]:
+        body = {
+            "agent_id": agent_id,
+            "provider": provider,
+            "model": model,
+            "estimated_cost_cents": estimated_cost_cents,
+            "tags": tags or {},
+        }
+        try:
+            r = self._session.post(
+                f"{self._base}/v1/policy/check",
+                json=body,
+                headers=self._headers(),
+                timeout=self.timeout_seconds,
+            )
+            r.raise_for_status()
+            return r.json()
+        except (requests.RequestException, ValueError):
+            if self.fail_open:
+                return {"decision": "allowed", "alert_caps": []}
+            raise
+
+    def policy_check_strict(self, **kwargs: Any) -> dict[str, Any]:
+        """Like ``policy_check`` but raises ``BlockedError`` /
+        ``ApprovalRequiredError`` on non-allowed decisions."""
+        d = self.policy_check(**kwargs)
+        if d.get("decision") == "blocked":
+            raise BlockedError(
+                cap_id=d.get("cap_id", "?"),
+                projected_cents=d.get("projected_cents", 0),
+                limit_cents=d.get("limit_cents", 0),
+            )
+        if d.get("decision") == "approval_required":
+            raise ApprovalRequiredError(approval_caps=d.get("approval_caps", []))
+        return d
+
+    def observe(self, event: dict[str, Any]) -> None:
+        try:
+            self._session.post(
+                f"{self._base}/v1/spend/observe",
+                json=event,
+                headers=self._headers(),
+                timeout=self.timeout_seconds,
+            )
+        except requests.RequestException:
+            if not self.fail_open:
+                raise
+            # Fail-open: drop on the floor.
+
+    def about(self) -> dict[str, Any]:
+        r = self._session.get(
+            f"{self._base}/v1/about",
+            timeout=self.timeout_seconds,
+        )
+        r.raise_for_status()
+        return r.json()

spendwall/errors.py

@@ -0,0 +1,37 @@
+"""Spendwall SDK exceptions."""
+
+from __future__ import annotations
+
+
+class SpendwallError(Exception):
+    """Base for all spendwall-raised exceptions."""
+
+
+class BlockedError(SpendwallError):
+    """Raised in `enforce` mode when policy returned Blocked."""
+
+    def __init__(self, cap_id: str, projected_cents: int, limit_cents: int):
+        self.cap_id = cap_id
+        self.projected_cents = projected_cents
+        self.limit_cents = limit_cents
+        super().__init__(
+            f"Spendwall blocked by cap '{cap_id}': "
+            f"projected {projected_cents}c > limit {limit_cents}c"
+        )
+
+
+class ApprovalRequiredError(SpendwallError):
+    """Raised in `enforce` mode when policy returned ApprovalRequired and the
+    approval was denied or timed out."""
+
+    def __init__(self, approval_caps: list[str], reason: str = "denied"):
+        self.approval_caps = approval_caps
+        self.reason = reason
+        super().__init__(
+            f"Spendwall approval {reason} for caps={approval_caps}"
+        )
+
+
+class SpendwallVersionMismatch(SpendwallError):
+    """Raised once when the daemon's API version does not match the SDK's.
+    SDK falls back to fail-open `observe` mode for the rest of the process."""

spendwall/modes.py

@@ -0,0 +1,26 @@
+"""Mode resolution — observe, advisory, enforce."""
+
+from __future__ import annotations
+
+import os
+from typing import Literal, Optional
+
+Mode = Literal["observe", "advisory", "enforce"]
+_VALID = ("observe", "advisory", "enforce")
+_ENV_VAR = "SPENDWALL_MODE"
+
+
+def resolve(per_call: Optional[str] = None, configured: Optional[str] = None) -> Mode:
+    """Precedence (most specific wins):
+    1. `per_call` kwarg passed by user code at the call site
+    2. `configured` value from `wrap(..., mode=...)`
+    3. `SPENDWALL_MODE` env var
+    4. Default: `observe`
+    """
+    for v in (per_call, configured, os.environ.get(_ENV_VAR)):
+        if v is None:
+            continue
+        if v not in _VALID:
+            raise ValueError(f"invalid spendwall mode: {v!r}; expected one of {_VALID}")
+        return v  # type: ignore[return-value]
+    return "observe"

spendwall/openai.py

@@ -0,0 +1,98 @@
+"""Wrapper for ``openai.OpenAI`` clients.
+
+Patches ``client.chat.completions.create`` and ``client.responses.create``
+in-place so every upstream call is observed by spendwalld. In ``enforce``
+mode, the wrapper consults policy *before* dispatching to the upstream and
+raises ``BlockedError``/``ApprovalRequiredError`` when the daemon refuses.
+"""
+
+from __future__ import annotations
+
+import json as _json
+from typing import Any, Optional
+
+from spendwall.client import SpendwallClient
+from spendwall.modes import Mode, resolve as resolve_mode
+
+
+def _estimate_tokens(messages_or_input: Any) -> int:
+    """Cheap byte-based estimate; daemon reconciles cost post-flight."""
+    try:
+        return max(1, len(_json.dumps(messages_or_input)) // 4)
+    except (TypeError, ValueError):
+        return 1
+
+
+def wrap(
+    openai_client: Any,
+    *,
+    sw_client: Optional[SpendwallClient] = None,
+    agent_id: str = "anonymous",
+    mode: Optional[Mode] = None,
+    tags: Optional[dict[str, str]] = None,
+) -> Any:
+    """Patch ``openai_client.chat.completions.create`` (and ``.responses.create``)
+    to call into spendwall before/after the upstream request.
+
+    Mutates the supplied client in-place AND returns it for ergonomic chaining:
+
+        client = wrap(openai.OpenAI(...), agent_id="x")
+    """
+    sw = sw_client or SpendwallClient()
+    configured_mode = mode
+
+    def _patch(parent: Any, name: str) -> None:
+        original = getattr(parent, name)
+
+        def patched(*args: Any, **kwargs: Any) -> Any:
+            call_mode = resolve_mode(configured=configured_mode)
+            model = kwargs.get("model", "unknown")
+            est_input_tokens = _estimate_tokens(
+                kwargs.get("messages") or kwargs.get("input")
+            )
+            # Daemon does pricing lookup; SDK sends estimated_cost_cents=0
+            # to defer cost estimation to the daemon side.
+            if call_mode == "enforce":
+                sw.policy_check_strict(
+                    agent_id=agent_id, provider="openai", model=model,
+                    estimated_cost_cents=0, tags=tags or {},
+                )
+            elif call_mode == "advisory":
+                sw.policy_check(
+                    agent_id=agent_id, provider="openai", model=model,
+                    estimated_cost_cents=0, tags=tags or {},
+                )
+            # observe-mode skips policy_check entirely (zero added latency).
+            try:
+                result = original(*args, **kwargs)
+            except Exception:
+                sw.observe({
+                    "agent_id": agent_id, "provider": "openai", "model": model,
+                    "source": "sdk_python", "input_tokens": est_input_tokens,
+                    "output_tokens": None, "estimated_cost_cents": 0,
+                    "actual_cost_cents": None, "decision_str": "allowed",
+                    "binding_caps": [], "tags": tags or {},
+                    "outcome": "upstream_error",
+                })
+                raise
+
+            usage = getattr(result, "usage", None)
+            input_tokens = getattr(usage, "prompt_tokens", None) if usage else None
+            output_tokens = getattr(usage, "completion_tokens", None) if usage else None
+            sw.observe({
+                "agent_id": agent_id, "provider": "openai", "model": model,
+                "source": "sdk_python", "input_tokens": input_tokens,
+                "output_tokens": output_tokens, "estimated_cost_cents": 0,
+                "actual_cost_cents": None, "decision_str": "allowed",
+                "binding_caps": [], "tags": tags or {},
+                "outcome": "success",
+            })
+            return result
+
+        setattr(parent, name, patched)
+
+    if hasattr(openai_client, "chat") and hasattr(openai_client.chat, "completions"):
+        _patch(openai_client.chat.completions, "create")
+    if hasattr(openai_client, "responses"):
+        _patch(openai_client.responses, "create")
+    return openai_client

spendwall-0.0.6.dist-info/METADATA

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: spendwall
+Version: 0.0.6
+Summary: Spendwall SDK — local-first agent spend firewall
+Author: Spendwall
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests-unixsocket>=0.3
+Requires-Dist: requests>=2.28
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.21; extra == "anthropic"
+Provides-Extra: all
+Requires-Dist: openai>=1.0; extra == "all"
+Requires-Dist: anthropic>=0.21; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+
+# spendwall (Python)
+
+```python
+import openai
+import spendwall.openai as sw
+
+client = openai.OpenAI(api_key="sk-...")
+client = sw.wrap(client, mode="enforce")
+
+# Now every client.chat.completions.create(...) is observed by spendwalld.
+```

spendwall-0.0.6.dist-info/RECORD

@@ -0,0 +1,10 @@
+spendwall/__init__.py,sha256=3wFQ_DwCWW1VNLsMKG1Nnnuf4BalHj3CUh1rFdoPgX8,328
+spendwall/anthropic.py,sha256=uHQmwXrSr7VLSIRNdo_GEkQvuJYGuzZbh6rnOa67yf4,3219
+spendwall/client.py,sha256=YfjrgQM1lbuqRLL80Rf2-SjfeSMACxX-JNE35NHDiFo,3756
+spendwall/errors.py,sha256=DuBdVvo8e7tnXim6HVZlHPT-byf_8kerBFL6FNG42TI,1228
+spendwall/modes.py,sha256=-YHg3q90HjQdBqD5i17kyNUeAVXN9aJwuVwuAGdOSsQ,860
+spendwall/openai.py,sha256=0viGVSZ-5fdVDUQBNQXrrhowOmdqyKIZ-rUuePXrn3g,3974
+spendwall-0.0.6.dist-info/METADATA,sha256=z1b3UBj5-K5_yySHhfyeBSbdSk5o2ZCj7FP_xFm0EkA,943
+spendwall-0.0.6.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+spendwall-0.0.6.dist-info/top_level.txt,sha256=Dk33kymC3JHwUjo8dO_m55Qja7dyRtU6Q4AKLwxugdU,10
+spendwall-0.0.6.dist-info/RECORD,,

spendwall-0.0.6.dist-info/WHEEL

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

spendwall-0.0.6.dist-info/top_level.txt

@@ -0,0 +1 @@
+spendwall