aether-sim

Aether

Aether is a Python SDK for persistent, character-driven simulations. You define a world, place characters and objects in it, and change that world only by submitting actions. Accepted actions become events: durable facts the simulation stores, and that each witness can remember and believe.

Models can propose what a character tries. Modules decide what actually happens. Cognition turns committed events into subjective memory and knowledge.

Version 1.0.1 — installable SDK (aether-sim). Inventory, navigation, dialogue, access, containers, time, cognitive encoding, Postgres persistence, and an act-one LangGraph interact loop are in place.

Contents

1. Quickstart
2. Architecture
3. Creating a world
4. Creating characters
5. Actions & events
6. Building modules
7. Cognition
8. AI runtime
9. Persistence
10. LangGraph lifecycle
11. Custom module tutorial
12. Blackwood Manor example
13. OOC example

---

Quickstart

Requirements: Python 3.11+. uv recommended for local development.

pip install aether-sim                 # core simulation SDK
pip install "aether-sim[ai]"           # + LangGraph interact / OpenAI helpers
pip install "aether-sim[postgres]"     # + Neon/Postgres store
pip install "aether-sim[all]"          # ai + postgres

From a git checkout:

uv sync --all-extras

Core runtime needs Pydantic only. Optional extras add LangChain/LangGraph ([ai]) and psycopg ([postgres]). The in-memory path does not need a database or an API key. Copy .env.example to .env only if you want Postgres or an OpenAI chat model.

Minimal typed turn (examples/one_room_demo.py):

from aether import Action, Aether, WorldAction
from aether.modules import InventoryModule

aether = Aether().use(InventoryModule())

world = aether.create_world(
    name="Blackwood Manor",
    description="A mystery mansion full of secrets.",
)

library = world.create_location(
    name="Library",
    description="A quiet room filled with old books.",
)

player = world.create_character(
    name="Detective",
    role="Player",
    location_id=library.id,
)

arthur = world.create_character(
    name="Arthur",
    role="Butler",
    background="Arthur has served the family for thirty years.",
    location_id=library.id,
)

arthur.add_goal("Protect the family reputation.", priority=90)
arthur.learn(
    "No one saw Arthur enter the study.",
    believed_value="true",
    confidence=0.8,
)
arthur.remember(
    "Arthur entered the study at midnight and found the victim already dead.",
    importance=0.95,
    emotion="fear",
)

old_key = world.create_item(
    name="Old Key",
    description="A brass key with strange initials engraved on it.",
    location_id=library.id,
)

action = Action(
    actor_id=player.id,
    target_id=old_key.id,
    data=WorldAction(
        type="pick_up_item",
        module="inventory",
        parameters={"item_id": old_key.id},
    ),
)

result = aether.step(world, action)

print(result.accepted)          # True
print(result.events[0].type)    # item_picked_up
print(player.inventory.item_ids)
print([m.perspective for m in player.memory.episodic])
# ["I picked up the Old Key."]
print([m.perspective for m in arthur.memory.episodic])
# includes "I saw Detective pick up the Old Key."

uv run python examples/one_room_demo.py

Natural-language turns need a chat model and aether.interact:

uv run python examples/manor_interact_demo.py

from aether import Aether
from aether.ai.model import llm
from aether.modules import DialogueModule, InventoryModule, NavigationModule

aether = Aether(model=llm).use(
    InventoryModule(),
    NavigationModule(),
    DialogueModule(),
)
# ... author world, create session ...
result = aether.interact(world, session, "ask Arthur about the key", actor_id=player.id)

Aether() uses InMemoryStore. create_world saves immediately. aether.step encodes cognition and saves again only when the action is accepted. Prefer aether.step(world, action) over bare world.step so cognition and persistence run.

---

Architecture

Rule of thumb: engines and registries are plain Python services. Things that serialize or travel over an API stay as Pydantic models.

How a turn works:

