revenium-middleware-ollama 0.1.7

A Python library that meters Ollama usage to Revenium.

🤖 Revenium Middleware for Ollama

A middleware library for metering and monitoring Ollama API usage in Python applications. 🐍✨

✨ Features

• 📊 Precise Usage Tracking: Monitor tokens, costs, and request counts across all Ollama API endpoints
• 🔌 Seamless Integration: Drop-in middleware that works with minimal code changes
• ⚙️ Flexible Configuration: Customize metering behavior to suit your application needs

📥 Installation

pip install revenium-middleware-ollama

🔧 Usage

🔄 Zero-Config Integration

Simply export your REVENIUM_METERING_API_KEY and import the middleware. Your Ollama calls will be metered automatically:

import ollama
import revenium_middleware_ollama

# Ensure REVENIUM_METERING_API_KEY environment variable is set

response: ollama.ChatResponse = ollama.chat(
    model='qwen2.5:0.5b', messages=[
        {
            'role': 'user',
            'content': 'Why is the sky blue?',
        },
    ])
print(response['message']['content'])

The middleware automatically intercepts Ollama API calls and sends metering data to Revenium without requiring any changes to your existing code. Make sure to set the REVENIUM_METERING_API_KEY environment variable for authentication with the Revenium service.

📈 Enhanced Tracking with Metadata

For more granular usage tracking and detailed reporting, add the usage_metadata parameter:

import ollama
import revenium_middleware_ollama

response = ollama.chat(
    model='qwen2.5:0.5b', messages=[
        {
            'role': 'user',
            'content': 'Why is the sky blue?',
        },
    ],
    usage_metadata={
        "trace_id": "conv-28a7e9d4-1c3b-4e5f-8a9b-7d1e3f2c1b4a",
        "task_id": "chat-summary-af23c910",
        "task_type": "text-classification",
        "subscriber_identity": "[e-mail]",
        "organization_id": "acme-corporation-12345",
        "subscription_id": "startup-plan-quarterly-2025-Q1",
        "product_id": "intelligent-document-processor-v3",
        "source_id": "mobile-app-ios-v4.2",
        "ai_provider_key_name": "ollama-production-key1",
        "agent": "customer-support-assistant-v2",
    },
)
print(response.choices[0].message.content)

🚀 OpenAI Compatibility Mode

The middleware can also be used with Ollama's OpenAI compatibility mode.

import openai
import revenium_middleware_openai

openai.api_key = 'ollama'
openai.base_url = 'http://localhost:11434/v1/'
question = "Why is the sky blue?"

response = openai.chat.completions.create(
    model="gemma3:12b",
    messages=[
       {"role": "system", "content": "You are a helpful assistant."},
       {"role": "user", "content": question}
    ],
    usage_metadata={
        "trace_id": "conv-28a7e9d4-1c3b-4e5f-8a9b-7d1e3f2c1b4a",
        "task_id": "chat-summary-af23c910",
        "task_type": "text-classification",
        "subscriber_identity": "[e-mail]",
        "organization_id": "acme-corporation-12345",
        "subscription_id": "startup-plan-quarterly-2025-Q1",
        "product_id": "intelligent-document-processor-v3",
        "source_id": "mobile-app-ios-v4.2",
        "ai_provider_key_name": "ollama-production-key1",
        "agent": "customer-support-assistant-v2",
    }
)

print(response)

🏷️ Metadata Fields

The usage_metadata parameter supports the following fields:

Field	Description	Use Case
trace_id	Unique identifier for a conversation or session	Track multi-turn conversations
task_id	Identifier for a specific AI task	Group related API calls for a single task
task_type	Classification of the AI operation	Categorize usage by purpose (e.g., classification, summarization)
subscriber_email	The email address of the subscriber	Track usage by individual users
subscriber_credential	The credential associated with the subscriber	Track usage by individual users
organization_id	Customer or department identifier	Allocate costs to business units
subscription_id	Reference to a billing plan	Associate usage with specific subscriptions
product_id	The product or feature using AI	Track usage across different products
agent	Identifier for the specific AI agent	Compare performance across different AI agents
response_quality_score	The quality of the AI response (0..1)	Track AI response quality

All metadata fields are optional. Adding them enables more detailed reporting and analytics in Revenium.

🔄 Compatibility

• 🐍 Python 3.8+
• 🤖 Ollama Python SDK 1.0.0+
• 🌐 Works with all Ollama models

🔍 Logging

This module uses Python's standard logging system. You can control the log level by setting the REVENIUM_LOG_LEVEL environment variable:

# Enable debug logging
export REVENIUM_LOG_LEVEL=DEBUG

# Or when running your script
REVENIUM_LOG_LEVEL=DEBUG python your_script.py

Available log levels:

• DEBUG: Detailed debugging information
• INFO: General information (default)
• WARNING: Warning messages only
• ERROR: Error messages only
• CRITICAL: Critical error messages only

📚 Documentation

Full documentation is available at https://revenium-middleware-ollama.readthedocs.io/

👥 Contributing

Contributions are welcome! Please check out our contributing guidelines for details.

1. 🍴 Fork the repository
2. 🌿 Create your feature branch (git checkout -b feature/amazing-feature)
3. 💾 Commit your changes (git commit -m 'Add some amazing feature')
4. 🚀 Push to the branch (git push origin feature/amazing-feature)
5. 🔍 Open a Pull Request

📄 License

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

🙏 Acknowledgments

• 🔥 Thanks to the Ollama team for creating an excellent API
• 💖 Built with ❤️ by the Revenium team