cayu.server

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

`AuthConfigurationError`

from cayu.server import AuthConfigurationError

Server authentication cannot be assembled from its configured inputs.

The message names the inputs to fix and never includes their values.

Bases: ValueError.

This type’s implementation and inherited behavior are available in the linked release source.

Release source · Runtime guarantees · Capability guides

`AuthContext`

from cayu.server import AuthContext

Authenticated caller identity and operator-action provenance.

Authentication protects access to Cayu’s server surfaces. tenant does not scope sessions, events, transcripts, tasks, knowledge, artifacts, usage, or dashboard/control-plane reads; applications must enforce any tenant authorization and storage isolation separately.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
`subject`	`str`	`Field(max_length=AUTH_IDENTITY_MAX_CHARS, description='Verified identity of the authenticated caller.')`
`tenant`	`str \| None`	`Field(default=None, max_length=AUTH_IDENTITY_MAX_CHARS, description='Optional verified tenant identity for actor provenance only. It is not a storage partition, authorization rule, row-level filter, or tenant-isolation primitive, and it does not scope Cayu data.')`
`claims`	`dict[str, Any]`	`Field(default_factory=dict, description='Verified authentication claims available to trusted server code.')`

validate_subject (method)

AuthContext.validate_subject(value: str, info) -> str

validate_tenant (method)

AuthContext.validate_tenant(value: str | None, info) -> str | None

copy_claims (method)

AuthContext.copy_claims(value: dict[str, Any]) -> dict[str, Any]

Release source · Runtime guarantees · Capability guides

`AuthDependency`

from cayu.server import AuthDependency

AuthDependency = Callable[[Any], AuthDependencyResult | Awaitable[AuthDependencyResult]]

Release source · Runtime guarantees · Capability guides

`AuthenticatedAccess`

from cayu.server import AuthenticatedAccess

Access guarded by an application-provided Cayu auth dependency.

The callable is runtime wiring rather than serializable configuration. It is consequently excluded from representations and model serialization so a dependency carrying credentials cannot leak through diagnostics.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`kind`	`Literal['authenticated']`	`'authenticated'`
`dependency`	`Any`	`Field(exclude=True, repr=False)`

validate_dependency (method)

AuthenticatedAccess.validate_dependency(value: Any, handler: Any) -> AuthenticatedAccess

Release source · Runtime guarantees · Capability guides

`AuthenticatedProductAccess`

from cayu.server import AuthenticatedProductAccess

Production product authentication and trusted tenant resolution.

Bases: _ProductAccess.

Fields and attributes

Name	Type	Default
`dependency`	`Any`	`Field(exclude=True, repr=False)`
`kind`	`Literal['authenticated']`	`'authenticated'`

validate_dependency (method)

AuthenticatedProductAccess.validate_dependency(value: Any, handler: Any) -> _ProductAccess

Release source · Runtime guarantees · Capability guides

`BasicAuth`

from cayu.server import BasicAuth

HTTP Basic authentication dependency for small self-hosted deployments.

tenant, when configured, is copied into AuthContext as authenticated actor provenance only. It does not scope or authorize access to Cayu data.

from_environment (method)

BasicAuth.from_environment(username_variable: str=OPERATOR_USERNAME_VARIABLE, password_variable: str=OPERATOR_PASSWORD_VARIABLE, *, environ: Mapping[str, str] | None=None, realm: str='Cayu', subject: str | None=None, tenant: str | None=None, claims: dict[str, Any] | None=None) -> Self

Build Basic authentication from two environment variables.

The variables are read once, when this method is called. A variable that is unset, empty, or whitespace-only raises AuthConfigurationError; there is no fallback to open access. Requests are checked exactly as by the BasicAuth constructor, including constant-time comparison.

environ replaces os.environ as the source, for tests and for callers that resolve secrets into a mapping first.

init (method)

BasicAuth.__init__(*, username: str, password: str, realm: str='Cayu', subject: str | None=None, tenant: str | None=None, claims: dict[str, Any] | None=None) -> None

call (method)

async BasicAuth.__call__(request: Request) -> AuthContext

Release source · Runtime guarantees · Capability guides

`BrowserControlServerConfig`

from cayu.server import BrowserControlServerConfig

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`operator_origin`	`str`	`required`
`signing_key`	`SecretBytes`	`Field(repr=False, exclude=True)`

exact_origin (method)

BrowserControlServerConfig.exact_origin(value: str) -> str

dedicated_key (method)

BrowserControlServerConfig.dedicated_key(value: SecretBytes) -> SecretBytes

Release source · Runtime guarantees · Capability guides

`CayuService`

from cayu.server import CayuService

One assembled and inspectable maintained Cayu product service.

init (method)

CayuService.__init__(*, cayu_app: CayuApp, asgi_app: FastAPI, manifest: PublicServiceManifest, product_store: ProductOperationStore, agent_name: str, project_control_plane_context: ProjectControlPlaneContext | None=None, _assembly_token: object | None=None) -> None

cayu_app (property)

CayuService.cayu_app() -> CayuApp

asgi_app (property)

CayuService.asgi_app() -> FastAPI

manifest (property)

CayuService.manifest() -> PublicServiceManifest

product_store (property)

CayuService.product_store() -> ProductOperationStore

agent_name (property)

CayuService.agent_name() -> str

project_control_plane_context_attached (property)

CayuService.project_control_plane_context_attached() -> bool

execute_work (method)

async CayuService.execute_work(work_id: str) -> ProductOperation | None

Reload trusted ownership from product storage, then run opaque queued work.

Release source · Runtime guarantees · Capability guides

`CorsConfig`

from cayu.server import CorsConfig

Explicit browser cross-origin request policy.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`allowed_origins`	`tuple[str, ...]`	`()`
`allow_methods`	`tuple[str, ...]`	`('*',)`
`allow_headers`	`tuple[str, ...]`	`('*',)`
`allow_credentials`	`StrictBool`	`False`

validate_string_sequence (method)

CorsConfig.validate_string_sequence(value: object, info) -> tuple[str, ...]

validate_credentials_policy (method)

CorsConfig.validate_credentials_policy() -> CorsConfig

Release source · Runtime guarantees · Capability guides

`create_agent_service`

from cayu.server import create_agent_service

Assemble the maintained product API and separately protected control plane.

create_agent_service(app: CayuApp, *, agent_name: str, mode: ServiceMode | str, product_access: ProductAccess, operator_access: OperatorAccess, product_store: ProductOperationStore, product_api_path: str='/api', control_plane_path: str='/cayu', evaluation_promotion: EvaluationPromotionConfig | None=None, evals: EvalsConfig | None=None, project_context: ProjectControlPlaneContext | None=None) -> CayuService

