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.