Metadata-Version: 2.4
Name: tokengauge
Version: 0.3.2
Summary: Zero-config AI usage tracking — wrap any OpenAI/Anthropic/Gemini client and log to your TokenGauge dashboard
License: MIT
Keywords: ai,llm,openai,anthropic,gemini,token,usage,tracking,observability
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20; extra == "anthropic"
Provides-Extra: google
Requires-Dist: google-genai>=0.1; extra == "google"
Provides-Extra: all
Requires-Dist: openai>=1.0; extra == "all"
Requires-Dist: anthropic>=0.20; extra == "all"
Requires-Dist: google-genai>=0.1; extra == "all"

# TokenGauge SDK

Zero-config AI usage tracking + model recommendations. Wrap your existing OpenAI, Anthropic, or Google Gemini client with one line — every call is automatically logged to your [TokenGauge](https://tokengauge.onrender.com) dashboard. Or ask the SDK which model to use before you even make a call.

**Your API keys stay with you.** The SDK only reads token counts from API responses and sends them to TokenGauge. Nothing is proxied.

## Install

```bash
pip install tokengauge
```

## Quick start

1. Sign up at [tokengauge.onrender.com](https://tokengauge.onrender.com) and copy your SDK token from Settings.

2. Wrap your client:

```python
from tokengauge import TokenGauge
import openai

tw = TokenGauge(token="your-sdk-token")
client = tw.wrap(openai.OpenAI(api_key="sk-..."))

# Use exactly as before — usage appears on your dashboard automatically
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)
```

## Anthropic

```python
from tokengauge import TokenGauge
import anthropic

tw = TokenGauge(token="your-sdk-token")
client = tw.wrap(anthropic.Anthropic(api_key="sk-ant-..."))

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=256,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.content[0].text)
```

## Google Gemini

```python
from tokengauge import TokenGauge
from google import genai

tw = TokenGauge(token="your-sdk-token")
client = tw.wrap(genai.Client(api_key="your-gemini-key"))

response = client.models.generate_content(
    model="gemini-1.5-flash",
    contents="Hello!",
)
print(response.text)
```

## Async clients

```python
from tokengauge import TokenGauge
import openai, asyncio

tw = TokenGauge(token="your-sdk-token")
client = tw.wrap(openai.AsyncOpenAI(api_key="sk-..."))

async def main():
    response = await client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Hello!"}],
    )
    print(response.choices[0].message.content)

asyncio.run(main())
```

## Model recommendations

Not sure which model to use? `recommend_model()` classifies your prompt locally, estimates the cost, and scores every model by success probability — no API call required.

```python
tw = TokenGauge(token="your-sdk-token")

rec = tw.recommend_model(
    messages=[{"role": "user", "content": "Refactor this Python class to use dataclasses..."}],
    provider="anthropic",   # optional: also return best within this provider
    budget_usd=0.05,        # optional: exclude models above this cost estimate
)

print(rec["prompt_type"])                              # "code"
print(rec["complexity"])                               # 1–10 score
print(rec["best_overall"]["model"])                    # e.g. "claude-opus-4.6"
print(rec["best_overall"]["success_probability"])      # e.g. 1.0
print(rec["best_overall"]["estimated_cost_usd"])       # e.g. 0.00047
print(rec["within_provider"]["model"])                 # best Anthropic model
```

### What's returned

```python
{
  "prompt_type": "code",          # classified category
  "complexity": 4,                # estimated complexity 1–10
  "estimated_tokens_in": 312,     # rough token estimate
  "best_overall": {               # best model across all providers
    "model": "claude-opus-4.6",
    "provider": "anthropic",
    "quality_score": 10,
    "estimated_tokens_in": 312,
    "estimated_tokens_out": 124,
    "estimated_cost_usd": 0.00469,
    "success_probability": 1.0
  },
  "within_provider": { ... }      # best model within your preferred provider
}
```

### How it works

| Step | What happens |
|---|---|
| Classify | Prompt is matched against 8 categories: `code`, `chat`, `summarization`, `analysis`, `creative`, `extraction`, `translation`, `other` |
| Estimate | Token count estimated from text length (~4 chars/token); output estimated at 40% of input |
| Score | Each model gets a success probability based on its type-specific quality score minus a penalty for complexity above its ceiling |
| Rank | Models sorted by success probability, then cheapest on tie; budget filter applied if set |

Prompt text is **never sent anywhere** — classification runs entirely on your machine.

### Supported models in the registry

| Provider | Models |
|---|---|
| OpenAI | gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-4o, gpt-4o-mini, o3, o3-mini, o4-mini |
| Anthropic | claude-opus-4.6, claude-sonnet-4.6, claude-haiku-4-5, claude-3-7-sonnet, claude-3-5-sonnet, claude-3-5-haiku |
| Google | gemini-2.5-pro, gemini-2.5-flash, gemini-2.0-flash, gemini-2.0-flash-lite |

## Tag calls by feature

```python
summarizer = tw.wrap(openai.OpenAI(api_key="sk-..."), app_tag="summarizer")
chatbot    = tw.wrap(openai.OpenAI(api_key="sk-..."), app_tag="chatbot")
```

## Login instead of pasting a token

```python
tw = TokenGauge.login(email="you@example.com", password="your-password")
```

## What gets tracked

| Field | Description |
|---|---|
| Provider | openai / anthropic / google |
| Model | e.g. gpt-4o-mini, claude-3-5-sonnet |
| Tokens in | Prompt token count |
| Tokens out | Completion token count |
| Cost (USD) | Calculated from current model pricing |
| Latency | End-to-end request time in ms |
| Prompt type | Auto-classified category (code, chat, analysis, etc.) |
| Complexity | Estimated complexity score 1–10 |
| App tag | Optional label you set per-client |
