cmdrdata-gemini 0.2.0

Customer tracking and usage-based billing for Google Gemini with arbitrary metadata support

cmdrdata-gemini

The standard for AI customer intelligence - track every Gemini call by customer, feature, or any dimension

Join hundreds of companies making customer-level AI tracking the default. One line of code to add complete visibility into your AI operations. Free during beta.

📊 Complete AI Intelligence Layer

cmdrdata-gemini is the missing analytics layer for your AI-powered application:

Track Everything That Matters

• Customer Intelligence - Know exactly which customers use what features
• Metadata Everything - Tag usage by feature, experiment, team, region, or any dimension
• Usage Patterns - Understand how your AI is actually being used
• Real-time Analytics - Instant visibility into your AI operations

Built for Modern AI Apps

• One-line integration - Drop-in replacement for Google GenAI SDK
• Zero latency overhead - Async tracking never blocks your API calls
• Unlimited custom fields - Track any metadata that matters to your business
• Privacy first - Your data never touches our servers (optional self-hosting)

What You Can Track

• Token usage by customer, feature, experiment, or any dimension
• Model usage patterns (Gemini 1.5 Flash, Gemini 1.5 Pro, etc.)
• Customer behavior - Who uses what, when, and how much
• Custom metadata - Unlimited fields for your specific needs
• Performance metrics - Latency, errors, success rates by segment

💎 Advanced Analytics with Custom Metadata

Track arbitrary metadata with each API call to enable sophisticated analytics:

# Example: AI-powered content generation with feature tracking
response = client.models.generate_content(
    model="gemini-1.5-pro",
    contents="Write a comprehensive guide about renewable energy...",
    customer_id="customer-123",
    # Custom metadata for analytics
    custom_metadata={
        "feature": "content_generation",
        "experiment_group": "gemini_pro_test",
        "content_type": "technical_guide",
        "user_segment": "enterprise",
        "session_id": "sess_xyz789"
    }
)

# Example: AI tutoring platform with learning analytics
response = client.models.generate_content(
    model="gemini-1.5-flash",
    contents=complex_physics_problem,
    customer_id="customer-456",
    custom_metadata={
        "use_case": "educational_tutoring",
        "subject": "physics",
        "interaction_count": 5,
        "learning_path": "advanced_physics",
        "engagement_score": "high"
    }
)

# Example: Multi-modal analysis with usage patterns
response = client.models.generate_content(
    model="gemini-1.5-pro-vision",
    contents=[image_data, "Analyze this image"],
    customer_id="customer-789",
    custom_metadata={
        "modality": "vision_text",
        "workflow": "image_analysis",
        "api_version": "v2",
        "client_platform": "web",
        "feature_flag": "vision_enabled"
    }
)

Intelligence Use Cases:

• Feature adoption: Track which AI features customers actually use
• A/B testing: Compare model performance across experiment groups
• Learning analytics: Understand educational engagement patterns
• Multi-modal insights: Analyze usage across different modalities
• Platform optimization: Identify performance bottlenecks by platform
• Product development: Data-driven feature prioritization

🛡️ Production Ready

Extremely robust and reliable - Built for production environments with:

• Resilient Tracking: Gemini calls succeed even if tracking fails.
• Non-blocking I/O: Fire-and-forget tracking never slows down your application.
• Automatic Retries: Failed tracking attempts are automatically retried with exponential backoff.
• Thread-Safe Context: Safely track usage across multi-threaded and async applications.
• Enterprise Security: API key sanitization and input validation.

🚀 Quick Start

Installation

pip install cmdrdata-gemini

Basic Usage

# Before
from google import genai
client = genai.Client(api_key="your-gemini-key")

# After - same API, automatic tracking!
import cmdrdata_gemini
client = cmdrdata_gemini.TrackedGemini(
    api_key="your-gemini-key",
    cmdrdata_api_key="your-cmdrdata-key"
)

# Same API as regular Google Gen AI client
response = client.models.generate_content(
    model="gemini-1.5-flash",
    contents="Explain how AI works"
)

print(response.text)
# Usage automatically tracked to cmdrdata backend!

Async Support

import cmdrdata_gemini

async def main():
    client = cmdrdata_gemini.AsyncTrackedGemini(
        api_key="your-gemini-key",
        cmdrdata_api_key="your-cmdrdata-key"
    )

    response = await client.models.generate_content(
        model="gemini-1.5-flash",
        contents="Hello, Gemini!"
    )

    print(response.text)
    # Async usage tracking included!

🎯 Customer Context Management

Automatic Customer Tracking

from cmdrdata_gemini.context import customer_context

# Set customer context for automatic tracking
with customer_context("customer-123"):
    response = client.models.generate_content(
        model="gemini-1.5-flash",
        contents="Help me code"
    )
    # Automatically tracked for customer-123!

