How AI Generation Works

Writan uses Claude (Anthropic’s API) for AI-assisted prose generation. The generation system exists but is not yet fully connected — the API endpoint works, the context composition logic exists, but they are not yet wired together or surfaced in the UI.

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
Formatted output — structured text ordered from Book → Beat

⚠️

This context composition system is not yet connected to the generation API endpoint. The API accepts a raw context string, but nothing in the UI calls getInheritedContext() to build it.

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
Format for prompt via formatContextForPrompt() — structures ancestor 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 (schema exists, not yet written to)

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