devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/vendor/datalumina_genai/core/nodes/router.py

@@ -0,0 +1,69 @@
+from abc import ABC, abstractmethod
+from typing import Optional, Type
+
+from pydantic import BaseModel
+
+from ..task import TaskContext
+from .base import Node
+
+"""
+Router Module
+
+This module implements the routing logic for workflow nodes.
+It provides base classes for implementing routing decisions between nodes
+in a processing workflow.
+"""
+
+
+class BaseRouter(Node):
+    """Base router class for implementing node routing logic.
+
+    The BaseRouter class provides core routing functionality for directing
+    task flow between workflow nodes. It processes routing rules in sequence
+    and falls back to a default node if no rules match.
+
+    Attributes:
+        routes: List of RouterNode instances defining routing rules
+        fallback: Optional default node to route to if no rules match
+    """
+
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        pass
+
+    def route(self, task_context: TaskContext) -> Node:
+        """Determines the next node based on routing rules.
+
+        Evaluates each routing rule in sequence and returns the first
+        matching node. Falls back to the default node if no rules match.
+
+        Args:
+            task_context: Current task execution context
+
+        Returns:
+            The next node to execute, or None if no route is found
+        """
+        for route_node in self.routes:
+            route_node.task_context = task_context
+            next_node = route_node.determine_next_node(task_context)
+            if next_node:
+                return next_node
+        return self.fallback if self.fallback else None
+
+
+class RouterNode(ABC):
+    def __init__(self, task_context: TaskContext = None):
+        self.task_context = task_context
+
+    @abstractmethod
+    def determine_next_node(self, task_context: TaskContext) -> Optional[Node]:
+        pass
+
+    @property
+    def node_name(self):
+        return self.__class__.__name__
+
+    def save_output(self, output: BaseModel):
+        self.task_context.nodes[self.node_name] = output
+
+    def get_output(self, node_class: Type[Node]):
+        return self.task_context.nodes.get(node_class.__name__, None)

devflow_engine/vendor/datalumina_genai/core/schema.py

@@ -0,0 +1,72 @@
+from typing import List, Type, Optional
+
+from pydantic import BaseModel, Field
+
+from .nodes.base import Node
+
+"""
+Workflow Schema Module
+
+This module defines the schema classes used to configure workflow structures.
+It provides a type-safe way to define node connections and workflow layouts
+using Pydantic models.
+"""
+
+
+class NodeConfig(BaseModel):
+    """Configuration model for workflow nodes.
+
+    NodeConfig defines the structure and behavior of a single node within
+    a workflow, including its connections to other nodes and routing properties.
+
+    Attributes:
+        node: The Node class to be instantiated
+        connections: List of Node classes this node can connect to
+        is_router: Flag indicating if this node performs routing logic
+        description: Optional description of the node's purpose
+        concurrent_nodes: Optional list of Node classes that can run concurrently
+
+    Example:
+        config = NodeConfig(
+            node=AnalyzeNode,
+            connections=[RouterNode],
+            is_router=False,
+            description="Analyzes incoming requests"
+            concurrent_nodes=[FilterContentGuardrailNode, FilterSQLInjectionGuardrailNode]
+        )
+    """
+
+    node: Type[Node]
+    connections: List[Type[Node]] = Field(default_factory=list)
+    is_router: bool = False
+    description: Optional[str] = None
+    concurrent_nodes: Optional[List[Type[Node]]] = Field(default_factory=list)
+
+
+class WorkflowSchema(BaseModel):
+    """Schema definition for a complete workflow.
+
+    WorkflowSchema defines the overall structure of a processing workflow,
+    including its entry point and all constituent nodes.
+
+    Attributes:
+        description: Optional description of the workflow's purpose
+        event_schema: Pydantic model for validating incoming events
+        start: The entry point Node class for the workflow
+        nodes: List of NodeConfig objects defining the workflow structure
+
+    Example:
+        schema = WorkflowSchema(
+            description="Support ticket processing workflow",
+            start=AnalyzeNode,
+            nodes=[
+                NodeConfig(node=AnalyzeNode, connections=[RouterNode]),
+                NodeConfig(node=RouterNode, connections=[ResponseNode, EscalateNode]),
+            ]
+        )
+    """
+
+    description: Optional[str] = None
+    event_schema: Type[BaseModel]
+    start: Type[Node]
+    nodes: List[NodeConfig]