flowchart LR
    Caller["Host app"] --> Step["Aether.step"]
    Step --> Action["Action"]
    Action --> Engine["RuntimeEngine"]
    Engine --> Validate["Validate parameters"]
    Validate --> Handler["Module handler"]
    Handler --> Events["WorldEvents"]
    Events --> Check["Validate event attributes"]
    Check --> Commit["Append events and bump version"]
    Commit --> Cognition["CognitiveEngine"]
    Cognition --> Perceive["Perceive per witness"]
    Perceive --> Mind["Memory + knowledge"]
    Mind --> Store["Persist world and events"]

1. The host builds an Action: who is acting, what they are trying (WorldAction.type), and typed parameters.
2. Prefer aether.step(world, action) so cognition and persistence run.
3. RuntimeEngine validates the action, runs the module handler, validates returned events, appends them, and bumps the world version.
4. CognitiveEngine runs for each witness: module perception handler → episodic/working memory → belief (when importance is high enough).
5. Accepted events and the world snapshot (including updated minds) are saved through the store.

Failures raise AetherError subclasses inside the engine. World.step catches those and returns SimulationResult(accepted=False, reason=...). The world version does not move, and Aether.step does not write anything.

Layout

src/aether/
  aether.py                 SDK entry: store, engine, cognition, AI, step
  domain/                   World, Character, Action, Event, Session, …
  engine/                   RuntimeEngine, registries
  modules/                  inventory, navigation, dialogue, access, …
  content/                  scenario JSON/YAML loader
  cognition/                CognitiveEngine, perception, memory, knowledge
  components/               Goals, inventory, timeline, planner, capabilities
  repositories/             Store, InMemory*, Postgres*, schema.sql
  ai/                       act-one LangGraph interact loop, prompts, model
examples/
  one_room_demo.py
  manor_interact_demo.py
  ooc_session_demo.py
  scenarios/blackwood_manor.json
  scenarios/gated_study.json

SDK surface

aether = Aether()                       # or .memory() / .postgres()
aether.use(InventoryModule())           # chains; returns self
aether.create_world(name, description="")
aether.get_world(world_id)
aether.load_world(world_id)
aether.save(world)
aether.delete_world(world_id)
aether.step(world, action)              # execute → cognize → persist if accepted
aether.interact(world, session, message, actor_id=..., style=..., idempotency_key=..., callbacks=...)
aether.interact_stream(...)             # yields event, narrative_delta, dialogue_line, result
aether.undo(world, session)             # restore previous turn snapshot
aether.fork(world, session)             # branch + restore snapshot
aether.checkout(world, session, "main")
aether.list_actions()

Public exports: Aether, AetherModule, Action, WorldAction, WorldActionEvent, WorldEvent, World, Character, Location, Item.

Errors

---

Creating a world

World is the aggregate root. It owns:

Authoring methods:

• create_location(name, description="")
• connect_locations(from_location_id, to_location_id, bidirectional=True)
• create_character(name, role="", background="", location_id=None)
• create_item(name, description="", location_id=None, owner_id=None)
• create_session(external_player_id=None)
• step(action) -> SimulationResult — simulation only; prefer aether.step
• describe_character / describe_item / describe_location
• determine_witnesses(actor_id) -> list[str]

An item is either in a location or owned by a character, never both. determine_witnesses returns every character whose location_id matches the actor, including the actor.

Or load a scenario file:

from aether.content import load_scenario

world = load_scenario(aether, "examples/scenarios/blackwood_manor.json")
session = world.create_session()

Sessions and timelines

world.create_session() starts a Session on the main branch with timeline, interaction history, runtime context, and an initial world tip snapshot.

branch = aether.fork(world, session)                 # fork current tip
branch = aether.fork(world, session, from_turn_id=t)  # fork a prior turn
aether.checkout(world, session, "main")              # restore another branch
aether.undo(world, session)                          # restore previous turn snapshot

