paygent-sdk 4.8.0

Official Python SDK for Paygent - Track AI usage and costs across multiple providers (OpenAI, Anthropic, Google, DeepSeek, etc.)

Paygent SDK for Python

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

Installation

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.

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.

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:

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:

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

python -m pytest tests/

License

MIT