devflow_engine/vendor/datalumina_genai/core/task.py

@@ -0,0 +1,52 @@
+from typing import Any, Dict
+from pydantic import BaseModel, Field
+
+"""
+Task Context Module
+This module defines the context object that gets passed between workflow nodes.
+It maintains the state and metadata throughout workflow execution.
+"""
+
+
+class TaskContext(BaseModel):
+    """Context container for workflow task execution.
+    TaskContext maintains the state and results of a workflow's execution,
+    tracking the original event, intermediate node results, and additional
+    metadata throughout the processing flow.
+    Attributes:
+        event: The original event that triggered the workflow
+        nodes: Dictionary storing results and state from each node's execution
+        metadata: Dictionary storing workflow-level metadata and configuration
+        should_stop: Boolean flag indicating whether the workflow should stop execution
+    Example:
+        context = TaskContext(
+            event=incoming_event,
+            nodes={"AnalyzeNode": {"score": 0.95}},
+            metadata={"priority": "high"}
+        )
+    """
+
+    event: Any
+    nodes: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Stores results and state from each node's execution",
+    )
+    metadata: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Stores workflow-level metadata and configuration",
+    )
+    should_stop: bool = Field(
+        default=False,
+        description="Flag indicating whether the workflow should stop execution",
+    )
+
+    def update_node(self, node_name: str, **kwargs):
+        self.nodes[node_name] = {**self.nodes.get(node_name, {}), **kwargs}
+
+    def stop_workflow(self) -> None:
+        """Stops the current workflow execution by setting the stop flag.
+
+        This method can be called from any node to halt the workflow processing.
+        Once called, the workflow will stop after the current node completes.
+        """
+        self.should_stop = True

devflow_engine/vendor/datalumina_genai/core/validate.py

@@ -0,0 +1,139 @@
+from collections import deque
+from typing import Set, Type
+
+from .nodes.base import Node
+from .schema import WorkflowSchema
+
+"""
+Workflow Validator Module
+
+This module provides validation logic for workflow schemas.
+It ensures that workflows form valid directed acyclic graphs (DAGs)
+and that routing configurations are correct.
+"""
+
+
+class WorkflowValidator:
+    """Validator for ensuring workflow schema correctness.
+
+    The WorkflowValidator performs comprehensive validation of workflow schemas,
+    checking for cycles, unreachable nodes, and proper routing configurations.
+    It ensures that the workflow forms a valid directed acyclic graph (DAG)
+    and that routing nodes are properly configured.
+
+    Attributes:
+        workflow_schema: The WorkflowSchema to validate
+
+    Example:
+        validator = WorkflowValidator(workflow_schema)
+        validator.validate()  # Raises ValueError if validation fails
+    """
+
+    def __init__(self, workflow_schema: WorkflowSchema):
+        """Initializes the validator with a workflow schema.
+
+        Args:
+            workflow_schema: The WorkflowSchema to validate
+        """
+        self.workflow_schema = workflow_schema
+
+    def validate(self):
+        """Validates all aspects of the workflow schema.
+
+        Performs comprehensive validation including DAG structure
+        and routing configuration checks.
+
+        Raises:
+            ValueError: If any validation check fails
+        """
+        self._validate_dag()
+        self._validate_connections()
+
+    def _validate_dag(self):
+        """Validates that the workflow schema forms a proper DAG.
+
+        Checks for cycles and ensures all nodes are reachable
+        from the start node.
+
+        Raises:
+            ValueError: If the workflow contains cycles or unreachable nodes
+        """
+        if self._has_cycle():
+            raise ValueError("Workflow schema contains a cycle")
+
+        reachable_nodes = self._get_reachable_nodes()
+        all_nodes = set(nc.node for nc in self.workflow_schema.nodes)
+        unreachable_nodes = all_nodes - reachable_nodes
+        if unreachable_nodes:
+            raise ValueError(
+                f"The following nodes are unreachable: {unreachable_nodes}"
+            )
+
+    def _has_cycle(self) -> bool:
+        """Detects cycles in the workflow graph using DFS.
+
+        Returns:
+            bool: True if a cycle is detected, False otherwise
+        """
+        visited = set()
+        rec_stack = set()
+
+        def dfs(node: Type[Node]) -> bool:
+            visited.add(node)
+            rec_stack.add(node)
+
+            node_config = next(
+                (nc for nc in self.workflow_schema.nodes if nc.node == node), None
+            )
+            if node_config:
+                for neighbor in node_config.connections:
+                    if neighbor not in visited:
+                        if dfs(neighbor):
+                            return True
+                    elif neighbor in rec_stack:
+                        return True
+
+            rec_stack.remove(node)
+            return False
+
+        for node_config in self.workflow_schema.nodes:
+            if node_config.node not in visited:
+                if dfs(node_config.node):
+                    return True
+
+        return False
+
+    def _get_reachable_nodes(self) -> Set[Type[Node]]:
+        """Identifies all nodes reachable from the start node using BFS.
+
+        Returns:
+            Set[Type[Node]]: Set of all reachable node classes
+        """
+        reachable = set()
+        queue = deque([self.workflow_schema.start])
+
+        while queue:
+            node = queue.popleft()
+            if node not in reachable:
+                reachable.add(node)
+                node_config = next(
+                    (nc for nc in self.workflow_schema.nodes if nc.node == node), None
+                )
+                if node_config:
+                    queue.extend(node_config.connections)
+
+        return reachable
+
+    def _validate_connections(self):
+        """Validates node connection configurations.
+
+        Ensures that only nodes marked as routers have multiple connections.
+
+        Raises:
+            ValueError: If a non-router node has multiple connections
+        """
+        for node_config in self.workflow_schema.nodes:
+            if len(node_config.connections) > 1 and not node_config.is_router:
+                raise ValueError(
+                    f"Node {node_config.node.__name__} has multiple connections but is not marked as a router."
+                )

