API Reference

This section documents the QuestFoundry Python API.

Runtime

The runtime module provides the execution engine.

State Management

Stores

Compiler

The compiler transforms MyST domain files to Python.

Compilation pipeline for QuestFoundry domain.

This module provides the main entry points for compiling MyST domain files into generated Python code. It orchestrates the parser and generators.

Example Usage

Compile the full domain:

from questfoundry.compiler import compile_domain

# Parse and generate
result = compile_domain(
    domain_dir="src/questfoundry/domain",
    output_dir="src/questfoundry/generated"
)

print(f"Generated {len(result)} files")

Command Line:

# From project root
uv run python -m questfoundry.compiler.compile

Parameters

domain_dirstr | Path: Path to the domain directory containing ontology/ subdirectory.
output_dirstr | Path: Path to the generated/models/ output directory.

Returns

dict[str, Path]: Dictionary mapping filename to path of generated files.

Examples

>>> result = compile_ontology(
...     "src/questfoundry/domain",
...     "src/questfoundry/generated/models"
... )
>>> "enums.py" in result
True

questfoundry.compiler.compile.compile_roles(domain_dir, output_dir)[source]

Compile role definitions to Python configurations.

Return type:

dict[str, Path]

Parameters:

domain_dir (str | Path)
output_dir (str | Path)

