Enforcement semantics
Budget enforcement semantics.
A hard budget is only useful when its behavior is predictable. This page explains exactly when Solwyn checks a budget, how usage is measured and priced, what can remain in flight, and what happens when the cloud or a provider is unavailable.
The specification
How the check behaves, step by step.
Enforcement modes
Alerts-only is the default: the request proceeds and your channels are notified at your configured thresholds. Hard deny is opt-in per project: the SDK raises BudgetExceededError before the request is sent. A run stopped from the dashboard is blocked the same way, raising RunStoppedError. Once a project-wide hard cap is denying, it keeps denying for as long as your process stays up — a Solwyn outage never lifts it. Caps scoped to a tag are re-checked against the cloud and are not held through an outage.
Check timing
The SDK evaluates every cap that applies to the call — your project budget, plus any model, provider, tag, or per-run cap you have set — before the call leaves your process, and before streaming begins. One pre-flight check covers the whole failover chain: it reserves against the largest output cap across your configured providers, so a fallback hop is already accounted for and is not re-checked. Inside a solwyn.run(...) scope the SDK draws on a server-granted token lease, so it does not pay a network round-trip on every call.
Cost calculation
Solwyn measures usage, not content: the SDK reads the token counts from each provider response and sends those counts to your Solwyn project, which prices them from dated, first-party provider rates. Pricing lives on the server, not in the SDK, so a price correction applies without a redeploy — and an unrecognized model is flagged, never silently billed at zero. Usage metadata is batched and sent in the background; it never blocks the model call.
Concurrency and in-flight spend
The Solwyn cloud aggregates usage across every SDK instance sharing a project. Each call reserves its worst-case cost before it is sent, so parallel calls cannot jointly overrun a cap. Your provider invoice can still land above the number: calls already in flight are never recalled, a response that runs past its reserved bound is charged in full, and during a Solwyn outage each instance may draw a bounded share of remaining headroom. Set caps with that headroom in mind for highly parallel workloads.
Cloud unavailability
The SDK fails open by default: if the Solwyn cloud is unreachable, calls are allowed rather than blocked. Two things still hold. A project-wide hard cap that is already denying keeps denying — an outage never reopens spending. And a run holding a budget lease keeps spending against that lease, then a bounded share of remaining headroom, before it opens up. Set fail_open=False if you would rather the SDK enforce your last known limit locally and block when it is reached. Queued metadata is retried and delivered when connectivity returns.
Provider unavailability
The circuit breaker is fully local: it tracks provider failures in your process and routes supported failures to your configured fallback with no Solwyn involvement, so failover works even when our cloud is unreachable. Failures that may already have reached the model — a read timeout, a 5xx — are surfaced to you rather than retried on another provider, so one call is never billed twice.
The commitment
What we guarantee, and what we don't.
- Once Solwyn has told the SDK a hard cap is reached, the SDK blocks the call before it is sent.
- Prompt and response content is never sent to Solwyn.
- A project-wide hard cap that is already denying is not lifted by a Solwyn outage.
- Provider calls are never routed through Solwyn's servers.
- That the provider invoice can never exceed the configured number — responses that overrun their reserved bound, outage headroom, and provider-side pricing changes affect the final amount.
- Enforcement of calls made outside the wrapped client, or of billable provider surfaces the SDK does not yet intercept (it logs a warning naming any it recognizes).
- That an alerts-only project default stops any request (it notifies; it does not block). A hard-deny cap set on a specific model, provider, tag, or run does block.