fabula_narratives/lib.rs
1//! Narrative scoring and thread management for fabula.
2//!
3//! Provides the GM's evaluation toolkit — scoring signals that tell the MCTS
4//! evaluation function whether a candidate action improves the narrative.
5//!
6//! # Research foundation
7//!
8//! - Nelson & Mateas (2005) "Search-Based Drama Management" (AIIDE 2005)
9//! — GM as optimizer with quality function over narrative states. This crate
10//! IS that quality function. The [`scorer`] module implements the composite
11//! evaluation from signals to score.
12//! - Schulz et al. (2024) "Narrative Information Theory" (arXiv:2411.12907)
13//! — Five measures (Complexity, Pivot, Predictability, Suspense, Plot Twist).
14//! [`pivot`] implements the Pivot measure via Jensen-Shannon Divergence.
15//! - Booth (2009) "The AI Director: Left 4 Dead's Approach to Procedural
16//! Intensity" — Pacing via trajectory sampling. [`tension`] classifies
17//! numeric trajectories (Rising/Falling/Plateau/Peak/Valley).
18//! - Ely, Frankel, Kamenica (2015) "Suspense and Surprise" — Trajectory
19//! matters more than absolute value; informs tension scoring.
20//! - Kowal, Mary Robinette. MICE Quotient (Writing Excuses) — Narrative
21//! threads open and close; well-formed stories close in reverse order
22//! (FILO). [`thread`] validates this nesting property.
23//!
24//! # Modules
25//!
26//! - [`thread`] — Thread lifecycle management (MICE-style open/close tracking, FILO validation)
27//! - [`tension`] — Numeric trajectory sampling (is tension rising/falling/plateaued?)
28//! - [`pivot`] — Event distribution shift detection (Schulz 2024 JSD pivot measure)
29//! - [`scorer`] — Composite narrative quality score for MCTS evaluation
30//!
31//! # Design principles
32//!
33//! 1. **Scoring, not patterns.** The GM needs scoring signals, not more patterns.
34//! The engine finds matches; this crate evaluates narrative quality.
35//! 2. **DataSource-agnostic where possible.** `ThreadTracker` and `PivotDetector`
36//! work on engine output (TickDelta, SiftEvent). `TensionTracker` accepts
37//! caller-provided samples, not DataSource queries.
38//! 3. **Research-backed.** Each module cites its academic foundation.
39
40pub mod pivot;
41pub mod scorer;
42pub mod tension;
43pub mod thread;