Release source · Runtime guarantees · Capability guides

`create_router`

from cayu.server import create_router

Create an APIRouter with standard cayu endpoints.

Args: auth: FastAPI-compatible dependency guarding the CAYU control plane. create_server callers normally supply this through AuthenticatedAccess; only deliberate OpenAccess should leave it unset. It protects every control-plane route that can start, change, inspect, or reveal runtime state; only the health route stays open for load balancers. It must return AuthContext or a compatible mapping and raise HTTPException (401/403) to deny a request. Authentication does not add tenant-level authorization or storage isolation: AuthContext.tenant is operator provenance only. api_path: URL path prefix for the CAYU control plane. Defaults to /api. openapi_url: Public OpenAPI schema URL advertised by /contract for client generation. Pass None when generated OpenAPI is disabled. replay_idle_timeout_s: Maximum time an active replay stream may wait without seeing a new persisted event before emitting an error and closing. It also bounds idle read-only session follow streams. session_follow_heartbeat_s: Seconds between SSE comment heartbeats on the read-only session follow stream. session_follow_max_streams_per_principal: Maximum concurrent follow streams one authenticated subject may hold in this process. Unauthenticated callers share one bucket. session_follow_max_streams_per_session: Maximum concurrent follow streams for one session in this process. dashboard_pricing_configured: Whether resolved dashboard configuration supplies a default price book for cost estimation. This is discovery metadata only; the usage endpoint still validates every submitted price book. dashboard_configured: Whether the bundled dashboard is mounted. Its own configured access dependency remains authoritative. deployment_name: Optional resolved server deployment identity. Embedded mounts that do not own a ServerConfig leave it unset. dashboard_access_authenticated: Whether the mounted dashboard has an authentication dependency. Defaults to the API access posture when the dashboard is configured. docs_enabled: Whether Cayu owns enabled generated documentation routes. Embedded mounts leave this unknown. dashboard_pricing_metadata: Validated default catalog version and opaque generation provenance. Values that exceed diagnostic bounds are omitted from the response. evaluation_promotion: Complete authenticated captured-session promotion policy. When absent, no promotion route or enabled capability exists. evaluation_promotion_pricing: Optional already-validated dashboard price book reused for captured cost evidence. generated_evals_pricing: Optional server-owned dashboard price book used by generated execution targets for cost assertions and run ceilings. evals: Complete authenticated durable execution wiring for one explicit V1 corpus target. It takes indivisible precedence over generated project targets. When both it and project authority are absent, no durable Evals route, worker, or enabled capability exists. continuation_loop_policy_provider: Optional internal-session policy resolver used by an embedding application for resume, approval, user-input, and tool-recovery continuations. The returned policies remain process-local and are never accepted from HTTP payloads.

create_router(*, cayu_app, session_store, task_store, knowledge_store=None, knowledge_access_scope=None, knowledge_review_namespace: str | None=None, knowledge_review_labels: dict[str, str] | None=None, auth: AuthDependency | None=None, api_path: str=SERVER_API_PREFIX, openapi_url: str | None='/openapi.json', replay_idle_timeout_s: float=300.0, session_follow_heartbeat_s: float=15.0, session_follow_max_streams_per_principal: int=16, session_follow_max_streams_per_session: int=32, dashboard_configured: bool=False, browser_recordings_configured: bool=False, dashboard_pricing_configured: bool=False, deployment_name: str | None=None, dashboard_access_authenticated: bool | None=None, docs_enabled: bool | None=None, dashboard_pricing_metadata: tuple[str, str] | None=None, evaluation_promotion: EvaluationPromotionConfig | None=None, evaluation_promotion_pricing: PriceBook | None=None, generated_evals_pricing: PriceBook | None=None, evals: EvalsConfig | None=None, continuation_loop_policy_provider: Callable[[str], Awaitable[tuple[LoopPolicy, ...]]] | None=None, _project_context: ResolvedProjectControlPlaneContext | None=None, _system_diagnostics_snapshot_sink: Callable[[SystemDiagnosticsSnapshot], None] | None=None, _browser_client_base_path: str | None=None, _request_timing: RequestTimingRecorder | None=None) -> APIRouter

Release source · Runtime guarantees · Capability guides

`create_server`

from cayu.server import create_server

Create a FastAPI server wired to a CayuApp.

Returns a FastAPI application with standard cayu API routes and optional static dashboard serving.

Args: app: The CayuApp instance with registered agents/providers. config: Fully resolved server identity and policy. Construct it directly after resolving any external settings or secrets. An authenticated policy’s dependency returns AuthContext; its tenant value is operator-action provenance only and does not filter Cayu data or provide tenant isolation. project_context: Optional framework-owned project identity and storage assembled by cayu serve. Embedded servers continue to use the explicit low-level Evals configuration APIs. fastapi_options: Optional non-policy FastAPI constructor options. Cayu validates the option names and retains ownership of its title, documentation routes, and lifespan composition.

create_server(app: CayuApp, *, config: ServerConfig, project_context: ProjectControlPlaneContext | None=None, browser_recordings: Any | None=None, fastapi_options: Mapping[str, Any] | None=None) -> Any

Release source · Runtime guarantees · Capability guides

`DashboardConfig`

from cayu.server import DashboardConfig

Bundled dashboard exposure, mount, and authorization policy.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`enabled`	`StrictBool`	`True`
`path`	`str`	`DEFAULT_DASHBOARD_PATH`
`directory`	`Path \| None`	`None`
`access`	`ServerAccessConfig \| None`	`None`
`runtime_config`	`Mapping[str, Any]`	`Field(default_factory=dict)`

redact_validation_inputs (method)

DashboardConfig.redact_validation_inputs(value: Any, handler: Any) -> DashboardConfig

validate_directory (method)

DashboardConfig.validate_directory(value: object) -> object

validate_access (method)

DashboardConfig.validate_access(value: Any) -> ServerAccessConfig | None

validate_path (method)

DashboardConfig.validate_path(value: str) -> str

copy_runtime_config (method)

DashboardConfig.copy_runtime_config(value: object) -> dict[str, Any]

freeze_runtime_config (method)

DashboardConfig.freeze_runtime_config(value: Mapping[str, Any]) -> Mapping[str, Any]

serialize_runtime_config (method)

DashboardConfig.serialize_runtime_config(value: Mapping[str, Any]) -> dict[str, Any]

Release source · Runtime guarantees · Capability guides

`DashboardStaticFiles`

from cayu.server import DashboardStaticFiles

