feat(dynaflow): built-in node library and graph execution pipeline (#283)

src/dynavec/__init__.py

@@ -63,6 +63,25 @@
     UpsertResult,
 )
 from .namespace import NamespaceView
+from .nodes import (
+    ApprovalNode,
+    CodeNode,
+    Edge,
+    LLMNode,
+    LoopNode,
+    Node,
+    NodePort,
+    NodeRegistry,
+    NodeSchema,
+    PortType,
+    RetrieverNode,
+    RouterNode,
+    SimpleGraph,
+    SubGraphNode,
+    ToolNode,
+    WebhookNode,
+    node_registry,
+)
 from .quantization import (
     OPQRotation,
     OptimizedProductQuantizer,
@@ -153,4 +172,22 @@
     "ItemTooLargeError",
     "ConflictError",
     "MissingDependencyError",
+    # Nodes & Graph
+    "Node",
+    "NodePort",
+    "NodeSchema",
+    "PortType",
+    "NodeRegistry",
+    "node_registry",
+    "Edge",
+    "SimpleGraph",
+    "RetrieverNode",
+    "LLMNode",
+    "ToolNode",
+    "RouterNode",
+    "CodeNode",
+    "ApprovalNode",
+    "LoopNode",
+    "WebhookNode",
+    "SubGraphNode",
 ]

src/dynavec/nodes/__init__.py

@@ -0,0 +1,38 @@
+"""Typed node library and execution graph for dynaflow."""
+
+from __future__ import annotations
+
+from .base import Node, NodePort, NodeSchema, PortType
+from .builtin import (
+    ApprovalNode,
+    CodeNode,
+    LLMNode,
+    LoopNode,
+    RetrieverNode,
+    RouterNode,
+    SubGraphNode,
+    ToolNode,
+    WebhookNode,
+)
+from .graph import Edge, SimpleGraph
+from .registry import NodeRegistry, node_registry
+
+__all__ = [
+    "Node",
+    "NodePort",
+    "NodeSchema",
+    "PortType",
+    "NodeRegistry",
+    "node_registry",
+    "RetrieverNode",
+    "LLMNode",
+    "ToolNode",
+    "RouterNode",
+    "CodeNode",
+    "ApprovalNode",
+    "LoopNode",
+    "WebhookNode",
+    "SubGraphNode",
+    "Edge",
+    "SimpleGraph",
+]

src/dynavec/nodes/base.py

@@ -0,0 +1,100 @@
+"""Base abstractions and schemas for the dynaflow node system."""
+
+from __future__ import annotations
+
+import uuid
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+PortType = Literal["string", "number", "boolean", "array", "object", "any"]
+
+
+@dataclass
+class NodePort:
+    """A typed input or output connection port on a node."""
+
+    name: str
+    port_type: PortType = "any"
+    description: str = ""
+    required: bool = True
+    default: Any = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert port definition to a dictionary."""
+        return {
+            "name": self.name,
+            "port_type": self.port_type,
+            "description": self.description,
+            "required": self.required,
+            "default": self.default,
+        }
+
+
+@dataclass
+class NodeSchema:
+    """Metadata describing a node type's ports, config, and canvas properties."""
+
+    node_type: str
+    label: str
+    description: str
+    category: str = "general"
+    inputs: list[NodePort] = field(default_factory=list)
+    outputs: list[NodePort] = field(default_factory=list)
+    config_schema: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize schema to dictionary."""
+        return {
+            "node_type": self.node_type,
+            "label": self.label,
+            "description": self.description,
+            "category": self.category,
+            "inputs": [p.to_dict() for p in self.inputs],
+            "outputs": [p.to_dict() for p in self.outputs],
+            "config_schema": self.config_schema,
+        }
+
+    def to_reactflow_dict(self) -> dict[str, Any]:
+        """Export ReactFlow-compatible component metadata for visual canvas builders."""
+        return {
+            "type": self.node_type,
+            "label": self.label,
+            "category": self.category,
+            "description": self.description,
+            "inputPorts": [p.name for p in self.inputs],
+            "outputPorts": [p.name for p in self.outputs],
+            "config": self.config_schema,
+        }
+
+
+class Node(ABC):
+    """Abstract base class for all execution nodes in dynaflow."""
+
+    node_type: str
+    schema: NodeSchema
+
+    def __init__(
+        self,
+        node_id: str | None = None,
+        config: dict[str, Any] | None = None,
+    ) -> None:
+        self.id = node_id or f"{self.node_type}_{uuid.uuid4().hex[:8]}"
+        self.config = dict(config or {})
+
+    @abstractmethod
+    def execute(self, inputs: dict[str, Any]) -> dict[str, Any]:
+        """Execute the node logic given an inputs dictionary, returning outputs."""
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize node to a ReactFlow-compatible node object."""
+        return {
+            "id": self.id,
+            "type": self.node_type,
+            "data": {
+                "label": self.schema.label,
+                "config": self.config,
+                "category": self.schema.category,
+            },
+            "position": {"x": 0, "y": 0},
+        }