shekel 0.1.0__tar.gz

shekel-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[all,dev]"
+
+      - name: Format check (black)
+        run: black --check .
+
+      - name: Import sort check (isort)
+        run: isort --check-only .
+
+      - name: Lint (ruff)
+        run: ruff check .
+
+      - name: Type check (mypy)
+        run: mypy shekel/
+
+      - name: Test (pytest)
+        run: pytest tests/ -v --cov=shekel --cov-report=xml
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        if: matrix.python-version == '3.11'
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false

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

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build
+        run: pip install build
+
+      - name: Build
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

shekel-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+dist/
+build/
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.env
+*.egg
+.venv/
+venv/
+.coverage
+coverage.xml
+htmlcov/

shekel-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2024-03-08
+
+### Added
+- `budget()` context manager with sync and async support
+- `BudgetExceededError` with spend/limit/model/token details
+- Monkey-patching for OpenAI `ChatCompletions.create` (sync + async + streaming)
+- Monkey-patching for Anthropic `Messages.create` (sync + async + streaming)
+- `ContextVar`-based isolation for thread-safe and async-safe budget tracking
+- Ref-counted patching (only patches once for nested contexts)
+- `warn_at` threshold with optional `on_exceed` callback
+- `price_per_1k_tokens` override for custom/unlisted models
+- Built-in pricing for 10 models (GPT-4o, GPT-4o-mini, o1, o1-mini, GPT-3.5-turbo, Claude 3.5 Sonnet, Claude 3 Haiku, Claude 3 Opus, Gemini 1.5 Flash, Gemini 1.5 Pro)
+- Track-only mode (`budget()` with no `max_usd`)
+- LangGraph integration example
+
+[Unreleased]: https://github.com/arieradle/shekel/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/arieradle/shekel/releases/tag/v0.1.0

shekel-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing to shekel
+
+Thanks for your interest in contributing!
+
+## Setup
+
+```bash
+git clone https://github.com/arieradle/shekel
+cd shekel
+pip install -e ".[all,dev]"
+```
+
+## Running checks
+
+```bash
+black .                  # format
+isort .                  # sort imports
+ruff check .             # lint
+mypy shekel/             # type check
+pytest tests/ -v         # run tests
+pytest tests/ --cov=shekel --cov-report=term-missing  # with coverage
+```
+
+## Adding a model
+
+Edit `shekel/prices.json` and add an entry:
+
+```json
+"model-name": {"input_per_1k": 0.001, "output_per_1k": 0.003}
+```
+
+Add a test in `tests/test_pricing.py` to verify the new model's cost calculation.
+
+## Pull requests
+
+- Keep PRs focused — one change per PR
+- Add tests for new behaviour
+- All CI checks must pass
+- Update `CHANGELOG.md` under `[Unreleased]`
+
+## Reporting bugs
+
+Open an issue at https://github.com/arieradle/shekel/issues with:
+- Python version
+- shekel version (`python -c "import shekel; print(shekel.__version__)"`)
+- Minimal reproduction

shekel-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Arie Radle
+
+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.