Serve dashboard assets with optional auth and React-router fallback.

auth may accept or reject access to the shell and assets. A returned AuthContext.tenant is provenance only and does not filter dashboard assets or the data requested from api_base_url.

Bases: StaticFiles.

init (method)

DashboardStaticFiles.__init__(*, directory: str, html: bool=True, auth: AuthDependency | None=None, base_path: str='/', api_base_url: str='/api', dashboard_config: dict[str, Any] | None=None, **kwargs) -> None

dashboard_pricing_configured (property)

DashboardStaticFiles.dashboard_pricing_configured() -> bool

Whether the resolved browser configuration carries a default price book.

dashboard_pricing_metadata (property)

DashboardStaticFiles.dashboard_pricing_metadata() -> tuple[str, str] | None

Return only the resolved catalog version and opaque generation provenance.

get_response (method)

async DashboardStaticFiles.get_response(path: str, scope: Scope)

Release source · Runtime guarantees · Capability guides

`DevelopmentProductAccess`

from cayu.server import DevelopmentProductAccess

Explicit local-development product identity adapter.

Bases: _ProductAccess.

Fields and attributes

Name	Type	Default
`dependency`	`Any`	`Field(exclude=True, repr=False)`
`kind`	`Literal['development']`	`'development'`

validate_dependency (method)

DevelopmentProductAccess.validate_dependency(value: Any, handler: Any) -> _ProductAccess

Release source · Runtime guarantees · Capability guides

`DocsConfig`

from cayu.server import DocsConfig

FastAPI OpenAPI and interactive documentation exposure.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`enabled`	`StrictBool`	`False`

Release source · Runtime guarantees · Capability guides

`EvalsConfig`

from cayu.server import EvalsConfig

Authenticated durable execution for one explicitly attached eval target.

target and store are trusted runtime wiring. They are excluded from representations and serialization so application objects, provider configuration, credentials, and database handles cannot cross diagnostics or configuration boundaries.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`target`	`CorpusTarget \| WorkflowEvalTarget`	`Field(exclude=True, repr=False)`
`store`	`EvalStore`	`Field(exclude=True, repr=False)`
`execution_capacity`	`EvalExecutionCapacity`	`Field(default_factory=EvalExecutionCapacity, exclude=True, repr=False)`
`execution_profile_policy`	`EvalExecutionProfilePolicyV1`	`Field(default_factory=EvalExecutionProfilePolicyV1.safe_default)`
`lease_seconds`	`StrictInt`	`Field(default=DEFAULT_EVAL_LEASE_SECONDS, ge=1, le=EVAL_STORE_MAX_LEASE_SECONDS)`
`poll_interval_seconds`	`StrictFloat`	`Field(default=DEFAULT_EVAL_POLL_INTERVAL_SECONDS, gt=0, le=60)`
`shutdown_grace_seconds`	`StrictFloat`	`Field(default=DEFAULT_EVAL_SHUTDOWN_GRACE_SECONDS, gt=0, le=300)`

validate_runtime_wiring (method)

EvalsConfig.validate_runtime_wiring(value: Any, handler: Any) -> EvalsConfig

validate_finite_seconds (method)

EvalsConfig.validate_finite_seconds(value: float, info) -> float

Release source · Runtime guarantees · Capability guides

`EvaluationPromotionConfig`

from cayu.server import EvaluationPromotionConfig

Authenticated, stateless captured-session promotion policy.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`target_key`	`str`	`required`
`source_agent_name`	`str`	`required`
`application_release_id`	`str`	`required`
`evidence_policy`	`EvaluationEvidencePolicySpec`	`Field(default_factory=EvaluationEvidencePolicySpec.standard)`

validate_target_key (method)

EvaluationPromotionConfig.validate_target_key(value: str) -> str

validate_identity_text (method)

EvaluationPromotionConfig.validate_identity_text(value: str, info) -> str

copy_evidence_policy (method)

EvaluationPromotionConfig.copy_evidence_policy(value: object) -> EvaluationEvidencePolicySpec

Release source · Runtime guarantees · Capability guides

`event_to_sse_data`

from cayu.server import event_to_sse_data

Serialize a runtime Event to a compact JSON string for SSE.

event_to_sse_data(event: Event) -> str

Release source · Runtime guarantees · Capability guides

`mount_cayu`

from cayu.server import mount_cayu

Mount CAYU’s control plane and dashboard into an existing FastAPI app.

This is the high-level adapter for product apps that already own their server. It mounts API routes at {path}/api and the dashboard shell at {path}, so the browser can use one same-origin product path. The dependency-free browser client is served at {path}/client.js with types at {path}/client.d.ts, even when dashboard=False. Its composed lifespan recovers persisted event side effects, then cascade parents inactive for at least interruption_recovery_inactive_after_seconds. On shutdown it closes the app with app.aclose() under one deadline of interruption_shutdown_grace_seconds plus knowledge_publication_shutdown_grace_seconds, and logs every step that did not settle. A shut-down app cannot start another lifespan.

access explicitly selects authenticated or deliberately open access to the complete mounted surface. AuthenticatedAccess wraps the existing auth dependency contract. Authentication does not make the surface tenant-scoped: AuthContext.tenant is operator-action provenance only, and Cayu’s built-in reads are not filtered by it. Treat the mount as an operator surface unless the host application enforces end-to-end tenant authorization and storage isolation.

OpenAccess(trusted_local_development=True) is the embedded equivalent of cayu serve --dev: every mounted route rejects requests unless both the client address and the Host header are loopback, and in exchange durable evals and evaluation_promotion are available without an auth dependency.

The dashboard page sends its own Content-Security-Policy. A host that applies a policy to the mount path must allow at least what cayu.server.static.dashboard_content_security_policy returns: the hashed inline config script, inline styles, base-uri 'self', blob:/data: images and media, and connect-src for the API origin.

dashboard_config must be a JSON object. Cayu validates and copies it before modifying the host application. evaluation_promotion remains disabled unless a complete configuration is supplied and requires authenticated or trusted-local access. Durable eval execution likewise remains disabled unless complete evals wiring is supplied. continuation_loop_policy_provider lets an embedding boundary attach trusted in-process policies to control-plane continuations; HTTP callers cannot supply or serialize those policies.

request_timing records per-request cost for the mounted Cayu routes, and for every host route as well when observe_host_requests is true. The default (None) turns it on for local development, meaning deliberate OpenAccess or a mount assembled by cayu serve, and leaves it off for other authenticated mounts. Pass True or a RequestTimingConfig to opt in, or False to turn it off. observe_host_requests=True also opts in unless timing is explicitly off.

