langflow-ai
diff --git a/‎src/backend/tests/unit/api/v1/test_mcp_client_server.py‎
Lines changed: 599 additions & 17 deletions b/‎src/backend/tests/unit/api/v1/test_mcp_client_server.py‎
Lines changed: 599 additions & 17 deletions
diff --git a/‎src/lfx/src/lfx/graph/flow_builder/__init__.py‎
Lines changed: 5 additions & 1 deletion b/‎src/lfx/src/lfx/graph/flow_builder/__init__.py‎
Lines changed: 5 additions & 1 deletion
diff --git a/‎src/lfx/src/lfx/graph/flow_builder/_utils.py‎
Lines changed: 15 additions & 0 deletions b/‎src/lfx/src/lfx/graph/flow_builder/_utils.py‎
Lines changed: 15 additions & 0 deletions
diff --git a/‎src/lfx/src/lfx/graph/flow_builder/builder.py‎
Lines changed: 140 additions & 0 deletions b/‎src/lfx/src/lfx/graph/flow_builder/builder.py‎
Lines changed: 140 additions & 0 deletions
diff --git a/‎src/lfx/src/lfx/graph/flow_builder/component.py‎
Lines changed: 2 additions & 5 deletions b/‎src/lfx/src/lfx/graph/flow_builder/component.py‎
Lines changed: 2 additions & 5 deletions
diff --git a/‎src/lfx/src/lfx/graph/flow_builder/flow.py‎
Lines changed: 86 additions & 0 deletions b/‎src/lfx/src/lfx/graph/flow_builder/flow.py‎
Lines changed: 86 additions & 0 deletions
diff --git a/‎src/lfx/src/lfx/graph/flow_builder/layout.py‎
Lines changed: 2 additions & 4 deletions b/‎src/lfx/src/lfx/graph/flow_builder/layout.py‎
Lines changed: 2 additions & 4 deletions
@@ -16,20 +16,24 @@
     list_connections,
     remove_connection,
 )
-from lfx.graph.flow_builder.flow import empty_flow, flow_info
+from lfx.graph.flow_builder.flow import empty_flow, flow_graph_repr, flow_info, flow_to_spec_summary
 from lfx.graph.flow_builder.layout import layout_flow
+from lfx.graph.flow_builder.spec import parse_flow_spec
 
 __all__ = [
     "add_component",
     "add_connection",
     "configure_component",
     "empty_flow",
+    "flow_graph_repr",
     "flow_info",
+    "flow_to_spec_summary",
     "get_component",
     "layout_flow",
     "list_components",
     "list_connections",
     "needs_server_update",
+    "parse_flow_spec",
     "remove_component",
     "remove_connection",
 ]
