Package Exports

ava-langgraph-narrative-intelligence
ava-langgraph-narrative-intelligence/graphs
ava-langgraph-narrative-intelligence/integrations
ava-langgraph-narrative-intelligence/nodes
ava-langgraph-narrative-intelligence/schemas

Readme

ava-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

npm install ava-langgraph-narrative-intelligence
# or
yarn add ava-langgraph-narrative-intelligence

Optional Dependencies

# 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:

import { ThreeUniverseProcessor } from "ava-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:

import {
  NarrativeCoherenceEngine,
  createStoryBeat,
  NarrativeFunction,
} from "ava-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:

import {
  createUnifiedNarrativeState,
  addBeat,
  createStoryBeat,
  NarrativeFunction,
} from "ava-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:

import { NarrativeRedisManager, createRedisConfig } from "ava-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:

Narrative Flow - Smooth transitions, logical causality
Character Consistency - Voice consistency, arc progression
Pacing - Tension/relief distribution, climax positioning
Theme Saturation - Theme presence and payoff
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:

import { LangGraphBridge } from "@langchain/langchain-narrative-tracing";
import { ThreeUniverseProcessor } from "ava-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

// Main exports
export {
  // Processing
  ThreeUniverseProcessor,
  NarrativeCoherenceEngine,
  EmotionalBeatClassifierNode,
  
  // State
  UnifiedNarrativeState,
  createUnifiedNarrativeState,
  
  // Types
  Universe,
  NarrativeFunction,
  NarrativePhase,
  GapType,
  GapSeverity,
  EmotionalTone,
  
  // Redis
  NarrativeRedisManager,
  MockRedis,
} from "ava-langgraph-narrative-intelligence";

// Subpath exports
import * as schemas from "ava-langgraph-narrative-intelligence/schemas";
import * as graphs from "ava-langgraph-narrative-intelligence/graphs";
import * as nodes from "ava-langgraph-narrative-intelligence/nodes";
import * as integrations from "ava-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