Streaming Improvements: Better Visibility on Edge Traversals and Pre-Execution Events

[Culpable]

While trying to get streaming to work, I came across two large gaps in the streaming functionality: edge traversal visibility and workflow preview capabilities.

Challenges

1. Limited Edge Traversal Visibility:

   • Opaque Transitions: The current implementation shows node-level execution details but lacks visibility into edge traversals across the graph.
   • Conditional Ambiguity: The logic governing node transitions remains obscured, hindering our ability to trace decision paths.

2. No Pre-Execution Event Insights:

   • Post-Execution Focus: While the updates and values stream events provide clear visibility on the node execution path and state, respectively, they only provide data after actions are completed, offering no foresight into upcoming tasks.

Examples

From Adaptive RAG,

From the existing streaming logs:

• Edge Traversal Gap:

  {
    "type": "task",
    "payload": {
      "name": "retrieve",
      "triggers": ["branch:__start__:route_question:retrieve"]
    }
  }

  Here, I can see that retrieve was triggered, and by splitting the triggers up I can ascertain that it was triggered by route_question.

Two issues here:

1. There was no debug event associated with route_question (I'm seeing this after the fact).
2. While I can technically extract route_question from this debug event, it doesn't seem to be made easy. It would be great if we had a dedicated key:value pair to look at, or triggers was more structured (and consistent. I've seen a few variations of in the format, sometimes a single node as the trigger, sometimes in a format akin to the above).

• No Pre-Execution Indicators:

  {
    "type": "task_result",
    "payload": {
      "name": "grade_documents",
      "result": { ... }
    }
  }

This only tells me what happened after grade_documents executed. It would be great to know that grade_documents was about to run beforehand.

Proposed Enhancements

1. Edge Traversal Visibility:

   • Emit events explicitly detailing edge traversals, including:
     • Source and destination nodes (from_node, to_node).
     • Conditional metadata explaining why the traversal occurred.
   • Example:

     {
       "type": "edge_traversal",
       "payload": {
         "from": "route_question",
         "to": "retrieve",
         "condition": "documents_found"
       }
     }

2. Pre-Execution Event Notifications:

   • Introduce events indicating the next node or operation to be executed.
   • Example:

     {
       "type": "pre_execution",
       "payload": {
         "next_node": "grade_documents",
         "expected_inputs": { ... }
       }
     }

3. Streamlined Debugging:

   • Integrate edge traversal and pre-execution data into existing debug streams
   • Provide structured formats that are easy to parse

While LangGraph's streaming capabilities form a solid foundation, these proposed enhancements would significantly improve workflow transparency and control. Real-time edge traversal insights and pre-execution notifications would empower developers with better debugging and optimisation capabilities while maintaining the platform's core strengths.