Python API

ducto for Python is published as the ducto package on PyPI. Requires Python 3.11+.

Installation

pip install ducto

# With store backends
pip install "ducto[supabase]"
pip install "ducto[postgres]"
pip install "ducto[test]"     # dev + testing

Core Classes

Class	Description
PricingEngine	Pure calculation layer — evaluates expressions against usage metrics
CreditManager	Orchestrates calculate → reserve → deduct lifecycle
MemoryStore	In-memory store for testing
HttpxSupabaseStore	Supabase-backed store (fetch-based)
PostgresStore	Direct PostgreSQL store
UsageMetrics	Data class for usage dimensions
CostBreakdown	Structured calculation result

Quick Example

from ducto import CreditManager, UsageMetrics
from ducto.interface.supabase import HttpxSupabaseStore

store = HttpxSupabaseStore(url="https://project.supabase.co", key="service_role_key")
manager = CreditManager(store=store)
manager.load_pricing_from_store()

manager.add_credits("user_abc", 1000)

result = manager.deduct(
    user_id="user_abc",
    metrics=UsageMetrics(model="gpt-4", input_tokens=500, output_tokens=200),
    idempotency_key="tx_001",
)
print(result.balance_after)  # remaining credits