# Paygent SDK for Python

A Python SDK for integrating with the Paygent API to track usage and costs for AI models automatically.

## Installation

```bash
pip install paygent-sdk
```

## Usage

### 1. Automatic Tracking (Recommended)

Paygent can automatically track usage for popular LLM clients using monkeypatching. This is the easiest way to integrate Paygent into your application. Just call `paygent_sdk.init()` at the start of your application.

```python
import os
import paygent_sdk
from openai import OpenAI

# Initialize Paygent and automatically instrument all supported providers
paygent_sdk.init(api_key="your-paygent-api-key")

# Normal OpenAI usage (or Anthropic, Gemini, etc.)
client = OpenAI(api_key="your-openai-api-key")

# Just add paygent_* kwargs to your standard calls!
# These are automatically extracted and not sent to the provider.
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
    
    # Tracking parameters
    paygent_agent_id="my-agent-123",
    paygent_customer_id="customer-456",
    paygent_indicator="chat-interaction"
)

print(f"Response: {response.choices[0].message.content}")
# Cost and tokens are automatically tracked in the background!
```

#### Supported Providers (Automatic)
Paygent automatically tracks calls from:
- **OpenAI** (chat.completions, completions, embeddings)
- **Anthropic** (messages)
- **Google Gemini** (generate_content)
- **Mistral AI**, **Cohere**, **Groq**, **Together AI**, **Ollama**, **LiteLLM**
- **LangChain & LangGraph**
- **CrewAI**

### 2. Manual Tracking

If you prefer to send usage data manually, or if you are using a provider not yet supported by automatic tracking, you can use the `Client` directly.

```python
import logging
from paygent_sdk import Client, UsageData

# Create a new client
client = Client.new_client("your-paygent-api-key")

# Define usage data
usage_data = UsageData(
    model="gpt-4o",
    prompt_tokens=100,
    completion_tokens=50,
    total_tokens=150
)

# Send usage data
try:
    client.send_usage("agent-123", "customer-456", "manual-tracking", usage_data)
    print("Usage data sent successfully!")
except Exception as e:
    print(f"Failed to send usage: {e}")
```

#### Tracking with Prompt/Output Strings
If you don't have token counts, Paygent can calculate them for you:

```python
from paygent_sdk import UsageDataWithStrings

usage_data = UsageDataWithStrings(
    service_provider="OpenAI",
    model="gpt-4o",
    prompt_string="What is the capital of France?",
    output_string="The capital of France is Paris."
)

client.send_usage_with_token_string("agent-123", "customer-456", "qa-event", usage_data)
```

### Model Constants

The SDK provides constants for all supported models and service providers:

```python
from paygent_sdk import OpenAIModels, ServiceProvider

usage_data = UsageData(
    service_provider=ServiceProvider.OPENAI,
    model=OpenAIModels.GPT_4O,
    prompt_tokens=1000,
    completion_tokens=500
)
```

Available constants for: OpenAI, Anthropic, Google Gemini (DeepMind), Meta (Llama), Mistral, Cohere, DeepSeek, AWS, and more.

## API Reference

### Global Functions

#### `paygent_sdk.init(api_key: str)`
Initializes the SDK and enables automatic tracking (monkeypatching) for all supported LLM providers.

### Client Methods

#### `Client.new_client(api_key: str) -> Client`
Creates a manual tracking client.

#### `send_usage(agent_id: str, customer_id: str, indicator: str, usage_data: UsageData)`
Sends pre-calculated usage data.

#### `send_usage_with_token_string(agent_id: str, customer_id: str, indicator: str, usage_data: UsageDataWithStrings)`
Sends usage based on strings; Paygent counts tokens and calculates costs.

### Data Models

#### `UsageData`
| Field | Type | Description |
| :--- | :--- | :--- |
| `model` | `str` | Model identifier |
| `prompt_tokens` | `int` | Input tokens |
| `completion_tokens` | `int` | Output tokens |
| `total_tokens` | `int` | Optional total (defaults to prompt + completion) |
| `cached_tokens` | `int` | Optional cached tokens |

#### `UsageDataWithStrings`
| Field | Type | Description |
| :--- | :--- | :--- |
| `service_provider` | `str` | Provider (e.g., "OpenAI") |
| `model` | `str` | Model identifier |
| `prompt_string` | `str` | The input text |
| `output_string` | `str` | The generated text |

## Development

### Running Tests
```bash
python -m pytest tests/
```

## License
MIT
