Metadata-Version: 2.4
Name: tknmtr
Version: 1.1.0
Summary: Token Meter - Lossless Prompt Optimizer for LLMs
Project-URL: Homepage, https://github.com/franvozzi/tknmtr
Project-URL: Documentation, https://github.com/franvozzi/tknmtr#readme
Project-URL: Repository, https://github.com/franvozzi/tknmtr
Project-URL: Issues, https://github.com/franvozzi/tknmtr/issues
Author-email: TKNMTR <engineering@tknmtr.com>
License: MIT
License-File: LICENSE
Keywords: ai,cost-saving,llm,optimization,prompt,tokens
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Requires-Dist: anthropic>=0.18.0
Requires-Dist: google-generativeai>=0.3.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: litellm>=1.50.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: resend>=0.8.0
Requires-Dist: rich>=13.0.0
Requires-Dist: sentry-sdk>=1.40.0
Requires-Dist: spacy>=3.7.0
Requires-Dist: supabase>=2.3.0
Requires-Dist: tenacity>=8.2.0
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: upstash-redis>=0.16.0
Provides-Extra: all
Requires-Dist: fastapi>=0.109.0; extra == 'all'
Requires-Dist: mkdocs-material>=9.0.0; extra == 'all'
Requires-Dist: mkdocs>=1.5.0; extra == 'all'
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'all'
Requires-Dist: mypy>=1.0.0; extra == 'all'
Requires-Dist: pre-commit>=3.0.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'all'
Requires-Dist: pytest-cov>=4.0.0; extra == 'all'
Requires-Dist: pytest>=7.0.0; extra == 'all'
Requires-Dist: ruff>=0.1.0; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.27.0; extra == 'all'
Provides-Extra: api
Requires-Dist: fastapi>=0.109.0; extra == 'api'
Requires-Dist: uvicorn[standard]>=0.27.0; extra == 'api'
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.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: docs
Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'docs'
Description-Content-Type: text/markdown

# TKNMTR: Token Meter 🔢

> **Lossless Prompt Optimizer for LLMs**

> Context sync (2026-02-20): TKNMTR Auto is positioned as a **semantic, policy-driven, multi-provider gateway** (not a closed vendor "Auto" mode).

Reduce your LLM API costs by 30-50% by automatically compressing prompts while preserving semantic fidelity.

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- 🔧 **Multi-Provider Support** - Works with Gemini, OpenAI, and Claude
- 💰 **Cost Estimation** - Calculate savings across 30+ LLM models
- ✅ **Fidelity Verification** - Ensures optimized prompts preserve meaning
- 🚀 **Multiple Interfaces** - SDK, CLI, and REST API
- 📊 **Built-in Test Suite** - Validate optimization quality

## Auth Modes (important)

- `/v1/optimize` uses `x-api-key`
- `/v1/chat/completions` uses `Authorization: Bearer tkn_xxx`
- `/v1/billing/*` uses Supabase JWT Bearer user token

## Quick Start

### Installation

```bash
# From PyPI (when published)
pip install tknmtr

# From source
pip install -e .

# With API server
pip install -e ".[api]"

# With dev tools
pip install -e ".[dev]"
```

### Configuration

Create a `.env` file:

```env
# At least one API key required
GEMINI_API_KEY=your_gemini_key
OPENAI_API_KEY=your_openai_key      # Optional
ANTHROPIC_API_KEY=your_anthropic_key # Optional
```

## Usage

### Python SDK

```python
from tknmtr import TKNMTR

# Initialize
client = TKNMTR()

# Optimize a prompt
result = client.optimize("Hello! Can you please write me a Python script that reads a CSV file?")

print(result.optimized)        # "Write Python script: read CSV file."
print(f"{result.savings_pct}% saved")  # "42.5% saved"
print(result.fidelity)         # "PASS"

# Batch optimization
results = client.batch([
    "Please write me a query...",
    "Can you help me with..."
])

# List available models
models = client.list_models()
```

### Command Line

```bash
# Optimize a single prompt
tknmtr -p "Hello! Please write me a Python script..."

# Interactive REPL mode
tknmtr -i

# Optimize from file
tknmtr -f prompt.txt -o result.json

# Run test suite
tknmtr -l 3 -o results.json

# List available models and pricing
tknmtr --list-models

# Use specific provider and target model
tknmtr --provider openai -m claude-opus-4 -l 1
```

### Web UI

Start the server and open http://localhost:8000 in your browser:

```bash
uvicorn tknmtr.api:app --reload
```

The Web UI provides a modern interface for testing prompts with real-time optimization.

### REST API

```bash
# Start the server
uvicorn tknmtr.api:app --reload

# Or with docker
docker-compose up
```

**Endpoints:**

| Method | Path | Description |
|--------|------|-------------|
| POST | `/v1/optimize` | Optimize single prompt |
| POST | `/v1/batch` | Batch optimization |
| GET | `/v1/models` | List available models |
| GET | `/health` | Health check |

**Example request:**

```bash
curl -X POST http://localhost:8000/v1/optimize \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello! Please help me...", "target_model": "gpt-5.2"}'
```

## Supported Models (30+)

| Provider | Models |
|----------|--------|
| **OpenAI** | gpt-5.2, gpt-5-mini, gpt-5.3-codex |
| **Anthropic** | claude-opus-4.6, claude-sonnet-5, claude-haiku-4.5 |
| **Google** | gemini-3-pro, gemini-3-flash |
| **Mistral** | mistral-large-3, mistral-medium-3 |
| **DeepSeek** | deepseek-v3, deepseek-r1 |
| **xAI** | grok-2, grok-2-vision |
| **Meta** | llama-3.1-8b, llama-3.3-70b, llama-3.1-405b |

## How It Works

1. **Compression**: Uses an LLM to rewrite prompts more concisely
2. **Fidelity Check**: Another LLM verifies the meaning is preserved
3. **Token Counting**: Uses tiktoken for accurate token estimation
4. **Cost Calculation**: Estimates savings based on model pricing

## Why not just use provider "Auto"?

Provider "Auto" modes are usually black-box decisions inside a single ecosystem.
TKNMTR acts as a semantic gateway you control:

- **Multi-provider routing** (OpenAI, Anthropic, Gemini, etc.)
- **Transparent and configurable policies** based on workload intent
- **Unified auth, usage, and billing controls** at one gateway layer
- **Business-optimized decisions** (cost, latency, quality) instead of vendor-only optimization

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/

# Type check
mypy src/
```

## License

MIT License - see [LICENSE](LICENSE)

---

Made with 🫀 by Francisco Vozzi
