token-budget-contracts 0.1.0__tar.gz

token_budget_contracts-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Swaranshu Borgaonkar
+
+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.

token_budget_contracts-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: token-budget-contracts
+Version: 0.1.0
+Summary: Priority-weighted, confidence-gated token budget governance for multi-agent LLM systems.
+Project-URL: Homepage, https://github.com/swaranshu-borgaonkar/Research_TBC
+Project-URL: Repository, https://github.com/swaranshu-borgaonkar/Research_TBC
+Author: Swaranshu Borgaonkar
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,budget,crewai,langgraph,llm,multi-agent,orchestration,tokens
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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
+Provides-Extra: accurate-tokenizer
+Requires-Dist: tiktoken>=0.5; extra == 'accurate-tokenizer'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Token Budget Contracts (`tbcontracts`)
+
+Priority-weighted, confidence-gated token budget governance for
+multi-agent LLM systems.
+
+When a multi-agent system (a planner spawning a researcher, a writer, a
+critic, etc.) is running, every sub-agent burns tokens — and money. Most
+projects today either hardcode a flat cap per agent or don't budget at
+all, so an important agent can starve mid-task while a less important one
+sits on unused budget. `tbcontracts` fixes that by letting unused budget
+flow, in real time, from lower-priority or idle agents to whichever agent
+actually needs it right now — without ever starving the donor below a
+protected minimum reserve, and without ever letting tokens flow "uphill"
+from an important agent to a less important one.
+
+It also supports **confidence-gated spending**: once an agent reports a
+high-confidence result, further spending on that agent is automatically
+blocked, so you're not paying for retrieval the model didn't need.
+
+This implements the governance model described in U.S. Provisional
+Patent Application No. 64/081,925 ("Token Budget Contracts"), filed
+June 3, 2026, and published research (Zenodo DOI:
+10.5281/zenodo.20549509). The patent application is pending; this
+package's code is released under the MIT license. If you plan to use
+this commercially at scale, consult your own counsel on licensing terms.
+
+## Install
+
+```bash
+pip install token-budget-contracts
+```
+
+For more accurate token counting (OpenAI/Anthropic-style BPE tokenizer),
+install the optional extra:
+
+```bash
+pip install "token-budget-contracts[accurate-tokenizer]"
+```
+
+Without it, the library falls back to a lightweight word-count heuristic
+and has zero hard dependencies.
+
+## Quick start
+
+```python
+from tbcontracts import BudgetManager
+
+manager = BudgetManager()
+
+# Higher priority = more important. The researcher will be able to pull
+# spare budget from the lower-priority critic agent if it runs low.
+manager.register_agent("researcher", priority=3, max_tokens=4000)
+manager.register_agent("critic", priority=1, max_tokens=2000)
+
+@manager.govern("researcher")
+def call_researcher(prompt: str) -> str:
+    return my_llm_call(prompt)  # however you already call your LLM
+
+@manager.govern("critic")
+def call_critic(prompt: str) -> str:
+    return my_llm_call(prompt)
+
+call_researcher("find the latest figures on X")
+call_critic("check the researcher's claims")
+
+print(manager.report())
+# {'researcher': {'allocated': 4000, 'consumed': 312, 'remaining': 3688},
+#  'critic':     {'allocated': 2000, 'consumed': 88,  'remaining': 1912}}
+```
+
+## Confidence-gated spending
+
+```python
+manager.register_agent(
+    "fact_checker",
+    priority=2,
+    max_tokens=3000,
+    confidence_threshold=0.85,  # block further calls once this confident
+)
+
+@manager.govern("fact_checker", confidence_fn=lambda result: result["confidence"])
+def check_fact(claim: str) -> dict:
+    response = my_llm_call(claim)
+    return {"answer": response, "confidence": extract_confidence(response)}
+```
+
+Once `check_fact` returns a confidence at or above `0.85`, the next call
+to `check_fact` raises `BudgetExceededError` — the agent has already done
+its job well enough, so further spend isn't approved.
+
+## What happens when an agent runs out of budget
+
+1. `tbcontracts` estimates how many tokens the call used (or you can
+   call `manager.ledger.record(agent_name, exact_token_count)` directly
+   if your LLM provider returns real usage numbers).
+2. If the agent doesn't have enough remaining budget, the `Reallocator`
+   looks for spare capacity in other agents — starting with the
+   lowest-priority, most-idle ones — and pulls just enough to cover the
+   shortfall, never dipping a donor below its own `min_reserve`.
+3. If no combination of donors can cover the shortfall, a
+   `BudgetExceededError` is raised so you can handle it (retry, degrade
+   gracefully, alert, etc.) instead of silently overspending.
+
+## Exact accounting
+
+The built-in token estimate is good enough for budget *governance*
+decisions, but if you want exact dollar accounting, bypass the estimator
+and record real usage directly:
+
+```python
+response = my_llm_call(prompt)
+manager.ledger.record("researcher", response.usage.total_tokens)
+```
+
+## Project status
+
+This is an early, actively developed implementation of the Token Budget
+Contracts protocol. Issues and PRs welcome at the GitHub repository
+linked in the project metadata.
+
+## License
+
+MIT for the code in this package. See `LICENSE`. The underlying
+governance method is the subject of a pending U.S. patent application;
+see the note above.

