tokenfence 0.1.0__tar.gz

tokenfence-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TokenFence Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tokenfence-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: tokenfence
+Version: 0.1.0
+Summary: Cost circuit breaker for AI agents — guard your OpenAI spend with automatic downgrade and kill switch.
+Author: TokenFence Team
+License: MIT
+Project-URL: Homepage, https://github.com/tokenfence/tokenfence-python
+Project-URL: Issues, https://github.com/tokenfence/tokenfence-python/issues
+Keywords: openai,cost,budget,ai,llm,guardrail
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30.0; extra == "anthropic"
+Provides-Extra: google
+Requires-Dist: google-generativeai>=0.7.0; extra == "google"
+Provides-Extra: all
+Requires-Dist: openai>=1.0.0; extra == "all"
+Requires-Dist: anthropic>=0.30.0; extra == "all"
+Requires-Dist: google-generativeai>=0.7.0; extra == "all"
+Dynamic: license-file
+
+# TokenFence
+
+Cost circuit breaker for AI agents. Guard your LLM spend with automatic model downgrade and kill switch. Supports OpenAI, Anthropic Claude, Google Gemini, and DeepSeek.
+
+## Install
+
+```bash
+pip install tokenfence[openai]
+```
+
+## Quick Start
+
+```python
+import openai
+from tokenfence import guard
+
+client = guard(
+    openai.OpenAI(),
+    budget='$0.50',
+    fallback='gpt-4o-mini',
+    on_limit='stop',
+)
+
+# Use exactly like a normal OpenAI client
+response = client.chat.completions.create(
+    model='gpt-4o',
+    messages=[{'role': 'user', 'content': 'Hello'}],
+)
+
+# Check spend
+print(client.tokenfence.spent)      # 0.0023
+print(client.tokenfence.remaining)  # 0.4977
+print(client.tokenfence.calls)      # 1
+```
+
+## Anthropic Claude
+
+```python
+import anthropic
+from tokenfence import guard
+
+client = guard(
+    anthropic.Anthropic(),
+    budget='$1.00',
+    fallback='claude-3-haiku-20240307',
+    on_limit='stop',
+)
+
+# Use exactly like a normal Anthropic client
+response = client.messages.create(
+    model='claude-3-5-sonnet-20241022',
+    max_tokens=1024,
+    messages=[{'role': 'user', 'content': 'Hello'}],
+)
+
+# Check spend
+print(client.tokenfence.spent)      # 0.00105
+print(client.tokenfence.remaining)  # 0.99895
+```
+
+## How It Works
+
+1. **Track** — every `chat.completions.create()` call records token usage and calculates cost.
+2. **Downgrade** — when cumulative spend hits the threshold (default 80% of budget), the model is transparently swapped to your fallback.
+3. **Kill switch** — when the budget is fully consumed:
+   - `on_limit='stop'` — returns a synthetic response explaining the budget was exceeded.
+   - `on_limit='warn'` — logs a warning but allows the call through.
+   - `on_limit='raise'` — raises `BudgetExceeded`.
+
+## API
+
+### `guard(client, *, budget, fallback=None, on_limit='stop', threshold=0.8)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `client` | `openai.OpenAI` | An OpenAI client instance |
+| `budget` | `str \| float` | Max spend — `'$0.50'` or `0.50` |
+| `fallback` | `str \| None` | Model to downgrade to when threshold is hit |
+| `on_limit` | `str` | `'stop'`, `'warn'`, or `'raise'` |
+| `threshold` | `float` | Fraction of budget at which downgrade kicks in (0.0–1.0) |
+
+### `client.tokenfence`
+
+| Attribute | Description |
+|-----------|-------------|
+| `.spent` | Total USD spent so far |
+| `.remaining` | USD remaining in budget |
+| `.calls` | Number of tracked API calls |
+| `.budget` | The configured budget |
+| `.reset()` | Reset spend tracking to zero |
+
+## License
+
+MIT

tokenfence-0.1.0/README.md

