babylon.utils.exceptions

Exception hierarchy for Babylon/Babylon.

Exceptions are contradictions made manifest in code. They represent the system’s failure to reproduce itself.

Error Code Schema: - CFG_XXX: Configuration errors - DB_XXX: Database/persistence errors - EMB_XXX: Embedding/vector errors - VAL_XXX: Validation errors - SYS_XXX: System-level errors - LLM_XXX: LLM generation errors

Exceptions

`BabylonError`(message[, error_code, details])	Base exception for all Babylon/Babylon errors.
`ConfigurationError`(message[, error_code, ...])	Raised when configuration is invalid or missing.
`DataAPIError`(status_code, message, url[, ...])	Base class for data layer API errors.
`DatabaseError`(message[, error_code, details])	Raised when database operations fail.
`EmbeddingError`(message[, error_code, details])	DEPRECATED: Use RagError instead.
`InfrastructureError`(message[, error_code, ...])	Base class for infrastructure-related errors.
`LLMError`(message[, error_code, details])	Raised when LLM generation fails.
`LLMGenerationError`	alias of `LLMError`
`ObserverError`(message[, error_code, details])	Base class for AI/RAG observer layer errors.
`SchemaError`(message[, error_code, details])	Raised when schema validation fails.
`SimulationError`(message[, error_code, details])	Raised when simulation logic fails.
`StorageError`(message[, error_code, details])	Raised when file/storage operations fail.
`TopologyError`(message[, error_code, details])	Raised when graph/topology operations fail.
`ValidationError`(message[, error_code, details])	Raised when data validation fails.

exception babylon.utils.exceptions.BabylonError(message, error_code=None, details=None)[source]

Bases: Exception

Base exception for all Babylon/Babylon errors.

All exceptions in the system inherit from this class, allowing for unified error handling at the boundary.

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

message: Human-readable error description

error_code: Machine-readable error identifier

details: Additional context for debugging

__init__(message, error_code=None, details=None)[source]

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

to_dict()[source]

Serialize exception for logging/API responses.

Return type:: dict[str, object]

log(logger, level=logging.ERROR, exc_info=True)[source]

Log this exception with full structured context.

Convenience method for logging exceptions with their structured data included in the log record’s extra fields.

Parameters:

logger (Logger) – The logger instance to use.
level (int) – Log level (default: ERROR).
exc_info (bool) – Whether to include exception info (default: True).

Return type:

None

Example

try:: risky_operation()
except BabylonError as e:: e.log(logger) # Logs with ERROR level and full context

exception babylon.utils.exceptions.InfrastructureError(message, error_code=None, details=None)[source]

Bases: BabylonError

Base class for infrastructure-related errors.

These errors are typically retryable and represent external system failures (database, network, filesystem). The simulation can often recover from these.

Error codes: INFRA_XXX

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

__init__(message, error_code=None, details=None)[source]

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

exception babylon.utils.exceptions.StorageError(message, error_code=None, details=None)[source]

Bases: InfrastructureError

Raised when file/storage operations fail.

Covers checkpoints, backups, and file I/O.

Error codes: - STOR_001: File not found - STOR_002: File corrupted - STOR_003: Schema validation failed - STOR_004: Write failed

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

__init__(message, error_code=None, details=None)[source]

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

exception babylon.utils.exceptions.ObserverError(message, error_code=None, details=None)[source]

Bases: BabylonError

Base class for AI/RAG observer layer errors.

These errors are non-fatal and represent failures in the narrative/observation layer. The simulation can and should continue without the observer.

Error codes: OBS_XXX

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

__init__(message, error_code=None, details=None)[source]

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

exception babylon.utils.exceptions.DataAPIError(status_code, message, url, error_code=None, details=None)[source]

Bases: InfrastructureError

Base class for data layer API errors.

These errors represent failures when communicating with external data REST APIs (Census Bureau, FRED, EIA, FCC, etc.). They include HTTP status information and the URL that caused the failure.

Distinct from AI/LLM API errors (Claude, DeepSeek, etc.) which would use different exception classes under ObserverError.

Error codes: DAPI_XXX

Parameters:

status_code (int)
message (str)
url (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

status_code: HTTP status code (0 for connection/timeout errors).

message: Error message from API or description of failure.

url: Request URL that caused the error (sensitive params redacted).

__init__(status_code, message, url, error_code=None, details=None)[source]

Parameters:

status_code (int)
message (str)
url (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

exception babylon.utils.exceptions.DatabaseError(message, error_code=None, details=None)[source]

Bases: InfrastructureError

Raised when database operations fail.

The Ledger cannot record the material reality.

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

__init__(message, error_code=None, details=None)[source]

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

exception babylon.utils.exceptions.SchemaError(message, error_code=None, details=None)[source]

Bases: DatabaseError

Raised when schema validation fails.

Base class for schema-related errors such as schema drift, missing tables, or incompatible column types.

Error codes: - SCH_001: General schema error - SCH_002: Schema drift detected - SCH_003: Missing table - SCH_004: Incompatible type

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

__init__(message, error_code=None, details=None)[source]

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

exception babylon.utils.exceptions.ValidationError(message, error_code=None, details=None)[source]

Bases: BabylonError

Raised when data validation fails.

The input does not conform to the schema of material reality.

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

__init__(message, error_code=None, details=None)[source]

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

exception babylon.utils.exceptions.ConfigurationError(message, error_code=None, details=None)[source]

Bases: ValidationError

Raised when configuration is invalid or missing.

The material conditions for operation have not been established.

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

__init__(message, error_code=None, details=None)[source]

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

exception babylon.utils.exceptions.SimulationError(message, error_code=None, details=None)[source]

Bases: BabylonError

Raised when simulation logic fails.

The dialectical process has encountered a fatal contradiction.

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

__init__(message, error_code=None, details=None)[source]

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

exception babylon.utils.exceptions.TopologyError(message, error_code=None, details=None)[source]

Bases: SimulationError

Raised when graph/topology operations fail.

The relations of production cannot be computed.

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

__init__(message, error_code=None, details=None)[source]

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

exception babylon.utils.exceptions.LLMError(message, error_code=None, details=None)[source]

Bases: ObserverError

Raised when LLM generation fails.

The ideological superstructure cannot produce narrative.

Error codes: - LLM_001: General API error - LLM_002: Timeout error - LLM_003: Rate limit exceeded

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

__init__(message, error_code=None, details=None)[source]

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

babylon.utils.exceptions.LLMGenerationError: alias of LLMError

exception babylon.utils.exceptions.EmbeddingError(message, error_code=None, details=None)[source]

Bases: BabylonError

DEPRECATED: Use RagError instead.

Raised when embedding operations fail. The Archive cannot encode semantic meaning.

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None

__init__(message, error_code=None, details=None)[source]

Parameters:

message (str)
error_code (str | None)
details (dict[str, object] | None)

Return type:

None