llm-tokencost 0.3.0__tar.gz

llm_tokencost-0.3.0/LICENSE

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

llm_tokencost-0.3.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: llm-tokencost
+Version: 0.3.0
+Summary: A lightweight Python library for tracking LLM API costs via litellm's callback system
+Author-email: Paawan Purdhani <paawanpurdhani@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Paawan13/tokencost
+Project-URL: Repository, https://github.com/Paawan13/tokencost
+Project-URL: Bug Tracker, https://github.com/Paawan13/tokencost/issues
+Keywords: llm,cost,tracking,token,budget,openai,anthropic,litellm
+Classifier: Development Status :: 4 - Beta
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: litellm>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Dynamic: license-file
+
+# tokencost
+
+A lightweight Python library for tracking LLM API costs via litellm's callback system, with budget alerts and spending limits.
+
+## Installation
+
+```bash
+pip install tokencost
+```
+
+## Quick Start
+
+```python
+import litellm
+from tokencost import CostTracker, BudgetExceededError
+
+# Create a tracker with a $5 budget
+def alert(tracker):
+    print(f"Budget exceeded! Spent ${tracker.total_cost:.2f}")
+
+tracker = CostTracker(
+    budget=5.00,
+    on_budget_exceeded=alert,
+    raise_on_budget=True
+)
+
+# Register with litellm
+litellm.callbacks = [tracker]
+
+# Make LLM calls as usual
+try:
+    response = litellm.completion(
+        model="gpt-4",
+        messages=[{"role": "user", "content": "Hello!"}]
+    )
+except BudgetExceededError as e:
+    print(f"Stopped at ${e.total_cost:.2f} (budget: ${e.budget:.2f})")
+
+# Check usage
+print(f"Total: ${tracker.total_cost:.4f} across {tracker.request_count} requests")
+```
+
+## Features
+
+- **Real-time cost tracking** during LLM calls
+- **Budget alerts** via callback and/or exception
+- **Async support** for `litellm.acompletion()`
+- **Per-model cost aggregation** via `cost_by_model` property
+- **Automatic exit summary** — prints cost report when program ends
+- **Thread-safe** for concurrent usage
+- **Uses litellm's pricing data** for accurate costs (1600+ models)
+
+## Async Support
+
+```python
+import asyncio
+import litellm
+from tokencost import CostTracker
+
+async def main():
+    tracker = CostTracker()
+    litellm.callbacks = [tracker]
+
+    # Works with async completions
+    response = await litellm.acompletion(
+        model="gpt-4",
+        messages=[{"role": "user", "content": "Hello!"}]
+    )
+
+    print(f"Cost: ${tracker.total_cost:.6f}")
+
+asyncio.run(main())
+```
+
+## Per-Model Cost Breakdown
+
+```python
+tracker = CostTracker()
+litellm.callbacks = [tracker]
+
+# Make calls to different models...
+litellm.completion(model="gpt-4", messages=[...])
+litellm.completion(model="gpt-3.5-turbo", messages=[...])
+litellm.completion(model="claude-3-sonnet", messages=[...])
+
+# Get cost breakdown by model
+for model, cost in tracker.cost_by_model.items():
+    print(f"{model}: ${cost:.6f}")
+```
+
+## API Reference
+
+### CostTracker
+
+```python
+CostTracker(
+    budget: float | None = None,           # Spending limit in USD
+    on_budget_exceeded: Callable | None = None,  # Callback when exceeded
+    raise_on_budget: bool = False,         # Raise exception when exceeded
+    print_summary: bool = True             # Print summary on program exit
+)
+```
+
+**Properties:**
+
+- `total_cost: float` — Running total in USD
+- `request_count: int` — Number of successful requests
+- `history: list[dict]` — All logged requests
+- `budget: float | None` — Configured budget
+- `budget_exceeded: bool` — Whether budget has been exceeded
+- `cost_by_model: dict[str, float]` — Cost aggregated by model name
+
+**Methods:**
+
+- `reset()` — Clear all tracked data
+
+### BudgetExceededError
+
+Raised when budget is exceeded (if `raise_on_budget=True`).
+
+```python
+class BudgetExceededError(Exception):
+    budget: float       # Configured budget
+    total_cost: float   # Actual spend when exceeded
+```
+
+## Exit Summary
+
+When your program ends, a cost summary is automatically printed:
+
+```
+==================================================
+LLM COST SUMMARY
+==================================================
+Total Cost:     $0.001959
+Total Requests: 4
+Budget:         $0.0100 (OK)
+Remaining:      $0.008041
+--------------------------------------------------
+Requests:
+  1. gpt-4: 7+18 tokens = $0.000750
+  2. gpt-4: 13+17 tokens = $0.000900
+  3. gpt-3.5-turbo: 8+82 tokens = $0.000166
+  4. gpt-3.5-turbo: 10+58 tokens = $0.000143
+==================================================
+```
+
+Disable with `print_summary=False`.
+
+## History Entry Format
+
+Each request is logged with:
+
+```python
+{
+    "model": "gpt-4",
+    "prompt_tokens": 150,
+    "completion_tokens": 50,
+    "cost": 0.0123,
+    "timestamp": "2026-02-22T10:30:00Z"
+}
+```
+
+## Development
+
+```bash
+git clone https://github.com/Paawan13/tokencost.git
+cd tokencost
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

llm_tokencost-0.3.0/README.md

@@ -0,0 +1,175 @@
+# tokencost
+
+A lightweight Python library for tracking LLM API costs via litellm's callback system, with budget alerts and spending limits.
+
+## Installation
+
+```bash
+pip install tokencost
+```
+
+## Quick Start
+
+```python
+import litellm
+from tokencost import CostTracker, BudgetExceededError
+
+# Create a tracker with a $5 budget
+def alert(tracker):
+    print(f"Budget exceeded! Spent ${tracker.total_cost:.2f}")
+
+tracker = CostTracker(
+    budget=5.00,
+    on_budget_exceeded=alert,
+    raise_on_budget=True
+)
+
+# Register with litellm
+litellm.callbacks = [tracker]
+
+# Make LLM calls as usual
+try:
+    response = litellm.completion(
+        model="gpt-4",
+        messages=[{"role": "user", "content": "Hello!"}]
+    )
+except BudgetExceededError as e:
+    print(f"Stopped at ${e.total_cost:.2f} (budget: ${e.budget:.2f})")
+
+# Check usage
+print(f"Total: ${tracker.total_cost:.4f} across {tracker.request_count} requests")
+```
+
+## Features
+
+- **Real-time cost tracking** during LLM calls
+- **Budget alerts** via callback and/or exception
+- **Async support** for `litellm.acompletion()`
+- **Per-model cost aggregation** via `cost_by_model` property
+- **Automatic exit summary** — prints cost report when program ends
+- **Thread-safe** for concurrent usage
+- **Uses litellm's pricing data** for accurate costs (1600+ models)
+
+## Async Support
+
+```python
+import asyncio
+import litellm
+from tokencost import CostTracker
+
+async def main():
+    tracker = CostTracker()
+    litellm.callbacks = [tracker]
+
+    # Works with async completions
+    response = await litellm.acompletion(
+        model="gpt-4",
+        messages=[{"role": "user", "content": "Hello!"}]
+    )
+
+    print(f"Cost: ${tracker.total_cost:.6f}")
+
+asyncio.run(main())
+```
+
+## Per-Model Cost Breakdown
+
+```python
+tracker = CostTracker()
+litellm.callbacks = [tracker]
+
+# Make calls to different models...
+litellm.completion(model="gpt-4", messages=[...])
+litellm.completion(model="gpt-3.5-turbo", messages=[...])
+litellm.completion(model="claude-3-sonnet", messages=[...])
+
+# Get cost breakdown by model
+for model, cost in tracker.cost_by_model.items():
+    print(f"{model}: ${cost:.6f}")
+```
+
+## API Reference
+
+### CostTracker
+
+```python
+CostTracker(
+    budget: float | None = None,           # Spending limit in USD
+    on_budget_exceeded: Callable | None = None,  # Callback when exceeded
+    raise_on_budget: bool = False,         # Raise exception when exceeded
+    print_summary: bool = True             # Print summary on program exit
+)
+```
+
+**Properties:**
+
+- `total_cost: float` — Running total in USD
+- `request_count: int` — Number of successful requests
+- `history: list[dict]` — All logged requests
+- `budget: float | None` — Configured budget
+- `budget_exceeded: bool` — Whether budget has been exceeded
+- `cost_by_model: dict[str, float]` — Cost aggregated by model name
+
+**Methods:**
+
+- `reset()` — Clear all tracked data
+
+### BudgetExceededError
+
+Raised when budget is exceeded (if `raise_on_budget=True`).
+
+```python
+class BudgetExceededError(Exception):
+    budget: float       # Configured budget
+    total_cost: float   # Actual spend when exceeded
+```
+
+## Exit Summary
+
+When your program ends, a cost summary is automatically printed:
+
+```
+==================================================
+LLM COST SUMMARY
+==================================================
+Total Cost:     $0.001959
+Total Requests: 4
+Budget:         $0.0100 (OK)
+Remaining:      $0.008041
+--------------------------------------------------
+Requests:
+  1. gpt-4: 7+18 tokens = $0.000750
+  2. gpt-4: 13+17 tokens = $0.000900
+  3. gpt-3.5-turbo: 8+82 tokens = $0.000166
+  4. gpt-3.5-turbo: 10+58 tokens = $0.000143
+==================================================
+```
+
+Disable with `print_summary=False`.
+
+## History Entry Format
+
+Each request is logged with:
+
+```python
+{
+    "model": "gpt-4",
+    "prompt_tokens": 150,
+    "completion_tokens": 50,
+    "cost": 0.0123,
+    "timestamp": "2026-02-22T10:30:00Z"
+}
+```
+
+## Development
+
+```bash
+git clone https://github.com/Paawan13/tokencost.git
+cd tokencost
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