token_budget_contracts-0.1.0/README.md

@@ -0,0 +1,125 @@
+# Token Budget Contracts (`tbcontracts`)
+
+Priority-weighted, confidence-gated token budget governance for
+multi-agent LLM systems.
+
+When a multi-agent system (a planner spawning a researcher, a writer, a
+critic, etc.) is running, every sub-agent burns tokens — and money. Most
+projects today either hardcode a flat cap per agent or don't budget at
+all, so an important agent can starve mid-task while a less important one
+sits on unused budget. `tbcontracts` fixes that by letting unused budget
+flow, in real time, from lower-priority or idle agents to whichever agent
+actually needs it right now — without ever starving the donor below a
+protected minimum reserve, and without ever letting tokens flow "uphill"
+from an important agent to a less important one.
+
+It also supports **confidence-gated spending**: once an agent reports a
+high-confidence result, further spending on that agent is automatically
+blocked, so you're not paying for retrieval the model didn't need.
+
+This implements the governance model described in U.S. Provisional
+Patent Application No. 64/081,925 ("Token Budget Contracts"), filed
+June 3, 2026, and published research (Zenodo DOI:
+10.5281/zenodo.20549509). The patent application is pending; this
+package's code is released under the MIT license. If you plan to use
+this commercially at scale, consult your own counsel on licensing terms.
+
+## Install
+
+```bash
+pip install token-budget-contracts
+```
+
+For more accurate token counting (OpenAI/Anthropic-style BPE tokenizer),
+install the optional extra:
+
+```bash
+pip install "token-budget-contracts[accurate-tokenizer]"
+```
+
+Without it, the library falls back to a lightweight word-count heuristic
+and has zero hard dependencies.
+
+## Quick start
+
+```python
+from tbcontracts import BudgetManager
+
+manager = BudgetManager()
+
+# Higher priority = more important. The researcher will be able to pull
+# spare budget from the lower-priority critic agent if it runs low.
+manager.register_agent("researcher", priority=3, max_tokens=4000)
+manager.register_agent("critic", priority=1, max_tokens=2000)
+
+@manager.govern("researcher")
+def call_researcher(prompt: str) -> str:
+    return my_llm_call(prompt)  # however you already call your LLM
+
+@manager.govern("critic")
+def call_critic(prompt: str) -> str:
+    return my_llm_call(prompt)
+
+call_researcher("find the latest figures on X")
+call_critic("check the researcher's claims")
+
+print(manager.report())
+# {'researcher': {'allocated': 4000, 'consumed': 312, 'remaining': 3688},
+#  'critic':     {'allocated': 2000, 'consumed': 88,  'remaining': 1912}}
+```
+
+## Confidence-gated spending
+
+```python
+manager.register_agent(
+    "fact_checker",
+    priority=2,
+    max_tokens=3000,
+    confidence_threshold=0.85,  # block further calls once this confident
+)
+
+@manager.govern("fact_checker", confidence_fn=lambda result: result["confidence"])
+def check_fact(claim: str) -> dict:
+    response = my_llm_call(claim)
+    return {"answer": response, "confidence": extract_confidence(response)}
+```
+
+Once `check_fact` returns a confidence at or above `0.85`, the next call
+to `check_fact` raises `BudgetExceededError` — the agent has already done
+its job well enough, so further spend isn't approved.
+
+## What happens when an agent runs out of budget
+
+1. `tbcontracts` estimates how many tokens the call used (or you can
+   call `manager.ledger.record(agent_name, exact_token_count)` directly
+   if your LLM provider returns real usage numbers).
+2. If the agent doesn't have enough remaining budget, the `Reallocator`
+   looks for spare capacity in other agents — starting with the
+   lowest-priority, most-idle ones — and pulls just enough to cover the
+   shortfall, never dipping a donor below its own `min_reserve`.
+3. If no combination of donors can cover the shortfall, a
+   `BudgetExceededError` is raised so you can handle it (retry, degrade
+   gracefully, alert, etc.) instead of silently overspending.
+
+## Exact accounting
+
+The built-in token estimate is good enough for budget *governance*
+decisions, but if you want exact dollar accounting, bypass the estimator
+and record real usage directly:
+
+```python
+response = my_llm_call(prompt)
+manager.ledger.record("researcher", response.usage.total_tokens)
+```
+
+## Project status
+
+This is an early, actively developed implementation of the Token Budget
+Contracts protocol. Issues and PRs welcome at the GitHub repository
+linked in the project metadata.
+
+## License
+
+MIT for the code in this package. See `LICENSE`. The underlying
+governance method is the subject of a pending U.S. patent application;
+see the note above.