mount_cayu(server: Any, app: CayuApp, *, path: str='/cayu', dashboard: bool=True, dashboard_dir: str | Path | None=None, access: ServerAccessConfig, dashboard_config: dict[str, Any] | None=None, evaluation_promotion: EvaluationPromotionConfig | None=None, evals: EvalsConfig | None=None, replay_idle_timeout_s: float=DEFAULT_REPLAY_IDLE_TIMEOUT_SECONDS, session_follow_heartbeat_s: float=DEFAULT_SESSION_FOLLOW_HEARTBEAT_SECONDS, session_follow_max_streams_per_principal: int=DEFAULT_SESSION_FOLLOW_MAX_STREAMS_PER_PRINCIPAL, session_follow_max_streams_per_session: int=DEFAULT_SESSION_FOLLOW_MAX_STREAMS_PER_SESSION, event_side_effect_startup_timeout_seconds: float=DEFAULT_EVENT_SIDE_EFFECT_STARTUP_TIMEOUT_SECONDS, interruption_shutdown_grace_seconds: float=DEFAULT_INTERRUPTION_SHUTDOWN_GRACE_SECONDS, knowledge_publication_shutdown_grace_seconds: float=DEFAULT_KNOWLEDGE_PUBLICATION_SHUTDOWN_GRACE_SECONDS, interruption_recovery_inactive_after_seconds: int=DEFAULT_RECOVERY_INACTIVE_AFTER_SECONDS, continuation_loop_policy_provider: Callable[[str], Awaitable[tuple[LoopPolicy, ...]]] | None=None, name: str='cayu-dashboard', request_timing: RequestTimingConfig | bool | None=None, observe_host_requests: bool=False, _project_context: ProjectControlPlaneContext | None=None, _system_diagnostics_snapshot_sink: Callable[[SystemDiagnosticsSnapshot], None] | None=None) -> None

Release source · Runtime guarantees · Capability guides

`mount_dashboard`

from cayu.server import mount_dashboard

Mount the built CAYU dashboard on a FastAPI app.

Product apps that compose CAYU with create_router can call this helper after registering their API routes. It serves one subpath-safe dashboard build under dashboard_path and injects runtime config so the dashboard uses the selected mount path.

auth protects only the dashboard shell and static assets; the API at api_base_url must have its own equivalent protection. A returned AuthContext.tenant is provenance only and does not filter dashboard or API data. Treat this helper as an operator surface unless the host proves end-to-end tenant authorization and storage isolation.

dashboard_config must be a JSON object. Cayu validates and takes an owned copy before registering any dashboard route.

Returns True when a dashboard was mounted and False when mounting was disabled, the dashboard directory is absent, or its index.html entrypoint is unavailable.

mount_dashboard(server: Any, *, dashboard_dir: str | Path | None=None, dashboard_path: str | None='/cayu', auth: AuthDependency | None=None, api_base_url: str=SERVER_API_PREFIX, dashboard_config: dict[str, Any] | None=None, name: str='dashboard') -> bool

Release source · Runtime guarantees · Capability guides

`OidcBearerAuth`

from cayu.server import OidcBearerAuth

Verify OIDC/JWT bearer tokens as a Cayu server auth dependency.

Construct it once per process (it caches signing keys) and pass it wherever a server auth dependency is accepted::

auth = OidcBearerAuth(
    issuer="https://example.okta.com/oauth2/default",
    audience="api://cayu",
)
config = ServerConfig.protected(auth)

Each request must carry Authorization: Bearer <JWT>. The token must be signed by a key in the issuer’s JWKS with one of algorithms (asymmetric only), and must carry iss equal to issuer, an audience in audience, and an unexpired exp. nbf and iat are checked when present. All time checks allow leeway_seconds of clock skew.

subject_claim becomes AuthContext.subject. tenant_claim, when set, is required and becomes AuthContext.tenant (actor provenance only; it does not scope Cayu data). required_claims lists claim names that must be present, or maps claim names to the exact value they must have (a list-valued claim must contain it). required_scopes must all appear in the token’s scope or scp claim, otherwise the request gets 403 insufficient_scope. audience_claim names the claim checked against audience; use "client_id" for Amazon Cognito access tokens, which have no aud.

AuthContext.claims holds the token’s standard iss, sub, aud, azp, client_id, scope, scp, exp, and iat values. Pass claims_mapper to choose them yourself: it receives a copy of the verified claims and returns a JSON object of at most 16 KiB.

Rejections return 401 with WWW-Authenticate: Bearer (and error="invalid_token" when a token was presented). Error bodies and logs never include the token. A token whose key the issuer’s current JWKS no longer lists gets 401. When no signing keys can be fetched and no earlier key set is within its stale window, requests get 503 rather than 401.

This verifies tokens that clients already hold. Browser sign-in flows (authorization-code redirects, sessions, refresh) are not provided; put an identity-aware proxy or your own login service in front for those.

init (method)

OidcBearerAuth.__init__(*, issuer: str, audience: str | Sequence[str], jwks_url: str | None=None, algorithms: Sequence[str]=SUPPORTED_OIDC_ALGORITHMS, leeway_seconds: float=DEFAULT_LEEWAY_SECONDS, subject_claim: ClaimPath='sub', tenant_claim: ClaimPath | None=None, audience_claim: str='aud', required_claims: Sequence[str] | Mapping[str, str | int | bool]=(), required_scopes: Sequence[str]=(), realm: str='Cayu', claims_mapper: ClaimsMapper | None=None, max_token_bytes: int=DEFAULT_MAX_TOKEN_BYTES, signing_keys: OidcSigningKeys | None=None, http_client: httpx.AsyncClient | None=None, allow_insecure_loopback: bool=False) -> None

from_environment (method)

OidcBearerAuth.from_environment(issuer_variable: str=OIDC_ISSUER_VARIABLE, audience_variable: str=OIDC_AUDIENCE_VARIABLE, *, environ: Mapping[str, str] | None=None, **options: Any) -> Self

Build OIDC bearer authentication from two environment variables.

The issuer variable holds the exact issuer URL; the audience variable holds one audience or a comma-separated list. Both are read once, when this method is called. A variable that is unset, empty, or whitespace-only, or that holds an unusable issuer URL or no audience, raises AuthConfigurationError naming it (never its value); there is no fallback to open access. Invalid arguments to this method are programming errors and still raise ValueError. Other keyword arguments go to the constructor. environ replaces os.environ as the source.

call (method)

async OidcBearerAuth.__call__(request: Request) -> AuthContext

verify_request (method)

async OidcBearerAuth.verify_request(request: Request) -> dict[str, Any]

