ava-langgraph-narrative-intelligence 0.1.0

package/README.md

@@ -0,0 +1,268 @@
+# @langchain/langgraph-narrative-intelligence
+
+Narrative Intelligence Toolkit for JavaScript/TypeScript - a complete port of the Python `narrative-intelligence` package.
+
+## Overview
+
+This package provides the core narrative intelligence components for the LangGraph ecosystem:
+
+- **Three-Universe Processing** - Analyze events through Engineer (Mia), Ceremony (Ava8), and Story Engine (Miette) perspectives
+- **Narrative Coherence Analysis** - Score narrative quality across 5 dimensions with actionable gap identification
+- **Story Beat Classification** - Emotional tone detection using rule-based and LLM classification
+- **State Management** - Redis-backed persistence for cross-system state sharing
+
+## Installation
+
+```bash
+npm install @langchain/langgraph-narrative-intelligence
+# or
+yarn add @langchain/langgraph-narrative-intelligence
+```
+
+### Optional Dependencies
+
+```bash
+# For LangGraph integration
+npm install @langchain/langgraph
+
+# For Redis persistence
+npm install ioredis
+```
+
+## Quick Start
+
+### Three-Universe Processing
+
+Process any event through three interpretive lenses:
+
+```typescript
+import { ThreeUniverseProcessor } from "@langchain/langgraph-narrative-intelligence";
+
+const processor = new ThreeUniverseProcessor();
+
+// Process a GitHub event
+const analysis = processor.process(
+  { content: "feat: implement new feature together with team" },
+  "github.push"
+);
+
+console.log(`Lead universe: ${analysis.leadUniverse}`); // "ceremony" (collaborative work)
+console.log(`Coherence: ${analysis.coherenceScore}`); // 0.75
+
+// Access individual perspectives
+console.log(analysis.engineer.intent); // "feature_implementation"
+console.log(analysis.ceremony.intent); // "co_creation"
+console.log(analysis.storyEngine.intent); // "rising_action"
+```
+
+### Narrative Coherence Analysis
+
+Analyze the quality of story beats:
+
+```typescript
+import {
+  NarrativeCoherenceEngine,
+  createStoryBeat,
+  NarrativeFunction,
+} from "@langchain/langgraph-narrative-intelligence";
+
+const engine = new NarrativeCoherenceEngine();
+
+const beats = [
+  createStoryBeat("beat_1", 1, "Setup", NarrativeFunction.INCITING_INCIDENT, 1),
+  createStoryBeat("beat_2", 2, "Rising action", NarrativeFunction.RISING_ACTION, 2),
+  createStoryBeat("beat_3", 3, "Climax", NarrativeFunction.CLIMAX, 3),
+  createStoryBeat("beat_4", 4, "Resolution", NarrativeFunction.RESOLUTION, 3),
+];
+
+const result = engine.analyze(beats);
+
+// Overall coherence score
+console.log(`Overall: ${result.coherenceScore.overall}%`);
+
+// Component scores
+console.log(`Narrative Flow: ${result.coherenceScore.narrativeFlow.score}%`);
+console.log(`Pacing: ${result.coherenceScore.pacing.score}%`);
+
+// Identified gaps
+for (const gap of result.gaps) {
+  console.log(`Gap: ${gap.description} (${gap.severity})`);
+  console.log(`Route to: ${gap.suggestedRoute}`);
+}
+
+// Trinity assessment (Mia/Miette/Ava8)
+console.log(`Mia (structure): ${result.trinityAssessment.mia}`);
+console.log(`Miette (emotion): ${result.trinityAssessment.miette}`);
+console.log(`Ava8 (atmosphere): ${result.trinityAssessment.ava8}`);
+```
+
+### Unified Narrative State
+
+Create and manage narrative state across systems:
+
+```typescript
+import {
+  createUnifiedNarrativeState,
+  addBeat,
+  createStoryBeat,
+  NarrativeFunction,
+} from "@langchain/langgraph-narrative-intelligence";
+
+// Create a new state with default characters (Mia, Ava8, Miette)
+const state = createUnifiedNarrativeState("story_123", "session_456");
+
+// Add a beat
+const beat = createStoryBeat(
+  "beat_1",
+  1,
+  "The hero begins their journey",
+  NarrativeFunction.INCITING_INCIDENT,
+  1,
+  {
+    emotionalTone: "hopeful",
+    thematicTags: ["journey", "transformation"],
+  }
+);
+
+addBeat(state, beat);
+
+console.log(`Act: ${state.position.act}`);
+console.log(`Beat count: ${state.position.beatCount}`);
+console.log(`Lead universe: ${state.position.leadUniverse}`);
+```
+
+### Redis Persistence
+
+Use Redis for cross-system state sharing:
+
+```typescript
+import { NarrativeRedisManager, createRedisConfig } from "@langchain/langgraph-narrative-intelligence";
+
+const manager = new NarrativeRedisManager(createRedisConfig({
+  url: "redis://localhost:6379",
+}));
+
+await manager.connect();
+
+// Get or create state
+const state = await manager.getOrCreateState("story_123", "session_456");
+
+// Add beats
+await manager.addBeatToSession("session_456", beat);
+
+// Cache analysis
+await manager.cacheEventAnalysis("event_123", analysis);
+
+await manager.disconnect();
+```
+
+## The Three Universes
+
+The three-universe model from `multiverse_3act`:
+
+| Universe | Character | Focus | Keywords |
+|----------|-----------|-------|----------|
+| **ENGINEER** | Mia (The Builder) | Technical precision | feat:, fix:, refactor |
+| **CEREMONY** | Ava8 (The Keeper) | Relational protocols | together, thanks, collaborate |
+| **STORY_ENGINE** | Miette (The Weaver) | Narrative patterns | begin, climax, resolution |
+
+## Coherence Dimensions
+
+The coherence engine analyzes 5 dimensions:
+
+1. **Narrative Flow** - Smooth transitions, logical causality
+2. **Character Consistency** - Voice consistency, arc progression
+3. **Pacing** - Tension/relief distribution, climax positioning
+4. **Theme Saturation** - Theme presence and payoff
+5. **Continuity** - Timeline consistency, sequence ordering
+
+## Gap Types
+
+Identified gaps are categorized and routed:
+
+| Gap Type | Route To | Description |
+|----------|----------|-------------|
+| STRUCTURAL | Structurist | Missing beats, incomplete arcs |
+| THEMATIC | Structurist | Underdeveloped themes |
+| CHARACTER | Storyteller | Inconsistent character voice |
+| SENSORY | Storyteller | Lacking grounding detail |
+| CONTINUITY | Author | Timeline inconsistencies |
+
+## Emotional Tones
+
+The emotional classifier recognizes these tones:
+
+- Devastating, Hopeful, Tense, Joyful
+- Melancholic, Triumphant, Fearful, Peaceful
+- Conflicted, Resigned
+
+## Integration with narrative-tracing
+
+Connect to the `@langchain/langchain-narrative-tracing` package:
+
+```typescript
+import { LangGraphBridge } from "@langchain/langchain-narrative-tracing";
+import { ThreeUniverseProcessor } from "@langchain/langgraph-narrative-intelligence";
+
+const bridge = new LangGraphBridge(handler);
+
+const processor = new ThreeUniverseProcessor({
+  tracingCallback: bridge.createThreeUniverseCallback(),
+});
+
+// All analyses now get traced to Langfuse
+const analysis = processor.process(event, "github.push");
+```
+
+## API Reference
+
+### Exports
+
+```typescript
+// Main exports
+export {
+  // Processing
+  ThreeUniverseProcessor,
+  NarrativeCoherenceEngine,
+  EmotionalBeatClassifierNode,
+  
+  // State
+  UnifiedNarrativeState,
+  createUnifiedNarrativeState,
+  
+  // Types
+  Universe,
+  NarrativeFunction,
+  NarrativePhase,
+  GapType,
+  GapSeverity,
+  EmotionalTone,
+  
+  // Redis
+  NarrativeRedisManager,
+  MockRedis,
+} from "@langchain/langgraph-narrative-intelligence";
+
+// Subpath exports
+import * as schemas from "@langchain/langgraph-narrative-intelligence/schemas";
+import * as graphs from "@langchain/langgraph-narrative-intelligence/graphs";
+import * as nodes from "@langchain/langgraph-narrative-intelligence/nodes";
+import * as integrations from "@langchain/langgraph-narrative-intelligence/integrations";
+```
+
+## Python Parity
+
+This package is a complete TypeScript port of the Python `narrative-intelligence` package, maintaining full feature parity:
+
+| Python Module | TypeScript Module |
+|---------------|-------------------|
+| `narrative_intelligence/schemas/unified_state_bridge.py` | `schemas/unified_state_bridge.ts` |
+| `narrative_intelligence/schemas/ncp.py` | `schemas/ncp.ts` |
+| `narrative_intelligence/graphs/three_universe_processor.py` | `graphs/three_universe_processor.ts` |
+| `narrative_intelligence/graphs/coherence_engine.py` | `graphs/coherence_engine.ts` |
+| `narrative_intelligence/nodes/emotional_classifier.py` | `nodes/emotional_classifier.ts` |
+| `narrative_intelligence/integrations/redis_state.py` | `integrations/redis_state.ts` |
+
+## License
+
+MIT