standard_asr.contract.exceptions

Raised when an error occurs during audio loading or processing.

The audio loading and conversion functions in standard_asr.audio raise this.

Raised when the CONFIGURATION -- supplied or ambient -- is invalid.

The type asserts fault ownership: the configuration's SUPPLIER can fix it (a bad init-config field, a default_language not in selectable_languages, a malformed --config / --set). Who that supplier is depends on the surface, and each surface maps the SAME error accordingly:

• CLI: the invoking user owns the config -- the flags AND the env vars -- so every ConfigError is caller-actionable there: usage exit 2, with the sanitized message naming the field to fix.
• Reference server: a wire client cannot supply engine config at all (construction is zero-arg; options are the portable WireRuntimeParams), so a ConfigError reaching the server -- at construction, transcription, or session establishment -- is a deployment-side fault and maps to a scrubbed 500 (WS internal_error); the client-fixable rejections have their own types (UnsupportedFeatureError -> 422, request validation -> 422). See ConfigurationRequiredError for the absent-config 503 state.

Engine-DECLARATION defects (a malformed declared language tag, an unsatisfiable prepare shape, an IC.6 violation) are NOT this type: they raise EngineContractError, because no configuration value fixes them. An engine that raises ConfigError (or lets a construction-time ValidationError, which ModelRegistry.create wraps into one, escape its factory) for a fault that is NOT about the supplied configuration mis-asserts this ownership contract -- the compliance suite's zero-arg construction check fails such engines (engine_construction_failed); consumers do not second-guess the type. The ValueError mixin serves IN-PROCESS callers, who genuinely can pass a bad config value to a constructor.

The one machine-distinguishable sub-state is ABSENT required configuration: raise (or catch) ConfigurationRequiredError for that -- consumers such as the compliance suite treat "config missing from this environment" (skip) differently from "config invalid" (fail).

Raised when required runtime configuration is ABSENT, not invalid.

The narrow, machine-distinguishable subtype of ConfigError for the one state that is a fact about the ENVIRONMENT rather than about any code or declaration: a required config field (typically a credential) was neither passed explicitly nor found in the environment. Consumers use the distinction to keep two very different verdicts apart:

• the compliance suite SKIPS instantiation-level checks on this error (a credentialed engine on a clean CI is behaving correctly; the verdict must not depend on the runtime's credential state), while
• any other ConfigError -- an invalid supplied value, an internally inconsistent declaration, a factory contract bug -- stays a compliance FAILURE (skipping those would let a broken plugin read as green-with-warning).

from_env raises this automatically when construction failed solely because required fields are missing, so engines following the documented explicit > env > raise pattern get the classification for free. An engine building its config another way should raise this type itself for the missing-credential state.

Transport mapping: the reference server maps this state to HTTP 503 (REST) / a service_unavailable frame (WS) with a stable generic detail -- whether it surfaces at zero-arg engine construction or lazily at transcription/session establishment (an engine deferring its credential check past __init__). An operator-side availability state, never the caller's 422, and never the absent field names (those are deployment detail, safe-logged for the operator only).

Base class for discovery and plugin-related errors.

Raised when a constructed engine breaks the protocol contract.

The runtime counterpart of a compliance failure, in two shapes:

• Runtime behavior: a SYNCHRONOUS StandardASR member (transcribe / start_transcription / supports / recommended_wire_format / prepare) returned an awaitable (an async def implementation, or a sync wrapper delegating to one) or a value outside its protocol-pinned return type. Raised by standard_asr.runtime.protocol_boundary.require_sync_result at the consumer call sites (CLI, reference server) so the defect is loud at the boundary instead of surfacing as a confusing secondary AttributeError (or a silent misreading) deep inside another subsystem.
• Declaration shape: the engine DECLARED something the contract forbids -- a prepare that is a coroutine function, non-callable, or parameter-requiring; a malformed selectable_languages / detectable_languages tag; a language axis without the IC.6 default_language obligation. No caller-side value can fix these, which is what separates them from ConfigError (an invalid configuration VALUE, fixable by whoever supplies the config).

An engine/plugin fault, never a caller mistake -- deliberately NOT a ValueError: transports and the CLI map the ValueError family to caller-fixable surfaces (HTTP 422 / usage exit 2), while this must land on the engine-fault surfaces (scrubbed HTTP 500 / internal_error frame / CLI exit 1). If you hit it as an application developer, report it to the engine's author. Messages carry type names only, never the offending value.

Raised when an entry point name or metadata is invalid.

Raised when FFmpeg is required but not found in the system PATH.

Raised when FFprobe is required but not found in the system PATH.

Raised when an entry point target cannot be imported or is not callable.

Raised when no viable conversion path exists for the provided audio.

This happens when the shape an application provides cannot be negotiated into any shape the engine accepts (for example, a local array given to an engine that only accepts a server-fetchable URL).

Raised when provider_params are invalid for the target engine.

Unlike standard-set parameters, provider_params errors are always raised regardless of strict / best_effort -- they indicate a code-level bug (such as passing one engine's params model to another after a swap).

Raised when a streaming session is driven incorrectly while still live.

A caller-side programming error against an open session -- distinct from StreamClosedError (the stream genuinely ended). It covers the still-live-session usage breaches that are NOT lifecycle-close:

• mixing managed feed() with manual send_audio / end_audio (only one input mode may own a session);
• calling feed() more than once (a session owns at most one fed source);
• iterating the event stream more than once (single-consumer contract).

The session is not closed in any of these cases -- the mistake is in how the application used it. Catching StreamClosedError here would lead an application to wrongly conclude the session terminated and rebuild it. Mixes in ValueError (like ConfigError / InvalidProviderParamError): it is a bad-call programming error. (It has no HTTP mapping: it fires only against an in-process session object, and the server drives its own sessions correctly by construction.)

Base class for every domain error the Standard ASR runtime raises.

It does not cover data-model construction, which is pydantic's: a malformed field on RuntimeParams, on a result model, or on a config raises pydantic.ValidationError. That is a ValueError, not a StandardASRError. Plain caller misuse likewise raises a built-in: ValueError for a bad value (two mutually exclusive arguments), TypeError for a wrong type (an unsupported input type).

except (StandardASRError, ValueError) catches the domain errors and the value mistakes. A TypeError stays outside both on purpose -- a wrong input type is a code bug to fix, not a state to handle.

Raised when audio is delivered to a streaming session that is closed.

Strictly a lifecycle-close breach: the input side is over, so the audio can no longer be consumed. Covers send_audio after end_audio() and send_audio after the session already delivered a terminal event (the audio queue has no consumer anymore). It does NOT cover usage mistakes against a still-live session (mixing feed with manual input, calling feed twice, or iterating the event stream twice) -- those raise InvalidSessionUseError, so an application can tell "the session ended" apart from "my code drove the session incorrectly".

Base for errors that carry machine-readable context beside the message.

Gives the error half of the contract the same "don't make me parse the message" property the diagnostics have: an application can read .param (the offending field/parameter), .hint (actionable guidance), and .details (structured context -- for example, the sanitized pydantic error entries behind a wrapped config failure) without scraping str(exc). Every context field is optional and keyword-only, so Error("message") keeps working while Error("message", param="base_url", hint="use https") is now valid too -- removing the asymmetry where only some exceptions accepted structured fields (spec: explicit > implicit; structured over stringly typed).

Raised by to_srt / to_vtt when segments cannot render as visible cues.

A subtitle cue is an interval claim -- "this text occurs at this time" -- and it must survive the output's millisecond grid to be seen at all. A segment is therefore UNRENDERABLE in either of two ways: it lacks a measured span (Segment.timestamp_status is "start_only" or "unavailable"), or its measured span quantizes to zero milliseconds on the output grid (end and start format to the same timestamp -- players silently drop such cues, so emitting one silently hides the text while the render call reports success). Neither dropping the text nor fabricating timing is the renderer's to choose silently: under the default policy (on_unrenderable="error") it raises this error, and the caller picks the loss explicitly ("omit" drops the unrenderable segments' text from the timed cues; "collapse" renders one whole-text cue with no real timeline). Mixes in ValueError: the caller can fix the call -- choose a policy, or supply renderable segments.

Raised when an engine fails during batch transcription (the cardinal sin guard).

This is the portable batch error contract: when an engine's model inference, network call, or SDK fails inside _transcribe, the failure MUST surface as a TranscriptionError (with the original exception preserved as __cause__ via raise ... from) so an application can catch one type across every engine instead of each engine's native exception (RuntimeError, an SDK error, requests.HTTPError, and so on). It is the batch counterpart of the streaming error event's engine_error code. It denotes an engine/runtime fault, not a caller mistake (those raise ConfigError / UnsupportedFeatureError / InvalidProviderParamError / AudioProcessingError), so the server maps it to a generic 5xx.

Carries the StructuredError fields plus .retriable: when an engine knows a failure is transient (a 503 / timeout / rate-limit) it MAY pass retriable=True so an application can decide whether to retry. None (the default) means "unknown" -- the safe reading is do not assume it is safe to retry.

Raised in strict mode when a requested standard feature is unsupported.

In best_effort mode the unsupported parameter is ignored and a structured diagnostic is returned instead of raising. The strict path carries the same structured context as that diagnostic so callers can inspect which feature was rejected without parsing the message.