Verify the request’s bearer token and return its claims.

Raises HTTPException (401, 403, or 503) with a WWW-Authenticate challenge. Use it to build your own dependency on the same verifier.

verify_token (method)

async OidcBearerAuth.verify_token(token: str) -> dict[str, Any]

Verify one compact JWT and return its claims, or raise OidcTokenError.

auth_context (method)

OidcBearerAuth.auth_context(claims: Mapping[str, Any]) -> AuthContext

Build the AuthContext for already-verified claims.

Raises OidcTokenError when the identity claims cannot form an AuthContext (for example a subject longer than 512 characters).

product_dependency (method)

OidcBearerAuth.product_dependency(*, tenant_claim: ClaimPath | None=None, subject_claim: ClaimPath | None=None) -> Callable[[Request], Awaitable[ProductPrincipal]]

Return a product auth dependency for AuthenticatedProductAccess.

The tenant and subject come only from the verified token: tenant_claim (or the verifier’s own tenant_claim) and subject_claim (or the verifier’s). A token without a usable tenant claim is rejected with 401; there is no default tenant. Both values must be non-blank strings.

Release source · Runtime guarantees · Capability guides

`OidcSigningKeys`

from cayu.server import OidcSigningKeys

Discover, fetch, and cache one issuer’s JWKS signing keys.

Keys are fetched lazily with httpx under a timeout and cached for the JWKS response’s Cache-Control: max-age (bounded to 60 seconds through 24 hours; cache_seconds when absent). An unknown kid triggers at most one refetch per refetch_interval_seconds, concurrent refreshes share one request, and a failed fetch is retried no more than every 5 seconds.

Every authoritative JWKS response (HTTP 200 with a JSON keys array within the size and max_keys bounds) replaces the cached keys, even when it holds no usable signing keys, so a key the issuer withdraws stops verifying tokens at the next refresh, and such tokens get 401 invalid_token. Only a failure to get an authoritative response (network error, timeout, non-200 status, or a malformed, compressed, or oversized document) keeps the previous keys, and then for at most max_stale_seconds (default one hour, 0 disables it) after they expire. A longer window rides out longer issuer outages; a shorter one limits how long keys stay trusted while the issuer cannot be reached. When no key set is usable, verification returns 503.

Issuer and JWKS URLs must use HTTPS. allow_insecure_loopback=True also admits http:// URLs on a loopback host, for tests and local development. Pass http_client to route fetches through your own httpx.AsyncClient (for example an egress proxy); Cayu does not close it.

init (method)

OidcSigningKeys.__init__(issuer: str, *, jwks_url: str | None=None, http_client: httpx.AsyncClient | None=None, allow_insecure_loopback: bool=False, cache_seconds: float=DEFAULT_JWKS_CACHE_SECONDS, refetch_interval_seconds: float=DEFAULT_JWKS_REFETCH_INTERVAL_SECONDS, http_timeout_seconds: float=DEFAULT_HTTP_TIMEOUT_SECONDS, max_keys: int=DEFAULT_MAX_JWKS_KEYS, max_stale_seconds: float=DEFAULT_MAX_STALE_KEY_SECONDS) -> None

discovery_url (property)

OidcSigningKeys.discovery_url() -> str

signing_key (method)

async OidcSigningKeys.signing_key(kid: str, algorithm: str) -> Any

Return the verification key for kid and algorithm.

Raises OidcTokenError (401) when no matching key exists after any allowed refetch, including when the issuer’s current JWKS has no usable keys at all, and OidcTokenError (503) when no authoritative key set could be fetched and no earlier one is within max_stale_seconds of its expiry.

Release source · Runtime guarantees · Capability guides

`OidcTokenError`

from cayu.server import OidcTokenError

A bearer token was rejected, or its signing keys are unavailable.

The message is a fixed category and never contains token contents. error is the RFC 6750 error code (invalid_token or insufficient_scope), or None when verification is temporarily unavailable (status_code 503).

Bases: Exception.

init (method)

OidcTokenError.__init__(reason: str, *, error: str | None='invalid_token', status_code: int=401, scopes: tuple[str, ...]=()) -> None

Release source · Runtime guarantees · Capability guides

`OpenAccess`

from cayu.server import OpenAccess

Deliberate unauthenticated access to the configured server surface.

trusted_local_development=True restricts the surface to loopback requests (client address and Host header) and, in exchange, enables the features cayu serve --dev enables locally: durable Evals execution and evaluation promotion. Use it for a single-developer app bound to loopback.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`kind`	`Literal['open']`	`'open'`
`trusted_local_development`	`bool`	`False`

redact_validation_inputs (method)

OpenAccess.redact_validation_inputs(value: Any, handler: Any) -> OpenAccess

Release source · Runtime guarantees · Capability guides

`OperatorAccess`

from cayu.server import OperatorAccess

OperatorAccess = ServerAccessConfig | PlaceholderOperatorAccess

Release source · Runtime guarantees · Capability guides

`PlaceholderOperatorAccess`

from cayu.server import PlaceholderOperatorAccess

Fail-closed missing operator authentication surfaced by deployment checks.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`kind`	`Literal['placeholder']`	`'placeholder'`

redact_validation_inputs (method)

PlaceholderOperatorAccess.redact_validation_inputs(value: Any, handler: Any) -> PlaceholderOperatorAccess

Release source · Runtime guarantees · Capability guides

`PlaceholderProductAccess`

from cayu.server import PlaceholderProductAccess

Fail-closed missing product authentication surfaced by deployment checks.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`kind`	`Literal['placeholder']`	`'placeholder'`

redact_validation_inputs (method)

PlaceholderProductAccess.redact_validation_inputs(value: Any, handler: Any) -> PlaceholderProductAccess

Release source · Runtime guarantees · Capability guides

`ProductAccess`

from cayu.server import ProductAccess

ProductAccess = AuthenticatedProductAccess | DevelopmentProductAccess | PlaceholderProductAccess

Release source · Runtime guarantees · Capability guides

`ProductExecutionClaimLost`

from cayu.server import ProductExecutionClaimLost

A product worker no longer owns the operation it attempted to settle.

Bases: Exception.

This type’s implementation and inherited behavior are available in the linked release source.

Release source · Runtime guarantees · Capability guides

`ProductIdempotencyConflict`

from cayu.server import ProductIdempotencyConflict

An idempotency identity is already bound to different trusted work.

Bases: Exception.

This type’s implementation and inherited behavior are available in the linked release source.

Release source · Runtime guarantees · Capability guides

`ProductOperation`

from cayu.server import ProductOperation

