babylon.engine.simdb.database

Simulation database (ephemeral SQLite per-run).

The simulation database provides: 1. Fast row-based storage for time-series analysis 2. Ephemeral storage (each run creates fresh database) 3. Full tick-keyed temporal snapshots (ADR031)

This module replaces the previous DuckDB implementation per ADR030 (Unified SQLite Runtime Architecture).

Usage:

from babylon.engine.simdb import SimulationDB

# In-memory for tests with SimulationDB(in_memory=True) as sim:

sim.con.execute(“INSERT INTO tick_summary VALUES (…)”)

# File-based for production with SimulationDB(run_id=”2024-01-01_scenario_A”) as sim:

sim.record_tick_summary(tick=0, total_c=100.0, …)

Classes

SimulationDB([run_id, in_memory, ...])

Ephemeral SQLite database for simulation state.

class babylon.engine.simdb.database.SimulationDB(run_id=None, in_memory=False, attach_reference=True)

Bases: object

Ephemeral SQLite database for simulation state.

Each simulation run creates a fresh database (or uses in-memory). Implements ADR030 (Unified SQLite Runtime) and ADR031 (Tick-Keyed Temporal Tables).

Parameters:

• run_id (str | None)

• in_memory (bool)

• attach_reference (bool)

run_id

Unique identifier for this simulation run.

db_path

Path to the SQLite file (None for in-memory).

con

sqlite3 connection handle.

__init__(run_id=None, in_memory=False, attach_reference=True)

Initialize simulation database.

Parameters:

• run_id (str | None) – Unique run identifier. Defaults to timestamp-based ID.

• in_memory (bool) – If True, use :memory: database (no persistence).

• attach_reference (bool) – Deprecated. Previously used for DuckDB ATTACH. Now a no-op - reference data should be queried separately.

Return type:

None

transaction()

Context manager for explicit transactions.

Return type:

Iterator[Connection]

Usage:

with sim.transaction() as con:

con.execute(“INSERT INTO …”) con.execute(“UPDATE …”)

Yields:

sqlite3 connection within an active transaction.

Return type:

Iterator[Connection]

record_tick_summary(tick, total_c, total_v, total_s, avg_consciousness, uprising_count)

Record aggregate metrics for a simulation tick.

Parameters:

• tick (int) – Simulation tick number.

• total_c (float) – Total constant capital (c).

• total_v (float) – Total variable capital/wages (v).

• total_s (float) – Total surplus value (s).

• avg_consciousness (float) – Average class consciousness [0,1].

• uprising_count (int) – Number of uprising events this tick.

Return type:

None

set_metadata(key, value)

Store simulation metadata.

Parameters:

• key (str) – Metadata key (e.g., ‘scenario_name’, ‘config_hash’).

• value (str) – Metadata value.

Return type:

None

get_metadata(key)

Retrieve simulation metadata.

Parameters:

key (str) – Metadata key.

Return type:

str | None

Returns:

Metadata value or None if not found.

close()

Close the database connection.

Return type:

None

__enter__()

Context manager entry.

Return type:

SimulationDB

__exit__(exc_type, exc_val, exc_tb)

Context manager exit.

Return type:

None

Parameters:

• exc_type (type[BaseException] | None)

• exc_val (BaseException | None)

• exc_tb (object)

__repr__()

String representation.

Return type:

str