Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

12.5 KB
Raw Blame
from typing import Generic, cast, get_args

import structlog
from langchain_core.messages import AIMessageChunk

from posthog.schema import (
    ArtifactMessage,
    AssistantGenerationStatusEvent,
    AssistantGenerationStatusType,
    AssistantToolCall,
    AssistantUpdateEvent,
    FailureMessage,
    SubagentUpdateEvent,
)

from posthog.models import Team, User

from ee.hogai.artifacts.manager import ArtifactManager
from ee.hogai.chat_agent.notebook_streaming import NotebookStreamingMixin
from ee.hogai.core.stream_processor import AssistantStreamProcessorProtocol
from ee.hogai.utils.helpers import normalize_ai_message, should_output_assistant_message
from ee.hogai.utils.state import is_message_update, is_state_update, merge_message_chunk
from ee.hogai.utils.types.base import (
    ArtifactRefMessage,
    AssistantDispatcherEvent,
    AssistantGraphName,
    AssistantResultUnion,
    AssistantStreamedMessageUnion,
    BaseStateWithMessages,
    LangGraphUpdateEvent,
    MessageAction,
    MessageChunkAction,
    NodeEndAction,
    NodePath,
    NodeStartAction,
    StateType,
    UpdateAction,
)
from ee.hogai.utils.types.composed import MaxNodeName

logger = structlog.get_logger(__name__)


def find_subgraph(node_path: tuple[NodePath, ...]) -> bool:
    return bool(next((path for path in node_path if path.name in AssistantGraphName), None))


MESSAGE_TYPE_TUPLE = get_args(AssistantStreamedMessageUnion)


