spendguard 0.1.0__py3-none-any.whl

spendguard/__init__.py

@@ -0,0 +1,36 @@
+"""spendguard -- blocks an over-budget LLM API call before it happens.
+
+Build status: Stage 4 (core platform build), matching README.md's quickstart.
+SpendGuard.wrap_openai() / wrap_anthropic() / track() are implemented and
+gate client.chat.completions.create() / client.messages.create() respectively
+-- every other client attribute (embeddings, models, ...) and streaming calls
+(stream=True) are explicitly out of scope for this MVP wrapper, not silently
+mishandled. Pricing data in config/ is placeholder, not verified current
+rates -- see cost/pricing.py.
+"""
+from .exceptions import BudgetError, BudgetExceededError, PricingDataError
+from .tracker import SpendTracker
+from .cost import CostCalculator, CostEstimator, ModelPrice, PricingTable
+from .providers import AnthropicProvider, OpenAIProvider, Provider, Usage
+from .session import SpendGuard
+from .wrappers import AnthropicClientWrapper, OpenAIClientWrapper
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "SpendGuard",
+    "SpendTracker",
+    "BudgetError",
+    "BudgetExceededError",
+    "PricingDataError",
+    "CostCalculator",
+    "CostEstimator",
+    "ModelPrice",
+    "PricingTable",
+    "Provider",
+    "Usage",
+    "OpenAIProvider",
+    "AnthropicProvider",
+    "OpenAIClientWrapper",
+    "AnthropicClientWrapper",
+]

spendguard/config/pricing_anthropic.json

@@ -0,0 +1,7 @@
+{
+  "_note": "Pricing last verified 2026-06-25 against anthropic.com/pricing. Update _version_date and rates when Anthropic publishes a price change.",
+  "_version_date": "2026-06-25",
+  "claude-haiku-4-5": {"input_per_million": 1.00, "output_per_million": 5.00},
+  "claude-sonnet-4-6": {"input_per_million": 3.00, "output_per_million": 15.00},
+  "claude-opus-4-6": {"input_per_million": 15.00, "output_per_million": 75.00}
+}

spendguard/config/pricing_openai.json

@@ -0,0 +1,7 @@
+{
+  "_note": "Pricing last verified 2026-06-25 against openai.com/api/pricing. Update _version_date and rates when OpenAI publishes a price change.",
+  "_version_date": "2026-06-25",
+  "gpt-4o-mini": {"input_per_million": 0.15, "output_per_million": 0.60},
+  "gpt-4o": {"input_per_million": 2.50, "output_per_million": 10.00},
+  "gpt-4.1-mini": {"input_per_million": 0.40, "output_per_million": 1.60}
+}

spendguard/context.py

@@ -0,0 +1,46 @@
+"""Thread-local override state shared between SpendGuard.track() and the
+provider wrappers it gates.
+
+`with guard.track(override=True):` has to affect only calls made on the
+current thread inside that block, not every thread sharing the same
+SpendGuard -- otherwise one thread's override would silently apply to
+another's concurrent call.
+"""
+from __future__ import annotations
+
+import threading
+
+
+class OverrideContext:
+    def __init__(self) -> None:
+        self._local = threading.local()
+
+    def push(self, override: bool) -> None:
+        stack = getattr(self._local, "stack", None)
+        if stack is None:
+            stack = []
+            self._local.stack = stack
+        stack.append(override)
+
+    def pop(self) -> None:
+        self._local.stack.pop()
+
+    def current(self) -> bool:
+        stack = getattr(self._local, "stack", None)
+        return bool(stack) and stack[-1]
+
+
+class TrackContext:
+    """Returned by SpendGuard.track() -- see README.md's "Overriding a block on purpose"."""
+
+    def __init__(self, override_context: OverrideContext, override: bool) -> None:
+        self._override_context = override_context
+        self._override = override
+
+    def __enter__(self) -> "TrackContext":
+        self._override_context.push(self._override)
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        self._override_context.pop()
+        return False

spendguard/cost/__init__.py

@@ -0,0 +1,5 @@
+from .pricing import ModelPrice, PricingTable
+from .estimator import CostEstimator
+from .calculator import CostCalculator
+
+__all__ = ["ModelPrice", "PricingTable", "CostEstimator", "CostCalculator"]

spendguard/cost/calculator.py

@@ -0,0 +1,21 @@
+"""CostCalculator -- turns real, post-call token usage into an actual dollar cost.
+
+Always the source of truth recorded into SpendTracker.commit() -- never the
+pre-call estimate, once the provider's real usage numbers are known.
+"""
+from __future__ import annotations
+
+from ..providers.base import Usage
+from .pricing import PricingTable
+
+
+class CostCalculator:
+    def __init__(self, pricing: PricingTable) -> None:
+        self._pricing = pricing
+
+    def actual_cost_usd(self, provider: str, model: str, usage: Usage) -> float:
+        price = self._pricing.get_price(provider, model)
+        return (
+            usage.input_tokens / 1_000_000 * price.input_per_million
+            + usage.output_tokens / 1_000_000 * price.output_per_million
+        )

spendguard/cost/estimator.py