Application-owned binding between public identity and private Cayu authority.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`tenant_id`	`str`	`Field(max_length=MAX_PRODUCT_IDENTITY_CHARS)`
`subject_id`	`str`	`Field(max_length=MAX_PRODUCT_IDENTITY_CHARS)`
`public_id`	`str`	`Field(max_length=MAX_PRODUCT_IDENTITY_CHARS)`
`work_id`	`str`	`Field(max_length=MAX_PRODUCT_IDENTITY_CHARS)`
`idempotency_key`	`str`	`Field(max_length=MAX_PRODUCT_IDENTITY_CHARS)`
`request_fingerprint`	`str`	`Field(max_length=MAX_PRODUCT_IDENTITY_CHARS)`
`session_id`	`str`	`Field(max_length=MAX_PRODUCT_IDENTITY_CHARS)`
`task_id`	`str`	`Field(max_length=MAX_PRODUCT_IDENTITY_CHARS)`
`request_text`	`str`	`Field(max_length=100000)`
`status`	`Literal['pending', 'completed', 'failed']`	`required`
`result`	`str \| None`	`Field(max_length=100000)`
`result_receipt`	`ProductResultReceipt \| None`	`None`
`recovery_status`	`ProductRecoveryStatus \| None`	`None`

validate_clean_identity (method)

ProductOperation.validate_clean_identity(value: str, info) -> str

validate_request_text (method)

ProductOperation.validate_request_text(value: str) -> str

validate_result_state (method)

ProductOperation.validate_result_state() -> ProductOperation

Release source · Runtime guarantees · Capability guides

`ProductOperationExecutionClaim`

from cayu.server import ProductOperationExecutionClaim

One authoritative attempt to execute pending product work.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`operation`	`ProductOperation`	`required`
`acquired`	`bool`	`required`

Release source · Runtime guarantees · Capability guides

`ProductOperationReservation`

from cayu.server import ProductOperationReservation

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`operation`	`ProductOperation`	`required`
`created`	`bool`	`required`

Release source · Runtime guarantees · Capability guides

`ProductOperationSettlementConflict`

from cayu.server import ProductOperationSettlementConflict

A product operation already has a different terminal result.

Bases: Exception.

This type’s implementation and inherited behavior are available in the linked release source.

Release source · Runtime guarantees · Capability guides

`ProductOperationStore`

from cayu.server import ProductOperationStore

Application-owned authorization, idempotency, and execution boundary.

Claims, heartbeats, and terminal writes must be atomic in the backing store and use its clock for lease expiry. Concurrent heartbeats for the same claim must not shorten its lease. Terminal rows retain the settling claim_id; repeating a write with that identity reconstructs the committed result after an ambiguous acknowledgement loss.

Decorators: @runtime_checkable.

Bases: Protocol.

Fields and attributes

Name	Type	Default
`category`	`ServiceIdentityStoreKind`	`required`

reserve (method)

async ProductOperationStore.reserve(*, tenant_id: str, subject_id: str, idempotency_key: str, request_fingerprint: str, public_id: str, work_id: str, session_id: str, task_id: str, request_text: str) -> ProductOperationReservation

find (method)

async ProductOperationStore.find(*, tenant_id: str, public_id: str) -> ProductOperation | None

find_by_session_id (method)

async ProductOperationStore.find_by_session_id(*, session_id: str) -> ProductOperation | None

Load private product authority for an internal continuation hook.

This lookup is never exposed as a product API and must use the exact application-owned unique session index rather than Cayu labels, metadata, or a scan.

claim_execution (method)

async ProductOperationStore.claim_execution(*, work_id: str, claim_id: str, lease_seconds: int) -> ProductOperationExecutionClaim | None

Acquire, renew, or observe one pending operation atomically.

heartbeat_execution (method)

async ProductOperationStore.heartbeat_execution(*, work_id: str, claim_id: str, lease_seconds: int) -> bool

Extend pending ownership or recognize this claim’s terminal write.

Implementations must return true when the operation is still pending under claim_id and the lease was renewed, or when that exact claim already settled the operation. False means another execution owns or settled the work.

release_execution (method)

async ProductOperationStore.release_execution(*, work_id: str, claim_id: str) -> bool

Relinquish one pending execution claim without clearing a successor.

Implementations must atomically clear claim_id only while that exact claim still owns pending work. True means the claim was cleared or was already unclaimed. False means the operation is terminal or another claim owns it, so this caller no longer owns the operation in either case. Repeating the call after an ambiguous acknowledgement must be safe.

record_result_receipt (method)

async ProductOperationStore.record_result_receipt(*, work_id: str, claim_id: str, receipt: ProductResultReceipt) -> ProductResultReceipt

Insert or reconstruct the exact result receipt owned by claim_id.

Repeating the same content-bound receipt after an ambiguous acknowledgement must return the existing receipt. While work remains pending, its current execution owner may replace a candidate only with one carrying a greater durable source-event sequence. This permits a queued message to advance the same session after an earlier before-stop candidate without allowing stale workers to overwrite newer evidence.

record_recovery_status (method)

async ProductOperationStore.record_recovery_status(*, work_id: str, claim_id: str, recovery_status: ProductRecoveryStatus) -> ProductOperation

Record bounded pending-work evidence under the current execution claim.

Repeating the same status after an ambiguous acknowledgement must reconstruct the current operation. Terminal work and stale claims must reject the update.

finish (method)

async ProductOperationStore.finish(*, work_id: str, claim_id: str, status: Literal['completed', 'failed'], result: str | None) -> ProductOperation

Conditionally settle owned work or reconstruct the same terminal write.

Completed settlement must match the operation’s recorded result receipt. Failed settlement must persist no public result.

Release source · Runtime guarantees · Capability guides

`ProductPrincipal`

from cayu.server import ProductPrincipal

Trusted product identity resolved by server-side authentication.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`tenant_id`	`str`	`Field(max_length=MAX_PRODUCT_IDENTITY_CHARS)`
`subject_id`	`str`	`Field(max_length=MAX_PRODUCT_IDENTITY_CHARS)`

validate_identity (method)

ProductPrincipal.validate_identity(value: str, info) -> str

Release source · Runtime guarantees · Capability guides

`ProductRecoveryStatus`

from cayu.server import ProductRecoveryStatus

ProductRecoveryStatus = Literal['runtime_active', 'waiting_for_approval', 'waiting_for_user_input', 'interrupted', 'manual_reconciliation_required']

Release source · Runtime guarantees · Capability guides

`ProductResultReceipt`

from cayu.server import ProductResultReceipt

