Phase 01: Data Model, Project Structure, Save Format, and Versioning¶

theact/
  .env                      # LLM_API_KEY, model config
  .env.example
  .gitignore
  pyproject.toml
  main.py                   # Entry point (Phase 04)
  src/
    theact/
      __init__.py
      models/
        __init__.py
        world.py            # World model
        character.py        # Character model
        chapter.py          # Chapter model
        state.py            # GameState model
        memory.py           # CharacterMemory model
        conversation.py     # ConversationEntry model
        game.py             # Game (aggregate root — loads everything)
      io/
        __init__.py
        yaml_io.py          # Load/dump YAML, model serialization
        save_manager.py     # Create save, load save, list saves
      versioning/
        __init__.py
        git_save.py         # Git init, commit, undo, history
      engine/               # Phase 03
      agents/               # Phase 03
      llm/                  # Phase 02
      cli/                  # Phase 04
  games/
    lost-island/            # Example game definition
      game.yaml
      world.yaml
      characters/
        maya.yaml
        joaquin.yaml
      chapters/
        01-the-crash.yaml
        02-survival.yaml
  saves/                    # Created at runtime, gitignored from project repo
    lost-island-001/        # Each save is its own git repo
      ...
  tests/
    __init__.py
    test_models.py
    test_yaml_io.py
    test_save_manager.py
    test_git_save.py
    conftest.py             # Fixtures: sample game data, tmp dirs

games/lost-island/
  game.yaml                 # Metadata: title, description, character list, chapter order
  world.yaml                # Setting, tone, rules — one short paragraph each
  characters/
    maya.yaml
    joaquin.yaml
  chapters/
    01-the-crash.yaml
    02-survival.yaml
    03-the-discovery.yaml

saves/lost-island-001/
  .git/                     # Git repo — one commit per turn
  game.yaml                 # Copied from game definition (immutable)
  world.yaml                # Copied from game definition (immutable)
  characters/
    maya.yaml               # Copied from game definition (immutable)
    joaquin.yaml            # Copied from game definition (immutable)
  chapters/
    01-the-crash.yaml       # Copied from game definition (immutable)
    02-survival.yaml        # Copied from game definition (immutable)
  state.yaml                # Created at save init — mutable, updated each turn
  conversation.yaml         # Created at save init — append-only, one entry per message
  memory/
    maya.yaml               # Created when Maya first acts — rolling memory per character
    joaquin.yaml            # Created when Joaquin first acts
  summaries.yaml            # Chapter summaries — appended as chapters complete

# src/theact/models/game.py

from pydantic import BaseModel, ConfigDict

class GameMeta(BaseModel):
    """Top-level game definition metadata. Loaded from game.yaml."""
    model_config = ConfigDict(extra="forbid")

    id: str                    # URL-safe slug, e.g. "lost-island"
    title: str                 # Display name, e.g. "The Lost Island"
    description: str           # One-sentence pitch
    characters: list[str]      # Character file stems, e.g. ["maya", "joaquin"]
    chapters: list[str]        # Chapter file stems in order, e.g. ["01-the-crash", ...]

# src/theact/models/world.py

from pydantic import BaseModel, ConfigDict

class World(BaseModel):
    """World definition. Loaded from world.yaml. Keep each field to 1-3 sentences."""
    model_config = ConfigDict(extra="forbid")

    setting: str               # Where and when. ~2 sentences.
    tone: str                  # Narrative voice and style. ~2 sentences.
    rules: str                 # Key constraints the narrator must follow. ~2 sentences.

# src/theact/models/character.py

from pydantic import BaseModel, ConfigDict

class Character(BaseModel):
    """Character definition. Loaded from characters/<name>.yaml. ~60 words total."""
    model_config = ConfigDict(extra="forbid")

    name: str                  # Display name
    role: str                  # One-line role in the story
    personality: str           # Core traits, speech patterns. 2-3 sentences.
    secret: str                # Hidden motivation or knowledge. 1 sentence.
    relationships: dict[str, str]  # name -> one-line relationship stance

# src/theact/models/chapter.py

from pydantic import BaseModel, ConfigDict