@@ -0,0 +1,94 @@
+# TokenFence
+
+Cost circuit breaker for AI agents. Guard your LLM spend with automatic model downgrade and kill switch. Supports OpenAI, Anthropic Claude, Google Gemini, and DeepSeek.
+
+## Install
+
+```bash
+pip install tokenfence[openai]
+```
+
+## Quick Start
+
+```python
+import openai
+from tokenfence import guard
+
+client = guard(
+    openai.OpenAI(),
+    budget='$0.50',
+    fallback='gpt-4o-mini',
+    on_limit='stop',
+)
+
+# Use exactly like a normal OpenAI client
+response = client.chat.completions.create(
+    model='gpt-4o',
+    messages=[{'role': 'user', 'content': 'Hello'}],
+)
+
+# Check spend
+print(client.tokenfence.spent)      # 0.0023
+print(client.tokenfence.remaining)  # 0.4977
+print(client.tokenfence.calls)      # 1
+```
+
+## Anthropic Claude
+
+```python
+import anthropic
+from tokenfence import guard
+
+client = guard(
+    anthropic.Anthropic(),
+    budget='$1.00',
+    fallback='claude-3-haiku-20240307',
+    on_limit='stop',
+)
+
+# Use exactly like a normal Anthropic client
+response = client.messages.create(
+    model='claude-3-5-sonnet-20241022',
+    max_tokens=1024,
+    messages=[{'role': 'user', 'content': 'Hello'}],
+)
+
+# Check spend
+print(client.tokenfence.spent)      # 0.00105
+print(client.tokenfence.remaining)  # 0.99895
+```
+
+## How It Works
+
+1. **Track** — every `chat.completions.create()` call records token usage and calculates cost.
+2. **Downgrade** — when cumulative spend hits the threshold (default 80% of budget), the model is transparently swapped to your fallback.
+3. **Kill switch** — when the budget is fully consumed:
+   - `on_limit='stop'` — returns a synthetic response explaining the budget was exceeded.
+   - `on_limit='warn'` — logs a warning but allows the call through.
+   - `on_limit='raise'` — raises `BudgetExceeded`.
+
+## API
+
+### `guard(client, *, budget, fallback=None, on_limit='stop', threshold=0.8)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `client` | `openai.OpenAI` | An OpenAI client instance |
+| `budget` | `str \| float` | Max spend — `'$0.50'` or `0.50` |
+| `fallback` | `str \| None` | Model to downgrade to when threshold is hit |
+| `on_limit` | `str` | `'stop'`, `'warn'`, or `'raise'` |
+| `threshold` | `float` | Fraction of budget at which downgrade kicks in (0.0–1.0) |
+
+### `client.tokenfence`
+
+| Attribute | Description |
+|-----------|-------------|
+| `.spent` | Total USD spent so far |
+| `.remaining` | USD remaining in budget |
+| `.calls` | Number of tracked API calls |
+| `.budget` | The configured budget |
+| `.reset()` | Reset spend tracking to zero |
+
+## License
+
+MIT

tokenfence-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tokenfence"
+version = "0.1.0"
+description = "Cost circuit breaker for AI agents — guard your OpenAI spend with automatic downgrade and kill switch."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    { name = "TokenFence Team" },
+]
+keywords = ["openai", "cost", "budget", "ai", "llm", "guardrail"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.optional-dependencies]
+openai = ["openai>=1.0.0"]
+anthropic = ["anthropic>=0.30.0"]
+google = ["google-generativeai>=0.7.0"]
+all = ["openai>=1.0.0", "anthropic>=0.30.0", "google-generativeai>=0.7.0"]
+
+[project.urls]
+Homepage = "https://github.com/tokenfence/tokenfence-python"
+Issues = "https://github.com/tokenfence/tokenfence-python/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

tokenfence-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tokenfence-0.1.0/src/tokenfence/__init__.py

@@ -0,0 +1,7 @@
+"""TokenFence — cost circuit breaker for AI agents."""
+
+from .exceptions import BudgetExceeded, TokenFenceError
+from .guard import guard
+
+__all__ = ["guard", "TokenFenceError", "BudgetExceeded"]
+__version__ = "0.1.0"

tokenfence-0.1.0/src/tokenfence/exceptions.py