Application-owned proof of one exact public result projection.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`record_type`	`Literal['cayu.product-result-receipt']`	`_PRODUCT_RESULT_RECEIPT_RECORD_TYPE`
`schema_version`	`Literal[1]`	`_PRODUCT_RESULT_RECEIPT_SCHEMA_VERSION`
`work_id`	`str`	`Field(max_length=MAX_PRODUCT_IDENTITY_CHARS)`
`public_id`	`str`	`Field(max_length=MAX_PRODUCT_IDENTITY_CHARS)`
`request_fingerprint`	`str`	`Field(max_length=MAX_PRODUCT_IDENTITY_CHARS)`
`session_id`	`str`	`Field(max_length=MAX_PRODUCT_IDENTITY_CHARS)`
`task_id`	`str`	`Field(max_length=MAX_PRODUCT_IDENTITY_CHARS)`
`source_event_id`	`str`	`Field(max_length=MAX_PRODUCT_IDENTITY_CHARS)`
`source_event_sequence`	`StrictInt`	`Field(ge=1, le=MAX_DURABLE_JSON_INTEGER)`
`model_step_id`	`str`	`Field(max_length=MAX_PRODUCT_IDENTITY_CHARS)`
`model_attempt_id`	`str`	`Field(max_length=MAX_PRODUCT_IDENTITY_CHARS)`
`interaction_id`	`str`	`Field(max_length=MAX_PRODUCT_IDENTITY_CHARS)`
`publication_status`	`Literal['completed', 'failed']`	`required`
`result`	`str \| None`	`Field(max_length=MAX_PUBLIC_RESULT_CHARS)`
`failure_code`	`Literal['unsafe_result'] \| None`	`None`
`receipt_digest`	`str`	`Field(pattern='^sha256:[0-9a-f]{64}$')`

create (method)

ProductResultReceipt.create(*, work_id: str, public_id: str, request_fingerprint: str, session_id: str, task_id: str, source_event_id: str, source_event_sequence: int, model_step_id: str, model_attempt_id: str, interaction_id: str, publication_status: Literal['completed', 'failed'], result: str | None, failure_code: Literal['unsafe_result'] | None=None) -> ProductResultReceipt

validate_clean_identity (method)

ProductResultReceipt.validate_clean_identity(value: str, info) -> str

validate_result (method)

ProductResultReceipt.validate_result(value: str | None) -> str | None

validate_digest (method)

ProductResultReceipt.validate_digest() -> ProductResultReceipt

Release source · Runtime guarantees · Capability guides

`ProductResultReceiptConflict`

from cayu.server import ProductResultReceiptConflict

Product work is already bound to a different result receipt.

Bases: Exception.

This type’s implementation and inherited behavior are available in the linked release source.

Release source · Runtime guarantees · Capability guides

`ProjectControlPlaneContext`

from cayu.server import ProjectControlPlaneContext

Opaque project authority assembled by cayu serve and cayu check.

Application factories may pass this object through to Cayu’s maintained service assembler, but cannot construct or rewrite it. Runtime objects and filesystem locations are deliberately absent from its representation.

init (method)

ProjectControlPlaneContext.__init__(*, project_root: Path, project_id: str | None, configured_release_id: str | None, eval_judge_configuration: ProjectEvalJudgeConfiguration | None, eval_price_book: PriceBook | None, eval_store: EvalStore | None, store_backend: Literal['sqlite', 'postgres'] | None, store_source: str | None, access: ProjectControlPlaneAccess, _assembly_token: object | None=None) -> None

project_identity_configured (property)

ProjectControlPlaneContext.project_identity_configured() -> bool

eval_store_configured (property)

ProjectControlPlaneContext.eval_store_configured() -> bool

eval_judge_configured (property)

ProjectControlPlaneContext.eval_judge_configured() -> bool

eval_pricing_configured (property)

ProjectControlPlaneContext.eval_pricing_configured() -> bool

access (property)

ProjectControlPlaneContext.access() -> ProjectControlPlaneAccess

close (method)

async ProjectControlPlaneContext.close() -> None

Close the framework-owned store at most once.

Release source · Runtime guarantees · Capability guides

`PublicServiceManifest`

from cayu.server import PublicServiceManifest

Content-free facts emitted by Cayu’s maintained service assembler.

