Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
Build FlowDefinition from Flow DSL metadata (#6017)
Vini Brasil051fa0c1cb7c
diff --git a/lib/crewai/src/crewai/flow/__init__.py b/lib/crewai/src/crewai/flow/__init__.pyindex 7142403ad..2475dd226 100644--- a/lib/crewai/src/crewai/flow/__init__.py+++ b/lib/crewai/src/crewai/flow/__init__.py@@ -11,7 +11,6 @@ from crewai.flow.conversation 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@@ -38,7 +37,6 @@ __all__ = ["and_","build_flow_structure","flow_config",- "flow_structure","human_feedback","listen","or_",diff --git a/lib/crewai/src/crewai/flow/dsl.py b/lib/crewai/src/crewai/flow/dsl.pyindex 3181acd50..353d8f187 100644--- a/lib/crewai/src/crewai/flow/dsl.py+++ b/lib/crewai/src/crewai/flow/dsl.py@@ -1,36 +1,342 @@-"""Flow authoring DSL: the ``@start`` / ``@listen`` / ``@router`` decorators-plus the ``or_`` / ``and_`` condition combinators.+"""Flow DSL: the Python authoring layer for Flows.-These decorators wrap user methods into the typed wrappers defined in-``flow_wrappers`` and record their trigger conditions. The structural model-those conditions feed is built in ``flow_definition``; execution happens in-``runtime``.+Provides the ``@start`` / ``@listen`` / ``@router`` decorators and the+``or_`` / ``and_`` condition combinators used to write Flow classes in+Python. The DSL is one way to produce a Flow Structure: this module+extracts a :class:`~crewai.flow.flow_definition.FlowDefinition` from a+Python Flow class. Execution is handled by ``runtime``."""from __future__ import annotations-from collections.abc import Callable-from typing import Any, ParamSpec, TypeVar+from collections.abc import Callable, Sequence+from enum import Enum+import inspect+import json+import logging+from types import UnionType+from typing import (+ Any,+ Literal,+ ParamSpec,+ TypeVar,+ Union,+ get_args,+ get_origin,+ get_type_hints,+)++from pydantic import BaseModel+from typing_extensions import TypeIsfrom crewai.flow.constants import AND_CONDITION, OR_CONDITIONfrom crewai.flow.flow_definition import (- _extract_all_methods,- is_flow_condition_dict,- is_flow_method_callable,- is_flow_method_name,+ FlowConfigDefinition,+ FlowDefinition,+ FlowDefinitionCondition,+ FlowDefinitionDiagnostic,+ FlowHumanFeedbackDefinition,+ FlowMethodDefinition,+ FlowPersistenceDefinition,+ FlowStateDefinition,)from crewai.flow.flow_wrappers import (FlowCondition,FlowConditions,+ FlowMethod,ListenMethod,RouterMethod,+ SimpleFlowCondition,StartMethod,)+from crewai.flow.types import FlowMethodNameP = ParamSpec("P")R = TypeVar("R")+logger = logging.getLogger(__name__)++__all__ = ["and_", "listen", "or_", "router", "start"]++_FLOW_METHOD_DEFINITION_ATTR = "__flow_method_definition__"+++def is_simple_flow_condition(obj: Any) -> TypeIs[SimpleFlowCondition]:+ """Check if the object is a ``(condition_type, methods)`` tuple."""+ return (+ isinstance(obj, tuple)+ and len(obj) == 2+ and isinstance(obj[0], str)+ and isinstance(obj[1], list)+ )+++def is_flow_method(obj: Any) -> TypeIs[FlowMethod[Any, Any]]:+ """Check if the object carries Flow method wrapper metadata."""+ return (+ hasattr(obj, "__is_flow_method__")+ or hasattr(obj, "__is_start_method__")+ or hasattr(obj, "__trigger_methods__")+ or hasattr(obj, "__is_router__")+ or hasattr(obj, _FLOW_METHOD_DEFINITION_ATTR)+ )+++def _should_include_flow_method(flow_class: type, method: Any) -> bool:+ if getattr(method, "__conversational_only__", False):+ return bool(getattr(flow_class, "conversational", False))+ return True+++def is_flow_condition_dict(obj: Any) -> TypeIs[FlowCondition]:+ """Check if the object matches the FlowCondition structure."""+ if not isinstance(obj, dict):+ return False++ type_value = obj.get("type")+ if type_value not in ("AND", "OR"):+ return False++ if "conditions" in obj:+ conditions = obj["conditions"]+ if not isinstance(conditions, list):+ return False+ for cond in conditions:+ if not (+ isinstance(cond, str)+ or (isinstance(cond, dict) and is_flow_condition_dict(cond))+ ):+ return False++ if "methods" in obj:+ methods = obj["methods"]+ if not (isinstance(methods, list) and all(isinstance(m, str) for m in methods)):+ return False++ allowed_keys = {"type", "conditions", "methods"}+ if not set(obj).issubset(allowed_keys):+ return False++ return True+++def _method_reference_name(value: Any) -> FlowMethodName | None:+ name = getattr(value, "__name__", None)+ if callable(value) and isinstance(name, str):+ return FlowMethodName(name)+ return None+++def _flow_method_names(values: Sequence[Any]) -> list[FlowMethodName]:+ return [FlowMethodName(str(value)) for value in values]+++def _extract_all_methods_recursive(+ condition: str | FlowCondition | dict[str, Any] | list[Any],+ flow: Any | None = None,+) -> list[FlowMethodName]:+ if isinstance(condition, str):+ if flow is not None:+ if condition in flow._methods:+ return [FlowMethodName(condition)]+ return []+ return [FlowMethodName(condition)]+ if is_flow_condition_dict(condition):+ normalized = _normalize_condition(condition)+ methods = []+ for sub_cond in normalized.get("conditions", []):+ methods.extend(_extract_all_methods_recursive(sub_cond, flow))+ return methods+ if isinstance(condition, list):+ methods = []+ for item in condition:+ methods.extend(_extract_all_methods_recursive(item, flow))+ return methods+ return []+++def _normalize_condition(+ condition: FlowConditions | FlowCondition | str,+) -> FlowCondition:+ if isinstance(condition, str):+ return {"type": OR_CONDITION, "conditions": [FlowMethodName(condition)]}+ if is_flow_condition_dict(condition):+ if "conditions" in condition:+ return condition+ if "methods" in condition:+ return {"type": condition["type"], "conditions": condition["methods"]}+ return condition+ if isinstance(condition, list) and all(+ isinstance(item, str) or is_flow_condition_dict(item) for item in condition+ ):+ return {"type": OR_CONDITION, "conditions": condition}++ raise ValueError(f"Cannot normalize condition: {condition}")+++def _extract_all_methods(+ condition: str | FlowCondition | dict[str, Any] | list[Any],+) -> list[FlowMethodName]:+ if isinstance(condition, str):+ return [FlowMethodName(condition)]+ if is_flow_condition_dict(condition):+ normalized = _normalize_condition(condition)+ cond_type = normalized.get("type", OR_CONDITION)++ if cond_type == AND_CONDITION:+ return [+ FlowMethodName(sub_cond)+ for sub_cond in normalized.get("conditions", [])+ if isinstance(sub_cond, str)+ ]+ return []+ if isinstance(condition, list):+ methods = []+ for item in condition:+ methods.extend(_extract_all_methods(item))+ return methods+ return []+++def _unwrap_function(function: Any) -> Any:+ if hasattr(function, "__func__"):+ function = function.__func__++ if hasattr(function, "__wrapped__"):+ wrapped = function.__wrapped__+ if hasattr(wrapped, "unwrap"):+ return wrapped.unwrap()+ return wrapped++ if hasattr(function, "unwrap"):+ return function.unwrap()++ return function+++def _string_values_from_annotation(annotation: Any) -> list[str]:+ if annotation is inspect.Signature.empty or isinstance(annotation, str):+ return []+ if isinstance(annotation, type) and issubclass(annotation, Enum):+ return [member.value for member in annotation if isinstance(member.value, str)]++ origin = get_origin(annotation)+ if origin is None:+ return []++ args = get_args(annotation)+ if origin is Literal or getattr(origin, "__name__", "") == "Literal":+ return [arg for arg in args if isinstance(arg, str)]++ if not (+ origin is Union+ or origin is UnionType+ or getattr(origin, "__name__", "") == "Annotated"+ ):+ return []++ values: list[str] = []+ for arg in args:+ values.extend(_string_values_from_annotation(arg))+ return values+++def _return_annotation(function: Any) -> Any:+ unwrapped = _unwrap_function(function)++ try:+ return get_type_hints(unwrapped, include_extras=True).get(+ "return", inspect.Signature.empty+ )+ except (NameError, TypeError, ValueError):+ try:+ return inspect.signature(unwrapped).return_annotation+ except (TypeError, ValueError):+ return inspect.Signature.empty+++def _get_router_return_events(function: Any) -> list[str] | None:+ values = _string_values_from_annotation(_return_annotation(function))+ return list(dict.fromkeys(values)) if values else None+++def _normalize_router_emit(value: Sequence[Any] | str) -> list[str]:+ if isinstance(value, str):+ return [str(value)]+ return list(dict.fromkeys(str(item) for item in value))+++def _set_trigger_metadata(+ wrapper: StartMethod[P, R] | ListenMethod[P, R] | RouterMethod[P, R],+ condition: str | FlowCondition | Callable[..., Any],+) -> None:+ if isinstance(condition, str):+ wrapper.__trigger_methods__ = [FlowMethodName(condition)]+ wrapper.__condition_type__ = OR_CONDITION+ return++ if is_flow_condition_dict(condition):+ if "conditions" in condition:+ wrapper.__trigger_condition__ = condition+ wrapper.__trigger_methods__ = _extract_all_methods(condition)+ wrapper.__condition_type__ = condition["type"]+ return+ if "methods" in condition:+ wrapper.__trigger_methods__ = _flow_method_names(condition["methods"])+ wrapper.__condition_type__ = condition["type"]+ return+ raise ValueError("Condition dict must contain 'conditions' or 'methods'")++ method_name = _method_reference_name(condition)+ if method_name is not None:+ wrapper.__trigger_methods__ = [method_name]+ wrapper.__condition_type__ = OR_CONDITION+ return++ raise ValueError(+ "Condition must be a method, string, or a result of or_() or and_()"+ )+++def _condition_trigger(+ condition: str | FlowCondition | Callable[..., Any],+) -> FlowMethodName | FlowCondition:+ if isinstance(condition, str):+ return FlowMethodName(condition)+ if is_flow_condition_dict(condition):+ return condition+ method_name = _method_reference_name(condition)+ if method_name is not None:+ return method_name+ raise ValueError("Invalid condition")+++def _condition_triggers(+ conditions: Sequence[str | FlowCondition | Callable[..., Any]],+ error_message: str,+) -> FlowConditions:+ try:+ return [_condition_trigger(condition) for condition in conditions]+ except ValueError as exc:+ raise ValueError(error_message) from exc+++def _set_flow_method_definition(+ wrapper: StartMethod[P, R] | ListenMethod[P, R] | RouterMethod[P, R],+ definition: FlowMethodDefinition,+) -> None:+ setattr(wrapper, _FLOW_METHOD_DEFINITION_ATTR, definition)+++def _get_flow_method_definition(method: Any) -> FlowMethodDefinition | None:+ definition = getattr(method, _FLOW_METHOD_DEFINITION_ATTR, None)+ if isinstance(definition, FlowMethodDefinition):+ return definition+ if definition is not None:+ return FlowMethodDefinition.model_validate(definition)+ return None+def start(condition: str | FlowCondition | Callable[..., Any] | None = None,@@ -69,39 +375,18 @@ def start("""def decorator(func: Callable[P, R]) -> StartMethod[P, R]:- """Decorator that wraps a function as a start method.-- Args:- func: The function to wrap as a start method.-- Returns:- A StartMethod wrapper around the function.- """wrapper = StartMethod(func)if condition is not None:- if is_flow_method_name(condition):- wrapper.__trigger_methods__ = [condition]- wrapper.__condition_type__ = OR_CONDITION- elif is_flow_condition_dict(condition):- if "conditions" in condition:- wrapper.__trigger_condition__ = condition- wrapper.__trigger_methods__ = _extract_all_methods(condition)- wrapper.__condition_type__ = condition["type"]- elif "methods" in condition:- wrapper.__trigger_methods__ = condition["methods"]- wrapper.__condition_type__ = condition["type"]- else:- raise ValueError(- "Condition dict must contain 'conditions' or 'methods'"- )- elif is_flow_method_callable(condition):- wrapper.__trigger_methods__ = [condition.__name__]- wrapper.__condition_type__ = OR_CONDITION- else:- raise ValueError(- "Condition must be a method, string, or a result of or_() or and_()"- )+ _set_flow_method_definition(+ wrapper,+ FlowMethodDefinition(+ start=_definition_condition_from_runtime(condition)+ ),+ )+ _set_trigger_metadata(wrapper, condition)+ else:+ _set_flow_method_definition(wrapper, FlowMethodDefinition(start=True))return wrapperreturn decorator@@ -136,38 +421,13 @@ def listen("""def decorator(func: Callable[P, R]) -> ListenMethod[P, R]:- """Decorator that wraps a function as a listener method.-- Args:- func: The function to wrap as a listener method.-- Returns:- A ListenMethod wrapper around the function.- """wrapper = ListenMethod(func)- if is_flow_method_name(condition):- wrapper.__trigger_methods__ = [condition]- wrapper.__condition_type__ = OR_CONDITION- elif is_flow_condition_dict(condition):- if "conditions" in condition:- wrapper.__trigger_condition__ = condition- wrapper.__trigger_methods__ = _extract_all_methods(condition)- wrapper.__condition_type__ = condition["type"]- elif "methods" in condition:- wrapper.__trigger_methods__ = condition["methods"]- wrapper.__condition_type__ = condition["type"]- else:- raise ValueError(- "Condition dict must contain 'conditions' or 'methods'"- )- elif is_flow_method_callable(condition):- wrapper.__trigger_methods__ = [condition.__name__]- wrapper.__condition_type__ = OR_CONDITION- else:- raise ValueError(- "Condition must be a method, string, or a result of or_() or and_()"- )+ _set_flow_method_definition(+ wrapper,+ FlowMethodDefinition(listen=_definition_condition_from_runtime(condition)),+ )+ _set_trigger_metadata(wrapper, condition)return wrapperreturn decorator@@ -175,19 +435,23 @@ def listen(def router(condition: str | FlowCondition | Callable[..., Any],+ *,+ emit: Sequence[str] | str | None = None,) -> Callable[[Callable[P, R]], RouterMethod[P, R]]:"""Creates a routing method that directs flow execution based on conditions.This decorator marks a method as a router, which can dynamically determinethe next steps in the flow based on its return value. Routers are triggered- by specified conditions and can return constants that determine which path- the flow should take.+ by specified conditions and can return constants that emit downstream events.Args:condition: Specifies when the router should execute. Can be:- str: Name of a method that triggers this router- FlowCondition: Result from or_() or and_(), including nested conditions- Callable[..., Any]: A method reference that triggers this router+ emit: Optional explicit router output events for static FlowDefinition+ and visualization. If omitted, Literal/Enum return annotations are+ used when available.Returns:A decorator function that wraps the method as a router and preserves its signature.@@ -207,41 +471,35 @@ def router(... if all([self.state.valid, self.state.processed]):... return "CONTINUE"... return "STOP"++ >>> @router("check_status", emit=["SUCCESS", "FAILURE"])+ >>> def explicit_routing(self):+ ... return "SUCCESS""""def decorator(func: Callable[P, R]) -> RouterMethod[P, R]:- """Decorator that wraps a function as a router method.-- Args:- func: The function to wrap as a router method.-- Returns:- A RouterMethod wrapper around the function.- """wrapper = RouterMethod(func)- if is_flow_method_name(condition):- wrapper.__trigger_methods__ = [condition]- wrapper.__condition_type__ = OR_CONDITION- elif is_flow_condition_dict(condition):- if "conditions" in condition:- wrapper.__trigger_condition__ = condition- wrapper.__trigger_methods__ = _extract_all_methods(condition)- wrapper.__condition_type__ = condition["type"]- elif "methods" in condition:- wrapper.__trigger_methods__ = condition["methods"]- wrapper.__condition_type__ = condition["type"]- else:- raise ValueError(- "Condition dict must contain 'conditions' or 'methods'"- )- elif is_flow_method_callable(condition):- wrapper.__trigger_methods__ = [condition.__name__]- wrapper.__condition_type__ = OR_CONDITION+ if emit is not None:+ router_events = _normalize_router_emit(emit)else:- raise ValueError(- "Condition must be a method, string, or a result of or_() or and_()"- )+ router_events = _get_router_return_events(func) or []++ _set_flow_method_definition(+ wrapper,+ FlowMethodDefinition(+ listen=_definition_condition_from_runtime(condition),+ router=True,+ emit=router_events or None,+ ),+ )++ _set_trigger_metadata(wrapper, condition)++ if emit is not None:+ wrapper.__router_emit__ = router_events+ elif router_events:+ wrapper.__router_emit__ = router_eventsreturn wrapperreturn decorator@@ -272,15 +530,8 @@ def or_(*conditions: str | FlowCondition | Callable[..., Any]) -> FlowCondition:>>> def handle_nested(self):... pass"""- processed_conditions: FlowConditions = []- for condition in conditions:- if is_flow_condition_dict(condition) or is_flow_method_name(condition):- processed_conditions.append(condition)- elif is_flow_method_callable(condition):- processed_conditions.append(condition.__name__)- else:- raise ValueError("Invalid condition in or_()")- return {"type": OR_CONDITION, "conditions": processed_conditions}+ processed_triggers = _condition_triggers(conditions, "Invalid condition in or_()")+ return {"type": OR_CONDITION, "conditions": processed_triggers}def and_(*conditions: str | FlowCondition | Callable[..., Any]) -> FlowCondition:@@ -309,12 +560,474 @@ def and_(*conditions: str | FlowCondition | Callable[..., Any]) -> FlowCondition>>> def handle_nested(self):... pass"""- processed_conditions: FlowConditions = []- for condition in conditions:- if is_flow_condition_dict(condition) or is_flow_method_name(condition):- processed_conditions.append(condition)- elif is_flow_method_callable(condition):- processed_conditions.append(condition.__name__)- else:- raise ValueError("Invalid condition in and_()")- return {"type": AND_CONDITION, "conditions": processed_conditions}+ processed_triggers = _condition_triggers(conditions, "Invalid condition in and_()")+ return {"type": AND_CONDITION, "conditions": processed_triggers}+++def _object_ref(value: Any) -> str:+ target = value if isinstance(value, type) else type(value)+ module = getattr(target, "__module__", "")+ qualname = getattr(target, "__qualname__", getattr(target, "__name__", ""))+ return f"{module}:{qualname}" if module and qualname else repr(value)+++def _is_json_serializable(value: Any) -> bool:+ try:+ json.dumps(value)+ except (TypeError, ValueError):+ return False+ return True+++def _serialize_static_value(+ value: Any,+ diagnostics: list[FlowDefinitionDiagnostic],+ path: str,+) -> Any:+ if value is None or _is_json_serializable(value):+ return value++ to_config = getattr(value, "to_config_dict", None)+ if callable(to_config):+ try:+ config = to_config()+ if _is_json_serializable(config):+ return config+ except Exception:+ logger.debug(+ "Failed to serialize %s via to_config_dict().",+ path,+ exc_info=True,+ )++ if isinstance(value, BaseModel):+ try:+ data = value.model_dump(mode="json")+ if _is_json_serializable(data):+ return data+ except Exception:+ logger.debug(+ "Failed to serialize %s via Pydantic model_dump().",+ path,+ exc_info=True,+ )++ ref = _object_ref(value)+ diagnostics.append(+ FlowDefinitionDiagnostic(+ code="non_serializable_value",+ path=path,+ message=f"value is not fully serializable; preserved import reference {ref}",+ )+ )+ return {"ref": ref}+++def _state_ref(value: Any) -> str | None:+ if value is None:+ return None+ target = value if isinstance(value, type) else type(value)+ module = getattr(target, "__module__", None)+ qualname = getattr(target, "__qualname__", None)+ if module and qualname:+ return f"{module}:{qualname}"+ return None+++def _build_state_definition(+ flow_class: type,+ diagnostics: list[FlowDefinitionDiagnostic],+) -> FlowStateDefinition | None:+ from pydantic import BaseModel as PydanticBaseModel++ state_value = getattr(flow_class, "_initial_state_t", None)+ initial_state = getattr(flow_class, "initial_state", None)+ if initial_state is not None:+ state_value = initial_state++ if state_value is None:+ return None+ if state_value is dict or isinstance(state_value, dict):+ default = None+ if isinstance(state_value, dict):+ default = _serialize_static_value(state_value, diagnostics, "state.default")+ return FlowStateDefinition(type="dict", default=default)+ if isinstance(state_value, type) and issubclass(state_value, PydanticBaseModel):+ return FlowStateDefinition(type="pydantic", ref=_state_ref(state_value))+ if isinstance(state_value, PydanticBaseModel):+ return FlowStateDefinition(+ type="pydantic",+ ref=_state_ref(state_value),+ default=_serialize_static_value(state_value, diagnostics, "state.default"),+ )+ diagnostics.append(+ FlowDefinitionDiagnostic(+ code="unknown_state_type",+ path="state",+ message=f"could not serialize state type {_object_ref(state_value)}",+ )+ )+ return FlowStateDefinition(type="unknown", ref=_state_ref(state_value))+++def _build_config_definition(+ flow_class: type,+ diagnostics: list[FlowDefinitionDiagnostic],+) -> FlowConfigDefinition:+ config_field_names = set(FlowConfigDefinition.model_fields)+ field_defaults = {+ name: field.default+ for name, field in getattr(flow_class, "model_fields", {}).items()+ if name in config_field_names+ }+ values: dict[str, Any] = {}+ for field_name, default in field_defaults.items():+ value = getattr(flow_class, field_name, default)+ values[field_name] = _serialize_static_value(+ value, diagnostics, f"config.{field_name}"+ )+ return FlowConfigDefinition(**values)+++def _definition_condition_from_runtime(condition: Any) -> FlowDefinitionCondition:+ if isinstance(condition, str):+ return str(condition)+ method_name = _method_reference_name(condition)+ if method_name is not None:+ return str(method_name)+ if is_flow_condition_dict(condition):+ normalized = _normalize_condition(condition)+ key = "and" if normalized.get("type") == AND_CONDITION else "or"+ return {+ key: [+ _definition_condition_from_runtime(sub_condition)+ for sub_condition in normalized.get("conditions", [])+ ]+ }+ if isinstance(condition, list):+ return {"or": [_definition_condition_from_runtime(item) for item in condition]}+ return str(condition)+++def _condition_from_method_metadata(method: Any) -> FlowDefinitionCondition | None:+ trigger_condition = getattr(method, "__trigger_condition__", None)+ if trigger_condition is not None:+ return _definition_condition_from_runtime(trigger_condition)++ trigger_methods = getattr(method, "__trigger_methods__", None)+ if trigger_methods is None:+ return None+ condition_type = getattr(method, "__condition_type__", OR_CONDITION)+ method_names = [str(method_name) for method_name in trigger_methods]+ if condition_type == AND_CONDITION:+ return {"and": method_names}+ if len(method_names) == 1:+ return method_names[0]+ return {"or": method_names}+++def _flow_method_definition_from_legacy_metadata(method: Any) -> FlowMethodDefinition:+ is_start = bool(getattr(method, "__is_start_method__", False))+ is_router = bool(getattr(method, "__is_router__", False))+ condition = _condition_from_method_metadata(method)++ if not is_start:+ start_value: bool | FlowDefinitionCondition | None = None+ elif condition is not None:+ start_value = condition+ else:+ start_value = True++ definition = FlowMethodDefinition(+ start=start_value,+ listen=condition if not is_start else None,+ router=is_router,+ )++ router_emit = getattr(method, "__router_emit__", None)+ if router_emit:+ definition.emit = [str(value) for value in router_emit]+ return definition+++def _definition_trigger_condition(+ method_definition: FlowMethodDefinition,+) -> FlowDefinitionCondition | None:+ if method_definition.listen is not None:+ return method_definition.listen+ if isinstance(method_definition.start, (str, dict)):+ return method_definition.start+ return None+++def _runtime_condition_from_definition(+ condition: FlowDefinitionCondition,+) -> FlowMethodName | FlowCondition:+ if isinstance(condition, str):+ return FlowMethodName(condition)+ if is_flow_condition_dict(condition):+ return condition++ if "and" in condition:+ return {+ "type": AND_CONDITION,+ "conditions": [+ _runtime_condition_from_definition(item)+ for item in condition.get("and", [])+ ],+ }+ return {+ "type": OR_CONDITION,+ "conditions": [+ _runtime_condition_from_definition(item) for item in condition.get("or", [])+ ],+ }+++def _runtime_listener_condition_from_definition(+ condition: FlowDefinitionCondition,+) -> SimpleFlowCondition | FlowCondition:+ runtime_condition = _runtime_condition_from_definition(condition)+ if isinstance(runtime_condition, str):+ return (OR_CONDITION, [FlowMethodName(str(runtime_condition))])+ return runtime_condition+++def _build_human_feedback_definition(+ method: Any,+ diagnostics: list[FlowDefinitionDiagnostic],+ path: str,+) -> FlowHumanFeedbackDefinition | None:+ config = getattr(method, "__human_feedback_config__", None)+ if config is None:+ return None+ emit = getattr(config, "emit", None)+ return FlowHumanFeedbackDefinition(+ message=str(config.message),+ emit=[str(value) for value in emit] if emit is not None else None,+ llm=_serialize_static_value(+ getattr(config, "llm", None), diagnostics, f"{path}.llm"+ ),+ default_outcome=getattr(config, "default_outcome", None),+ metadata=_serialize_static_value(+ getattr(config, "metadata", None), diagnostics, f"{path}.metadata"+ ),+ provider=_serialize_static_value(+ getattr(config, "provider", None), diagnostics, f"{path}.provider"+ ),+ learn=bool(getattr(config, "learn", False)),+ learn_source=str(getattr(config, "learn_source", "hitl")),+ learn_strict=bool(getattr(config, "learn_strict", False)),+ )+++def _build_persistence_definition(+ value: Any,+ diagnostics: list[FlowDefinitionDiagnostic],+ path: str,+) -> FlowPersistenceDefinition | None:+ config = getattr(value, "__flow_persistence_config__", None)+ if config is None:+ return None+ persistence = getattr(config, "persistence", None)+ verbose = bool(getattr(config, "verbose", False))+ return FlowPersistenceDefinition(+ enabled=True,+ verbose=verbose,+ persistence=_serialize_static_value(+ persistence, diagnostics, f"{path}.persistence"+ ),+ )+++def _build_method_definition(+ method: Any,+ diagnostics: list[FlowDefinitionDiagnostic],+ path: str,+) -> FlowMethodDefinition:+ fragment = _get_flow_method_definition(method)+ if fragment is None:+ method_definition = _flow_method_definition_from_legacy_metadata(method)+ else:+ method_definition = fragment.model_copy(deep=True)++ if bool(getattr(method, "__is_router__", False)):+ method_definition.router = True++ human_feedback = _build_human_feedback_definition(+ method, diagnostics, f"{path}.human_feedback"+ )+ if human_feedback is not None:+ method_definition.human_feedback = human_feedback+ if human_feedback.emit:+ method_definition.router = True+ method_definition.emit = None++ method_definition.persist = _build_persistence_definition(+ method, diagnostics, f"{path}.persist"+ )++ router_emit = getattr(method, "__router_emit__", None)+ if router_emit and not (human_feedback and human_feedback.emit):+ if not method_definition.emit:+ method_definition.emit = [str(value) for value in router_emit]++ return method_definition+++def _iter_flow_methods(flow_class: type) -> dict[str, Any]:+ methods: dict[str, Any] = {}+ for attr_name in dir(flow_class):+ if attr_name.startswith("_"):+ continue+ try:+ attr_value = getattr(flow_class, attr_name)+ except AttributeError:+ continue+ if is_flow_method(attr_value) and _should_include_flow_method(+ flow_class, attr_value+ ):+ methods[attr_name] = attr_value++ # A wrapped method whose name collides with a base Flow model field+ # (e.g. ``checkpoint``) is absorbed by Pydantic as a field; the underlying+ # function is preserved as the field default. Recover those so the+ # definition still reflects every method once the class is built.+ for field_name, field in getattr(flow_class, "model_fields", {}).items():+ if field_name in methods or field_name.startswith("_"):+ continue+ default = getattr(field, "default", None)+ if is_flow_method(default) and _should_include_flow_method(flow_class, default):+ methods[field_name] = default+ return methods+++def _build_flow_definition_from_class(+ flow_class: type,+ namespace: dict[str, Any] | None = None,+) -> FlowDefinition:+ diagnostics: list[FlowDefinitionDiagnostic] = []+ methods: dict[str, FlowMethodDefinition] = {}+ flow_methods = _iter_flow_methods(flow_class)+ if namespace is not None:+ for attr_name, attr_value in namespace.items():+ if is_flow_method(attr_value) and _should_include_flow_method(+ flow_class, attr_value+ ):+ flow_methods[attr_name] = attr_value++ for method_name, method in flow_methods.items():+ methods[method_name] = _build_method_definition(+ method, diagnostics, f"methods.{method_name}"+ )++ description = None+ docstring = flow_class.__doc__+ if docstring:+ description = docstring.strip()++ definition = FlowDefinition(+ name=getattr(flow_class, "__name__", "Flow"),+ description=description,+ state=_build_state_definition(flow_class, diagnostics),+ config=_build_config_definition(flow_class, diagnostics),+ persist=_build_persistence_definition(flow_class, diagnostics, "persist"),+ methods=methods,+ diagnostics=diagnostics,+ )+ definition.diagnostics.extend(definition.validate_contract())+ definition.log_diagnostics()+ return definition+++def build_flow_definition(+ flow_class: type,+ namespace: dict[str, Any] | None = None,+) -> FlowDefinition:+ """Build a FlowDefinition from a Python Flow class."""+ return _build_flow_definition_from_class(flow_class, namespace)+++def extract_flow_definition(+ namespace: dict[str, Any],+) -> tuple[list[str], dict[str, Any], set[str], dict[str, Any]]:+ """Extract the structural flow registries from a Python class namespace."""+ start_methods = []+ listeners = {}+ router_emit = {}+ routers = set()++ for attr_name, attr_value in namespace.items():+ if is_flow_method(attr_value):+ method_definition = _get_flow_method_definition(attr_value)+ if method_definition is not None:+ if method_definition.is_start:+ start_methods.append(attr_name)++ condition = _definition_trigger_condition(method_definition)+ if condition is not None:+ listeners[attr_name] = _runtime_listener_condition_from_definition(+ condition+ )++ is_router = method_definition.router or bool(+ getattr(attr_value, "__is_router__", False)+ )+ if is_router:+ routers.add(attr_name)+ if method_definition.emit:+ router_emit[attr_name] = [+ str(value) for value in method_definition.emit+ ]+ elif (+ hasattr(attr_value, "__router_emit__")+ and attr_value.__router_emit__+ ):+ router_emit[attr_name] = attr_value.__router_emit__+ else:+ router_emit[attr_name] = []+ continue++ if hasattr(attr_value, "__is_start_method__"):+ start_methods.append(attr_name)++ if (+ hasattr(attr_value, "__trigger_methods__")+ and attr_value.__trigger_methods__ is not None+ ):+ methods = attr_value.__trigger_methods__+ condition_type = getattr(attr_value, "__condition_type__", OR_CONDITION)++ if (+ hasattr(attr_value, "__trigger_condition__")+ and attr_value.__trigger_condition__ is not None+ ):+ listeners[attr_name] = attr_value.__trigger_condition__+ else:+ listeners[attr_name] = (condition_type, methods)++ if hasattr(attr_value, "__is_router__") and attr_value.__is_router__:+ routers.add(attr_name)+ if (+ hasattr(attr_value, "__router_emit__")+ and attr_value.__router_emit__+ ):+ router_emit[attr_name] = attr_value.__router_emit__+ else:+ router_emit[attr_name] = []++ if (+ hasattr(attr_value, "__is_start_method__")+ and hasattr(attr_value, "__is_router__")+ and attr_value.__is_router__+ ):+ routers.add(attr_name)+ if (+ hasattr(attr_value, "__router_emit__")+ and attr_value.__router_emit__+ ):+ router_emit[attr_name] = attr_value.__router_emit__+ else:+ router_emit[attr_name] = []++ return start_methods, listeners, routers, router_emitdiff --git a/lib/crewai/src/crewai/flow/flow.py b/lib/crewai/src/crewai/flow/flow.pyindex 3cac04521..353f0ba9c 100644--- a/lib/crewai/src/crewai/flow/flow.py+++ b/lib/crewai/src/crewai/flow/flow.py@@ -3,8 +3,8 @@The implementation now lives in three modules, split by concern:- ``crewai.flow.dsl`` -- authoring decorators (``@start`` / ``@listen`` /- ``@router``, ``or_`` / ``and_``)-- ``crewai.flow.flow_definition`` -- the structural model extracted from the DSL+ ``@router``, ``or_`` / ``and_``) and Python Flow class projection+- ``crewai.flow.flow_definition`` -- the serializable Flow Definition contract- ``crewai.flow.runtime`` -- the Flow execution engine and statePrefer importing from those modules in new code; this module preserves thediff --git a/lib/crewai/src/crewai/flow/flow_definition.py b/lib/crewai/src/crewai/flow/flow_definition.pyindex cc0b2d9ff..1c05a51a9 100644--- a/lib/crewai/src/crewai/flow/flow_definition.py+++ b/lib/crewai/src/crewai/flow/flow_definition.py@@ -1,1036 +1,280 @@-"""-Flow definition: the structural model derived from the DSL.--Condition predicates, condition decoding, AST-based router-path extraction,-graph/level analysis, and ``extract_flow_definition`` (the structural-registries the runtime metaclass attaches to a Flow class). Previously these-lived in ``crewai.flow.utils``, which now re-exports from here.--This module provides core functionality for analyzing and manipulating flow structures,-including node level calculation, ancestor tracking, and return value analysis.-Functions in this module are primarily used by the visualization system to create-accurate and informative flow diagrams.+"""Flow Structure: the serializable, language-agnostic Flow contract.-Example--------->>> flow = Flow()->>> node_levels = calculate_node_levels(flow)->>> ancestors = build_ancestor_dict(flow)+Defines :class:`FlowDefinition` and its sub-models — a static, textual+(JSON/YAML) representation of a Flow: its methods, trigger conditions,+state, and configuration. It is independent of the Python authoring+layer that may have produced it and of the engine that runs it (see+``runtime``)."""from __future__ import annotations-import ast-from collections import defaultdict, deque-from enum import Enum-import inspect-import textwrap-from typing import TYPE_CHECKING, Any--from crewai_core.printer import PRINTER-from typing_extensions import TypeIs--from crewai.flow.constants import AND_CONDITION, OR_CONDITION-from crewai.flow.flow_wrappers import (- FlowCondition,- FlowConditions,- FlowMethod,- SimpleFlowCondition,-)-from crewai.flow.types import FlowMethodCallable, FlowMethodName---if TYPE_CHECKING:- from crewai.flow.flow import Flow---def _extract_string_literals_from_type_annotation(- node: ast.expr,- function_globals: dict[str, Any] | None = None,-) -> list[str]:- """Extract string literals from a type annotation AST node.-- Handles:- - Literal["a", "b", "c"]- - "a" | "b" | "c" (union of string literals)- - Just "a" (single string constant annotation)- - Enum types with string values (e.g., class MyEnum(str, Enum))-- Args:- node: The AST node representing a type annotation.- function_globals: The globals dict from the function, used to resolve Enum types.+import json+import logging+from typing import Any, Literal as TypingLiteral- Returns:- List of string literals found in the annotation.- """+from pydantic import BaseModel, ConfigDict, Field+import yaml- strings: list[str] = []- if isinstance(node, ast.Constant) and isinstance(node.value, str):- strings.append(node.value)+logger = logging.getLogger(__name__)- elif isinstance(node, ast.Name) and function_globals:- enum_class = function_globals.get(node.id)- if (- enum_class is not None- and isinstance(enum_class, type)- and issubclass(enum_class, Enum)- ):- strings.extend(- member.value for member in enum_class if isinstance(member.value, str)- )+FlowDefinitionCondition = str | dict[str, Any]- elif isinstance(node, ast.Attribute) and function_globals:- try:- if isinstance(node.value, ast.Name):- module = function_globals.get(node.value.id)- if module is not None:- enum_class = getattr(module, node.attr, None)- if (- enum_class is not None- and isinstance(enum_class, type)- and issubclass(enum_class, Enum)- ):- strings.extend(- member.value- for member in enum_class- if isinstance(member.value, str)- )- except (AttributeError, TypeError):- pass+__all__ = [+ "FlowConfigDefinition",+ "FlowDefinition",+ "FlowDefinitionCondition",+ "FlowDefinitionDiagnostic",+ "FlowHumanFeedbackDefinition",+ "FlowMethodDefinition",+ "FlowPersistenceDefinition",+ "FlowStateDefinition",+]- elif isinstance(node, ast.Subscript):- is_literal = False- if isinstance(node.value, ast.Name) and node.value.id == "Literal":- is_literal = True- elif isinstance(node.value, ast.Attribute) and node.value.attr == "Literal":- is_literal = True- if is_literal:- if isinstance(node.slice, ast.Tuple):- strings.extend(- elt.value- for elt in node.slice.elts- if isinstance(elt, ast.Constant) and isinstance(elt.value, str)- )- elif isinstance(node.slice, ast.Constant) and isinstance(- node.slice.value, str- ):- strings.append(node.slice.value)+class FlowDefinitionDiagnostic(BaseModel):+ """A non-fatal Flow Definition build or validation diagnostic."""- elif isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):- strings.extend(- _extract_string_literals_from_type_annotation(node.left, function_globals)- )- strings.extend(- _extract_string_literals_from_type_annotation(node.right, function_globals)- )+ code: str+ message: str+ severity: TypingLiteral["warning", "error"] = "warning"+ path: str | None = None- return strings+class FlowStateDefinition(BaseModel):+ """Static description of a Flow state contract."""-def _unwrap_function(function: Any) -> Any:- """Unwrap a function to get the original function with correct globals.+ type: TypingLiteral["dict", "pydantic", "unknown"] = "dict"+ ref: str | None = None+ default: Any = None- Flow methods are wrapped by decorators like @router, @listen, etc.- This function unwraps them to get the original function which has- the correct __globals__ for resolving type annotations like Enums.- Args:- function: The potentially wrapped function.+class FlowConfigDefinition(BaseModel):+ """Serializable Flow-level configuration."""- Returns:- The unwrapped original function.- """- if hasattr(function, "__func__"):- function = function.__func__+ tracing: bool | None = None+ stream: bool = False+ memory: Any = None+ input_provider: Any = None+ suppress_flow_events: bool = False+ max_method_calls: int = 100- if hasattr(function, "__wrapped__"):- wrapped = function.__wrapped__- if hasattr(wrapped, "unwrap"):- return wrapped.unwrap()- return wrapped- return function+class FlowPersistenceDefinition(BaseModel):+ """Static persistence configuration."""+ enabled: bool = False+ verbose: bool = False+ persistence: Any = None-def get_possible_return_constants(- function: Any, verbose: bool = True-) -> list[str] | None:- """Extract possible string return values from a function using AST parsing.- This function analyzes the source code of a router method to identify- all possible string values it might return. It handles:- - Return type annotations: -> Literal["a", "b"] or -> "a" | "b" | "c"- - Enum type annotations: -> MyEnum (extracts string values from members)- - Direct string literals: return "value"- - Variable assignments: x = "value"; return x- - Dictionary lookups: d = {"k": "v"}; return d[key]- - Conditional returns: return "a" if cond else "b"- - State attributes: return self.state.attr (infers from class context)+class FlowHumanFeedbackDefinition(BaseModel):+ """Static human feedback configuration."""- Args:- function: The function to analyze.+ message: str+ emit: list[str] | None = None+ llm: Any = "gpt-4o-mini"+ default_outcome: str | None = None+ metadata: dict[str, Any] | None = None+ provider: Any = None+ learn: bool = False+ learn_source: str = "hitl"+ learn_strict: bool = False- Returns:- List of possible string return values, or None if analysis fails.- """- unwrapped = _unwrap_function(function)- try:- source = inspect.getsource(function)- except OSError:- return None- except Exception as e:- if verbose:- PRINTER.print(- f"Error retrieving source code for function {function.__name__}: {e}",- color="red",- )- return None+class FlowMethodDefinition(BaseModel):+ """Static definition of one Flow method and its execution roles."""- try:- source = textwrap.dedent(source)- code_ast = ast.parse(source)- except IndentationError as e:- if verbose:- PRINTER.print(- f"IndentationError while parsing source code of {function.__name__}: {e}",- color="red",- )- PRINTER.print(f"Source code:\n{source}", color="yellow")- return None- except SyntaxError as e:- if verbose:- PRINTER.print(- f"SyntaxError while parsing source code of {function.__name__}: {e}",- color="red",- )- PRINTER.print(f"Source code:\n{source}", color="yellow")- return None- except Exception as e:- if verbose:- PRINTER.print(- f"Unexpected error while parsing source code of {function.__name__}: {e}",- color="red",- )- PRINTER.print(f"Source code:\n{source}", color="yellow")- return None+ start: bool | FlowDefinitionCondition | None = None+ listen: FlowDefinitionCondition | None = None+ router: bool = False+ emit: list[str] | None = None+ human_feedback: FlowHumanFeedbackDefinition | None = None+ persist: FlowPersistenceDefinition | None = None- return_values: set[str] = set()+ @property+ def is_start(self) -> bool:+ """Whether this method is a start method.- function_globals = getattr(unwrapped, "__globals__", None)-- for node in ast.walk(code_ast):- if isinstance(node, ast.FunctionDef):- if node.returns:- annotation_values = _extract_string_literals_from_type_annotation(- node.returns, function_globals- )- return_values.update(annotation_values)- break # Only process the first function definition- dict_definitions: dict[str, list[str]] = {}- variable_values: dict[str, list[str]] = {}- state_attribute_values: dict[str, list[str]] = {}-- def extract_string_constants(node: ast.expr) -> list[str]:- """Recursively extract all string constants from an AST node."""- strings: list[str] = []- if isinstance(node, ast.Constant) and isinstance(node.value, str):- strings.append(node.value)- elif isinstance(node, ast.IfExp):- strings.extend(extract_string_constants(node.body))- strings.extend(extract_string_constants(node.orelse))- elif isinstance(node, ast.Call):- if (- isinstance(node.func, ast.Attribute)- and node.func.attr == "get"- and len(node.args) >= 2- ):- default_arg = node.args[1]- if isinstance(default_arg, ast.Constant) and isinstance(- default_arg.value, str- ):- strings.append(default_arg.value)- return strings-- class VariableAssignmentVisitor(ast.NodeVisitor):- def visit_Assign(self, node: ast.Assign) -> None:- if isinstance(node.value, ast.Dict) and len(node.targets) == 1:- target = node.targets[0]- if isinstance(target, ast.Name):- var_name = target.id- dict_values = [- val.value- for val in node.value.values- if isinstance(val, ast.Constant) and isinstance(val.value, str)- ]- if dict_values:- dict_definitions[var_name] = dict_values-- if len(node.targets) == 1:- target = node.targets[0]- var_name_alt: str | None = None- if isinstance(target, ast.Name):- var_name_alt = target.id- elif isinstance(target, ast.Attribute):- var_name_alt = f"{target.value.id if isinstance(target.value, ast.Name) else '_'}.{target.attr}"-- if var_name_alt:- strings = extract_string_constants(node.value)- if strings:- variable_values[var_name_alt] = strings-- self.generic_visit(node)-- def get_attribute_chain(node: ast.expr) -> str | None:- """Extract the full attribute chain from an AST node.-- Examples:- self.state.run_type -> "self.state.run_type"- x.y.z -> "x.y.z"- simple_var -> "simple_var"+ A loaded contract may carry ``start: false`` to mark a non-start+ method explicitly, so falsy values (``False``/``None``/empty string)+ are treated as "not a start method"."""- if isinstance(node, ast.Name):- return node.id- if isinstance(node, ast.Attribute):- base = get_attribute_chain(node.value)- if base:- return f"{base}.{node.attr}"- return None-- class ReturnVisitor(ast.NodeVisitor):- def visit_Return(self, node: ast.Return) -> None:- if (- node.value- and isinstance(node.value, ast.Constant)- and isinstance(node.value.value, str)- ):- return_values.add(node.value.value)- elif node.value and isinstance(node.value, ast.Subscript):- if isinstance(node.value.value, ast.Name):- var_name_dict = node.value.value.id- if var_name_dict in dict_definitions:- for v in dict_definitions[var_name_dict]:- return_values.add(v)- elif node.value:- var_name_ret = get_attribute_chain(node.value)-- if var_name_ret and var_name_ret in variable_values:- for v in variable_values[var_name_ret]:- return_values.add(v)- elif var_name_ret and var_name_ret in state_attribute_values:- for v in state_attribute_values[var_name_ret]:- return_values.add(v)-- self.generic_visit(node)-- def visit_If(self, node: ast.If) -> None:- self.generic_visit(node)-- try:- if hasattr(function, "__self__"):- class_obj = function.__self__.__class__- elif hasattr(function, "__qualname__") and "." in function.__qualname__:- class_name = function.__qualname__.rsplit(".", 1)[0]- if hasattr(function, "__globals__"):- class_obj = function.__globals__.get(class_name)- else:- class_obj = None- else:- class_obj = None-- if class_obj is not None:- try:- class_source = inspect.getsource(class_obj)- class_source = textwrap.dedent(class_source)- class_ast = ast.parse(class_source)-- class StateAttributeVisitor(ast.NodeVisitor):- def visit_Compare(self, node: ast.Compare) -> None:- """Find comparisons like: self.state.attr == "value" """- left_attr = get_attribute_chain(node.left)-- if left_attr:- for comparator in node.comparators:- if isinstance(comparator, ast.Constant) and isinstance(- comparator.value, str- ):- if left_attr not in state_attribute_values:- state_attribute_values[left_attr] = []- if (- comparator.value- not in state_attribute_values[left_attr]- ):- state_attribute_values[left_attr].append(- comparator.value- )-- for comparator in node.comparators:- right_attr = get_attribute_chain(comparator)- if (- right_attr- and isinstance(node.left, ast.Constant)- and isinstance(node.left.value, str)- ):- if right_attr not in state_attribute_values:- state_attribute_values[right_attr] = []- if (- node.left.value- not in state_attribute_values[right_attr]- ):- state_attribute_values[right_attr].append(- node.left.value- )-- self.generic_visit(node)+ return bool(self.start)+++class FlowDefinition(BaseModel):+ """Static, serializable definition of a Flow."""++ model_config = ConfigDict(populate_by_name=True, arbitrary_types_allowed=True)++ schema_: str = Field(default="crewai.flow/v1", alias="schema")+ name: str+ description: str | None = None+ state: FlowStateDefinition | None = None+ config: FlowConfigDefinition = Field(default_factory=FlowConfigDefinition)+ persist: FlowPersistenceDefinition | None = None+ methods: dict[str, FlowMethodDefinition] = Field(default_factory=dict)+ diagnostics: list[FlowDefinitionDiagnostic] = Field(default_factory=list)++ def to_dict(self, *, exclude_none: bool = True) -> dict[str, Any]:+ """Serialize the definition to a JSON/YAML-ready dictionary."""+ return self.model_dump(by_alias=True, exclude_none=exclude_none, mode="json")++ def to_json(self, *, indent: int | None = 2, exclude_none: bool = True) -> str:+ """Serialize the definition to JSON."""+ data = self.to_dict(exclude_none=exclude_none)+ return json.dumps(data, indent=indent)++ def to_yaml(self, *, exclude_none: bool = True) -> str:+ """Serialize the definition to YAML."""+ return yaml.safe_dump(+ self.to_dict(exclude_none=exclude_none),+ sort_keys=False,+ allow_unicode=True,+ )- StateAttributeVisitor().visit(class_ast)- except Exception as e:- if verbose:- PRINTER.print(- f"Could not analyze class context for {function.__name__}: {e}",- color="yellow",+ @classmethod+ def from_dict(cls, data: dict[str, Any]) -> FlowDefinition:+ """Load a definition from a dictionary and attach diagnostics."""+ serialized_diagnostics = _deserialize_diagnostics(data.get("diagnostics", []))+ definition = cls.model_validate(data)+ definition.diagnostics = _merge_diagnostics(+ serialized_diagnostics, definition.validate_contract()+ )+ definition.log_diagnostics()+ return definition++ @classmethod+ def from_json(cls, data: str) -> FlowDefinition:+ """Load a definition from JSON."""+ return cls.from_dict(json.loads(data))++ @classmethod+ def from_yaml(cls, data: str) -> FlowDefinition:+ """Load a definition from YAML."""+ loaded = yaml.safe_load(data) or {}+ if not isinstance(loaded, dict):+ raise ValueError("Flow definition YAML must contain a mapping")+ return cls.from_dict(loaded)++ @classmethod+ def json_schema(cls) -> dict[str, Any]:+ """Return the JSON Schema for the Flow Definition contract."""+ return cls.model_json_schema(by_alias=True)++ def validate_contract(self) -> list[FlowDefinitionDiagnostic]:+ """Validate the static contract without rejecting dynamic routing."""+ diagnostics: list[FlowDefinitionDiagnostic] = []+ for method_name, method in self.methods.items():+ path = f"methods.{method_name}"+ if method.router and not method.is_start and method.listen is None:+ diagnostics.append(+ FlowDefinitionDiagnostic(+ code="router_without_trigger",+ severity="error",+ path=path,+ message="router: true requires either start or listen",)- except Exception as e:- if verbose:- PRINTER.print(- f"Could not introspect class for {function.__name__}: {e}",- color="yellow",- )-- VariableAssignmentVisitor().visit(code_ast)- ReturnVisitor().visit(code_ast)-- return list(return_values) if return_values else None---def calculate_node_levels(flow: Any) -> dict[str, int]:- """- Calculate the hierarchical level of each node in the flow.-- Performs a breadth-first traversal of the flow graph to assign levels- to nodes, starting with start methods at level 0.-- Parameters- ----------- flow : Any- The flow instance containing methods, listeners, and router configurations.-- Returns- -------- Dict[str, int]- Dictionary mapping method names to their hierarchical levels.-- Notes- ------ - Start methods are assigned level 0- - Each subsequent connected node is assigned level = parent_level + 1- - Handles both OR and AND conditions for listeners- - Processes router paths separately- """- levels: dict[str, int] = {}- queue: deque[str] = deque()- visited: set[str] = set()- pending_and_listeners: dict[str, set[str]] = {}-- for method_name, method in flow._methods.items():- if hasattr(method, "__is_start_method__"):- levels[method_name] = 0- queue.append(method_name)-- or_listeners = defaultdict(list)- and_listeners = defaultdict(set)- for listener_name, condition_data in flow._listeners.items():- if isinstance(condition_data, tuple):- condition_type, trigger_methods = condition_data- elif isinstance(condition_data, dict):- trigger_methods = _extract_all_methods_recursive(condition_data, flow)- condition_type = condition_data.get("type", "OR")- else:- continue-- if condition_type == "OR":- for method in trigger_methods:- or_listeners[method].append(listener_name)- elif condition_type == "AND":- and_listeners[listener_name] = set(trigger_methods)-- while queue:- current = queue.popleft()- current_level = levels[current]- visited.add(current)-- for listener_name in or_listeners[current]:- if listener_name not in levels or levels[listener_name] > current_level + 1:- levels[listener_name] = current_level + 1- if listener_name not in visited:- queue.append(listener_name)-- for listener_name, required_methods in and_listeners.items():- if current in required_methods:- if listener_name not in pending_and_listeners:- pending_and_listeners[listener_name] = set()- pending_and_listeners[listener_name].add(current)-- if required_methods == pending_and_listeners[listener_name]:- if (- listener_name not in levels- or levels[listener_name] > current_level + 1- ):- levels[listener_name] = current_level + 1- if listener_name not in visited:- queue.append(listener_name)-- process_router_paths(flow, current, current_level, levels, queue)-- max_level = max(levels.values()) if levels else 0- for method_name in flow._methods:- if method_name not in levels:- levels[method_name] = max_level + 1-- return levels---def count_outgoing_edges(flow: Any) -> dict[str, int]:- """- Count the number of outgoing edges for each method in the flow.-- Parameters- ----------- flow : Any- The flow instance to analyze.-- Returns- -------- Dict[str, int]- Dictionary mapping method names to their outgoing edge count.- """- counts = {}- for method_name in flow._methods:- counts[method_name] = 0- for condition_data in flow._listeners.values():- if isinstance(condition_data, tuple):- _, trigger_methods = condition_data- elif isinstance(condition_data, dict):- trigger_methods = _extract_all_methods_recursive(condition_data, flow)- else:- continue-- for trigger in trigger_methods:- if trigger in flow._methods:- counts[trigger] += 1- return counts---def build_ancestor_dict(flow: Any) -> dict[str, set[str]]:- """- Build a dictionary mapping each node to its ancestor nodes.-- Parameters- ----------- flow : Any- The flow instance to analyze.-- Returns- -------- Dict[str, Set[str]]- Dictionary mapping each node to a set of its ancestor nodes.- """- ancestors: dict[str, set[str]] = {node: set() for node in flow._methods}- visited: set[str] = set()- for node in flow._methods:- if node not in visited:- dfs_ancestors(node, ancestors, visited, flow)- return ancestors---def dfs_ancestors(- node: str, ancestors: dict[str, set[str]], visited: set[str], flow: Any-) -> None:- """- Perform depth-first search to build ancestor relationships.-- Parameters- ----------- node : str- Current node being processed.- ancestors : Dict[str, Set[str]]- Dictionary tracking ancestor relationships.- visited : Set[str]- Set of already visited nodes.- flow : Any- The flow instance being analyzed.-- Notes- ------ This function modifies the ancestors dictionary in-place to build- the complete ancestor graph.- """- if node in visited:- return- visited.add(node)-- for listener_name, condition_data in flow._listeners.items():- if isinstance(condition_data, tuple):- _, trigger_methods = condition_data- elif isinstance(condition_data, dict):- trigger_methods = _extract_all_methods_recursive(condition_data, flow)- else:- continue-- if node in trigger_methods:- ancestors[listener_name].add(node)- ancestors[listener_name].update(ancestors[node])- dfs_ancestors(listener_name, ancestors, visited, flow)-- if node in flow._routers:- router_method_name = node- paths = flow._router_paths.get(router_method_name, [])- for path in paths:- for listener_name, condition_data in flow._listeners.items():- if isinstance(condition_data, tuple):- _, trigger_methods = condition_data- elif isinstance(condition_data, dict):- trigger_methods = _extract_all_methods_recursive(- condition_data, flow+ )+ if method.emit and not method.router:+ diagnostics.append(+ FlowDefinitionDiagnostic(+ code="emit_without_router",+ path=f"{path}.emit",+ message="emit is only used by routers to declare downstream events",)- else:- continue-- if path in trigger_methods:- ancestors[listener_name].update(ancestors[node])- dfs_ancestors(listener_name, ancestors, visited, flow)---def is_ancestor(- node: str, ancestor_candidate: str, ancestors: dict[str, set[str]]-) -> bool:- """- Check if one node is an ancestor of another.-- Parameters- ----------- node : str- The node to check ancestors for.- ancestor_candidate : str- The potential ancestor node.- ancestors : Dict[str, Set[str]]- Dictionary containing ancestor relationships.-- Returns- -------- bool- True if ancestor_candidate is an ancestor of node, False otherwise.- """- return ancestor_candidate in ancestors.get(node, set())---def build_parent_children_dict(flow: Any) -> dict[str, list[str]]:- """- Build a dictionary mapping parent nodes to their children.-- Parameters- ----------- flow : Any- The flow instance to analyze.-- Returns- -------- Dict[str, List[str]]- Dictionary mapping parent method names to lists of their child method names.-- Notes- ------ - Maps listeners to their trigger methods- - Maps router methods to their paths and listeners- - Children lists are sorted for consistent ordering- """- parent_children: dict[str, list[str]] = {}-- for listener_name, condition_data in flow._listeners.items():- if isinstance(condition_data, tuple):- _, trigger_methods = condition_data- elif isinstance(condition_data, dict):- trigger_methods = _extract_all_methods_recursive(condition_data, flow)- else:- continue-- for trigger in trigger_methods:- if trigger not in parent_children:- parent_children[trigger] = []- if listener_name not in parent_children[trigger]:- parent_children[trigger].append(listener_name)-- for router_method_name, paths in flow._router_paths.items():- for path in paths:- for listener_name, condition_data in flow._listeners.items():- if isinstance(condition_data, tuple):- _, trigger_methods = condition_data- elif isinstance(condition_data, dict):- trigger_methods = _extract_all_methods_recursive(- condition_data, flow+ )+ if method.human_feedback:+ human_feedback_config = method.human_feedback+ if human_feedback_config.emit and not human_feedback_config.llm:+ diagnostics.append(+ FlowDefinitionDiagnostic(+ code="human_feedback_llm_required",+ severity="error",+ path=f"{path}.human_feedback.llm",+ message="llm is required when human_feedback.emit is set",+ ))- else:- continue-- if path in trigger_methods:- if router_method_name not in parent_children:- parent_children[router_method_name] = []- if listener_name not in parent_children[router_method_name]:- parent_children[router_method_name].append(listener_name)-- return parent_children---def get_child_index(- parent: str, child: str, parent_children: dict[str, list[str]]-) -> int:- """- Get the index of a child node in its parent's sorted children list.-- Parameters- ----------- parent : str- The parent node name.- child : str- The child node name to find the index for.- parent_children : Dict[str, List[str]]- Dictionary mapping parents to their children lists.-- Returns- -------- int- Zero-based index of the child in its parent's sorted children list.- """- children = parent_children.get(parent, [])- children.sort()- return children.index(child)---def process_router_paths(- flow: Any,- current: str,- current_level: int,- levels: dict[str, int],- queue: deque[str],-) -> None:- """Handle the router connections for the current node."""- if current in flow._routers:- paths = flow._router_paths.get(current, [])- for path in paths:- for listener_name, condition_data in flow._listeners.items():- if isinstance(condition_data, tuple):- _condition_type, trigger_methods = condition_data- elif isinstance(condition_data, dict):- trigger_methods = _extract_all_methods_recursive(- condition_data, flow+ if (+ human_feedback_config.default_outcome is not None+ and not human_feedback_config.emit+ ):+ diagnostics.append(+ FlowDefinitionDiagnostic(+ code="human_feedback_default_requires_emit",+ severity="error",+ path=f"{path}.human_feedback.default_outcome",+ message="default_outcome requires human_feedback.emit",+ ))- else:- continue-- if path in trigger_methods:+ elif (+ human_feedback_config.default_outcome is not None+ and human_feedback_config.emit+ ):if (- listener_name not in levels- or levels[listener_name] > current_level + 1+ human_feedback_config.default_outcome+ not in human_feedback_config.emit):- levels[listener_name] = current_level + 1- queue.append(listener_name)---def is_flow_method_name(obj: Any) -> TypeIs[FlowMethodName]:- """Check if the object is a valid flow method name.-- Args:- obj: The object to check.- Returns:- True if the object is a valid flow method name, False otherwise.- """- return isinstance(obj, str)---def is_flow_method_callable(obj: Any) -> TypeIs[FlowMethodCallable[..., Any]]:- """Check if the object is a callable flow method.-- Args:- obj: The object to check.-- Returns:- True if the object is a callable, False otherwise.- """- return callable(obj) and hasattr(obj, "__name__")---def is_flow_condition_list(obj: Any) -> TypeIs[FlowConditions]:- """Check if the object is a list of FlowCondition dictionaries.-- Args:- obj: The object to check.-- Returns:- True if the object is a list of FlowCondition dictionaries, False otherwise.- """- if not isinstance(obj, list):- return False-- for item in obj:- if not (is_flow_method_name(item) or is_flow_condition_dict(item)):- return False-- return True---def is_simple_flow_condition(obj: Any) -> TypeIs[SimpleFlowCondition]:- """Check if the object is a simple flow condition tuple.-- Args:- obj: The object to check.-- Returns:- True if the object is a (condition_type, methods) tuple, False otherwise.- """- return (- isinstance(obj, tuple)- and len(obj) == 2- and isinstance(obj[0], str)- and isinstance(obj[1], list)- )---def is_flow_method(obj: Any) -> TypeIs[FlowMethod[Any, Any]]:- """Check if the object is a flow method wrapper.-- Checks for attributes added by @start, @listen, or @router decorators.-- Args:- obj: The object to check.-- Returns:- True if the object is a FlowMethod subclass (StartMethod, ListenMethod, or RouterMethod).- """- return (- hasattr(obj, "__is_flow_method__")- or hasattr(obj, "__is_start_method__")- or hasattr(obj, "__trigger_methods__")- or hasattr(obj, "__is_router__")- )---def is_flow_condition_dict(obj: Any) -> TypeIs[FlowCondition]:- """Check if the object matches the FlowCondition structure.-- Args:- obj: The object to check.-- Returns:- True if the object is a valid FlowCondition dictionary, False otherwise.- """- if not isinstance(obj, dict):- return False-- type_value = obj.get("type")- if type_value not in ("AND", "OR"):- return False-- if "conditions" in obj:- conditions = obj["conditions"]- if not isinstance(conditions, list):- return False- for cond in conditions:- if not (- isinstance(cond, str)- or (isinstance(cond, dict) and is_flow_condition_dict(cond))- ):- return False-- if "methods" in obj:- methods = obj["methods"]- if not (isinstance(methods, list) and all(isinstance(m, str) for m in methods)):- return False-- allowed_keys = {"type", "conditions", "methods"}- if not set(obj).issubset(allowed_keys):- return False-- return True---def _extract_all_methods_recursive(- condition: str | FlowCondition | dict[str, Any] | list[Any],- flow: Flow[Any] | None = None,-) -> list[FlowMethodName]:- """Extract ALL method names from a condition tree recursively.-- This function recursively extracts every method name from the entire- condition tree, regardless of nesting. Used for visualization and debugging.-- Note: Only extracts actual method names, not router output strings.- If flow is provided, it will filter out strings that are not in flow._methods.-- Args:- condition: Can be a string, dict, or list- flow: Optional flow instance to filter out non-method strings-- Returns:- List of all method names found in the condition tree- """- if is_flow_method_name(condition):- if flow is not None:- if condition in flow._methods:- return [condition]- return []- return [condition]- if is_flow_condition_dict(condition):- normalized = _normalize_condition(condition)- methods = []- for sub_cond in normalized.get("conditions", []):- methods.extend(_extract_all_methods_recursive(sub_cond, flow))- return methods- if isinstance(condition, list):- methods = []- for item in condition:- methods.extend(_extract_all_methods_recursive(item, flow))- return methods- return []---def _normalize_condition(- condition: FlowConditions | FlowCondition | FlowMethodName,-) -> FlowCondition:- """Normalize a condition to standard format with 'conditions' key.-- Args:- condition: Can be a string (method name), dict (condition), or list-- Returns:- Normalized dict with 'type' and 'conditions' keys- """- if is_flow_method_name(condition):- return {"type": OR_CONDITION, "conditions": [condition]}- if is_flow_condition_dict(condition):- if "conditions" in condition:- return condition- if "methods" in condition:- return {"type": condition["type"], "conditions": condition["methods"]}- return condition- if is_flow_condition_list(condition):- return {"type": OR_CONDITION, "conditions": condition}-- raise ValueError(f"Cannot normalize condition: {condition}")---def _extract_all_methods(- condition: str | FlowCondition | dict[str, Any] | list[Any],-) -> list[FlowMethodName]:- """Extract all method names from a condition (including nested).-- For AND conditions, this extracts methods that must ALL complete.- For OR conditions nested inside AND, we don't extract their methods- since only one branch of the OR needs to trigger, not all methods.-- This function is used for runtime execution logic, where we need to know- which methods must complete for AND conditions. For visualization purposes,- use _extract_all_methods_recursive() instead.-- Args:- condition: Can be a string, dict, or list-- Returns:- List of all method names in the condition tree that must complete- """- if is_flow_method_name(condition):- return [condition]- if is_flow_condition_dict(condition):- normalized = _normalize_condition(condition)- cond_type = normalized.get("type", OR_CONDITION)-- if cond_type == AND_CONDITION:- return [- sub_cond- for sub_cond in normalized.get("conditions", [])- if is_flow_method_name(sub_cond)- ]- return []- if isinstance(condition, list):- methods = []- for item in condition:- methods.extend(_extract_all_methods(item))- return methods- return []+ diagnostics.append(+ FlowDefinitionDiagnostic(+ code="human_feedback_default_not_in_emit",+ severity="error",+ path=f"{path}.human_feedback.default_outcome",+ message="default_outcome must be one of human_feedback.emit",+ )+ )+ return diagnostics-def extract_flow_definition(- namespace: dict[str, Any],-) -> tuple[list[str], dict[str, Any], set[str], dict[str, Any]]:- """Extract the structural flow registries from a class namespace.+ def with_diagnostics(self) -> FlowDefinition:+ """Attach fresh diagnostics and return this definition."""+ self.diagnostics = self.validate_contract()+ self.log_diagnostics()+ return self- Walks the decorated methods in ``namespace`` and returns the- ``(start_methods, listeners, routers, router_paths)`` registries that the- runtime metaclass attaches to a Flow class. This is the structural half of- what used to live inline in ``FlowMeta.__new__``.- """- start_methods = []- listeners = {}- router_paths = {}- routers = set()+ def log_diagnostics(self) -> None:+ """Emit all attached diagnostics through the flow definition logger."""+ _log_flow_definition_diagnostics(self.name, self.diagnostics)- for attr_name, attr_value in namespace.items():- if (- hasattr(attr_value, "__is_flow_method__")- or hasattr(attr_value, "__is_start_method__")- or hasattr(attr_value, "__trigger_methods__")- or hasattr(attr_value, "__is_router__")- ):- if hasattr(attr_value, "__is_start_method__"):- start_methods.append(attr_name)- if (- hasattr(attr_value, "__trigger_methods__")- and attr_value.__trigger_methods__ is not None- ):- methods = attr_value.__trigger_methods__- condition_type = getattr(attr_value, "__condition_type__", OR_CONDITION)+def _log_flow_definition_diagnostics(+ definition_name: str,+ diagnostics: list[FlowDefinitionDiagnostic],+) -> None:+ for diagnostic in diagnostics:+ level = logging.ERROR if diagnostic.severity == "error" else logging.WARNING+ path = f" at {diagnostic.path}" if diagnostic.path else ""+ logger.log(+ level,+ "Flow definition diagnostic for %s%s [%s]: %s",+ definition_name,+ path,+ diagnostic.code,+ diagnostic.message,+ )- if (- hasattr(attr_value, "__trigger_condition__")- and attr_value.__trigger_condition__ is not None- ):- listeners[attr_name] = attr_value.__trigger_condition__- else:- listeners[attr_name] = (condition_type, methods)- if hasattr(attr_value, "__is_router__") and attr_value.__is_router__:- routers.add(attr_name)- # Explicit __router_paths__ set by @human_feedback(emit=[...]) takes priority over source analysis- if (- hasattr(attr_value, "__router_paths__")- and attr_value.__router_paths__- ):- router_paths[attr_name] = attr_value.__router_paths__- else:- possible_returns = get_possible_return_constants(attr_value)- if possible_returns:- router_paths[attr_name] = possible_returns- else:- router_paths[attr_name] = []+def _deserialize_diagnostics(value: Any) -> list[FlowDefinitionDiagnostic]:+ return [FlowDefinitionDiagnostic.model_validate(item) for item in value or []]- # Handle start methods that are also routers (e.g., @human_feedback with emit)- if (- hasattr(attr_value, "__is_start_method__")- and hasattr(attr_value, "__is_router__")- and attr_value.__is_router__- ):- routers.add(attr_name)- if (- hasattr(attr_value, "__router_paths__")- and attr_value.__router_paths__- ):- router_paths[attr_name] = attr_value.__router_paths__- else:- possible_returns = get_possible_return_constants(attr_value)- if possible_returns:- router_paths[attr_name] = possible_returns- else:- router_paths[attr_name] = []- return start_methods, listeners, routers, router_paths+def _merge_diagnostics(+ *diagnostic_groups: list[FlowDefinitionDiagnostic],+) -> list[FlowDefinitionDiagnostic]:+ diagnostics: list[FlowDefinitionDiagnostic] = []+ seen: set[tuple[str, str, str | None, str]] = set()+ for group in diagnostic_groups:+ for diagnostic in group:+ key = (+ diagnostic.code,+ diagnostic.severity,+ diagnostic.path,+ diagnostic.message,+ )+ if key in seen:+ continue+ seen.add(key)+ diagnostics.append(diagnostic)+ return diagnosticsdiff --git a/lib/crewai/src/crewai/flow/flow_serializer.py b/lib/crewai/src/crewai/flow/flow_serializer.pydeleted file mode 100644index 028b0a430..000000000--- a/lib/crewai/src/crewai/flow/flow_serializer.py+++ /dev/null@@ -1,602 +0,0 @@-"""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:- func = method- if hasattr(method, "_meth"):- func = method._meth- elif hasattr(method, "__wrapped__"):- func = method.__wrapped__-- source = inspect.getsource(func)- source = textwrap.dedent(source)-- 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):- 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-- 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__", "")-- if hasattr(method, "__router_paths__") and method.__router_paths__:- return [str(p) for p in method.__router_paths__]-- 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", [])- dict_methods: list[str] = []- for sub_cond in conditions_list:- dict_methods.extend(_extract_all_methods_from_condition(sub_cond))- return dict_methods- if isinstance(condition, list):- list_methods: list[str] = []- for item in condition:- list_methods.extend(_extract_all_methods_from_condition(item))- return list_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] = []-- 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)-- 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- )-- for router_name, paths in router_paths.items():- for path in paths:- 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-- # _initial_state_t is set by Flow.__class_getitem__- if hasattr(flow_class, "_initial_state_t"):- state_type = flow_class._initial_state_t-- 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)-- 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-- 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)- 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:- 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] = []-- try:- init_method = flow_class.__init__ # type: ignore[misc]- init_sig = inspect.signature(init_method)- 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__}"- )-- 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", {}- )-- 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-- 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-- # Conversational built-ins on the base ``Flow`` class (``conversation_start``,- # ``route_conversation``, ``converse_turn``, etc.) are inert on non-chat- # subclasses — they're not registered in ``_start_methods`` / ``_listeners``,- # so excluding them here keeps the serialized structure aligned with what- # actually fires at runtime.- if getattr(attr, "__conversational_only__", False) and not getattr(- flow_class, "conversational", False- ):- continue-- all_method_names.add(attr_name)-- method_type = _get_method_type(attr_name, attr, start_methods, routers)-- trigger_methods, condition_type = _extract_trigger_methods(attr)-- router_paths_list: list[str] = []- if method_type in ("router", "start_router"):- router_paths_list = _extract_router_paths(attr, router_paths_registry)-- has_hf = _has_human_feedback(attr)-- 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)-- edges = _generate_edges(listeners, routers, router_paths_registry, all_method_names)-- state_schema = _extract_state_schema(flow_class)-- inputs = _detect_flow_inputs(flow_class)-- 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/src/crewai/flow/flow_wrappers.py b/lib/crewai/src/crewai/flow/flow_wrappers.pyindex 80292671b..7e42859c8 100644--- a/lib/crewai/src/crewai/flow/flow_wrappers.py+++ b/lib/crewai/src/crewai/flow/flow_wrappers.py@@ -18,6 +18,17 @@ R = TypeVar("R")FlowConditionType: TypeAlias = Literal["OR", "AND"]SimpleFlowCondition: TypeAlias = tuple[FlowConditionType, list[FlowMethodName]]+__all__ = [+ "FlowCondition",+ "FlowConditionType",+ "FlowConditions",+ "FlowMethod",+ "ListenMethod",+ "RouterMethod",+ "SimpleFlowCondition",+ "StartMethod",+]+class FlowCondition(TypedDict, total=False):"""Type definition for flow trigger conditions.@@ -73,10 +84,12 @@ class FlowMethod(Generic[P, R]):# Preserve flow-related attributes from wrapped method (e.g., from @human_feedback)for attr in ["__is_router__",- "__router_paths__",+ "__router_emit__","__human_feedback_config__","__conversational_only__", # gates registration on Flow.conversational- "_hf_llm", # Live LLM object for HITL resume+ "__flow_persistence_config__",+ "__flow_method_definition__",+ "_human_feedback_llm", # Live LLM object for HITL resume]:if hasattr(meth, attr):setattr(self, attr, getattr(meth, attr))@@ -166,3 +179,4 @@ class RouterMethod(FlowMethod[P, R]):__trigger_methods__: list[FlowMethodName] | None = None__condition_type__: FlowConditionType | None = None__trigger_condition__: FlowCondition | None = None+ __router_emit__: list[str] | None = Nonediff --git a/lib/crewai/src/crewai/flow/human_feedback.py b/lib/crewai/src/crewai/flow/human_feedback.pyindex 2985dab13..65a61d5b2 100644--- a/lib/crewai/src/crewai/flow/human_feedback.py+++ b/lib/crewai/src/crewai/flow/human_feedback.py@@ -65,6 +65,7 @@ from typing import TYPE_CHECKING, Any, TypeVarfrom pydantic import BaseModel, Field+from crewai.flow.flow_definition import FlowMethodDefinitionfrom crewai.flow.flow_wrappers import FlowMethod@@ -78,14 +79,10 @@ logger = logging.getLogger(__name__)F = TypeVar("F", bound=Callable[..., Any])+__all__ = ["HumanFeedbackResult", "human_feedback"]-def _serialize_llm_for_context(llm: Any) -> dict[str, Any] | str | None:- """Serialize a BaseLLM object to a dict preserving full config.- Delegates to ``llm.to_config_dict()`` when available (BaseLLM and- subclasses). Falls back to extracting the model string with provider- prefix for unknown LLM types.- """+def _serialize_llm_for_context(llm: Any) -> dict[str, Any] | str | None:to_config: Callable[[], dict[str, Any]] | None = getattr(llm, "to_config_dict", None)@@ -103,13 +100,6 @@ def _serialize_llm_for_context(llm: Any) -> dict[str, Any] | str | None:def _deserialize_llm_from_context(llm_data: dict[str, Any] | str | None,) -> BaseLLM | None:- """Reconstruct an LLM instance from serialized context data.-- Handles both the new dict format (with full config) and the legacy- string format (model name only) for backward compatibility.-- Returns a BaseLLM instance, or None if llm_data is None.- """if llm_data is None:return None@@ -202,12 +192,12 @@ class HumanFeedbackMethod(FlowMethod[Any, Any]):Attributes:__is_router__: True when emit is specified, enabling router behavior.- __router_paths__: List of possible outcomes when acting as a router.+ __router_emit__: List of possible outcomes when acting as a router.__human_feedback_config__: The HumanFeedbackConfig for this method."""__is_router__: bool = False- __router_paths__: list[str] | None = None+ __router_emit__: list[str] | None = None__human_feedback_config__: HumanFeedbackConfig | None = None@@ -356,20 +346,12 @@ def human_feedback(raise ValueError("default_outcome requires emit to be specified.")def decorator(func: F) -> F:- """Inner decorator that wraps the function."""-def _get_hitl_prompt(key: str) -> str:- """Read a HITL prompt from the i18n translations."""from crewai.utilities.i18n import I18N_DEFAULTreturn I18N_DEFAULT.slice(key)def _resolve_llm_instance() -> Any:- """Resolve the ``llm`` parameter to a BaseLLM instance.-- Uses the SAME model specified in the decorator so pre-review,- distillation, and outcome collapsing all share one model.- """if llm is None:from crewai.llm import LLM@@ -383,7 +365,6 @@ def human_feedback(def _pre_review_with_lessons(flow_instance: Flow[Any], method_output: Any) -> Any:- """Recall past HITL lessons and use LLM to pre-review the output."""try:mem = flow_instance.memoryif mem is None:@@ -431,7 +412,6 @@ def human_feedback(def _distill_and_store_lessons(flow_instance: Flow[Any], method_output: Any, raw_feedback: str) -> None:- """Extract generalizable lessons from output + feedback, store in memory."""try:mem = flow_instance.memoryif mem is None:@@ -485,7 +465,6 @@ def human_feedback(def _build_feedback_context(flow_instance: Flow[Any], method_output: Any) -> tuple[Any, Any]:- """Build the PendingFeedbackContext and resolve the effective provider."""from crewai.flow.async_feedback.types import PendingFeedbackContextcontext = PendingFeedbackContext(@@ -509,7 +488,6 @@ def human_feedback(return context, effective_providerdef _request_feedback(flow_instance: Flow[Any], method_output: Any) -> str:- """Request feedback using provider or default console (sync)."""context, effective_provider = _build_feedback_context(flow_instance, method_output)@@ -535,7 +513,6 @@ def human_feedback(async def _request_feedback_async(flow_instance: Flow[Any], method_output: Any) -> str:- """Request feedback, awaiting the provider if it returns a coroutine."""context, effective_provider = _build_feedback_context(flow_instance, method_output)@@ -559,7 +536,6 @@ def human_feedback(method_output: Any,raw_feedback: str,) -> HumanFeedbackResult | str:- """Process feedback and return result or outcome."""collapsed_outcome: str | None = Noneif not raw_feedback.strip():@@ -661,6 +637,10 @@ def human_feedback("__condition_type__","__trigger_condition__","__is_flow_method__",+ "__flow_persistence_config__",+ "__is_router__",+ "__router_emit__",+ "__flow_method_definition__",]:if hasattr(func, attr):setattr(wrapper, attr, getattr(func, attr))@@ -681,7 +661,16 @@ def human_feedback(if emit:wrapper.__is_router__ = True- wrapper.__router_paths__ = list(emit)+ wrapper.__router_emit__ = list(emit)+ # Keep the definition fragment in sync: emit promotes the method to+ # a router and the feedback outcomes replace any emit recorded by an+ # inner @router. Copy before updating so the wrapped method's own+ # fragment (shared by reference) is left untouched.+ fragment = getattr(wrapper, "__flow_method_definition__", None)+ if isinstance(fragment, FlowMethodDefinition):+ wrapper.__flow_method_definition__ = fragment.model_copy(+ update={"router": True, "emit": list(emit)}+ )# Stash the live LLM object for HITL resume to retrieve.# When a flow pauses for human feedback and later resumes (possibly in a@@ -689,7 +678,7 @@ def human_feedback(# By storing the original LLM on the wrapper, resume_async can retrieve# the fully-configured LLM (with credentials, project, safety_settings, etc.)# instead of creating a bare LLM from just the model string.- wrapper._hf_llm = llm+ wrapper._human_feedback_llm = llmreturn wrapper # type: ignore[no-any-return]diff --git a/lib/crewai/src/crewai/flow/persistence/__init__.py b/lib/crewai/src/crewai/flow/persistence/__init__.pyindex 50de9abcc..e9f0b1807 100644--- a/lib/crewai/src/crewai/flow/persistence/__init__.py+++ b/lib/crewai/src/crewai/flow/persistence/__init__.py@@ -4,16 +4,9 @@ CrewAI Flow Persistence.This module provides interfaces and implementations for persisting flow states."""-from typing import Any, TypeVar--from pydantic import BaseModel-from crewai.flow.persistence.base import FlowPersistencefrom crewai.flow.persistence.decorators import persistfrom crewai.flow.persistence.sqlite import SQLiteFlowPersistence__all__ = ["FlowPersistence", "SQLiteFlowPersistence", "persist"]--StateType = TypeVar("StateType", bound=dict[str, Any] | BaseModel)-DictStateType = dict[str, Any]diff --git a/lib/crewai/src/crewai/flow/persistence/decorators.py b/lib/crewai/src/crewai/flow/persistence/decorators.pyindex 83dd6d69a..3fc5f9bf9 100644--- a/lib/crewai/src/crewai/flow/persistence/decorators.py+++ b/lib/crewai/src/crewai/flow/persistence/decorators.py@@ -28,6 +28,7 @@ import asynciofrom collections.abc import Callableimport functoolsimport logging+from types import SimpleNamespacefrom typing import TYPE_CHECKING, Any, Final, TypeVar, castfrom crewai_core.printer import PRINTER@@ -44,6 +45,8 @@ if TYPE_CHECKING:logger = logging.getLogger(__name__)T = TypeVar("T")+__all__ = ["PersistenceDecorator", "persist"]+LOG_MESSAGES: Final[dict[str, str]] = {"save_state": "Saving flow state to memory for ID: {}","save_error": "Failed to persist state for method {}: {}",@@ -52,6 +55,31 @@ LOG_MESSAGES: Final[dict[str, str]] = {}+def _stamp_persistence_metadata(+ target: Any,+ persistence: FlowPersistence,+ verbose: bool,+) -> None:+ target.__flow_persistence_config__ = SimpleNamespace(+ persistence=persistence,+ verbose=verbose,+ )+++_PRESERVED_FLOW_ATTRS: Final[tuple[str, ...]] = (+ "__is_start_method__",+ "__trigger_methods__",+ "__condition_type__",+ "__trigger_condition__",+ "__is_router__",+ "__router_emit__",+ "__human_feedback_config__",+ "__flow_persistence_config__",+ "__flow_method_definition__",+ "_human_feedback_llm",+)++class PersistenceDecorator:"""Class to handle flow state persistence with consistent logging."""@@ -163,10 +191,10 @@ def persist("""def decorator(target: type | Callable[..., T]) -> type | Callable[..., T]:- """Decorator that handles both class and method decoration."""actual_persistence = persistence or SQLiteFlowPersistence()if isinstance(target, type):+ _stamp_persistence_metadata(target, actual_persistence, verbose)original_init = target.__init__ # type: ignore[misc]@functools.wraps(original_init)@@ -211,12 +239,7 @@ def persist(wrapped = create_async_wrapper(name, method)- for attr in [- "__is_start_method__",- "__trigger_methods__",- "__condition_type__",- "__is_router__",- ]:+ for attr in _PRESERVED_FLOW_ATTRS:if hasattr(method, attr):setattr(wrapped, attr, getattr(method, attr))wrapped.__is_flow_method__ = True # type: ignore[attr-defined]@@ -239,12 +262,7 @@ def persist(wrapped = create_sync_wrapper(name, method)- for attr in [- "__is_start_method__",- "__trigger_methods__",- "__condition_type__",- "__is_router__",- ]:+ for attr in _PRESERVED_FLOW_ATTRS:if hasattr(method, attr):setattr(wrapped, attr, getattr(method, attr))wrapped.__is_flow_method__ = True # type: ignore[attr-defined]@@ -254,6 +272,7 @@ def persist(return targetmethod = targetmethod.__is_flow_method__ = True # type: ignore[attr-defined]+ _stamp_persistence_metadata(method, actual_persistence, verbose)if asyncio.iscoroutinefunction(method):@@ -271,15 +290,13 @@ def persist()return cast(T, result)- for attr in [- "__is_start_method__",- "__trigger_methods__",- "__condition_type__",- "__is_router__",- ]:+ for attr in _PRESERVED_FLOW_ATTRS:if hasattr(method, attr):setattr(method_async_wrapper, attr, getattr(method, attr))method_async_wrapper.__is_flow_method__ = True # type: ignore[attr-defined]+ _stamp_persistence_metadata(+ method_async_wrapper, actual_persistence, verbose+ )return cast(Callable[..., T], method_async_wrapper)@functools.wraps(method)@@ -290,15 +307,11 @@ def persist()return result- for attr in [- "__is_start_method__",- "__trigger_methods__",- "__condition_type__",- "__is_router__",- ]:+ for attr in _PRESERVED_FLOW_ATTRS:if hasattr(method, attr):setattr(method_sync_wrapper, attr, getattr(method, attr))method_sync_wrapper.__is_flow_method__ = True # type: ignore[attr-defined]+ _stamp_persistence_metadata(method_sync_wrapper, actual_persistence, verbose)return cast(Callable[..., T], method_sync_wrapper)return decoratordiff --git a/lib/crewai/src/crewai/flow/runtime.py b/lib/crewai/src/crewai/flow/runtime.pyindex 0a2a84a95..33bfbacea 100644--- a/lib/crewai/src/crewai/flow/runtime.py+++ b/lib/crewai/src/crewai/flow/runtime.py@@ -1,9 +1,9 @@-"""Flow runtime: the Flow execution engine, its metaclass, and state proxies.+"""Flow Runtime: the engine that executes a Flow.-Holds the Flow class (kickoff/resume/listener dispatch), the FlowMeta-metaclass (Pydantic model construction; structural extraction is delegated to-``flow_definition.extract_flow_definition``), and the thread-safe state-proxies. The authoring decorators live in ``crewai.flow.dsl``.+Provides the ``Flow`` class (kickoff/resume/listener dispatch), the+``FlowMeta`` metaclass, and the thread-safe state proxies. Flows+authored with the Python DSL (see ``dsl``) are described by a Flow+Structure (see ``flow_definition``) and executed here."""from __future__ import annotations@@ -90,18 +90,18 @@ from crewai.experimental.conversational import ()from crewai.experimental.conversational_mixin import _ConversationalMixinfrom crewai.flow.constants import AND_CONDITION, OR_CONDITION-from crewai.flow.flow_context import current_flow_id, current_flow_request_id-from crewai.flow.flow_definition import (+from crewai.flow.dsl import (_extract_all_methods,_extract_all_methods_recursive,_normalize_condition,+ build_flow_definition,extract_flow_definition,- get_possible_return_constants,is_flow_condition_dict,is_flow_method,- is_flow_method_name,is_simple_flow_condition,)+from crewai.flow.flow_context import current_flow_id, current_flow_request_id+from crewai.flow.flow_definition import FlowDefinitionfrom crewai.flow.flow_wrappers import (FlowCondition,FlowMethod,@@ -601,7 +601,7 @@ class FlowMeta(ModelMetaclass):cls = super().__new__(mcs, name, bases, namespace)- start_methods, listeners, routers, router_paths = extract_flow_definition(+ start_methods, listeners, routers, router_emit = extract_flow_definition(namespace)@@ -631,9 +631,7 @@ class FlowMeta(ModelMetaclass):start_methods = [m for m in start_methods if not _is_conv_only(m)]listeners = {k: v for k, v in listeners.items() if not _is_conv_only(k)}routers = {r for r in routers if not _is_conv_only(r)}- router_paths = {- k: v for k, v in router_paths.items() if not _is_conv_only(k)- }+ router_emit = {k: v for k, v in router_emit.items() if not _is_conv_only(k)}# 2. Harvest conversational-only methods from base classes when this# subclass opts in. (extract_flow_definition only scans the current@@ -670,21 +668,16 @@ class FlowMeta(ModelMetaclass):if getattr(attr_value, "__is_router__", False):routers.add(attr_name)- paths = getattr(attr_value, "__router_paths__", None)- if paths:- router_paths[attr_name] = paths- else:- possible_returns = get_possible_return_constants(- attr_value- )- router_paths[attr_name] = (- possible_returns if possible_returns else []- )+ emit = getattr(attr_value, "__router_emit__", None)+ router_emit[attr_name] = list(emit) if emit else []cls._start_methods = start_methods # type: ignore[attr-defined]cls._listeners = listeners # type: ignore[attr-defined]cls._routers = routers # type: ignore[attr-defined]- cls._router_paths = router_paths # type: ignore[attr-defined]+ cls._router_emit = router_emit # type: ignore[attr-defined]+ # The static FlowDefinition is built lazily (on first access via+ # ``Flow.flow_definition()`` or visualization), not at class-definition+ # time, to avoid AST parsing and diagnostic logging on every import.return cls@@ -704,7 +697,8 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):_start_methods: ClassVar[list[FlowMethodName]] = []_listeners: ClassVar[dict[FlowMethodName, SimpleFlowCondition | FlowCondition]] = {}_routers: ClassVar[set[FlowMethodName]] = set()- _router_paths: ClassVar[dict[FlowMethodName, list[FlowMethodName]]] = {}+ _router_emit: ClassVar[dict[FlowMethodName, list[FlowMethodName]]] = {}+ _flow_definition: ClassVar[FlowDefinition | None] = None# === EXPERIMENTAL: conversational mode ===# When ``conversational = True`` on a subclass, the built-in conversational@@ -741,6 +735,15 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):entity_type: Literal["flow"] = "flow"+ @classmethod+ def flow_definition(cls) -> FlowDefinition:+ """Return the static Flow Definition built from this Flow class."""+ flow_definition = cls.__dict__.get("_flow_definition")+ if flow_definition is None:+ flow_definition = build_flow_definition(cls)+ cls._flow_definition = flow_definition+ return flow_definition+initial_state: Annotated[ # type: ignore[type-arg]type[BaseModel] | type[dict] | dict[str, Any] | BaseModel | None,BeforeValidator(_deserialize_initial_state),@@ -1466,7 +1469,7 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):llm = Nonemethod = self._methods.get(FlowMethodName(context.method_name))if method is not None:- live_llm = getattr(method, "_hf_llm", None)+ live_llm = getattr(method, "_human_feedback_llm", None)if live_llm is not None:from crewai.llms.base_llm import BaseLLM as BaseLLMClass@@ -2841,7 +2844,7 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):Returns:True if the condition is satisfied, False otherwise"""- if is_flow_method_name(condition):+ if isinstance(condition, str):return condition == trigger_methodif is_flow_condition_dict(condition):diff --git a/lib/crewai/src/crewai/flow/types.py b/lib/crewai/src/crewai/flow/types.pyindex 65ed3a995..46a285bbe 100644--- a/lib/crewai/src/crewai/flow/types.py+++ b/lib/crewai/src/crewai/flow/types.py@@ -22,7 +22,6 @@ P = ParamSpec("P")R = TypeVar("R", covariant=True)FlowMethodName = NewType("FlowMethodName", str)-FlowRouteName = NewType("FlowRouteName", str)PendingListenerKey = NewType("PendingListenerKey",Annotated[str, "nested flow conditions use 'listener_name:object_id'"],diff --git a/lib/crewai/src/crewai/flow/utils.py b/lib/crewai/src/crewai/flow/utils.pydeleted file mode 100644index e23354784..000000000--- a/lib/crewai/src/crewai/flow/utils.py+++ /dev/null@@ -1,53 +0,0 @@-"""Backwards-compatible shim. The implementation moved to ``crewai.flow.flow_definition``.--Import from ``crewai.flow.flow_definition`` directly in new code.-"""--from crewai.flow.flow_definition import (- _extract_all_methods,- _extract_all_methods_recursive,- _extract_string_literals_from_type_annotation,- _normalize_condition,- _unwrap_function,- build_ancestor_dict,- build_parent_children_dict,- calculate_node_levels,- count_outgoing_edges,- dfs_ancestors,- extract_flow_definition,- get_child_index,- get_possible_return_constants,- is_ancestor,- is_flow_condition_dict,- is_flow_condition_list,- is_flow_method,- is_flow_method_callable,- is_flow_method_name,- is_simple_flow_condition,- process_router_paths,-)---__all__ = [- "_extract_all_methods",- "_extract_all_methods_recursive",- "_extract_string_literals_from_type_annotation",- "_normalize_condition",- "_unwrap_function",- "build_ancestor_dict",- "build_parent_children_dict",- "calculate_node_levels",- "count_outgoing_edges",- "dfs_ancestors",- "extract_flow_definition",- "get_child_index",- "get_possible_return_constants",- "is_ancestor",- "is_flow_condition_dict",- "is_flow_condition_list",- "is_flow_method",- "is_flow_method_callable",- "is_flow_method_name",- "is_simple_flow_condition",- "process_router_paths",-]diff --git a/lib/crewai/src/crewai/flow/visualization/assets/interactive.js b/lib/crewai/src/crewai/flow/visualization/assets/interactive.jsindex 10788727f..83f8691b7 100644--- a/lib/crewai/src/crewai/flow/visualization/assets/interactive.js+++ b/lib/crewai/src/crewai/flow/visualization/assets/interactive.js@@ -684,7 +684,7 @@ class TriggeredByHighlighter {});} else {for (const [nodeName, nodeInfo] of Object.entries(nodeData)) {- if (nodeInfo.router_paths && nodeInfo.router_paths.includes(triggerNodeId)) {+ if (nodeInfo.router_events && nodeInfo.router_events.includes(triggerNodeId)) {const routerNode = nodeName;const routerEdges = allEdges.filter(@@ -768,7 +768,7 @@ class TriggeredByHighlighter {this.animateEdgeStyles();}- highlightAllRouterPaths() {+ highlightAllRouterEvents() {this.clear();if (!this.activeDrawerNodeId) {@@ -792,10 +792,10 @@ class TriggeredByHighlighter {routerEdges.forEach(edge => {pathNodes.add(edge.to);});- } else if (activeMetadata && activeMetadata.router_paths && activeMetadata.router_paths.length > 0) {- activeMetadata.router_paths.forEach(pathName => {+ } else if (activeMetadata && activeMetadata.router_events && activeMetadata.router_events.length > 0) {+ activeMetadata.router_events.forEach(eventName => {for (const [nodeName, nodeInfo] of Object.entries(nodeData)) {- if (nodeInfo.router_paths && nodeInfo.router_paths.includes(pathName)) {+ if (nodeInfo.router_events && nodeInfo.router_events.includes(eventName)) {const edgeFromRouter = allEdges.filter((edge) => edge.from === nodeName && edge.to === this.activeDrawerNodeId && edge.dashes);@@ -821,6 +821,42 @@ class TriggeredByHighlighter {this.animateEdgeStyles();}+ highlightRouterEvent(eventName) {+ this.clear();++ if (this.activeDrawerEdges && this.activeDrawerEdges.length > 0) {+ this.resetEdgesToDefault(this.activeDrawerEdges);+ this.activeDrawerEdges = [];+ }++ if (!this.activeDrawerNodeId || !eventName) {+ return;+ }++ const routerEdges = this.edges.get().filter(+ (edge) =>+ edge.from === this.activeDrawerNodeId &&+ edge.dashes &&+ edge.label === eventName,+ );++ if (routerEdges.length === 0) {+ return;+ }++ const pathNodes = new Set([this.activeDrawerNodeId]);+ routerEdges.forEach((edge) => {+ pathNodes.add(edge.from);+ pathNodes.add(edge.to);+ });++ this.highlightedNodes = Array.from(pathNodes);+ this.highlightedEdges = routerEdges.map((e) => e.id);++ this.animateNodeOpacity();+ this.animateEdgeStyles();+ }+highlightTriggeredBy(triggerNodeId) {this.clear();@@ -892,8 +928,8 @@ class TriggeredByHighlighter {) {for (const [nodeName, nodeInfo] of Object.entries(nodeData)) {if (- nodeInfo.router_paths &&- nodeInfo.router_paths.includes(triggerNodeId)+ nodeInfo.router_events &&+ nodeInfo.router_events.includes(triggerNodeId)) {const routerNode = nodeName;@@ -1501,7 +1537,7 @@ class DrawerManager {const activeMetadata = nodeData[activeNodeId];if (activeMetadata && activeMetadata.trigger_methods && activeMetadata.trigger_methods.includes(triggerNodeId)) {for (const [nodeName, nodeInfo] of Object.entries(nodeData)) {- if (nodeInfo.router_paths && nodeInfo.router_paths.includes(triggerNodeId)) {+ if (nodeInfo.router_events && nodeInfo.router_events.includes(triggerNodeId)) {const routerEdges = allEdges.filter((edge) => edge.from === nodeName && edge.dashes);@@ -1660,16 +1696,16 @@ class DrawerManager {`;}- if (metadata.router_paths && metadata.router_paths.length > 0) {- const uniqueRouterPaths = [...new Set(metadata.router_paths)];- const routerPathsJson = JSON.stringify(uniqueRouterPaths).replace(/"/g, '"');+ if (metadata.router_events && metadata.router_events.length > 0) {+ const uniqueRouterEvents = [...new Set(metadata.router_events)];+ const routerEventsJson = JSON.stringify(uniqueRouterEvents).replace(/"/g, '"');metadataContent += `<div class="drawer-section">- <div class="drawer-section-title router-paths-title" data-router-paths="${routerPathsJson}" style="cursor: pointer; display: inline-flex; align-items: center; gap: 4px;">- Router Paths <i data-lucide="chevron-down" style="width: 14px; height: 14px; color: var(--text-primary);"></i>+ <div class="drawer-section-title router-events-title" data-router-events="${routerEventsJson}" style="cursor: pointer; display: inline-flex; align-items: center; gap: 4px;">+ Router Events <i data-lucide="chevron-down" style="width: 14px; height: 14px; color: var(--text-primary);"></i></div><ul class="drawer-list">- ${uniqueRouterPaths.map((p) => `<li><span class="drawer-code-link" data-node-id="${p}" style="color: {{ CREWAI_ORANGE }}; border-color: rgba(255,90,80,0.3);">${p}</span></li>`).join("")}+ ${uniqueRouterEvents.map((eventName) => `<li><span class="drawer-code-link" data-router-event="${eventName}" style="color: {{ CREWAI_ORANGE }}; border-color: rgba(255,90,80,0.3);">${eventName}</span></li>`).join("")}</ul></div>`;@@ -1823,14 +1859,26 @@ class DrawerManager {});});- const routerPathsTitle = this.elements.content.querySelector(- ".router-paths-title[data-router-paths]",+ const routerEventLinks = this.elements.content.querySelectorAll(+ ".drawer-code-link[data-router-event]",+ );+ routerEventLinks.forEach((link) => {+ link.addEventListener("click", (e) => {+ e.preventDefault();+ e.stopPropagation();+ const routerEvent = link.getAttribute("data-router-event");+ this.triggeredByHighlighter.highlightRouterEvent(routerEvent);+ });+ });++ const routerEventsTitle = this.elements.content.querySelector(+ ".router-events-title[data-router-events]",);- if (routerPathsTitle) {- routerPathsTitle.addEventListener("click", (e) => {+ if (routerEventsTitle) {+ routerEventsTitle.addEventListener("click", (e) => {e.preventDefault();e.stopPropagation();- this.triggeredByHighlighter.highlightAllRouterPaths();+ this.triggeredByHighlighter.highlightAllRouterEvents();});}}diff --git a/lib/crewai/src/crewai/flow/visualization/builder.py b/lib/crewai/src/crewai/flow/visualization/builder.pyindex e277c1bbc..987eaf760 100644--- a/lib/crewai/src/crewai/flow/visualization/builder.py+++ b/lib/crewai/src/crewai/flow/visualization/builder.py@@ -1,131 +1,118 @@-"""Flow structure builder for analyzing Flow execution."""+"""Flow structure builder for definition-only Flow visualization."""from __future__ import annotationsfrom collections import defaultdict-import inspectimport logging-from typing import TYPE_CHECKING, Any+from typing import TYPE_CHECKING, Any, castfrom crewai.flow.constants import AND_CONDITION, OR_CONDITION-from crewai.flow.flow_wrappers import FlowCondition-from crewai.flow.types import FlowMethodName-from crewai.flow.utils import (- is_flow_condition_dict,- is_simple_flow_condition,+from crewai.flow.flow_definition import (+ FlowDefinition,+ FlowDefinitionCondition,+ FlowMethodDefinition,)-from crewai.flow.visualization.schema import extract_method_signaturefrom crewai.flow.visualization.types import FlowStructure, NodeMetadata, StructureEdgelogger = logging.getLogger(__name__)+__all__ = ["build_flow_structure", "calculate_execution_paths"]+if TYPE_CHECKING:from crewai.flow.flow import Flow-def _extract_direct_or_triggers(- condition: str | dict[str, Any] | list[Any] | FlowCondition,-) -> list[str]:- """Extract direct OR-level trigger strings from a condition.+def _definition_condition_items(+ condition: dict[str, Any],+ key: str,+) -> list[FlowDefinitionCondition]:+ return cast(list[FlowDefinitionCondition], condition.get(key, []))- This function extracts strings that would directly trigger a listener,- meaning they appear at the top level of an OR condition. Strings nested- inside AND conditions are NOT considered direct triggers for router paths.- For example:- - or_("a", "b") -> ["a", "b"] (both are direct triggers)- - and_("a", "b") -> [] (neither are direct triggers, both required)- - or_(and_("a", "b"), "c") -> ["c"] (only "c" is a direct trigger)+def _definition_condition_parts(+ condition: dict[str, Any],+) -> tuple[str, list[FlowDefinitionCondition]]:+ if "and" in condition:+ return AND_CONDITION, _definition_condition_items(condition, "and")+ return OR_CONDITION, _definition_condition_items(condition, "or")- Args:- condition: Can be a string, dict, or list.- Returns:- List of direct OR-level trigger strings.- """- if isinstance(condition, str):- return [condition]+def _condition_type_from_definition(+ condition: FlowDefinitionCondition | None,+) -> str | None:if isinstance(condition, dict):- cond_type = condition.get("type", OR_CONDITION)- conditions_list = condition.get("conditions", [])-- if cond_type == OR_CONDITION:- strings = []- for sub_cond in conditions_list:- strings.extend(_extract_direct_or_triggers(sub_cond))- return strings- return []- if isinstance(condition, list):- strings = []- for item in condition:- strings.extend(_extract_direct_or_triggers(item))- return strings- if callable(condition) and hasattr(condition, "__name__"):- return [condition.__name__]- return []+ if "and" in condition:+ return AND_CONDITION+ if "or" in condition:+ return OR_CONDITION+ if isinstance(condition, str):+ return OR_CONDITION+ return None-def _extract_all_trigger_names(- condition: str | dict[str, Any] | list[Any] | FlowCondition,-) -> list[str]:- """Extract ALL trigger names from a condition for display purposes.+def _runtime_condition_from_definition(+ condition: FlowDefinitionCondition,+) -> str | dict[str, Any]:+ if isinstance(condition, str):+ return condition+ condition_type, conditions = _definition_condition_parts(condition)+ return {+ "type": condition_type,+ "conditions": [_runtime_condition_from_definition(item) for item in conditions],+ }+++def _method_trigger_condition(+ method_definition: FlowMethodDefinition,+) -> FlowDefinitionCondition | None:+ if method_definition.listen is not None:+ return method_definition.listen+ if isinstance(method_definition.start, str | dict):+ return method_definition.start+ return None+++def _method_router_events(method_definition: FlowMethodDefinition) -> list[str]:+ if method_definition.human_feedback and method_definition.human_feedback.emit:+ return [str(event) for event in method_definition.human_feedback.emit]+ if method_definition.emit:+ return [str(event) for event in method_definition.emit]+ return []- Unlike _extract_direct_or_triggers, this extracts ALL strings and method- names from the entire condition tree, including those nested in AND conditions.- This is used for displaying trigger information in the UI.- For example:- - or_("a", "b") -> ["a", "b"]- - and_("a", "b") -> ["a", "b"]- - or_(and_("a", method_6), method_4) -> ["a", "method_6", "method_4"]+def _extract_direct_or_triggers(+ condition: FlowDefinitionCondition,+) -> list[str]:+ if isinstance(condition, str):+ return [condition]+ condition_type, conditions = _definition_condition_parts(condition)+ if condition_type == AND_CONDITION:+ return []+ strings: list[str] = []+ for sub_condition in conditions:+ strings.extend(_extract_direct_or_triggers(sub_condition))+ return strings- Args:- condition: Can be a string, dict, or list.- Returns:- List of all trigger names found in the condition.- """+def _extract_all_trigger_names(+ condition: FlowDefinitionCondition,+) -> list[str]:if isinstance(condition, str):return [condition]- if isinstance(condition, dict):- conditions_list = condition.get("conditions", [])- strings = []- for sub_cond in conditions_list:- strings.extend(_extract_all_trigger_names(sub_cond))- return strings- if isinstance(condition, list):- strings = []- for item in condition:- strings.extend(_extract_all_trigger_names(item))- return strings- if callable(condition) and hasattr(condition, "__name__"):- return [condition.__name__]- return []+ _, conditions = _definition_condition_parts(condition)+ strings: list[str] = []+ for sub_condition in conditions:+ strings.extend(_extract_all_trigger_names(sub_condition))+ return stringsdef _create_edges_from_condition(- condition: str | dict[str, Any] | list[Any] | FlowCondition,+ condition: FlowDefinitionCondition,target: str,nodes: dict[str, NodeMetadata],) -> list[StructureEdge]:- """Create edges from a condition tree, preserving AND/OR semantics.-- This function recursively processes the condition tree and creates edges- with the appropriate condition_type for each trigger.-- For AND conditions, all triggers get edges with condition_type="AND".- For OR conditions, triggers get edges with condition_type="OR".-- Args:- condition: The condition tree (string, dict, or list).- target: The target node name.- nodes: Dictionary of all nodes for validation.-- Returns:- List of StructureEdge objects representing the condition.- """edges: list[StructureEdge] = []if isinstance(condition, str):@@ -135,24 +122,11 @@ def _create_edges_from_condition(source=condition,target=target,condition_type=OR_CONDITION,- is_router_path=False,- )- )- elif callable(condition) and hasattr(condition, "__name__"):- method_name = condition.__name__- if method_name in nodes:- edges.append(- StructureEdge(- source=method_name,- target=target,- condition_type=OR_CONDITION,- is_router_path=False,+ is_router_event=False,))elif isinstance(condition, dict):- cond_type = condition.get("type", OR_CONDITION)- conditions_list = condition.get("conditions", [])-+ cond_type, conditions = _definition_condition_parts(condition)if cond_type == AND_CONDITION:triggers = _extract_all_trigger_names(condition)edges.extend(@@ -160,277 +134,144 @@ def _create_edges_from_condition(source=trigger,target=target,condition_type=AND_CONDITION,- is_router_path=False,+ is_router_event=False,)for trigger in triggersif trigger in nodes)else:- for sub_cond in conditions_list:- edges.extend(_create_edges_from_condition(sub_cond, target, nodes))- elif isinstance(condition, list):- for item in condition:- edges.extend(_create_edges_from_condition(item, target, nodes))+ for sub_condition in conditions:+ edges.extend(_create_edges_from_condition(sub_condition, target, nodes))return edges-def build_flow_structure(flow: Flow[Any]) -> FlowStructure:- """Build a structure representation of a Flow's execution.+def _flow_definition_from(+ flow_or_definition: Flow[Any] | type[Flow[Any]] | FlowDefinition,+) -> FlowDefinition:+ if isinstance(flow_or_definition, FlowDefinition):+ return flow_or_definition- Args:- flow: Flow instance to analyze.+ flow_class = (+ flow_or_definition+ if isinstance(flow_or_definition, type)+ else type(flow_or_definition)+ )+ flow_definition = getattr(flow_class, "flow_definition", None)+ if callable(flow_definition):+ return cast(FlowDefinition, flow_definition())+ raise TypeError(+ "build_flow_structure requires a FlowDefinition or a Flow class/instance "+ "with flow_definition()."+ )- Returns:- Dictionary with nodes, edges, start_methods, and router_methods.- """++def build_flow_structure(+ flow_or_definition: Flow[Any] | type[Flow[Any]] | FlowDefinition,+) -> FlowStructure:+ """Build a visualization structure projection from a FlowDefinition."""+ definition = _flow_definition_from(flow_or_definition)nodes: dict[str, NodeMetadata] = {}edges: list[StructureEdge] = []start_methods: list[str] = []router_methods: list[str] = []- for method_name, method in flow._methods.items():- node_metadata: NodeMetadata = {"type": "listen"}+ for method_name, method_definition in definition.methods.items():+ node_metadata: NodeMetadata = {"type": "listen", "class_name": definition.name}- if hasattr(method, "__is_start_method__") and method.__is_start_method__:+ if method_definition.is_start:node_metadata["type"] = "start"start_methods.append(method_name)- if hasattr(method, "__is_router__") and method.__is_router__:+ if method_definition.router:node_metadata["is_router"] = Truenode_metadata["type"] = "router"router_methods.append(method_name)-- if method_name in flow._router_paths:- node_metadata["router_paths"] = [- str(p) for p in flow._router_paths[method_name]- ]-- if hasattr(method, "__trigger_methods__") and method.__trigger_methods__:- node_metadata["trigger_methods"] = [- str(m) for m in method.__trigger_methods__- ]-- if hasattr(method, "__condition_type__") and method.__condition_type__:- node_metadata["trigger_condition_type"] = method.__condition_type__- if "condition_type" not in node_metadata:- node_metadata["condition_type"] = method.__condition_type__+ router_events = _method_router_events(method_definition)+ if router_events:+ node_metadata["router_events"] = router_events++ trigger_condition = _method_trigger_condition(method_definition)+ condition_type = _condition_type_from_definition(trigger_condition)+ if condition_type is not None and trigger_condition is not None:+ node_metadata["trigger_condition_type"] = condition_type+ node_metadata["condition_type"] = condition_type+ extracted = _extract_all_trigger_names(trigger_condition)+ if extracted:+ node_metadata["trigger_methods"] = extracted+ runtime_condition = _runtime_condition_from_definition(trigger_condition)+ if isinstance(runtime_condition, dict):+ node_metadata["trigger_condition"] = runtime_conditionif node_metadata.get("is_router") and "condition_type" not in node_metadata:node_metadata["condition_type"] = "IF"- if (- hasattr(method, "__trigger_condition__")- and method.__trigger_condition__ is not None- ):- node_metadata["trigger_condition"] = method.__trigger_condition__-- if "trigger_methods" not in node_metadata:- extracted = _extract_all_trigger_names(method.__trigger_condition__)- if extracted:- node_metadata["trigger_methods"] = extracted-- node_metadata["method_signature"] = extract_method_signature(- method, method_name- )-- try:- source_code = inspect.getsource(method)- node_metadata["source_code"] = source_code-- try:- source_lines, start_line = inspect.getsourcelines(method)- node_metadata["source_lines"] = source_lines- node_metadata["source_start_line"] = start_line- except (OSError, TypeError):- pass-- try:- source_file = inspect.getsourcefile(method)- if source_file:- node_metadata["source_file"] = source_file- except (OSError, TypeError):- try:- class_file = inspect.getsourcefile(flow.__class__)- if class_file:- node_metadata["source_file"] = class_file- except (OSError, TypeError):- pass- except (OSError, TypeError):- pass-- try:- class_obj = flow.__class__-- if class_obj:- class_name = class_obj.__name__-- bases = class_obj.__bases__- if bases:- base_strs = []- for base in bases:- if hasattr(base, "__name__"):- if hasattr(base, "__origin__"):- base_strs.append(str(base))- else:- base_strs.append(base.__name__)- else:- base_strs.append(str(base))-- try:- source_lines = inspect.getsource(class_obj).split("\n")- _, class_start_line = inspect.getsourcelines(class_obj)-- for idx, line in enumerate(source_lines):- stripped = line.strip()- if stripped.startswith("class ") and class_name in stripped:- class_signature = stripped.rstrip(":")- node_metadata["class_signature"] = class_signature- node_metadata["class_line_number"] = (- class_start_line + idx- )- break- except (OSError, TypeError):- class_signature = f"class {class_name}({', '.join(base_strs)})"- node_metadata["class_signature"] = class_signature- else:- class_signature = f"class {class_name}"- node_metadata["class_signature"] = class_signature-- node_metadata["class_name"] = class_name- except (OSError, TypeError, AttributeError):- pass-nodes[method_name] = node_metadata- for listener_name, condition_data in flow._listeners.items():- if listener_name in router_methods:+ for method_name, method_definition in definition.methods.items():+ trigger_condition = _method_trigger_condition(method_definition)+ if trigger_condition is None:continue-- if is_simple_flow_condition(condition_data):- cond_type, methods = condition_data- edges.extend(- StructureEdge(- source=str(trigger_method),- target=str(listener_name),- condition_type=cond_type,- is_router_path=False,- )- for trigger_method in methods- if str(trigger_method) in nodes- )- elif is_flow_condition_dict(condition_data):- edges.extend(- _create_edges_from_condition(condition_data, str(listener_name), nodes)- )-- for method_name, node_metadata in nodes.items(): # type: ignore[assignment]- if node_metadata.get("is_router") and "trigger_methods" in node_metadata:- trigger_methods = node_metadata["trigger_methods"]- condition_type = node_metadata.get("trigger_condition_type", OR_CONDITION)-- if "trigger_condition" in node_metadata:- edges.extend(- _create_edges_from_condition(- node_metadata["trigger_condition"], # type: ignore[arg-type]- method_name,- nodes,- )- )- else:- edges.extend(- StructureEdge(- source=trigger_method,- target=method_name,- condition_type=condition_type,- is_router_path=False,- )- for trigger_method in trigger_methods- if trigger_method in nodes- )+ edges.extend(+ _create_edges_from_condition(trigger_condition, method_name, nodes)+ )all_string_triggers: set[str] = set()- for condition_data in flow._listeners.values():- if is_simple_flow_condition(condition_data):- _, methods = condition_data- for m in methods:- if str(m) not in nodes: # It's a string trigger, not a method name- all_string_triggers.add(str(m))- elif is_flow_condition_dict(condition_data):- for trigger in _extract_direct_or_triggers(condition_data):- if trigger not in nodes:- all_string_triggers.add(trigger)-- all_router_outputs: set[str] = set()- for router_method_name in router_methods:- if router_method_name not in flow._router_paths:- flow._router_paths[FlowMethodName(router_method_name)] = []+ for method_definition in definition.methods.values():+ trigger_condition = _method_trigger_condition(method_definition)+ if trigger_condition is None:+ continue+ for trigger in _extract_direct_or_triggers(trigger_condition):+ if trigger not in nodes:+ all_string_triggers.add(trigger)- current_paths = flow._router_paths.get(FlowMethodName(router_method_name), [])- if current_paths and router_method_name in nodes:- nodes[router_method_name]["router_paths"] = [str(p) for p in current_paths]- all_router_outputs.update(str(p) for p in current_paths)+ all_router_events: set[str] = set()+ for router_method_name in router_methods:+ router_events = _method_router_events(definition.methods[router_method_name])+ if router_events and router_method_name in nodes:+ nodes[router_method_name]["router_events"] = router_events+ all_router_events.update(router_events)- if not current_paths:+ if not router_events:logger.warning(- f"Could not determine return paths for router '{router_method_name}'. "- f"Add a return type annotation like "- f"'-> Literal[\"path1\", \"path2\"]' or '-> YourEnum' "- f"to enable proper flow visualization."+ f"Router events for '{router_method_name}' are dynamic or not "+ f"statically inferable; static visualization may omit event edges.")- orphaned_triggers = all_string_triggers - all_router_outputs+ orphaned_triggers = all_string_triggers - all_router_eventsif orphaned_triggers:- logger.error(- f"Found listeners waiting for triggers {orphaned_triggers} "- f"but no router outputs these values explicitly. "- f"If your router returns a non-static value, check that your router has proper return type annotations."+ logger.warning(+ f"Static visualization could not match listener triggers "+ f"{orphaned_triggers} to explicit router events. "+ f"Dynamic router values may still trigger these listeners at runtime.")for router_method_name in router_methods:- if router_method_name not in flow._router_paths:- continue-- router_paths = flow._router_paths[FlowMethodName(router_method_name)]+ router_events = _method_router_events(definition.methods[router_method_name])- for path in router_paths:- for listener_name, condition_data in flow._listeners.items():+ for event in router_events:+ for listener_name, method_definition in definition.methods.items():if listener_name == router_method_name:continue- trigger_strings_from_cond: list[str] = []-- if is_simple_flow_condition(condition_data):- _, methods = condition_data- trigger_strings_from_cond = [str(m) for m in methods]- elif is_flow_condition_dict(condition_data):- trigger_strings_from_cond = _extract_direct_or_triggers(- condition_data- )+ trigger_condition = _method_trigger_condition(method_definition)+ if trigger_condition is None:+ continue+ trigger_strings_from_cond = _extract_direct_or_triggers(+ trigger_condition+ )- if str(path) in trigger_strings_from_cond:+ if str(event) in trigger_strings_from_cond:edges.append(StructureEdge(source=router_method_name,- target=str(listener_name),+ target=listener_name,condition_type=None,- is_router_path=True,- router_path_label=str(path),+ is_router_event=True,+ router_event=str(event),))- for start_method in flow._start_methods:- if start_method not in nodes and start_method in flow._methods:- method = flow._methods[start_method]- nodes[str(start_method)] = NodeMetadata(type="start")-- if hasattr(method, "__trigger_methods__") and method.__trigger_methods__:- nodes[str(start_method)]["trigger_methods"] = [- str(m) for m in method.__trigger_methods__- ]- if hasattr(method, "__condition_type__") and method.__condition_type__:- nodes[str(start_method)]["condition_type"] = method.__condition_type__-return FlowStructure(nodes=nodes,edges=edges,@@ -453,7 +294,7 @@ def calculate_execution_paths(structure: FlowStructure) -> int:graph[edge["source"]].append({"target": edge["target"],- "is_router": edge["is_router_path"],+ "is_router": edge["is_router_event"],"condition": edge["condition_type"],})@@ -466,15 +307,6 @@ def calculate_execution_paths(structure: FlowStructure) -> int:return 0def count_paths_from(node: str, visited: set[str]) -> int:- """Recursively count execution paths from a given node.-- Args:- node: Node name to start counting from.- visited: Set of already visited nodes to prevent cycles.-- Returns:- Number of execution paths from this node to terminal nodes.- """if node in terminal_nodes:return 1diff --git a/lib/crewai/src/crewai/flow/visualization/renderers/interactive.py b/lib/crewai/src/crewai/flow/visualization/renderers/interactive.pyindex 88242bea6..0ad8943f1 100644--- a/lib/crewai/src/crewai/flow/visualization/renderers/interactive.py+++ b/lib/crewai/src/crewai/flow/visualization/renderers/interactive.py@@ -309,18 +309,18 @@ def render_interactive(</div>""")- if metadata.get("router_paths"):- paths = metadata["router_paths"]- paths_items = "".join(+ if metadata.get("router_events"):+ router_events = metadata["router_events"]+ event_items = "".join([f'<li style="margin: 3px 0;"><code style="background: rgba(255,90,80,0.08); padding: 2px 6px; border-radius: 3px; font-size: 10px; color: {CREWAI_ORANGE}; border: 1px solid rgba(255,90,80,0.2); font-weight: 600;">{p}</code></li>'- for p in paths+ for p in router_events])title_parts.append(f"""<div>- <div style="font-size: 10px; text-transform: uppercase; color: {GRAY}; letter-spacing: 0.5px; margin-bottom: 4px; font-weight: 600;">Router Paths</div>- <ul style="list-style: none; padding: 0; margin: 0;">{paths_items}</ul>+ <div style="font-size: 10px; text-transform: uppercase; color: {GRAY}; letter-spacing: 0.5px; margin-bottom: 4px; font-weight: 600;">Router Events</div>+ <ul style="list-style: none; padding: 0; margin: 0;">{event_items}</ul></div>""")@@ -364,11 +364,11 @@ def render_interactive(edge_color: str = GRAYedge_dashes: bool | list[int] = False- if edge["is_router_path"]:+ if edge["is_router_event"]:edge_color = CREWAI_ORANGEedge_dashes = [15, 10]- if "router_path_label" in edge:- edge_label = edge["router_path_label"]+ if "router_event" in edge:+ edge_label = edge["router_event"] or ""elif edge["condition_type"] == "AND":edge_label = "AND"edge_color = CREWAI_ORANGEdiff --git a/lib/crewai/src/crewai/flow/visualization/schema.py b/lib/crewai/src/crewai/flow/visualization/schema.pydeleted file mode 100644index fe0de7fd1..000000000--- a/lib/crewai/src/crewai/flow/visualization/schema.py+++ /dev/null@@ -1,104 +0,0 @@-"""OpenAPI schema conversion utilities for Flow methods."""--import inspect-from typing import Any, get_args, get_origin---def type_to_openapi_schema(type_hint: Any) -> dict[str, Any]:- """Convert Python type hint to OpenAPI schema.-- Args:- type_hint: Python type hint to convert.-- Returns:- OpenAPI schema dictionary.- """- if type_hint is inspect.Parameter.empty:- return {}-- if type_hint is None or type_hint is type(None):- return {"type": "null"}-- if hasattr(type_hint, "__module__") and hasattr(type_hint, "__name__"):- if type_hint.__module__ == "typing" and type_hint.__name__ == "Any":- return {}-- type_str = str(type_hint)- if type_str == "typing.Any" or type_str == "<class 'typing.Any'>":- return {}-- if isinstance(type_hint, str):- return {"type": type_hint}-- origin = get_origin(type_hint)- args = get_args(type_hint)-- if type_hint is str:- return {"type": "string"}- if type_hint is int:- return {"type": "integer"}- if type_hint is float:- return {"type": "number"}- if type_hint is bool:- return {"type": "boolean"}- if type_hint is dict or origin is dict:- if args and len(args) > 1:- return {- "type": "object",- "additionalProperties": type_to_openapi_schema(args[1]),- }- return {"type": "object"}- if type_hint is list or origin is list:- if args:- return {"type": "array", "items": type_to_openapi_schema(args[0])}- return {"type": "array"}- if hasattr(type_hint, "__name__"):- return {"type": "object", "className": type_hint.__name__}-- return {}---def extract_method_signature(method: Any, method_name: str) -> dict[str, Any]:- """Extract method signature as OpenAPI schema with documentation.-- Args:- method: Method to analyze.- method_name: Method name.-- Returns:- Dictionary with operationId, parameters, returns, summary, and description.- """- try:- sig = inspect.signature(method)-- parameters = {}- for param_name, param in sig.parameters.items():- if param_name == "self":- continue- parameters[param_name] = type_to_openapi_schema(param.annotation)-- return_type = type_to_openapi_schema(sig.return_annotation)-- docstring = inspect.getdoc(method)-- result: dict[str, Any] = {- "operationId": method_name,- "parameters": parameters,- "returns": return_type,- }-- if docstring:- lines = docstring.strip().split("\n")- summary = lines[0].strip()-- if summary:- result["summary"] = summary-- if len(lines) > 1:- description = "\n".join(line.strip() for line in lines[1:]).strip()- if description:- result["description"] = description-- return result- except Exception:- return {"operationId": method_name, "parameters": {}, "returns": {}}diff --git a/lib/crewai/src/crewai/flow/visualization/types.py b/lib/crewai/src/crewai/flow/visualization/types.pyindex 6ce57069e..6fe01589a 100644--- a/lib/crewai/src/crewai/flow/visualization/types.py+++ b/lib/crewai/src/crewai/flow/visualization/types.py@@ -1,6 +1,11 @@"""Type definitions for Flow structure visualization."""-from typing import Any, TypedDict+from typing import Any++from typing_extensions import Required, TypedDict+++__all__ = ["FlowStructure", "NodeMetadata", "StructureEdge"]class NodeMetadata(TypedDict, total=False):@@ -8,19 +13,12 @@ class NodeMetadata(TypedDict, total=False):type: stris_router: bool- router_paths: list[str]+ router_events: list[str]condition_type: str | Nonetrigger_condition_type: str | Nonetrigger_methods: list[str]trigger_condition: dict[str, Any] | None- method_signature: dict[str, Any]- source_code: str- source_lines: list[str]- source_start_line: int- source_file: str- class_signature: strclass_name: str- class_line_number: intclass StructureEdge(TypedDict, total=False):@@ -29,8 +27,8 @@ class StructureEdge(TypedDict, total=False):source: strtarget: strcondition_type: str | None- is_router_path: bool- router_path_label: str+ is_router_event: Required[bool]+ router_event: str | Noneclass FlowStructure(TypedDict):diff --git a/lib/crewai/tests/test_async_human_feedback.py b/lib/crewai/tests/test_async_human_feedback.pyindex fbd047ccf..19b682405 100644--- a/lib/crewai/tests/test_async_human_feedback.py+++ b/lib/crewai/tests/test_async_human_feedback.py@@ -1012,7 +1012,7 @@ class TestLLMObjectPreservedInContext:call_kwargs = mock_collapse.call_argsassert call_kwargs.kwargs["feedback"] == "this looks good, proceed!"assert call_kwargs.kwargs["outcomes"] == ["needs_changes", "approved"]- # LLM should be a live object (from _hf_llm) or reconstructed, not None+ # LLM should be a live object (from _human_feedback_llm) or reconstructed, not Noneassert call_kwargs.kwargs["llm"] is not Noneassert getattr(call_kwargs.kwargs["llm"], "model", None) == "gemini-2.0-flash"assert flow2.last_human_feedback.outcome == "approved"@@ -1171,8 +1171,8 @@ class TestAsyncHumanFeedbackEdgeCases:class TestLiveLLMPreservationOnResume:"""Tests for preserving the full LLM config across HITL resume."""- def test_hf_llm_attribute_set_on_wrapper_with_basellm(self) -> None:- """Test that _hf_llm is set on the wrapper when llm is a BaseLLM instance."""+ def test_human_feedback_llm_attribute_set_on_wrapper_with_basellm(self) -> None:+ """Test that _human_feedback_llm is set on the wrapper when llm is a BaseLLM instance."""from crewai.llms.base_llm import BaseLLMmock_llm = MagicMock(spec=BaseLLM)@@ -1191,11 +1191,11 @@ class TestLiveLLMPreservationOnResume:flow = TestFlow()method = flow._methods.get("review")assert method is not None- assert hasattr(method, "_hf_llm")- assert method._hf_llm is mock_llm+ assert hasattr(method, "_human_feedback_llm")+ assert method._human_feedback_llm is mock_llm- def test_hf_llm_attribute_set_on_wrapper_with_string(self) -> None:- """Test that _hf_llm is set on the wrapper even when llm is a string."""+ def test_human_feedback_llm_attribute_set_on_wrapper_with_string(self) -> None:+ """Test that _human_feedback_llm is set on the wrapper even when llm is a string."""class TestFlow(Flow):@start()@@ -1210,8 +1210,8 @@ class TestLiveLLMPreservationOnResume:flow = TestFlow()method = flow._methods.get("review")assert method is not None- assert hasattr(method, "_hf_llm")- assert method._hf_llm == "gpt-4o-mini"+ assert hasattr(method, "_human_feedback_llm")+ assert method._human_feedback_llm == "gpt-4o-mini"@patch("crewai.flow.runtime.crewai_event_bus.emit")def test_resume_async_uses_live_basellm_over_serialized_string(@@ -1277,20 +1277,20 @@ class TestLiveLLMPreservationOnResume:flow.resume("looks good!")# NOT the serialized string. The live_llm was captured at class definition- # time and stored on the method wrapper as _hf_llm.+ # time and stored on the method wrapper as _human_feedback_llm.assert len(captured_llm) == 1- # (which is stored on the method's _hf_llm attribute)+ # (which is stored on the method's _human_feedback_llm attribute)method = flow._methods.get("review")assert method is not None- assert captured_llm[0] is method._hf_llm+ assert captured_llm[0] is method._human_feedback_llm# And verify it's a BaseLLM instance, not a stringassert isinstance(captured_llm[0], BaseLLM)@patch("crewai.flow.runtime.crewai_event_bus.emit")- def test_resume_async_falls_back_to_serialized_string_when_no_hf_llm(+ def test_resume_async_falls_back_to_serialized_string_when_no_human_feedback_llm(self, mock_emit: MagicMock) -> None:- """Test that resume_async falls back to context.llm when _hf_llm is not available.+ """Test that resume_async falls back to context.llm when _human_feedback_llm is not available.This ensures backward compatibility with flows that were paused before this fix."""@@ -1325,10 +1325,10 @@ class TestLiveLLMPreservationOnResume:flow = TestFlow.from_pending("fallback-test", persistence)- # Remove _hf_llm to simulate old decorator without this attribute+ # Remove _human_feedback_llm to simulate old decorator without this attributemethod = flow._methods.get("review")- if hasattr(method, "_hf_llm"):- delattr(method, "_hf_llm")+ if hasattr(method, "_human_feedback_llm"):+ delattr(method, "_human_feedback_llm")captured_llm = []@@ -1345,10 +1345,10 @@ class TestLiveLLMPreservationOnResume:assert captured_llm[0].model == "gpt-4o-mini"@patch("crewai.flow.runtime.crewai_event_bus.emit")- def test_resume_async_uses_string_from_context_when_hf_llm_is_string(+ def test_resume_async_uses_string_from_context_when_human_feedback_llm_is_string(self, mock_emit: MagicMock) -> None:- """Test that when _hf_llm is a string (not BaseLLM), we still use context.llm.+ """Test that when _human_feedback_llm is a string (not BaseLLM), we still use context.llm.String LLM values offer no benefit over the serialized context.llm,so we don't prefer them.@@ -1385,7 +1385,7 @@ class TestLiveLLMPreservationOnResume:flow = TestFlow.from_pending("string-llm-test", persistence)method = flow._methods.get("review")- assert method._hf_llm == "gpt-4o-mini"+ assert method._human_feedback_llm == "gpt-4o-mini"captured_llm = []@@ -1396,14 +1396,14 @@ class TestLiveLLMPreservationOnResume:with patch.object(flow, "_collapse_to_outcome", side_effect=capture_llm):flow.resume("looks good!")- # _hf_llm is a string, so resume deserializes context.llm into an LLM instance+ # _human_feedback_llm is a string, so resume deserializes context.llm into an LLM instanceassert len(captured_llm) == 1from crewai.llms.base_llm import BaseLLM as BaseLLMClassassert isinstance(captured_llm[0], BaseLLMClass)assert captured_llm[0].model == "gpt-4o-mini"- def test_hf_llm_set_for_async_wrapper(self) -> None:- """Test that _hf_llm is set on async wrapper functions."""+ def test_human_feedback_llm_set_for_async_wrapper(self) -> None:+ """Test that _human_feedback_llm is set on async wrapper functions."""import asynciofrom crewai.llms.base_llm import BaseLLM@@ -1423,5 +1423,5 @@ class TestLiveLLMPreservationOnResume:flow = TestFlow()method = flow._methods.get("async_review")assert method is not None- assert hasattr(method, "_hf_llm")- assert method._hf_llm is mock_llm+ assert hasattr(method, "_human_feedback_llm")+ assert method._human_feedback_llm is mock_llmdiff --git a/lib/crewai/tests/test_flow.py b/lib/crewai/tests/test_flow.pyindex bc9a4ab87..e5eaade21 100644--- a/lib/crewai/tests/test_flow.py+++ b/lib/crewai/tests/test_flow.py@@ -1160,9 +1160,9 @@ def test_router_cascade_chain():@router(process_level_1)def router_level_2(self):execution_order.append("router_level_2")- return "level_2_path"+ return "level_2_event"- @listen("level_2_path")+ @listen("level_2_event")def process_level_2(self):execution_order.append("process_level_2")self.state["level"] = 3@@ -1171,9 +1171,9 @@ def test_router_cascade_chain():@router(process_level_2)def router_level_3(self):execution_order.append("router_level_3")- return "final_path"+ return "final_event"- @listen("final_path")+ @listen("final_event")def finalize(self):execution_order.append("finalize")return "complete"@@ -1261,14 +1261,14 @@ def test_complex_and_or_branching():assert execution_order.index("final") > execution_order.index("branch_2b")-def test_conditional_router_paths_exclusivity():- """Test that only the returned router path activates, not all paths."""+def test_conditional_router_events_exclusivity():+ """Test that only the returned router event activates, not all events."""execution_order = []class ConditionalRouterFlow(Flow):def __init__(self):super().__init__()- self.state["condition"] = "take_path_b"+ self.state["condition"] = "take_event_b"@start()def begin(self):@@ -1277,33 +1277,33 @@ def test_conditional_router_paths_exclusivity():@router(begin)def decision_point(self):execution_order.append("decision_point")- if self.state["condition"] == "take_path_a":- return "path_a"- elif self.state["condition"] == "take_path_b":- return "path_b"+ if self.state["condition"] == "take_event_a":+ return "event_a"+ elif self.state["condition"] == "take_event_b":+ return "event_b"else:- return "path_c"+ return "event_c"- @listen("path_a")- def handle_path_a(self):- execution_order.append("handle_path_a")+ @listen("event_a")+ def handle_event_a(self):+ execution_order.append("handle_event_a")- @listen("path_b")- def handle_path_b(self):- execution_order.append("handle_path_b")+ @listen("event_b")+ def handle_event_b(self):+ execution_order.append("handle_event_b")- @listen("path_c")- def handle_path_c(self):- execution_order.append("handle_path_c")+ @listen("event_c")+ def handle_event_c(self):+ execution_order.append("handle_event_c")flow = ConditionalRouterFlow()flow.kickoff()assert "begin" in execution_orderassert "decision_point" in execution_order- assert "handle_path_b" in execution_order- assert "handle_path_a" not in execution_order- assert "handle_path_c" not in execution_order+ assert "handle_event_b" in execution_order+ assert "handle_event_a" not in execution_order+ assert "handle_event_c" not in execution_orderdef test_state_consistency_across_parallel_branches():diff --git a/lib/crewai/tests/test_flow_definition.py b/lib/crewai/tests/test_flow_definition.pynew file mode 100644index 000000000..a02036f66--- /dev/null+++ b/lib/crewai/tests/test_flow_definition.py@@ -0,0 +1,839 @@+"""Tests for the static Flow Definition contract."""++import ast+from enum import Enum+import importlib+import inspect+import logging+from pathlib import Path+from typing import Annotated, Literal++from pydantic import BaseModel++import crewai.flow.dsl as flow_dsl+import crewai.flow.flow_definition as flow_definition+import crewai.flow.visualization.builder as visualization_builder+from crewai.flow import Flow, and_, human_feedback, listen, or_, persist, router, start+++def test_flow_public_exports_are_explicit():+ import crewai.flow.visualization as flow_visualization++ flow_package = importlib.import_module("crewai.flow")++ assert "FlowDefinition" not in flow_package.__all__+ assert "FlowDefinitionDiagnostic" not in flow_package.__all__+ assert "build_flow_definition" not in flow_package.__all__+ assert "flow_structure" not in flow_package.__all__+ assert set(flow_dsl.__all__) == {"and_", "listen", "or_", "router", "start"}+ assert set(flow_definition.__all__) == {+ "FlowConfigDefinition",+ "FlowDefinition",+ "FlowDefinitionCondition",+ "FlowDefinitionDiagnostic",+ "FlowHumanFeedbackDefinition",+ "FlowMethodDefinition",+ "FlowPersistenceDefinition",+ "FlowStateDefinition",+ }+ assert "build_flow_structure" in flow_visualization.__all__+ assert "calculate_node_levels" not in flow_visualization.__all__+++def test_private_flow_helpers_do_not_have_docstrings():+ import crewai.flow.flow_wrappers as flow_wrappers+ import crewai.flow.human_feedback as human_feedback+ import crewai.flow.persistence.decorators as persistence_decorators+ import crewai.flow.visualization.types as visualization_types++ modules = [+ flow_dsl,+ flow_definition,+ flow_wrappers,+ human_feedback,+ persistence_decorators,+ visualization_builder,+ visualization_types,+ ]+ violations: list[str] = []++ for module in modules:+ source_path = Path(inspect.getsourcefile(module) or "")+ tree = ast.parse(source_path.read_text())+ stack: list[ast.AST] = []+ if getattr(module, "__all__", None) == [] and ast.get_docstring(tree):+ violations.append(f"{source_path}:1:<module>")++ class PrivateDocstringVisitor(ast.NodeVisitor):+ def visit_ClassDef(self, node: ast.ClassDef) -> None:+ self._check_docstring(node)+ stack.append(node)+ self.generic_visit(node)+ stack.pop()++ def visit_FunctionDef(self, node: ast.FunctionDef) -> None:+ self._check_docstring(node)+ stack.append(node)+ self.generic_visit(node)+ stack.pop()++ def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:+ self._check_docstring(node)+ stack.append(node)+ self.generic_visit(node)+ stack.pop()++ def _check_docstring(+ self,+ node: ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef,+ ) -> None:+ is_dunder = node.name.startswith("__") and node.name.endswith("__")+ is_private_name = node.name.startswith("_") and not is_dunder+ is_nested_function = any(+ isinstance(parent, (ast.FunctionDef, ast.AsyncFunctionDef))+ for parent in stack+ )+ if (is_private_name or is_nested_function) and ast.get_docstring(node):+ violations.append(f"{source_path}:{node.lineno}:{node.name}")++ PrivateDocstringVisitor().visit(tree)++ assert violations == []+++def test_flow_definition_contract_is_dsl_agnostic():+ source_path = Path(inspect.getsourcefile(flow_definition) or "")+ source = source_path.read_text()++ assert "DSL" not in source+ assert "flow_wrappers" not in source+ assert "build_flow_definition" not in source+ assert "extract_flow_definition" not in source+++def test_flow_definition_maps_dsl_to_static_contract():+ class ContractState(BaseModel):+ topic: str = ""++ class ContractFlow(Flow[ContractState]):+ """A flow with every core DSL role."""++ initial_state = ContractState+ stream = True+ max_method_calls = 7++ @start()+ def begin(self):+ return "started"++ @listen(begin)+ def process(self):+ return "processed"++ @router(process)+ def decide(self):+ return "approved"++ @listen(or_("approved", "revise"))+ @human_feedback(+ message="Review this output.",+ emit=["done", "revise"],+ llm="gpt-4o-mini",+ default_outcome="done",+ metadata={"team": "qa"},+ learn=True,+ learn_source="hitl",+ learn_strict=True,+ )+ def review(self):+ return "review"++ @listen(and_(begin, process))+ def audit(self):+ return "audit"++ definition = ContractFlow.flow_definition()++ assert definition.schema_ == "crewai.flow/v1"+ assert definition.name == "ContractFlow"+ assert definition.description == "A flow with every core DSL role."+ assert definition.state is not None+ assert definition.state.type == "pydantic"+ assert definition.state.ref and "ContractState" in definition.state.ref+ assert definition.config.stream is True+ assert definition.config.max_method_calls == 7++ assert definition.methods["begin"].start is True+ assert definition.methods["process"].listen == "begin"++ decide = definition.methods["decide"]+ assert decide.listen == "process"+ assert decide.router is True+ assert decide.emit is None++ review = definition.methods["review"]+ assert review.listen == {"or": ["approved", "revise"]}+ assert review.router is True+ assert review.emit is None+ assert review.human_feedback is not None+ assert review.human_feedback.emit == ["done", "revise"]+ assert review.human_feedback.default_outcome == "done"+ assert review.human_feedback.metadata == {"team": "qa"}+ assert review.human_feedback.learn is True+ assert review.human_feedback.learn_strict is True++ assert definition.methods["audit"].listen == {"and": ["begin", "process"]}+ assert definition.diagnostics == []+++def test_flow_definition_excludes_conversational_builtins_for_regular_flows():+ class RegularFlow(Flow):+ @start()+ def begin(self):+ return "begin"++ methods = RegularFlow.flow_definition().methods++ assert set(methods) == {"begin"}+ assert "conversation_start" not in methods+ assert "route_conversation" not in methods+ assert "converse_turn" not in methods+++def test_flow_definition_includes_conversational_builtins_when_enabled():+ class ChatFlow(Flow):+ conversational = True++ methods = ChatFlow.flow_definition().methods++ assert "conversation_start" in methods+ assert "route_conversation" in methods+ assert "converse_turn" in methods+ assert methods["conversation_start"].start is True+++def test_flow_definition_serializes_human_feedback_metadata():+ marker = object()++ class MetadataFlow(Flow):+ @start()+ def begin(self):+ return "started"++ @listen(begin)+ @human_feedback(message="Review this output.", metadata={"marker": marker})+ def review(self):+ return "review"++ definition = MetadataFlow.flow_definition()+ review = definition.methods["review"]++ assert review.human_feedback is not None+ assert review.human_feedback.metadata == {"ref": "builtins:dict"}+ assert any(+ diagnostic.code == "non_serializable_value"+ and diagnostic.path == "methods.review.human_feedback.metadata"+ for diagnostic in definition.diagnostics+ )+ definition.to_json()+++def test_flow_definition_fragments_cover_start_listen_and_condition_sugar():+ class FragmentFlow(Flow):+ @start()+ def begin(self):+ return "begin"++ @start("restart_event")+ def restart(self):+ return "restart"++ @listen(begin)+ def by_callable(self):+ return "callable"++ @listen("manual_event")+ def by_string(self):+ return "string"++ @listen(and_(begin, by_callable))+ def by_and(self):+ return "and"++ @listen(or_(and_("manual_event", by_string), "fallback_event"))+ def nested(self):+ return "nested"++ definition = FragmentFlow.flow_definition()++ assert definition.methods["begin"].start is True+ assert definition.methods["restart"].start == "restart_event"+ assert definition.methods["by_callable"].listen == "begin"+ assert definition.methods["by_string"].listen == "manual_event"+ assert definition.methods["by_and"].listen == {"and": ["begin", "by_callable"]}+ assert definition.methods["nested"].listen == {+ "or": [{"and": ["manual_event", "by_string"]}, "fallback_event"]+ }++ assert set(FragmentFlow._start_methods) == {"begin", "restart"}+ assert FragmentFlow._listeners["restart"] == ("OR", ["restart_event"])+ assert FragmentFlow._listeners["by_callable"] == ("OR", ["begin"])+ assert FragmentFlow._listeners["by_string"] == ("OR", ["manual_event"])+ assert FragmentFlow._listeners["by_and"] == {+ "type": "AND",+ "conditions": ["begin", "by_callable"],+ }+ assert FragmentFlow._listeners["nested"] == {+ "type": "OR",+ "conditions": [+ {"type": "AND", "conditions": ["manual_event", "by_string"]},+ "fallback_event",+ ],+ }+++def test_extract_flow_definition_prefers_fragments_over_legacy_metadata():+ class RegistryFlow(Flow):+ @start()+ def begin(self):+ return "begin"++ @listen(begin)+ def handle(self):+ return "handle"++ @router(handle, emit=["done"])+ def decide(self):+ return "done"++ handle = RegistryFlow.__dict__["handle"]+ original_trigger_methods = handle.__trigger_methods__+ handle.__trigger_methods__ = ["wrong"]+ try:+ _, listeners, routers, router_emit = flow_dsl.extract_flow_definition(+ {+ "begin": RegistryFlow.__dict__["begin"],+ "handle": handle,+ "decide": RegistryFlow.__dict__["decide"],+ }+ )+ finally:+ handle.__trigger_methods__ = original_trigger_methods++ assert listeners["handle"] == ("OR", ["begin"])+ assert listeners["decide"] == ("OR", ["handle"])+ assert routers == {"decide"}+ assert router_emit == {"decide": ["done"]}+++def test_flow_definition_falls_back_to_legacy_metadata_without_fragment():+ class LegacyMetadataFlow(Flow):+ @start()+ def begin(self):+ return "begin"++ @router(begin, emit=["left"])+ def decide(self):+ return "left"++ @listen("left")+ def left(self):+ return "left"++ for method_name in ("begin", "decide", "left"):+ method = LegacyMetadataFlow.__dict__[method_name]+ delattr(method, "__flow_method_definition__")++ definition = flow_dsl.build_flow_definition(LegacyMetadataFlow)++ assert definition.methods["begin"].start is True+ assert definition.methods["decide"].listen == "begin"+ assert definition.methods["decide"].router is True+ assert definition.methods["decide"].emit == ["left"]+ assert definition.methods["left"].listen == "left"+++def test_human_feedback_emit_overrides_inner_router_emit():+ class FeedbackOverRouterFlow(Flow):+ @start()+ def begin(self):+ return "data"++ @human_feedback(+ message="Review:",+ emit=["approved", "rejected"],+ llm="gpt-4o-mini",+ )+ @router(begin, emit=["x", "y"])+ def route(self):+ return "approved"++ @listen("approved")+ def proceed(self):+ return "ok"++ assert "route" in FeedbackOverRouterFlow._routers+ assert FeedbackOverRouterFlow._router_emit["route"] == ["approved", "rejected"]++ route = FeedbackOverRouterFlow.flow_definition().methods["route"]+ assert route.router is True+ assert route.human_feedback is not None+ assert route.human_feedback.emit == ["approved", "rejected"]+ assert route.emit is None+++def test_flow_definition_classifies_start_router_from_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"++ definition = StartRouterFlow.flow_definition()+ entry_point = definition.methods["entry_point"]++ assert entry_point.is_start is True+ assert entry_point.router is True+ assert entry_point.human_feedback is not None+ assert entry_point.human_feedback.emit == ["continue", "stop"]+ assert entry_point.emit is None+++def test_flow_definition_round_trips_json_and_yaml():+ class RoundTripFlow(Flow):+ @start()+ def begin(self):+ return "started"++ @router(begin)+ def decide(self):+ return "left"++ @listen("left")+ def left(self):+ return "left"++ definition = RoundTripFlow.flow_definition()++ json_round_trip = flow_definition.FlowDefinition.from_json(definition.to_json())+ yaml_round_trip = flow_definition.FlowDefinition.from_yaml(definition.to_yaml())++ assert json_round_trip.to_dict() == definition.to_dict()+ assert yaml_round_trip.to_dict() == definition.to_dict()+ assert yaml_round_trip.methods["decide"].router is True+ assert yaml_round_trip.methods["decide"].listen == "begin"+++def test_flow_definition_detects_persist_metadata():+ @persist(verbose=True)+ class PersistedFlow(Flow[dict]):+ initial_state = {}++ @start()+ def begin(self):+ return "started"++ @persist(verbose=False)+ @listen(begin)+ def checkpoint(self):+ return "saved"++ definition = PersistedFlow.flow_definition()++ assert definition.persist is not None+ assert definition.persist.enabled is True+ assert definition.persist.verbose is True++ assert definition.methods["begin"].persist is None++ method_persist = definition.methods["checkpoint"].persist+ assert method_persist is not None+ assert method_persist.enabled is True+ assert method_persist.verbose is False+++def test_flow_definition_allows_dynamic_router_emit():+ class DynamicRouterFlow(Flow):+ @start()+ def begin(self):+ return "started"++ @router(begin)+ def decide(self):+ return self.state["dynamic_event"]++ definition = DynamicRouterFlow.flow_definition()++ assert definition.methods["decide"].emit is None+ assert definition.diagnostics == []+++def test_flow_definition_infers_literal_router_emit():+ class LiteralRouterFlow(Flow):+ @start()+ def begin(self):+ return "started"++ @router(begin)+ def decide(self) -> Literal["left", "right"]:+ return "left"++ @listen("left")+ def left(self):+ return "left"++ @listen("right")+ def right(self):+ return "right"++ definition = LiteralRouterFlow.flow_definition()++ assert definition.methods["decide"].emit == ["left", "right"]+++def test_flow_definition_infers_enum_router_emit():+ class Decision(str, Enum):+ APPROVE = "approve"+ REJECT = "reject"++ class EnumRouterFlow(Flow):+ @start()+ def begin(self):+ return "started"++ @router(begin)+ def decide(self) -> Decision:+ return Decision.APPROVE++ @listen("approve")+ def approve(self):+ return "approve"++ @listen("reject")+ def reject(self):+ return "reject"++ definition = EnumRouterFlow.flow_definition()++ assert definition.methods["decide"].emit == ["approve", "reject"]+++def test_flow_definition_infers_literal_union_router_emit():+ class LiteralUnionRouterFlow(Flow):+ @start()+ def begin(self):+ return "started"++ @router(begin)+ def decide(self) -> Literal["left"] | Literal["right"]:+ return "left"++ @listen("left")+ def left(self):+ return "left"++ @listen("right")+ def right(self):+ return "right"++ definition = LiteralUnionRouterFlow.flow_definition()++ assert definition.methods["decide"].emit == ["left", "right"]+++def test_flow_definition_infers_annotated_literal_router_emit():+ class AnnotatedRouterFlow(Flow):+ @start()+ def begin(self):+ return "started"++ @router(begin)+ def decide(self) -> Annotated[Literal["left"] | None, "route"]:+ return "left"++ definition = AnnotatedRouterFlow.flow_definition()++ assert definition.methods["decide"].emit == ["left"]+++def test_flow_definition_does_not_infer_container_literal_router_emit():+ class ContainerLiteralRouterFlow(Flow):+ @start()+ def begin(self):+ return "started"++ @router(begin)+ def list_route(self) -> list[Literal["left"]]:+ return ["left"]++ @router(begin)+ def dict_route(self) -> dict[str, Literal["right"]]:+ return {"route": "right"}++ definition = ContainerLiteralRouterFlow.flow_definition()++ assert definition.methods["list_route"].emit is None+ assert definition.methods["dict_route"].emit is None+++def test_flow_definition_does_not_infer_unannotated_router_body_emit():+ class UnannotatedRouterFlow(Flow):+ @start()+ def begin(self):+ return "started"++ @router(begin)+ def decide(self):+ return "left"++ @listen("left")+ def left(self):+ return "left"++ definition = UnannotatedRouterFlow.flow_definition()++ assert definition.methods["decide"].emit is None+++def test_flow_definition_accepts_explicit_router_events():+ class ExplicitRouterFlow(Flow):+ @start()+ def begin(self):+ return "started"++ @router(begin, emit=["left", "right", "left"])+ def decide(self):+ return self.state["dynamic_event"]++ @listen("left")+ def left(self):+ return "left"++ @listen("right")+ def right(self):+ return "right"++ definition = ExplicitRouterFlow.flow_definition()++ assert definition.methods["decide"].emit == ["left", "right"]+++def test_flow_definition_preserves_diagnostics_loaded_from_contract():+ definition = flow_definition.FlowDefinition.from_dict(+ {+ "schema": "crewai.flow/v1",+ "name": "LoadedDiagnosticsFlow",+ "methods": {+ "decision": {+ "router": True,+ "emit": ["continue"],+ }+ },+ "diagnostics": [+ {+ "code": "serialized_warning",+ "message": "Preserved serialized diagnostic",+ "severity": "warning",+ "path": "methods.decision",+ },+ {+ "code": "router_without_trigger",+ "message": "router: true requires either start or listen",+ "severity": "error",+ "path": "methods.decision",+ },+ ],+ }+ )++ codes = [diagnostic.code for diagnostic in definition.diagnostics]+ assert "serialized_warning" in codes+ assert codes.count("router_without_trigger") == 1+++def test_router_start_false_without_listen_reports_missing_trigger():+ definition = flow_definition.FlowDefinition.from_dict(+ {+ "schema": "crewai.flow/v1",+ "name": "LoadedFlow",+ "methods": {+ "decision": {+ "router": True,+ "start": False,+ "emit": ["continue"],+ }+ },+ }+ )++ assert any(+ diagnostic.code == "router_without_trigger"+ and diagnostic.path == "methods.decision"+ for diagnostic in definition.diagnostics+ )+++def test_router_human_feedback_preserves_existing_router_metadata():+ class RouterHumanFeedbackFlow(Flow):+ @start()+ def begin(self):+ return "started"++ @human_feedback(message="Review route:")+ @router(begin, emit=["approved", "rejected"])+ def decide(self):+ return "approved"++ @listen("approved")+ def approved(self):+ return "approved"++ definition = RouterHumanFeedbackFlow.flow_definition()+ method = definition.methods["decide"]++ assert method.router is True+ assert method.listen == "begin"+ assert method.emit == ["approved", "rejected"]+ assert method.human_feedback is not None+++def test_dynamic_router_flow_definition_has_no_diagnostics():+ class LazyDynamicRouterFlow(Flow):+ @start()+ def begin(self):+ return "started"++ @router(begin)+ def decide(self):+ return self.state["dynamic_event"]++ definition = LazyDynamicRouterFlow.flow_definition()+ assert definition.diagnostics == []+++def test_dynamic_router_string_listener_is_valid_contract():+ class DynamicRouterListenerFlow(Flow):+ @start()+ def begin(self):+ return "started"++ @router(begin)+ def decide(self):+ return self.state["dynamic_event"]++ @listen("dynamic_event")+ def handle(self):+ return "handled"++ definition = DynamicRouterListenerFlow.flow_definition()++ assert definition.diagnostics == []+++def test_static_string_listener_is_allowed_by_contract():+ definition = flow_definition.FlowDefinition.from_dict(+ {+ "schema": "crewai.flow/v1",+ "name": "TypoFlow",+ "methods": {+ "begin": {"start": True},+ "handle": {"listen": "begni"},+ },+ }+ )+ assert definition.diagnostics == []+++def test_start_false_not_classified_as_start_method():+ definition = flow_definition.FlowDefinition.from_dict(+ {+ "schema": "crewai.flow/v1",+ "name": "ExplicitNonStartFlow",+ "methods": {+ "begin": {"start": True},+ "handle": {"start": False, "listen": "begin"},+ },+ }+ )++ assert definition.methods["begin"].is_start is True+ assert definition.methods["handle"].is_start is False++ class ExplicitNonStartFlow(Flow):+ @start()+ def begin(self):+ return "started"++ @listen(begin)+ def handle(self):+ return "handled"++ # Attach the loaded contract (with explicit ``start: false``) so the+ # projections read from it rather than rebuilding from the DSL.+ ExplicitNonStartFlow._flow_definition = definition++ flow = ExplicitNonStartFlow()+ viz_structure = visualization_builder.build_flow_structure(flow)+ assert "handle" not in viz_structure["start_methods"]+ assert viz_structure["nodes"]["handle"]["type"] != "start"+++def test_flow_definition_cache_is_not_inherited_by_subclasses():+ class ParentFlow(Flow):+ @start()+ def begin(self):+ return "begin"++ parent_definition = ParentFlow.flow_definition()++ class ChildFlow(ParentFlow):+ @listen(ParentFlow.begin)+ def child_step(self):+ return "child"++ child_definition = ChildFlow.flow_definition()++ assert parent_definition.name == "ParentFlow"+ assert child_definition.name == "ChildFlow"+ assert child_definition is not parent_definition+ assert set(child_definition.methods) == {"begin", "child_step"}+++def test_flow_definition_logs_diagnostics_when_loaded_from_contract(caplog):+ caplog.set_level(logging.WARNING, logger="crewai.flow.flow_definition")++ definition = flow_definition.FlowDefinition.from_dict(+ {+ "schema": "crewai.flow/v1",+ "name": "LoadedFlow",+ "methods": {+ "decision": {+ "router": True,+ "emit": ["continue"],+ }+ },+ }+ )++ assert any(+ diagnostic.code == "router_without_trigger"+ for diagnostic in definition.diagnostics+ )+ assert any(+ record.levelno == logging.ERROR+ and "LoadedFlow" in record.message+ and "router_without_trigger" in record.message+ for record in caplog.records+ )diff --git a/lib/crewai/tests/test_flow_serializer.py b/lib/crewai/tests/test_flow_serializer.pydeleted file mode 100644index 4ff423f7f..000000000--- a/lib/crewai/tests/test_flow_serializer.py+++ /dev/null@@ -1,818 +0,0 @@-"""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-- 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"-- 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-- 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"]}-- 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"-- assert "path_a" in method_map["decide"]["router_paths"]- assert "path_b" in method_map["decide"]["router_paths"]-- # 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-- 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"-- assert method_map["converge"]["condition_type"] == "AND"-- triggers = method_map["converge"]["trigger_methods"]- assert "step_a" in triggers- assert "step_b" in triggers-- 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-- def test_listen_plus_human_feedback_router_edges(self):- """Test that @listen + @human_feedback(emit=...) generates router edges.-- This is the pattern used in the whitepaper generator:- a listener method that also acts as a router via @human_feedback(emit=[...]).- The serializer must generate edges from this method to listeners of its emit paths.- """-- class ReviewFlow(Flow):- @start()- def generate(self):- return "content"-- @listen(generate)- @human_feedback(- message="Review this:",- emit=["approved", "needs_changes", "cancelled"],- llm="gpt-4o-mini",- )- def review(self):- return "review result"-- @listen("approved")- def handle_approved(self):- return "done"-- @listen("needs_changes")- def handle_changes(self):- return "regenerating"-- @listen("cancelled")- def handle_cancelled(self):- return "cancelled"-- structure = flow_structure(ReviewFlow)-- method_map = {m["name"]: m for m in structure["methods"]}- edge_set = {(e["from_method"], e["to_method"], e.get("condition")) for e in structure["edges"]}-- # review should be detected as a router with the emit paths- assert method_map["review"]["type"] == "router"- assert set(method_map["review"]["router_paths"]) == {"approved", "needs_changes", "cancelled"}- assert method_map["review"]["has_human_feedback"] is True-- assert ("generate", "review", None) in edge_set-- assert ("review", "handle_approved", "approved") in edge_set- assert ("review", "handle_changes", "needs_changes") in edge_set- assert ("review", "handle_cancelled", "cancelled") in edge_set---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):- 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,- # 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-- field_map = {f["name"]: f for f in fields}- assert "int" in field_map["counter"]["type"]- assert "str" in field_map["message"]["type"]-- 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"]}-- 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)-- edges = structure["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-- 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"]-- 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)-- json_str = json.dumps(structure)- assert json_str is not None-- 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"-- 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-- 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"-- 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.- # 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):- 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"]) == 3diff --git a/lib/crewai/tests/test_flow_visualization.py b/lib/crewai/tests/test_flow_visualization.pyindex 0efca3fe8..167703a14 100644--- a/lib/crewai/tests/test_flow_visualization.py+++ b/lib/crewai/tests/test_flow_visualization.py@@ -8,6 +8,7 @@ from pathlib import Pathimport pytestfrom crewai.flow.flow import Flow, and_, listen, or_, router, start+from crewai.flow.flow_definition import FlowDefinitionfrom crewai.flow.visualization import (build_flow_structure,visualize_flow_structure,@@ -36,14 +37,14 @@ class RouterFlow(Flow):@router(init)def decide(self):if hasattr(self, "state") and self.state.get("path") == "b":- return "path_b"- return "path_a"+ return "event_b"+ return "event_a"- @listen("path_a")+ @listen("event_a")def handle_a(self):return "handled_a"- @listen("path_b")+ @listen("event_b")def handle_b(self):return "handled_b"@@ -69,13 +70,23 @@ class ComplexFlow(Flow):@router(converge_and)def router_decision(self):- return "final_path"+ return "final_event"- @listen("final_path")+ @listen("final_event")def finalize(self):return "complete"+def _attach_flow_definition(flow_class: type[Flow], methods: dict[str, object]) -> None:+ flow_class._flow_definition = FlowDefinition.from_dict(+ {+ "schema": "crewai.flow/v1",+ "name": flow_class.__name__,+ "methods": methods,+ }+ )++def test_build_flow_structure_simple():"""Test building structure for a simple sequential flow."""flow = SimpleFlow()@@ -98,6 +109,47 @@ def test_build_flow_structure_simple():assert edge["condition_type"] == "OR"+def test_build_flow_structure_from_flow_class():+ """Test building structure from a Flow class via its FlowDefinition."""+ structure = build_flow_structure(SimpleFlow)++ assert set(structure["nodes"]) == {"begin", "process"}+ assert structure["start_methods"] == ["begin"]+ assert structure["nodes"]["begin"]["class_name"] == "SimpleFlow"+++def test_build_flow_structure_from_flow_definition():+ """Test building visualization directly from a FlowDefinition."""+ definition = FlowDefinition.from_dict(+ {+ "schema": "crewai.flow/v1",+ "name": "DefinedFlow",+ "methods": {+ "begin": {"start": True},+ "decide": {+ "listen": "begin",+ "router": True,+ "emit": ["done"],+ },+ "finish": {"listen": "done"},+ },+ }+ )++ structure = build_flow_structure(definition)++ assert set(structure["nodes"]) == {"begin", "decide", "finish"}+ assert structure["start_methods"] == ["begin"]+ assert structure["router_methods"] == ["decide"]+ assert structure["nodes"]["begin"]["class_name"] == "DefinedFlow"+ assert any(+ edge["source"] == "decide"+ and edge["target"] == "finish"+ and edge["router_event"] == "done"+ for edge in structure["edges"]+ )++def test_build_flow_structure_with_router():"""Test building structure for a flow with router."""flow = RouterFlow()@@ -111,13 +163,10 @@ def test_build_flow_structure_with_router():router_node = structure["nodes"]["decide"]assert router_node["type"] == "router"+ assert "router_events" not in router_node- if "router_paths" in router_node:- assert len(router_node["router_paths"]) >= 1- assert any("path" in path for path in router_node["router_paths"])-- router_edges = [edge for edge in structure["edges"] if edge["is_router_path"]]- assert len(router_edges) >= 1+ router_edges = [edge for edge in structure["edges"] if edge["is_router_event"]]+ assert router_edges == []def test_build_flow_structure_with_and_or_conditions():@@ -203,49 +252,40 @@ def test_visualize_flow_structure_json_data():assert "handle_b" in js_contentassert "router" in js_content.lower()- assert "path_a" in js_content- assert "path_b" in js_content+ assert "event_a" in js_content+ assert "event_b" in js_content-def test_node_metadata_includes_source_info():- """Test that nodes include source code and line number information."""+def test_node_metadata_omits_source_info():+ """Test that definition-only visualization omits Python source metadata."""flow = SimpleFlow()structure = build_flow_structure(flow)- for node_name, node_metadata in structure["nodes"].items():- assert node_metadata["source_code"] is not None- assert len(node_metadata["source_code"]) > 0- assert node_metadata["source_start_line"] is not None- assert node_metadata["source_start_line"] > 0- assert node_metadata["source_file"] is not None- assert node_metadata["source_file"].endswith(".py")+ for node_metadata in structure["nodes"].values():+ assert "source_code" not in node_metadata+ assert "source_lines" not in node_metadata+ assert "source_start_line" not in node_metadata+ assert "source_file" not in node_metadata-def test_node_metadata_includes_method_signature():- """Test that nodes include method signature information."""+def test_node_metadata_omits_method_signature():+ """Test that definition-only visualization omits Python method signatures."""flow = SimpleFlow()structure = build_flow_structure(flow)begin_node = structure["nodes"]["begin"]- assert begin_node["method_signature"] is not None- assert "operationId" in begin_node["method_signature"]- assert begin_node["method_signature"]["operationId"] == "begin"- assert "parameters" in begin_node["method_signature"]- assert "returns" in begin_node["method_signature"]+ assert "method_signature" not in begin_nodedef test_router_node_has_correct_metadata():- """Test that router nodes have correct type and paths."""+ """Test that router nodes have correct type and event metadata."""flow = RouterFlow()structure = build_flow_structure(flow)router_node = structure["nodes"]["decide"]assert router_node["type"] == "router"assert router_node["is_router"] is True- assert router_node["router_paths"] is not None- assert len(router_node["router_paths"]) == 2- assert "path_a" in router_node["router_paths"]- assert "path_b" in router_node["router_paths"]+ assert "router_events" not in router_nodedef test_listen_node_has_trigger_methods():@@ -255,7 +295,7 @@ def test_listen_node_has_trigger_methods():handle_a_node = structure["nodes"]["handle_a"]assert handle_a_node["trigger_methods"] is not None- assert "path_a" in handle_a_node["trigger_methods"]+ assert "event_a" in handle_a_node["trigger_methods"]def test_and_condition_node_metadata():@@ -317,16 +357,15 @@ def test_topological_path_counting():assert len(structure["edges"]) > 0-def test_class_signature_metadata():- """Test that nodes include class signature information."""+def test_class_metadata_comes_from_definition():+ """Test that nodes include only definition-derived class metadata."""flow = SimpleFlow()structure = build_flow_structure(flow)- for node_name, node_metadata in structure["nodes"].items():+ for node_metadata in structure["nodes"].values():assert node_metadata["class_name"] is not Noneassert node_metadata["class_name"] == "SimpleFlow"- assert node_metadata["class_signature"] is not None- assert "SimpleFlow" in node_metadata["class_signature"]+ assert "class_signature" not in node_metadatadef test_visualization_plot_method():@@ -338,8 +377,8 @@ def test_visualization_plot_method():assert os.path.exists(html_file)-def test_router_paths_to_string_conditions():- """Test that router paths correctly connect to listeners with string conditions."""+def test_router_events_to_string_conditions():+ """Test that router events correctly connect to listeners with string conditions."""class RouterToStringFlow(Flow):@start()@@ -349,25 +388,34 @@ def test_router_paths_to_string_conditions():@router(init)def decide(self):if hasattr(self, "state") and self.state.get("path") == "b":- return "path_b"- return "path_a"+ return "event_b"+ return "event_a"- @listen(or_("path_a", "path_b"))+ @listen(or_("event_a", "event_b"))def handle_either(self):return "handled"- @listen("path_b")+ @listen("event_b")def handle_b_only(self):return "handled_b"flow = RouterToStringFlow()+ _attach_flow_definition(+ RouterToStringFlow,+ {+ "init": {"start": True},+ "decide": {"listen": "init", "router": True, "emit": ["event_a", "event_b"]},+ "handle_either": {"listen": {"or": ["event_a", "event_b"]}},+ "handle_b_only": {"listen": "event_b"},+ },+ )structure = build_flow_structure(flow)decide_node = structure["nodes"]["decide"]- assert "path_a" in decide_node["router_paths"]- assert "path_b" in decide_node["router_paths"]+ assert "event_a" in decide_node["router_events"]+ assert "event_b" in decide_node["router_events"]- router_edges = [edge for edge in structure["edges"] if edge["is_router_path"]]+ router_edges = [edge for edge in structure["edges"] if edge["is_router_event"]]assert len(router_edges) == 3@@ -382,8 +430,8 @@ def test_router_paths_to_string_conditions():assert len(edges_to_handle_b_only) == 1-def test_router_paths_not_in_and_conditions():- """Test that router paths don't create edges to AND-nested conditions."""+def test_router_events_not_in_and_conditions():+ """Test that router events don't create edges to AND-nested conditions."""class RouterAndConditionFlow(Flow):@start()@@ -392,24 +440,34 @@ def test_router_paths_not_in_and_conditions():@router(init)def decide(self):- return "path_a"+ return "event_a"- @listen("path_a")+ @listen("event_a")def step_1(self):return "step_1_done"- @listen(and_("path_a", step_1))+ @listen(and_("event_a", step_1))def step_2_and(self):return "step_2_done"- @listen(or_(and_("path_a", step_1), "path_a"))+ @listen(or_(and_("event_a", step_1), "event_a"))def step_3_or(self):return "step_3_done"flow = RouterAndConditionFlow()+ _attach_flow_definition(+ RouterAndConditionFlow,+ {+ "init": {"start": True},+ "decide": {"listen": "init", "router": True, "emit": ["event_a"]},+ "step_1": {"listen": "event_a"},+ "step_2_and": {"listen": {"and": ["event_a", "step_1"]}},+ "step_3_or": {"listen": {"or": [{"and": ["event_a", "step_1"]}, "event_a"]}},+ },+ )structure = build_flow_structure(flow)- router_edges = [edge for edge in structure["edges"] if edge["is_router_path"]]+ router_edges = [edge for edge in structure["edges"] if edge["is_router_event"]]targets = [edge["target"] for edge in router_edges]@@ -454,6 +512,17 @@ def test_chained_routers_no_self_loops():return "need_auth"flow = ChainedRouterFlow()+ _attach_flow_definition(+ ChainedRouterFlow,+ {+ "entrance": {"start": True},+ "session_in_cache": {"listen": "entrance", "router": True, "emit": ["exp"]},+ "check_exp": {"listen": "exp", "router": True, "emit": ["auth"]},+ "call_ai_auth": {"listen": "auth", "router": True, "emit": ["action"]},+ "forward_to_action": {"listen": "action"},+ "forward_to_authenticate": {"listen": "authenticate"},+ },+ )structure = build_flow_structure(flow)for edge in structure["edges"]:@@ -461,13 +530,13 @@ def test_chained_routers_no_self_loops():f"Self-loop detected: {edge['source']} -> {edge['target']}")- router_edges = [edge for edge in structure["edges"] if edge["is_router_path"]]+ router_edges = [edge for edge in structure["edges"] if edge["is_router_event"]]# session_in_cache -> check_exp (via 'exp')exp_edges = [edgefor edge in router_edges- if edge["router_path_label"] == "exp" and edge["source"] == "session_in_cache"+ if edge["router_event"] == "exp" and edge["source"] == "session_in_cache"]assert len(exp_edges) == 1assert exp_edges[0]["target"] == "check_exp"@@ -476,7 +545,7 @@ def test_chained_routers_no_self_loops():auth_edges = [edgefor edge in router_edges- if edge["router_path_label"] == "auth" and edge["source"] == "check_exp"+ if edge["router_event"] == "auth" and edge["source"] == "check_exp"]assert len(auth_edges) == 1assert auth_edges[0]["target"] == "call_ai_auth"@@ -485,7 +554,7 @@ def test_chained_routers_no_self_loops():action_edges = [edgefor edge in router_edges- if edge["router_path_label"] == "action" and edge["source"] == "call_ai_auth"+ if edge["router_event"] == "action" and edge["source"] == "call_ai_auth"]assert len(action_edges) == 1assert action_edges[0]["target"] == "forward_to_action"@@ -523,6 +592,16 @@ def test_routers_with_shared_output_strings():return "skipped"flow = SharedOutputRouterFlow()+ _attach_flow_definition(+ SharedOutputRouterFlow,+ {+ "start": {"start": True},+ "router_a": {"listen": "start", "router": True, "emit": ["auth"]},+ "router_b": {"listen": "auth", "router": True, "emit": ["done"]},+ "finalize": {"listen": "done"},+ "handle_skip": {"listen": "skip"},+ },+ )structure = build_flow_structure(flow)for edge in structure["edges"]:@@ -531,11 +610,11 @@ def test_routers_with_shared_output_strings():)# router_a should connect to router_b via 'auth'- router_edges = [edge for edge in structure["edges"] if edge["is_router_path"]]+ router_edges = [edge for edge in structure["edges"] if edge["is_router_event"]]auth_from_a = [edgefor edge in router_edges- if edge["source"] == "router_a" and edge["router_path_label"] == "auth"+ if edge["source"] == "router_a" and edge["router_event"] == "auth"]assert len(auth_from_a) == 1assert auth_from_a[0]["target"] == "router_b"@@ -544,17 +623,17 @@ def test_routers_with_shared_output_strings():done_from_b = [edgefor edge in router_edges- if edge["source"] == "router_b" and edge["router_path_label"] == "done"+ if edge["source"] == "router_b" and edge["router_event"] == "done"]assert len(done_from_b) == 1assert done_from_b[0]["target"] == "finalize"-def test_warning_for_router_without_paths(caplog):- """Test that a warning is logged when a router has no determinable paths."""+def test_warning_for_router_without_events(caplog):+ """Test that a warning is logged when a router has no determinable events."""import logging- class RouterWithoutPathsFlow(Flow):+ class RouterWithoutEventsFlow(Flow):"""Flow with a router that returns a dynamic value."""@start()@@ -564,34 +643,35 @@ def test_warning_for_router_without_paths(caplog):@router(begin)def dynamic_router(self):import random- return random.choice(["path_a", "path_b"])+ return random.choice(["event_a", "event_b"])- @listen("path_a")+ @listen("event_a")def handle_a(self):return "a"- @listen("path_b")+ @listen("event_b")def handle_b(self):return "b"- flow = RouterWithoutPathsFlow()+ flow = RouterWithoutEventsFlow()with caplog.at_level(logging.WARNING):build_flow_structure(flow)assert any(- "Could not determine return paths for router 'dynamic_router'" in record.message+ "Router events for 'dynamic_router' are dynamic" in record.messagefor record in caplog.records)assert any(- "Found listeners waiting for triggers" in record.message+ "Static visualization could not match listener triggers" in record.messagefor record in caplog.records)+ assert not any(record.levelno >= logging.ERROR for record in caplog.records)def test_warning_for_orphaned_listeners(caplog):- """Test that an error is logged when listeners wait for triggers no router outputs."""+ """Test that a warning is logged when a trigger has no explicit router output."""import loggingfrom typing import Literal@@ -615,19 +695,33 @@ def test_warning_for_orphaned_listeners(caplog):return "orphan"flow = OrphanedListenerFlow()+ _attach_flow_definition(+ OrphanedListenerFlow,+ {+ "begin": {"start": True},+ "my_router": {+ "listen": "begin",+ "router": True,+ "emit": ["option_a", "option_b"],+ },+ "handle_a": {"listen": "option_a"},+ "handle_orphan": {"listen": "option_c"},+ },+ )- with caplog.at_level(logging.ERROR):+ with caplog.at_level(logging.WARNING):build_flow_structure(flow)assert any(- "Found listeners waiting for triggers" in record.message+ "Static visualization could not match listener triggers" in record.messageand "option_c" in record.messagefor record in caplog.records)+ assert not any(record.levelno >= logging.ERROR for record in caplog.records)-def test_no_warning_for_properly_typed_router(caplog):- """Test that no warning is logged when router has proper type annotations."""+def test_no_warning_for_explicit_contract_router_events(caplog):+ """Test no warning is logged when router events are declared in the contract."""import loggingfrom typing import Literal@@ -639,23 +733,39 @@ def test_no_warning_for_properly_typed_router(caplog):return "started"@router(begin)- def typed_router(self) -> Literal["path_a", "path_b"]:- return "path_a"+ def typed_router(self) -> Literal["event_a", "event_b"]:+ return "event_a"- @listen("path_a")+ @listen("event_a")def handle_a(self):return "a"- @listen("path_b")+ @listen("event_b")def handle_b(self):return "b"flow = ProperlyTypedRouterFlow()+ _attach_flow_definition(+ ProperlyTypedRouterFlow,+ {+ "begin": {"start": True},+ "typed_router": {+ "listen": "begin",+ "router": True,+ "emit": ["event_a", "event_b"],+ },+ "handle_a": {"listen": "event_a"},+ "handle_b": {"listen": "event_b"},+ },+ )with caplog.at_level(logging.WARNING):build_flow_structure(flow)# No warnings should be loggedwarning_messages = [r.message for r in caplog.records if r.levelno >= logging.WARNING]- assert not any("Could not determine return paths" in msg for msg in warning_messages)- assert not any("Found listeners waiting for triggers" in msg for msg in warning_messages)\ No newline at end of file+ assert not any("Router events for" in msg for msg in warning_messages)+ assert not any(+ "Static visualization could not match listener triggers" in msg+ for msg in warning_messages+ )diff --git a/lib/crewai/tests/test_human_feedback_decorator.py b/lib/crewai/tests/test_human_feedback_decorator.pyindex 68428ee71..63fe56f53 100644--- a/lib/crewai/tests/test_human_feedback_decorator.py+++ b/lib/crewai/tests/test_human_feedback_decorator.py@@ -13,7 +13,7 @@ from unittest.mock import MagicMock, patchimport pytest-from crewai.flow import Flow, human_feedback, listen, start+from crewai.flow import Flow, human_feedback, listen, persist, startfrom crewai.flow.human_feedback import (HumanFeedbackConfig,HumanFeedbackResult,@@ -79,7 +79,7 @@ class TestHumanFeedbackValidation:assert hasattr(test_method, "__human_feedback_config__")assert test_method.__is_router__ is True- assert test_method.__router_paths__ == ["approve", "reject"]+ assert test_method.__router_emit__ == ["approve", "reject"]def test_valid_configuration_without_routing(self):"""Test that valid configuration without routing doesn't raise."""@@ -91,6 +91,22 @@ class TestHumanFeedbackValidation:assert hasattr(test_method, "__human_feedback_config__")assert not hasattr(test_method, "__is_router__") or not test_method.__is_router__+ def test_persist_preserves_human_feedback_llm_attribute(self):+ """Test @persist preserves the live LLM stashed by @human_feedback."""+ llm = object()++ @persist()+ @human_feedback(+ message="Review this:",+ emit=["approve", "reject"],+ llm=llm,+ )+ def test_method(self):+ return "output"++ assert hasattr(test_method, "_human_feedback_llm")+ assert test_method._human_feedback_llm is llm+class TestHumanFeedbackConfig:"""Tests for HumanFeedbackConfig dataclass."""@@ -189,7 +205,7 @@ class TestDecoratorAttributePreservation:return "output"assert review_method.__is_router__ is True- assert review_method.__router_paths__ == ["approved", "rejected"]+ assert review_method.__router_emit__ == ["approved", "rejected"]class TestAsyncSupport:diff --git a/lib/crewai/tests/test_human_feedback_integration.py b/lib/crewai/tests/test_human_feedback_integration.pyindex d8cdf3f6c..8036fdb90 100644--- a/lib/crewai/tests/test_human_feedback_integration.py+++ b/lib/crewai/tests/test_human_feedback_integration.py@@ -778,14 +778,14 @@ class TestEdgeCases:class TestLLMConfigPreservation:"""Tests that LLM config is preserved through @human_feedback serialization.- PR #4970 introduced _hf_llm stashing so the live LLM object survives+ PR #4970 introduced _human_feedback_llm stashing so the live LLM object survivesdecorator wrapping for same-process resume. The serialization path(_serialize_llm_for_context / _deserialize_llm_from_context) preservesconfig for cross-process resume."""- def test_hf_llm_stashed_on_wrapper_with_llm_instance(self):- """Test that passing an LLM instance stashes it on the wrapper as _hf_llm."""+ def test_human_feedback_llm_stashed_on_wrapper_with_llm_instance(self):+ """Test that passing an LLM instance stashes it on the wrapper as _human_feedback_llm."""from crewai.llm import LLMllm_instance = LLM(model="gpt-4o-mini", temperature=0.42)@@ -801,11 +801,11 @@ class TestLLMConfigPreservation:return "content"method = ConfigFlow.review- assert hasattr(method, "_hf_llm"), "_hf_llm not found on wrapper"- assert method._hf_llm is llm_instance, "_hf_llm is not the same object"+ assert hasattr(method, "_human_feedback_llm"), "_human_feedback_llm not found on wrapper"+ assert method._human_feedback_llm is llm_instance, "_human_feedback_llm is not the same object"- def test_hf_llm_preserved_on_listen_method(self):- """Test that _hf_llm is preserved when @human_feedback is on a @listen method."""+ def test_human_feedback_llm_preserved_on_listen_method(self):+ """Test that _human_feedback_llm is preserved when @human_feedback is on a @listen method."""from crewai.llm import LLMllm_instance = LLM(model="gpt-4o-mini", temperature=0.7)@@ -825,11 +825,11 @@ class TestLLMConfigPreservation:return "content"method = ListenConfigFlow.review- assert hasattr(method, "_hf_llm")- assert method._hf_llm is llm_instance+ assert hasattr(method, "_human_feedback_llm")+ assert method._human_feedback_llm is llm_instance- def test_hf_llm_accessible_on_instance(self):- """Test that _hf_llm survives Flow instantiation (bound method access)."""+ def test_human_feedback_llm_accessible_on_instance(self):+ """Test that _human_feedback_llm survives Flow instantiation (bound method access)."""from crewai.llm import LLMllm_instance = LLM(model="gpt-4o-mini", temperature=0.42)@@ -846,8 +846,8 @@ class TestLLMConfigPreservation:flow = InstanceFlow()instance_method = flow.review- assert hasattr(instance_method, "_hf_llm")- assert instance_method._hf_llm is llm_instance+ assert hasattr(instance_method, "_human_feedback_llm")+ assert instance_method._human_feedback_llm is llm_instancedef test_serialize_llm_preserves_config_fields(self):"""Test that _serialize_llm_for_context captures temperature, base_url, etc."""