spendguard 0.1.0__tar.gz

spendguard-0.1.0/.github/workflows/publish-spendguard.yml

@@ -0,0 +1,96 @@
+name: Publish SpendGuard to PyPI
+
+# Trigger: create a GitHub Release with a tag of the form spendguard-v<version>
+# e.g. tag = "spendguard-v0.1.0", release title = "SpendGuard 0.1.0"
+#
+# PyPI Trusted Publishing setup (one-time, on pypi.org):
+#   1. pypi.org -> Account -> Publishing -> "Add pending publisher"
+#   2. Fill in:
+#        GitHub owner:            Rahul-git23
+#        Repository name:         spendguard
+#        Workflow filename:       publish-spendguard.yml
+#        Environment name:        pypi
+#   3. Save. No token or secret needed.
+#
+# GitHub Environment setup (one-time, in this repo):
+#   Settings -> Environments -> New environment -> name it "pypi"
+#   Optional: add yourself as Required reviewer for manual approval.
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    if: startsWith(github.ref_name, 'spendguard-v')
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package + dev deps
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: python -m pytest --tb=short -q
+
+  build:
+    name: Build distribution
+    if: startsWith(github.ref_name, 'spendguard-v')
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Verify tag matches pyproject.toml version
+        run: |
+          python -c "
+          import re, sys
+          tag = '${{ github.ref_name }}'
+          with open('pyproject.toml') as f:
+              content = f.read()
+          m = re.search(r'^\s*version\s*=\s*\"([^\"]+)\"', content, re.MULTILINE)
+          version = m.group(1)
+          expected = 'spendguard-v' + version
+          if tag != expected:
+              print('ERROR: tag', tag, 'does not match version', version)
+              sys.exit(1)
+          print('OK: tag', tag, 'matches version', version)
+          "
+      - name: Install build
+        run: pip install build twine
+      - name: Build wheel and sdist
+        run: python -m build
+      - name: Check dist
+        run: python -m twine check dist/*
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: spendguard-dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    if: startsWith(github.ref_name, 'spendguard-v')
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: spendguard-dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

spendguard-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.pypirc
+*.pyc
+.DS_Store

spendguard-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,118 @@
+# 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/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "spendguard"
+version = "0.1.0"
+description = "A 2-line wrapper around your OpenAI or Anthropic client that blocks an over-budget API call before it happens."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Rahul Vichare", email = "rahulvichare@gmail.com" },
+]
+keywords = ["openai", "anthropic", "llm", "cost", "budget", "guardrail", "ai"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "openai>=1.0.0",
+    "anthropic>=0.25.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0.0"]
+tiktoken = ["tiktoken>=0.5.0"]
+
+[project.urls]
+Homepage = "https://github.com/Rahul-git23/spendguard"
+Repository = "https://github.com/Rahul-git23/spendguard"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/spendguard"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+

spendguard-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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]