Metadata-Version: 2.4
Name: paygent-sdk
Version: 4.6.0
Summary: Official Python SDK for Paygent - Track AI usage and costs across multiple providers (OpenAI, Anthropic, Google, DeepSeek, etc.)
Home-page: https://github.com/paygent/paygent-sdk-python
Author: Paygent
Author-email: Paygent Team <support@paygent.com>
Maintainer-email: Paygent Team <support@paygent.com>
License: MIT
Project-URL: Homepage, https://paygent.com
Project-URL: Repository, https://github.com/paygent/paygent-sdk-python
Project-URL: Documentation, https://github.com/paygent/paygent-sdk-python#readme
Project-URL: Bug Tracker, https://github.com/paygent/paygent-sdk-python/issues
Project-URL: Changelog, https://github.com/paygent/paygent-sdk-python/releases
Project-URL: Source Code, https://github.com/paygent/paygent-sdk-python
Keywords: paygent,sdk,ai,llm,usage,tracking,costs,openai,anthropic,claude,gpt,gemini,deepseek,token-counting,cost-calculation,api-integration
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
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 :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: urllib3>=1.26.0
Requires-Dist: tiktoken>=0.5.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: mypy>=0.800; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 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
