Skip to main content

ducto.engine module

Core engine that loads config and calculates credit costs.

The PricingEngine class is the main entry point for the ducto package. It loads a validated PricingConfig from a dict or DB, then calculates credit costs from UsageMetrics.

class ducto.engine.PricingEngine(config: PricingConfig)​

Bases: object

Credit calculation engine.

Usage:

engine = PricingEngine.from_dict({
    "models": {"_default": "input_tokens * 0.001 + output_tokens * 0.003"},
})
result = engine.calculate(UsageMetrics(
    model="claude-opus-4",
    input_tokens=1000,
    output_tokens=2000,
))
print(result.total)  # 35.0

calculate(metrics: UsageMetrics) → CostBreakdown​

Calculate credit cost for a single usage event.

Args: : metrics: Usage metrics including model, tokens, tool calls.

Returns: : CostBreakdown with per-dimension and total costs.

Raises: : ValueError: If the model is not found and no _default : exists in the config.

calculate_batch(metrics_list: list[UsageMetrics]) → list[CostBreakdown]​

Calculate credit costs for multiple usage events.

Args: : metrics_list: List of usage metrics to calculate.

Returns: : List of CostBreakdown objects, one per input.

classmethod from_dict(data: dict[str, Any]) → PricingEngine​

Load engine from a config dictionary.

Args: : data: Dictionary representation of a pricing config.

Returns: : A new PricingEngine instance.

Raises: : ConfigError: If the config structure or expressions are invalid.

get_fixed_cost(job_name: str) → int | None​

Get the fixed credit cost for a named batch job.

has_model(model_name: str) → bool​

Check if a model name exists in the pricing config (exact match).

property min_balance : int​

Minimum balance users must keep (prevents spending last N credits).

pricing_schema() → PricingConfigData​

Return the pricing config as a typed model.

Returns: : PricingConfigData with all pricing sections and expressions.

resolve_model(model_version: str) → str | None​

Resolve a model version string to a pricing config key.

Tries exact match first, then prefix match (e.g. "claude-sonnet-4-20250514" -> "claude-sonnet-4"). Returns None when no match exists.