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.

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.

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:
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:
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:
Return type:

None

__init__(message, error_code=None, details=None)[source]
Parameters:
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:
Return type:

None

__init__(message, error_code=None, details=None)[source]
Parameters:
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:
Return type:

None

__init__(message, error_code=None, details=None)[source]
Parameters:
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:
Return type:

None

__init__(message, error_code=None, details=None)[source]
Parameters:
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:
Return type:

None

__init__(message, error_code=None, details=None)[source]
Parameters:
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:
Return type:

None

__init__(message, error_code=None, details=None)[source]
Parameters:
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:
Return type:

None

__init__(message, error_code=None, details=None)[source]
Parameters:
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:
Return type:

None

__init__(message, error_code=None, details=None)[source]
Parameters:
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:
Return type:

None

__init__(message, error_code=None, details=None)[source]
Parameters:
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:
Return type:

None

__init__(message, error_code=None, details=None)[source]
Parameters:
Return type:

None