tknmtr 1.0.0

Token Meter - Lossless Prompt Optimizer for LLMs

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.

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

# 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:

# 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

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

# 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:

uvicorn tknmtr.api:app --reload

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

REST API

# 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:

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

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

# Run tests
pytest

# Lint
ruff check src/

# Type check
mypy src/

License

MIT License - see LICENSE

---

Made with 🫀 by Francisco Vozzi