osrforge.errors
The osr-forge exception hierarchy.
The typed hierarchy covers runtime failures of the work itself — unreadable
sources, provider transport trouble, schema-invalid model output. Programmer
misuse raises stdlib ValueError/TypeError, never these. The hierarchy grows
additively as the package does.
ClefAuthError
Bases: ProviderError
Workers AI refused the token (401). The message tells the user to run wrangler login; nothing refreshes it.
ExtractionError
Bases: OsrForgeError
The extraction work itself failed: the survey found no dungeons or no keyed areas.
Provider failures keep propagating as
ProviderError/
SchemaValidationError; calling a
stage on a workdir whose upstream stage isn't completed is programmer
misuse and raises stdlib ValueError.
FixtureMissError
Bases: ProviderError
No recorded fixture matches the request's fingerprint.
LedgerStopError
Bases: ProviderError
A request's reservation would take a ledger's spend past its stop, so the request wasn't sent.
OsrForgeError
Bases: Exception
Base class for every osr-forge runtime failure.
OverrideError
Bases: OsrForgeError
An override entry cannot take effect.
An unknown monster name, an unknown area or level address that isn't a
well-formed add, contradictory entries, an edge collision after
canonicalization, or a duplicate YAML key. The division of labor, pinned:
addressing errors are loud (this error); content validity flows to the
report — a dangling template_id takes effect and validate_adventure
reports it in report.json.
PdfError
Bases: OsrForgeError
The source PDF is unreadable, encrypted, or violates a configured limit.
ProviderError
Bases: OsrForgeError
A model provider failed: transport, auth, or rate-limit exhaustion.
ReadingFailure
Bases: ProviderError
A reading answer stopped at max_tokens or with a refusal, so there is no answer to check.
Attributes:
| Name | Type | Description |
|---|---|---|
stop_reason |
The stop reason the service returned: |
Record the stop reason beside the message.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
What failed, naming the request kind. |
required |
stop_reason
|
str
|
The service's stop reason. |
required |
SchemaValidationError
Bases: ProviderError
A model response failed the request's JSON Schema after the retry budget.
StaleRecordingError
Bases: ProviderError
A recording's key matches the request, but its stored body isn't the body the current code builds.