class Chapter(BaseModel):
    """Chapter definition. Loaded from chapters/<id>.yaml."""
    model_config = ConfigDict(extra="forbid")

    id: str                    # e.g. "01-the-crash"
    title: str                 # e.g. "The Crash"
    summary: str               # What this chapter is about. 2-3 sentences.
    beats: list[str]           # Key events that should happen. Short phrases.
    completion: str            # What must be true for chapter to end. 1 sentence.
    characters: list[str]      # Which characters are active in this chapter.
    next: str | None = None    # Next chapter id, or None if final chapter.

# src/theact/models/state.py

from pydantic import BaseModel, ConfigDict

class GameState(BaseModel):
    """Mutable game state. Written to state.yaml. Updated every turn."""
    model_config = ConfigDict(extra="forbid")

    player_name: str
    current_chapter: str       # Chapter id
    turn: int                  # Monotonically increasing turn counter
    beats_hit: list[str]       # Beat phrases from current chapter that have occurred
                               # Reset to [] when chapter advances.
    flags: dict[str, str]      # Arbitrary key-value pairs set by agents
    chapter_history: list[str] # List of completed chapter ids
    rolling_summary: str = ""  # Incremental summary of expired conversation turns.
                               # Updated when old turns are trimmed from context window.
                               # Used by context assembly (Phase 03) to give agents
                               # a compressed view of earlier events.

# src/theact/models/conversation.py

from pydantic import BaseModel, ConfigDict
from typing import Literal

class ConversationEntry(BaseModel):
    """Single message in the conversation log. Appended to conversation.yaml."""
    model_config = ConfigDict(extra="forbid")

    turn: int
    role: Literal["narrator", "character", "player"]
    character: str | None = None   # Set when role is "character"
    content: str

# src/theact/models/memory.py

from pydantic import BaseModel, ConfigDict

class CharacterMemory(BaseModel):
    """Per-character rolling memory. Written to memory/<name>.yaml."""
    model_config = ConfigDict(extra="forbid")

    character: str             # Character name
    summary: str               # Rolling summary of what this character knows/feels.
                               # Updated each turn by merging new info into existing summary.
                               # ~3-5 sentences. Never grows unbounded.
    key_facts: list[str]       # Important discrete facts. Max ~10, oldest pruned.

# src/theact/models/chapter.py  (same file, additional model)

class ChapterSummary(BaseModel):
    """Summary of a completed chapter. Appended to summaries.yaml."""
    model_config = ConfigDict(extra="forbid")

    chapter_id: str
    title: str
    summary: str               # 2-3 sentence summary of what happened.

# src/theact/models/game.py  (same file, additional model)

class LoadedGame(BaseModel):
    """A fully loaded game with all data resolved. Not persisted — constructed in memory."""
    model_config = ConfigDict(extra="forbid")

    meta: GameMeta
    world: World
    characters: dict[str, Character]       # keyed by character file stem
    chapters: dict[str, Chapter]           # keyed by chapter id
    state: GameState
    conversation: list[ConversationEntry]
    memories: dict[str, CharacterMemory]   # keyed by character name
    chapter_summaries: list[ChapterSummary]
    save_path: Path                        # Absolute path to save directory

    # Note: characters and memories dicts are keyed by file stem (e.g. "maya"),
    # while Character.name and CharacterMemory.character store display names
    # (e.g. "Maya Chen"). The save_manager must handle this mapping.                        # Absolute path to save directory

id: lost-island
title: The Lost Island
description: Survivors of a plane crash on an uncharted island discover something ancient beneath the jungle.
characters:
  - maya
  - joaquin
chapters:
  - 01-the-crash
  - 02-survival
  - 03-the-discovery

setting: >
  Uncharted volcanic island, South Pacific, 2024. Survivors of Flight NZ-417
  crashed into the northern reef. No GPS, no radio, no rescue coming.

tone: >
  Second person, present tense. Sensory-first narration. Slow-burn tension
  through small wrong details. 150-300 words per turn.

rules: >
  The supernatural is always ambiguous — every anomaly has a mundane explanation.
  NPCs remember everything. Never break the second-person frame.

name: Maya Chen
role: Fellow crash survivor, pragmatic engineer, player's primary ally.
personality: >
  Direct, sharp, dry humor. Speaks in short declarative sentences.
  Competence is her coping mechanism — idle hands make her anxious.
  Slow to trust, fiercely loyal once earned.
secret: Racing home to her estranged mother who has cancer.
relationships:
  joaquin: "Respects his calm but distrusts his evasiveness."