class BaseStreamProcessor(AssistantStreamProcessorProtocol, Generic[StateType]):
    """
    Base stream processor that reduces streamed actions to client-facing messages.
    """

    _verbose_nodes: set[MaxNodeName]
    """Nodes that emit messages."""
    _streaming_nodes: set[MaxNodeName]
    """Nodes that produce streaming messages."""
    _chunks: dict[str, AIMessageChunk]
    """Tracks the current message chunk."""
    _state: StateType | None
    """Tracks the current state."""
    _state_type: type[StateType]
    """The type of the state."""

    def __init__(
        self,
        team: Team,
        user: User,
        verbose_nodes: set[MaxNodeName],
        streaming_nodes: set[MaxNodeName],
        state_type: type[StateType],
    ):
        """
        Initialize the stream processor with node configuration.

        Args:
            team: The team
            user: The user
            verbose_nodes: Nodes that produce messages
            streaming_nodes: Nodes that produce streaming messages
            state_type: The type of the state
        """
        self._team = team
        self._user = user
        # If a node is streaming node, it should also be verbose.
        self._verbose_nodes = verbose_nodes | streaming_nodes
        self._streaming_nodes = streaming_nodes
        self._streamed_update_ids: set[str] = set()
        self._chunks = {}
        self._state_type = state_type
        self._state = None
        self._artifact_manager = ArtifactManager(self._team, self._user)

    async def process(self, event: AssistantDispatcherEvent) -> list[AssistantResultUnion] | None:
        """
        Reduce streamed actions to client messages.

        This is the main entry point for processing actions from nodes. It delegates
        to specialized handlers based on action type and message characteristics.
        """
        action = event.action

        if isinstance(action, NodeStartAction):
            self._chunks[event.node_run_id] = AIMessageChunk(content="")
            return [AssistantGenerationStatusEvent(type=AssistantGenerationStatusType.ACK)]

        if isinstance(action, NodeEndAction):
            if event.node_run_id in self._chunks:
                del self._chunks[event.node_run_id]
            return await self._handle_node_end(event, action)

        if isinstance(action, MessageChunkAction) and (results := self._handle_message_stream(event, action.message)):
            return results

        if isinstance(action, MessageAction):
            message = action.message
            if result := await self._handle_message(event, message):
                return [result]

        if isinstance(action, UpdateAction) and (update_event := self._handle_update_message(event, action)):
            return [update_event]

        return None

    async def process_langgraph_update(self, event: LangGraphUpdateEvent) -> list[AssistantResultUnion] | None:
        """
        Process a LangGraph update event.
        """
        if is_message_update(event.update):
            # Convert the message chunk update to a dispatcher event to prepare for a bright future without LangGraph
            maybe_message_chunk, state = event.update[1]
            if not isinstance(maybe_message_chunk, AIMessageChunk):
                return None
            action = AssistantDispatcherEvent(
                action=MessageChunkAction(message=maybe_message_chunk),
                node_name=state["langgraph_node"],
                node_run_id=state["langgraph_checkpoint_ns"],
            )
            return await self.process(action)

        if is_state_update(event.update):
            new_state = self._state_type.model_validate(event.update[1])
            self._state = new_state

        return None

    async def _handle_message(
        self, action: AssistantDispatcherEvent, message: AssistantStreamedMessageUnion
    ) -> AssistantStreamedMessageUnion | None:
        """Handle a message from a node."""
        node_name = cast(MaxNodeName, action.node_name)
        produced_message: AssistantStreamedMessageUnion | None = None

        # ArtifactRefMessage must always be enriched with content, regardless of nesting level
        if isinstance(message, ArtifactRefMessage):
            try:
                enriched_message = await self._artifact_manager.aenrich_message(message)
            except (ValueError, KeyError) as e:
                logger.warning("Failed to enrich ArtifactMessage", error=str(e), artifact_id=message.artifact_id)
                enriched_message = None
            # If the message is not enriched, return None.
            if not enriched_message:
                return None
            message = enriched_message

        # Output all messages from the top-level graph.
        if not self._is_message_from_nested_node_or_graph(action.node_path or ()):
            produced_message = self._handle_root_message(message, node_name)
        # Other message types with parents (viz, notebook, failure, tool call)
        else:
            produced_message = self._handle_special_child_message(message)

        # Messages with existing IDs must be deduplicated.
        # Messages WITHOUT IDs must be streamed because they're progressive.
        if produced_message is not None and isinstance(produced_message, MESSAGE_TYPE_TUPLE):
            message_id = getattr(produced_message, "id", None)
            if not self._should_emit_message(message_id):
                return None

        return produced_message

    def _should_emit_message(self, message_id: str | None) -> bool:
        """
        Check if message should be emitted (not already streamed) and mark as streamed.

        Messages without IDs are always emitted (they're progressive streaming messages).
        Messages with IDs are deduplicated to avoid sending the same message twice.
        """
        if message_id is None:
            return True
        if message_id in self._streamed_update_ids:
            return False
        self._streamed_update_ids.add(message_id)
        return True

    def _is_message_from_nested_node_or_graph(self, node_path: tuple[NodePath, ...]) -> bool:
        """Check if the message is from a nested node or graph."""
        if not node_path:
            return False
        # The first path is always the top-level graph.
        if len(node_path) > 2:
            # The second path can is a top-level node.
            # But we have to check the next node to see if it's a nested node or graph.
            return find_subgraph(node_path[2:])

        return False

    def _handle_root_message(
        self, message: AssistantStreamedMessageUnion, node_name: MaxNodeName
    ) -> AssistantStreamedMessageUnion | None:
        """Handle messages with no parent (root messages)."""
        if node_name not in self._verbose_nodes or not should_output_assistant_message(message):
            return None
        return message

    def _handle_update_message(
        self, event: AssistantDispatcherEvent, action: UpdateAction
    ) -> AssistantUpdateEvent | SubagentUpdateEvent | None:
        """Handle AssistantMessage that has a parent, creating an AssistantUpdateEvent."""
        if not event.node_path or not action.content:
            return None

        # Find the closest tool call id to the update.
        parent_path = next((path for path in reversed(event.node_path) if path.tool_call_id), None)
        # Updates from the top-level graph nodes are not supported.
        if not parent_path:
            return None

        tool_call_id = parent_path.tool_call_id
        message_id = parent_path.message_id

        if not message_id or not tool_call_id:
            return None

        if isinstance(action.content, AssistantToolCall):
            return SubagentUpdateEvent(id=message_id, tool_call_id=tool_call_id, content=action.content)

        return AssistantUpdateEvent(id=message_id, tool_call_id=tool_call_id, content=action.content)

    def _handle_special_child_message(
        self, message: AssistantStreamedMessageUnion
    ) -> AssistantStreamedMessageUnion | None:
        """
        Handle special message types that have parents.

        These messages are returned as-is regardless of where in the nesting hierarchy they are.
        """
        # These message types are always returned as-is
        if isinstance(message, FailureMessage | ArtifactMessage):
            return message

        return None

    def _handle_message_stream(
        self, event: AssistantDispatcherEvent, message: AIMessageChunk
    ) -> list[AssistantResultUnion] | None:
        """
        Process LLM chunks from "messages" stream mode.

        With dispatch pattern, complete messages are dispatched by nodes.
        This handles AIMessageChunk for ephemeral streaming (responsiveness).

        Subclasses can override this method to add custom streaming behavior.
        """
        node_name = cast(MaxNodeName, event.node_name)
        run_id = event.node_run_id

        if node_name not in self._streaming_nodes:
            return None
        if run_id not in self._chunks:
            self._chunks[run_id] = AIMessageChunk(content="")

        # Merge message chunks
        self._chunks[run_id] = merge_message_chunk(self._chunks[run_id], message)

        # Stream ephemeral messages (no ID = not persisted).
        # normalize_ai_message() returns a list when server_tool_use blocks are present,
        # but we only stream the latest message for incremental updates
        messages = normalize_ai_message(self._chunks[run_id])
        return [messages[-1]] if messages else None

    async def _handle_node_end(
        self, event: AssistantDispatcherEvent, action: NodeEndAction
    ) -> list[AssistantResultUnion] | None:
        """Handle the end of a node. Reset the streaming chunks."""
        if not isinstance(action.state, BaseStateWithMessages):
            return None
        results: list[AssistantResultUnion] = []
        for message in action.state.messages:
            if new_event := await self.process(
                AssistantDispatcherEvent(
                    action=MessageAction(message=message),
                    node_name=event.node_name,
                    node_run_id=event.node_run_id,
                    node_path=event.node_path,
                )
            ):
                results.extend(new_event)
        return results


class ChatAgentStreamProcessor(NotebookStreamingMixin, BaseStreamProcessor[StateType]):
    """
    Stream processor for chat agents with notebook streaming support.

    This class combines the base stream processor with notebook streaming capabilities.
    Use BaseStreamProcessor directly if you don't need notebook streaming.
    """

    def _handle_message_stream(
        self, event: AssistantDispatcherEvent, message: AIMessageChunk
    ) -> list[AssistantResultUnion] | None:
        """
        Process LLM chunks with notebook streaming support.
        """
        results = super()._handle_message_stream(event, message) or []

        # Add notebook streaming results if applicable
        chunk = self._chunks.get(event.node_run_id)
        if chunk and (notebook_artifact := self._check_for_notebook_streaming(chunk)):
            results.append(notebook_artifact)

        return results if results else None