@@ -0,0 +1,16 @@
+"""TokenFence exceptions."""
+
+
+class TokenFenceError(Exception):
+    """Base exception for all TokenFence errors."""
+
+
+class BudgetExceeded(TokenFenceError):
+    """Raised when the budget has been fully consumed and on_limit='raise'."""
+
+    def __init__(self, budget: float, spent: float) -> None:
+        self.budget = budget
+        self.spent = spent
+        super().__init__(
+            f"Budget of ${budget:.4f} exceeded (spent ${spent:.4f})"
+        )

tokenfence-0.1.0/src/tokenfence/guard.py

@@ -0,0 +1,353 @@
+"""Core ``guard()`` function — wraps an OpenAI client with cost controls."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Literal, Optional, Union
+
+from .exceptions import BudgetExceeded, TokenFenceError
+from .pricing import calculate_cost
+from .tracker import CostTracker
+
+logger = logging.getLogger("tokenfence")
+
+OnLimit = Literal["stop", "warn", "raise"]
+
+
+def _parse_budget(budget: Union[str, float, int]) -> float:
+    """Convert a budget value like ``'$0.50'`` or ``0.50`` to a float."""
+    if isinstance(budget, str):
+        cleaned = budget.strip().lstrip("$").strip()
+        try:
+            return float(cleaned)
+        except ValueError:
+            raise TokenFenceError(f"Invalid budget string: {budget!r}") from None
+    return float(budget)
+
+
+def guard(
+    client: Any,
+    *,
+    budget: Union[str, float, int],
+    fallback: Optional[str] = None,
+    on_limit: OnLimit = "stop",
+    threshold: float = 0.8,
+) -> Any:
+    """Wrap an OpenAI client with cost tracking and budget enforcement.
+
+    Args:
+        client: An ``openai.OpenAI`` (or compatible) client instance.
+        budget: Maximum spend in USD — accepts ``'$0.50'`` or ``0.50``.
+        fallback: Model name to downgrade to when the threshold is reached.
+        on_limit: Behaviour when the budget is exhausted —
+            ``'stop'`` returns a synthetic response,
+            ``'warn'`` logs a warning and allows the call,
+            ``'raise'`` raises :class:`BudgetExceeded`.
+        threshold: Fraction of the budget (0.0–1.0) at which to start
+            downgrading to the *fallback* model.
+
+    Returns:
+        A wrapped client that is a drop-in replacement for the original.
+    """
+    if on_limit not in ("stop", "warn", "raise"):
+        raise TokenFenceError(f"on_limit must be 'stop', 'warn', or 'raise', got {on_limit!r}")
+    if not 0.0 <= threshold <= 1.0:
+        raise TokenFenceError(f"threshold must be between 0.0 and 1.0, got {threshold!r}")
+
+    parsed_budget = _parse_budget(budget)
+    if parsed_budget <= 0:
+        raise TokenFenceError(f"budget must be positive, got {parsed_budget}")
+
+    tracker = CostTracker(budget=parsed_budget, threshold=threshold)
+
+    return _GuardedClient(
+        client=client,
+        tracker=tracker,
+        fallback=fallback,
+        on_limit=on_limit,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Internal proxy objects
+# ---------------------------------------------------------------------------
+
+class _GuardedClient:
+    """Transparent proxy around an OpenAI client."""
+
+    def __init__(
+        self,
+        client: Any,
+        tracker: CostTracker,
+        fallback: Optional[str],
+        on_limit: OnLimit,
+    ) -> None:
+        self._client = client
+        self._tracker = tracker
+        self._fallback = fallback
+        self._on_limit = on_limit
+
+    # Expose tracker as ``client.tokenfence``
+    @property
+    def tokenfence(self) -> CostTracker:
+        return self._tracker
+
+    # Intercept ``client.chat`` to return our guarded namespace (OpenAI)
+    @property
+    def chat(self) -> "_GuardedChat":
+        return _GuardedChat(self._client.chat, self._tracker, self._fallback, self._on_limit)
+
+    # Intercept ``client.messages`` for Anthropic-style clients
+    @property
+    def messages(self) -> "_GuardedAnthropicMessages":
+        return _GuardedAnthropicMessages(self._client.messages, self._tracker, self._fallback, self._on_limit)
+
+    # Pass everything else through to the real client
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._client, name)
+
+
+class _GuardedChat:
+    """Proxy for ``client.chat``."""
+
+    def __init__(self, chat: Any, tracker: CostTracker, fallback: Optional[str], on_limit: OnLimit) -> None:
+        self._chat = chat
+        self._tracker = tracker
+        self._fallback = fallback
+        self._on_limit = on_limit
+
+    @property
+    def completions(self) -> "_GuardedCompletions":
+        return _GuardedCompletions(self._chat.completions, self._tracker, self._fallback, self._on_limit)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._chat, name)
+
+
+class _GuardedCompletions:
+    """Proxy for ``client.chat.completions`` — intercepts ``create()``."""
+
+    def __init__(self, completions: Any, tracker: CostTracker, fallback: Optional[str], on_limit: OnLimit) -> None:
+        self._completions = completions
+        self._tracker = tracker
+        self._fallback = fallback
+        self._on_limit = on_limit
+
+    def create(self, **kwargs: Any) -> Any:
+        """Intercept ``chat.completions.create()`` with budget enforcement."""
+        tracker = self._tracker
+
+        # --- Kill switch: budget already exhausted before the call ----------
+        if tracker.budget_exceeded:
+            return self._handle_limit(kwargs)
+
+        # --- Auto-downgrade -------------------------------------------------
+        original_model = kwargs.get("model")
+        if tracker.should_downgrade and self._fallback and original_model != self._fallback:
+            logger.warning(
+                "TokenFence: spend $%.4f has reached %.0f%% of $%.4f budget — "
+                "downgrading from %s to %s",
+                tracker.spent,
+                tracker.usage_ratio * 100,
+                tracker.budget,
+                original_model,
+                self._fallback,
+            )
+            kwargs["model"] = self._fallback
+
+        # --- Make the real API call -----------------------------------------
+        response = self._completions.create(**kwargs)
+
+        # --- Track cost -----------------------------------------------------
+        model_used = kwargs.get("model", original_model) or ""
+        usage = getattr(response, "usage", None)
+        if usage is not None:
+            input_tokens = getattr(usage, "prompt_tokens", 0) or 0
+            output_tokens = getattr(usage, "completion_tokens", 0) or 0
+            cost = calculate_cost(model_used, input_tokens, output_tokens)
+            tracker.record(cost)
+        else:
+            tracker.record(0.0)
+
+        return response
+
+    # --- limit handling -----------------------------------------------------
+
+    def _handle_limit(self, kwargs: dict[str, Any]) -> Any:
+        tracker = self._tracker
+        if self._on_limit == "raise":
+            raise BudgetExceeded(budget=tracker.budget, spent=tracker.spent)
+
+        if self._on_limit == "warn":
+            logger.warning(
+                "TokenFence: budget of $%.4f exhausted (spent $%.4f) — allowing call anyway",
+                tracker.budget,
+                tracker.spent,
+            )
+            return self._completions.create(**kwargs)
+
+        # on_limit == "stop" — return a synthetic response
+        return _synthetic_response(tracker)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._completions, name)
+
+
+# ---------------------------------------------------------------------------
+# Anthropic ``client.messages.create()`` proxy
+# ---------------------------------------------------------------------------
+
+class _GuardedAnthropicMessages:
+    """Proxy for Anthropic ``client.messages`` — intercepts ``create()``."""
+
+    def __init__(self, messages: Any, tracker: CostTracker, fallback: Optional[str], on_limit: OnLimit) -> None:
+        self._messages = messages
+        self._tracker = tracker
+        self._fallback = fallback
+        self._on_limit = on_limit
+
+    def create(self, **kwargs: Any) -> Any:
+        """Intercept ``messages.create()`` with budget enforcement."""
+        tracker = self._tracker
+
+        # --- Kill switch: budget already exhausted --------------------------
+        if tracker.budget_exceeded:
+            return self._handle_limit(kwargs)
+
+        # --- Auto-downgrade -------------------------------------------------
+        original_model = kwargs.get("model")
+        if tracker.should_downgrade and self._fallback and original_model != self._fallback:
+            logger.warning(
+                "TokenFence: spend $%.4f has reached %.0f%% of $%.4f budget — "
+                "downgrading from %s to %s",
+                tracker.spent,
+                tracker.usage_ratio * 100,
+                tracker.budget,
+                original_model,
+                self._fallback,
+            )
+            kwargs["model"] = self._fallback
+
+        # --- Make the real API call -----------------------------------------
+        response = self._messages.create(**kwargs)
+
+        # --- Track cost (Anthropic usage format) ----------------------------
+        model_used = kwargs.get("model", original_model) or ""
+        usage = getattr(response, "usage", None)
+        if usage is not None:
+            input_tokens = getattr(usage, "input_tokens", 0) or 0
+            output_tokens = getattr(usage, "output_tokens", 0) or 0
+            cost = calculate_cost(model_used, input_tokens, output_tokens)
+            tracker.record(cost)
+        else:
+            tracker.record(0.0)
+
+        return response
+
+    def _handle_limit(self, kwargs: dict[str, Any]) -> Any:
+        tracker = self._tracker
+        if self._on_limit == "raise":
+            raise BudgetExceeded(budget=tracker.budget, spent=tracker.spent)
+
+        if self._on_limit == "warn":
+            logger.warning(
+                "TokenFence: budget of $%.4f exhausted (spent $%.4f) — allowing call anyway",
+                tracker.budget,
+                tracker.spent,
+            )
+            return self._messages.create(**kwargs)
+
+        # on_limit == "stop" — return a synthetic Anthropic-style response
+        return _synthetic_anthropic_response(tracker)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._messages, name)
+
+
+# ---------------------------------------------------------------------------
+# Synthetic response for on_limit='stop'
+# ---------------------------------------------------------------------------
+
+class _SyntheticUsage:
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+
+
+class _SyntheticMessage:
+    role: str = "assistant"
+    content: str = ""
+
+    def __init__(self, content: str) -> None:
+        self.content = content
+
+
+class _SyntheticChoice:
+    index: int = 0
+    finish_reason: str = "stop"
+    message: _SyntheticMessage
+
+    def __init__(self, message: _SyntheticMessage) -> None:
+        self.message = message
+
+
+class _SyntheticResponse:
+    """Mimics the shape of an OpenAI ``ChatCompletion`` enough for most code."""
+
+    id: str = "tokenfence-budget-exceeded"
+    object: str = "chat.completion"
+    model: str = "tokenfence"
+    usage: _SyntheticUsage
+
+    def __init__(self, tracker: CostTracker) -> None:
+        self.usage = _SyntheticUsage()
+        msg = _SyntheticMessage(
+            f"[TokenFence] Budget of ${tracker.budget:.2f} exceeded "
+            f"(spent ${tracker.spent:.4f}). Request blocked."
+        )
+        self.choices = [_SyntheticChoice(msg)]
+
+
+def _synthetic_response(tracker: CostTracker) -> _SyntheticResponse:
+    return _SyntheticResponse(tracker)
+
+
+# ---------------------------------------------------------------------------
+# Anthropic-style synthetic response for on_limit='stop'
+# ---------------------------------------------------------------------------
+
+class _SyntheticAnthropicUsage:
+    input_tokens: int = 0
+    output_tokens: int = 0
+
+
+class _SyntheticAnthropicContentBlock:
+    type: str = "text"
+    text: str = ""
+
+    def __init__(self, text: str) -> None:
+        self.type = "text"
+        self.text = text
+
+
+class _SyntheticAnthropicResponse:
+    """Mimics the shape of an Anthropic ``Message`` enough for most code."""
+
+    id: str = "tokenfence-budget-exceeded"
+    type: str = "message"
+    role: str = "assistant"
+    model: str = "tokenfence"
+    stop_reason: str = "end_turn"
+
+    def __init__(self, tracker: CostTracker) -> None:
+        self.usage = _SyntheticAnthropicUsage()
+        self.content = [
+            _SyntheticAnthropicContentBlock(
+                f"[TokenFence] Budget of ${tracker.budget:.2f} exceeded "
+                f"(spent ${tracker.spent:.4f}). Request blocked."
+            )
+        ]
+
+
+def _synthetic_anthropic_response(tracker: CostTracker) -> _SyntheticAnthropicResponse:
+    return _SyntheticAnthropicResponse(tracker)