iil-outlinefw

Story Outline Framework for AI-assisted creative writing.

Pure Python — no Django, no DB dependency in the core.

Part of the iil- platform package family alongside iil-aifw, iil-authoringfw, iil-promptfw.

Install

pip install iil-outlinefw
# With Outline Wiki knowledge enrichment:
pip install "iil-outlinefw[knowledge]"
# With Django adapter:
pip install "iil-outlinefw[django]"
# Everything:
pip install "iil-outlinefw[full]"

Extras / Optional Dependencies

Features

• 5 story frameworks: Three-Act, Save the Cat, Hero's Journey, Five-Act, Dan Harmon Story Circle
• Beat definitions with act position (0.0–1.0), tension level, emotional arc
• OutlineGenerator: LLM-based outline generation via any iil-aifw-compatible router
• parse_nodes(): Robust JSON parser for LLM responses (handles fencing, <think> tags, leading text)
• Pydantic schemas: OutlineNode, OutlineResult, ProjectContext
• Django adapter in outlinefw.django_adapter (optional, no hard dependency)

Quick Start

from outlinefw import OutlineGenerator, FRAMEWORKS
from outlinefw.schemas import ProjectContext

gen = OutlineGenerator(my_llm_router)

ctx = ProjectContext(
    title="My Novel",
    genre="Thriller",
    description="A story about ...",
)

# generate(framework_key, context) — always returns an OutlineResult, never raises
result = gen.generate("save_the_cat", ctx)
for node in result.nodes:
    print(f"{node.position:.2f} {node.title} [{node.beat_name}]")

Frameworks

Architecture

src/outlinefw/
    __init__.py        # Public API
    schemas.py         # Pydantic: OutlineNode, OutlineResult, ProjectContext
    frameworks.py      # FRAMEWORKS dict + BeatDefinition TypedDicts
    generator.py       # OutlineGenerator (LLMRouter Protocol)
    parser.py          # parse_nodes() -- robust LLM JSON parser
    django_adapter.py  # Optional Django bridge (override in host app)

Used By

• writing-hub — outline generation + standalone Outlines section
• travel-beat — scene-based story planning (migration planned)
• bfagent — advanced outline handlers (migration planned)

Part of the iil- Platform

Changelog

See CHANGELOG.md.