Voltarium

Modern, asynchronous Python client for the CCEE (Brazilian Electric Energy Commercialization Chamber) API. Built with Python 3.13+ and designed for high-performance energy sector applications.

🚀 Key Features

• 🔥 Asynchronous: Built with httpx and asyncio for maximum performance
• 🔒 Type Safe: Complete type hints with Pydantic models for bulletproof code
• 🛡️ Robust: Automatic OAuth2 token management with intelligent retry logic
• 🏗️ Real Staging Data: 60+ authentic CCEE credentials for comprehensive testing
• ⚡ Modern: Python 3.13+ with UV for lightning-fast dependency management
• ✅ Production Ready: Comprehensive test suite and error handling

📦 Installation

# Using UV (recommended)
uv add voltarium

# Using pip
pip install voltarium

🔥 Quick Start

import asyncio
from voltarium import VoltariumClient

async def main():
    async with VoltariumClient(
        client_id="your_client_id",
        client_secret="your_client_secret"
    ) as client:
        # List retailer migrations with automatic pagination
        migrations = client.list_migrations(
            initial_reference_month="2024-01",
            final_reference_month="2024-12",
            agent_code="12345",
            profile_code="67890"
        )

        # Stream results efficiently
        async for migration in migrations:
            print(f"Migration {migration.migration_id}: {migration.migration_status}")

asyncio.run(main())

🏗️ Real Staging Environment

Test with real CCEE data using our comprehensive staging environment:

from voltarium.sandbox import RETAILERS, UTILITIES
from voltarium import SANDBOX_BASE_URL

# Use real staging credentials
retailer = RETAILERS[0]  # 30+ available retailers
utility = UTILITIES[0]   # 30+ available utilities

# Test with actual CCEE staging API
async with VoltariumClient(
    base_url=SANDBOX_BASE_URL,
    client_id=retailer.client_id,
    client_secret=retailer.client_secret
) as client:
    # All operations work with real data
    migrations = await client.list_migrations(...)

📚 Comprehensive Documentation

Visit our complete documentation for:

• About - Architecture and detailed features
• Supported Endpoints - Complete API reference
• Examples - Practical usage patterns
• Staging Environment - Real data testing & roadmap

🛠️ Development

# Clone and setup
git clone https://github.com/joaodaher/voltarium-python.git
cd voltarium-python

# Install dependencies (requires UV)
task install-dev

# Run tests
task test

# Quality checks
task lint && task format && task typecheck

🎯 Current Status

Alpha Release - Core migration endpoints fully supported:

✅ Retailer Migrations - Complete CRUD operations, with V1/V1.1/V2 API version support (api_version=, defaults to "v2") ✅ Contracts - List, get, create, and download signed contract files ✅ Measurements - List consumption measurements with automatic same-month chunking ✅ Change Requests (Solicitações) - Representative changes, return to captive market, supply suspension, and approve/reject workflow 🚧 Utility Migrations - Under development 📋 Additional Endpoints - See roadmap

1.0.0 note: VoltariumClient's default api_version is now "v2" (previously the only option was CCEE's V1 migrations API). Pass api_version="v1" to keep the old behavior — see API Versioning.

🤝 Contributing

We welcome contributions! Please see our documentation for details on:

• Feature roadmap and priorities
• Development setup and guidelines
• Testing with real staging data

📄 License

Apache License 2.0 - see LICENSE.md for details.

Built for the Brazilian energy sector 🇧🇷 | Powered by modern Python 🐍