# Ecobench
[](https://pypi.org/project/ecobench/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/psf/black)
A comprehensive Python library for tracking LLM usage, costs, and environmental impact. Monitor your AI model consumption with detailed analytics and environmental metrics.
## Features
- **Easy Integration**: Simple API for tracking LLM usage in your applications
- **Cost Tracking**: Monitor API costs with support for input, output, and cached tokens
- **Environmental Impact**: Track energy consumption and water usage
- **Multiple Models**: Built-in support for popular models (GPT-4o, GPT-4o-mini, o3-mini, Mixtral-8x22B)
- **Custom Models**: Support for custom model configurations
- **Chain of Thought**: Support for CoT reasoning with token multipliers
## Installation
### From PyPI (Recommended)
```bash
pip install ecobench
```
### From Source
```bash
git clone https://github.com/ecobench/ecobench.git
cd ecobench
pip install -e .
```
### Development Installation
```bash
git clone https://github.com/ecobench/ecobench.git
cd ecobench
pip install -e ".[dev]"
```
## Quick Start
```python
from ecobench import Tracker
# Initialize tracker
tracker = Tracker("GPT-4o")
# Track usage
tracker.update_state(input_tokens=100, output_tokens=50, cached_tokens=20)
# Get summary
tracker.print_summary()
```
## Usage Examples
### Basic Usage
```python
from ecobench import Tracker
# Initialize tracker with GPT-4o
tracker = Tracker("GPT-4o")
# Track an API call
result = tracker.update_state(
input_tokens=100,
output_tokens=50,
cached_tokens=20
)
print(f"Cost: ${result['cost']:.4f}")
print(f"Energy: {result['energy_wh']:.4f} Wh")
```
### Running Examples
The library includes several example scripts:
```bash
# Simple model comparison
python examples/simple_comparison.py
# Comprehensive visualization
python examples/visualize_model_comparison.py
# Notebook integration
python examples/notebook_integration.py
```
### Integration with Chat Applications
```python
class ChatApp:
def __init__(self):
self.tracker = Tracker("GPT-4o")
def make_api_call(self, prompt, response, cached_tokens=0):
# Estimate tokens (in practice, get from API response)
input_tokens = len(prompt.split())
output_tokens = len(response.split())
# Track usage
result = self.tracker.update_state(
input_tokens=input_tokens,
output_tokens=output_tokens,
cached_tokens=cached_tokens
)
return response, result
```
### Model Comparison
```python
# Compare different models
tracker_gpt4o = Tracker("GPT-4o")
tracker_mini = Tracker("GPT-4o-mini")
result_gpt4o = tracker_gpt4o.update_state(input_tokens=1000, output_tokens=500)
result_mini = tracker_mini.update_state(input_tokens=1000, output_tokens=500)
print(f"GPT-4o cost: ${result_gpt4o['cost']:.4f}")
print(f"GPT-4o-mini cost: ${result_mini['cost']:.4f}")
```
### Custom Models
```python
from ecobench import Model, Tracker
# Create custom model
custom_model = Model(
name="Custom Model",
d_model=4096,
d_ff=11008,
layers=32,
num_query_heads=32,
cost_per_input_token=0.001/1000,
cost_per_output_token=0.002/1000,
cost_per_cache_token=0.0005/1000
)
# Use with tracker
tracker = Tracker(custom_model=custom_model)
```
## Available Models
- **GPT-4o**: OpenAI's flagship model
- **GPT-4o-mini**: Smaller, faster version of GPT-4o
- **o3-mini**: OpenAI's reasoning model with CoT support
- **Mixtral-8x22B**: Open-source MoE model
## API Reference
### Tracker
#### `__init__(model_name: str = "GPT-4o", custom_model: Model = None)`
Initialize tracker with a model.
#### `update_state(input_tokens: int, output_tokens: int, cached_tokens: int = 0, use_cot_reasoning: bool = False, cache_percent: float = None) -> dict`
Update tracker with new usage data.
#### `get_summary() -> dict`
Get summary of all tracked usage.
#### `print_summary()`
Print formatted summary to console.
#### `reset()`
Reset all tracking data.
## Environmental Impact
The library tracks:
- **Energy Consumption**: In Watt-hours (Wh)
- **Water Usage**: In liters
- **Carbon Footprint**: Through energy calculations
### Development Setup
1. Fork the repository
2. Clone your fork: `git clone https://github.com/yourusername/ecobench.git`
3. Install in development mode: `pip install -e ".[dev]"`
4. Run tests: `pytest`
5. Run linting: `flake8 src/ tests/`
6. Format code: `black src/ tests/`
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
```
## Support
- 📖 [Documentation](https://github.com/KnutOplandMoen/ecobench#readme)
- 🐛 [Bug Reports](https://github.com/KnutOplandMoen/ecobench/issues)
- 💬 [Discussions](https://github.com/KnutOplandMoen/ecobench/discussions)
- 📧 Email: knutomoe@stud.ntnu.no
Raw data
{
"_id": null,
"home_page": "https://github.com/KnutOplandMoen/ecobench",
"name": "ecobench",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Ecobench Team <contact@ecobench.dev>",
"keywords": "llm, tracking, cost, energy, environmental, monitoring, ai, machine-learning",
"author": "knut Opland Moen",
"author_email": "Ecobench Team <contact@ecobench.dev>",
"download_url": "https://files.pythonhosted.org/packages/bc/ae/009c3cfb997b94db7d11a324707bd634d9a5ee9dc944766c14b3d27bdda0/ecobench-1.0.1.tar.gz",
"platform": null,
"description": "# Ecobench\n\n[](https://pypi.org/project/ecobench/)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/psf/black)\n\nA comprehensive Python library for tracking LLM usage, costs, and environmental impact. Monitor your AI model consumption with detailed analytics and environmental metrics.\n\n## Features\n\n- **Easy Integration**: Simple API for tracking LLM usage in your applications\n- **Cost Tracking**: Monitor API costs with support for input, output, and cached tokens\n- **Environmental Impact**: Track energy consumption and water usage\n- **Multiple Models**: Built-in support for popular models (GPT-4o, GPT-4o-mini, o3-mini, Mixtral-8x22B)\n- **Custom Models**: Support for custom model configurations\n- **Chain of Thought**: Support for CoT reasoning with token multipliers\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install ecobench\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/ecobench/ecobench.git\ncd ecobench\npip install -e .\n```\n\n### Development Installation\n\n```bash\ngit clone https://github.com/ecobench/ecobench.git\ncd ecobench\npip install -e \".[dev]\"\n```\n\n## Quick Start\n\n```python\nfrom ecobench import Tracker\n\n# Initialize tracker\ntracker = Tracker(\"GPT-4o\")\n\n# Track usage\ntracker.update_state(input_tokens=100, output_tokens=50, cached_tokens=20)\n\n# Get summary\ntracker.print_summary()\n```\n\n## Usage Examples\n\n### Basic Usage\n\n```python\nfrom ecobench import Tracker\n\n# Initialize tracker with GPT-4o\ntracker = Tracker(\"GPT-4o\")\n\n# Track an API call\nresult = tracker.update_state(\n input_tokens=100,\n output_tokens=50,\n cached_tokens=20\n)\n\nprint(f\"Cost: ${result['cost']:.4f}\")\nprint(f\"Energy: {result['energy_wh']:.4f} Wh\")\n```\n\n### Running Examples\n\nThe library includes several example scripts:\n\n```bash\n# Simple model comparison\npython examples/simple_comparison.py\n\n# Comprehensive visualization\npython examples/visualize_model_comparison.py\n\n# Notebook integration\npython examples/notebook_integration.py\n```\n\n### Integration with Chat Applications\n\n```python\nclass ChatApp:\n def __init__(self):\n self.tracker = Tracker(\"GPT-4o\")\n \n def make_api_call(self, prompt, response, cached_tokens=0):\n # Estimate tokens (in practice, get from API response)\n input_tokens = len(prompt.split())\n output_tokens = len(response.split())\n \n # Track usage\n result = self.tracker.update_state(\n input_tokens=input_tokens,\n output_tokens=output_tokens,\n cached_tokens=cached_tokens\n )\n \n return response, result\n```\n\n### Model Comparison\n\n```python\n# Compare different models\ntracker_gpt4o = Tracker(\"GPT-4o\")\ntracker_mini = Tracker(\"GPT-4o-mini\")\n\nresult_gpt4o = tracker_gpt4o.update_state(input_tokens=1000, output_tokens=500)\nresult_mini = tracker_mini.update_state(input_tokens=1000, output_tokens=500)\n\nprint(f\"GPT-4o cost: ${result_gpt4o['cost']:.4f}\")\nprint(f\"GPT-4o-mini cost: ${result_mini['cost']:.4f}\")\n```\n\n### Custom Models\n\n```python\nfrom ecobench import Model, Tracker\n\n# Create custom model\ncustom_model = Model(\n name=\"Custom Model\",\n d_model=4096,\n d_ff=11008,\n layers=32,\n num_query_heads=32,\n cost_per_input_token=0.001/1000,\n cost_per_output_token=0.002/1000,\n cost_per_cache_token=0.0005/1000\n)\n\n# Use with tracker\ntracker = Tracker(custom_model=custom_model)\n```\n\n## Available Models\n\n- **GPT-4o**: OpenAI's flagship model\n- **GPT-4o-mini**: Smaller, faster version of GPT-4o\n- **o3-mini**: OpenAI's reasoning model with CoT support\n- **Mixtral-8x22B**: Open-source MoE model\n\n## API Reference\n\n### Tracker\n\n#### `__init__(model_name: str = \"GPT-4o\", custom_model: Model = None)`\nInitialize tracker with a model.\n\n#### `update_state(input_tokens: int, output_tokens: int, cached_tokens: int = 0, use_cot_reasoning: bool = False, cache_percent: float = None) -> dict`\nUpdate tracker with new usage data.\n\n#### `get_summary() -> dict`\nGet summary of all tracked usage.\n\n#### `print_summary()`\nPrint formatted summary to console.\n\n#### `reset()`\nReset all tracking data.\n\n## Environmental Impact\n\nThe library tracks:\n- **Energy Consumption**: In Watt-hours (Wh)\n- **Water Usage**: In liters\n- **Carbon Footprint**: Through energy calculations\n\n### Development Setup\n\n1. Fork the repository\n2. Clone your fork: `git clone https://github.com/yourusername/ecobench.git`\n3. Install in development mode: `pip install -e \".[dev]\"`\n4. Run tests: `pytest`\n5. Run linting: `flake8 src/ tests/`\n6. Format code: `black src/ tests/`\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n```\n\n## Support\n\n- \ud83d\udcd6 [Documentation](https://github.com/KnutOplandMoen/ecobench#readme)\n- \ud83d\udc1b [Bug Reports](https://github.com/KnutOplandMoen/ecobench/issues)\n- \ud83d\udcac [Discussions](https://github.com/KnutOplandMoen/ecobench/discussions)\n- \ud83d\udce7 Email: knutomoe@stud.ntnu.no\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python library for tracking LLM usage, costs, and environmental impact",
"version": "1.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/ecobench/ecobench/issues",
"Documentation": "https://github.com/ecobench/ecobench#readme",
"Homepage": "https://github.com/ecobench/ecobench",
"Repository": "https://github.com/ecobench/ecobench"
},
"split_keywords": [
"llm",
" tracking",
" cost",
" energy",
" environmental",
" monitoring",
" ai",
" machine-learning"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "62dab71ea794863f0da59b5d0e13e6de430f1d144442c8d2526662bb93f57301",
"md5": "8461ff952fc9dbb61b664c0851ba190f",
"sha256": "e402362482d8e604919cd5e65171061174e321b309796f2cbd1699f7cc14ab19"
},
"downloads": -1,
"filename": "ecobench-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8461ff952fc9dbb61b664c0851ba190f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 14713,
"upload_time": "2025-10-07T12:47:44",
"upload_time_iso_8601": "2025-10-07T12:47:44.595300Z",
"url": "https://files.pythonhosted.org/packages/62/da/b71ea794863f0da59b5d0e13e6de430f1d144442c8d2526662bb93f57301/ecobench-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bcae009c3cfb997b94db7d11a324707bd634d9a5ee9dc944766c14b3d27bdda0",
"md5": "679d833af7427c9c432204f75690b02e",
"sha256": "c23cce2187313844585e5fd5308e712192d49cbd30b5cc0fdc567820db296d45"
},
"downloads": -1,
"filename": "ecobench-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "679d833af7427c9c432204f75690b02e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 29533,
"upload_time": "2025-10-07T12:47:45",
"upload_time_iso_8601": "2025-10-07T12:47:45.825270Z",
"url": "https://files.pythonhosted.org/packages/bc/ae/009c3cfb997b94db7d11a324707bd634d9a5ee9dc944766c14b3d27bdda0/ecobench-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-07 12:47:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "KnutOplandMoen",
"github_project": "ecobench",
"github_not_found": true,
"lcname": "ecobench"
}
JSON