Each completed Aether.interact turn stores a world snapshot. session.history_for_branch() returns lineage-aware history up to the fork point.

---

Creating characters

Memory and Knowledge live on the character (data). CognitiveEngine operates on them; it does not own them.

Capabilities

Characters start with an empty capability set, which means unrestricted (any registered action may be attempted).

If you add one or more capabilities, the character may only perform actions whose required_capability is in that set. By default each registered action requires a capability matching its action type (pick_up_item, move, ask_question, …).

player.add_capability("move")
player.add_capability("pick_up_item")
# player.can("ask_question") -> False; RuntimeEngine will reject ask_question

Pinned facts stay in later prompts:

character.pin_fact("Her name is Mara.", key="name", kind="name")
session.pin_fact("It is raining.", key="weather", kind="scene")

---

Actions & events

An action is an attempt. An event is a committed fact. Rejected attempts do not change the world.

Action(
    actor_id=player.id,
    target_id=old_key.id,
    data=WorldAction(
        type="pick_up_item",
        module="inventory",
        parameters={"item_id": old_key.id},
    ),
)

WorldEvent is the record that survives: envelope fields (id, world_id, actor_id, witnessed_by, …) plus payload data (type, module, attributes).

Query the in-memory log with world.events.latest(), by_type(), by_actor(), and by_witness().

If the detective is not in the library, or someone already holds the key, result.accepted is False and result.reason explains the rule that failed.

---

Building modules

AetherModule subclasses implement register(registry). Registration installs actions, events, and perception handlers.

aether = Aether().use(InventoryModule())

Modules are installed on that SDK instance’s engine. Call use again before load_world after a restart.

List registered mechanics:

aether.list_actions()
aether.engine.modules.list_events()
aether.engine.modules.list_perceptions()

Inventory

• pick_up_item — actor and unowned item must share a location; ownership moves to the actor.
• drop_item — actor must own the item; item returns to the actor’s location. Equipped items must be unequipped first.
• give_item — recipient is action.target_id; same location required. Equipped items must be unequipped first.
• use_item — actor must own the item; modes include keep / consume / transform. Equipped items must be unequipped first.
• equip_item / unequip_item — named slots; item stays owned.

Navigation

• move — destination must exist and be in connected_location_ids; updates character.state.location_id; emits character_moved.

Dialogue

• speak / say_to / ask_question / answer_question — commit speaking events with a topic gist (not polished NL). Targets must share the actor’s location when addressed.
• ask_question — target_character_ids for one or more people; empty list asks the crowd.
• answer_question — reply to a questioner_id, or omit it to answer the room.
• Events: dialogue_spoken, question_asked, question_answered. Surface lines come from generate_dialogue inside aether.interact after those events succeed.

Detective

• examine — inspect an item in reach/inventory or the current location; emits examined.
• search_location — reveal hidden items in the actor’s location; emits location_searched.
• present_evidence — show an owned item to a colocated character without transferring it; emits evidence_presented.

Items may set hidden=True and optional tags at creation.

For a full walkthrough of writing your own module, see Custom module tutorial.

---

Cognition

After accepted events, Aether.step calls CognitiveEngine.encode_events:

1. For each id in event.witnessed_by, run the module perception handler (or a generic fallback).
2. Write an episodic MemoryRecord and a working-memory item from the Perception.
3. If perception importance ≥ 0.4, form or reinforce a Belief from the perception summary (Knowledge.learn upserts by proposition).

Inventory perception examples:

Calling world.step(action) alone skips cognition and store writes. Use aether.step(world, action).

Episodic lines in AI prompts stay capped; memory.consolidate() (also run automatically once a character has four new episodes) folds older episodes into semantic lore.

---

AI runtime

AetherAI holds the engine plus optional LangChain BaseChatModel and Embeddings.

from aether.ai.model import llm
from aether import Aether