@@ -0,0 +1,45 @@
+"""CostEstimator -- pre-call cost estimate from a prompt and max output size.
+
+Zero required dependency: input tokens are approximated at ~4 characters per
+token unless tiktoken is installed (pip install spendguard[tiktoken]), in
+which case OpenAI prompts get exact cl100k_base counts. The estimate only has
+to be close enough to gate correctly -- CostCalculator always recomputes the
+real cost from the provider's own usage numbers after the call resolves.
+"""
+from __future__ import annotations
+
+from .pricing import PricingTable
+
+CHARS_PER_TOKEN_APPROX = 4
+
+try:
+    import tiktoken
+
+    _ENCODING = tiktoken.get_encoding("cl100k_base")
+except ImportError:
+    _ENCODING = None
+
+
+def _count_input_tokens(prompt_text: str, provider: str) -> int:
+    if _ENCODING is not None and provider == "openai":
+        return max(1, len(_ENCODING.encode(prompt_text)))
+    return max(1, len(prompt_text) // CHARS_PER_TOKEN_APPROX)
+
+
+class CostEstimator:
+    def __init__(self, pricing: PricingTable) -> None:
+        self._pricing = pricing
+
+    def estimate_usd(
+        self,
+        provider: str,
+        model: str,
+        prompt_text: str,
+        max_output_tokens: int,
+    ) -> float:
+        price = self._pricing.get_price(provider, model)
+        input_tokens = _count_input_tokens(prompt_text, provider)
+        return (
+            input_tokens / 1_000_000 * price.input_per_million
+            + max_output_tokens / 1_000_000 * price.output_per_million
+        )

spendguard/cost/pricing.py

@@ -0,0 +1,77 @@
+"""PricingTable -- loads per-provider model pricing from config/pricing_<provider>.json.
+
+Adding a new provider's prices later is a new config/pricing_<provider>.json
+file, not a code change here. Keys starting with "_" (e.g. "_note") are
+metadata, not models, and are skipped when loading.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import warnings
+from dataclasses import dataclass
+from datetime import date, datetime
+from pathlib import Path
+from typing import Dict, Optional
+
+from ..exceptions import PricingDataError
+
+_STALENESS_DAYS = 90
+_log = logging.getLogger(__name__)
+
+DEFAULT_CONFIG_DIR = Path(__file__).resolve().parent.parent / "config"
+
+
+@dataclass(frozen=True)
+class ModelPrice:
+    input_per_million: float
+    output_per_million: float
+
+
+class PricingTable:
+    def __init__(self, config_dir: Optional[Path] = None) -> None:
+        self._config_dir = config_dir if config_dir is not None else DEFAULT_CONFIG_DIR
+        self._cache: Dict[str, Dict[str, ModelPrice]] = {}
+
+    def _load_provider(self, provider: str) -> Dict[str, ModelPrice]:
+        if provider in self._cache:
+            return self._cache[provider]
+
+        path = self._config_dir / f"pricing_{provider}.json"
+        if not path.exists():
+            raise PricingDataError(f"no pricing config for provider '{provider}' (looked for {path})")
+
+        raw = json.loads(path.read_text(encoding="utf-8"))
+
+        version_date_str = raw.get("_version_date")
+        if version_date_str:
+            try:
+                version_date = datetime.strptime(version_date_str, "%Y-%m-%d").date()
+                age_days = (date.today() - version_date).days
+                if age_days > _STALENESS_DAYS:
+                    warnings.warn(
+                        f"SpendGuard: {provider} pricing data is {age_days} days old "
+                        f"(last verified {version_date_str}). Cost estimates may be inaccurate "
+                        f"if {provider} has changed their prices. Update config/pricing_{provider}.json "
+                        f"or pass a custom config_dir to PricingTable().",
+                        stacklevel=3,
+                    )
+            except ValueError:
+                _log.debug("Could not parse _version_date '%s' in pricing_%s.json", version_date_str, provider)
+
+        prices = {
+            model: ModelPrice(
+                input_per_million=entry["input_per_million"],
+                output_per_million=entry["output_per_million"],
+            )
+            for model, entry in raw.items()
+            if not model.startswith("_")
+        }
+        self._cache[provider] = prices
+        return prices
+
+    def get_price(self, provider: str, model: str) -> ModelPrice:
+        prices = self._load_provider(provider)
+        if model not in prices:
+            raise PricingDataError(f"unknown model '{model}' for provider '{provider}'")
+        return prices[model]

spendguard/events.py

@@ -0,0 +1,112 @@
+"""Local spend-event log -- zero-backend audit trail.
+
+release-gates.md's Observability readiness gate requires "a way to tell,
+after the fact, what happened during a failed run." For an SDK with no
+backend and no account, that has to be a local file: one JSON line per
+gated call, recording what was estimated, what was decided, what it took,
+and what was actually spent. This is also the file a future V1 Ingestion API
+would read from (prd.md's Dependency Map) -- spendguard doesn't need that
+API to exist yet, it just needs to not lose the data that API will
+eventually want.
+
+Rotation: release-gates.md's cost-model gate requires "logging volume...
+has an explicit limit or sampling rule" -- an unbounded append-only file
+would otherwise grow forever for a high-call-volume user (the exact
+runaway-agent scenario this product exists to catch). max_bytes bounds disk
+usage to roughly 2x its value: one rotated file is kept (events.jsonl.1),
+the previous rotation is discarded, never an unbounded history.
+"""
+from __future__ import annotations
+
+import json
+import threading
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+DEFAULT_EVENT_LOG_PATH = Path(".spendguard") / "events.jsonl"
+DEFAULT_MAX_BYTES = 10 * 1024 * 1024  # 10 MB
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+@dataclass(frozen=True)
+class SpendEvent:
+    at: str
+    workspace: str
+    provider: str
+    model: str
+    decision: str  # "allowed" | "allowed_with_override" | "blocked" | "rolled_back"
+    estimated_cost_usd: float
+    actual_cost_usd: Optional[float] = None
+    reservation_id: Optional[str] = None
+    latency_ms: Optional[float] = None
+
+
+class EventLog:
+    """Thread-safe append-only JSONL writer, with size-based rotation.
+
+    Output only -- spendguard never reads this back to make a decision in the
+    MVP. The lock here is separate from SpendTracker's: it protects the file
+    write, not the budget arithmetic.
+    """
+
+    def __init__(self, path: Path, max_bytes: Optional[int] = DEFAULT_MAX_BYTES) -> None:
+        self._path = path
+        self._max_bytes = max_bytes
+        self._lock = threading.Lock()
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    def _rotate_if_needed(self, incoming_bytes: int) -> None:
+        if self._max_bytes is None:
+            return
+        try:
+            current_size = self._path.stat().st_size
+        except FileNotFoundError:
+            return
+        if current_size + incoming_bytes <= self._max_bytes:
+            return
+        rotated = self._path.with_name(self._path.name + ".1")
+        if rotated.exists():
+            rotated.unlink()
+        self._path.rename(rotated)
+
+    def append(self, event: SpendEvent) -> None:
+        with self._lock:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            line = json.dumps(asdict(event)) + "\n"
+            self._rotate_if_needed(len(line.encode("utf-8")))
+            with self._path.open("a", encoding="utf-8") as f:
+                f.write(line)
+
+    def record(
+        self,
+        *,
+        workspace: str,
+        provider: str,
+        model: str,
+        decision: str,
+        estimated_cost_usd: float,
+        actual_cost_usd: Optional[float] = None,
+        reservation_id: Optional[str] = None,
+        latency_ms: Optional[float] = None,
+    ) -> None:
+        self.append(
+            SpendEvent(
+                at=_now_iso(),
+                workspace=workspace,
+                provider=provider,
+                model=model,
+                decision=decision,
+                estimated_cost_usd=estimated_cost_usd,
+                actual_cost_usd=actual_cost_usd,
+                reservation_id=reservation_id,
+                latency_ms=latency_ms,
+            )
+        )

spendguard/exceptions.py

@@ -0,0 +1,31 @@
+"""Exceptions raised by spendguard's budget enforcement."""
+from __future__ import annotations
+
+
+class BudgetError(Exception):
+    """Base class for all spendguard budget errors."""
+
+
+class BudgetExceededError(BudgetError):
+    """Raised when a call's estimated cost would cross the ceiling's threshold.
+
+    Carries the numbers that caused the block so a caller (or its except clause)
+    can report something more useful than the message string alone.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        estimated_cost: float,
+        remaining: float,
+        threshold_usd: float,
+    ) -> None:
+        super().__init__(message)
+        self.estimated_cost = estimated_cost
+        self.remaining = remaining
+        self.threshold_usd = threshold_usd
+
+
+class PricingDataError(BudgetError):
+    """Raised when a model's pricing can't be resolved (unknown model, bad config)."""

spendguard/providers/__init__.py

@@ -0,0 +1,5 @@
+from .base import Provider, Usage
+from .openai_provider import OpenAIProvider
+from .anthropic_provider import AnthropicProvider
+
+__all__ = ["Provider", "Usage", "OpenAIProvider", "AnthropicProvider"]

spendguard/providers/anthropic_provider.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .base import Provider, Usage
+
+
+class AnthropicProvider(Provider):
+    name = "anthropic"
+
+    def extract_usage(self, response: Any) -> Usage:
+        usage = response.usage
+        return Usage(input_tokens=usage.input_tokens, output_tokens=usage.output_tokens)

spendguard/providers/base.py

@@ -0,0 +1,31 @@
+"""Provider abstraction -- the seam a new LLM provider plugs into.
+
+Adding a provider beyond OpenAI/Anthropic (Gemini, Perplexity, etc. -- out of
+scope today per product-thesis.md's non-goals, but the reason this seam
+exists) means implementing extract_usage() below plus a pricing config file.
+SpendTracker, CostEstimator, and CostCalculator never reference a provider's
+SDK or response shape directly -- they only see Usage and dollar amounts.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Usage:
+    """Real token counts for one completed call, provider-shape already stripped off."""
+
+    input_tokens: int
+    output_tokens: int
+
+
+class Provider(ABC):
+    """Translates one provider SDK's response object into a Usage."""
+
+    name: str
+
+    @abstractmethod
+    def extract_usage(self, response: Any) -> Usage:
+        """Pull real token counts out of a completed API response."""

spendguard/providers/openai_provider.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .base import Provider, Usage
+
+
+class OpenAIProvider(Provider):
+    name = "openai"
+
+    def extract_usage(self, response: Any) -> Usage:
+        usage = response.usage
+        return Usage(input_tokens=usage.prompt_tokens, output_tokens=usage.completion_tokens)

spendguard/session.py

@@ -0,0 +1,85 @@
+"""SpendGuard -- the public entry point described in README.md's quickstart.
+
+wrap_openai() / wrap_anthropic() are the primary integration pattern: wrap
+the client once at construction, then call it exactly like the real client.
+track() is the escape hatch for README.md's "Overriding a block on purpose".
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Optional
+
+from .context import OverrideContext, TrackContext
+from .cost.calculator import CostCalculator
+from .cost.estimator import CostEstimator
+from .cost.pricing import PricingTable
+from .events import DEFAULT_EVENT_LOG_PATH, DEFAULT_MAX_BYTES, EventLog
+from .tracker import DEFAULT_THRESHOLD_PCT, SpendTracker
+from .wrappers.anthropic import AnthropicClientWrapper
+from .wrappers.openai import OpenAIClientWrapper
+
+
+class SpendGuard:
+    def __init__(
+        self,
+        workspace: str,
+        ceiling_usd: float,
+        threshold_pct: float = DEFAULT_THRESHOLD_PCT,
+        pricing_config_dir: Optional[Path] = None,
+        event_log_path: Optional[Path] = None,
+        event_log_max_bytes: Optional[int] = DEFAULT_MAX_BYTES,
+        log_events: bool = True,
+    ) -> None:
+        self.workspace = workspace
+        self._tracker = SpendTracker(ceiling_usd, threshold_pct)
+        pricing = PricingTable(config_dir=pricing_config_dir)
+        self._estimator = CostEstimator(pricing)
+        self._calculator = CostCalculator(pricing)
+        self._override_context = OverrideContext()
+        self._event_log = (
+            EventLog(
+                event_log_path if event_log_path is not None else DEFAULT_EVENT_LOG_PATH,
+                max_bytes=event_log_max_bytes,
+            )
+            if log_events
+            else None
+        )
+
+    def wrap_openai(self, client: Any) -> OpenAIClientWrapper:
+        return OpenAIClientWrapper(
+            client,
+            self._tracker,
+            self._estimator,
+            self._calculator,
+            self._override_context,
+            self.workspace,
+            self._event_log,
+        )
+
+    def wrap_anthropic(self, client: Any) -> AnthropicClientWrapper:
+        return AnthropicClientWrapper(
+            client,
+            self._tracker,
+            self._estimator,
+            self._calculator,
+            self._override_context,
+            self.workspace,
+            self._event_log,
+        )
+
+    def track(self, model: Optional[str] = None, override: bool = False) -> TrackContext:
+        """Escape hatch for one call -- see README.md's "Overriding a block on purpose".
+
+        `model` is accepted for forward-compatible per-call labeling (planned
+        for the V1.1 event log) but has no effect yet; `override` is the only
+        thing this currently does.
+        """
+        return TrackContext(self._override_context, override)
+
+    def get_summary(self) -> dict:
+        return self._tracker.get_summary()
+
+    @property
+    def event_log_path(self) -> Optional[Path]:
+        """Where local spend events are being written, or None if logging is disabled."""
+        return self._event_log.path if self._event_log is not None else None

spendguard/tracker.py

@@ -0,0 +1,131 @@
+"""SpendTracker — thread-safe ceiling enforcement with atomic reservation.
+
+Per README.md's "How the ceiling actually works" and prd.md's matching workflow,
+spendguard mirrors runtime/cost_ledger.py's hard rule: a call is blocked once
+cumulative spend plus its estimate would cross 25% of the founder-set ceiling.
+
+cost_ledger.py checks that rule against spend already recorded, which is safe for
+a single sequential caller but not for concurrent ones -- two calls firing at the
+same instant can each see room under the threshold and both proceed, together
+overshooting it. That gap is exactly the failure mode this product's own pitch
+describes (a fan-out or retry loop spending faster than a check-then-record
+ledger can track) and is why the PRD now requires this tracker to make the
+check-and-reserve step atomic: estimated cost is reserved against the threshold
+under a single lock *before* a call is allowed to proceed, then released and
+converted to real spend (commit) or discarded (rollback) once the call resolves.
+At every point in time, spent + reserved <= threshold.
+"""
+from __future__ import annotations
+
+import threading
+import uuid
+from typing import Dict
+
+from .exceptions import BudgetExceededError
+
+DEFAULT_THRESHOLD_PCT = 0.25
+
+
+class SpendTracker:
+    """Tracks spend and in-flight reservations against a ceiling's 25% threshold."""
+
+    def __init__(self, ceiling_usd: float, threshold_pct: float = DEFAULT_THRESHOLD_PCT) -> None:
+        if ceiling_usd < 0:
+            raise ValueError("ceiling_usd cannot be negative")
+        if not 0 < threshold_pct <= 1:
+            raise ValueError("threshold_pct must be between 0 and 1")
+
+        self._ceiling = float(ceiling_usd)
+        self._threshold_pct = threshold_pct
+        self._threshold = self._ceiling * threshold_pct
+        self._spent = 0.0
+        self._reserved = 0.0
+        self._reservations: Dict[str, float] = {}
+        self._lock = threading.Lock()
+
+    def check_and_reserve(self, estimated_cost: float, override: bool = False) -> str:
+        """Atomically check the threshold and reserve funds for a call.
+
+        Raises BudgetExceededError if the estimate would cross the threshold,
+        unless override=True -- an explicit override still reserves (and will
+        still show up as spend once committed), it just skips the block.
+
+        Returns a reservation ID to pass to commit() or rollback().
+        """
+        with self._lock:
+            remaining = self._threshold - self._spent - self._reserved
+            if estimated_cost > remaining and not override:
+                raise BudgetExceededError(
+                    f"Estimated cost ${estimated_cost:.6f} would exceed the remaining "
+                    f"${remaining:.6f} under the ${self._threshold:.2f} threshold "
+                    f"({self._threshold_pct:.0%} of ${self._ceiling:.2f} ceiling)",
+                    estimated_cost=estimated_cost,
+                    remaining=remaining,
+                    threshold_usd=self._threshold,
+                )
+
+            reservation_id = str(uuid.uuid4())
+            self._reserved += estimated_cost
+            self._reservations[reservation_id] = estimated_cost
+            return reservation_id
+
+    def commit(self, reservation_id: str, actual_cost: float) -> None:
+        """Release a reservation and record the real cost once a call succeeds."""
+        with self._lock:
+            if reservation_id not in self._reservations:
+                raise KeyError(f"no such reservation: {reservation_id}")
+            reserved_amount = self._reservations.pop(reservation_id)
+            self._reserved -= reserved_amount
+            self._spent += actual_cost
+
+    def rollback(self, reservation_id: str) -> None:
+        """Release a reservation with no spend recorded, e.g. after a failed call.
+
+        Idempotent -- rolling back a reservation that's already gone is a no-op,
+        not an error, since a caller's cleanup path may run more than once.
+        """
+        with self._lock:
+            reserved_amount = self._reservations.pop(reservation_id, None)
+            if reserved_amount is not None:
+                self._reserved -= reserved_amount
+
+    def get_ceiling_usd(self) -> float:
+        return self._ceiling
+
+    def get_threshold_usd(self) -> float:
+        return self._threshold
+
+    def get_spent(self) -> float:
+        with self._lock:
+            return self._spent
+
+    def get_reserved(self) -> float:
+        with self._lock:
+            return self._reserved
+
+    def get_remaining(self) -> float:
+        """Room left under the threshold, accounting for in-flight reservations."""
+        with self._lock:
+            return self._threshold - self._spent - self._reserved
+
+    def get_summary(self) -> dict:
+        with self._lock:
+            spent, reserved = self._spent, self._reserved
+        utilization = (spent + reserved) / self._threshold * 100 if self._threshold > 0 else 0.0
+        return {
+            "ceiling_usd": self._ceiling,
+            "threshold_pct": self._threshold_pct,
+            "threshold_usd": self._threshold,
+            "spent": spent,
+            "reserved": reserved,
+            "remaining": self._threshold - spent - reserved,
+            "utilization_percent": utilization,
+        }
+
+    def reset(self) -> None:
+        """Reset spent and reservations to zero. Does not cancel in-flight calls --
+        only call this when certain nothing is pending."""
+        with self._lock:
+            self._spent = 0.0
+            self._reserved = 0.0
+            self._reservations.clear()

spendguard/wrappers/__init__.py

@@ -0,0 +1,4 @@
+from .openai import OpenAIClientWrapper
+from .anthropic import AnthropicClientWrapper
+
+__all__ = ["OpenAIClientWrapper", "AnthropicClientWrapper"]

spendguard/wrappers/_messages.py

@@ -0,0 +1,15 @@
+"""Shared helper: flatten a chat-style messages list into plain text for the
+pre-call token estimate. OpenAI's and Anthropic's message dicts use the same
+{"role": ..., "content": "..."} shape for simple text content.
+"""
+from __future__ import annotations
+
+from typing import Iterable
+
+
+def flatten_messages(messages: Iterable[dict]) -> str:
+    parts = []
+    for message in messages:
+        content = message.get("content", "")
+        parts.append(content if isinstance(content, str) else str(content))
+    return "\n".join(parts)

spendguard/wrappers/anthropic.py

@@ -0,0 +1,118 @@
+"""AnthropicClientWrapper -- drop-in wrap of an anthropic.Anthropic() client.
+
+Gates client.messages.create() only; everything else delegates straight
+through, ungated -- same MVP scope boundary as OpenAIClientWrapper. Streaming
+is rejected outright for the same reason: usage can't be reliably read off a
+streamed response in this version.
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, List, Optional
+
+from ..context import OverrideContext
+from ..cost.calculator import CostCalculator
+from ..cost.estimator import CostEstimator
+from ..events import EventLog
+from ..exceptions import BudgetExceededError
+from ..providers.anthropic_provider import AnthropicProvider
+from ..tracker import SpendTracker
+from ._messages import flatten_messages
+
+
+class _GatedMessages:
+    def __init__(
+        self,
+        real_messages: Any,
+        tracker: SpendTracker,
+        estimator: CostEstimator,
+        calculator: CostCalculator,
+        override_context: OverrideContext,
+        workspace: str,
+        event_log: Optional[EventLog],
+    ) -> None:
+        self._real = real_messages
+        self._tracker = tracker
+        self._estimator = estimator
+        self._calculator = calculator
+        self._override_context = override_context
+        self._workspace = workspace
+        self._event_log = event_log
+        self._provider = AnthropicProvider()
+
+    def _log(
+        self, model: str, decision: str, estimated_cost: float, actual_cost=None, reservation_id=None, latency_ms=None
+    ) -> None:
+        if self._event_log is not None:
+            self._event_log.record(
+                workspace=self._workspace,
+                provider="anthropic",
+                model=model,
+                decision=decision,
+                estimated_cost_usd=estimated_cost,
+                actual_cost_usd=actual_cost,
+                reservation_id=reservation_id,
+                latency_ms=latency_ms,
+            )
+
+    def create(self, *, model: str, max_tokens: int, messages: List[dict], **kwargs: Any) -> Any:
+        if kwargs.get("stream"):
+            raise NotImplementedError(
+                "spendguard does not support stream=True yet -- usage can't be "
+                "reliably extracted from a streamed response in this version."
+            )
+
+        prompt_text = flatten_messages(messages)
+        estimated_cost = self._estimator.estimate_usd("anthropic", model, prompt_text, max_tokens)
+
+        override = self._override_context.current()
+        try:
+            reservation_id = self._tracker.check_and_reserve(estimated_cost, override=override)
+        except BudgetExceededError:
+            self._log(model, "blocked", estimated_cost)
+            raise
+
+        started_at = time.monotonic()
+        try:
+            response = self._real.create(model=model, max_tokens=max_tokens, messages=messages, **kwargs)
+        except Exception:
+            latency_ms = (time.monotonic() - started_at) * 1000
+            self._tracker.rollback(reservation_id)
+            self._log(model, "rolled_back", estimated_cost, reservation_id=reservation_id, latency_ms=latency_ms)
+            raise
+        latency_ms = (time.monotonic() - started_at) * 1000
+
+        usage = self._provider.extract_usage(response)
+        actual_cost = self._calculator.actual_cost_usd("anthropic", model, usage)
+        self._tracker.commit(reservation_id, actual_cost)
+        self._log(
+            model,
+            "allowed_with_override" if override else "allowed",
+            estimated_cost,
+            actual_cost,
+            reservation_id,
+            latency_ms,
+        )
+        return response
+
+
+class AnthropicClientWrapper:
+    """Wraps a sync anthropic.Anthropic() client. Async clients are not wrapped yet."""
+
+    def __init__(
+        self,
+        client: Any,
+        tracker: SpendTracker,
+        estimator: CostEstimator,
+        calculator: CostCalculator,
+        override_context: OverrideContext,
+        workspace: str = "default",
+        event_log: Optional[EventLog] = None,
+    ) -> None:
+        self._client = client
+        self.messages = _GatedMessages(
+            client.messages, tracker, estimator, calculator, override_context, workspace, event_log
+        )
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._client, name)

spendguard/wrappers/openai.py

@@ -0,0 +1,147 @@
+"""OpenAIClientWrapper -- drop-in wrap of an openai.OpenAI() client.
+
+Gates client.chat.completions.create() only; every other attribute on the
+client (embeddings, models, files, ...) delegates straight through, ungated.
+That's a deliberate MVP scope boundary, not an oversight -- see README.md's
+"What this does NOT do (yet)". Streaming (stream=True) is rejected outright
+rather than silently mis-tracked, since usage can't be reliably read off a
+streamed response in this version.
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, List, Optional
+
+from ..context import OverrideContext
+from ..cost.calculator import CostCalculator
+from ..cost.estimator import CostEstimator
+from ..events import EventLog
+from ..providers.openai_provider import OpenAIProvider
+from ..tracker import SpendTracker
+from ..exceptions import BudgetExceededError
+from ._messages import flatten_messages
+
+DEFAULT_MAX_OUTPUT_TOKENS_ESTIMATE = 1024
+
+
+class _GatedChatCompletions:
+    def __init__(
+        self,
+        real_completions: Any,
+        tracker: SpendTracker,
+        estimator: CostEstimator,
+        calculator: CostCalculator,
+        override_context: OverrideContext,
+        workspace: str,
+        event_log: Optional[EventLog],
+    ) -> None:
+        self._real = real_completions
+        self._tracker = tracker
+        self._estimator = estimator
+        self._calculator = calculator
+        self._override_context = override_context
+        self._workspace = workspace
+        self._event_log = event_log
+        self._provider = OpenAIProvider()
+
+    def _log(
+        self, model: str, decision: str, estimated_cost: float, actual_cost=None, reservation_id=None, latency_ms=None
+    ) -> None:
+        if self._event_log is not None:
+            self._event_log.record(
+                workspace=self._workspace,
+                provider="openai",
+                model=model,
+                decision=decision,
+                estimated_cost_usd=estimated_cost,
+                actual_cost_usd=actual_cost,
+                reservation_id=reservation_id,
+                latency_ms=latency_ms,
+            )
+
+    def create(
+        self, *, model: str, messages: List[dict], max_tokens: Optional[int] = None, **kwargs: Any
+    ) -> Any:
+        if kwargs.get("stream"):
+            raise NotImplementedError(
+                "spendguard does not support stream=True yet -- usage can't be "
+                "reliably extracted from a streamed response in this version."
+            )
+
+        prompt_text = flatten_messages(messages)
+        estimate_output_tokens = (
+            max_tokens if max_tokens is not None else DEFAULT_MAX_OUTPUT_TOKENS_ESTIMATE
+        )
+        estimated_cost = self._estimator.estimate_usd("openai", model, prompt_text, estimate_output_tokens)
+
+        override = self._override_context.current()
+        try:
+            reservation_id = self._tracker.check_and_reserve(estimated_cost, override=override)
+        except BudgetExceededError:
+            self._log(model, "blocked", estimated_cost)
+            raise
+
+        call_kwargs = dict(kwargs)
+        if max_tokens is not None:
+            call_kwargs["max_tokens"] = max_tokens
+
+        started_at = time.monotonic()
+        try:
+            response = self._real.create(model=model, messages=messages, **call_kwargs)
+        except Exception:
+            latency_ms = (time.monotonic() - started_at) * 1000
+            self._tracker.rollback(reservation_id)
+            self._log(model, "rolled_back", estimated_cost, reservation_id=reservation_id, latency_ms=latency_ms)
+            raise
+        latency_ms = (time.monotonic() - started_at) * 1000
+
+        usage = self._provider.extract_usage(response)
+        actual_cost = self._calculator.actual_cost_usd("openai", model, usage)
+        self._tracker.commit(reservation_id, actual_cost)
+        self._log(
+            model,
+            "allowed_with_override" if override else "allowed",
+            estimated_cost,
+            actual_cost,
+            reservation_id,
+            latency_ms,
+        )
+        return response
+
+
+class _GatedChat:
+    def __init__(
+        self,
+        real_chat: Any,
+        tracker: SpendTracker,
+        estimator: CostEstimator,
+        calculator: CostCalculator,
+        override_context: OverrideContext,
+        workspace: str,
+        event_log: Optional[EventLog],
+    ) -> None:
+        self.completions = _GatedChatCompletions(
+            real_chat.completions, tracker, estimator, calculator, override_context, workspace, event_log
+        )
+
+
+class OpenAIClientWrapper:
+    """Wraps a sync openai.OpenAI() client. Async clients are not wrapped yet."""
+
+    def __init__(
+        self,
+        client: Any,
+        tracker: SpendTracker,
+        estimator: CostEstimator,
+        calculator: CostCalculator,
+        override_context: OverrideContext,
+        workspace: str = "default",
+        event_log: Optional[EventLog] = None,
+    ) -> None:
+        self._client = client
+        self.chat = _GatedChat(
+            client.chat, tracker, estimator, calculator, override_context, workspace, event_log
+        )
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._client, name)

spendguard-0.1.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: spendguard
+Version: 0.1.0
+Summary: A 2-line wrapper around your OpenAI or Anthropic client that blocks an over-budget API call before it happens.
+Project-URL: Homepage, https://github.com/Rahul-git23/spendguard
+Project-URL: Repository, https://github.com/Rahul-git23/spendguard
+Author-email: Rahul Vichare <rahulvichare@gmail.com>
+License: MIT
+Keywords: ai,anthropic,budget,cost,guardrail,llm,openai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: anthropic>=0.25.0
+Requires-Dist: openai>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Provides-Extra: tiktoken
+Requires-Dist: tiktoken>=0.5.0; extra == 'tiktoken'
+Description-Content-Type: text/markdown
+
+# SpendGuard
+
+A 2-line wrapper around your OpenAI or Anthropic client that blocks an over-budget API call **before it happens** — no surprises at the end of the month.
+
+```python
+from spendguard import SpendGuard
+
+guard = SpendGuard(workspace="my-app", ceiling_usd=20.0)
+client = guard.wrap_openai(OpenAI())          # or wrap_anthropic(Anthropic())
+
+# Call the client exactly as normal — SpendGuard intercepts transparently.
+# If the estimated cost would push cumulative spend past 25% of the $20 ceiling,
+# it raises BudgetExceededError before the API call is made.
+response = client.chat.completions.create(model="gpt-4o", messages=[...])
+```
+
+## Install
+
+```bash
+pip install spendguard
+```
+
+For more accurate pre-call token counting on OpenAI models:
+
+```bash
+pip install spendguard[tiktoken]
+```
+
+## How it works
+
+SpendGuard wraps your existing client object. Every call goes through two steps:
+
+1. **Pre-call estimate** — approximates the input token count and adds the max output tokens × the model's per-token rate. If `cumulative_spend + estimate > ceiling × threshold_pct`, it raises `BudgetExceededError` before the network call.
+2. **Post-call commit** — reads the provider's actual usage numbers from the response and records the real cost.
+
+The default threshold is 25% of the ceiling (`threshold_pct=0.25`). This means a single call can consume at most 25% of your monthly budget — it is a guardrail against a single runaway call, not a hard cap at 100%.
+
+## Supported providers and models
+
+| Provider   | Client wrapper       | Models gated by default |
+| ---------- | -------------------- | ----------------------- |
+| OpenAI     | `wrap_openai()`      | gpt-4o, gpt-4o-mini, and all models in the pricing config |
+| Anthropic  | `wrap_anthropic()`   | claude-3-5-sonnet, claude-3-opus, haiku, and all models in the pricing config |
+
+## Usage
+
+### Basic setup
+
+```python
+from openai import OpenAI
+from spendguard import SpendGuard
+
+guard = SpendGuard(workspace="my-product", ceiling_usd=20.0)
+client = guard.wrap_openai(OpenAI())
+
+try:
+    response = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "user", "content": "Hello"}],
+        max_tokens=512,
+    )
+except BudgetExceededError as e:
+    print(f"Blocked: {e}")
+```
+
+### Anthropic
+
+```python
+from anthropic import Anthropic
+from spendguard import SpendGuard
+
+guard = SpendGuard(workspace="my-product", ceiling_usd=20.0)
+client = guard.wrap_anthropic(Anthropic())
+
+response = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello"}],
+)
+```
+
+### Overriding a block on purpose
+
+When you explicitly want to allow a call that would be blocked (e.g., a one-time large batch job), use `track()` with `override=True`:
+
+```python
+with guard.track(override=True):
+    response = client.chat.completions.create(...)   # never blocked
+```
+
+The override only applies inside the `with` block and does not persist.
+
+### Inspecting current spend
+
+```python
+summary = guard.get_summary()
+# {"ceiling_usd": 20.0, "spent_usd": 1.23, "reserved_usd": 0.0, "threshold_pct": 0.25}
+```
+
+## Workspace isolation
+
+Each `SpendGuard` instance is scoped to a `workspace` string. When you run multiple products or feature flags, give each its own workspace so their budgets are tracked independently.
+
+## Out of scope for v0.1
+
+- Streaming calls (`stream=True`) — explicitly rejected with a clear error.
+- Embeddings, images, audio, and other non-chat/messages endpoints.
+- Persistent spend across process restarts (resets on `SpendGuard()` construction).
+
+Persistence and streaming support are planned for v1.0.
+
+## Feedback
+
+Found a bug or have a feature request? [Open an issue](https://github.com/Rahul-git23/spendguard/issues) — all feedback welcome.
+
+## License
+
+MIT

spendguard-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+spendguard/__init__.py,sha256=nKIgYMx1-RYicoJ1PS4ZvWUNxI4t4t-7XJyPOB5_p4U,1279
+spendguard/context.py,sha256=nbxnQ-OX5_LtU_bCjcgedudo259F840K1GPuxL9EC_E,1402
+spendguard/events.py,sha256=cEl-GvgTRM8Y2gLH6tYQi7rCCZztFzhEPLxCJqzfjkc,3879
+spendguard/exceptions.py,sha256=uWxxaeiYMp4rTwtNDr65YX6MFsXpd5q1PfNPVt9tRC4,913
+spendguard/session.py,sha256=1yPoCq52k0znx80xH_LMlGhVs7TheIBx5b0l_5JMgK4,3136
+spendguard/tracker.py,sha256=xwo0e03nyP6roFGo_AIXQhkXfUy_UdFKwrX2Upj4ci0,5584
+spendguard/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+spendguard/config/pricing_anthropic.json,sha256=8O3CK6mjcw60c3FNYHCyAkWotojCnQ6-KIB6vn87pzM,426
+spendguard/config/pricing_openai.json,sha256=9w917MLpp5BA6I_zd_XRFfNqjqOywYft5Rg2T-OBPJA,403
+spendguard/cost/__init__.py,sha256=prdECLVbHNov2aojAxgwNS3AyQ0rG8FpGvmd9FLBMMA,199
+spendguard/cost/calculator.py,sha256=ab3_aGah5PngdF3nTdZGAAEhjv2_xBVp-Ptrt4_Hgw8,757
+spendguard/cost/estimator.py,sha256=joBdbAeeleZeZH8pb9iYT57uMtDWBr0pYOiwKk1gheg,1471
+spendguard/cost/pricing.py,sha256=lwOlTmG06kc99HW2MKc6XK3Rt-OCoqPTMp9C7fCPg0I,2925
+spendguard/providers/__init__.py,sha256=3GRtSd5P1iTHoVKxSP9UAb8t20fpTcv7_qk6GY2KR8Y,200
+spendguard/providers/anthropic_provider.py,sha256=cq9pP0_dPP_crQ4dTSpz21VkB2QD6V1HA9-C1kxyM_4,328
+spendguard/providers/base.py,sha256=-T6N1qBsInQvJl6tPWHz2bgmY5dCoodzJIcpnPYGiLY,1005
+spendguard/providers/openai_provider.py,sha256=TJnEKmhvKi5N9doLmgUzv2t2EuTm6pcEZN9sLerB38c,327
+spendguard/wrappers/__init__.py,sha256=qaLGpTJERDspdbMQqzIWMF_HB08TEgubsL-hC-_qDyk,147
+spendguard/wrappers/_messages.py,sha256=BrpD4vG36J3LEfoh6KuzsRaew8zvJ0g1Ops7Z7Cufv0,535
+spendguard/wrappers/anthropic.py,sha256=kGlxT6fkDivd9RaIziMxK7fZE8Bdn0hLQqMxvfQ94Hs,4328
+spendguard/wrappers/openai.py,sha256=pDLibdu49hIdvoKadU-8EfhpuhaIJ1WhA9sOrpDj8ws,5232
+spendguard-0.1.0.dist-info/METADATA,sha256=vA29iaaCMFdJqq8MGIxwS0wUR1XEdFHyfeZ5WmczXyg,4997
+spendguard-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+spendguard-0.1.0.dist-info/RECORD,,

spendguard-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any