# Or pass customer_id directly
response = client.models.generate_content(
    model="gemini-1.5-flash",
    contents="Hello",
    customer_id="customer-456"  # Direct customer ID
)

Manual Context Management

from cmdrdata_gemini.context import set_customer_context, clear_customer_context

# Set context for current thread
set_customer_context("customer-789")

response = client.models.generate_content(...)  # Tracked for customer-789

# Clear context
clear_customer_context()

⚙️ Configuration

Environment Variables

# Optional: Set via environment variables
export GEMINI_API_KEY="your-gemini-key"
export CMDRDATA_API_KEY="your-cmdrdata-key"
export CMDRDATA_ENDPOINT="https://api.cmdrdata.ai/api/events"  # Optional

# Then use without passing keys
client = cmdrdata_gemini.TrackedGemini()

Custom Configuration

client = cmdrdata_gemini.TrackedGemini(
    api_key="your-gemini-key",
    cmdrdata_api_key="your-cmdrdata-key",
    cmdrdata_endpoint="https://your-custom-endpoint.com/api/events",
    track_usage=True,  # Enable/disable tracking
    timeout=30,  # Custom timeout
    max_retries=3  # Custom retry logic
)

🔒 Security & Privacy

Automatic Data Sanitization

• API keys automatically redacted from logs
• Sensitive data sanitized before transmission
• Input validation prevents injection attacks
• Secure defaults for all configuration

What Gets Tracked

# Tracked data (anonymized):
{
    "customer_id": "customer-123",
    "model": "gemini-1.5-flash",
    "input_tokens": 25,
    "output_tokens": 150,
    "total_tokens": 175,
    "provider": "google",
    "timestamp": "2025-01-15T10:30:00Z",
    "metadata": {
        "response_id": "resp_abc123",
        "model_version": "001",
        "finish_reason": "STOP",
        "safety_ratings": null
    }
}

Note: Message content is never tracked - only metadata and token counts.

📊 Monitoring & Performance

Built-in Performance Monitoring

# Get performance statistics
stats = client.get_performance_stats()
print(f"Average response time: {stats['api_calls']['avg']}ms")
print(f"Total API calls: {stats['api_calls']['count']}")

Health Monitoring

# Check tracking system health
tracker = client.get_usage_tracker()
health = tracker.get_health_status()
print(f"Tracking healthy: {health['healthy']}")

🛠️ Advanced Usage

Token Counting

# Count tokens without generating content (also tracked)
token_count = client.models.count_tokens(
    model="gemini-1.5-flash",
    contents="How many tokens is this?"
)
print(f"Token count: {token_count.total_tokens}")

Disable Tracking for Specific Calls

# Disable tracking for sensitive operations
response = client.models.generate_content(
    model="gemini-1.5-flash",
    contents="Private query",
    track_usage=False  # This call won't be tracked
)

Error Handling

from cmdrdata_gemini.exceptions import CMDRDataError, TrackingError

try:
    client = cmdrdata_gemini.TrackedGemini(
        api_key="invalid-key",
        cmdrdata_api_key="invalid-cmdrdata-key"
    )
except CMDRDataError as e:
    print(f"Configuration error: {e}")
    # Handle configuration issues

Integration with Existing Error Handling

# All original Google Gen AI exceptions work the same way
try:
    response = client.models.generate_content(...)
except Exception as e:  # Google Gen AI exceptions
    print(f"Google Gen AI error: {e}")
    # Your existing error handling works unchanged

🔧 Development

Requirements

• Python 3.9+
• google-genai>=0.1.0

Installation for Development

git clone https://github.com/cmdrdata-ai/cmdrdata-gemini.git
cd cmdrdata-gemini
pip install -e .[dev]

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=cmdrdata_gemini

# Run specific test categories
pytest -m unit          # Unit tests only
pytest -m integration   # Integration tests only

Code Quality

# Format code
black cmdrdata_gemini/
isort cmdrdata_gemini/

# Type checking
mypy cmdrdata_gemini/

# Security scanning
safety check

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for your changes
5. Ensure all tests pass (pytest)
6. Format your code (black . && isort .)
7. Commit your changes (git commit -m 'Add amazing feature')
8. Push to the branch (git push origin feature/amazing-feature)
9. Open a Pull Request

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: https://docs.cmdrdata.ai/gemini
• Issues: GitHub Issues
• Support: [e-mail]

🔗 Related Projects

• cmdrdata-openai - Usage tracking for OpenAI
• cmdrdata-anthropic - Usage tracking for Anthropic Claude
• CMDR Data Platform - Complete LLM usage analytics

📈 Changelog

See CHANGELOG.md for a complete list of changes and version history.

---

Built with ❤️ by the CMDR Data team

Become the Google Analytics of your AI - understand everything, optimize everything.