token_budget_contracts-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "token-budget-contracts"
+version = "0.1.0"
+description = "Priority-weighted, confidence-gated token budget governance for multi-agent LLM systems."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Swaranshu Borgaonkar" }]
+keywords = ["llm", "agents", "tokens", "budget", "multi-agent", "orchestration", "langgraph", "crewai"]
+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",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.optional-dependencies]
+accurate-tokenizer = ["tiktoken>=0.5"]
+dev = ["pytest>=7.0", "build", "twine"]
+
+[project.urls]
+Homepage = "https://github.com/swaranshu-borgaonkar/Research_TBC"
+Repository = "https://github.com/swaranshu-borgaonkar/Research_TBC"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tbcontracts"]

token_budget_contracts-0.1.0/src/tbcontracts/__init__.py

@@ -0,0 +1,38 @@
+"""tbcontracts: priority-weighted, confidence-gated token budget
+governance for multi-agent LLM systems.
+
+Quick start:
+
+    from tbcontracts import BudgetManager
+
+    manager = BudgetManager()
+    manager.register_agent("researcher", priority=3, max_tokens=4000)
+    manager.register_agent("writer", priority=2, max_tokens=2000)
+
+    @manager.govern("researcher")
+    def call_researcher(prompt):
+        return my_llm_call(prompt)
+
+    call_researcher("find the latest figures on X")
+    print(manager.report())
+"""
+
+from .confidence_gate import ConfidenceGate
+from .contract import BudgetContract
+from .exceptions import BudgetExceededError, TBCError, UnknownAgentError
+from .ledger import Ledger
+from .manager import BudgetManager
+from .reallocator import Reallocator
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BudgetContract",
+    "Ledger",
+    "Reallocator",
+    "ConfidenceGate",
+    "BudgetManager",
+    "TBCError",
+    "BudgetExceededError",
+    "UnknownAgentError",
+]

token_budget_contracts-0.1.0/src/tbcontracts/confidence_gate.py

@@ -0,0 +1,33 @@
+"""Adaptive, confidence-gated spending decisions."""
+
+from typing import Optional
+
+from .contract import BudgetContract
+
+
+class ConfidenceGate:
+    """Decides whether an agent should be allowed to spend further tokens
+    based on how confident its most recent output was.
+
+    The idea: if an agent already produced a high-confidence answer, there
+    is no reason to let it keep spending tokens on additional retrieval or
+    reasoning. If it's still uncertain, further spend is justified.
+    """
+
+    @staticmethod
+    def allow_further_retrieval(contract: BudgetContract, confidence: Optional[float]) -> bool:
+        """Returns True if the agent should be allowed to keep spending.
+
+        - If the contract has no `confidence_threshold` configured,
+          gating is disabled and this always returns True.
+        - If no confidence score has been recorded yet (e.g. before the
+          agent's first call), this fails open and returns True, since
+          there's no signal yet to deny on.
+        - Otherwise, spending is allowed only while confidence remains
+          below the configured threshold.
+        """
+        if contract.confidence_threshold is None:
+            return True
+        if confidence is None:
+            return True
+        return confidence < contract.confidence_threshold

token_budget_contracts-0.1.0/src/tbcontracts/contract.py

