How AI Generation Works

Writan uses Claude (Anthropic’s API) for AI-assisted prose generation. The generation system has a working API endpoint and a context composition system that walks the node tree to build prompts.

What Exists Today

Generation API (`app/api/generate/route.ts`)

A Next.js API route that accepts beat notes and story context, sends them to Claude Sonnet, and returns generated prose.

Input:

{
  context: string,     // story context (currently passed manually)
  beatNotes: string,   // what this beat should achieve
  existingProse?: string  // for revision/rewriting
}

Prompt structure: The system prompt embeds craft principles directly — active voice, simple vocabulary, “said” for dialogue tags, sentence length variation, concrete nouns. These are hardcoded, not sourced from the rules engine.

Output: Raw prose (1-4 paragraphs), plus a prompt summary and token usage.

Context Composition (`lib/context/inheritedContext.ts`)

A module that walks the node tree from a target node up to the root, collecting:

Ancestor data blocks — characters (name, role, motivation, secret, fear), locations (name, atmosphere), freeform blocks
Beat notes — from each level
Sibling context — prior beats’ notes and prose for narrative continuity, with configurable depth and cross-scene bridging
Formatted output — structured text ordered from Book → Beat

See What Data Feeds Into Generation for the full data flow.

Submission Log

All Claude API requests are logged in-session via submissionLogStore. A floating log button (bottom-left) opens a modal showing every request with status, type, node, timestamp, full request/response, model, token usage, and duration. This is session-scoped (in-memory only) for debugging.

Planned Pipeline

When fully connected, generating prose for a beat will:

Collect beat notes from the target node
Composite parent context via getInheritedContext() — walks up the tree gathering scene, chapter, act, and book data
Collect sibling context via getSiblingContext() — preceding beats for continuity
Format for prompt via formatContextForPrompt() — structures all data into readable sections
Apply writing rules — select relevant rules from the active ruleset (not yet implemented)
Send to Claude — via the generation API
Log the interaction — record prompt, rules, and previous prose in generation.aiPrompts

Mechanical Analysis (Implemented)

The mechanical tier is fully implemented and runs client-side:

27 rule detectors in lib/rules/detectors/
Analyses prose on save, creates orange craft pips for violations
No AI usage — pure NLP/heuristic detection

See The Writing Rules Engine for details.

Craft Analysis (Planned)

The craft tier (Claude-powered analysis for show vs. tell, pacing, character development) is not yet implemented.

Overview What Data Feeds Into Generation