Skip to content
Briefcase AI

briefcase.controls

Install with pip install "briefcase-ai[controls]==4.4.0" and import from briefcase.controls.

Gateway

from briefcase.controls import FixedWindowQuotaStore, Gateway, GatewayConfig


gateway = Gateway(GatewayConfig(
    quota_store=FixedWindowQuotaStore(),
    buckets={"calls": {"limit": 20, "window_s": 60}},
))
GatewayConfig(
    quota_store,
    buckets={},
    entitlements=None,
    cooldown_seconds=3600.0,
    exporter=None,
    await_export=False,
    on_outcome=None,
    event_names={},
    port_error_policy="propagate",
    message_regex_throttle=False,
)


await Gateway(config).invoke(
    tenant_id=...,
    bucket=...,
    fn=...,
    ctx=None,
    deadline_s=None,
) -> Outcome

Outcome.reason is hard_capped, quota_exhausted, throttled, internal, or None on success.

Ports

  • QuotaStore.acquire() and mark_cooldown()
  • EntitlementsHook.is_hard_capped()
  • CacheStore.read() and write()
  • UsageSink.capture()
  • QuotaDecision, CacheEntry, and FixedWindowQuotaStore

Provider fallback

ProviderRegistry registers application-owned implementations of the runtime-checkable LLMProvider protocol. complete_text() returns a TextCompletion from the first available provider or raises NoProviderAvailable. Use scoped_credential(provider, credential) to bind a tenant credential to one provider for a request context.

Retry and throttle helpers

  • classify_provider_error(error, message_regex=False) -> ThrottleClassification
  • compute_backoff(attempt, base_delay_s=..., cap_delay_s=..., jitter=...)
  • retry_call(...) and retry_call_async(...)

See Invocation Controls for the complete flow.