Parses the domain/roles/*.md files and generates role config files.

Parameters

domain_dirstr | Path: Path to the domain directory containing roles/ subdirectory.
output_dirstr | Path: Path to the generated/roles/ output directory.

Returns

dict[str, Path]: Dictionary mapping filename to path of generated files.

questfoundry.compiler.compile.validate_loops(domain_dir, roles)[source]

Parse and validate loop definitions (no code generation).

Loop definitions serve as documentation and guidance for SR orchestration. They are NOT compiled to executable graphs. This function parses them for validation purposes only.

Return type:

dict[str, LoopIR]

Parameters:

domain_dir (str | Path)
roles (dict[str, RoleIR])

Parameters

domain_dirstr | Path: Path to the domain directory containing loops/ subdirectory.
rolesdict[str, RoleIR]: Available role definitions (for validation).

Returns

dict[str, LoopIR]: Dictionary mapping loop ID to LoopIR (for validation/reference).

Raises

ValueError: If a loop references a role that doesn’t exist.

questfoundry.compiler.compile.compile_domain(domain_dir='src/questfoundry/domain', output_dir='src/questfoundry/generated', *, validate=True)[source]

Compile full domain to generated code.

This is the main entry point for compilation. It compiles: - ontology/ → generated/models/ - roles/ → generated/roles/ - loops/ → generated/loops/

Return type:

dict[str, Path]

Parameters:

domain_dir (str | Path)
output_dir (str | Path)
validate (bool)

Parameters

domain_dirstr | Path: Path to the domain directory.
output_dirstr | Path: Path to the generated output directory.
validatebool, optional: If True, also validate loop definitions against roles (default: True).

Returns

dict[str, Path]: Dictionary mapping filename to path of all generated files.

Generated Models

Auto-generated Pydantic models from domain definitions.

Generated artifact models from domain/ontology/artifacts.md.

These Pydantic models provide type-safe data structures for QuestFoundry artifacts. Each model includes:

Full field documentation via Field(description=…)
Lifecycle states as a class attribute
JSON schema with examples for API documentation
Type hints for IDE autocompletion

class questfoundry.generated.models.artifacts.Act(**data)[source]

Act.

Store: both Lifecycle: draft → review → final

Attributes

titlestr: The act’s title or number
sequenceint: Order within the story
descriptionstr | None: Summary of the act’s narrative purpose (optional)
chapterslist[str] | None: IDs of chapters in this act (optional)
themeslist[str] | None: Thematic elements explored in this act (optional)
visibilityVisibility | None: Export visibility (defaults to ‘public’). Publisher filters based on this. (optional)
statusstr | None: Current lifecycle status (defaults to ‘draft’) (optional)

Examples

Create a Act:

from questfoundry.generated.models import Act

item = Act(
    title="example_title",
    sequence=1,
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'sequence': 1, 'title': 'example_title'}]}, 'title': 'Act'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

LIFECYCLE: ClassVar[list[str]] = ['draft', 'review', 'final']: Valid lifecycle states for this artifact type.

title: str

sequence: int

description: str | None

chapters: list[str] | None

themes: list[str] | None

visibility: Visibility | None

status: str | None

Parameters:

title (str)
sequence (int)
description (str | None)
chapters (list[str] | None)
themes (list[str] | None)
visibility (Visibility | None)
status (str | None)

class questfoundry.generated.models.artifacts.AudioPlan(**data)[source]

Audio Plan.

Store: hot Lifecycle: draft → approved → deferred → completed

Attributes

titlestr: Identifier for this audio plan
section_idstr: Section or scene this audio plan covers
ambientstr | None: Background atmosphere (e.g., ‘dock machinery, distant water’) (optional)
music_cueslist[dict] | None: Music moments with mood, timing, and transition notes (optional)
sfx_cueslist[dict] | None: Sound effect requirements with trigger and description (optional)
voice_notesstr | None: VO/narration guidance (tone, pacing, delivery) (optional)
statusstr | None: Current lifecycle status (optional)
prioritystr | None: Production priority (critical, standard, nice-to-have) (optional)
deferred_reasonstr | None: If deferred, why (optional)

Examples

Create a Audio Plan:

from questfoundry.generated.models import AudioPlan

item = AudioPlan(
    title="example_title",
    section_id="example_section_id",
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'section_id': 'example_section_id', 'title': 'example_title'}]}, 'title': 'Audio Plan'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

LIFECYCLE: ClassVar[list[str]] = ['draft', 'approved', 'deferred', 'completed']: Valid lifecycle states for this artifact type.

title: str

section_id: str

ambient: str | None

music_cues: list[dict] | None

sfx_cues: list[dict] | None

voice_notes: str | None

status: str | None

priority: str | None

deferred_reason: str | None

Parameters:

title (str)
section_id (str)
ambient (str | None)
music_cues (list[dict] | None)
sfx_cues (list[dict] | None)
voice_notes (str | None)
status (str | None)
priority (str | None)
deferred_reason (str | None)

class questfoundry.generated.models.artifacts.Beat(**data)[source]

Beat.

Store: hot Lifecycle: draft → review → final

Attributes

descriptionstr: What happens in this beat
sequence_idstr: Parent sequence this beat belongs to
orderint: Order within the sequence
beat_typestr | None: Category (action, dialogue, revelation, choice, etc.) (optional)
characterslist[str] | None: Character IDs involved in this beat (optional)
state_effectslist[str] | None: State changes triggered by this beat (optional)
statusstr | None: Current lifecycle status (defaults to ‘draft’) (optional)

Examples

Create a Beat:

from questfoundry.generated.models import Beat

item = Beat(
    description="example_description",
    sequence_id="example_sequence_id",
    order=1,
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'description': 'example_description', 'order': 1, 'sequence_id': 'example_sequence_id'}]}, 'title': 'Beat'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

LIFECYCLE: ClassVar[list[str]] = ['draft', 'review', 'final']: Valid lifecycle states for this artifact type.

description: str

sequence_id: str

order: int

beat_type: str | None

characters: list[str] | None

state_effects: list[str] | None

status: str | None

Parameters:

description (str)
sequence_id (str)
order (int)
beat_type (str | None)
characters (list[str] | None)
state_effects (list[str] | None)
status (str | None)

class questfoundry.generated.models.artifacts.Brief(**data)[source]

Brief.

Store: hot Lifecycle: draft → active → completed → cancelled

Attributes

titlestr: Short title describing the work unit
loop_typeLoopType: Which workflow loop this brief belongs to
scopestr: Description of what’s in scope for this work
statusstr | None: Current status (defaults to ‘draft’) (optional)
ownerstr | None: Role ID accountable for this brief (optional)
active_roleslist[str] | None: Role IDs that will work on this brief (optional)
dormant_roleslist[str] | None: Role IDs explicitly not participating (optional)
press_barslist[QualityBar] | None: Quality bars this brief aims to satisfy (optional)
monitor_barslist[QualityBar] | None: Quality bars to watch but not gate on (optional)
inputslist[str] | None: Prerequisite artifact IDs (optional)
deliverableslist[str] | None: Expected output artifact descriptions (optional)
exit_criteriastr | None: What ‘done’ looks like for this brief (optional)
related_hookslist[str] | None: Hook card IDs this brief addresses (optional)

Examples

Create a Brief:

from questfoundry.generated.models import Brief

item = Brief(
    title="example_title",
    loop_type="story_spark",
    scope="example_scope",
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'loop_type': 'story_spark', 'scope': 'example_scope', 'title': 'example_title'}]}, 'title': 'Brief'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

LIFECYCLE: ClassVar[list[str]] = ['draft', 'active', 'completed', 'cancelled']: Valid lifecycle states for this artifact type.

title: str

loop_type: LoopType

scope: str

status: str | None

owner: str | None

active_roles: list[str] | None

dormant_roles: list[str] | None

press_bars: list[QualityBar] | None

monitor_bars: list[QualityBar] | None

inputs: list[str] | None

deliverables: list[str] | None

exit_criteria: str | None

related_hooks: list[str] | None

Parameters:

title (str)
loop_type (LoopType)
scope (str)
status (str | None)
owner (str | None)
active_roles (list[str] | None)
dormant_roles (list[str] | None)
press_bars (list[QualityBar] | None)
monitor_bars (list[QualityBar] | None)
inputs (list[str] | None)
deliverables (list[str] | None)
exit_criteria (str | None)
related_hooks (list[str] | None)

class questfoundry.generated.models.artifacts.CanonEntry(**data)[source]

Canon Entry.

Store: cold Lifecycle: draft → verified → canon

Attributes

titlestr: The canon fact or concept name
contentstr: The verified canonical information
categorystr | None: Classification (character, location, event, rule, etc.) (optional)
statusstr | None: Current verification status (optional)
sourcestr | None: Where this canon originated (optional)
related_entrieslist[str] | None: IDs of related canon entries (optional)
spoiler_levelstr | None: hot (internal) or cold (player-safe) (optional)

Examples

Create a Canon Entry:

from questfoundry.generated.models import CanonEntry

item = CanonEntry(
    title="example_title",
    content="example_content",
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'content': 'example_content', 'title': 'example_title'}]}, 'title': 'Canon Entry'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

LIFECYCLE: ClassVar[list[str]] = ['draft', 'verified', 'canon']: Valid lifecycle states for this artifact type.

title: str

content: str

category: str | None

status: str | None

source: str | None

related_entries: list[str] | None

spoiler_level: str | None

Parameters:

title (str)
content (str)
category (str | None)
status (str | None)
source (str | None)
related_entries (list[str] | None)
spoiler_level (str | None)

class questfoundry.generated.models.artifacts.Chapter(**data)[source]

Chapter.

Store: both Lifecycle: draft → review → final

Attributes

titlestr: The chapter’s title
sequenceint: Order within the act
act_idstr | None: Parent act this chapter belongs to (optional)
sceneslist[str] | None: IDs of scenes in this chapter (optional)
summarystr | None: Brief summary of chapter events (optional)
statusstr | None: Current lifecycle status (optional)
visibilityVisibility | None: Export visibility (defaults to ‘public’). Publisher filters based on this. (optional)

Examples

Create a Chapter:

from questfoundry.generated.models import Chapter

item = Chapter(
    title="example_title",
    sequence=1,
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'sequence': 1, 'title': 'example_title'}]}, 'title': 'Chapter'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

LIFECYCLE: ClassVar[list[str]] = ['draft', 'review', 'final']: Valid lifecycle states for this artifact type.

title: str

sequence: int

act_id: str | None

scenes: list[str] | None

summary: str | None

status: str | None

visibility: Visibility | None

Parameters:

title (str)
sequence (int)
act_id (str | None)
scenes (list[str] | None)
summary (str | None)
status (str | None)
visibility (Visibility | None)

class questfoundry.generated.models.artifacts.Character(**data)[source]

Character.

Store: cold Lifecycle: draft → verified → canon

Attributes

namestr: The character’s primary name
descriptionstr: Physical and personality description
role_in_storystr | None: Narrative function (protagonist, antagonist, mentor, etc.) (optional)
factionstr | None: Primary faction or group affiliation (optional)
relationshipslist[str] | None: IDs of related Relationship artifacts (optional)
first_appearancestr | None: Scene or chapter where character is introduced (optional)
tagslist[str] | None: Categorization tags (mortal, immortal, recurring, etc.) (optional)
statusstr | None: Current lifecycle status (defaults to ‘draft’) (optional)

Examples

Create a Character:

from questfoundry.generated.models import Character

item = Character(
    name="example_name",
    description="example_description",
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'description': 'example_description', 'name': 'example_name'}]}, 'title': 'Character'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

LIFECYCLE: ClassVar[list[str]] = ['draft', 'verified', 'canon']: Valid lifecycle states for this artifact type.

name: str

description: str

role_in_story: str | None

faction: str | None

relationships: list[str] | None

first_appearance: str | None

tags: list[str] | None

status: str | None

Parameters:

name (str)
description (str)
role_in_story (str | None)
faction (str | None)
relationships (list[str] | None)
first_appearance (str | None)
tags (list[str] | None)
status (str | None)

class questfoundry.generated.models.artifacts.Choice(**data)[source]

Choice.

Store: both

Attributes

labelstr: Player-visible text for this choice (e.g., ‘Enter the library’)
targetstr: Anchor of the destination scene this choice leads to
conditionstr | None: Gate condition that must be met for this choice to be available (e.g., ‘has_key’) (optional)
sequenceint | None: Display order among choices (lower numbers first) (optional)
consequencestr | None: Codeword or flag set when this choice is taken (e.g., ‘chose_stealth’) (optional)

Examples

Create a Choice:

from questfoundry.generated.models import Choice

item = Choice(
    label="example_label",
    target="example_target",
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'label': 'example_label', 'target': 'example_target'}]}}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

label: str

target: str

condition: str | None

sequence: int | None

consequence: str | None

Parameters:

label (str)
target (str)
condition (str | None)
sequence (int | None)
consequence (str | None)

class questfoundry.generated.models.artifacts.ColdAct(**data)[source]

Cold Act.

Store: cold

Attributes

idint: Auto-increment primary key
anchorstr: Unique identifier (e.g., ‘act_1’, ‘act_finale’)
titlestr: Act title for display
sequenceint: Order within the story (1-indexed)
descriptionstr | None: Summary of the act’s narrative purpose (optional)
visibilityVisibility | None: Export visibility (defaults to ‘public’) (optional)

Examples

Create a Cold Act:

from questfoundry.generated.models import ColdAct

item = ColdAct(
    id=1,
    anchor="example_anchor",
    title="example_title",
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'anchor': 'example_anchor', 'id': 1, 'sequence': 1, 'title': 'example_title'}]}}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

id: int

anchor: str

title: str

sequence: int

description: str | None

visibility: Visibility | None

Parameters:

id (int)
anchor (str)
title (str)
sequence (int)
description (str | None)
visibility (Visibility | None)

class questfoundry.generated.models.artifacts.ColdAsset(**data)[source]

Cold Asset.

Store: cold

Attributes

anchorstr: Section anchor this asset belongs to (or ‘cover’, ‘logo’)
asset_typeAssetType: Type of asset (plate, cover, audio, font)
filenamestr: Filename in assets directory
file_hashstr: SHA-256 hash of file contents
file_sizeint: File size in bytes
mime_typestr: MIME type (e.g., ‘image/png’, ‘audio/mpeg’)
approved_bystr: Role ID that approved this asset (e.g., ‘gatekeeper’)
approved_atdatetime: When the asset was approved
provenanceAssetProvenance | None: Creation metadata for reproducibility (optional)

Examples

Create a Cold Asset:

from questfoundry.generated.models import ColdAsset

item = ColdAsset(
    anchor="example_anchor",
    asset_type="plate",
    filename="example_filename",
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'anchor': 'example_anchor', 'approved_by': 'example_approved_by', 'asset_type': 'plate', 'file_hash': 'example_file_hash', 'file_size': 1, 'filename': 'example_filename', 'mime_type': 'example_mime_type'}]}}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

anchor: str

asset_type: AssetType

filename: str

file_hash: str

file_size: int

mime_type: str

approved_by: str

approved_at: datetime

provenance: AssetProvenance | None

Parameters:: data (Any)

class questfoundry.generated.models.artifacts.ColdBook(**data)[source]

Cold Book.

Store: cold

Attributes

titlestr: Book title
languagestr: ISO 639-1 language code (e.g., ‘en’, ‘nl’)
start_anchorstr: Anchor of the first section (entry point)
subtitlestr | None: Book subtitle (optional)
authorstr | None: Author name (optional)

Examples

Create a Cold Book:

from questfoundry.generated.models import ColdBook

item = ColdBook(
    title="example_title",
    language="example_language",
    start_anchor="example_start_anchor",
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'language': 'example_language', 'start_anchor': 'example_start_anchor', 'title': 'example_title'}]}}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

title: str

language: str

start_anchor: str

subtitle: str | None

author: str | None

Parameters:

title (str)
language (str)
start_anchor (str)
subtitle (str | None)
author (str | None)

class questfoundry.generated.models.artifacts.ColdChapter(**data)[source]

Cold Chapter.

Store: cold

Attributes

idint: Auto-increment primary key
anchorstr: Unique identifier (e.g., ‘chapter_1’, ‘chapter_discovery’)
titlestr: Chapter title for display
sequenceint: Order within the act (1-indexed)
act_idint | None: Foreign key to parent act (nullable for single-act stories) (optional)
summarystr | None: Brief summary of chapter events (optional)
visibilityVisibility | None: Export visibility (defaults to ‘public’) (optional)

Examples

Create a Cold Chapter:

from questfoundry.generated.models import ColdChapter

item = ColdChapter(
    id=1,
    anchor="example_anchor",
    title="example_title",
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'anchor': 'example_anchor', 'id': 1, 'sequence': 1, 'title': 'example_title'}]}}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

id: int

anchor: str

title: str

sequence: int

act_id: int | None

summary: str | None

visibility: Visibility | None

Parameters:

id (int)
anchor (str)
title (str)
sequence (int)
act_id (int | None)
summary (str | None)
visibility (Visibility | None)

class questfoundry.generated.models.artifacts.ColdSection(**data)[source]

Cold Section.

Store: cold

Attributes

idint: Auto-increment primary key (stable across anchor renames)
anchorstr: Unique identifier for navigation (e.g., ‘scene_001’, ‘hub_market’). Can be renamed without breaking references.
titlestr: Player-visible section title
contentstr: Prose content as structured data. Publisher transforms this to markdown/HTML for export.
orderint: Display order in book (1-indexed)
content_hashstr: SHA-256 hash of content for integrity validation
requires_gatebool | None: Whether this section has access conditions (optional)
source_brief_idstr | None: ID of the Brief that produced this section (lineage) (optional)
choiceslist[Choice] | None: Available choices/exits from this section for interactive fiction (optional)
gateslist[Gate] | None: Gate conditions that control access to this section (optional)
chapter_idint | None: Foreign key to parent chapter (nullable for standalone sections) (optional)
visibilityVisibility | None: Export visibility (defaults to ‘public’). Publisher filters based on this. (optional)

Examples

Create a Cold Section:

from questfoundry.generated.models import ColdSection

item = ColdSection(
    id=1,
    anchor="example_anchor",
    title="example_title",
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'anchor': 'example_anchor', 'content': 'example_content', 'content_hash': 'example_content_hash', 'id': 1, 'order': 1, 'title': 'example_title'}]}}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

id: int

anchor: str

title: str

content: str

order: int

content_hash: str

requires_gate: bool | None

source_brief_id: str | None

choices: list[Choice] | None

gates: list[Gate] | None

chapter_id: int | None

visibility: Visibility | None

Parameters:: data (Any)

class questfoundry.generated.models.artifacts.ColdSnapshot(**data)[source]

Cold Snapshot.

Store: cold

Attributes

snapshot_idstr: Unique identifier (e.g., ‘cold-2025-12-08-001’)
created_atdatetime: When the snapshot was created
manifest_hashstr: SHA-256 hash of the manifest (all section + asset hashes)
section_countint: Number of sections in this snapshot
asset_countint: Number of assets in this snapshot
descriptionstr | None: Human-readable description of this snapshot (optional)

Examples

Create a Cold Snapshot:

from questfoundry.generated.models import ColdSnapshot

item = ColdSnapshot(
    snapshot_id="example_snapshot_id",
    manifest_hash="example_manifest_hash",
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'asset_count': 1, 'manifest_hash': 'example_manifest_hash', 'section_count': 1, 'snapshot_id': 'example_snapshot_id'}]}}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

snapshot_id: str

created_at: datetime

manifest_hash: str

section_count: int

asset_count: int

description: str | None

Parameters:: data (Any)

class questfoundry.generated.models.artifacts.Event(**data)[source]

Event.

Store: cold Lifecycle: draft → verified → canon

Attributes

titlestr: The event’s name
descriptionstr: What happened during this event
whenstr: When the event occurred (relative or absolute)
timeline_idstr | None: Timeline this event belongs to (optional)
participantslist[str] | None: Character or faction IDs involved (optional)
locationstr | None: Location ID where event occurred (optional)
consequenceslist[str] | None: Event IDs that resulted from this event (optional)
spoiler_levelstr | None: hot (internal) or cold (player-safe) (optional)
statusstr | None: Current lifecycle status (defaults to ‘draft’) (optional)

Examples

Create a Event:

from questfoundry.generated.models import Event

item = Event(
    title="example_title",
    description="example_description",
    when="example_when",
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'description': 'example_description', 'title': 'example_title', 'when': 'example_when'}]}, 'title': 'Event'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

LIFECYCLE: ClassVar[list[str]] = ['draft', 'verified', 'canon']: Valid lifecycle states for this artifact type.

title: str

description: str

when: str

timeline_id: str | None

participants: list[str] | None

location: str | None

consequences: list[str] | None

spoiler_level: str | None

status: str | None

Parameters:

title (str)
description (str)
when (str)
timeline_id (str | None)
participants (list[str] | None)
location (str | None)
consequences (list[str] | None)
spoiler_level (str | None)
status (str | None)

class questfoundry.generated.models.artifacts.Fact(**data)[source]

Fact.

Store: cold Lifecycle: draft → verified → canon

Attributes

statementstr: The factual assertion
categorystr | None: Type of fact (geography, history, magic, politics, etc.) (optional)
sourcestr | None: Where this fact originated (optional)
confidencestr | None: Certainty level (canon, provisional, disputed) (optional)
related_entitieslist[str] | None: Character, Location, or Item IDs this fact concerns (optional)
spoiler_levelstr | None: hot (internal) or cold (player-safe) (optional)
tagslist[str] | None: Categorization tags for filtering and search (optional)
statusstr | None: Current lifecycle status (defaults to ‘draft’) (optional)

Examples

Create a Fact:

from questfoundry.generated.models import Fact

item = Fact(
    statement="example_statement",
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'statement': 'example_statement'}]}, 'title': 'Fact'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

LIFECYCLE: ClassVar[list[str]] = ['draft', 'verified', 'canon']: Valid lifecycle states for this artifact type.

statement: str

category: str | None

source: str | None

confidence: str | None

related_entities: list[str] | None

spoiler_level: str | None

tags: list[str] | None

status: str | None

Parameters:

statement (str)
category (str | None)
source (str | None)
confidence (str | None)
related_entities (list[str] | None)
spoiler_level (str | None)
tags (list[str] | None)
status (str | None)

class questfoundry.generated.models.artifacts.Gate(**data)[source]

Gate.

Store: both

Attributes

keystr: Unique identifier for this gate condition (e.g., ‘has_red_key’, ‘knows_secret’)
gate_typeGateType: Category of condition (token, reputation, knowledge, physical, temporal, composite)
descriptionstr | None: Diegetic explanation shown to player when gate is relevant (optional)
unlock_hintstr | None: Optional hint about how to satisfy this gate (for player or author) (optional)

Examples

Create a Gate:

from questfoundry.generated.models import Gate

item = Gate(
    key="example_key",
    gate_type="token",
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'gate_type': 'token', 'key': 'example_key'}]}}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

key: str

gate_type: GateType

description: str | None

unlock_hint: str | None

Parameters:

key (str)
gate_type (GateType)
description (str | None)
unlock_hint (str | None)

class questfoundry.generated.models.artifacts.GatecheckReport(**data)[source]

Gatecheck Report.

Store: hot Lifecycle: pending → passed → failed → waived

Attributes

target_artifactstr: ID of the artifact being validated
bars_checkedlist[QualityBar]: Quality bars evaluated in this check
statusstr | None: Overall result (defaults to ‘pending’) (optional)
bar_resultsdict[str, str] | None: Per-bar pass/fail status with notes (optional)
issueslist[str] | None: Specific issues found during validation (optional)
recommendationslist[str] | None: Suggested fixes for failed bars (optional)
waiver_reasonstr | None: If waived, why (requires Showrunner approval) (optional)
checked_bystr | None: Role ID that performed the check (optional)

Examples

Create a Gatecheck Report:

from questfoundry.generated.models import GatecheckReport

item = GatecheckReport(
    target_artifact="example_target_artifact",
    bars_checked=["integrity"],
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'bars_checked': ['integrity'], 'target_artifact': 'example_target_artifact'}]}, 'title': 'Gatecheck Report'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

LIFECYCLE: ClassVar[list[str]] = ['pending', 'passed', 'failed', 'waived']: Valid lifecycle states for this artifact type.

target_artifact: str

bars_checked: list[QualityBar]

status: str | None

bar_results: dict[str, str] | None

issues: list[str] | None

recommendations: list[str] | None

waiver_reason: str | None

checked_by: str | None

Parameters:

target_artifact (str)
bars_checked (list[QualityBar])
status (str | None)
bar_results (dict[str, str] | None)
issues (list[str] | None)
recommendations (list[str] | None)
waiver_reason (str | None)
checked_by (str | None)

class questfoundry.generated.models.artifacts.HookCard(**data)[source]

Hook Card.

Store: hot Lifecycle: proposed → accepted → in_progress → resolved → canonized → deferred → rejected

Attributes

titlestr: Short, descriptive title for the hook
hook_typeHookType: The category of change this hook represents
descriptionstr: Detailed explanation of what needs to be done
statusHookStatus | None: Current lifecycle status (defaults to ‘proposed’) (optional)
ownerstr | None: Role ID responsible for this hook (optional)
priorityint | None: Priority level (1=highest, 5=lowest) (optional)
sourcestr | None: Where this hook originated (section ID, user input, etc.) (optional)
target_artifactstr | None: ID of the artifact this hook will modify (optional)
reasonstr | None: Reason for deferral or rejection (required for those states) (optional)
tagslist[str] | None: Optional categorization tags (optional)

Examples

Create a Hook Card:

from questfoundry.generated.models import HookCard

item = HookCard(
    title="example_title",
    hook_type="narrative",
    description="example_description",
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'description': 'example_description', 'hook_type': 'narrative', 'title': 'example_title'}]}, 'title': 'Hook Card'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

LIFECYCLE: ClassVar[list[str]] = ['proposed', 'accepted', 'in_progress', 'resolved', 'canonized', 'deferred', 'rejected']: Valid lifecycle states for this artifact type.

title: str

hook_type: HookType

description: str

status: HookStatus | None

owner: str | None

priority: int | None

source: str | None

target_artifact: str | None

reason: str | None

tags: list[str] | None

Parameters:

title (str)
hook_type (HookType)
description (str)
status (HookStatus | None)
owner (str | None)
priority (int | None)
source (str | None)
target_artifact (str | None)
reason (str | None)
tags (list[str] | None)

class questfoundry.generated.models.artifacts.Item(**data)[source]

Item.

Store: cold Lifecycle: draft → verified → canon

Attributes

namestr: The item’s primary name
descriptionstr: Physical description and properties
item_typestr | None: Category (weapon, artifact, key, consumable, etc.) (optional)
significancestr | None: Narrative importance (quest item, MacGuffin, collectible) (optional)
ownerstr | None: Character ID of current or original owner (optional)
locationstr | None: Location ID where item can be found (optional)
tagslist[str] | None: Categorization tags (magical, mundane, unique, etc.) (optional)
statusstr | None: Current lifecycle status (defaults to ‘draft’) (optional)

Examples

Create a Item:

from questfoundry.generated.models import Item

item = Item(
    name="example_name",
    description="example_description",
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'description': 'example_description', 'name': 'example_name'}]}, 'title': 'Item'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

LIFECYCLE: ClassVar[list[str]] = ['draft', 'verified', 'canon']: Valid lifecycle states for this artifact type.

name: str

description: str

item_type: str | None

significance: str | None

owner: str | None

location: str | None

tags: list[str] | None

status: str | None

Parameters:

name (str)
description (str)
item_type (str | None)
significance (str | None)
owner (str | None)
location (str | None)
tags (list[str] | None)
status (str | None)

class questfoundry.generated.models.artifacts.Location(**data)[source]

Location.

Store: cold Lifecycle: draft → verified → canon

Attributes

namestr: The location’s primary name
descriptionstr: Physical and atmospheric description
regionstr | None: Parent region or area this location belongs to (optional)
location_typestr | None: Category (city, wilderness, dungeon, etc.) (optional)
connected_tolist[str] | None: IDs of adjacent or connected locations (optional)
notable_featureslist[str] | None: Distinctive elements (landmarks, hazards, resources) (optional)
tagslist[str] | None: Categorization tags (safe, dangerous, hub, etc.) (optional)
statusstr | None: Current lifecycle status (defaults to ‘draft’) (optional)

Examples

Create a Location:

from questfoundry.generated.models import Location

item = Location(
    name="example_name",
    description="example_description",
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'description': 'example_description', 'name': 'example_name'}]}, 'title': 'Location'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

LIFECYCLE: ClassVar[list[str]] = ['draft', 'verified', 'canon']: Valid lifecycle states for this artifact type.

name: str

description: str

region: str | None

location_type: str | None

connected_to: list[str] | None

notable_features: list[str] | None

tags: list[str] | None

status: str | None

Parameters:

name (str)
description (str)
region (str | None)
location_type (str | None)
connected_to (list[str] | None)
notable_features (list[str] | None)
tags (list[str] | None)
status (str | None)

class questfoundry.generated.models.artifacts.Relationship(**data)[source]

Relationship.

Store: cold Lifecycle: draft → verified → canon

Attributes

source_entitystr: ID of the first entity in the relationship
target_entitystr: ID of the second entity in the relationship
relationship_typestr: Nature of connection (ally, enemy, family, mentor, etc.)
descriptionstr | None: Details about the relationship (optional)
strengthstr | None: Intensity (strong, moderate, weak, complicated) (optional)
is_mutualbool | None: Whether the relationship is bidirectional (optional)
tagslist[str] | None: Categorization tags (public, secret, evolving, etc.) (optional)
statusstr | None: Current lifecycle status (defaults to ‘draft’) (optional)

Examples

Create a Relationship:

from questfoundry.generated.models import Relationship

item = Relationship(
    source_entity="example_source_entity",
    target_entity="example_target_entity",
    relationship_type="example_relationship_type",
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'relationship_type': 'example_relationship_type', 'source_entity': 'example_source_entity', 'target_entity': 'example_target_entity'}]}, 'title': 'Relationship'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

LIFECYCLE: ClassVar[list[str]] = ['draft', 'verified', 'canon']: Valid lifecycle states for this artifact type.

source_entity: str

target_entity: str

relationship_type: str

description: str | None

strength: str | None

is_mutual: bool | None

tags: list[str] | None

status: str | None

Parameters:

source_entity (str)
target_entity (str)
relationship_type (str)
description (str | None)
strength (str | None)
is_mutual (bool | None)
tags (list[str] | None)
status (str | None)

class questfoundry.generated.models.artifacts.Scene(**data)[source]

Scene.

Store: both Lifecycle: draft → review → final

Attributes

titlestr: Scene title or identifier
section_idstr: Parent section this scene belongs to
contentstr: The scene prose content
statusstr | None: Current lifecycle status (defaults to ‘draft’) (optional)
sequenceint | None: Order within the chapter (optional)
gateslist[Gate] | None: Gate conditions that control access to this scene (optional)
choiceslist[Choice] | None: Available choices/exits from this scene (optional)
canon_refslist[str] | None: Canon entries referenced in this scene (optional)
style_notesstr | None: Voice/register guidance for this scene (optional)
visibilityVisibility | None: Export visibility (defaults to ‘public’). Publisher filters based on this. (optional)

Examples

Create a Scene:

from questfoundry.generated.models import Scene

item = Scene(
    title="example_title",
    section_id="example_section_id",
    content="example_content",
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'content': 'example_content', 'section_id': 'example_section_id', 'title': 'example_title'}]}, 'title': 'Scene'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

LIFECYCLE: ClassVar[list[str]] = ['draft', 'review', 'final']: Valid lifecycle states for this artifact type.

title: str

section_id: str

content: str

status: str | None

sequence: int | None

gates: list[Gate] | None

choices: list[Choice] | None

canon_refs: list[str] | None

style_notes: str | None

visibility: Visibility | None

Parameters:

title (str)
section_id (str)
content (str)
status (str | None)
sequence (int | None)
gates (list[Gate] | None)
choices (list[Choice] | None)
canon_refs (list[str] | None)
style_notes (str | None)
visibility (Visibility | None)

class questfoundry.generated.models.artifacts.Sequence(**data)[source]

Sequence.

Store: hot Lifecycle: draft → review → final

Attributes

titlestr: The sequence’s identifier
scene_idstr: Parent scene this sequence belongs to
orderint: Order within the scene
beatslist[str] | None: IDs of beats in this sequence (optional)
purposestr | None: Narrative function of this sequence (optional)
statusstr | None: Current lifecycle status (defaults to ‘draft’) (optional)

Examples

Create a Sequence:

from questfoundry.generated.models import Sequence

item = Sequence(
    title="example_title",
    scene_id="example_scene_id",
    order=1,
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'order': 1, 'scene_id': 'example_scene_id', 'title': 'example_title'}]}, 'title': 'Sequence'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

LIFECYCLE: ClassVar[list[str]] = ['draft', 'review', 'final']: Valid lifecycle states for this artifact type.

title: str

scene_id: str

order: int

beats: list[str] | None

purpose: str | None

status: str | None

Parameters:

title (str)
scene_id (str)
order (int)
beats (list[str] | None)
purpose (str | None)
status (str | None)

class questfoundry.generated.models.artifacts.Shotlist(**data)[source]

Shotlist.

Store: hot Lifecycle: draft → approved → deferred → completed

Attributes

titlestr: Identifier for this shotlist (e.g., ‘Act I Hub Visuals’)
section_idstr: Section or scene this shotlist covers
shotslist[dict]: List of shot definitions with subject, mood, and purpose
statusstr | None: Current lifecycle status (optional)
art_direction_notesstr | None: Overall visual guidance from Creative Director (optional)
prioritystr | None: Production priority (critical, standard, nice-to-have) (optional)
deferred_reasonstr | None: If deferred, why (e.g., ‘pending budget’, ‘art-only release’) (optional)

Examples

Create a Shotlist:

from questfoundry.generated.models import Shotlist

item = Shotlist(
    title="example_title",
    section_id="example_section_id",
    shots=[],
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'section_id': 'example_section_id', 'shots': [], 'title': 'example_title'}]}, 'title': 'Shotlist'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

LIFECYCLE: ClassVar[list[str]] = ['draft', 'approved', 'deferred', 'completed']: Valid lifecycle states for this artifact type.

title: str

section_id: str

shots: list[dict]

status: str | None

art_direction_notes: str | None

priority: str | None

deferred_reason: str | None

Parameters:

title (str)
section_id (str)
shots (list[dict])
status (str | None)
art_direction_notes (str | None)
priority (str | None)
deferred_reason (str | None)

class questfoundry.generated.models.artifacts.Timeline(**data)[source]

Timeline.

Store: cold Lifecycle: draft → verified → canon

Attributes

namestr: The timeline’s identifier (e.g., ‘Main’, ‘Pre-History’)
descriptionstr | None: What period or scope this timeline covers (optional)
reference_pointstr | None: The T0 or anchor point for relative dates (optional)
eventslist[str] | None: IDs of events in this timeline (optional)
scalestr | None: Time scale (years, decades, centuries, etc.) (optional)
statusstr | None: Current lifecycle status (defaults to ‘draft’) (optional)

Examples

Create a Timeline:

from questfoundry.generated.models import Timeline

item = Timeline(
    name="example_name",
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'name': 'example_name'}]}, 'title': 'Timeline'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

LIFECYCLE: ClassVar[list[str]] = ['draft', 'verified', 'canon']: Valid lifecycle states for this artifact type.

name: str

description: str | None

reference_point: str | None

events: list[str] | None

scale: str | None

status: str | None

Parameters:

name (str)
description (str | None)
reference_point (str | None)
events (list[str] | None)
scale (str | None)
status (str | None)

class questfoundry.generated.models.artifacts.TranslationPack(**data)[source]

Translation Pack.

Store: hot Lifecycle: draft → in_progress → review → complete

Attributes

titlestr: Identifier for this translation pack
source_languagestr: Language code of source content (e.g., ‘en’)
target_languagestr: Language code of translation target (e.g., ‘nl’, ‘de’)
scopelist[str]: Section or artifact IDs included in this pack
statusstr | None: Current lifecycle status (optional)
coverage_percentint | None: Percentage of scope that’s translated (0-100) (optional)
translatorstr | None: Assigned translator or team (optional)
register_notesstr | None: Voice/formality guidance for this language (optional)
glossary_termslist[str] | None: Key terms that must be translated consistently (optional)
blockerslist[str] | None: Issues preventing progress (missing context, ambiguous source) (optional)

Examples

Create a Translation Pack:

from questfoundry.generated.models import TranslationPack

item = TranslationPack(
    title="example_title",
    source_language="example_source_language",
    target_language="example_target_language",
)

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'examples': [{'scope': ['item1', 'item2'], 'source_language': 'example_source_language', 'target_language': 'example_target_language', 'title': 'example_title'}]}, 'title': 'Translation Pack'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

LIFECYCLE: ClassVar[list[str]] = ['draft', 'in_progress', 'review', 'complete']: Valid lifecycle states for this artifact type.

title: str

source_language: str

target_language: str

scope: list[str]

status: str | None

coverage_percent: int | None

translator: str | None

register_notes: str | None

glossary_terms: list[str] | None

blockers: list[str] | None

Parameters:

title (str)
source_language (str)
target_language (str)
scope (list[str])
status (str | None)
coverage_percent (int | None)
translator (str | None)
register_notes (str | None)
glossary_terms (list[str] | None)
blockers (list[str] | None)

Generated enum definitions from domain/ontology/taxonomy.md.

class questfoundry.generated.models.enums.Agency(value)[source]

Role autonomy level - how much discretion the role has

HIGH = 'high': Can deviate, improvise, make judgment calls

MEDIUM = 'medium': Follows patterns but has domain discretion

LOW = 'low': Applies rules mechanically with minimal discretion

ZERO = 'zero': Purely deterministic; crashes on ambiguity

class questfoundry.generated.models.enums.AssetType(value)[source]

Classification of external binary assets

PLATE = 'plate': Illustration for a section

COVER = 'cover': Book cover image

ICON = 'icon': Small graphic (character portrait, item icon)

AUDIO = 'audio': Sound file (ambient, music, SFX)

FONT = 'font': Custom typography file

ORNAMENT = 'ornament': Decorative element (divider, flourish)

class questfoundry.generated.models.enums.GateType(value)[source]

In-world condition type controlling access

TOKEN = 'token': Physical object possession (badge, key, device)

REPUTATION = 'reputation': Social standing, relationships, faction trust

KNOWLEDGE = 'knowledge': Information discovered, secrets learned

PHYSICAL = 'physical': Location access, capability, tool availability

TEMPORAL = 'temporal': Time-based constraints, deadlines, windows

COMPOSITE = 'composite': Multiple conditions (AND/OR combinations)

class questfoundry.generated.models.enums.HookStatus(value)[source]

Lifecycle state of a hook card

PROPOSED = 'proposed': Initial capture - not yet triaged

ACCEPTED = 'accepted': Approved for work - owner and scope defined

IN_PROGRESS = 'in_progress': Active work - owner actively developing

RESOLVED = 'resolved': Work complete - deliverable artifact exists

CANONIZED = 'canonized': Merged to cold store - terminal success state

DEFERRED = 'deferred': Postponed with reason - may be reactivated

REJECTED = 'rejected': Declined with reason - terminal failure state

class questfoundry.generated.models.enums.HookType(value)[source]

The category of change a hook represents

NARRATIVE = 'narrative': Changes to story content, dialogue, or prose

SCENE = 'scene': New or modified scenes within the structure

FACTUAL = 'factual': Canon facts, lore entries, or world truths

TAXONOMY = 'taxonomy': Terminology, naming conventions, or glossary

STRUCTURE = 'structure': Topology changes - hubs, loops, gateways

CANON = 'canon': Backstory, timeline, causality, or constraints

STYLE = 'style': Voice, register, phrasing patterns, or motifs

ACCESSIBILITY = 'accessibility': Alt text, content warnings, or inclusive design

class questfoundry.generated.models.enums.IntentType(value)[source]

Role communication signal type

HANDOFF = 'handoff': Normal completion - transfer to next role

ESCALATION = 'escalation': Exception - bump to higher-agency role

BROADCAST = 'broadcast': Notification - inform without routing change

TERMINATE = 'terminate': Completion signal - end workflow execution

class questfoundry.generated.models.enums.LoopType(value)[source]

Workflow type classification

STORY_SPARK = 'story_spark': Discovery - topology and structure design

HOOK_HARVEST = 'hook_harvest': Discovery - triage and classify change requests

LORE_DEEPENING = 'lore_deepening': Discovery - canon development and consistency

SCENE_CRAFT = 'scene_craft': Refinement - prose writing and scene development

STYLE_PASS = 'style_pass': Refinement - voice, register, and motif tuning

QUALITY_GATE = 'quality_gate': Export - validation and approval checkpoint

BINDING_RUN = 'binding_run': Export - final assembly and publication

class questfoundry.generated.models.enums.QualityBar(value)[source]

Quality validation category

INTEGRITY = 'integrity': Structural consistency - anchors resolve, no orphans

REACHABILITY = 'reachability': Critical content accessible via valid paths

NONLINEARITY = 'nonlinearity': Choices have meaningful consequences

GATEWAYS = 'gateways': All gates have valid unlock conditions

STYLE = 'style': Voice and tone consistency

DETERMINISM = 'determinism': Same inputs produce same outputs

PRESENTATION = 'presentation': Formatting and structure correctness

ACCESSIBILITY = 'accessibility': Content usable by all players

class questfoundry.generated.models.enums.StoreType(value)[source]

Where an artifact lives - determines mutability

HOT = 'hot': Working drafts - mutable, visible to all roles

COLD = 'cold': Committed canon - append-only, immutable once written

BOTH = 'both': May exist in either store depending on lifecycle

class questfoundry.generated.models.enums.Visibility(value)[source]

Export visibility - controls what Publisher includes in player exports

PUBLIC = 'public': Included in player exports - safe for players to see

INTERNAL = 'internal': Author reference only - excluded from player exports

SPOILER = 'spoiler': Contains spoilers - excluded until player reaches unlock point

API Reference

Runtime

State Management

Stores

Compiler

Example Usage

See Also

Parameters

Returns

Examples

Parameters

Returns

Parameters

Returns

Raises

Parameters

Returns

Generated Models

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples

Attributes

Examples