Metadata-Version: 2.4
Name: tokenguard-sdk
Version: 0.1.0
Summary: Monitor AI agents, track LLM costs, debug failures — TokenGuard Python SDK
Author: TokenGuard
License: MIT
Project-URL: Homepage, https://github.com/acher112/TokenGuard
Project-URL: Documentation, https://tokenguard-app-two.vercel.app/docs
Keywords: ai,llm,monitoring,tracing,openai,anthropic,cost
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.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.18.0; extra == "anthropic"

# tokenguard (Python SDK)

**Monitor AI agents, track LLM costs, debug failures — in 2 lines of code.**

## Install

```bash
pip install tokenguard
```

## Quick Start — Auto-wrap Groq (zero code change)

```python
from groq import Groq
from tokenguard import TokenGuard

aw = TokenGuard(
    api_key="tg_live_...",           # from your dashboard Settings
    base_url="http://localhost:3000", # your TokenGuard URL
)

# Wrap your existing Groq client — ONE LINE
groq = aw.wrap_groq(Groq(api_key="..."), agent_name="DietAgent")

# Use exactly as before — tracking happens automatically
response = groq.chat.completions.create(
    model="llama3-8b-8192",
    messages=[{"role": "user", "content": "Give me a low-carb meal plan"}],
)

print(response.choices[0].message.content)
# → Your dashboard now shows cost, tokens, latency for this call
```

## Quick Start — Auto-wrap OpenAI

```python
from openai import OpenAI
from tokenguard import TokenGuard

aw = TokenGuard(api_key="tg_live_...", base_url="http://localhost:3000")

# Wrap your OpenAI client
openai = aw.wrap_openai(OpenAI(api_key="..."), agent_name="SupportBot")

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)
```

## Manual Tracing (full control)

```python
from tokenguard import TokenGuard

aw = TokenGuard(api_key="tg_live_...", base_url="http://localhost:3000")

def get_diet_plan(user_message):
    with aw.trace("DietSuggestionAgent") as trace:

        # Track the Groq call
        llm = trace.llm(model="llama3-8b-8192", provider="groq")
        response = groq_client.chat.completions.create(
            model="llama3-8b-8192",
            messages=[{"role": "user", "content": user_message}],
        )
        llm.end(
            input_tokens=response.usage.prompt_tokens,
            output_tokens=response.usage.completion_tokens,
        )

        # Track a tool call (optional)
        tool = trace.tool("nutrition_database_lookup")
        foods = lookup_foods(user_message)
        tool.end(result=foods)

        return response.choices[0].message.content
```

## What appears in your dashboard

Every call shows:
- 💰 **Cost** — exact cost per request
- ⏱️ **Latency** — how long it took
- 🔢 **Tokens** — input and output token counts
- 🐛 **Errors** — full error details with stack traces
- 📊 **Agent breakdown** — which agents cost the most

## Supported providers

| Provider | Method | Notes |
|---|---|---|
| **Groq** | `aw.wrap_groq(client)` | LLaMA, Mixtral, Gemma |
| **OpenAI** | `aw.wrap_openai(client)` | GPT-4o, GPT-4o-mini |
| **Any LLM** | Manual `trace.llm()` | Works with any provider |

## Before you exit your script

```python
aw.flush()  # makes sure all traces are sent before process ends
```
