Budget Enforcement - Pylva

Budget rules cap spend for a customer or pooled account over a daily, weekly, or monthly period.

Enforcement modes

Mode	Behavior
Warn	The provider call proceeds. Pylva records and alerts when spend crosses the limit.
Hard stop	The SDK throws before the provider call, so the provider is not billed.

For rollout guidance, see Controls Workflow.

TypeScript handling

import { init, PylvaBudgetExceeded } from "@pylva/sdk";

init({ apiKey: process.env.PYLVA_API_KEY! });

try {
  return await openai.chat.completions.create({ model, messages });
} catch (err) {
  if (err instanceof PylvaBudgetExceeded) {
    return cachedOrSmallerResponse();
  }
  throw err;
}

Python handling

from pylva import PylvaBudgetExceeded

try:
    response = openai_client.chat.completions.create(...)
except PylvaBudgetExceeded:
    response = cached_or_smaller_response()

How the SDK stays current

The SDK keeps a local accumulator for active budget rules so it can make a fast pre-call decision. Pylva then reconciles that local view with backend totals. Backend totals are authoritative. If pricing data is unavailable or the backend cannot be reached, the SDK passes through rather than blocking the host application because of a Pylva outage.

Recommended fallback behavior

When a hard stop fires, return a product-specific fallback:

Cached answer.
Smaller model path.
Queued job.
“Try again later” response.
Human handoff.

Avoid retry loops that immediately reissue the same expensive call. Hard stops only block when the SDK has an active cached rule it can enforce safely. Pylva fails open when rule state, pricing, or backend access is unavailable, so Pylva does not become the reason your agent is down.