Python Bindings

The kairos-pylib crate provides Python bindings for the Kairos engine via PyO3 and maturin. The resulting kairos_engine Python module exposes the simulation engine for batch experiments, trace analysis, and integration testing.

Build & Install

pip install maturin

# Development install (editable, linked to source)
cd crates/kairos-pylib
maturin develop

# Build wheel for distribution
maturin build --release
pip install target/wheels/kairos_engine-*.whl

Requires Python 3.9+. No runtime dependencies beyond the compiled extension module.

API Reference

`EngineConfig`

from kairos_engine import EngineConfig

config = EngineConfig(
    columns=25,
    rows=17,
    lambda_=0.65,
    gamma=0.1,
    enable_ghost_traces=True
)

Parameter	Default	Description
`columns`	`25`	Grid width
`rows`	`17`	Grid height
`lambda_`	`0.65`	Lambda parameter (trailing underscore avoids Python keyword conflict)
`gamma`	`0.1`	Gamma parameter
`enable_ghost_traces`	`True`	Enable ghost trace computation

Properties: config.columns, config.rows.

`Engine`

from kairos_engine import Engine, EngineConfig

engine = Engine(EngineConfig(), start_x=0.0, start_y=0.0)

Configuration

Method	Description
`set_seed(seed: int)`	Set RNG seed
`get_seed() -> int`	Get current seed
`set_lambda(v: float)`	Set $\lambda$ parameter
`get_lambda() -> float`	Get $\lambda$ parameter
`set_gamma(v: float)`	Set $\gamma$ parameter
`get_gamma() -> float`	Get $\gamma$ parameter
`set_grid_size(columns: int, rows: int)`	Override grid dimensions

State

Method	Returns	Description
`get_state()`	`dict`	Current engine state (`t`, `b`, `lastMove`, `marker`)
`get_warning()`	`dict`	Warning signal (`active`, `level`, `kind`, `metrics`)

Simulation

Method	Returns	Description
`decide_next_move()`	`str`	Policy-decided move: `"left"`, `"stay"`, or `"right"`
`decide_all_moves()`	`dict`	Mapping of agent IDs to moves
`run_tick(move: str)`	`dict`	Execute single tick with the given move
`run_tick_multi(moves: dict)`	`dict`	Execute multi-agent tick

Trace Recording

Method	Returns	Description
`start_recording(scenario_id=None)`	None	Begin trace recording
`stop_recording()`	`dict` or `None`	End recording and return trace
`export_trace(steps: int, scenario_id=None)`	`dict`	Convenience: record N auto-decided ticks and return trace

Scenario Loading

Method	Description
`load_scenario(scenario)`	Load from dict or JSON string
`load_event_script(events)`	Load EDMS event script

Module-Level Functions

from kairos_engine import load_trace_file, save_trace_file, diff_traces_py

trace = load_trace_file("trace.json")
save_trace_file(trace, "output.json")
result = diff_traces_py(trace_a, trace_b, epsilon=1e-6)

Data Exchange

All complex data (state, warnings, traces) crosses the Python/Rust boundary as Python dicts via JSON round-trip serialization. The overhead is negligible for typical workloads.

Batch Simulation Example

from kairos_engine import Engine, EngineConfig, save_trace_file

config = EngineConfig(columns=25, rows=17)

for seed in range(1000, 2000):
    engine = Engine(config)
    engine.set_seed(seed)
    trace = engine.export_trace(steps=500, scenario_id="standard")
    save_trace_file(trace, f"traces/standard_{seed}.json")

Determinism Testing

from kairos_engine import Engine, EngineConfig, diff_traces_py

config = EngineConfig()

engine_a = Engine(config)
engine_a.set_seed(1207)
trace_a = engine_a.export_trace(steps=200, scenario_id="standard")

engine_b = Engine(config)
engine_b.set_seed(1207)
trace_b = engine_b.export_trace(steps=200, scenario_id="standard")

result = diff_traces_py(trace_a, trace_b, epsilon=1e-6)
assert result["identical"], "Traces should be identical for the same seed"

Thread Safety

Each Engine instance is not thread-safe — do not share a single instance across threads. Multiple independent engines on separate threads are supported.