@@ -0,0 +1,49 @@
+"""Budget contract definitions for individual agents."""
+
+from dataclasses import dataclass, field
+from typing import Optional
+import time
+
+
+@dataclass
+class BudgetContract:
+    """Defines the token budget rules for a single agent.
+
+    Attributes:
+        agent_name: Unique identifier for the agent.
+        priority: Relative importance (higher = more important). The
+            Reallocator only ever pulls spare tokens from agents whose
+            priority is less than or equal to the needy agent's priority,
+            so budget never flows "downhill" from an important agent to a
+            less important one.
+        max_tokens: The initial token allocation for this agent.
+        min_reserve: The minimum number of tokens this agent must always
+            keep, even when the Reallocator wants to pull from it.
+            Defaults to 10% of max_tokens.
+        confidence_threshold: Minimum model confidence (0-1) at which the
+            agent is considered "confident enough" and further spending is
+            blocked. Defaults to None (confidence gating disabled).
+        last_confidence: The most recent confidence score reported for
+            this agent, used internally by ConfidenceGate. Not meant to
+            be set directly; updated automatically by BudgetManager.govern.
+    """
+
+    agent_name: str
+    priority: int = 1
+    max_tokens: int = 1000
+    min_reserve: Optional[int] = None
+    confidence_threshold: Optional[float] = None
+    last_confidence: Optional[float] = field(default=None, repr=False)
+    created_at: float = field(default_factory=time.time)
+
+    def __post_init__(self):
+        if self.priority < 1:
+            raise ValueError("priority must be >= 1")
+        if self.max_tokens < 0:
+            raise ValueError("max_tokens must be >= 0")
+        if self.min_reserve is None:
+            self.min_reserve = int(self.max_tokens * 0.1)
+        if self.min_reserve < 0 or self.min_reserve > self.max_tokens:
+            raise ValueError("min_reserve must be between 0 and max_tokens")
+        if self.confidence_threshold is not None and not (0 <= self.confidence_threshold <= 1):
+            raise ValueError("confidence_threshold must be between 0 and 1")

token_budget_contracts-0.1.0/src/tbcontracts/exceptions.py

@@ -0,0 +1,24 @@
+"""Exceptions raised by tbcontracts."""
+
+
+class TBCError(Exception):
+    """Base exception for all tbcontracts errors."""
+
+
+class BudgetExceededError(TBCError):
+    """Raised when an agent attempts to spend beyond its available budget
+    and no further reallocation from other agents is possible.
+    """
+
+    def __init__(self, agent_name: str, requested: int, available: int):
+        self.agent_name = agent_name
+        self.requested = requested
+        self.available = available
+        super().__init__(
+            f"Agent '{agent_name}' requested {requested} tokens but only "
+            f"{available} were available even after attempting reallocation."
+        )
+
+
+class UnknownAgentError(TBCError):
+    """Raised when referencing an agent that was never registered."""

token_budget_contracts-0.1.0/src/tbcontracts/ledger.py

@@ -0,0 +1,72 @@
+"""Tracks live token consumption and allocation per agent."""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+import time
+
+
+@dataclass
+class LedgerEntry:
+    agent_name: str
+    tokens: int
+    timestamp: float
+    note: str = ""
+
+
+class Ledger:
+    """Tracks consumption and remaining budget for every registered agent.
+
+    This is the single source of truth the Reallocator and BudgetManager
+    read from and write to. Allocation totals can change over time (when
+    the Reallocator moves tokens between agents); consumption only ever
+    goes up.
+    """
+
+    def __init__(self):
+        self._allocated: Dict[str, int] = {}
+        self._consumed: Dict[str, int] = {}
+        self._history: List[LedgerEntry] = []
+
+    def register(self, agent_name: str, allocated_tokens: int) -> None:
+        self._allocated[agent_name] = allocated_tokens
+        self._consumed.setdefault(agent_name, 0)
+
+    def record(self, agent_name: str, tokens: int, note: str = "") -> None:
+        if agent_name not in self._allocated:
+            raise KeyError(f"Unknown agent '{agent_name}'. Register it first.")
+        self._consumed[agent_name] += tokens
+        self._history.append(LedgerEntry(agent_name, tokens, time.time(), note))
+
+    def remaining(self, agent_name: str) -> int:
+        return self._allocated[agent_name] - self._consumed[agent_name]
+
+    def consumed(self, agent_name: str) -> int:
+        return self._consumed[agent_name]
+
+    def allocated(self, agent_name: str) -> int:
+        return self._allocated[agent_name]
+
+    def adjust_allocation(self, agent_name: str, delta: int) -> None:
+        """Increase (delta > 0) or decrease (delta < 0) an agent's total
+        allocation. Used by the Reallocator to move budget between agents.
+        """
+        self._allocated[agent_name] += delta
+
+    def history(self, agent_name: Optional[str] = None) -> List[LedgerEntry]:
+        if agent_name is None:
+            return list(self._history)
+        return [e for e in self._history if e.agent_name == agent_name]
+
+    def snapshot(self) -> Dict[str, Dict[str, int]]:
+        """A point-in-time view of every agent's allocated/consumed/
+        remaining tokens. Useful for building a dashboard or printing a
+        summary report.
+        """
+        return {
+            name: {
+                "allocated": self._allocated[name],
+                "consumed": self._consumed[name],
+                "remaining": self.remaining(name),
+            }
+            for name in self._allocated
+        }

