Core: sessions and universes

axiom.session

axiom/session.py

High-level public API of the Axiom engine (headless, zero Qt).

A Session composes the engine building blocks (Arbitrator, EventSourcer, CheckpointManager, VectorMemory) and exposes a synchronous game loop that any application (GUI, CLI, server) can drive:

from axiom.session import Session
from axiom.config import load_config, build_llm_from_config

llm = build_llm_from_config(load_config())
sess = Session("universes/my_world.axiom", save_id, llm=llm)
result = sess.take_turn("I open the door.", on_token=print)

Streaming happens through the on_token callback. The method is synchronous: on the GUI side, the app wraps it in a QThread (see workers/narrative_worker.py).

axiom.session.IMAGE_GEN_STATUS = 'Generating scene illustration...'

Status string emitted right before contextual image generation starts. Exposed as a constant so the GUI can react (e.g. show a placeholder) without matching a hard-coded English message.

class axiom.session.Session(universe_path, save_id, *, llm, vector_memory=None, data_dir=None, mode='Normal', hero_llm=None, time_llm=None)

High-level wrapper to play one save of a universe.

Parameters:

• universe_path (str | Path) – Path of the universe file (.axiom / SQLite .db).

• save_id (str) – Identifier of the active save.

• llm (LLMBackend) – Pre-built LLM backend (see build_llm_from_config).

• vector_memory (VectorMemory | None) – Vector memory. If None, a VectorMemory is created under <data_dir>/vector/<save_id> (or the app’s default vector folder when data_dir is None).

• data_dir (str | Path | None) – Optional data root for path injection (only used for the default VectorMemory).

• mode (str) – Game mode (‘Normal’, ‘Hardcore’, ‘Companion’).

• hero_llm (LLMBackend | None) – Optional backend for the hero’s decision (Companion mode). If None, lazily built from the config (local extraction_model), like the worker does.

• time_llm (LLMBackend | None)

property turn_id: int

Number of the last played turn (0 if the game has not started).

submit_intent(entity_id, intent_text)

Submit an action intent to the pool for the current turn.

Parameters:

• entity_id (str)

• intent_text (str)

Return type:

None

resolve_tick(*, on_token=None, on_status=None, temperature=0.7, top_p=1.0, verbosity_level='balanced', hero_entity_id=None)

Resolve every intent currently in the pool as a single tick.

Parameters:

• on_token (Callable[[str], None] | None)

• on_status (Callable[[str], None] | None)

• temperature (float)

• top_p (float)

• verbosity_level (str)

• hero_entity_id (str | None)

Return type:

ArbitratorResult

take_turn(player_input, *, player_id='player', on_token=None, on_status=None, on_hero_decision=None, temperature=0.7, top_p=1.0, verbosity_level='balanced', hero_action=None, hero_entity_id=None)

Run a full turn (synchronously) and return the result.

Wraps submit_intent and resolve_tick for backward compatibility.

Parameters:

• player_input (str)

• player_id (str)

• on_token (Callable[[str], None] | None)

• on_status (Callable[[str], None] | None)

• on_hero_decision (Callable[[str], None] | None)

• temperature (float)

• top_p (float)

• verbosity_level (str)

• hero_action (str | None)

• hero_entity_id (str | None)

Return type:

ArbitratorResult

rewind(target_turn_id)

Bring the save back to its state at turn target_turn_id.

Invalidates the Arbitrator’s stats cache and resynchronises turn_id. Returns the summary provided by CheckpointManager.rewind.

Parameters:

target_turn_id (int)

Return type:

dict[str, int]

list_checkpoints()

List the turns for which a checkpoint (snapshot) exists.

Return type:

list[int]

regenerate_variant(turn_id, history, user_message, temperature=0.7, top_p=1.0, verbosity_level='balanced', player_id='player_1', on_token=None)

Regenerate a variant of turn turn_id’s narrative text.

Replays the same player message to produce an alternative text (without re-evaluating rules or stats); the variant is appended to the turn’s multiverse payload and becomes active. Delegates to axiom.regenerate.

Parameters:

• history (list[dict]) – event-sourced history (user_input/narrative_text) up to the previous turn.

• turn_id (int)

• user_message (str)

• temperature (float)

• top_p (float)

• verbosity_level (str)

• player_id (str)

• on_token (Callable[[str], None] | None)

Return type:

str

current_stats()

Current materialised stats per entity (rebuilds the State_Cache).

Returns:

Mapping of entity_id to a dict of stat_key to stat_value strings.

Return type:

dict[str, dict[str, str]]

axiom.universe

axiom/universe.py

Headless representation of an Axiom universe (a .axiom file = SQLite database).

Exposes the metadata (name, system prompt) and the list of saves, with no Qt dependency whatsoever. Entry point: Universe.load(path).

class axiom.universe.Universe(path, name, system_prompt)

A loaded universe (read-only view of its metadata).

Parameters:

• path (str)

• name (str)

• system_prompt (str)

path

Path of the universe file (.axiom / SQLite .db).

name

Display name of the universe.

system_prompt

Founding system prompt handed to the narrator.

classmethod load(universe_path)

Load a universe from its SQLite file.

Parameters:

universe_path (str | Path) – Path to the existing universe file.

Returns:

A Universe instance populated from Universe_Meta.

Return type:

Universe

list_saves()

List this universe’s saves (separate save files + embedded legacy ones).

Return type:

list[dict]