Instructions for LangChain Narrative-Tracing Instance#

Current Context#

You've completed the core narrative-tracing library with 22 tests. The library is designed to instrument the three-project ecosystem (LangChain observability, LangGraph intelligence, Miadi event consumption) for tracing narrative intelligence.

Your mission: Create bridge adapters that wire narrative-tracing to the three systems it's designed to observe, proving ecosystem coherence through observable traces.

What You Need to Know (Without Accessing Patent Folder)#

The narrative intelligence system is built on:

Autonomous Detection: File watcher detects new artifacts via pattern matching
Three-Universe Analysis: Events analyzed through Engineer, Ceremony, Story perspectives
Hierarchical Traces: Root traces contain semantic SPANs containing EVENT observations
Narrative Beats: Creative work documented as story beats with lessons
Cross-Session Coordination: Parallel instances discover each other's work automatically

Your implementation proves these work at the system level by showing traces capture the ecosystem's distributed coordination.

Phase 1: LangGraph Bridge Adapter (CRITICAL - START HERE)#

Objective#

Wire the LangGraph ThreeUniverseProcessor to narrative-tracing, so every three-universe analysis automatically logs to Langfuse.

Steps#

1. Explore LangGraph (1 day)

```bash cd /workspace/langgraph find . -name "*.py" -type f | grep -i "universe|processor|analysis" | head -10 ```

Look for:

ThreeUniverseProcessor or similar class
Input: narrative event or artifact
Output: lead universe + coherence score
Look for callback hooks or decorator points

2. Create Bridge (2 days)

Create file: /workspace/langchain/libs/narrative-tracing/adapters/langgraph_bridge.py

```python from narrative_tracing import NarrativeTracingHandler from typing import Any, Dict, Optional

class LangGraphBridge: """Wire LangGraph three-universe processing to narrative tracing."""

def __init__(self, handler: NarrativeTracingHandler):
    self.handler = handler

def create_three_universe_callback(self):
    """
    Return callback function for LangGraph to inject trace logging.
    
    Hook this into LangGraph's ThreeUniverseProcessor output.
    """
    def log_universe_analysis(
        event_id: str,
        event_content: str,
        engineer_result: Dict[str, Any],
        ceremony_result: Dict[str, Any],
        story_engine_result: Dict[str, Any],
        lead_universe: str,
        coherence_score: float
    ):
        """Called after three-universe analysis completes."""
        self.handler.log_three_universe_analysis(
            event_id=event_id,
            engineer_intent=engineer_result.get("intent"),
            engineer_confidence=engineer_result.get("confidence", 0.0),
            ceremony_intent=ceremony_result.get("intent"),
            ceremony_confidence=ceremony_result.get("confidence", 0.0),
            story_engine_intent=story_engine_result.get("intent"),
            story_engine_confidence=story_engine_result.get("confidence", 0.0),
            lead_universe=lead_universe,
            coherence_score=coherence_score
        )
    return log_universe_analysis

```

3. Write Tests (1 day)

Create: /workspace/langchain/libs/narrative-tracing/tests/test_langgraph_bridge.py

Tests needed:

test_bridge_instantiation - Can create bridge with handler
test_callback_receives_universe_data - Callback accepts all parameters
test_callback_logs_to_handler - Calls handler.log_three_universe_analysis
test_coherence_score_range - Validates 0-1 range
test_lead_universe_values - Validates engineer|ceremony|story_engine

Phase 2: Miadi Integration Adapter (CRITICAL - SECOND)#

Objective#

Enable narrative-tracing to inject trace correlation headers into HTTP calls to Miadi, so traces flow across system boundaries.

Steps#

1. Explore Miadi (1 day)

```bash cd /src/Miadi/miadi-code find . -name "*.py" -type f | grep -i "webhook|event|handler" | head -10 ```

Look for:

How Miadi receives webhook events
Where HTTP calls are made (to Flowise, LangFlow, etc.)
How events are structured
Authentication/header injection points

2. Create Integration (1 day)

Create: /workspace/langchain/libs/narrative-tracing/adapters/miadi_integration.py

```python from narrative_tracing import NarrativeTraceOrchestrator from typing import Dict, Any, Optional

class MiadiIntegration: """Wire Miadi webhook events to narrative tracing."""

def __init__(self, orchestrator: NarrativeTraceOrchestrator):
    self.orchestrator = orchestrator
    self.correlation_header = "X-Langfuse-Trace-Id"

def inject_trace_headers(
    self, 
    headers: Dict[str, str], 
    root_trace_id: str
) -> Dict[str, str]:
    """
    Add Langfuse correlation headers for outgoing HTTP calls.
    
    Call this before making HTTP requests to downstream systems.
    """
    headers[self.correlation_header] = root_trace_id
    return headers

def log_webhook_event(
    self,
    event_id: str,
    event_type: str,
    source: str,
    payload: Dict[str, Any],
    root_trace_id: str
):
    """
    Log Miadi webhook consumption as narrative event.
    
    Call this when Miadi receives webhook events.
    """
    # Create span in trace
    span = self.orchestrator.create_agent_flow_span(
        flow_id=f"miadi_{event_type}",
        flow_name=f"Miadi: {event_type}",
        root_trace=root_trace_id,
        input_data=payload
    )
    return span

```

