init() options

Every parameter capsera.init() accepts, its default, and when to change it.

Most applications set two or three of these.

Connection

Option	Default	Notes
`api_key`	`"dev"`	Your `cap-` key. The default is for local experiments and reports nothing useful.
`endpoint`	`"http://localhost:8000"`	Backend base URL. Set this for self-hosting.
`env`	`"development"`	Environment label on every event.

Default attribution

Option	Default	Notes
`agent_name`	`None`	Fallback agent for calls with no scope, replacing `unknown`.
`team`	`None`	Fallback team.

Decorators and tag() override both.

Delivery

Option	Default	Notes
`flush_interval_ms`	`500`	How often the worker ships a batch.
`max_retries`	`3`	Attempts per failed batch, with exponential backoff.
`on_error`	`None`	Callback for delivery failures.

Lowering flush_interval_ms does not make your calls faster, because nothing waits on delivery. It makes events appear sooner at the cost of more requests. Raising it is reasonable for a high-volume service.

Budget enforcement

Option	Default	Notes
`enable_budget_enforcement`	`True`	Pre-call budget check. On by default.
`budget_check_timeout`	`1.0`	Seconds to wait before allowing the call.

This is the one default that adds latency, because it performs a round trip to the backend before each provider call. When no budget matches the call, the result is "allowed" and the call proceeds.

To disable it:

capsera.init(api_key=..., enable_budget_enforcement=False)

The timeout fails open. If the check does not complete in time, the call is allowed.

Routing

Option	Default	Notes
`enable_routing`	`False`	Off by default, because routing changes which model answers.
`routing_rules`	`None`	Local rules, merged with backend rules. Local wins on name.
`routing_refresh_interval`	`60`	Seconds between backend rule refreshes.
`critical_task_types`	`None`	Task types exempt from cost-driven downgrades.

Use critical_task_types to protect work that must not be moved to a cheaper model:

capsera.init(
    api_key=...,
    enable_routing=True,
    critical_task_types=["legal-review", "medical-summary"],
)

See Routing.

Prompt analysis

Option	Default	Notes
`enable_prompt_analysis`	`False`	Structural metrics only, never content.
`prompt_size_threshold`	`4000`	Token count above which a prompt is oversized.
`on_oversized_prompt`	`None`	Callback receiving `(tokens, threshold)`.

See Prompt analysis.

Diagnostics

Option	Default	Notes
`debug`	`False`	One INFO log line per intercepted call.

Useful while integrating, noisy in production.

A production example

import os

import capsera

capsera.init(
    api_key=os.environ["CAPSERA_API_KEY"],
    env=os.environ.get("APP_ENV", "development"),
    agent_name="api-server",
    team="platform",
    on_error=lambda exc: logging.warning("capsera delivery failed: %s", exc),
)

Everything else is left at its default: budget enforcement on, routing off, prompt analysis off, debug off.

Calling init() repeatedly

Safe. The patch is applied once per class and guarded, so a second call cannot record a call twice. Re-initialising flushes the previous emitter so queued events are delivered, then points new calls at the new configuration.

The full signature

This page covers the options worth a decision. For the complete parameter list in declaration order, with types and defaults, see Lifecycle functions.