llm_tokencost-0.3.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "llm-tokencost"
+version = "0.3.0"
+description = "A lightweight Python library for tracking LLM API costs via litellm's callback system"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+    {name = "Paawan Purdhani", email = "paawanpurdhani@gmail.com"},
+]
+keywords = ["llm", "cost", "tracking", "token", "budget", "openai", "anthropic", "litellm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "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",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = [
+    "litellm>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-asyncio>=0.21.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Paawan13/tokencost"
+Repository = "https://github.com/Paawan13/tokencost"
+"Bug Tracker" = "https://github.com/Paawan13/tokencost/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["tokencost*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+asyncio_mode = "auto"

llm_tokencost-0.3.0/setup.cfg

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

llm_tokencost-0.3.0/src/llm_tokencost.egg-info/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: llm-tokencost
+Version: 0.3.0
+Summary: A lightweight Python library for tracking LLM API costs via litellm's callback system
+Author-email: Paawan Purdhani <paawanpurdhani@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Paawan13/tokencost
+Project-URL: Repository, https://github.com/Paawan13/tokencost
+Project-URL: Bug Tracker, https://github.com/Paawan13/tokencost/issues
+Keywords: llm,cost,tracking,token,budget,openai,anthropic,litellm
+Classifier: Development Status :: 4 - Beta
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: litellm>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Dynamic: license-file
+
+# tokencost
+
+A lightweight Python library for tracking LLM API costs via litellm's callback system, with budget alerts and spending limits.
+
+## Installation
+
+```bash
+pip install tokencost
+```
+
+## Quick Start
+
+```python
+import litellm
+from tokencost import CostTracker, BudgetExceededError
+
+# Create a tracker with a $5 budget
+def alert(tracker):
+    print(f"Budget exceeded! Spent ${tracker.total_cost:.2f}")
+
+tracker = CostTracker(
+    budget=5.00,
+    on_budget_exceeded=alert,
+    raise_on_budget=True
+)
+
+# Register with litellm
+litellm.callbacks = [tracker]
+
+# Make LLM calls as usual
+try:
+    response = litellm.completion(
+        model="gpt-4",
+        messages=[{"role": "user", "content": "Hello!"}]
+    )
+except BudgetExceededError as e:
+    print(f"Stopped at ${e.total_cost:.2f} (budget: ${e.budget:.2f})")
+
+# Check usage
+print(f"Total: ${tracker.total_cost:.4f} across {tracker.request_count} requests")
+```
+
+## Features
+
+- **Real-time cost tracking** during LLM calls
+- **Budget alerts** via callback and/or exception
+- **Async support** for `litellm.acompletion()`
+- **Per-model cost aggregation** via `cost_by_model` property
+- **Automatic exit summary** — prints cost report when program ends
+- **Thread-safe** for concurrent usage
+- **Uses litellm's pricing data** for accurate costs (1600+ models)
+
+## Async Support
+
+```python
+import asyncio
+import litellm
+from tokencost import CostTracker
+
+async def main():
+    tracker = CostTracker()
+    litellm.callbacks = [tracker]
+
+    # Works with async completions
+    response = await litellm.acompletion(
+        model="gpt-4",
+        messages=[{"role": "user", "content": "Hello!"}]
+    )
+
+    print(f"Cost: ${tracker.total_cost:.6f}")
+
+asyncio.run(main())
+```
+
+## Per-Model Cost Breakdown
+
+```python
+tracker = CostTracker()
+litellm.callbacks = [tracker]
+
+# Make calls to different models...
+litellm.completion(model="gpt-4", messages=[...])
+litellm.completion(model="gpt-3.5-turbo", messages=[...])
+litellm.completion(model="claude-3-sonnet", messages=[...])
+
+# Get cost breakdown by model
+for model, cost in tracker.cost_by_model.items():
+    print(f"{model}: ${cost:.6f}")
+```
+
+## API Reference
+
+### CostTracker
+
+```python
+CostTracker(
+    budget: float | None = None,           # Spending limit in USD
+    on_budget_exceeded: Callable | None = None,  # Callback when exceeded
+    raise_on_budget: bool = False,         # Raise exception when exceeded
+    print_summary: bool = True             # Print summary on program exit
+)
+```
+
+**Properties:**
+
+- `total_cost: float` — Running total in USD
+- `request_count: int` — Number of successful requests
+- `history: list[dict]` — All logged requests
+- `budget: float | None` — Configured budget
+- `budget_exceeded: bool` — Whether budget has been exceeded
+- `cost_by_model: dict[str, float]` — Cost aggregated by model name
+
+**Methods:**
+
+- `reset()` — Clear all tracked data
+
+### BudgetExceededError
+
+Raised when budget is exceeded (if `raise_on_budget=True`).
+
+```python
+class BudgetExceededError(Exception):
+    budget: float       # Configured budget
+    total_cost: float   # Actual spend when exceeded
+```
+
+## Exit Summary
+
+When your program ends, a cost summary is automatically printed:
+
+```
+==================================================
+LLM COST SUMMARY
+==================================================
+Total Cost:     $0.001959
+Total Requests: 4
+Budget:         $0.0100 (OK)
+Remaining:      $0.008041
+--------------------------------------------------
+Requests:
+  1. gpt-4: 7+18 tokens = $0.000750
+  2. gpt-4: 13+17 tokens = $0.000900
+  3. gpt-3.5-turbo: 8+82 tokens = $0.000166
+  4. gpt-3.5-turbo: 10+58 tokens = $0.000143
+==================================================
+```
+
+Disable with `print_summary=False`.
+
+## History Entry Format
+
+Each request is logged with:
+
+```python
+{
+    "model": "gpt-4",
+    "prompt_tokens": 150,
+    "completion_tokens": 50,
+    "cost": 0.0123,
+    "timestamp": "2026-02-22T10:30:00Z"
+}
+```
+
+## Development
+
+```bash
+git clone https://github.com/Paawan13/tokencost.git
+cd tokencost
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

llm_tokencost-0.3.0/src/llm_tokencost.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/llm_tokencost.egg-info/PKG-INFO
+src/llm_tokencost.egg-info/SOURCES.txt
+src/llm_tokencost.egg-info/dependency_links.txt
+src/llm_tokencost.egg-info/requires.txt
+src/llm_tokencost.egg-info/top_level.txt
+src/tokencost/__init__.py
+src/tokencost/exceptions.py
+src/tokencost/py.typed
+src/tokencost/tracker.py
+tests/test_tracker.py

llm_tokencost-0.3.0/src/llm_tokencost.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

llm_tokencost-0.3.0/src/llm_tokencost.egg-info/requires.txt

@@ -0,0 +1,6 @@
+litellm>=1.0.0
+
+[dev]
+pytest>=7.0.0
+pytest-cov>=4.0.0
+pytest-asyncio>=0.21.0

llm_tokencost-0.3.0/src/llm_tokencost.egg-info/top_level.txt

@@ -0,0 +1 @@
+tokencost

llm_tokencost-0.3.0/src/tokencost/__init__.py

@@ -0,0 +1,7 @@
+"""LLM Cost Tracker - Track LLM API costs via litellm's callback system."""
+
+from .exceptions import BudgetExceededError
+from .tracker import CostTracker
+
+__version__ = "0.2.0"
+__all__ = ["CostTracker", "BudgetExceededError"]