Metadata-Version: 2.4
Name: tokenable
Version: 1.0.0
Summary: FinOps CLI for LLM API costs: scan code, estimate token spend, and block over-budget PRs.
Project-URL: Homepage, https://github.com/pardhusrepo/tokenable
Project-URL: Repository, https://github.com/pardhusrepo/tokenable
Project-URL: Issues, https://github.com/pardhusrepo/tokenable/issues
Author: TokEnable Contributors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai,cli,cost,finops,llm,tokens
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: gitpython<4.0,>=3.1.40
Requires-Dist: httpx<1.0,>=0.27.0
Requires-Dist: pydantic<3.0,>=2.6.0
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: rich<14.0,>=13.7.0
Requires-Dist: tiktoken<1.0,>=0.7.0
Requires-Dist: typer<1.0,>=0.12.0
Provides-Extra: all
Requires-Dist: mypy<2.0,>=1.8; extra == 'all'
Requires-Dist: opentelemetry-api<2.0,>=1.22.0; extra == 'all'
Requires-Dist: opentelemetry-sdk<2.0,>=1.22.0; extra == 'all'
Requires-Dist: pytest-asyncio<1.0,>=0.23.0; extra == 'all'
Requires-Dist: pytest-cov<6.0,>=5.0; extra == 'all'
Requires-Dist: pytest<9.0,>=8.0; extra == 'all'
Requires-Dist: ruff<1.0,>=0.4.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy<2.0,>=1.8; extra == 'dev'
Requires-Dist: pytest-asyncio<1.0,>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov<6.0,>=5.0; extra == 'dev'
Requires-Dist: pytest<9.0,>=8.0; extra == 'dev'
Requires-Dist: ruff<1.0,>=0.4.0; extra == 'dev'
Provides-Extra: telemetry
Requires-Dist: opentelemetry-api<2.0,>=1.22.0; extra == 'telemetry'
Requires-Dist: opentelemetry-sdk<2.0,>=1.22.0; extra == 'telemetry'
Description-Content-Type: text/markdown

# TokEnable

[![PyPI](https://img.shields.io/pypi/v/tokenable)](https://pypi.org/project/tokenable/)
[![Python](https://img.shields.io/pypi/pyversions/tokenable)](https://pypi.org/project/tokenable/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![CI](https://github.com/pardhusrepo/tokenable/actions/workflows/ci.yml/badge.svg)](https://github.com/pardhusrepo/tokenable/actions)

**FinOps CLI for LLM API costs.** Scan code, estimate token spend, recommend cheaper models, and block over-budget PRs.

---

## Quick Start

```bash
pip install tokenable
tokenable estimate .
```

```
┌──────────────────────────────────────────────────────────────────────────┐
│                          TokEnable Estimate                                │
├─────────────┬──────┬───────────┬──────────────────┬─────────┬────────────┤
│ File        │ Line │ Provider  │ Model            │ $/call  │ $/month    │
├─────────────┼──────┼───────────┼──────────────────┼─────────┼────────────┤
│ src/chat.py │   42 │ anthropic │ claude-opus-4-6  │ $0.0450 │ $45.00     │
│ src/sum.py  │   15 │ openai    │ gpt-4o           │ $0.0035 │  $3.50     │
└─────────────┴──────┴───────────┴──────────────────┴─────────┴────────────┘
Total estimated monthly cost: $48.50
```

## Features

| Feature | Description |
|---------|-------------|
| **Code Scanner** | Detects LLM API calls in `.py`, `.ts`, `.js` files |
| **Cost Estimation** | Projects monthly costs from token counts and pricing data |
| **Smart Recommendations** | Suggests cheaper models with equivalent capabilities |
| **Auto-Fix** | Rewrites model IDs in source files automatically |
| **Budget Enforcement** | Pre-commit hooks and CI gates for cost control |
| **MCP Integration** | AI agent tools via Model Context Protocol |
| **Calibration** | Corrects estimates with real provider usage data |
| **Multi-Provider** | Anthropic, OpenAI, Google, xAI, Perplexity |

## CLI Commands

```bash
tokenable estimate .                    # Estimate costs
tokenable check . --max-monthly-cost 500  # CI budget gate
tokenable audit .                       # Find savings opportunities
tokenable fix . --dry-run               # Preview model swaps
tokenable diff . --base main            # Cost diff between branches
tokenable price anthropic claude-sonnet-4-6  # Look up pricing
tokenable calibrate . --provider openai # Calibrate from production
tokenable init                          # Set up config + hooks
tokenable update-pricing                # Refresh pricing data (--dynamic for live)
```

## CI Integration

```yaml
# .github/workflows/tokenable.yml
- run: pip install tokenable
- run: tokenable check . --max-monthly-cost 500
```

Fails the build if estimated costs exceed your budget. See [CI Integration docs](docs/ci-integration.md).

## Pricing Updates

TokEnable ships with bundled pricing data updated each release. For the latest prices:

```bash
tokenable update-pricing              # Refresh from static provider data
tokenable update-pricing --dynamic    # Fetch live prices from LiteLLM community DB
```

A [GitHub Actions workflow](.github/workflows/sync-pricing.yml) runs daily to keep pricing in sync automatically.

## MCP for AI Agents

TokEnable runs as an MCP server for Claude Code, Cursor, and other AI agents:

```json
{
  "mcpServers": {
    "tokenable": {
      "command": "python",
      "args": ["-m", "tokenable.mcp"]
    }
  }
}
```

Tools: `suggest_model`, `estimate_cost`, `audit`, `apply_recommendations`. See [MCP docs](docs/mcp-integration.md).

## Configuration

Create `tokenable.config.json`:

```json
{
  "defaultVolume": 1000,
  "ignore": ["**/test/**"],
  "overrides": [
    { "pattern": "src/batch/**", "volume": 50000 }
  ],
  "budgets": {
    "block": 0.05,
    "maxMonthlyCost": 500
  }
}
```

## Supported Providers

| Provider | Example Models |
|----------|---------------|
| Anthropic | claude-opus-4-6, claude-sonnet-4-6, claude-haiku-3-5 |
| OpenAI | gpt-4o, gpt-4o-mini, o3, o3-mini |
| Google | gemini-3.1-pro-preview, gemini-2.5-flash |
| xAI | grok-3, grok-3-mini |
| Perplexity | sonar-pro, sonar-reasoning-pro, sonar |

Full list: [Supported Models](docs/supported-models.md)

## Documentation

- [Installation](docs/installation.md)
- [Quick Start](docs/quick-start.md)
- [CLI Reference](docs/cli-reference.md)
- [Supported Models](docs/supported-models.md)
- [CI Integration](docs/ci-integration.md)
- [MCP Integration](docs/mcp-integration.md)
- [FAQ](docs/faq.md)
- [Contributing](docs/contributing.md)

## Development

```bash
git clone https://github.com/pardhusrepo/tokenable.git
cd tokenable
pip install -e '.[dev]'
make test
```

## License

Apache-2.0
