core[minor]: Add parent_ids to astream_events API (#22563)

Include a list of parent ids for each event in astream events.

Author: eyurtsev

libs/core/langchain_core/runnables/base.py

@@ -959,6 +959,11 @@ async def astream_events(
             the runnable that emitted the event.
             A child runnable that gets invoked as part of the execution of a
             parent runnable is assigned its own unique ID.
+        - ``parent_ids``: **List[str]** - The IDs of the parent runnables that
+            generated the event. The root runnable will have an empty list.
+            The order of the parent IDs is from the root to the immediate parent.
+            Only available for v2 version of the API. The v1 version of the API
+            will return an empty list.
         - ``tags``: **Optional[List[str]]** - The tags of the runnable that generated
             the event.
         - ``metadata``: **Optional[Dict[str, Any]]** - The metadata of the runnable
@@ -1051,7 +1056,8 @@ async def reverse(s: str) -> str:
                 event async for event in chain.astream_events("hello", version="v2")
             ]
 
-            # will produce the following events (run_id has been omitted for brevity):
+            # will produce the following events (run_id, and parent_ids
+            # has been omitted for brevity):
             [
                 {
                     "data": {"input": "hello"},

libs/core/langchain_core/runnables/schema.py

@@ -1,7 +1,7 @@
 """Module contains typedefs that are used with runnables."""
 from __future__ import annotations
 
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Sequence
 
 from typing_extensions import NotRequired, TypedDict
 
@@ -54,7 +54,8 @@ async def reverse(s: str) -> str:
 
             events = [event async for event in chain.astream_events("hello")]
 
-            # will produce the following events (run_id has been omitted for brevity):
+            # will produce the following events
+            # (where some fields have been omitted for brevity):
             [
                 {
                     "data": {"input": "hello"},
@@ -131,3 +132,16 @@ async def reverse(s: str) -> str:
 
     The contents of the event data depend on the event type.
     """
+
+    parent_ids: Sequence[str]
+    """A list of the parent IDs associated with this event.
+
+    Root Events will have an empty list.
+
+    For example, if a Runnable A calls Runnable B, then the event generated by Runnable 
+    B will have Runnable A's ID in the parent_ids field.
+
+    The order of the parent IDs is from the root parent to the immediate parent.
+    
+    Only supported as of v2 of the astream events API. v1 will return an empty list.
+    """