devflow_engine/vendor/datalumina_genai/core/workflow.py

@@ -0,0 +1,200 @@
+"""Workflow orchestration (vendored from Datalumina GenAI).
+
+This is a *minimal* subset used by DevFlow Engine.
+
+Notable changes vs upstream:
+- Removed Langfuse tracing + dotenv side-effects (keep engine self-contained)
+- Normalized imports to be package-relative
+
+The engine supports async execution and simple router nodes.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from abc import ABC
+from contextlib import contextmanager, nullcontext
+from typing import Any, AsyncIterator, ClassVar, Dict, Optional, Type
+
+from .nodes.agent_streaming_node import AgentStreamingNode
+from .nodes.base import Node
+from .nodes.router import BaseRouter
+from .schema import NodeConfig, WorkflowSchema
+from .task import TaskContext
+from .validate import WorkflowValidator
+
+
+class NoOpSpan:
+    """No-op span for compatibility with upstream tracing hooks."""
+
+    def update(self, **_kwargs: Any) -> None:  # noqa: D401
+        return
+
+
+class Workflow(ABC):
+    """Abstract base class for defining a processing workflow."""
+
+    workflow_schema: ClassVar[WorkflowSchema]
+
+    def __init__(self) -> None:
+        self.validator = WorkflowValidator(self.workflow_schema)
+        self.validator.validate()
+        self.nodes: Dict[Type[Node], NodeConfig] = self._initialize_nodes()
+
+    def _observation_context(self, _name: str):
+        # Tracing intentionally disabled in vendored version.
+        return nullcontext(NoOpSpan())
+
+    @contextmanager
+    def node_context(self, node_name: str):
+        logging.info("Starting node: %s", node_name)
+        try:
+            yield
+        except Exception:
+            logging.exception("Error in node %s", node_name)
+            raise
+        finally:
+            logging.info("Finished node: %s", node_name)
+
+    def _initialize_nodes(self) -> Dict[Type[Node], NodeConfig]:
+        nodes: Dict[Type[Node], NodeConfig] = {}
+        for node_config in self.workflow_schema.nodes:
+            nodes[node_config.node] = node_config
+            for connected_node in node_config.connections:
+                if connected_node not in nodes:
+                    nodes[connected_node] = NodeConfig(node=connected_node)
+        return nodes
+
+    def run(self, event: Any) -> TaskContext:
+        return asyncio.run(self._run(event))
+
+    async def run_async(self, event: Any) -> TaskContext:
+        return await self._run(event)
+
+    async def run_stream_async(self, event: Any) -> AsyncIterator[Dict[str, Any]]:
+        task_context = TaskContext(event=event)
+
+        with self._observation_context(self.__class__.__name__) as workflow_span:
+            try:
+                logging.info("Starting workflow streaming execution")
+
+                task_context.event = self.workflow_schema.event_schema(**event)
+                workflow_span.update(input=event)
+
+                task_context.metadata["nodes"] = self.nodes
+                current_node_class: Optional[Type[Node]] = self.workflow_schema.start
+
+                while current_node_class:
+                    if task_context.should_stop:
+                        break
+
+                    current_node = self.nodes[current_node_class].node
+                    node_name = current_node_class.__name__
+
+                    with self._observation_context(node_name) as node_span:
+                        node_span.update(
+                            input=task_context.model_dump(
+                                exclude={"metadata": {"nodes"}}
+                            )
+                        )
+
+                        with self.node_context(node_name):
+                            if not issubclass(current_node, BaseRouter):
+                                node_instance = current_node(task_context=task_context)
+
+                                if isinstance(node_instance, AgentStreamingNode):
+                                    async for stream_event in node_instance.process(
+                                        task_context
+                                    ):
+                                        yield stream_event
+                                else:
+                                    task_context = await node_instance.process(
+                                        task_context
+                                    )
+
+                            node_span.update(
+                                output=task_context.model_dump(
+                                    include={"nodes": {node_name}}
+                                )
+                            )
+
+                    current_node_class = await self._get_next_node_class(
+                        current_node_class, task_context
+                    )
+
+                workflow_span.update(
+                    output=task_context.model_dump(exclude={"metadata": {"nodes"}})
+                )
+                task_context.metadata.pop("nodes", None)
+
+            except Exception as e:
+                logging.exception("Error in workflow execution")
+                workflow_span.update(level="ERROR", status_message=str(e))
+                yield {"type": "error", "error": str(e)}
+                raise
+
+    async def _run(self, event: Any) -> TaskContext:
+        task_context = TaskContext(event=event)
+
+        with self._observation_context(self.__class__.__name__) as workflow_span:
+            task_context.event = self.workflow_schema.event_schema(**event)
+            workflow_span.update(input=event)
+
+            task_context.metadata["nodes"] = self.nodes
+            current_node_class: Optional[Type[Node]] = self.workflow_schema.start
+
+            while current_node_class:
+                if task_context.should_stop:
+                    break
+
+                current_node = self.nodes[current_node_class].node
+                node_name = current_node_class.__name__
+
+                with self._observation_context(node_name) as node_span:
+                    node_span.update(
+                        input=task_context.model_dump(exclude={"metadata": {"nodes"}})
+                    )
+
+                    with self.node_context(node_name):
+                        if not issubclass(current_node, BaseRouter):
+                            task_context = await current_node(
+                                task_context=task_context
+                            ).process(task_context)
+
+                    node_span.update(
+                        output=task_context.model_dump(include={"nodes": {node_name}})
+                    )
+
+                current_node_class = await self._get_next_node_class(
+                    current_node_class, task_context
+                )
+
+            workflow_span.update(
+                output=task_context.model_dump(exclude={"metadata": {"nodes"}})
+            )
+            task_context.metadata.pop("nodes", None)
+            return task_context
+
+    async def _get_next_node_class(
+        self, current_node_class: Type[Node], task_context: TaskContext
+    ) -> Optional[Type[Node]]:
+        node_config = next(
+            (nc for nc in self.workflow_schema.nodes if nc.node == current_node_class),
+            None,
+        )
+
+        if not node_config or not node_config.connections:
+            return None
+
+        if node_config.is_router:
+            router: BaseRouter = self.nodes[current_node_class].node()  # type: ignore[assignment]
+            return await self._handle_router(router, task_context)
+
+        return node_config.connections[0]
+
+    async def _handle_router(
+        self, router: BaseRouter, task_context: TaskContext
+    ) -> Optional[Type[Node]]:
+        next_node = router.route(task_context)
+        return next_node.__class__ if next_node else None