aether = Aether(model=llm)

Presentation after committed events is split into two renderers:

1. Narrative — immersive third-person prose (no quoted speech)
2. Dialogue — in-character spoken lines when speaking events occurred

Both use dedicated prompts grounded only in committed events and character briefs.

from aether import PresentationCallbacks, PresentationStyle

def on_delta(text: str) -> None:
    print(text, end="", flush=True)

result = aether.interact(
    world,
    session,
    "ask Mara about tonight, quietly",
    actor_id=player.id,
    style=PresentationStyle(tone="lyrical", length="terse", pov="third"),
    idempotency_key="turn-12",
    callbacks=PresentationCallbacks(on_narrative_delta=on_delta),
)
# Same key returns the stored result and does not apply the beat again.
aether.interact(world, session, "ask Mara about tonight, quietly", idempotency_key="turn-12")

interact_stream yields the same beats as they commit: event, then narrative_delta / dialogue_line, then a final result chunk. Narrative tokens are not emitted before the step commits.

Turn report

InteractionResult.report (TurnReport) summarizes a host turn: decisions, reject reasons, event types, speaking events, dialogue count, NPC actions, cognition counts, the rolling scene_summary, relationship_deltas, and open_questions.

result = aether.interact(world, session, "pick up the key", actor_id=player.id)
print(result.report.event_types)
print(result.report.beliefs_formed)
print(result.report.scene_summary.text if result.report and result.report.scene_summary else "")
print([q.topic for q in (result.report.open_questions if result.report else [])])
print(result.trace.reject_reasons)

Host-facing continuity:

• session.scene_summary is refreshed after each interact and copied onto result.report.scene_summary.
• result.report.relationship_deltas lists trust / affinity / fear / suspicion changes from this turn.
• result.report.open_questions lists question_asked events that no later answer or refusal closed.

Prefer Aether.interact over deprecated Session.interact.

---

Persistence

Aether takes a single Store (not individual repositories):

aether = Aether()                              # InMemoryStore
aether = Aether.memory()                       # explicit in-memory
aether = Aether.postgres(apply_migrations=True)  # Neon / Postgres

PostgresStore reads DATABASE_URL (see .env.example). apply_migrations=True runs src/aether/repositories/schema.sql.

Host apps should go through Aether / Store. Repository classes remain available for custom stores.

---

LangGraph lifecycle

aether.interact runs an act-one LangGraph loop (src/aether/ai/graph.py):

gather_context
  → decide_next_action          # one action or respond
  → validate_action             # reject → decide again
  → execute_action              # aether.step
  → generate_dialogue           # narrative + optional spoken lines
  → npc_react                   # optional one NPC beat
  → loop until respond or max_steps

Conditional edges (src/aether/ai/edges.py) route after decide, validate, execute, presentation, and NPC react. The graph ends when the model chooses to respond or the step budget is exhausted.

Typed aether.step still works with no model. aether.interact(...) requires Aether(model=llm).

---

Custom module tutorial

Minimal speech module:

from pydantic import BaseModel, Field

from aether.domain.actions import Action
from aether.domain.events import WorldActionEvent, WorldEvent
from aether.domain.world import World
from aether.engine.registries import ModuleRegistry
from aether.modules.base import AetherModule


class SpeakParams(BaseModel):
    text: str = Field(..., description="Line the actor says.")


class SpeechAttributes(BaseModel):
    text: str
    speaker_id: str


