Account for participating paid calls

Live policy

The economics descriptor and Eco Admin

economics.yaml is the sixth environment descriptor. It defines reservation defaults, price tables, the reference LLM service, quota and budget policies, plans, and overdraft behavior for one tenant/project deployment.

Eco Admin manages plan overrides, trials and lifetime credits, quotas, budgets, the plan catalog, external subscription price mappings, and reservation floors without a platform rebuild. General service price tables and the reference service remain descriptor-edited policy. Descriptor policy and database-backed operational policy remain distinct rather than treating Redis or a dashboard draft as authority.

Who pays

One request, one funding split

Before it reserves anything, the engine resolves who pays. Every request is a single split. A primary funding source — an external subscription's period budget, or the project budget for everyone else — covers the part bounded by both the remaining plan quota and the primary funds. The user's wallet covers the remainder.

When plan quota or funds run out, plan_part shrinks toward zero and the wallet covers the rest in the same pass. Settlement charges plan quota and primary funds first, then the wallet for the over-quota remainder; wallet-paid tokens do not consume plan quota.

The engine

Guard any paid surface

The economics model is exposed as a small, reusable engine so any accountable flow — one that runs paid work on a user's behalf without a chat turn — verifies, reserves, and settles through the same resolution. Two entry points, chosen by who settles the cost.

from kdcube_ai_app.apps.chat.sdk.infra.economics.enforcement import (
    EconomicsGuard, EconomicsEstimate, FlowPolicy,
)
from kdcube_ai_app.apps.chat.sdk.infra.economics.policy import EconomicsLimitException

try:
    async with EconomicsGuard(
        self, subject=subject,
        scope_id="report_render_42", flow="reports.render",
        estimate=EconomicsEstimate(reservation_usd=0.05),
        policy=FlowPolicy(enforce_concurrency=False),
    ) as decision:
        result = await do_the_paid_work()   # accounted calls run here
except EconomicsLimitException as exc:
    return degraded_response(exc)      # nothing ran; no hold left behind

Recipe: Guard a Paid Surface and Enforce Economics.

Usage

Accounting & self-tracked services

A paid call routed through the accounting trackers emits an accounting event — a service type, provider/model, unit counts, cost, and runtime lineage — captured by a decorator such as @track_llm, @track_embedding, or @track_web_search. A turn report sums those spending events; it does not assign a synthetic turn price. Your own paid work can join the same rails through a tracker and usage extractors.

Cold-Turn Attribution

A model switch moves to a different model cache namespace. A capability toggle changes the cached system catalog, so the entire prompt is cold for one turn rather than only one catalog slice. When a selection delta is adopted on a warm conversation, the runtime emits a [CACHE] ANNOUNCE line, cache_cold_turn accounting metadata on the decision call, and a correlating log entry.

The marker attributes the cache-rebuild premium as one identifiable spending component; it is not a total or a promised amount. The user holds the cache policy (accept, confirm, defer_cold, or defer_conversation), while app configuration supplies only the allowed set and default.

from kdcube_ai_app.infra.accounting import AccountingTracker, ServiceType, ServiceUsage

def track_document_ocr(**extractors):
    return AccountingTracker(ServiceType.VISION, **extractors)

def _ocr_usage(result, *args, **kwargs) -> ServiceUsage:
    pages = int(result["pages_processed"])
    return ServiceUsage(
        document_pages=pages, requests=1,
        cost_usd=round(pages * 0.01, 6),   # the pricing lever
    )

The Claude Code runtime already runs on exactly this path: a Claude Code turn is accounted as ordinary LLM usage — same @track_llm tracker, provider = "anthropic", runtime = "claude_code" — with tokens and a cost_usd parsed from the CLI's stream output, priced by table lookup or the reported cost. Recipe: Implement a Self-Tracked Service.

Coverage is explicit, not universal: integrated model, embedding, web-search, and participating custom/self-tracked calls can be enforced and attributed. Arbitrary external spending by code that bypasses these service contracts is outside the economics boundary.

Payments

Payment Integration (Stripe)

Stripe handles all external payment flows: wallet top-ups (one-time credits), recurring subscriptions, refunds, and subscription cancellations. Project budgets are never topped up directly from Stripe events — only by admin actions or the subscription rollover job.

Webhook Flow

1. 1

   Checkout

   User initiates a wallet top-up or subscription via POST /api/economics/stripe/checkout/topup or .../subscription. The API creates a Stripe Checkout Session and returns a redirect URL.

2. 2

   Stripe fires webhook

   On payment completion Stripe sends an event to POST /api/economics/webhooks/stripe. The handler verifies the HMAC signature, checks idempotency via external_economics_events (keyed by Stripe event ID), and applies the change.

3. 3

   Reconcile job

   A cron-driven reconcile job (STRIPE_RECONCILE_CRON) catches missed webhooks by fetching Stripe events ordered ascending by created timestamp from a Redis-stored watermark. All replay is idempotent.

Webhook Events Handled

Subscription Plans & Funding Sources

Each chargeable plan maps to a Stripe product via its price id. When invoice.paid fires, the handler tops up the user's subscription period budget (the funding source for that billing cycle). On period end the rollover job moves unused balance into the project budget. Wallet top-ups credit the lifetime credits source directly; refunds debit lifetime credits and issue a Stripe refund against the original payment_intent_id.