Content generation

axiom.populate

axiom.populate — LLM universe authoring.

The seven Creator Studio “Populate” generators, engine-side: each one reads the universe context from the .db, queries the extraction LLM and inserts the new content idempotently (already-known ids/names are skipped). After every write, the text source of a folder universe is resynchronised (the text stays the source of truth).

Zero Qt dependency. The LLM is injectable (llm=) for tests and composition; by default it is built from the user config with the extraction model. Progress messages go through on_status (optional callback) — the Qt tasks plug it into their signals.

populate_entities specificity (TICKET-031): the context is processed in chunks and each chunk is committed immediately — an LLM failure mid-batch (429 quota exhausted despite the backend retries) keeps the work already done, and re-running resumes where it stopped.

axiom.populate.entity_id_for(name)

Stable id derived from an entity name.

A 100% non-Latin name (Cyrillic, CJK…) would yield an empty _safe_id — the entity would then be silently skipped. Deterministic fallback (hash of the name): the Populate idempotency (re-run = resume, known ids skipped) requires ids that are stable from one run to the next.

Parameters:

name (str)

Return type:

str

axiom.populate.populate_meta(db_path, mode='auto', custom_text=None, llm=None, on_status=<function _noop_status>, cancel=None)

Refine the metadata (name, global lore, system prompt, first message).

Parameters:

• db_path (str)

• mode (str)

• custom_text (str | None)

• llm (LLMBackend | None)

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

• cancel (Event | None)

Return type:

bool

axiom.populate.populate_stats(db_path, mode='auto', custom_text=None, llm=None, on_status=<function _noop_status>, cancel=None)

Generate stat definitions. Returns the number inserted.

Parameters:

• db_path (str)

• mode (str)

• custom_text (str | None)

• llm (LLMBackend | None)

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

• cancel (Event | None)

Return type:

int

axiom.populate.populate_rules(db_path, mode='auto', custom_text=None, llm=None, on_status=<function _noop_status>, cancel=None)

Generate game rules. Returns the number inserted.

Parameters:

• db_path (str)

• mode (str)

• custom_text (str | None)

• llm (LLMBackend | None)

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

• cancel (Event | None)

Return type:

int

axiom.populate.populate_events(db_path, mode='auto', custom_text=None, llm=None, on_status=<function _noop_status>, cancel=None)

Schedule world events. Returns the number inserted.

Parameters:

• db_path (str)

• mode (str)

• custom_text (str | None)

• llm (LLMBackend | None)

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

• cancel (Event | None)

Return type:

int

axiom.populate.populate_entities(db_path, mode='auto', custom_text=None, llm=None, on_status=<function _noop_status>, cancel=None)

Generate NPCs/factions from the context (or a free-form instruction).

The context is split into chunks (global lore + each lore entry); each chunk is inserted and committed immediately (TICKET-031): an LLM failure mid-batch keeps the work already done, re-running resumes (existing ids are skipped). Returns the number inserted.

Parameters:

• db_path (str)

• mode (str)

• custom_text (str | None)

• llm (LLMBackend | None)

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

• cancel (Event | None)

Return type:

int

axiom.populate.populate_lore(db_path, mode='auto', custom_text=None, llm=None, on_status=<function _noop_status>, cancel=None)

Extend the Lore Book. Returns the number of inserted entries.

Parameters:

• db_path (str)

• mode (str)

• custom_text (str | None)

• llm (LLMBackend | None)

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

• cancel (Event | None)

Return type:

int

axiom.populate.populate_map(db_path, mode='auto', custom_text=None, llm=None, on_status=<function _noop_status>, cancel=None)

Extend the map (Locations + Connections). Returns {“added_locs”, “added_conns”}.

Parameters:

• db_path (str)

• mode (str)

• custom_text (str | None)

• llm (LLMBackend | None)

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

• cancel (Event | None)

Return type:

dict

axiom.regenerate

axiom.regenerate — regenerating a narrative variant.

Replays turn turn_id with the same player message to produce a new variant of the narrative text (without re-evaluating rules or stats), then appends it to the turn’s multiverse payload in the Event_Log ({“active”: idx, “variants”: […]}).

Zero Qt dependency. Streaming is surfaced through the on_token callback.

axiom.regenerate.history_to_messages(history)

Convert the event-sourced history (user_input / narrative_text) into LLM messages (the active variant is authoritative for the narrative).

Parameters:

history (list[dict])

Return type:

list[dict]

axiom.regenerate.regenerate_variant(llm, db_path, save_id, turn_id, history, system_prompt, user_message, temperature=0.7, top_p=1.0, verbosity_level='balanced', player_id='player_1', on_token=None)

Generate an alternative variant of turn turn_id and record it.

The new variant is appended to the turn’s narrative_text payload and becomes the active variant. Returns the generated text.

Parameters:

• llm (LLMBackend)

• db_path (str)

• save_id (str)

• turn_id (int)

• history (list[dict])

• system_prompt (str)

• user_message (str)

• temperature (float)

• top_p (float)

• verbosity_level (str)

• player_id (str)

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

Return type:

str

axiom.regenerate.append_variant(db_path, save_id, turn_id, text)

Append text as the active variant of a turn’s narrative_text.

A historical non-multiverse payload is converted on the way. Returns False when the turn has no narrative event (nothing is written).

Parameters:

• db_path (str)

• save_id (str)

• turn_id (int)

• text (str)

Return type:

bool

axiom.image_generator

axiom/image_generator.py

Image generator engine for Axiom AI. Translates game/narrative context into visual prompts using the LLM and calls local image generation APIs (Stable Diffusion WebUI, ComfyUI, or mock).

axiom.image_generator.closest_aspect_ratio(width, height)

Return the supported Gemini aspect ratio closest to width/height.

Parameters:

• width (int)

• height (int)

Return type:

str

class axiom.image_generator.ImageGenerator(config, llm=None)

Handles prompt generation and communication with local image generation backends.

Parameters:

• config (AppConfig)

• llm (LLMBackend | None)

config

The AppConfig instance containing image settings.

llm

The LLMBackend instance used for prompt engineering.

generate_prompt(narrative_text, location_desc='', character_desc='', game_state_tag='')

Use the auxiliary LLM to extract a visual prompt from the narrative turn.

Parameters:

• narrative_text (str) – Prose description of the scene.

• location_desc (str) – Optional description of the location/environment.

• character_desc (str) – Optional description of characters present.

• game_state_tag (str) – Optional mood tag (exploration, combat, dialogue, tension).

Returns:

A comma-separated visual prompt optimized for Stable Diffusion.

Return type:

str

generate_image(prompt, save_dir, filename)

Call the configured backend to generate and save an image.

Parameters:

• prompt (str) – Visual prompt.

• save_dir (str | Path) – Path to directory where the image should be saved.

• filename (str) – File name to save under (should end with .png).

Returns:

The absolute path to the generated image file, or None if generation failed.

Return type:

str | None