token_budget_contracts-0.1.0/src/tbcontracts/manager.py

@@ -0,0 +1,121 @@
+"""High-level orchestrator tying contracts, ledger, reallocation, and
+confidence gating together behind a simple decorator API.
+"""
+
+import functools
+from typing import Callable, Dict, Optional
+
+from .confidence_gate import ConfidenceGate
+from .contract import BudgetContract
+from .exceptions import BudgetExceededError, UnknownAgentError
+from .ledger import Ledger
+from .reallocator import Reallocator
+from .tokenizer import estimate_tokens
+
+
+class BudgetManager:
+    """The main entry point for tbcontracts.
+
+    Example:
+        manager = BudgetManager()
+        manager.register_agent("researcher", priority=3, max_tokens=4000)
+        manager.register_agent("writer", priority=2, max_tokens=2000)
+
+        @manager.govern("researcher")
+        def call_researcher(prompt: str) -> str:
+            return my_llm_call(prompt)
+
+        call_researcher("find the latest figures on X")
+        print(manager.report())
+    """
+
+    def __init__(self):
+        self.contracts: Dict[str, BudgetContract] = {}
+        self.ledger = Ledger()
+        self.reallocator = Reallocator(self.contracts, self.ledger)
+
+    def register_agent(
+        self,
+        agent_name: str,
+        priority: int = 1,
+        max_tokens: int = 1000,
+        min_reserve: Optional[int] = None,
+        confidence_threshold: Optional[float] = None,
+    ) -> BudgetContract:
+        """Register a new agent and its budget contract. Returns the
+        created BudgetContract for inspection if needed."""
+        contract = BudgetContract(
+            agent_name=agent_name,
+            priority=priority,
+            max_tokens=max_tokens,
+            min_reserve=min_reserve,
+            confidence_threshold=confidence_threshold,
+        )
+        self.contracts[agent_name] = contract
+        self.ledger.register(agent_name, max_tokens)
+        return contract
+
+    def govern(self, agent_name: str, confidence_fn: Optional[Callable] = None):
+        """Decorator that meters every call a function makes against the
+        named agent's budget contract.
+
+        Behavior on each call:
+          1. Checks the ConfidenceGate - if the agent was already
+             confident enough on its last call, the call is blocked.
+          2. Runs the wrapped function.
+          3. Estimates tokens used (input + output) and records it.
+          4. If the agent doesn't have enough budget left, asks the
+             Reallocator to pull spare tokens from lower/equal priority
+             agents before raising BudgetExceededError.
+
+        `confidence_fn`, if provided, is called with the wrapped
+        function's return value and should return a float between 0 and 1
+        representing how confident that result was. It's stored on the
+        agent's contract and used by the ConfidenceGate on the *next*
+        call to decide whether further spending is justified.
+        """
+        if agent_name not in self.contracts:
+            raise UnknownAgentError(f"Agent '{agent_name}' was never registered.")
+
+        def decorator(fn: Callable):
+            @functools.wraps(fn)
+            def wrapper(*args, **kwargs):
+                contract = self.contracts[agent_name]
+
+                if not ConfidenceGate.allow_further_retrieval(contract, contract.last_confidence):
+                    raise BudgetExceededError(
+                        agent_name,
+                        requested=0,
+                        available=self.ledger.remaining(agent_name),
+                    )
+
+                result = fn(*args, **kwargs)
+
+                tokens_used = estimate_tokens(args, kwargs, result)
+                remaining = self.ledger.remaining(agent_name)
+
+                if tokens_used > remaining:
+                    shortfall = tokens_used - remaining
+                    recovered = self.reallocator.reallocate(agent_name, shortfall)
+                    if recovered < shortfall:
+                        raise BudgetExceededError(
+                            agent_name,
+                            requested=tokens_used,
+                            available=remaining + recovered,
+                        )
+
+                self.ledger.record(agent_name, tokens_used, note=fn.__name__)
+
+                if confidence_fn is not None:
+                    contract.last_confidence = confidence_fn(result)
+
+                return result
+
+            return wrapper
+
+        return decorator
+
+    def report(self) -> dict:
+        """A snapshot of every agent's allocated/consumed/remaining
+        tokens. Useful for building a dashboard or printing a summary."""
+        return self.ledger.snapshot()

