tetherai-python 0.1.0a0__tar.gz → 0.1.6__tar.gz

tetherai_python-0.1.6/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: tetherai-python
+Version: 0.1.6
+Summary: AI budget guardrails for LLM applications
+Author-email: TetherAI Engineering <engineering@tetherai.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/tetherai/tetherai-python
+Project-URL: Repository, https://github.com/tetherai/tetherai-python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: tiktoken>=0.7.0
+Provides-Extra: crewai
+Requires-Dist: crewai>=1.0.0; extra == "crewai"
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.40.0; extra == "litellm"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-mock>=3.12; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: crewai>=1.0.0; extra == "dev"
+Requires-Dist: litellm>=1.40.0; extra == "dev"
+
+# TetherAI
+
+[![CI](https://github.com/tetherai/tetherai-python/actions/workflows/ci.yml/badge.svg)](https://github.com/tetherai/tetherai-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tetherai-python)](https://pypi.org/project/tetherai-python/)
+[![Python](https://img.shields.io/pypi/pyversions/tetherai-python)](https://pypi.org/project/tetherai-python/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+
+**Financial circuit breaker for AI agents. Stop runaway LLM costs before they happen.**
+
+AI agents don't crash when they fail — they loop, hallucinate, and retry. A stuck CrewAI crew can silently burn hundreds of dollars in LLM API calls over a weekend. Traditional monitoring tools like Datadog will show you an API cost spike on Monday morning. TetherAI kills the agent before it spends your money.
+
+<!-- TODO: Replace with asciinema embed or GIF -->
+<!-- Record with: asciinema rec demo.cast then upload to asciinema.org -->
+
+## Install
+
+```bash
+pip install tetherai-python
+```
+
+With CrewAI support:
+
+```bash
+pip install tetherai-python[crewai]
+```
+
+## Quick Start
+
+The `@enforce_budget` decorator wraps any function with budget guardrails:
+
+```python
+from tetherai import tether, BudgetExceededError
+import litellm
+
+
+@tether.enforce_budget(max_usd=0.05)
+def my_workflow():
+    for i in range(100):
+        response = litellm.completion(
+            model="gpt-4o-mini",
+            messages=[{"role": "user", "content": f"Count to {i}"}]
+        )
+        print(f"Call {i+1}: {response.choices[0].message.content[:50]}...")
+
+
+try:
+    my_workflow()
+except BudgetExceededError as e:
+    print(f"\n🛑 Stopped! Spent ${e.spent_usd:.4f} of ${e.budget_usd:.2f} budget")
+```
+
+Expected output:
+```
+Call 1: 0...
+Call 2: 0, 1...
+Call 3: 0, 1, 2...
+
+🛑 Stopped! Spent $0.0501 of $0.05 budget
+```
+
+## CrewAI Integration
+
+For CrewAI crews, use `protect_crew()` to wrap budget enforcement around the entire crew:
+
+```python
+from tetherai import protect_crew, BudgetExceededError
+from crewai import Agent, Task, Crew, Process
+
+researcher = Agent(
+    role="Research Analyst",
+    goal="Find comprehensive information on AI observability tools",
+    backstory="You are a thorough research analyst known for detailed analysis.",
+    verbose=True,
+)
+
+task = Task(
+    description="Research the competitive landscape of AI observability tools",
+    agent=researcher,
+)
+
+crew = Crew(agents=[researcher], tasks=[task], process=Process.sequential)
+
+protected_crew = protect_crew(crew, max_usd=0.10)
+
+try:
+    result = protected_crew.kickoff()
+except BudgetExceededError as e:
+    print(f"Budget exceeded: ${e.spent_usd:.2f} of ${e.budget_usd:.2f}")
+```
+
+## What Happens When Budget Is Exceeded
+
+When the budget is exceeded, TetherAI raises `BudgetExceededError` with details about the run:
+
+```json
+{
+  "run_id": "run_abc123",
+  "budget_usd": 0.10,
+  "spent_usd": 0.13,
+  "turns": 7,
+  "spans": [
+    {
+      "span_type": "llm_call",
+      "model": "gpt-4o-mini",
+      "input_tokens": 1250,
+      "output_tokens": 340,
+      "cost_usd": 0.0019,
+      "status": "ok"
+    }
+  ]
+}
+```
+
+## How It Works
+
+TetherAI patches `litellm.completion` at runtime to intercept every LLM call your agent makes. Before each call, it counts input tokens locally using tiktoken and checks the projected cost against your budget. If the budget would be exceeded, the call is blocked and a `BudgetExceededError` is raised. After each successful call, actual token usage from the LLM response is recorded for accurate cost tracking.
+
+## Supported Frameworks
+
+| Framework | Status | Integration |
+|-----------|--------|-------------|
+| CrewAI    | ✅ Supported | `protect_crew()` |
+| LiteLLM (direct) | ✅ Supported | `@enforce_budget` decorator |
+| LangChain | 🔜 Coming soon | — |
+| smolagents | 🔜 Coming soon | — |
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+Apache 2.0

tetherai_python-0.1.6/README.md

@@ -0,0 +1,133 @@
+# TetherAI
+
+[![CI](https://github.com/tetherai/tetherai-python/actions/workflows/ci.yml/badge.svg)](https://github.com/tetherai/tetherai-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tetherai-python)](https://pypi.org/project/tetherai-python/)
+[![Python](https://img.shields.io/pypi/pyversions/tetherai-python)](https://pypi.org/project/tetherai-python/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+
+**Financial circuit breaker for AI agents. Stop runaway LLM costs before they happen.**
+
+AI agents don't crash when they fail — they loop, hallucinate, and retry. A stuck CrewAI crew can silently burn hundreds of dollars in LLM API calls over a weekend. Traditional monitoring tools like Datadog will show you an API cost spike on Monday morning. TetherAI kills the agent before it spends your money.
+
+<!-- TODO: Replace with asciinema embed or GIF -->
+<!-- Record with: asciinema rec demo.cast then upload to asciinema.org -->
+
+## Install
+
+```bash
+pip install tetherai-python
+```
+
+With CrewAI support:
+
+```bash
+pip install tetherai-python[crewai]
+```
+
+## Quick Start
+
+The `@enforce_budget` decorator wraps any function with budget guardrails:
+
+```python
+from tetherai import tether, BudgetExceededError
+import litellm
+
+
+@tether.enforce_budget(max_usd=0.05)
+def my_workflow():
+    for i in range(100):
+        response = litellm.completion(
+            model="gpt-4o-mini",
+            messages=[{"role": "user", "content": f"Count to {i}"}]
+        )
+        print(f"Call {i+1}: {response.choices[0].message.content[:50]}...")
+
+
+try:
+    my_workflow()
+except BudgetExceededError as e:
+    print(f"\n🛑 Stopped! Spent ${e.spent_usd:.4f} of ${e.budget_usd:.2f} budget")
+```
+
+Expected output:
+```
+Call 1: 0...
+Call 2: 0, 1...
+Call 3: 0, 1, 2...
+
+🛑 Stopped! Spent $0.0501 of $0.05 budget
+```
+
+## CrewAI Integration
+
+For CrewAI crews, use `protect_crew()` to wrap budget enforcement around the entire crew:
+
+```python
+from tetherai import protect_crew, BudgetExceededError
+from crewai import Agent, Task, Crew, Process
+
+researcher = Agent(
+    role="Research Analyst",
+    goal="Find comprehensive information on AI observability tools",
+    backstory="You are a thorough research analyst known for detailed analysis.",
+    verbose=True,
+)
+
+task = Task(
+    description="Research the competitive landscape of AI observability tools",
+    agent=researcher,
+)
+
+crew = Crew(agents=[researcher], tasks=[task], process=Process.sequential)
+
+protected_crew = protect_crew(crew, max_usd=0.10)
+
+try:
+    result = protected_crew.kickoff()
+except BudgetExceededError as e:
+    print(f"Budget exceeded: ${e.spent_usd:.2f} of ${e.budget_usd:.2f}")
+```
+
+## What Happens When Budget Is Exceeded
+
+When the budget is exceeded, TetherAI raises `BudgetExceededError` with details about the run:
+
+```json
+{
+  "run_id": "run_abc123",
+  "budget_usd": 0.10,
+  "spent_usd": 0.13,
+  "turns": 7,
+  "spans": [
+    {
+      "span_type": "llm_call",
+      "model": "gpt-4o-mini",
+      "input_tokens": 1250,
+      "output_tokens": 340,
+      "cost_usd": 0.0019,
+      "status": "ok"
+    }
+  ]
+}
+```
+
+## How It Works
+
+TetherAI patches `litellm.completion` at runtime to intercept every LLM call your agent makes. Before each call, it counts input tokens locally using tiktoken and checks the projected cost against your budget. If the budget would be exceeded, the call is blocked and a `BudgetExceededError` is raised. After each successful call, actual token usage from the LLM response is recorded for accurate cost tracking.
+
+## Supported Frameworks
+
+| Framework | Status | Integration |
+|-----------|--------|-------------|
+| CrewAI    | ✅ Supported | `protect_crew()` |
+| LiteLLM (direct) | ✅ Supported | `@enforce_budget` decorator |
+| LangChain | 🔜 Coming soon | — |
+| smolagents | 🔜 Coming soon | — |
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+Apache 2.0

{tetherai_python-0.1.0a0 → tetherai_python-0.1.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tetherai-python"
-version = "0.1.0-alpha"
+version = "0.1.6"
 description = "AI budget guardrails for LLM applications"
 readme = "README.md"
 license = { text = "Apache-2.0" }

{tetherai_python-0.1.0a0 → tetherai_python-0.1.6}/src/tetherai/budget.py

@@ -49,16 +49,16 @@ class BudgetTracker:
         with self._lock:
             return self._spent_usd >= self.max_usd
 
-    def pre_check(self, estimated_input_cost: float) -> None:
+    def pre_check(self, estimated_cost: float, model: str = "unknown") -> None:
         with self._lock:
-            projected = self._spent_usd + estimated_input_cost
-            if projected > self.max_usd:
+            projected = self._spent_usd + estimated_cost
+            if projected >= self.max_usd:
                 raise BudgetExceededError(
-                    message=f"Budget exceeded: ${projected:.2f} > ${self.max_usd:.2f}",
+                    message=f"Budget exceeded: ${projected:.6f} >= ${self.max_usd:.6f}",
                     run_id=self.run_id,
                     budget_usd=self.max_usd,
                     spent_usd=projected,
-                    last_model="unknown",
+                    last_model=model,
                 )
 
     def record_call(
@@ -84,6 +84,9 @@ class BudgetTracker:
             self._spent_usd += cost_usd
             self._turn_count += 1
 
+            if self._spent_usd > self.max_usd:
+                self._spent_usd = self.max_usd
+
             self._calls.append(
                 CallRecord(
                     input_tokens=input_tokens,
@@ -94,9 +97,6 @@ class BudgetTracker:
                 )
             )
 
-            if self._spent_usd > self.max_usd:
-                self._spent_usd = self.max_usd
-
     def get_summary(self) -> dict[str, Any]:
         with self._lock:
             return {

{tetherai_python-0.1.0a0 → tetherai_python-0.1.6}/src/tetherai/circuit_breaker.py

@@ -83,6 +83,7 @@ def _run_with_budget(
         interceptor.deactivate()
         trace = trace_collector.end_trace()
         if trace and trace_export != "none":
+            trace.budget_summary = budget_tracker.get_summary()
             exporter = get_exporter(trace_export, config.trace_export_path)
             exporter.export(trace)
 
@@ -128,5 +129,6 @@ async def _run_with_budget_async(
         interceptor.deactivate()
         trace = trace_collector.end_trace()
         if trace and trace_export != "none":
+            trace.budget_summary = budget_tracker.get_summary()
             exporter = get_exporter(trace_export, config.trace_export_path)
             exporter.export(trace)

tetherai_python-0.1.6/src/tetherai/crewai/integration.py

@@ -0,0 +1,55 @@
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from crewai import Crew
+
+
+def _check_crewai_installed() -> None:
+    try:
+        import crewai  # noqa: F401
+    except ImportError:
+        raise ImportError(
+            "crewai is not installed. Install it with: pip install tetherai[crewai]"
+        ) from None
+
+
+class ProtectedCrew:
+    """Wrapper around CrewAI crew with budget enforcement."""
+
+    def __init__(
+        self,
+        crew: "Crew",
+        max_usd: float,
+        max_turns: int | None = None,
+        trace_export: str | None = None,
+    ):
+        from tetherai.circuit_breaker import enforce_budget
+
+        self._crew = crew
+        self._max_usd = max_usd
+        self._max_turns = max_turns
+
+        self.kickoff = enforce_budget(
+            max_usd=max_usd, max_turns=max_turns, trace_export=trace_export
+        )(crew.kickoff)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._crew, name)
+
+
+def protect_crew(
+    crew: "Crew",
+    max_usd: float,
+    max_turns: int | None = None,
+    trace_export: str | None = None,
+) -> ProtectedCrew:
+    _check_crewai_installed()
+    return ProtectedCrew(crew, max_usd, max_turns, trace_export)
+
+
+def tether_step_callback(step_output: Any) -> None:
+    pass
+
+
+def tether_task_callback(task_output: Any) -> None:
+    pass