class SpeechModule(AetherModule):
    name = "speech"
    version = "0.1.0"

    def register(self, registry: ModuleRegistry) -> None:
        registry.actions.register(
            action_type="speak",
            module_name=self.name,
            parameter_model=SpeakParams,
            handler=self.speak,
        )
        registry.events.register(
            event_type="speech_spoken",
            module_name=self.name,
            attribute_model=SpeechAttributes,
        )
        # optional: registry.perceptions.register(...)

    def speak(self, world: World, action: Action) -> list[WorldEvent]:
        params = SpeakParams.model_validate(action.data.parameters)
        return [
            WorldEvent(
                world_id=world.id,
                actor_id=action.actor_id,
                data=WorldActionEvent(
                    type="speech_spoken",
                    module=self.name,
                    attributes={
                        "text": params.text,
                        "speaker_id": action.actor_id,
                    },
                ),
                witnessed_by=world.determine_witnesses(action.actor_id),
            )
        ]

Install it like any built-in module:

aether = Aether().use(SpeechModule())

Handlers return events; they do not mutate the world directly beyond what those events imply. Perception handlers (optional) turn committed events into first-person Perceptions for cognition.

---

Blackwood Manor example

Scenario pack under examples/scenarios/blackwood_manor.json: library, hall, study, detective, butler, and a key.

from aether import Aether
from aether.ai.model import llm
from aether.content import load_scenario
from aether.modules import (
    DetectiveModule,
    DialogueModule,
    InventoryModule,
    NavigationModule,
)

aether = Aether(model=llm).use(
    InventoryModule(),
    NavigationModule(),
    DialogueModule(),
    DetectiveModule(),
)

world = load_scenario(aether, "examples/scenarios/blackwood_manor.json")
session = world.create_session()
player = next(c for c in world.characters.values() if c.identity.name == "Detective")

result = aether.interact(
    world,
    session,
    "examine the key, then ask Arthur about it",
    actor_id=player.id,
)
print(result.narrative)
print(result.dialogue)

Interactive demo:

uv run python examples/manor_interact_demo.py

A locked room and a hidden clue without custom Python: examples/scenarios/gated_study.json (hall, key, locked passage, letter in a closed chest).

---

OOC example

Aether stays the world model. The host renders narrative, dialogue, and report and does not keep a second copy of inventory, location, or secrets.

What not to reinvent in the host: memory, beliefs, relationships, scene continuity, or “who heard that.” Read them back from the character and from TurnReport.

from aether import Aether, PresentationCallbacks, PresentationStyle
from aether.ai.model import llm
from aether.modules import (
    AccessModule,
    ContainerModule,
    DialogueModule,
    InventoryModule,
    NavigationModule,
    SocialModule,
    TimeModule,
)

aether = Aether(model=llm).use(
    InventoryModule(),
    NavigationModule(),
    DialogueModule(),
    SocialModule(),
    AccessModule(),
    ContainerModule(),
    TimeModule(),
)

Long social walkthrough (typed beats, no live model required):

uv run python examples/ooc_session_demo.py

That script plays 10+ beats — whisper privacy, a lie, a refusal, a pin, a key, a container, a schedule, undo, and an idempotent retry — and checks world consistency.

Building a host app

1. Create an SDK instance and install the modules you need.
2. Author a world (code or scenario file), create a session, then call aether.interact for NL turns and/or aether.step for typed actions.
3. Choose a store: default Aether() / Aether.memory() for local/dev; Aether.postgres(apply_migrations=True) for Neon/Postgres.
4. Render result.narrative, result.dialogue, and optionally result.report in your UI.

---

Status

Implemented:

• World authoring, action validation, inventory / navigation / dialogue / access / containers / time / detective handlers, event log, versioning.
• Character memory, beliefs, goals, relationships, inventory, capabilities enforcement.
• CognitiveEngine hooked into Aether.step (perceive → memory → knowledge).
• In-memory and Postgres persistence via Store.
• Aether.interact act-one loop: decide → step → narrative/dialogue → optional npc_react.
• Host turn report (InteractionResult.report) and scenario packing (aether.content.load_scenario).

Not implemented yet:

• Rich per-item effect tables beyond use_item modes.
• Narrative / cinematic generation modes as separate host modes.
• A first-party CLI. Use the examples under examples/ for now.

License

MIT. See LICENSE.