token_budget_contracts-0.1.0/src/tbcontracts/reallocator.py

@@ -0,0 +1,78 @@
+"""Priority-weighted dynamic token reallocation across agents.
+
+This is the core mechanism of Token Budget Contracts: instead of every
+agent being stuck with a fixed, isolated cap, spare budget from
+lower-priority or idle agents can flow to a higher-priority agent that's
+running low, in real time, without ever dropping a donor below its own
+protected minimum reserve.
+"""
+
+from typing import Dict, List
+
+from .contract import BudgetContract
+from .ledger import Ledger
+
+
+class Reallocator:
+    """Moves unused token budget between agents according to priority.
+
+    Rules:
+      1. A donor never gives up tokens below its own `min_reserve`.
+      2. Tokens only ever flow from an agent with priority <= the needy
+         agent's priority. Budget never flows "downhill" from a more
+         important agent to a less important one.
+      3. Among eligible donors, the lowest-priority / most-idle agents are
+         drained first.
+    """
+
+    def __init__(self, contracts: Dict[str, BudgetContract], ledger: Ledger):
+        self.contracts = contracts
+        self.ledger = ledger
+
+    def find_donors(self, exclude: str) -> List[str]:
+        """Agents with spare budget above their reserve, sorted so the
+        lowest-priority / most-idle agents are donated from first."""
+        donors = []
+        for name, contract in self.contracts.items():
+            if name == exclude:
+                continue
+            spare = self.ledger.remaining(name) - contract.min_reserve
+            if spare > 0:
+                donors.append(name)
+        donors.sort(key=lambda n: (self.contracts[n].priority, -self.ledger.remaining(n)))
+        return donors
+
+    def reallocate(self, needy_agent: str, shortfall: int) -> int:
+        """Attempt to cover `shortfall` tokens for `needy_agent` by pulling
+        spare budget from eligible donor agents. Returns the number of
+        tokens actually recovered, which may be less than `shortfall` if
+        no eligible donor has enough spare capacity.
+        """
+        if needy_agent not in self.contracts:
+            raise KeyError(f"Unknown agent '{needy_agent}'")
+        if shortfall <= 0:
+            return 0
+
+        needy_priority = self.contracts[needy_agent].priority
+        recovered = 0
+
+        for donor in self.find_donors(exclude=needy_agent):
+            if recovered >= shortfall:
+                break
+
+            donor_priority = self.contracts[donor].priority
+            if donor_priority > needy_priority:
+                # Never pull tokens from a more important agent.
+                continue
+
+            donor_contract = self.contracts[donor]
+            spare = self.ledger.remaining(donor) - donor_contract.min_reserve
+            take = min(spare, shortfall - recovered)
+            if take <= 0:
+                continue
+
+            self.ledger.adjust_allocation(donor, -take)
+            self.ledger.adjust_allocation(needy_agent, take)
+            recovered += take
+
+        return recovered

token_budget_contracts-0.1.0/src/tbcontracts/tokenizer.py

@@ -0,0 +1,44 @@
+"""Pluggable token estimation.
+
+Uses tiktoken if it's installed (accurate for OpenAI/Anthropic-style BPE
+tokenizers). Falls back to a simple word-count heuristic otherwise, so the
+library has zero hard dependencies out of the box.
+
+For exact accounting (e.g. real usage numbers returned by your LLM
+provider's API response), bypass this entirely and call
+`Ledger.record(agent_name, real_token_count)` directly instead of relying
+on the estimate.
+"""
+
+from typing import Any
+
+try:
+    import tiktoken
+
+    _ENCODER = tiktoken.get_encoding("cl100k_base")
+except Exception:  # pragma: no cover - exercised only when tiktoken absent
+    _ENCODER = None
+
+
+def _count(text: str) -> int:
+    if not text:
+        return 0
+    if _ENCODER is not None:
+        return len(_ENCODER.encode(text))
+    # Fallback heuristic: roughly 1.3 tokens per whitespace-separated word.
+    return max(1, int(len(text.split()) * 1.3))
+
+
+def estimate_tokens(args: tuple, kwargs: dict, result: Any) -> int:
+    """Rough token estimate covering both the input an agent was called
+    with and the output it produced."""
+    total = 0
+    for a in args:
+        if isinstance(a, str):
+            total += _count(a)
+    for v in kwargs.values():
+        if isinstance(v, str):
+            total += _count(v)
+    if isinstance(result, str):
+        total += _count(result)
+    return total