name: Father Joaquin Reyes
role: Mysterious priest who has been to this island before.
personality: >
  Calm, cryptic, speaks in parables and questions. Genuinely kind but
  evasive about specifics. Gets quieter when most serious.
  Never raises his voice.
secret: Visited this island 40 years ago. His companions entered the caves and never returned.
relationships:
  maya: "Admires her strength but worries about her refusal to accept mystery."

id: 01-the-crash
title: The Crash
summary: >
  Player wakes alone on the beach amid wreckage. They explore, find evidence
  of death, and discover Maya — the first sign they are not alone.
beats:
  - Player wakes on the beach, disoriented and injured
  - Explores crash debris and finds supplies
  - Discovers a body — death is real here
  - Finds Maya working alone beyond the headland
  - Together they establish a basic camp
  - First night — strange sounds from the jungle
completion: Player and Maya have established camp and survived the first night.
characters:
  - maya
next: 02-survival

player_name: ""
current_chapter: 01-the-crash
turn: 0
beats_hit: []
flags: {}
chapter_history: []
rolling_summary: ""

- turn: 1
  role: narrator
  content: >
    You open your eyes to white light and the taste of salt. Sand grinds
    against your cheek. Your left arm is pinned under something heavy.
    Somewhere beyond the ringing in your ears, waves break against metal.

- turn: 1
  role: player
  content: I try to free my arm and look around.

- turn: 1
  role: narrator
  content: >
    You wrench your arm free — a duffel bag, half-buried. Sitting up sends
    the world tilting. Beach. Wreckage. No engines. No voices. Just the reef
    and the wind and the cry of a single bird circling overhead.

- turn: 2
  role: character
  character: Maya Chen
  content: >
    She looks up sharply, a strip of seatbelt dangling from one hand. Her
    eyes sweep you head to toe — assessing, not greeting. "You're bleeding.
    How many others did you see?"

character: Maya Chen
summary: >
  Met the player on the beach after the crash. They seem resourceful —
  found supplies before finding her. Worked together to build camp.
  Heard the drums that first night but neither of us spoke about it.
key_facts:
  - Player found a lighter and first-aid kit
  - Camp is in the fuselage section on north beach
  - Strange drumming sound from jungle at nightfall

- chapter_id: 01-the-crash
  title: The Crash
  summary: >
    Player woke amid the wreckage of Flight NZ-417. Found Maya beyond the
    headland. Together they built a camp in the fuselage. That first night,
    they both heard drums from the jungle but said nothing.

# src/theact/io/yaml_io.py

from pathlib import Path
from typing import TypeVar, Type
from pydantic import BaseModel
import yaml

T = TypeVar("T", bound=BaseModel)

def load_yaml(path: Path, model: Type[T]) -> T:
    """Load a YAML file and validate it against a Pydantic model."""
    with open(path) as f:
        data = yaml.safe_load(f)
    return model.model_validate(data)

def load_yaml_list(path: Path, model: Type[T]) -> list[T]:
    """Load a YAML file containing a list and validate each item."""
    with open(path) as f:
        data = yaml.safe_load(f)
    if data is None:
        return []
    return [model.model_validate(item) for item in data]

def dump_yaml(path: Path, model: BaseModel) -> None:
    """Serialize a Pydantic model to YAML and write to file."""
    path.parent.mkdir(parents=True, exist_ok=True)
    with open(path, "w") as f:
        yaml.dump(
            model.model_dump(exclude_none=True),
            f,
            default_flow_style=False,
            allow_unicode=True,
            sort_keys=False,
        )

def dump_yaml_list(path: Path, models: list[BaseModel]) -> None:
    """Serialize a list of Pydantic models to YAML and write to file."""
    path.parent.mkdir(parents=True, exist_ok=True)
    data = [m.model_dump(exclude_none=True) for m in models]
    with open(path, "w") as f:
        yaml.dump(
            data,
            f,
            default_flow_style=False,
            allow_unicode=True,
            sort_keys=False,
        )

