ducto 0.1.0__tar.gz

ducto-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 apoorwv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ducto-0.1.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: ducto
+Version: 0.1.0
+Summary: Declarative credit calculation engine AI SaaS platforms
+Project-URL: Homepage, https://github.com/apoorwv/ducto
+Project-URL: Source, https://github.com/apoorwv/ducto
+Project-URL: Documentation, https://github.com/apoorwv/ducto#readme
+Project-URL: Issues, https://github.com/apoorwv/ducto/issues
+Keywords: credits,billing,llm,usage-metering,pricing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0.3
+Provides-Extra: supabase
+Requires-Dist: httpx>=0.27; extra == "supabase"
+Requires-Dist: psycopg2-binary>=2.9; extra == "supabase"
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary>=2.9; extra == "postgres"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: ruff>=0.15.0; extra == "test"
+Requires-Dist: pyright; extra == "test"
+Requires-Dist: pytest-testmon>=2.0.0; extra == "test"
+Dynamic: license-file

ducto-0.1.0/README.md

@@ -0,0 +1,308 @@
+# ducto
+
+[![CI](https://github.com/apoorwv/ducto/actions/workflows/ci.yml/badge.svg)](https://github.com/apoorwv/ducto/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Declarative credit calculation engine for AI SaaS platforms.
+
+Pricing expressions stored in a `credit_pricing_config` table enable live
+updates without redeploys. A safe AST-walking expression engine calculates
+credit costs from usage metrics. Supports per-model formulas, tool costs, search/RAG pricing,
+cache discounts, fixed-cost batch jobs, and a full reserve-then-deduct
+lifecycle.
+
+## Features
+
+- **Safe expression engine** — Uses Python's `ast` module with a strict
+  allowlist (no `eval()` of raw strings, no `exec()`, no attribute access,
+  no imports). Validated at config load time.
+- **Database-backed pricing** — Pricing expressions stored in a
+  `credit_pricing_config` table. Enables live pricing updates without
+  redeploys. Dict loading available for testing and stateless calculation.
+- **Multi-dimensional** — Per-model formulas (with `_default` fallback),
+  per-tool overrides, search/RAG, cache read discounts, fixed-cost jobs.
+- **Stateless core** — Pure calculation layer has zero database dependency.
+- **Auditable** — Returns a structured `CostBreakdown` with per-dimension
+  costs and metadata.
+- **Pluggable storage** — Reserve-then-deduct pattern via `CreditStore`
+  adapters: Supabase, raw PostgreSQL, or in-memory for testing.
+
+## Installation
+
+```bash
+pip install ducto
+
+# With Supabase store support
+pip install "ducto[supabase]"
+
+# With PostgreSQL store support
+pip install "ducto[postgres]"
+
+# Development & testing
+pip install "ducto[test]"
+```
+
+Requires Python 3.11+.
+
+## Quick Start
+
+### Full lifecycle with store
+
+```python
+from ducto import CreditManager, UsageMetrics
+from ducto.interface.supabase import HttpxSupabaseStore
+
+store = HttpxSupabaseStore(url=supabase_url, key=service_role_key)
+manager = CreditManager(store=store)
+
+# Load pricing from the credit_pricing_config table
+manager.load_pricing_from_store()
+
+# Deduct credits for a usage event
+result = manager.deduct(
+    user_id="user_abc",
+    metrics=UsageMetrics(model="claude-opus-4", input_tokens=500, output_tokens=200),
+    idempotency_key="chat_42_turn_7",
+)
+```
+
+Requires existing schema (run `ducto migrate`) and seeded pricing config
+(run `ducto pricing set defaults.yaml`).
+
+### Calculation only (no database)
+
+For testing or stateless calculation without a store:
+
+```python
+from ducto import PricingEngine, UsageMetrics
+
+engine = PricingEngine.from_dict({
+    "version": 1,
+    "models": {"_default": "input_tokens * 0.001 + output_tokens * 0.003"},
+})
+
+result = engine.calculate(
+    UsageMetrics(model="gpt-4", input_tokens=500, output_tokens=200),
+)
+print(f"Total credits: {result.total}")
+```
+
+## Pricing Configuration
+
+Pricing is stored in the `credit_pricing_config` table via the
+`set_active_pricing_config` RPC. The
+`CreditManager.load_pricing_from_store()` method fetches the active
+config at runtime. See [`scripts/seed_pricing.py`](scripts/seed_pricing.py)
+for reference.
+
+### Expression format
+
+```json
+{
+  "version": 1,
+  "models": {
+    "gpt-4": "input_tokens * 0.01 + output_tokens * 0.03",
+    "_default": "input_tokens * 0.001 + output_tokens * 0.003"
+  },
+  "tools": {
+    "_default": "tool_calls * 0",
+    "web_search": "web_search_calls * 0.5"
+  },
+  "search": {
+    "costs": "search_queries * 0.5 + search_results * 0.05"
+  },
+  "cache": {
+    "discount": "-cache_read_tokens * 0.0045"
+  },
+  "fixed": {
+    "batch_job": 20
+  },
+  "min_balance": 5
+}
+```
+
+### Available expression variables
+
+| Variable | Source field in `UsageMetrics` |
+|----------|--------------------------------|
+| `input_tokens` | `metrics.input_tokens` |
+| `output_tokens` | `metrics.output_tokens` |
+| `cache_read_tokens` | `metrics.cache_read_tokens` |
+| `cache_write_tokens` | `metrics.cache_write_tokens` |
+| `tool_calls` | `len(metrics.tool_calls)` |
+| `search_queries` | `metrics.search_queries` |
+| `search_results` | `metrics.search_results` |
+| `web_search_calls` | `metrics.web_search_calls` |
+| `code_exec_calls` | `metrics.code_exec_calls` |
+
+### Supported functions
+
+`ceil`, `floor`, `min`, `max`, `round`
+
+### Version 1 rules
+
+- `models` section is **required** and must be a non-empty dict
+- `_default` model is used when no specific model matches
+- Tool costs don't double-count: tools with individual entries are
+  evaluated separately; remaining calls use `_default`
+- `cache.discount` is typically a negative value (savings/rebate)
+- `fixed` costs are non-negative integers, applied when
+  `UsageMetrics.fixed_job` matches
+
+## Storage Backends
+
+### MemoryStore (testing/dev)
+
+```python
+from ducto import CreditManager
+from ducto.interface.memory import MemoryStore
+
+store = MemoryStore()
+manager = CreditManager(store=store)
+```
+
+### SupabaseStore
+
+```python
+from ducto.interface.supabase import HttpxSupabaseStore
+
+store = HttpxSupabaseStore(url=supabase_url, key=service_role_key)
+```
+
+### PostgresStore
+
+```python
+from ducto.interface.postgres import PostgresStore
+
+store = PostgresStore("postgresql://user:pass@host:5432/db")
+```
+
+### Custom adapters
+
+Implement `ducto.interface.base.CreditStore` (an ABC with 8 methods) to
+integrate with any backend.
+
+## Credit Lifecycle
+
+`CreditManager` orchestrates a three-step reserve-then-deduct pattern:
+
+1. **Calculate** — `PricingEngine.calculate(UsageMetrics)` -> `CostBreakdown`
+2. **Reserve** — `store.reserve_credits(user_id, amount)` -> `ReserveResult`
+   (locks the user row; reservations auto-expire after 10 minutes)
+3. **Deduct** — `store.deduct_credits(user_id, reservation_id, amount)`
+   -> `DeductionResult` (idempotent, atomic)
+
+```python
+manager = CreditManager(store=store)
+manager.load_pricing_from_store()
+result = manager.deduct(
+    user_id="user_abc",
+    metrics=UsageMetrics(model="gpt-4", input_tokens=100, output_tokens=50),
+    idempotency_key="tx_42",
+)
+```
+
+Pricing can also be loaded from a dict (no database):
+
+```python
+manager.publish_pricing_from_dict({
+    "version": 1,
+    "models": {"_default": "input_tokens * 0.001 + output_tokens * 0.003"},
+})
+```
+
+## SQL Migrations
+
+Three bundled SQL files create the required schema:
+
+| File | Creates |
+|------|---------|
+| `001_credit_tables.sql` | `user_credits`, `credit_transactions`, `credit_reservations` tables, RLS policies, signup bonus trigger |
+| `002_credit_rpcs.sql` | `credits_add`, `reserve_credits`, `deduct_credits`, `get_credits_balance` RPCs (SECURITY DEFINER, service_role only) |
+| `003_pricing_config.sql` | `credit_pricing_config` table, `get_active_pricing_config`, `set_active_pricing_config` RPCs |
+
+All DDL is idempotent (uses `IF NOT EXISTS` / `CREATE OR REPLACE`).
+
+### CLI reference
+
+```bash
+# Create tables, indexes, and RPC functions
+ducto migrate "postgresql://user:pass@host:5432/db"
+
+# Show current active pricing config
+ducto pricing get
+
+# Update active pricing from a JSON or YAML file
+ducto pricing set config.yaml
+```
+
+The `pricing` commands require `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY`
+environment variables.
+
+Or from Python:
+
+```python
+from ducto.interface.supabase import run_migrations
+
+result = run_migrations("postgresql://user:pass@host:5432/db")
+assert result.success, result.errors
+```
+
+## Expression Safety
+
+The expression engine uses a strict AST-walking validator:
+
+1. Parse `ast.parse(expr, mode="eval")`
+2. Walk the AST -- every node type must be in an allowlist (~25 node
+   types: binary ops, comparisons, conditionals, booleans, constants,
+   names, calls)
+3. Function calls must be in a whitelist (`ceil`, `floor`, `min`, `max`,
+   `round`)
+4. Rejects: attributes (`x.__class__`), subscripts (`x[0]`), lambdas,
+   comprehensions, imports, starred expressions
+5. Evaluation namespace has `__builtins__` emptied -- only the 5
+   whitelisted math/python builtins and user-provided variable names are
+   available
+6. All expression strings are validated at config load time -- invalid
+   configs never reach the engine
+
+## Architecture
+
+```
+ducto/
+  expr.py          # Safe AST expression evaluator
+  config.py        # Pydantic model + dict loading for PricingConfig
+  engine.py        # PricingEngine -- core calculation logic
+  metrics.py       # UsageMetrics, ToolCall dataclasses
+  breakdown.py     # CostBreakdown dataclass
+  manager.py       # CreditManager -- calculate -> reserve -> deduct
+  interface/
+    base.py        # CreditStore ABC
+    models.py      # Pydantic schemas for store operations
+    memory.py      # MemoryStore (in-memory for testing)
+    supabase.py    # HttpxSupabaseStore adapter + run_migrations()
+    postgres.py    # PostgresStore adapter
+  sql/
+    001_credit_tables.sql
+    002_credit_rpcs.sql
+    003_pricing_config.sql
+```
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install "ducto[test]"
+
+# Run tests
+pytest
+
+# Lint & format
+ruff check .
+ruff format .
+
+# Type check
+pyright
+```
+

ducto-0.1.0/pyproject.toml

@@ -0,0 +1,94 @@
+[project]
+name = "ducto"
+version = "0.1.0"
+description = "Declarative credit calculation engine AI SaaS platforms"
+requires-python = ">=3.11"
+dependencies = [
+    "pydantic>=2.0.0",
+    "pyyaml>=6.0.3",
+]
+keywords = ["credits", "billing", "llm", "usage-metering", "pricing"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/apoorwv/ducto"
+Source = "https://github.com/apoorwv/ducto"
+Documentation = "https://github.com/apoorwv/ducto#readme"
+Issues = "https://github.com/apoorwv/ducto/issues"
+
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project.scripts]
+ducto = "ducto.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.optional-dependencies]
+supabase = [
+    "httpx>=0.27",
+    "psycopg2-binary>=2.9",
+]
+postgres = [
+    "psycopg2-binary>=2.9",
+]
+test = [
+    "pytest>=8.0",
+    "ruff>=0.15.0",
+    "pyright",
+    "pytest-testmon>=2.0.0",
+]
+
+[tool.setuptools.package-data]
+ducto = ["sql/*.sql"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "ASYNC", "RUF100", "SIM", "RET", "C901"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 15
+
+[tool.ruff.lint.per-file-ignores]
+"**/__init__.py" = ["UP006"]
+"**/test_*.py" = ["SIM", "RET", "N"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.pyright]
+typeCheckingMode = "standard"
+useLibraryCodeForTypes = false
+venvPath = "."
+venv = ".venv"
+exclude = ["**/__pycache__", "**/.venv/**", "**/.pytest_cache/**"]
+reportMissingImports = "none"
+reportMissingModuleSource = "none"
+reportOptionalMemberAccess = "none"
+
+[tool.coverage.run]
+source = ["ducto"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = ["pragma: no cover", "if TYPE_CHECKING:", "def __repr__", "raise NotImplementedError"]
+
+[dependency-groups]
+dev = [
+    "pytest-testmon>=2.2.0",
+]

ducto-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ducto-0.1.0/src/ducto/__init__.py

@@ -0,0 +1,45 @@
+"""ducto — declarative credit calculation engine for AI SaaS platforms."""
+
+__version__ = "0.1.0"
+
+from ducto.breakdown import CostBreakdown
+from ducto.config import ConfigError, PricingConfig
+from ducto.engine import PricingEngine
+from ducto.expr import ExpressionError, evaluate_expression, validate_expression
+from ducto.interface.memory import MemoryStore
+from ducto.interface.models import (
+    AddCreditsResult,
+    BalanceResult,
+    CreditMetadata,
+    DeductionResult,
+    PricingConfigData,
+    PricingConfigResult,
+    ReserveResult,
+    SetupResult,
+)
+from ducto.manager import CreditManager, InsufficientCreditsError, PricingNotLoadedError
+from ducto.metrics import ToolCall, UsageMetrics
+
+__all__ = [
+    "PricingEngine",
+    "CostBreakdown",
+    "UsageMetrics",
+    "ToolCall",
+    "PricingConfig",
+    "ConfigError",
+    "ExpressionError",
+    "evaluate_expression",
+    "validate_expression",
+    "CreditManager",
+    "InsufficientCreditsError",
+    "PricingNotLoadedError",
+    "CreditMetadata",
+    "PricingConfigData",
+    "BalanceResult",
+    "AddCreditsResult",
+    "ReserveResult",
+    "DeductionResult",
+    "PricingConfigResult",
+    "SetupResult",
+    "MemoryStore",
+]

ducto-0.1.0/src/ducto/__main__.py

@@ -0,0 +1,157 @@
+"""ducto CLI — migrate, pricing get/set."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ducto.interface.supabase import HttpxSupabaseStore
+
+_RETRY_DELAY = 2
+_RETRIES = 15
+
+
+def _store_from_env() -> HttpxSupabaseStore:
+    """Create HttpxSupabaseStore from SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY."""
+    url = os.environ.get("SUPABASE_URL")
+    key = os.environ.get("SUPABASE_SERVICE_ROLE_KEY")
+    if not url:
+        print("SUPABASE_URL required", file=sys.stderr)
+        sys.exit(1)
+    if not key:
+        print("SUPABASE_SERVICE_ROLE_KEY required", file=sys.stderr)
+        sys.exit(1)
+
+    from ducto.interface.supabase import HttpxSupabaseStore
+
+    return HttpxSupabaseStore(url=url, key=key)
+
+
+def _migrate(args: list[str]) -> None:
+    if not args:
+        print("Usage: ducto migrate <database_url>", file=sys.stderr)
+        sys.exit(1)
+
+    from ducto.interface.supabase import run_migrations
+
+    result = run_migrations(args[0])
+    for t in result.tables_created:
+        print(f"  ✓ {t}")
+    for e in result.errors:
+        print(f"  ✗ {e}", file=sys.stderr)
+
+    if result.success:
+        print("Migration complete.")
+    else:
+        print("Migration completed with errors.", file=sys.stderr)
+        sys.exit(1)
+
+
+def _load_pricing_file(filepath: str) -> dict:
+    """Read a JSON or YAML pricing config file."""
+    if filepath.endswith((".yaml", ".yml")):
+        try:
+            import yaml
+        except ImportError:
+            print("PyYAML required for .yaml files: pip install ducto[supabase]", file=sys.stderr)
+            sys.exit(1)
+        try:
+            with open(filepath) as f:
+                return yaml.safe_load(f)
+        except FileNotFoundError:
+            print(f"File not found: {filepath}", file=sys.stderr)
+            sys.exit(1)
+    else:
+        try:
+            with open(filepath) as f:
+                return json.load(f)
+        except FileNotFoundError:
+            print(f"File not found: {filepath}", file=sys.stderr)
+            sys.exit(1)
+
+
+def _pricing_set(args: list[str]) -> None:
+    if not args:
+        print("Usage: ducto pricing set <file.json|file.yaml>", file=sys.stderr)
+        sys.exit(1)
+
+    from ducto.interface.models import PricingConfigData
+
+    data = _load_pricing_file(args[0])
+
+    config = PricingConfigData.model_validate(data)
+
+    store = _store_from_env()
+
+    # Retry: PostgREST schema cache may not be refreshed yet
+    for attempt in range(_RETRIES):
+        try:
+            existing = store.get_active_pricing()
+            if existing is not None:
+                print(f"Active pricing already exists (id={existing.id}) — skipping.")
+                return
+            store.set_active_pricing(config)
+            print("Pricing config set successfully.")
+            return
+        except Exception as exc:
+            if attempt == _RETRIES - 1:
+                print(f"Failed to set pricing: {exc}", file=sys.stderr)
+                print("Tip: Ensure 'ducto migrate' has been run and the schema cache has refreshed.", file=sys.stderr)
+                sys.exit(1)
+            time.sleep(_RETRY_DELAY)
+
+
+def _pricing_get() -> None:
+    store = _store_from_env()
+    for attempt in range(_RETRIES):
+        try:
+            result = store.get_active_pricing()
+            if result is None:
+                print("No active pricing config.", file=sys.stderr)
+                sys.exit(1)
+            print(json.dumps(result.model_dump(mode="json"), indent=2))
+            return
+        except Exception as exc:
+            if attempt == _RETRIES - 1:
+                print(f"Failed to get pricing: {exc}", file=sys.stderr)
+                print("Tip: Ensure 'ducto migrate' has been run and the schema cache has refreshed.", file=sys.stderr)
+                sys.exit(1)
+            time.sleep(_RETRY_DELAY)
+
+
+def _pricing(args: list[str]) -> None:
+    if not args:
+        print("Usage: ducto pricing <get|set> ...", file=sys.stderr)
+        sys.exit(1)
+
+    sub = args[0]
+    if sub == "set":
+        _pricing_set(args[1:])
+    elif sub == "get":
+        _pricing_get()
+    else:
+        print(f"Unknown pricing subcommand: {sub}", file=sys.stderr)
+        sys.exit(1)
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print("Usage: ducto <migrate|pricing> ...", file=sys.stderr)
+        sys.exit(1)
+
+    cmd = sys.argv[1]
+    if cmd == "migrate":
+        _migrate(sys.argv[2:])
+    elif cmd == "pricing":
+        _pricing(sys.argv[2:])
+    else:
+        print(f"Unknown command: {cmd}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

ducto-0.1.0/src/ducto/breakdown.py

@@ -0,0 +1,30 @@
+"""Aggregated cost breakdown produced by ``PricingEngine.calculate()``.
+
+The ``CostBreakdown`` dataclass holds per-category credit costs and
+computes a ``total`` in ``__post_init__``.
+"""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class CostBreakdown:
+    """Granular credit cost report for a usage event or batch.
+
+    ``total`` is automatically computed from the component fields
+    during initialisation and is capped at ``0.0`` from below.
+    """
+
+    model_credits: float = 0.0
+    tool_credits: float = 0.0
+    search_credits: float = 0.0
+    cache_savings: float = 0.0
+    fixed_credits: float = 0.0
+    total: float = 0.0
+    breakdown: dict = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self.total = max(
+            0.0,
+            self.model_credits + self.tool_credits + self.search_credits + self.fixed_credits + self.cache_savings,
+        )