token_budget_contracts-0.1.0/tests/test_confidence_gate.py

@@ -0,0 +1,21 @@
+from tbcontracts import BudgetContract, ConfidenceGate
+
+
+def test_no_threshold_always_allows():
+    c = BudgetContract("a")
+    assert ConfidenceGate.allow_further_retrieval(c, confidence=0.1) is True
+
+
+def test_low_confidence_allows_more_retrieval():
+    c = BudgetContract("a", confidence_threshold=0.8)
+    assert ConfidenceGate.allow_further_retrieval(c, confidence=0.5) is True
+
+
+def test_high_confidence_blocks_further_retrieval():
+    c = BudgetContract("a", confidence_threshold=0.8)
+    assert ConfidenceGate.allow_further_retrieval(c, confidence=0.95) is False
+
+
+def test_missing_confidence_fails_open():
+    c = BudgetContract("a", confidence_threshold=0.8)
+    assert ConfidenceGate.allow_further_retrieval(c, confidence=None) is True

token_budget_contracts-0.1.0/tests/test_contract.py

@@ -0,0 +1,28 @@
+import pytest
+
+from tbcontracts import BudgetContract
+
+
+def test_default_min_reserve_is_ten_percent():
+    c = BudgetContract(agent_name="a", max_tokens=1000)
+    assert c.min_reserve == 100
+
+
+def test_explicit_min_reserve_respected():
+    c = BudgetContract(agent_name="a", max_tokens=1000, min_reserve=50)
+    assert c.min_reserve == 50
+
+
+def test_invalid_priority_raises():
+    with pytest.raises(ValueError):
+        BudgetContract(agent_name="a", priority=0)
+
+
+def test_invalid_confidence_threshold_raises():
+    with pytest.raises(ValueError):
+        BudgetContract(agent_name="a", confidence_threshold=1.5)
+
+
+def test_min_reserve_cannot_exceed_max_tokens():
+    with pytest.raises(ValueError):
+        BudgetContract(agent_name="a", max_tokens=100, min_reserve=200)

token_budget_contracts-0.1.0/tests/test_ledger.py

@@ -0,0 +1,43 @@
+import pytest
+
+from tbcontracts import Ledger
+
+
+def test_register_and_record():
+    ledger = Ledger()
+    ledger.register("a", 1000)
+    ledger.record("a", 200, note="call 1")
+    assert ledger.consumed("a") == 200
+    assert ledger.remaining("a") == 800
+
+
+def test_record_unknown_agent_raises():
+    ledger = Ledger()
+    with pytest.raises(KeyError):
+        ledger.record("ghost", 10)
+
+
+def test_adjust_allocation():
+    ledger = Ledger()
+    ledger.register("a", 1000)
+    ledger.adjust_allocation("a", -300)
+    assert ledger.allocated("a") == 700
+
+
+def test_snapshot():
+    ledger = Ledger()
+    ledger.register("a", 1000)
+    ledger.record("a", 400)
+    snap = ledger.snapshot()
+    assert snap["a"] == {"allocated": 1000, "consumed": 400, "remaining": 600}
+
+
+def test_history_filters_by_agent():
+    ledger = Ledger()
+    ledger.register("a", 1000)
+    ledger.register("b", 1000)
+    ledger.record("a", 100)
+    ledger.record("b", 50)
+    ledger.record("a", 25)
+    assert len(ledger.history("a")) == 2
+    assert len(ledger.history()) == 3

token_budget_contracts-0.1.0/tests/test_manager.py

