Teer Python SDK

The official Python SDK for Teer, a platform for tracking and analyzing LLM usage across multiple providers including Anthropic, OpenAI, and Google.

Table of Contents

• Installation
• Usage
• Usage Reports
• Billing
• Examples
• Documentation
• License

Installation

pip install teer

Usage

Initializing the Client

from teer import TeerClient

# Initialize with your API key
client = TeerClient("YOUR_API_KEY")

# Or initialize with a custom base URL if you need
client = TeerClient(
    api_key="YOUR_API_KEY",
    base_url="https://proxy-url.com"
)

Sending Basic Usage Data

# Send basic usage data
client.ingest.send({
    # Required: Specify the LLM provider
    "provider": "anthropic",

    # Required: Specify the model name
    "model": "claude-3-haiku-20240307",

    # Optional: A unique identifier for the function or endpoint using the LLM
    "function_id": "summarize-article",

    # Required: Token usage information
    "usage": {
        # Number of input tokens
        "input": 1000,
        # Number of output tokens
        "output": 2000
    }
})

Usage Reports

Teer supports detailed usage reports for different LLM providers. Here are some examples of more advanced usage reports:

Usage Reports with Cache Information

Anthropic Cache

client.ingest.send({
    "provider": "anthropic",
    "model": "claude-3-haiku-20240307",
    "function_id": "legal-document-analysis",
    "usage": {
        "input": 2000,
        "output": 3000,
        # Anthropic-specific cache information
        "cache": {
            "anthropic": {
                # Tokens used to create the cache
                "cache_creation_input_tokens": 1500,
                # Tokens read from the cache
                "cache_read_input_tokens": 500
            }
        }
    }
})

OpenAI Cache

client.ingest.send({
    "provider": "openai",
    "model": "gpt-4o",
    "function_id": "code-generation",
    "usage": {
        "input": 800,
        "output": 2500,
        # OpenAI-specific cache information
        "cache": {
            "openai": {
                # Tokens retrieved from cache
                "input_cached_tokens": 300
            }
        }
    }
})

Google Cache

client.ingest.send({
    "provider": "google",
    "model": "gemini-ultra",
    "function_id": "image-analysis",
    "usage": {
        "input": 1200,
        "output": 1800,
        # Google-specific cache information
        "cache": {
            "google": {
                # Tokens retrieved from cache
                "cached_content_token_count": 800,
                # Tokens used for thoughts
                "thoughts_token_count": 400
            }
        }
    }
})

Usage Report with User Attribution

client.ingest.send({
    "provider": "openai",
    "model": "gpt-4o-mini-2024-07-18",
    "function_id": "generate-content",
    "usage": {
        "input": 500,
        "output": 1500
    },
    # Metadata for user attribution and analytics
    "metadata": {
        # User identification
        "user_id": "user-123456",
        "organization_id": "org-abcdef",

        # Session information
        "session_id": "session-xyz789"
    }
})

Usage Report Without Function ID

client.ingest.send({
    # Required: Specify the LLM provider
    "provider": "google",

    # Required: Specify the model name
    "model": "gemini-2.0-flash-001",

    # function_id is optional and can be omitted

    # Required: Token usage information
    "usage": {
        "input": 400,
        "output": 1200
    }
})

For a complete reference of all supported fields in usage reports, see the Usage Reports documentation.

Billing

Teer provides a billing resource for usage-based billing integration with providers like Stripe.

Creating Meter Events

from teer import TeerClient
from datetime import datetime, UTC

# Initialize the client with your API key
client = TeerClient("YOUR_API_KEY")

# Get the current timestamp in ISO 8601 format using timezone-aware approach
current_timestamp = datetime.now(UTC).isoformat()

# Create a meter event
meter_event = client.billing.meter_events.create({
    "provider": "stripe",
    "fields": {
        "identifier": "idmp_12345678",
        "event_name": "ai_search_api",
        "timestamp": current_timestamp,
        "payload": {
            "stripe_customer_id": "cus_12345678",
            "value": "25",
        },
    },
})

Examples

Check out the examples directory for more usage examples:

• Basic Usage: Simple example of using the Teer client
• Custom Base URL: Example of initializing the Teer client with a custom base URL
• Comprehensive Usage Reports: Detailed examples of various usage report scenarios
• Usage Payload Example: Example of creating a payload for the Teer ingest API
• Billing Meter Events: Example of creating meter events for usage-based billing

Documentation

Detailed documentation is available in the docs directory:

• Usage Reports: Detailed information about the structure and fields of usage reports

License

teer is distributed under the terms of the MIT license.

Publishing

python scripts/publish.py patch

python scripts/publish.py minor

python scripts/publish.py major