3. Write Tests (1 day)

Create: /workspace/langchain/libs/narrative-tracing/tests/test_miadi_integration.py

Tests needed:

test_integration_instantiation
test_header_injection - Adds correlation header
test_webhook_event_logging - Creates span from event
test_trace_correlation_across_boundaries - Header value matches trace ID
test_multiple_events_same_trace - All events under one root trace

Phase 3: Storytelling System Integration (SECONDARY)#

Objective#

Hook into beat generation lifecycle, so narrative beats automatically appear in traces with lessons extracted.

Steps#

1. Explore Storytelling (1 day)

```bash cd /src/storytelling find . -name "*.py" -type f | grep -i "beat|generate|story" | head -10 ```

Look for:

Beat generation function
Where narrative function is assigned (inciting_incident, turning_point, etc.)
Where lessons might be extracted
Lifecycle hooks (pre/post beat creation)

2. Create Hooks (2 days)

Create: /workspace/langchain/libs/narrative-tracing/adapters/storytelling_hooks.py

```python from narrative_tracing import NarrativeTracingHandler from typing import Any, Dict, List

class StorytellingHooks: """Hook into storytelling beat lifecycle for tracing."""

def __init__(self, handler: NarrativeTracingHandler):
    self.handler = handler

def on_beat_created(
    self,
    beat_id: str,
    beat_content: str,
    narrative_function: str,
    act_number: int,
    sequence: int
):
    """Called when storytelling system creates a beat."""
    self.handler.log_beat_creation(
        beat_id=beat_id,
        content=beat_content,
        narrative_function=narrative_function,
        sequence=sequence,
        emotional_tone=self._extract_tone(beat_content)
    )

def on_beat_enriched(
    self,
    beat_id: str,
    enriched_content: str,
    improvements: List[str]
):
    """Called when beat is enriched/improved."""
    self.handler.log_beat_enrichment(
        beat_id=beat_id,
        enriched_content=enriched_content,
        improvements=improvements
    )

def on_lessons_extracted(
    self,
    beat_id: str,
    lessons: List[str]
):
    """Called when lessons are extracted from beat."""
    # Store lessons in metadata for later analysis
    return {"lessons": lessons, "beat_id": beat_id}

def _extract_tone(self, content: str) -> str:
    """Simple emotional tone extraction."""
    # Implement actual tone detection or use heuristics
    return "neutral"

```

What Success Looks Like#

After LangGraph Bridge (2-3 days)#

✅ Bridge adapter created
✅ Tests pass
✅ Can hook LangGraph ThreeUniverseProcessor to trace logging
✅ Three-universe analyses appear in Langfuse with lead universe + coherence

After Miadi Integration (3-4 days total)#

✅ Miadi integration created
✅ Tests pass
✅ HTTP headers include correlation IDs
✅ Webhook events appear in traces as spans
✅ Traces flow across system boundaries

After Storytelling Integration (5-6 days total)#

✅ Storytelling hooks created
✅ Tests pass
✅ Beat creation lifecycle logged
✅ Lessons appear in trace metadata
✅ Acts and narrative functions tracked

Final Proof (6-7 days)#

Create simple test that demonstrates end-to-end: ``` File Detection → LangChain Reads → LangGraph Analyzes (3-universe) → Narrative-Tracing Logs → Langfuse Shows Complete Trace ```

Code Quality Standards#

✅ Type hints on all functions
✅ Google-style docstrings
✅ 100% test coverage for new code
✅ No breaking changes to NarrativeTracingHandler API
✅ All tests in tests/ directory with test_ prefix

Resources Available#

/workspace/langgraph - ThreeUniverseProcessor implementation
/src/Miadi/miadi-code - Webhook event handling
/src/storytelling - Beat generation system
/workspace/langchain/libs/narrative-tracing/README.md - Your library API

How to Submit When Done#

Update README.md in /workspace/langchain/libs/narrative-tracing/ with:

Integration examples for each adapter
Instructions for wiring to LangGraph, Miadi, and Storytelling
Expected trace structure after integration

Create example file: /workspace/langchain/examples/three_system_integration_example.py showing how all three adapters work together.

Success Criteria: Traces demonstrating that LangChain, LangGraph, and Miadi automatically coordinate without shared state, discovering pre-existing architectural coherence through observation.