@@ -0,0 +1,74 @@
+import pytest
+
+from tbcontracts import BudgetManager, BudgetExceededError, UnknownAgentError
+
+
+def test_govern_tracks_consumption():
+    manager = BudgetManager()
+    manager.register_agent("writer", priority=2, max_tokens=100)
+
+    @manager.govern("writer")
+    def call_writer(prompt):
+        return "a short reply"
+
+    call_writer("write something short")
+    snap = manager.report()
+    assert snap["writer"]["consumed"] > 0
+    assert snap["writer"]["remaining"] < 100
+
+
+def test_govern_reallocates_from_lower_priority_agent():
+    manager = BudgetManager()
+    manager.register_agent("researcher", priority=3, max_tokens=20, min_reserve=2)
+    manager.register_agent("helper", priority=1, max_tokens=500, min_reserve=10)
+
+    @manager.govern("researcher")
+    def call_researcher(prompt):
+        return (
+            "a fairly long generated response that will use more tokens "
+            "than the small budget allows for this particular agent"
+        )
+
+    # Should NOT raise: helper has plenty of spare budget to donate.
+    result = call_researcher("research something")
+    assert isinstance(result, str)
+    snap = manager.report()
+    assert snap["helper"]["allocated"] < 500  # tokens were pulled from it
+
+
+def test_govern_raises_when_no_budget_anywhere():
+    manager = BudgetManager()
+    manager.register_agent("solo", priority=1, max_tokens=5, min_reserve=0)
+
+    @manager.govern("solo")
+    def call_solo(prompt):
+        return "a fairly long generated response with way more tokens than five"
+
+    with pytest.raises(BudgetExceededError):
+        call_solo("go")
+
+
+def test_unregistered_agent_raises():
+    manager = BudgetManager()
+    with pytest.raises(UnknownAgentError):
+
+        @manager.govern("ghost")
+        def fn(prompt):
+            return "x"
+
+
+def test_confidence_gate_blocks_second_call_once_confident():
+    manager = BudgetManager()
+    manager.register_agent("checker", priority=1, max_tokens=1000, confidence_threshold=0.8)
+
+    @manager.govern("checker", confidence_fn=lambda result: 0.95)
+    def call_checker(prompt):
+        return "confident answer"
+
+    # First call succeeds and records confidence 0.95 afterwards.
+    call_checker("question 1")
+
+    # Second call should be blocked: 0.95 >= 0.8 means we're already
+    # confident enough, so no further spend is justified.
+    with pytest.raises(BudgetExceededError):
+        call_checker("question 2")

token_budget_contracts-0.1.0/tests/test_reallocator.py

@@ -0,0 +1,57 @@
+from tbcontracts import BudgetContract, Ledger, Reallocator
+
+
+def make_setup():
+    contracts = {
+        "researcher": BudgetContract("researcher", priority=3, max_tokens=1000, min_reserve=100),
+        "critic": BudgetContract("critic", priority=1, max_tokens=1000, min_reserve=100),
+    }
+    ledger = Ledger()
+    for name, c in contracts.items():
+        ledger.register(name, c.max_tokens)
+    return contracts, ledger
+
+
+def test_reallocate_pulls_from_lower_priority_idle_agent():
+    contracts, ledger = make_setup()
+    ledger.record("researcher", 950)  # only 50 left
+    reallocator = Reallocator(contracts, ledger)
+
+    recovered = reallocator.reallocate("researcher", shortfall=300)
+
+    assert recovered == 300
+    assert ledger.remaining("researcher") == 350  # 50 + 300, before consuming
+    assert ledger.allocated("critic") == 700  # 1000 - 300 taken
+
+
+def test_reallocate_never_dips_below_donor_reserve():
+    contracts, ledger = make_setup()
+    ledger.record("researcher", 950)
+    ledger.record("critic", 850)  # critic only has 150 spare above its 100 reserve
+    reallocator = Reallocator(contracts, ledger)
+
+    recovered = reallocator.reallocate("researcher", shortfall=300)
+
+    assert recovered == 50  # critic could only spare 150 - 100 reserve = 50
+    assert ledger.allocated("critic") == 950
+    assert ledger.remaining("critic") == 100  # exactly at reserve, never below
+
+
+def test_reallocate_does_not_pull_from_higher_priority_agent():
+    contracts, ledger = make_setup()
+    # critic (priority 1) is needy; researcher (priority 3) has spare, but
+    # tokens must never flow from a more important agent to a less
+    # important one.
+    ledger.record("critic", 950)
+    reallocator = Reallocator(contracts, ledger)
+
+    recovered = reallocator.reallocate("critic", shortfall=300)
+
+    assert recovered == 0
+    assert ledger.allocated("researcher") == 1000  # untouched
+
+
+def test_reallocate_zero_shortfall_is_noop():
+    contracts, ledger = make_setup()
+    reallocator = Reallocator(contracts, ledger)
+    assert reallocator.reallocate("researcher", shortfall=0) == 0