This does not claim that arbitrary host routes are authorized correctly. It describes only the application assembled by create_agent_service.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal['2']`	`PUBLIC_SERVICE_MANIFEST_SCHEMA_VERSION`
`mode`	`ServiceMode`	`required`
`product_access`	`Literal['authenticated', 'development', 'placeholder']`	`required`
`operator_access`	`Literal['authenticated', 'open', 'placeholder']`	`required`
`identity_store`	`ServiceIdentityStoreKind`	`required`
`runtime_session_store`	`RuntimeStoreDurability`	`required`
`runtime_task_store`	`RuntimeStoreDurability \| Literal['missing']`	`required`
`product_api_path`	`str`	`required`
`control_plane_path`	`str`	`required`
`product_docs`	`Literal['disabled']`	`'disabled'`
`product_cors`	`Literal['disabled']`	`'disabled'`
`host_routing`	`Literal['maintained']`	`'maintained'`

Release source · Runtime guarantees · Capability guides

`RequestTimingConfig`

from cayu.server import RequestTimingConfig

Per-request cost recording and development warnings.

Records carry the method, route template, status, wall time, apportioned process CPU time, response size, and a keyed client hash. They live only in a bounded in-memory ring buffer of buffer_size records. warnings controls the cayu.server.slow_request, cayu.server.growing_cost, and cayu.server.hot_poll log warnings; the buffer is kept either way.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`buffer_size`	`StrictInt`	`Field(default=10000, ge=100, le=1000000)`
`warnings`	`StrictBool`	`True`
`slow_get_threshold_ms`	`float`	`Field(default=250.0, gt=0, le=600000)`
`slow_get_window_seconds`	`float`	`Field(default=300.0, gt=0, le=86400)`
`slow_get_min_requests`	`StrictInt`	`Field(default=5, ge=1, le=10000)`
`growing_cost_bucket_requests`	`StrictInt`	`Field(default=10, ge=2, le=10000)`
`growing_cost_buckets`	`StrictInt`	`Field(default=4, ge=2, le=100)`
`growing_cost_ratio`	`float`	`Field(default=1.5, gt=1, le=1000)`
`growing_cost_min_ms`	`float`	`Field(default=20.0, ge=0, le=600000)`
`hot_poll_requests_per_minute`	`StrictInt`	`Field(default=12, ge=1, le=100000)`
`hot_poll_duration_seconds`	`float`	`Field(default=120.0, gt=0, le=86400)`
`hot_poll_identical_share`	`float`	`Field(default=0.8, gt=0, le=1)`

validate_finite_number (method)

RequestTimingConfig.validate_finite_number(value: object, info) -> float

Release source · Runtime guarantees · Capability guides

`RuntimeStoreDurability`

from cayu.server import RuntimeStoreDurability

Durability evidence declared by a Cayu runtime store implementation.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`DEVELOPMENT`	`class attribute`	`'development'`
`DURABLE`	`class attribute`	`'durable'`
`READ_ONLY`	`class attribute`	`'read_only'`
`UNVERIFIED`	`class attribute`	`'unverified'`

Release source · Runtime guarantees · Capability guides

`ServerAccessConfig`

from cayu.server import ServerAccessConfig

ServerAccessConfig = Annotated[OpenAccess | AuthenticatedAccess, Field(discriminator='kind')]

Release source · Runtime guarantees · Capability guides

`ServerApiConfig`

from cayu.server import ServerApiConfig

Control-plane API exposure and mount policy.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`enabled`	`StrictBool`	`True`
`path`	`str`	`SERVER_API_PREFIX`

validate_path (method)

ServerApiConfig.validate_path(value: str) -> str

Release source · Runtime guarantees · Capability guides

`ServerConfig`

from cayu.server import ServerConfig

Fully resolved Cayu server identity and policy.

This model deliberately knows nothing about where configuration originated. Applications may construct it directly after resolving secrets from any provider. Deployment identity is metadata only and never selects policy.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`deployment_name`	`str`	`DEFAULT_SERVER_DEPLOYMENT_NAME`
`title`	`str`	`DEFAULT_SERVER_TITLE`
`access`	`ServerAccessConfig`	`required`
`api`	`ServerApiConfig`	`Field(default_factory=ServerApiConfig)`
`dashboard`	`DashboardConfig`	`Field(default_factory=DashboardConfig)`
`evaluation_promotion`	`EvaluationPromotionConfig \| None`	`None`
`evals`	`EvalsConfig \| None`	`None`
`browser_control`	`BrowserControlServerConfig \| None`	`None`
`docs`	`DocsConfig`	`Field(default_factory=DocsConfig)`
`cors`	`CorsConfig`	`Field(default_factory=CorsConfig)`
`lifecycle`	`ServerLifecycleConfig`	`Field(default_factory=ServerLifecycleConfig)`
`request_timing`	`RequestTimingConfig \| None`	`None`

redact_validation_inputs (method)

ServerConfig.redact_validation_inputs(value: Any, handler: Any) -> ServerConfig

validate_access (method)

ServerConfig.validate_access(value: Any) -> ServerAccessConfig

validate_nonblank_text (method)

ServerConfig.validate_nonblank_text(value: str, info) -> str

local_development (method)

ServerConfig.local_development(*, deployment_name: str=DEFAULT_SERVER_DEPLOYMENT_NAME, api: ServerApiConfig | None=None, dashboard: DashboardConfig | None=None, lifecycle: ServerLifecycleConfig | None=None, request_timing: RequestTimingConfig | None=_DEFAULT_REQUEST_TIMING) -> ServerConfig

Build an explicitly open local configuration with docs and Vite CORS.

Request timing is on by default here; pass request_timing=None to turn it off.

protected (method)

ServerConfig.protected(dependency: Any, *, deployment_name: str=DEFAULT_SERVER_DEPLOYMENT_NAME, api: ServerApiConfig | None=None, dashboard: DashboardConfig | None=None, docs: DocsConfig | None=None, cors: CorsConfig | None=None, lifecycle: ServerLifecycleConfig | None=None, evaluation_promotion: EvaluationPromotionConfig | None=None, evals: EvalsConfig | None=None, browser_control: BrowserControlServerConfig | None=None, request_timing: RequestTimingConfig | None=None) -> ServerConfig

Build a protected configuration around an application auth dependency.

safe_summary (method)

ServerConfig.safe_summary() -> dict[str, Any]

Return non-secret effective policy suitable for operator diagnostics.

Release source · Runtime guarantees · Capability guides

`ServerLifecycleConfig`

from cayu.server import ServerLifecycleConfig

Recovery, replay, and shutdown behavior owned by the Cayu server.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`replay_idle_timeout_s`	`float`	`DEFAULT_REPLAY_IDLE_TIMEOUT_SECONDS`
`session_follow_heartbeat_s`	`float`	`DEFAULT_SESSION_FOLLOW_HEARTBEAT_SECONDS`
`session_follow_max_streams_per_principal`	`int`	`DEFAULT_SESSION_FOLLOW_MAX_STREAMS_PER_PRINCIPAL`
`session_follow_max_streams_per_session`	`int`	`DEFAULT_SESSION_FOLLOW_MAX_STREAMS_PER_SESSION`
`startup_recovery_statuses`	`frozenset[SessionStatus] \| None`	`None`
`recovery_inactive_after_seconds`	`int`	`DEFAULT_RECOVERY_INACTIVE_AFTER_SECONDS`
`event_side_effect_startup_timeout_seconds`	`float`	`DEFAULT_EVENT_SIDE_EFFECT_STARTUP_TIMEOUT_SECONDS`
`interruption_shutdown_grace_seconds`	`float`	`DEFAULT_INTERRUPTION_SHUTDOWN_GRACE_SECONDS`
`knowledge_publication_shutdown_grace_seconds`	`float`	`DEFAULT_KNOWLEDGE_PUBLICATION_SHUTDOWN_GRACE_SECONDS`

validate_positive_seconds (method)

ServerLifecycleConfig.validate_positive_seconds(value: object, info) -> float

validate_stream_limit (method)

ServerLifecycleConfig.validate_stream_limit(value: object, info) -> int

validate_recovery_inactivity (method)

ServerLifecycleConfig.validate_recovery_inactivity(value: object) -> int

validate_startup_recovery_statuses (method)

ServerLifecycleConfig.validate_startup_recovery_statuses(value: object) -> frozenset[SessionStatus] | None

Release source · Runtime guarantees · Capability guides

`ServiceIdentityStoreKind`

from cayu.server import ServiceIdentityStoreKind

Whether application-owned public/private identity state survives a process.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`DEVELOPMENT`	`class attribute`	`'development'`
`DURABLE`	`class attribute`	`'durable'`

Release source · Runtime guarantees · Capability guides

`ServiceMode`

from cayu.server import ServiceMode

The exposure posture requested from a maintained service factory.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`DEVELOPMENT`	`class attribute`	`'development'`
`PRODUCTION`	`class attribute`	`'production'`

Release source · Runtime guarantees · Capability guides