shekel-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: shekel
+Version: 0.1.0
+Summary: LLM cost tracking and budget enforcement. Zero config — with budget(max_usd=1.00): run_agent(). Works with LangGraph, CrewAI, raw OpenAI/Anthropic.
+Project-URL: Homepage, https://github.com/arieradle/shekel
+Project-URL: Repository, https://github.com/arieradle/shekel
+Project-URL: Issues, https://github.com/arieradle/shekel/issues
+Project-URL: Changelog, https://github.com/arieradle/shekel/blob/main/CHANGELOG.md
+Author-email: Arie Radle <arie.radle@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2024 Arie Radle
+        
+        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.
+License-File: LICENSE
+Keywords: agent budget,anthropic spend enforcement,crewai cost control,langchain cost enforcement,langgraph budget,llm budget,llm cost tracking,llm spend limit,openai budget limit
+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
+Provides-Extra: all
+Requires-Dist: anthropic>=0.7.0; extra == 'all'
+Requires-Dist: openai>=1.0.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.7.0; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: isort>=5.12.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+[![PyPI version](https://badge.fury.io/py/shekel.svg)](https://badge.fury.io/py/shekel)
+[![Python versions](https://img.shields.io/pypi/pyversions/shekel.svg)](https://pypi.org/project/shekel/)
+[![CI](https://github.com/arieradle/shekel/actions/workflows/ci.yml/badge.svg)](https://github.com/arieradle/shekel/actions/workflows/ci.yml)
+
+```python
+with budget(max_usd=1.00):
+    run_my_agent()  # raises BudgetExceededError if spend exceeds $1.00
+```
+
+I spent $47 debugging a LangGraph retry loop. The agent kept failing, LangGraph kept retrying, and OpenAI kept charging — all while I slept. I built shekel so you don't have to learn that lesson yourself.
+
+---
+
+## Install
+
+```bash
+pip install shekel[openai]      # OpenAI only
+pip install shekel[anthropic]   # Anthropic only
+pip install shekel[all]         # Both SDKs
+```
+
+*Advanced: `pip install shekel` installs the core with no SDK deps (track-only mode).*
+
+---
+
+## Quick start
+
+```python
+from shekel import budget, BudgetExceededError
+import openai
+
+client = openai.OpenAI()
+
+try:
+    with budget(max_usd=1.00, warn_at=0.8) as b:
+        response = client.chat.completions.create(
+            model="gpt-4o",
+            messages=[{"role": "user", "content": "Hello!"}],
+        )
+    print(f"Spent: ${b.spent:.4f} of ${b.limit:.2f}")
+except BudgetExceededError as e:
+    print(e)
+```
+
+---
+
+## Track-only mode
+
+No `max_usd` = track spend without enforcing a limit. Great for profiling agents.
+
+```python
+with budget() as b:
+    run_my_agent()
+
+print(f"That run cost: ${b.spent:.4f}")
+```
+
+---
+
+## How it works
+
+- **Monkey-patching**: When you enter a `budget()` context, shekel wraps `openai.ChatCompletions.create` and `anthropic.Messages.create` at the class level. Your code calls the real SDK — shekel intercepts the response, reads the token counts, and calculates cost. On context exit, original methods are restored.
+- **ContextVar isolation**: Each `budget()` context tracks its own spend using Python's `contextvars.ContextVar`. Two concurrent agent runs never share a budget counter, even in async or multi-threaded code.
+- **Zero config**: No API keys, no external services, no config files. `pip install` + `with budget(...)` is all you need.
+
+---
+
+## Model support
+
+| Model | Input (per 1k) | Output (per 1k) |
+|-------|---------------|-----------------|
+| gpt-4o | $0.00250 | $0.01000 |
+| gpt-4o-mini | $0.000150 | $0.000600 |
+| o1 | $0.01500 | $0.06000 |
+| o1-mini | $0.00300 | $0.01200 |
+| gpt-3.5-turbo | $0.000500 | $0.001500 |
+| claude-3-5-sonnet-20241022 | $0.00300 | $0.01500 |
+| claude-3-haiku-20240307 | $0.000250 | $0.001250 |
+| claude-3-opus-20240229 | $0.01500 | $0.07500 |
+| gemini-1.5-flash | $0.0000750 | $0.000300 |
+| gemini-1.5-pro | $0.00125 | $0.00500 |
+
+**Model not listed?** Pass a price override:
+
+```python
+with budget(max_usd=1.00, price_per_1k_tokens={"input": 0.001, "output": 0.003}):
+    run_my_agent()
+```
+
+---
+
+## Works with LangGraph, CrewAI, and any framework
+
+shekel is framework-agnostic. It intercepts at the SDK level, so it works with anything that calls OpenAI or Anthropic under the hood:
+
+```python
+# LangGraph
+with budget(max_usd=2.00, warn_at=0.8) as b:
+    result = langgraph_app.invoke({"input": "..."})
+print(f"Graph run cost: ${b.spent:.4f}")
+
+# CrewAI
+with budget(max_usd=5.00) as b:
+    crew.kickoff()
+
+# Raw SDK
+with budget(max_usd=0.50) as b:
+    for _ in range(100):
+        client.chat.completions.create(...)  # stops when budget hit
+```
+
+---
+
+## License
+
+MIT

shekel-0.1.0/README.md

@@ -0,0 +1,116 @@
+[![PyPI version](https://badge.fury.io/py/shekel.svg)](https://badge.fury.io/py/shekel)
+[![Python versions](https://img.shields.io/pypi/pyversions/shekel.svg)](https://pypi.org/project/shekel/)
+[![CI](https://github.com/arieradle/shekel/actions/workflows/ci.yml/badge.svg)](https://github.com/arieradle/shekel/actions/workflows/ci.yml)
+
+```python
+with budget(max_usd=1.00):
+    run_my_agent()  # raises BudgetExceededError if spend exceeds $1.00
+```
+
+I spent $47 debugging a LangGraph retry loop. The agent kept failing, LangGraph kept retrying, and OpenAI kept charging — all while I slept. I built shekel so you don't have to learn that lesson yourself.
+
+---
+
+## Install
+
+```bash
+pip install shekel[openai]      # OpenAI only
+pip install shekel[anthropic]   # Anthropic only
+pip install shekel[all]         # Both SDKs
+```
+
+*Advanced: `pip install shekel` installs the core with no SDK deps (track-only mode).*
+
+---
+
+## Quick start
+
+```python
+from shekel import budget, BudgetExceededError
+import openai
+
+client = openai.OpenAI()
+
+try:
+    with budget(max_usd=1.00, warn_at=0.8) as b:
+        response = client.chat.completions.create(
+            model="gpt-4o",
+            messages=[{"role": "user", "content": "Hello!"}],
+        )
+    print(f"Spent: ${b.spent:.4f} of ${b.limit:.2f}")
+except BudgetExceededError as e:
+    print(e)
+```
+
+---
+
+## Track-only mode
+
+No `max_usd` = track spend without enforcing a limit. Great for profiling agents.
+
+```python
+with budget() as b:
+    run_my_agent()
+
+print(f"That run cost: ${b.spent:.4f}")
+```
+
+---
+
+## How it works
+
+- **Monkey-patching**: When you enter a `budget()` context, shekel wraps `openai.ChatCompletions.create` and `anthropic.Messages.create` at the class level. Your code calls the real SDK — shekel intercepts the response, reads the token counts, and calculates cost. On context exit, original methods are restored.
+- **ContextVar isolation**: Each `budget()` context tracks its own spend using Python's `contextvars.ContextVar`. Two concurrent agent runs never share a budget counter, even in async or multi-threaded code.
+- **Zero config**: No API keys, no external services, no config files. `pip install` + `with budget(...)` is all you need.
+
+---
+
+## Model support
+
+| Model | Input (per 1k) | Output (per 1k) |
+|-------|---------------|-----------------|
+| gpt-4o | $0.00250 | $0.01000 |
+| gpt-4o-mini | $0.000150 | $0.000600 |
+| o1 | $0.01500 | $0.06000 |
+| o1-mini | $0.00300 | $0.01200 |
+| gpt-3.5-turbo | $0.000500 | $0.001500 |
+| claude-3-5-sonnet-20241022 | $0.00300 | $0.01500 |
+| claude-3-haiku-20240307 | $0.000250 | $0.001250 |
+| claude-3-opus-20240229 | $0.01500 | $0.07500 |
+| gemini-1.5-flash | $0.0000750 | $0.000300 |
+| gemini-1.5-pro | $0.00125 | $0.00500 |
+
+**Model not listed?** Pass a price override:
+
+```python
+with budget(max_usd=1.00, price_per_1k_tokens={"input": 0.001, "output": 0.003}):
+    run_my_agent()
+```
+
+---
+
+## Works with LangGraph, CrewAI, and any framework
+
+shekel is framework-agnostic. It intercepts at the SDK level, so it works with anything that calls OpenAI or Anthropic under the hood:
+
+```python
+# LangGraph
+with budget(max_usd=2.00, warn_at=0.8) as b:
+    result = langgraph_app.invoke({"input": "..."})
+print(f"Graph run cost: ${b.spent:.4f}")
+
+# CrewAI
+with budget(max_usd=5.00) as b:
+    crew.kickoff()
+
+# Raw SDK
+with budget(max_usd=0.50) as b:
+    for _ in range(100):
+        client.chat.completions.create(...)  # stops when budget hit
+```
+
+---
+
+## License
+
+MIT

shekel-0.1.0/examples/langgraph_demo.py

@@ -0,0 +1,59 @@
+# Requires: pip install shekel[openai] "langgraph>=0.2"
+"""
+Minimal LangGraph demo showing shekel budget enforcement.
+
+This example builds a simple one-node LangGraph that calls OpenAI,
+wrapped in a shekel budget context to track and cap spend.
+"""
+
+import os
+
+from shekel import BudgetExceededError, budget
+
+
+def main() -> None:
+    try:
+        import openai
+        from langgraph.graph import END, StateGraph  # type: ignore[import]
+        from typing_extensions import TypedDict
+    except ImportError as e:
+        print(f"Missing dependency: {e}")
+        print("Run: pip install shekel[openai] 'langgraph>=0.2' typing_extensions")
+        return
+
+    api_key = os.environ.get("OPENAI_API_KEY")
+    if not api_key:
+        print("Set OPENAI_API_KEY to run this demo.")
+        return
+
+    client = openai.OpenAI(api_key=api_key)
+
+    class State(TypedDict):
+        question: str
+        answer: str
+
+    def call_llm(state: State) -> State:
+        response = client.chat.completions.create(
+            model="gpt-4o-mini",
+            messages=[{"role": "user", "content": state["question"]}],
+            max_tokens=50,
+        )
+        return {"question": state["question"], "answer": response.choices[0].message.content}
+
+    graph = StateGraph(State)
+    graph.add_node("llm", call_llm)
+    graph.set_entry_point("llm")
+    graph.add_edge("llm", END)
+    app = graph.compile()
+
+    try:
+        with budget(max_usd=0.10, warn_at=0.8) as b:
+            result = app.invoke({"question": "What is 2+2?", "answer": ""})
+            print(f"Answer: {result['answer']}")
+            print(f"Spent: ${b.spent:.4f} / ${b.limit:.2f}")
+    except BudgetExceededError as e:
+        print(f"Budget exceeded: {e}")
+
+
+if __name__ == "__main__":
+    main()

shekel-0.1.0/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shekel"
+version = "0.1.0"
+description = "LLM cost tracking and budget enforcement. Zero config — with budget(max_usd=1.00): run_agent(). Works with LangGraph, CrewAI, raw OpenAI/Anthropic."
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Arie Radle", email = "arie.radle@gmail.com" }]
+requires-python = ">=3.9"
+keywords = [
+    "llm cost tracking",
+    "openai budget limit",
+    "anthropic spend enforcement",
+    "langchain cost enforcement",
+    "llm spend limit",
+    "agent budget",
+    "llm budget",
+    "langgraph budget",
+    "crewai cost control",
+]
+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",
+]
+# Zero hard dependencies — stdlib only
+dependencies = []
+
+[project.optional-dependencies]
+openai = ["openai>=1.0.0"]
+anthropic = ["anthropic>=0.7.0"]
+all = ["openai>=1.0.0", "anthropic>=0.7.0"]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+    "black>=23.0.0",
+    "isort>=5.12.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/arieradle/shekel"
+Repository = "https://github.com/arieradle/shekel"
+Issues = "https://github.com/arieradle/shekel/issues"
+Changelog = "https://github.com/arieradle/shekel/blob/main/CHANGELOG.md"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.black]
+line-length = 100
+target-version = ["py39"]
+
+[tool.isort]
+profile = "black"
+line_length = 100
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+warn_return_any = true
+warn_unused_configs = true

shekel-0.1.0/shekel/__init__.py

@@ -0,0 +1,5 @@
+from shekel._budget import Budget as budget
+from shekel.exceptions import BudgetExceededError
+
+__version__ = "0.1.0"
+__all__ = ["budget", "BudgetExceededError"]