Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
feat: add flow_structure() serializer for Flow class introspection (#5021)
alex-clawd1704ccdfa817
diff --git a/lib/crewai/src/crewai/flow/__init__.py b/lib/crewai/src/crewai/flow/__init__.pyindex ec4a3ac5e..6922725fa 100644--- a/lib/crewai/src/crewai/flow/__init__.py+++ b/lib/crewai/src/crewai/flow/__init__.py@@ -6,6 +6,7 @@ from crewai.flow.async_feedback import ()from crewai.flow.flow import Flow, and_, listen, or_, router, startfrom crewai.flow.flow_config import flow_config+from crewai.flow.flow_serializer import flow_structurefrom crewai.flow.human_feedback import HumanFeedbackResult, human_feedbackfrom crewai.flow.input_provider import InputProvider, InputResponsefrom crewai.flow.persistence import persist@@ -29,6 +30,7 @@ __all__ = ["and_","build_flow_structure","flow_config",+ "flow_structure","human_feedback","listen","or_",diff --git a/lib/crewai/src/crewai/flow/flow_serializer.py b/lib/crewai/src/crewai/flow/flow_serializer.pynew file mode 100644index 000000000..85ff8be1a--- /dev/null+++ b/lib/crewai/src/crewai/flow/flow_serializer.py@@ -0,0 +1,619 @@+"""Flow structure serializer for introspecting Flow classes.++This module provides the flow_structure() function that analyzes a Flow class+and returns a JSON-serializable dictionary describing its graph structure.+This is used by Studio UI to render a visual flow graph.++Example:+ >>> from crewai.flow import Flow, start, listen+ >>> from crewai.flow.flow_serializer import flow_structure+ >>>+ >>> class MyFlow(Flow):+ ... @start()+ ... def begin(self):+ ... return "started"+ ...+ ... @listen(begin)+ ... def process(self):+ ... return "done"+ >>>+ >>> structure = flow_structure(MyFlow)+ >>> print(structure["name"])+ 'MyFlow'+"""++from __future__ import annotations++import inspect+import logging+import re+import textwrap+from typing import Any, TypedDict, get_args, get_origin++from pydantic import BaseModel+from pydantic_core import PydanticUndefined++from crewai.flow.flow_wrappers import (+ FlowCondition,+ FlowMethod,+ ListenMethod,+ RouterMethod,+ StartMethod,+)+++logger = logging.getLogger(__name__)+++class MethodInfo(TypedDict, total=False):+ """Information about a single flow method.++ Attributes:+ name: The method name.+ type: Method type - start, listen, router, or start_router.+ trigger_methods: List of method names that trigger this method.+ condition_type: 'AND' or 'OR' for composite conditions, null otherwise.+ router_paths: For routers, the possible route names returned.+ has_human_feedback: Whether the method has @human_feedback decorator.+ has_crew: Whether the method body references a Crew.+ """++ name: str+ type: str+ trigger_methods: list[str]+ condition_type: str | None+ router_paths: list[str]+ has_human_feedback: bool+ has_crew: bool+++class EdgeInfo(TypedDict, total=False):+ """Information about an edge between flow methods.++ Attributes:+ from_method: Source method name.+ to_method: Target method name.+ edge_type: Type of edge - 'listen' or 'route'.+ condition: Route name for router edges, null for listen edges.+ """++ from_method: str+ to_method: str+ edge_type: str+ condition: str | None+++class StateFieldInfo(TypedDict, total=False):+ """Information about a state field.++ Attributes:+ name: Field name.+ type: Field type as string.+ default: Default value if any.+ """++ name: str+ type: str+ default: Any+++class StateSchemaInfo(TypedDict, total=False):+ """Information about the flow's state schema.++ Attributes:+ fields: List of field information.+ """++ fields: list[StateFieldInfo]+++class FlowStructureInfo(TypedDict, total=False):+ """Complete flow structure information.++ Attributes:+ name: Flow class name.+ description: Flow docstring if available.+ methods: List of method information.+ edges: List of edge information.+ state_schema: State schema if typed, null otherwise.+ inputs: Detected flow inputs if available.+ """++ name: str+ description: str | None+ methods: list[MethodInfo]+ edges: list[EdgeInfo]+ state_schema: StateSchemaInfo | None+ inputs: list[str]+++def _get_method_type(+ method_name: str,+ method: Any,+ start_methods: list[str],+ routers: set[str],+) -> str:+ """Determine the type of a flow method.++ Args:+ method_name: Name of the method.+ method: The method object.+ start_methods: List of start method names.+ routers: Set of router method names.++ Returns:+ One of: 'start', 'listen', 'router', or 'start_router'.+ """+ is_start = method_name in start_methods or getattr(+ method, "__is_start_method__", False+ )+ is_router = method_name in routers or getattr(method, "__is_router__", False)++ if is_start and is_router:+ return "start_router"+ if is_start:+ return "start"+ if is_router:+ return "router"+ return "listen"+++def _has_human_feedback(method: Any) -> bool:+ """Check if a method has the @human_feedback decorator.++ Args:+ method: The method object to check.++ Returns:+ True if the method has __human_feedback_config__ attribute.+ """+ return hasattr(method, "__human_feedback_config__")+++def _detect_crew_reference(method: Any) -> bool:+ """Detect if a method body references a Crew.++ Checks for patterns like:+ - .crew() method calls+ - Crew( instantiation+ - References to Crew class in type hints++ Note:+ This is a **best-effort heuristic for UI hints**, not a guarantee.+ Uses inspect.getsource + regex which can false-positive on comments+ or string literals, and may fail on dynamically generated methods+ or lambdas. Do not rely on this for correctness-critical logic.++ Args:+ method: The method object to inspect.++ Returns:+ True if crew reference detected, False otherwise.+ """+ try:+ # Get the underlying function from wrapper+ func = method+ if hasattr(method, "_meth"):+ func = method._meth+ elif hasattr(method, "__wrapped__"):+ func = method.__wrapped__++ source = inspect.getsource(func)+ source = textwrap.dedent(source)++ # Patterns that indicate Crew usage+ crew_patterns = [+ r"\.crew\(\)", # .crew() method call+ r"Crew\s*\(", # Crew( instantiation+ r":\s*Crew\b", # Type hint with Crew+ r"->.*Crew", # Return type hint with Crew+ ]++ for pattern in crew_patterns:+ if re.search(pattern, source):+ return True++ return False+ except (OSError, TypeError):+ # Can't get source code - assume no crew reference+ return False+++def _extract_trigger_methods(method: Any) -> tuple[list[str], str | None]:+ """Extract trigger methods and condition type from a method.++ Args:+ method: The method object to inspect.++ Returns:+ Tuple of (trigger_methods list, condition_type or None).+ """+ trigger_methods: list[str] = []+ condition_type: str | None = None++ # First try __trigger_methods__ (populated for simple conditions)+ if hasattr(method, "__trigger_methods__") and method.__trigger_methods__:+ trigger_methods = [str(m) for m in method.__trigger_methods__]++ # For complex conditions (or_/and_ combinators), extract from __trigger_condition__+ if (+ not trigger_methods+ and hasattr(method, "__trigger_condition__")+ and method.__trigger_condition__+ ):+ trigger_condition = method.__trigger_condition__+ trigger_methods = _extract_all_methods_from_condition(trigger_condition)++ if hasattr(method, "__condition_type__") and method.__condition_type__:+ condition_type = str(method.__condition_type__)++ return trigger_methods, condition_type+++def _extract_router_paths(+ method: Any, router_paths_registry: dict[str, list[str]]+) -> list[str]:+ """Extract router paths for a router method.++ Args:+ method: The method object.+ router_paths_registry: The class-level _router_paths dict.++ Returns:+ List of possible route names.+ """+ method_name = getattr(method, "__name__", "")++ # First check if there are __router_paths__ on the method itself+ if hasattr(method, "__router_paths__") and method.__router_paths__:+ return [str(p) for p in method.__router_paths__]++ # Then check the class-level registry+ if method_name in router_paths_registry:+ return [str(p) for p in router_paths_registry[method_name]]++ return []+++def _extract_all_methods_from_condition(+ condition: str | FlowCondition | dict[str, Any] | list[Any],+) -> list[str]:+ """Extract all method names from a condition tree recursively.++ Args:+ condition: Can be a string, FlowCondition tuple, dict, or list.++ Returns:+ List of all method names found in the condition.+ """+ if isinstance(condition, str):+ return [condition]+ if isinstance(condition, tuple) and len(condition) == 2:+ # FlowCondition: (condition_type, methods_list)+ _, methods = condition+ if isinstance(methods, list):+ result: list[str] = []+ for m in methods:+ result.extend(_extract_all_methods_from_condition(m))+ return result+ return []+ if isinstance(condition, dict):+ conditions_list = condition.get("conditions", [])+ methods: list[str] = []+ for sub_cond in conditions_list:+ methods.extend(_extract_all_methods_from_condition(sub_cond))+ return methods+ if isinstance(condition, list):+ methods = []+ for item in condition:+ methods.extend(_extract_all_methods_from_condition(item))+ return methods+ return []+++def _generate_edges(+ listeners: dict[str, tuple[str, list[str]] | FlowCondition],+ routers: set[str],+ router_paths: dict[str, list[str]],+ all_methods: set[str],+) -> list[EdgeInfo]:+ """Generate edges from listeners and routers.++ Args:+ listeners: Map of listener_name -> (condition_type, trigger_methods) or FlowCondition.+ routers: Set of router method names.+ router_paths: Map of router_name -> possible return values.+ all_methods: Set of all method names in the flow.++ Returns:+ List of EdgeInfo dictionaries.+ """+ edges: list[EdgeInfo] = []++ # Generate edges from listeners (listen edges)+ for listener_name, condition_data in listeners.items():+ trigger_methods: list[str] = []++ if isinstance(condition_data, tuple) and len(condition_data) == 2:+ _condition_type, methods = condition_data+ trigger_methods = [str(m) for m in methods]+ elif isinstance(condition_data, dict):+ trigger_methods = _extract_all_methods_from_condition(condition_data)++ # Create edges from each trigger to the listener+ edges.extend(+ EdgeInfo(+ from_method=trigger,+ to_method=listener_name,+ edge_type="listen",+ condition=None,+ )+ for trigger in trigger_methods+ if trigger in all_methods+ )++ # Generate edges from routers (route edges)+ for router_name, paths in router_paths.items():+ for path in paths:+ # Find listeners that listen to this path+ for listener_name, condition_data in listeners.items():+ path_triggers: list[str] = []++ if isinstance(condition_data, tuple) and len(condition_data) == 2:+ _, methods = condition_data+ path_triggers = [str(m) for m in methods]+ elif isinstance(condition_data, dict):+ path_triggers = _extract_all_methods_from_condition(condition_data)++ if str(path) in path_triggers:+ edges.append(+ EdgeInfo(+ from_method=router_name,+ to_method=listener_name,+ edge_type="route",+ condition=str(path),+ )+ )++ return edges+++def _extract_state_schema(flow_class: type) -> StateSchemaInfo | None:+ """Extract state schema from a Flow class.++ Checks for:+ - Generic type parameter (Flow[MyState])+ - initial_state class attribute++ Args:+ flow_class: The Flow class to inspect.++ Returns:+ StateSchemaInfo if a Pydantic model state is detected, None otherwise.+ """+ state_type: type | None = None++ # Check for _initial_state_t set by __class_getitem__+ if hasattr(flow_class, "_initial_state_t"):+ state_type = flow_class._initial_state_t++ # Check initial_state class attribute+ if state_type is None and hasattr(flow_class, "initial_state"):+ initial_state = flow_class.initial_state+ if isinstance(initial_state, type) and issubclass(initial_state, BaseModel):+ state_type = initial_state+ elif isinstance(initial_state, BaseModel):+ state_type = type(initial_state)++ # Check __orig_bases__ for generic parameters+ if state_type is None and hasattr(flow_class, "__orig_bases__"):+ for base in flow_class.__orig_bases__:+ origin = get_origin(base)+ if origin is not None:+ args = get_args(base)+ if args:+ candidate = args[0]+ if isinstance(candidate, type) and issubclass(candidate, BaseModel):+ state_type = candidate+ break++ if state_type is None or not issubclass(state_type, BaseModel):+ return None++ # Extract fields from the Pydantic model+ fields: list[StateFieldInfo] = []+ try:+ model_fields = state_type.model_fields+ for field_name, field_info in model_fields.items():+ field_type_str = "Any"+ if field_info.annotation is not None:+ field_type_str = str(field_info.annotation)+ # Clean up the type string+ field_type_str = field_type_str.replace("typing.", "")+ field_type_str = field_type_str.replace("<class '", "").replace(+ "'>", ""+ )++ default_value = None+ if (+ field_info.default is not PydanticUndefined+ and field_info.default is not None+ and not callable(field_info.default)+ ):+ try:+ # Try to serialize the default value+ default_value = field_info.default+ except Exception:+ default_value = str(field_info.default)++ fields.append(+ StateFieldInfo(+ name=field_name,+ type=field_type_str,+ default=default_value,+ )+ )+ except Exception:+ logger.debug(+ "Failed to extract state schema fields for %s", flow_class.__name__+ )++ return StateSchemaInfo(fields=fields) if fields else None+++def _detect_flow_inputs(flow_class: type) -> list[str]:+ """Detect flow input parameters.++ Inspects the __init__ signature for custom parameters beyond standard Flow params.++ Args:+ flow_class: The Flow class to inspect.++ Returns:+ List of detected input names.+ """+ inputs: list[str] = []++ # Check for inputs in __init__ signature beyond standard Flow params+ try:+ init_sig = inspect.signature(flow_class.__init__)+ standard_params = {+ "self",+ "persistence",+ "tracing",+ "suppress_flow_events",+ "max_method_calls",+ "kwargs",+ }+ inputs.extend(+ param_name+ for param_name in init_sig.parameters+ if param_name not in standard_params and not param_name.startswith("_")+ )+ except Exception:+ logger.debug(+ "Failed to detect inputs from __init__ for %s", flow_class.__name__+ )++ return inputs+++def flow_structure(flow_class: type) -> FlowStructureInfo:+ """Introspect a Flow class and return its structure as a JSON-serializable dict.++ This function analyzes a Flow CLASS (not instance) and returns complete+ information about its graph structure including methods, edges, and state.++ Args:+ flow_class: A Flow class (not an instance) to introspect.++ Returns:+ FlowStructureInfo dictionary containing:+ - name: Flow class name+ - description: Docstring if available+ - methods: List of method info dicts+ - edges: List of edge info dicts+ - state_schema: State schema if typed, None otherwise+ - inputs: Detected input names++ Raises:+ TypeError: If flow_class is not a class.++ Example:+ >>> structure = flow_structure(MyFlow)+ >>> print(structure["name"])+ 'MyFlow'+ >>> for method in structure["methods"]:+ ... print(method["name"], method["type"])+ """+ if not isinstance(flow_class, type):+ raise TypeError(+ f"flow_structure requires a Flow class, not an instance. "+ f"Got {type(flow_class).__name__}"+ )++ # Get class-level metadata set by FlowMeta+ start_methods: list[str] = getattr(flow_class, "_start_methods", [])+ listeners: dict[str, Any] = getattr(flow_class, "_listeners", {})+ routers: set[str] = getattr(flow_class, "_routers", set())+ router_paths_registry: dict[str, list[str]] = getattr(+ flow_class, "_router_paths", {}+ )++ # Collect all flow methods+ methods: list[MethodInfo] = []+ all_method_names: set[str] = set()++ for attr_name in dir(flow_class):+ if attr_name.startswith("_"):+ continue++ try:+ attr = getattr(flow_class, attr_name)+ except AttributeError:+ continue++ # Check if it's a flow method+ is_flow_method = (+ isinstance(attr, (FlowMethod, StartMethod, ListenMethod, RouterMethod))+ or hasattr(attr, "__is_flow_method__")+ or hasattr(attr, "__is_start_method__")+ or hasattr(attr, "__trigger_methods__")+ or hasattr(attr, "__is_router__")+ )++ if not is_flow_method:+ continue++ all_method_names.add(attr_name)++ # Get method type+ method_type = _get_method_type(attr_name, attr, start_methods, routers)++ # Get trigger methods and condition type+ trigger_methods, condition_type = _extract_trigger_methods(attr)++ # Get router paths if applicable+ router_paths_list: list[str] = []+ if method_type in ("router", "start_router"):+ router_paths_list = _extract_router_paths(attr, router_paths_registry)++ # Check for human feedback+ has_hf = _has_human_feedback(attr)++ # Check for crew reference+ has_crew = _detect_crew_reference(attr)++ method_info = MethodInfo(+ name=attr_name,+ type=method_type,+ trigger_methods=trigger_methods,+ condition_type=condition_type,+ router_paths=router_paths_list,+ has_human_feedback=has_hf,+ has_crew=has_crew,+ )+ methods.append(method_info)++ # Generate edges+ edges = _generate_edges(listeners, routers, router_paths_registry, all_method_names)++ # Extract state schema+ state_schema = _extract_state_schema(flow_class)++ # Detect inputs+ inputs = _detect_flow_inputs(flow_class)++ # Get flow description from docstring+ description: str | None = None+ if flow_class.__doc__:+ description = flow_class.__doc__.strip()++ return FlowStructureInfo(+ name=flow_class.__name__,+ description=description,+ methods=methods,+ edges=edges,+ state_schema=state_schema,+ inputs=inputs,+ )diff --git a/lib/crewai/tests/test_flow_serializer.py b/lib/crewai/tests/test_flow_serializer.pynew file mode 100644index 000000000..952325deb--- /dev/null+++ b/lib/crewai/tests/test_flow_serializer.py@@ -0,0 +1,795 @@+"""Tests for flow_serializer.py - Flow structure serialization for Studio UI."""++from typing import Literal++import pytest+from pydantic import BaseModel, Field++from crewai.flow.flow import Flow, and_, listen, or_, router, start+from crewai.flow.flow_serializer import flow_structure+from crewai.flow.human_feedback import human_feedback+++class TestSimpleLinearFlow:+ """Test simple linear flow (start → listen → listen)."""++ def test_linear_flow_structure(self):+ """Test a simple sequential flow structure."""++ class LinearFlow(Flow):+ """A simple linear flow for testing."""++ @start()+ def begin(self):+ return "started"++ @listen(begin)+ def process(self):+ return "processed"++ @listen(process)+ def finalize(self):+ return "done"++ structure = flow_structure(LinearFlow)++ assert structure["name"] == "LinearFlow"+ assert structure["description"] == "A simple linear flow for testing."+ assert len(structure["methods"]) == 3++ # Check method types+ method_map = {m["name"]: m for m in structure["methods"]}++ assert method_map["begin"]["type"] == "start"+ assert method_map["process"]["type"] == "listen"+ assert method_map["finalize"]["type"] == "listen"++ # Check edges+ assert len(structure["edges"]) == 2++ edge_pairs = [(e["from_method"], e["to_method"]) for e in structure["edges"]]+ assert ("begin", "process") in edge_pairs+ assert ("process", "finalize") in edge_pairs++ # All edges should be listen type+ for edge in structure["edges"]:+ assert edge["edge_type"] == "listen"+ assert edge["condition"] is None+++class TestRouterFlow:+ """Test flow with router branching."""++ def test_router_flow_structure(self):+ """Test a flow with router that branches to different paths."""++ class BranchingFlow(Flow):+ @start()+ def init(self):+ return "initialized"++ @router(init)+ def decide(self) -> Literal["path_a", "path_b"]:+ return "path_a"++ @listen("path_a")+ def handle_a(self):+ return "handled_a"++ @listen("path_b")+ def handle_b(self):+ return "handled_b"++ structure = flow_structure(BranchingFlow)++ assert structure["name"] == "BranchingFlow"+ assert len(structure["methods"]) == 4++ method_map = {m["name"]: m for m in structure["methods"]}++ # Check method types+ assert method_map["init"]["type"] == "start"+ assert method_map["decide"]["type"] == "router"+ assert method_map["handle_a"]["type"] == "listen"+ assert method_map["handle_b"]["type"] == "listen"++ # Check router paths+ assert "path_a" in method_map["decide"]["router_paths"]+ assert "path_b" in method_map["decide"]["router_paths"]++ # Check edges+ # Should have: init -> decide (listen), decide -> handle_a (route), decide -> handle_b (route)+ listen_edges = [e for e in structure["edges"] if e["edge_type"] == "listen"]+ route_edges = [e for e in structure["edges"] if e["edge_type"] == "route"]++ assert len(listen_edges) == 1+ assert listen_edges[0]["from_method"] == "init"+ assert listen_edges[0]["to_method"] == "decide"++ assert len(route_edges) == 2+ route_targets = {e["to_method"] for e in route_edges}+ assert "handle_a" in route_targets+ assert "handle_b" in route_targets++ # Check route conditions+ route_conditions = {e["to_method"]: e["condition"] for e in route_edges}+ assert route_conditions["handle_a"] == "path_a"+ assert route_conditions["handle_b"] == "path_b"+++class TestAndOrConditions:+ """Test flow with AND/OR conditions."""++ def test_and_condition_flow(self):+ """Test a flow where a method waits for multiple methods (AND)."""++ class AndConditionFlow(Flow):+ @start()+ def step_a(self):+ return "a"++ @start()+ def step_b(self):+ return "b"++ @listen(and_(step_a, step_b))+ def converge(self):+ return "converged"++ structure = flow_structure(AndConditionFlow)++ assert len(structure["methods"]) == 3++ method_map = {m["name"]: m for m in structure["methods"]}++ assert method_map["step_a"]["type"] == "start"+ assert method_map["step_b"]["type"] == "start"+ assert method_map["converge"]["type"] == "listen"++ # Check condition type+ assert method_map["converge"]["condition_type"] == "AND"++ # Check trigger methods+ triggers = method_map["converge"]["trigger_methods"]+ assert "step_a" in triggers+ assert "step_b" in triggers++ # Check edges - should have 2 edges to converge+ converge_edges = [e for e in structure["edges"] if e["to_method"] == "converge"]+ assert len(converge_edges) == 2++ def test_or_condition_flow(self):+ """Test a flow where a method is triggered by any of multiple methods (OR)."""++ class OrConditionFlow(Flow):+ @start()+ def path_1(self):+ return "1"++ @start()+ def path_2(self):+ return "2"++ @listen(or_(path_1, path_2))+ def handle_any(self):+ return "handled"++ structure = flow_structure(OrConditionFlow)++ method_map = {m["name"]: m for m in structure["methods"]}++ assert method_map["handle_any"]["condition_type"] == "OR"++ triggers = method_map["handle_any"]["trigger_methods"]+ assert "path_1" in triggers+ assert "path_2" in triggers+++class TestHumanFeedbackMethods:+ """Test flow with @human_feedback decorated methods."""++ def test_human_feedback_detection(self):+ """Test that human feedback methods are correctly identified."""++ class HumanFeedbackFlow(Flow):+ @start()+ @human_feedback(+ message="Please review:",+ emit=["approved", "rejected"],+ llm="gpt-4o-mini",+ )+ def review_step(self):+ return "content to review"++ @listen("approved")+ def handle_approved(self):+ return "approved"++ @listen("rejected")+ def handle_rejected(self):+ return "rejected"++ structure = flow_structure(HumanFeedbackFlow)++ method_map = {m["name"]: m for m in structure["methods"]}++ # review_step should have human feedback+ assert method_map["review_step"]["has_human_feedback"] is True+ # It's a start+router (due to emit)+ assert method_map["review_step"]["type"] == "start_router"+ assert "approved" in method_map["review_step"]["router_paths"]+ assert "rejected" in method_map["review_step"]["router_paths"]++ # Other methods should not have human feedback+ assert method_map["handle_approved"]["has_human_feedback"] is False+ assert method_map["handle_rejected"]["has_human_feedback"] is False+++class TestCrewReferences:+ """Test detection of Crew references in method bodies."""++ def test_crew_detection_with_crew_call(self):+ """Test that .crew() calls are detected."""++ class FlowWithCrew(Flow):+ @start()+ def run_crew(self):+ # Simulating crew usage pattern+ # result = MyCrew().crew().kickoff()+ return "result"++ @listen(run_crew)+ def no_crew(self):+ return "done"++ structure = flow_structure(FlowWithCrew)++ method_map = {m["name"]: m for m in structure["methods"]}++ # Note: Since the actual .crew() call is in a comment/string,+ # the detection might not trigger. In real code it would.+ # We're testing the mechanism exists.+ assert "has_crew" in method_map["run_crew"]+ assert "has_crew" in method_map["no_crew"]++ def test_no_crew_when_absent(self):+ """Test that methods without Crew refs return has_crew=False."""++ class SimpleNonCrewFlow(Flow):+ @start()+ def calculate(self):+ return 1 + 1++ @listen(calculate)+ def display(self):+ return "result"++ structure = flow_structure(SimpleNonCrewFlow)++ method_map = {m["name"]: m for m in structure["methods"]}++ assert method_map["calculate"]["has_crew"] is False+ assert method_map["display"]["has_crew"] is False+++class TestTypedStateSchema:+ """Test flow with typed Pydantic state."""++ def test_pydantic_state_schema_extraction(self):+ """Test extracting state schema from a Flow with Pydantic state."""++ class MyState(BaseModel):+ counter: int = 0+ message: str = ""+ items: list[str] = Field(default_factory=list)++ class TypedStateFlow(Flow[MyState]):+ initial_state = MyState++ @start()+ def increment(self):+ self.state.counter += 1+ return self.state.counter++ @listen(increment)+ def display(self):+ return f"Count: {self.state.counter}"++ structure = flow_structure(TypedStateFlow)++ assert structure["state_schema"] is not None+ fields = structure["state_schema"]["fields"]++ field_names = {f["name"] for f in fields}+ assert "counter" in field_names+ assert "message" in field_names+ assert "items" in field_names++ # Check types+ field_map = {f["name"]: f for f in fields}+ assert "int" in field_map["counter"]["type"]+ assert "str" in field_map["message"]["type"]++ # Check defaults+ assert field_map["counter"]["default"] == 0+ assert field_map["message"]["default"] == ""++ def test_dict_state_returns_none(self):+ """Test that flows using dict state return None for state_schema."""++ class DictStateFlow(Flow):+ @start()+ def begin(self):+ self.state["count"] = 1+ return "started"++ structure = flow_structure(DictStateFlow)++ assert structure["state_schema"] is None+++class TestEdgeCases:+ """Test edge cases and special scenarios."""++ def test_start_router_combo(self):+ """Test a method that is both @start and a router (via human_feedback emit)."""++ class StartRouterFlow(Flow):+ @start()+ @human_feedback(+ message="Review:",+ emit=["continue", "stop"],+ llm="gpt-4o-mini",+ )+ def entry_point(self):+ return "data"++ @listen("continue")+ def proceed(self):+ return "proceeding"++ @listen("stop")+ def halt(self):+ return "halted"++ structure = flow_structure(StartRouterFlow)++ method_map = {m["name"]: m for m in structure["methods"]}++ assert method_map["entry_point"]["type"] == "start_router"+ assert method_map["entry_point"]["has_human_feedback"] is True+ assert "continue" in method_map["entry_point"]["router_paths"]+ assert "stop" in method_map["entry_point"]["router_paths"]++ def test_multiple_start_methods(self):+ """Test a flow with multiple start methods."""++ class MultiStartFlow(Flow):+ @start()+ def start_a(self):+ return "a"++ @start()+ def start_b(self):+ return "b"++ @listen(and_(start_a, start_b))+ def combine(self):+ return "combined"++ structure = flow_structure(MultiStartFlow)++ start_methods = [m for m in structure["methods"] if m["type"] == "start"]+ assert len(start_methods) == 2++ start_names = {m["name"] for m in start_methods}+ assert "start_a" in start_names+ assert "start_b" in start_names++ def test_orphan_methods(self):+ """Test that orphan methods (not connected to flow) are still captured."""++ class FlowWithOrphan(Flow):+ @start()+ def begin(self):+ return "started"++ @listen(begin)+ def connected(self):+ return "connected"++ @listen("never_triggered")+ def orphan(self):+ return "orphan"++ structure = flow_structure(FlowWithOrphan)++ method_names = {m["name"] for m in structure["methods"]}+ assert "orphan" in method_names++ method_map = {m["name"]: m for m in structure["methods"]}+ assert method_map["orphan"]["trigger_methods"] == ["never_triggered"]++ def test_empty_flow(self):+ """Test building structure for a flow with no methods."""++ class EmptyFlow(Flow):+ pass++ structure = flow_structure(EmptyFlow)++ assert structure["name"] == "EmptyFlow"+ assert structure["methods"] == []+ assert structure["edges"] == []+ assert structure["state_schema"] is None++ def test_flow_with_docstring(self):+ """Test that flow docstring is captured."""++ class DocumentedFlow(Flow):+ """This is a well-documented flow.++ It has multiple lines of documentation.+ """++ @start()+ def begin(self):+ return "started"++ structure = flow_structure(DocumentedFlow)++ assert structure["description"] is not None+ assert "well-documented flow" in structure["description"]++ def test_flow_without_docstring(self):+ """Test that missing docstring returns None."""++ class UndocumentedFlow(Flow):+ @start()+ def begin(self):+ return "started"++ structure = flow_structure(UndocumentedFlow)++ assert structure["description"] is None++ def test_nested_conditions(self):+ """Test flow with nested AND/OR conditions."""++ class NestedConditionFlow(Flow):+ @start()+ def a(self):+ return "a"++ @start()+ def b(self):+ return "b"++ @start()+ def c(self):+ return "c"++ @listen(or_(and_(a, b), c))+ def complex_trigger(self):+ return "triggered"++ structure = flow_structure(NestedConditionFlow)++ method_map = {m["name"]: m for m in structure["methods"]}++ # Should have triggers for a, b, and c+ triggers = method_map["complex_trigger"]["trigger_methods"]+ assert len(triggers) == 3+ assert "a" in triggers+ assert "b" in triggers+ assert "c" in triggers+++class TestErrorHandling:+ """Test error handling and validation."""++ def test_instance_raises_type_error(self):+ """Test that passing an instance raises TypeError."""++ class TestFlow(Flow):+ @start()+ def begin(self):+ return "started"++ flow_instance = TestFlow()++ with pytest.raises(TypeError) as exc_info:+ flow_structure(flow_instance)++ assert "requires a Flow class, not an instance" in str(exc_info.value)++ def test_non_class_raises_type_error(self):+ """Test that passing non-class raises TypeError."""++ with pytest.raises(TypeError):+ flow_structure("not a class")++ with pytest.raises(TypeError):+ flow_structure(123)+++class TestEdgeGeneration:+ """Test edge generation in various scenarios."""++ def test_all_edges_generated_correctly(self):+ """Verify all edges are correctly generated for a complex flow."""++ class ComplexFlow(Flow):+ @start()+ def entry(self):+ return "started"++ @listen(entry)+ def step_1(self):+ return "step_1"++ @router(step_1)+ def branch(self) -> Literal["left", "right"]:+ return "left"++ @listen("left")+ def left_path(self):+ return "left_done"++ @listen("right")+ def right_path(self):+ return "right_done"++ @listen(or_(left_path, right_path))+ def converge(self):+ return "done"++ structure = flow_structure(ComplexFlow)++ # Build edge map for easier checking+ edges = structure["edges"]++ # Check listen edges+ listen_edges = [(e["from_method"], e["to_method"]) for e in edges if e["edge_type"] == "listen"]++ assert ("entry", "step_1") in listen_edges+ assert ("step_1", "branch") in listen_edges+ assert ("left_path", "converge") in listen_edges+ assert ("right_path", "converge") in listen_edges++ # Check route edges+ route_edges = [(e["from_method"], e["to_method"], e["condition"]) for e in edges if e["edge_type"] == "route"]++ assert ("branch", "left_path", "left") in route_edges+ assert ("branch", "right_path", "right") in route_edges++ def test_router_edge_conditions(self):+ """Test that router edge conditions are properly set."""++ class RouterConditionFlow(Flow):+ @start()+ def begin(self):+ return "start"++ @router(begin)+ def route(self) -> Literal["option_1", "option_2", "option_3"]:+ return "option_1"++ @listen("option_1")+ def handle_1(self):+ return "1"++ @listen("option_2")+ def handle_2(self):+ return "2"++ @listen("option_3")+ def handle_3(self):+ return "3"++ structure = flow_structure(RouterConditionFlow)++ route_edges = [e for e in structure["edges"] if e["edge_type"] == "route"]++ # Should have 3 route edges+ assert len(route_edges) == 3++ conditions = {e["to_method"]: e["condition"] for e in route_edges}+ assert conditions["handle_1"] == "option_1"+ assert conditions["handle_2"] == "option_2"+ assert conditions["handle_3"] == "option_3"+++class TestMethodTypeClassification:+ """Test method type classification."""++ def test_all_method_types(self):+ """Test classification of all method types."""++ class AllTypesFlow(Flow):+ @start()+ def start_only(self):+ return "start"++ @listen(start_only)+ def listen_only(self):+ return "listen"++ @router(listen_only)+ def router_only(self) -> Literal["path"]:+ return "path"++ @listen("path")+ def after_router(self):+ return "after"++ @start()+ @human_feedback(+ message="Review",+ emit=["yes", "no"],+ llm="gpt-4o-mini",+ )+ def start_and_router(self):+ return "data"++ structure = flow_structure(AllTypesFlow)++ method_map = {m["name"]: m for m in structure["methods"]}++ assert method_map["start_only"]["type"] == "start"+ assert method_map["listen_only"]["type"] == "listen"+ assert method_map["router_only"]["type"] == "router"+ assert method_map["after_router"]["type"] == "listen"+ assert method_map["start_and_router"]["type"] == "start_router"+++class TestInputDetection:+ """Test flow input detection."""++ def test_inputs_list_exists(self):+ """Test that inputs list is always present."""++ class SimpleFlow(Flow):+ @start()+ def begin(self):+ return "started"++ structure = flow_structure(SimpleFlow)++ assert "inputs" in structure+ assert isinstance(structure["inputs"], list)+++class TestJsonSerializable:+ """Test that output is JSON serializable."""++ def test_structure_is_json_serializable(self):+ """Test that the entire structure can be JSON serialized."""+ import json++ class MyState(BaseModel):+ value: int = 0++ class SerializableFlow(Flow[MyState]):+ """Test flow for JSON serialization."""++ initial_state = MyState++ @start()+ @human_feedback(+ message="Review",+ emit=["ok", "not_ok"],+ llm="gpt-4o-mini",+ )+ def begin(self):+ return "data"++ @listen("ok")+ def proceed(self):+ return "done"++ structure = flow_structure(SerializableFlow)++ # Should not raise+ json_str = json.dumps(structure)+ assert json_str is not None++ # Should round-trip+ parsed = json.loads(json_str)+ assert parsed["name"] == "SerializableFlow"+ assert len(parsed["methods"]) > 0+++class TestFlowInheritance:+ """Test flow inheritance scenarios."""++ def test_child_flow_inherits_parent_methods(self):+ """Test that FlowB inheriting from FlowA includes methods from both.++ Note: FlowMeta propagates methods but does NOT fully propagate the+ _listeners registry from parent classes. This means edges defined+ in the parent class (e.g., parent_start -> parent_process) may not+ appear in the child's structure. This is a known FlowMeta limitation.+ """++ class FlowA(Flow):+ """Parent flow with start method."""++ @start()+ def parent_start(self):+ return "parent started"++ @listen(parent_start)+ def parent_process(self):+ return "parent processed"++ class FlowB(FlowA):+ """Child flow with additional methods."""++ @listen(FlowA.parent_process)+ def child_continue(self):+ return "child continued"++ @listen(child_continue)+ def child_finalize(self):+ return "child finalized"++ structure = flow_structure(FlowB)++ assert structure["name"] == "FlowB"++ # Check all methods are present (from both parent and child)+ method_names = {m["name"] for m in structure["methods"]}+ assert "parent_start" in method_names+ assert "parent_process" in method_names+ assert "child_continue" in method_names+ assert "child_finalize" in method_names++ # Check method types+ method_map = {m["name"]: m for m in structure["methods"]}+ assert method_map["parent_start"]["type"] == "start"+ assert method_map["parent_process"]["type"] == "listen"+ assert method_map["child_continue"]["type"] == "listen"+ assert method_map["child_finalize"]["type"] == "listen"++ # Check edges defined in child class exist+ edge_pairs = [(e["from_method"], e["to_method"]) for e in structure["edges"]]+ assert ("parent_process", "child_continue") in edge_pairs+ assert ("child_continue", "child_finalize") in edge_pairs++ # KNOWN LIMITATION: Edges defined in parent class (parent_start -> parent_process)+ # are NOT propagated to child's _listeners registry by FlowMeta.+ # The edge (parent_start, parent_process) will NOT be in edge_pairs.+ # This is a FlowMeta limitation, not a serializer bug.++ def test_child_flow_can_override_parent_method(self):+ """Test that child can override parent methods."""++ class BaseFlow(Flow):+ @start()+ def begin(self):+ return "base begin"++ @listen(begin)+ def process(self):+ return "base process"++ class ExtendedFlow(BaseFlow):+ @listen(BaseFlow.begin)+ def process(self):+ # Override parent's process method+ return "extended process"++ @listen(process)+ def finalize(self):+ return "extended finalize"++ structure = flow_structure(ExtendedFlow)++ method_names = {m["name"] for m in structure["methods"]}+ assert "begin" in method_names+ assert "process" in method_names+ assert "finalize" in method_names++ # Should have 3 methods total (not 4, since process is overridden)+ assert len(structure["methods"]) == 3