Axiom Engine

Axiom Engine (axiomai-engine on PyPI) is a headless, LLM-driven narrative game engine. It powers the Axiom AI desktop application, but it has zero GUI dependencies: you can drive it from a Python script, a terminal, a server — or build your own front-end on top of it.

import axiom
from axiom.config import load_config, build_llm_from_config
from axiom.db_helpers import create_new_save

llm = build_llm_from_config(load_config())
save_id = create_new_save("MyWorld.db", "Alice", "Normal")

session = axiom.Session("MyWorld.db", save_id, llm=llm)
result = session.take_turn("I open the tavern door.")
print(result.narrative_text)

What it does

• Persistent universes — each world is a self-contained SQLite database holding entities, stats, rules, lore, locations and scheduled events.

• Universe-as-Code — a universe can be defined as a versionable tree of plain-text files (TOML + Markdown); the .db is just a compiled cache. Compile, decompile, hot-reload, share on Git.

• LLM-arbitrated narration — a configurable LLM backend (Google Gemini, or any OpenAI-compatible API such as Ollama) narrates each turn, applies your universe’s rules, and tracks entity stats.

• Event sourcing & time travel — every turn is an event in a journal. Rewind to any past turn, fork a save into an alternate timeline, or edit a save state by hand.

• Causal time — an in-game clock advances with the story; an off-screen “Chronicler” simulates the rest of the world while the player is away.

• Vector memory (RAG) — long-term memory and lore retrieval backed by a local vector store.

• Content generation — populate a universe (entities, lore, map, rules…) with an LLM, from the command line or from Python.

• Optional scene illustration — generate an image per turn via Stable Diffusion WebUI, ComfyUI or the Gemini image API.

Where to start

• New here? Follow the Quickstart: install the engine, configure an LLM backend and play your first turn — in Python or straight from the terminal.

• Building a universe? Read the Universe-as-Code format and the CLI guide.

• Integrating the engine? Head to the API reference, generated from the source docstrings.

Getting started

• Quickstart
  • Requirements
  • Install
  • Configure an LLM backend
  • Get a universe
  • Play in the terminal
  • Play from Python
  • Where files live
  • Next steps

Guides

• The Universe-as-Code format
  • Layout
  • universe.toml
  • Entities — entities/*.toml
  • Stat definitions — stats/definitions.toml
  • Rules — rules/*.toml
  • Locations — locations/map.toml
  • Lore book — lore/**/*.md
  • Scheduled events — events/*.toml
  • Items — items/*.toml
  • Story setup — setup/questions.toml
  • Compilation and the cache
• The axiom command line
  • Playing
  • Authoring (Universe-as-Code)
  • Saves
• Saves, rewind and sharing
  • Where saves live
  • Rewind and checkpoints
  • Inspecting and editing a save
  • Sharing a save
  • From Python
• Populating a universe with an LLM
  • From the command line
  • What each target generates
  • From Python
  • Practical notes
• LLM backends and configuration
  • The settings file
  • Building backends from Python
  • Environment overrides
• Scene illustration
  • Configuration
  • Backends
  • From Python

Reference

• API reference
  • Core: sessions and universes
  • Configuration and paths
  • Universe-as-Code
  • Saves and event sourcing
  • Content generation
  • LLM backends
  • Runtime internals

Project links

• Source repository (the engine lives in the axiom/ package of the Axiom AI mono-repo)

• PyPI: axiomai-engine

• Issue tracker

Axiom Engine is free software, licensed under the GNU AGPL v3 or later; see the NOTICE file for the attribution requirement (“Based on Axiom AI by 17h59 and Frosoore”).