@@ -0,0 +1,15 @@
+"""Shared utilities for flow_builder modules.
+
+Extracted here to avoid duplicating helpers across component.py, layout.py,
+and other flow_builder modules that need the same node-level operations.
+"""
+
+
+def node_id(node: dict) -> str:
+    """Extract the node ID from a node dict.
+
+    Nodes store their ID in node["data"]["id"], falling back to node["id"].
+    This was duplicated in component.py and layout.py -- consolidated here
+    so both import from one place.
+    """
+    return node.get("data", {}).get("id", node.get("id", ""))
@@ -0,0 +1,140 @@
+"""Build a complete flow from a text spec using the local component registry.
+
+The component registry is loaded from a bundled index file and cached
+at module level. No network access or running server required.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from lfx.graph.flow_builder.component import add_component, configure_component
+from lfx.graph.flow_builder.connect import add_connection
+from lfx.graph.flow_builder.flow import empty_flow
+from lfx.graph.flow_builder.layout import layout_flow
+from lfx.graph.flow_builder.spec import parse_flow_spec, validate_spec_references
+from lfx.log.logger import logger
+
+_INDEX_PATH = Path(__file__).resolve().parent.parent.parent / "_assets" / "component_index.json"
+_registry_cache: dict[str, dict] | None = None
+
+
+def load_local_registry() -> dict[str, dict]:
+    """Load the component registry from the bundled index file.
+
+    Returns a flat dict: {component_type: template_dict}.
+    Results are cached after the first call.
+
+    Raises:
+        RuntimeError: If the index file is missing, corrupt, or empty.
+    """
+    global _registry_cache  # noqa: PLW0603
+    if _registry_cache is not None:
+        return _registry_cache
+
+    try:
+        with _INDEX_PATH.open() as f:
+            data = json.load(f)
+    except FileNotFoundError:
+        msg = f"Component registry not found at {_INDEX_PATH}. The lfx package may be installed incorrectly."
+        raise RuntimeError(msg) from None
+    except (json.JSONDecodeError, OSError) as e:
+        msg = f"Failed to load component registry from {_INDEX_PATH}: {e}"
+        raise RuntimeError(msg) from e
+
+    registry: dict[str, dict] = {}
+    for cat in data.get("entries", []):
+        if isinstance(cat, list) and len(cat) > 1 and isinstance(cat[1], dict):
+            category_name = cat[0] if isinstance(cat[0], str) else ""
+            for name, comp_data in cat[1].items():
+                if isinstance(comp_data, dict) and "template" in comp_data:
+                    registry[name] = {**comp_data, "category": category_name}
+
+    if not registry:
+        msg = f"Component registry at {_INDEX_PATH} contains no valid components."
+        raise RuntimeError(msg)
+
+    logger.debug("Loaded %d components from local registry", len(registry))
+    _registry_cache = registry
+    return registry
+
+
+def build_flow_from_spec(spec: str) -> dict[str, Any]:
+    """Build a flow dict from a text spec. Returns the flow or errors.
+
+    On success: {"flow": <flow_dict>, "name": str, "node_count": int, "edge_count": int}
+    On failure: {"error": str, "details": str}
+    """
+    registry = load_local_registry()
+
+    try:
+        parsed = parse_flow_spec(spec)
+    except ValueError as e:
+        return {"error": "Invalid spec", "details": str(e)}
+
+    # Validate that all component types exist in the registry
+    unknown = [n["type"] for n in parsed["nodes"] if n["type"] not in registry]
+    if unknown:
+        return {
+            "error": f"Unknown component types: {unknown}",
+            "details": f"Available types (sample): {sorted(registry.keys())[:30]}",
+        }
+
+    # Validate node references in edges and config
+    try:
+        validate_spec_references(parsed)
+    except ValueError as e:
+        return {"error": str(e), "details": str(e)}
+
+    # Build the flow
+    flow = empty_flow(
+        name=parsed.get("name", "Untitled Flow"),
+        description=parsed.get("description", ""),
+    )
+
+    id_map: dict[str, str] = {}
+
+    # Add components
+    for node in parsed["nodes"]:
+        try:
+            result = add_component(flow, node["type"], registry)
+        except (ValueError, KeyError) as e:
+            return {"error": f"Failed to add component '{node['type']}' (node '{node['id']}')", "details": str(e)}
+        id_map[node["id"]] = result["id"]
+
+    # Apply config
+    for spec_id, params in parsed.get("config", {}).items():
+        try:
+            configure_component(flow, id_map[spec_id], params)
+        except (ValueError, KeyError) as e:
+            return {"error": f"Failed to configure node '{spec_id}'", "details": str(e)}
+
+    # Connect edges
+    for edge in parsed["edges"]:
+        src_out = f"{edge['source_id']}.{edge['source_output']}"
+        tgt_in = f"{edge['target_id']}.{edge['target_input']}"
+        try:
+            add_connection(
+                flow,
+                id_map[edge["source_id"]],
+                edge["source_output"],
+                id_map[edge["target_id"]],
+                edge["target_input"],
+            )
+        except (ValueError, KeyError) as e:
+            return {"error": f"Failed to connect {src_out} -> {tgt_in}", "details": str(e)}
+
+    layout_flow(flow)
+
+    flow["name"] = parsed.get("name", "Untitled Flow")
+    flow["description"] = parsed.get("description", "")
+
+    return {
+        "flow": flow,
+        "name": flow["name"],
+        "node_count": len(flow["data"]["nodes"]),
+        "edge_count": len(flow["data"]["edges"]),
+        "node_id_map": id_map,
+    }
@@ -14,6 +14,8 @@
 import string
 from typing import Any
 
+from lfx.graph.flow_builder._utils import node_id as _node_id
+
 
 def _generate_id(component_type: str) -> str:
     """Generate a component ID like 'ChatInput-a1B2c'."""
@@ -162,11 +164,6 @@ def needs_server_update(template: dict, field: str) -> bool:
     return bool(field_def.get("real_time_refresh"))
 
 
-def _node_id(node: dict) -> str:
-    """Extract the node ID from a node dict."""
-    return node.get("data", {}).get("id", node.get("id", ""))
-
-
 def _find_node(flow: dict, component_id: str) -> dict | None:
     """Find a node by component ID."""
     for node in flow.get("data", {}).get("nodes", []):
 
@@ -57,3 +57,89 @@ def flow_info(flow: dict) -> dict:
         "inputs": inputs,
         "outputs": outputs,
     }
+
+
+def flow_to_spec_summary(flow: dict) -> str:
+    """Convert a flow dict to a compact summary with component IDs for LLM context.
+
+    Includes full component IDs so the agent can reference them in tool calls.
+    Field values are NOT included -- the agent should use get_field_value to inspect.
+    """
+    data = flow.get("data", {})
+    nodes = data.get("nodes", [])
+    edges = data.get("edges", [])
+
+    if not nodes:
+        return "(empty canvas)"
+
+    id_to_type: dict[str, str] = {}
+    lines = [f"name: {flow.get('name', 'Untitled')}"]
+
+    lines.append("\ncomponents:")
+    for node in nodes:
+        nd = node.get("data", {})
+        nid = nd.get("id", node.get("id", ""))
+        ntype = nd.get("type", "?")
+        id_to_type[nid] = ntype
+        lines.append(f"  {nid}: {ntype}")
+
+    if edges:
+        lines.append("\nconnections:")
+        for edge in edges:
+            src = edge.get("source", "")
+            tgt = edge.get("target", "")
+            edge_data = edge.get("data", {})
+            src_handle = edge_data.get("sourceHandle", {}).get("name", "?")
+            tgt_handle = edge_data.get("targetHandle", {}).get("fieldName", "?")
+            lines.append(f"  {src}.{src_handle} -> {tgt}.{tgt_handle}")
+
+    return "\n".join(lines)
+
+
+def flow_graph_repr(flow: dict) -> str:
+    """Build an ASCII DAG representation of a flow's graph.
+
+    Uses lfx's ASCII graph renderer (grandalf-based Sugiyama layout),
+    falling back to a simple chain representation if unavailable.
+    """
+    data = flow.get("data", {})
+    nodes = data.get("nodes", [])
+    edges = data.get("edges", [])
+
+    if not nodes:
+        return "(empty)"
+
+    # Build id -> label map, disambiguating duplicate types
+    id_to_label: dict[str, str] = {}
+    type_count: dict[str, int] = {}
+    for node in nodes:
+        nd = node.get("data", {})
+        nid = nd.get("id", node.get("id", ""))
+        node_type = nd.get("type", "?")
+        count = type_count.get(node_type, 0) + 1
+        type_count[node_type] = count
+        id_to_label[nid] = f"{node_type} #{count}" if count > 1 else node_type
+
+    # Go back and suffix the first occurrence too when there are duplicates
+    for nid, label in id_to_label.items():
+        if "#" not in label and type_count.get(label, 0) > 1:
+            id_to_label[nid] = f"{label} #1"
+
+    if not edges:
+        return ", ".join(sorted(id_to_label.values()))
+
+    vertexes = list(id_to_label.values())
+    edge_pairs = []
+    for edge in edges:
+        src_label = id_to_label.get(edge.get("source", ""))
+        tgt_label = id_to_label.get(edge.get("target", ""))
+        if src_label and tgt_label:
+            edge_pairs.append((src_label, tgt_label))
+
+    try:
+        from lfx.graph.graph.ascii import draw_graph
+
+        return draw_graph(vertexes, edge_pairs, return_ascii=True) or "(empty)"
+    except ImportError:
+        # grandalf not available; fall back to simple representation
+        return ", ".join(f"{s} -> {t}" for s, t in edge_pairs)
@@ -8,6 +8,8 @@
 
 from collections import defaultdict, deque
 
+from lfx.graph.flow_builder._utils import node_id as _node_id
+
 LAYER_SPACING_X = 600
 NODE_SPACING_Y = 350
 
@@ -86,7 +88,3 @@ def _assign_layers(
             next_layer += 1
 
     return layers
-
-
-def _node_id(node: dict) -> str:
-    return node.get("data", {}).get("id", node.get("id", ""))