babylon.utils

Utility modules for Babylon/Babylon.

These are the tools of production - the means by which the engine transforms inputs into outputs.

exception babylon.utils.BabylonError(message, error_code=None, details=None)

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)

Parameters:

• message (str)

• error_code (str | None)

• details (dict[str, object] | None)

Return type:

None

log(logger, level=logging.ERROR, exc_info=True)

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

to_dict()

Serialize exception for logging/API responses.

Return type:

dict[str, object]

exception babylon.utils.ConfigurationError(message, error_code=None, details=None)

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)

Parameters:

• message (str)

• error_code (str | None)

• details (dict[str, object] | None)

Return type:

None

exception babylon.utils.DatabaseError(message, error_code=None, details=None)

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)

Parameters:

• message (str)

• error_code (str | None)

• details (dict[str, object] | None)

Return type:

None

exception babylon.utils.EmbeddingError(message, error_code=None, details=None)

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)

Parameters:

• message (str)

• error_code (str | None)

• details (dict[str, object] | None)

Return type:

None

exception babylon.utils.ValidationError(message, error_code=None, details=None)

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)

Parameters:

• message (str)

• error_code (str | None)

• details (dict[str, object] | None)

Return type:

None

babylon.utils.retry_on_exception(max_retries=3, delay=1.0, backoff=2.0, exceptions=Exception, logger=None)

Decorator that retries a function on specified exceptions.

Uses exponential backoff to avoid hammering failing resources. This is a materialist approach: we respect the physical constraints of the systems we depend on.

Parameters:

• max_retries (int) – Maximum number of retry attempts

• delay (float) – Initial delay between retries (seconds)

• backoff (float) – Multiplier applied to delay after each retry

• exceptions (type[Exception] | tuple[type[Exception], ...]) – Exception types that trigger a retry

• logger (Logger | None) – Logger instance for retry messages

Return type:

Callable[[TypeVar(F, bound= Callable[..., Any])], TypeVar(F, bound= Callable[..., Any])]

Returns:

Decorated function with retry logic

Example

@retry_on_exception(max_retries=3, delay=1.0, exceptions=(ConnectionError,)) def fetch_data():

return requests.get(”https://api.example.com”)

babylon.utils.backup_chroma(backup_dir=None, backup_name=None)

Create a backup of the ChromaDB data directory.

Parameters:

• backup_dir (Path | None) – Directory to store backups. Defaults to ./backups

• backup_name (str | None) – Name for the backup. Defaults to timestamp-based name.

Return type:

Path

Returns:

Path to the created backup directory

Raises:

• FileNotFoundError – If ChromaDB directory doesn’t exist

• PermissionError – If backup directory isn’t writable

babylon.utils.restore_chroma(backup_path, force=False)

Restore ChromaDB from a backup.

Parameters:

• backup_path (Path) – Path to the backup directory

• force (bool) – If True, overwrite existing ChromaDB data

Raises:

• FileNotFoundError – If backup doesn’t exist

• FileExistsError – If ChromaDB exists and force=False

Return type:

None

Modules

backup	Backup and restore utilities for the Archive (ChromaDB).
exceptions	Exception hierarchy for Babylon/Babylon.
log	Custom logging utilities for Babylon.
retry	Retry decorator for transient failure handling.