def append_yaml_entry(path: Path, model: BaseModel) -> None:
    """Append a single model as a YAML list entry to an existing file.

    If the file doesn't exist or is empty, creates it with a single-item list.
    If the file exists, loads the list, appends, and rewrites.

    Note: For conversation.yaml, this means a full rewrite on each append.
    At 500 turns with ~4 messages per turn, that's ~2000 entries — still fast
    since each entry is a few lines of text. If this ever becomes a bottleneck,
    we can switch to streaming YAML output, but premature optimization is
    not warranted here.
    """
    if path.exists():
        with open(path) as f:
            data = yaml.safe_load(f) or []
    else:
        path.parent.mkdir(parents=True, exist_ok=True)
        data = []
    data.append(model.model_dump(exclude_none=True))
    with open(path, "w") as f:
        yaml.dump(
            data,
            f,
            default_flow_style=False,
            allow_unicode=True,
            sort_keys=False,
        )

# src/theact/io/save_manager.py

from pathlib import Path
from theact.models.game import GameMeta, LoadedGame
from theact.models.state import GameState

# Resolved relative to project root. Callers (including tests) can override
# by passing explicit paths to create_save/load_save.
GAMES_DIR = Path("games")
SAVES_DIR = Path("saves")

def list_games() -> list[GameMeta]:
    """List all available game definitions."""
    ...

def list_saves() -> list[dict]:
    """List all existing saves with basic info.

    Returns list of dicts with keys: id, game_title, turn, last_modified.
    """
    ...

def create_save(game_id: str, save_id: str, player_name: str) -> Path:
    """Create a new save from a game definition.

    1. Copy game definition files to saves/<save_id>/
    2. Create initial state.yaml with player_name and turn=0
    3. Create empty conversation.yaml
    4. Create empty summaries.yaml
    5. Create memory/ directory
    6. Initialize git repo and make initial commit

    Returns the save directory path.
    """
    ...

def load_save(save_id: str) -> LoadedGame:
    """Load a complete save into memory.

    Reads all YAML files, validates against Pydantic models,
    returns a LoadedGame aggregate.
    """
    ...

def save_state(save_path: Path, state: GameState) -> None:
    """Write updated game state to state.yaml."""
    ...

def append_conversation(save_path: Path, entry: "ConversationEntry") -> None:
    """Append a message to conversation.yaml."""
    ...

def save_memory(save_path: Path, memory: "CharacterMemory") -> None:
    """Write updated character memory to memory/<name>.yaml."""
    ...

def save_summaries(save_path: Path, summaries: list["ChapterSummary"]) -> None:
    """Write the full list of chapter summaries to summaries.yaml (full rewrite).

    Caller must load existing summaries, append, and pass the complete list.
    """
    ...

# src/theact/versioning/git_save.py

from pathlib import Path
from dataclasses import dataclass
from git import Repo  # gitpython

@dataclass
class TurnInfo:
    """Summary of a single turn from git history.
    Uses dataclass (not BaseModel) since this is a transient data carrier,
    never serialized to YAML.
    """
    turn: int
    commit_hash: str
    message: str
    timestamp: str

def init_repo(save_path: Path) -> Repo:
    """Initialize a git repo in the save directory and make the initial commit.

    The initial commit contains the game definition files and empty state/conversation.
    Commit message: 'New game: <game title>'
    """
    ...

def commit_turn(save_path: Path, turn: int, summary: str) -> str:
    """Stage all changes and commit.

    Commit message format: 'Turn <N>: <one-line summary>'
    The summary is a brief description derived from the narrator's output.

    Returns the commit hash.
    """
    ...

def undo(save_path: Path, steps: int = 1) -> int:
    """Undo the last N turns by resetting to HEAD~N.

    Returns the turn number we've rewound to.
    Raises ValueError if steps exceeds available history (excluding initial commit).
    """
    ...

def get_history(save_path: Path) -> list[TurnInfo]:
    """Get the full turn history from git log.

    Returns most recent first. Excludes the initial 'New game' commit.
    Parses turn number from commit message.
    """
    ...

def get_turn_count(save_path: Path) -> int:
    """Get the number of completed turns (number of turn commits)."""
    ...

Commit 0: "New game: The Lost Island"        ← initial state, all game files
Commit 1: "Turn 1: Player wakes on beach"    ← conversation + state changes
Commit 2: "Turn 2: Found Maya"               ← conversation + state + memory
Commit 3: "Turn 3: Built camp together"       ← conversation + state + memory
...

Before undo:    A --- B --- C --- D (HEAD)
After undo(2):  A --- B (HEAD)

dependencies = [
    "openai>=2.29.0",
    "python-dotenv>=1.2.2",
    "pydantic>=2.10.0",
    "pyyaml>=6.0",
    "gitpython>=3.1.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0",
]