Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
Split `flow.py` into DSL, definition, and runtime (#5997)
Vini Brasil1aba9fe41556
diff --git a/lib/crewai/src/crewai/flow/dsl.py b/lib/crewai/src/crewai/flow/dsl.pynew file mode 100644index 000000000..3181acd50--- /dev/null+++ b/lib/crewai/src/crewai/flow/dsl.py@@ -0,0 +1,320 @@+"""Flow authoring DSL: the ``@start`` / ``@listen`` / ``@router`` decorators+plus the ``or_`` / ``and_`` condition combinators.++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``.+"""++from __future__ import annotations++from collections.abc import Callable+from typing import Any, ParamSpec, TypeVar++from crewai.flow.constants import AND_CONDITION, OR_CONDITION+from crewai.flow.flow_definition import (+ _extract_all_methods,+ is_flow_condition_dict,+ is_flow_method_callable,+ is_flow_method_name,+)+from crewai.flow.flow_wrappers import (+ FlowCondition,+ FlowConditions,+ ListenMethod,+ RouterMethod,+ StartMethod,+)+++P = ParamSpec("P")+R = TypeVar("R")+++def start(+ condition: str | FlowCondition | Callable[..., Any] | None = None,+) -> Callable[[Callable[P, R]], StartMethod[P, R]]:+ """Marks a method as a flow's starting point.++ This decorator designates a method as an entry point for the flow execution.+ It can optionally specify conditions that trigger the start based on other+ method executions.++ Args:+ condition: Defines when the start method should execute. Can be:+ - str: Name of a method that triggers this start+ - FlowCondition: Result from or_() or and_(), including nested conditions+ - Callable[..., Any]: A method reference that triggers this start+ Default is None, meaning unconditional start.++ Returns:+ A decorator function that wraps the method as a flow start point and preserves its signature.++ Raises:+ ValueError: If the condition format is invalid.++ Examples:+ >>> @start() # Unconditional start+ >>> def begin_flow(self):+ ... pass++ >>> @start("method_name") # Start after specific method+ >>> def conditional_start(self):+ ... pass++ >>> @start(and_("method1", "method2")) # Start after multiple methods+ >>> def complex_start(self):+ ... pass+ """++ 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_()"+ )+ return wrapper++ return decorator+++def listen(+ condition: str | FlowCondition | Callable[..., Any],+) -> Callable[[Callable[P, R]], ListenMethod[P, R]]:+ """Creates a listener that executes when specified conditions are met.++ This decorator sets up a method to execute in response to other method+ executions in the flow. It supports both simple and complex triggering+ conditions.++ Args:+ condition: Specifies when the listener should execute.++ Returns:+ A decorator function that wraps the method as a flow listener and preserves its signature.++ Raises:+ ValueError: If the condition format is invalid.++ Examples:+ >>> @listen("process_data")+ >>> def handle_processed_data(self):+ ... pass++ >>> @listen("method_name")+ >>> def handle_completion(self):+ ... pass+ """++ 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_()"+ )+ return wrapper++ return decorator+++def router(+ condition: str | FlowCondition | Callable[..., Any],+) -> 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 determine+ the 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.++ 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++ Returns:+ A decorator function that wraps the method as a router and preserves its signature.++ Raises:+ ValueError: If the condition format is invalid.++ Examples:+ >>> @router("check_status")+ >>> def route_based_on_status(self):+ ... if self.state.status == "success":+ ... return "SUCCESS"+ ... return "FAILURE"++ >>> @router(and_("validate", "process"))+ >>> def complex_routing(self):+ ... if all([self.state.valid, self.state.processed]):+ ... return "CONTINUE"+ ... return "STOP"+ """++ 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+ else:+ raise ValueError(+ "Condition must be a method, string, or a result of or_() or and_()"+ )+ return wrapper++ return decorator+++def or_(*conditions: str | FlowCondition | Callable[..., Any]) -> FlowCondition:+ """Combines multiple conditions with OR logic for flow control.++ Creates a condition that is satisfied when any of the specified conditions+ are met. This is used with @start, @listen, or @router decorators to create+ complex triggering conditions.++ Args:+ conditions: Variable number of conditions that can be method names, existing condition dictionaries, or method references.++ Returns:+ A condition dictionary with format {"type": "OR", "conditions": list_of_conditions} where each condition can be a string (method name) or a nested dict++ Raises:+ ValueError: If condition format is invalid.++ Examples:+ >>> @listen(or_("success", "timeout"))+ >>> def handle_completion(self):+ ... pass++ >>> @listen(or_(and_("step1", "step2"), "step3"))+ >>> 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}+++def and_(*conditions: str | FlowCondition | Callable[..., Any]) -> FlowCondition:+ """Combines multiple conditions with AND logic for flow control.++ Creates a condition that is satisfied only when all specified conditions+ are met. This is used with @start, @listen, or @router decorators to create+ complex triggering conditions.++ Args:+ *conditions: Variable number of conditions that can be method names, existing condition dictionaries, or method references.++ Returns:+ A condition dictionary with format {"type": "AND", "conditions": list_of_conditions}+ where each condition can be a string (method name) or a nested dict++ Raises:+ ValueError: If any condition is invalid.++ Examples:+ >>> @listen(and_("validated", "processed"))+ >>> def handle_complete_data(self):+ ... pass++ >>> @listen(and_(or_("step1", "step2"), "step3"))+ >>> 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}diff --git a/lib/crewai/src/crewai/flow/flow.py b/lib/crewai/src/crewai/flow/flow.pyindex 1ac8b9fde..3cac04521 100644--- a/lib/crewai/src/crewai/flow/flow.py+++ b/lib/crewai/src/crewai/flow/flow.py@@ -1,3625 +1,39 @@-"""Core flow execution framework with decorators and state management.+"""Backwards-compatible re-export surface for the Flow framework.-This module provides the Flow class and decorators (@start, @listen, @router)-for building event-driven workflows with conditional execution and routing.-"""--from __future__ import annotations--import asyncio-from collections.abc import (- Callable,- ItemsView,- Iterable,- Iterator,- KeysView,- Sequence,- ValuesView,-)-from concurrent.futures import Future, ThreadPoolExecutor-import contextvars-import copy-import enum-import inspect-import logging-import threading-from typing import (- TYPE_CHECKING,- Annotated,- Any,- ClassVar,- Generic,- Literal,- ParamSpec,- SupportsIndex,- TypeVar,- cast,- overload,-)-from uuid import uuid4--from opentelemetry import baggage-from opentelemetry.context import attach, detach-from pydantic import (- BaseModel,- BeforeValidator,- ConfigDict,- Field,- PlainSerializer,- PrivateAttr,- SerializeAsAny,- ValidationError,-)-from pydantic._internal._model_construction import ModelMetaclass-from rich.console import Console-from rich.panel import Panel--from crewai.events.base_events import reset_emission_counter-from crewai.events.event_bus import crewai_event_bus-from crewai.events.event_context import (- get_current_parent_id,- reset_last_event_id,- restore_event_scope,- triggered_by_scope,-)-from crewai.events.listeners.tracing.trace_listener import (- TraceCollectionListener,-)-from crewai.events.listeners.tracing.utils import (- has_user_declined_tracing,- set_tracing_enabled,- should_enable_tracing,- should_suppress_tracing_messages,-)-from crewai.events.types.flow_events import (- FlowCreatedEvent,- FlowFinishedEvent,- FlowPausedEvent,- FlowPlotEvent,- FlowStartedEvent,- MethodExecutionFailedEvent,- MethodExecutionFinishedEvent,- MethodExecutionPausedEvent,- MethodExecutionStartedEvent,-)-from 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_wrappers import (- FlowCondition,- FlowConditions,- FlowMethod,- ListenMethod,- RouterMethod,- SimpleFlowCondition,- StartMethod,-)-from crewai.flow.human_feedback import HumanFeedbackResult-from crewai.flow.input_provider import InputProvider-from crewai.flow.persistence.base import FlowPersistence-from crewai.flow.types import (- FlowExecutionData,- FlowMethodName,- InputHistoryEntry,- PendingListenerKey,-)-from crewai.flow.utils import (- _extract_all_methods,- _extract_all_methods_recursive,- _normalize_condition,- get_possible_return_constants,- is_flow_condition_dict,- is_flow_method,- is_flow_method_callable,- is_flow_method_name,- is_simple_flow_condition,-)-from crewai.memory.memory_scope import MemoryScope, MemorySlice, _ensure_memory_kind-from crewai.memory.unified_memory import Memory-from crewai.state.checkpoint_config import (- CheckpointConfig,- _coerce_checkpoint,- apply_checkpoint,-)---if TYPE_CHECKING:- from crewai_files import FileInput-- from crewai.context import ExecutionContext- from crewai.flow.async_feedback.types import PendingFeedbackContext- from crewai.llms.base_llm import BaseLLM--from crewai.flow.visualization import build_flow_structure, render_interactive-from crewai.types.streaming import CrewStreamingOutput, FlowStreamingOutput-from crewai.utilities.env import get_env_context-from crewai.utilities.streaming import (- TaskInfo,- create_async_chunk_generator,- create_chunk_generator,- create_streaming_state,- register_cleanup,- signal_end,- signal_error,-)---logger = logging.getLogger(__name__)---def _resolve_persistence(value: Any) -> Any:- if value is None or isinstance(value, FlowPersistence):- return value- if isinstance(value, dict):- from crewai.flow.persistence.base import _persistence_registry-- type_name = value.get("persistence_type", "SQLiteFlowPersistence")- cls = _persistence_registry.get(type_name)- if cls is not None:- return cls.model_validate(value)- return value---def _serialize_persistence(value: Any) -> dict[str, Any] | None:- if value is None:- return None- if isinstance(value, FlowPersistence):- return value.model_dump(mode="json")- raise TypeError(- f"Cannot serialize Flow.persistence of type {type(value).__name__}: "- "expected FlowPersistence or None."- )---def _validate_input_provider(value: Any) -> Any:- if value is None or isinstance(value, InputProvider):- return value- from crewai.types.callback import _dotted_path_to_instance-- resolved = _dotted_path_to_instance(value)- if resolved is None or isinstance(resolved, InputProvider):- return resolved- raise ValueError(- f"Resolved input_provider {resolved!r} does not implement the "- "InputProvider protocol (missing request_input)."- )---def _serialize_input_provider(value: Any) -> str | None:- if value is None:- return None- from crewai.types.callback import _instance_to_dotted_path-- return _instance_to_dotted_path(value)---_INITIAL_STATE_CLASS_MARKER = "__crewai_pydantic_class_schema__"---def _serialize_initial_state(value: Any) -> Any:- """Make ``initial_state`` safe for JSON checkpoint serialization.-- ``BaseModel`` class refs are emitted as their JSON schema under a sentinel- marker key so deserialization can round-trip them back to a class.- ``BaseModel`` instances are dumped to JSON (round-trip as plain dicts,- which ``_create_initial_state`` accepts). Bare ``type`` values that are- not ``BaseModel`` subclasses (e.g. ``dict``) are dropped since they- can't be represented in JSON.- """- if isinstance(value, type):- if issubclass(value, BaseModel):- return {_INITIAL_STATE_CLASS_MARKER: value.model_json_schema()}- return None- if isinstance(value, BaseModel):- return value.model_dump(mode="json")- return value---def _deserialize_initial_state(value: Any) -> Any:- """Rehydrate a class ref serialized by :func:`_serialize_initial_state`."""- if isinstance(value, dict) and _INITIAL_STATE_CLASS_MARKER in value:- from crewai.utilities.pydantic_schema_utils import create_model_from_schema-- return create_model_from_schema(value[_INITIAL_STATE_CLASS_MARKER])- return value---class FlowState(BaseModel):- """Base model for all flow states, ensuring each state has a unique ID."""-- id: str = Field(- default_factory=lambda: str(uuid4()),- description="Unique identifier for the flow state",- )---T = TypeVar("T", bound=dict[str, Any] | BaseModel)-P = ParamSpec("P")-R = TypeVar("R")-F = TypeVar("F", bound=Callable[..., Any])---def start(- condition: str | FlowCondition | Callable[..., Any] | None = None,-) -> Callable[[Callable[P, R]], StartMethod[P, R]]:- """Marks a method as a flow's starting point.-- This decorator designates a method as an entry point for the flow execution.- It can optionally specify conditions that trigger the start based on other- method executions.-- Args:- condition: Defines when the start method should execute. Can be:- - str: Name of a method that triggers this start- - FlowCondition: Result from or_() or and_(), including nested conditions- - Callable[..., Any]: A method reference that triggers this start- Default is None, meaning unconditional start.-- Returns:- A decorator function that wraps the method as a flow start point and preserves its signature.-- Raises:- ValueError: If the condition format is invalid.-- Examples:- >>> @start() # Unconditional start- >>> def begin_flow(self):- ... pass-- >>> @start("method_name") # Start after specific method- >>> def conditional_start(self):- ... pass-- >>> @start(and_("method1", "method2")) # Start after multiple methods- >>> def complex_start(self):- ... pass- """-- 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_()"- )- return wrapper-- return decorator---def listen(- condition: str | FlowCondition | Callable[..., Any],-) -> Callable[[Callable[P, R]], ListenMethod[P, R]]:- """Creates a listener that executes when specified conditions are met.-- This decorator sets up a method to execute in response to other method- executions in the flow. It supports both simple and complex triggering- conditions.-- Args:- condition: Specifies when the listener should execute.-- Returns:- A decorator function that wraps the method as a flow listener and preserves its signature.-- Raises:- ValueError: If the condition format is invalid.-- Examples:- >>> @listen("process_data")- >>> def handle_processed_data(self):- ... pass-- >>> @listen("method_name")- >>> def handle_completion(self):- ... pass- """-- 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_()"- )- return wrapper-- return decorator---def router(- condition: str | FlowCondition | Callable[..., Any],-) -> 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 determine- the 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.-- 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-- Returns:- A decorator function that wraps the method as a router and preserves its signature.-- Raises:- ValueError: If the condition format is invalid.-- Examples:- >>> @router("check_status")- >>> def route_based_on_status(self):- ... if self.state.status == "success":- ... return "SUCCESS"- ... return "FAILURE"-- >>> @router(and_("validate", "process"))- >>> def complex_routing(self):- ... if all([self.state.valid, self.state.processed]):- ... return "CONTINUE"- ... return "STOP"- """-- 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- else:- raise ValueError(- "Condition must be a method, string, or a result of or_() or and_()"- )- return wrapper-- return decorator---def or_(*conditions: str | FlowCondition | Callable[..., Any]) -> FlowCondition:- """Combines multiple conditions with OR logic for flow control.-- Creates a condition that is satisfied when any of the specified conditions- are met. This is used with @start, @listen, or @router decorators to create- complex triggering conditions.-- Args:- conditions: Variable number of conditions that can be method names, existing condition dictionaries, or method references.-- Returns:- A condition dictionary with format {"type": "OR", "conditions": list_of_conditions} where each condition can be a string (method name) or a nested dict-- Raises:- ValueError: If condition format is invalid.-- Examples:- >>> @listen(or_("success", "timeout"))- >>> def handle_completion(self):- ... pass-- >>> @listen(or_(and_("step1", "step2"), "step3"))- >>> 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}---def and_(*conditions: str | FlowCondition | Callable[..., Any]) -> FlowCondition:- """Combines multiple conditions with AND logic for flow control.-- Creates a condition that is satisfied only when all specified conditions- are met. This is used with @start, @listen, or @router decorators to create- complex triggering conditions.-- Args:- *conditions: Variable number of conditions that can be method names, existing condition dictionaries, or method references.-- Returns:- A condition dictionary with format {"type": "AND", "conditions": list_of_conditions}- where each condition can be a string (method name) or a nested dict-- Raises:- ValueError: If any condition is invalid.-- Examples:- >>> @listen(and_("validated", "processed"))- >>> def handle_complete_data(self):- ... pass-- >>> @listen(and_(or_("step1", "step2"), "step3"))- >>> 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}---class LockedListProxy(list, Generic[T]): # type: ignore[type-arg]- """Thread-safe proxy for list operations.-- Subclasses ``list`` so that ``isinstance(proxy, list)`` returns True,- which is required by libraries like LanceDB and Pydantic that do strict- type checks. All mutations go through the lock; reads delegate to the- underlying list.- """-- def __init__(self, lst: list[T], lock: threading.Lock) -> None:- super().__init__() # empty builtin list; all access goes through self._list- self._list = lst- self._lock = lock-- def append(self, item: T) -> None:- with self._lock:- self._list.append(item)-- def extend(self, items: Iterable[T]) -> None:- with self._lock:- self._list.extend(items)-- def insert(self, index: SupportsIndex, item: T) -> None:- with self._lock:- self._list.insert(index, item)-- def remove(self, item: T) -> None:- with self._lock:- self._list.remove(item)-- def pop(self, index: SupportsIndex = -1) -> T:- with self._lock:- return self._list.pop(index)-- def clear(self) -> None:- with self._lock:- self._list.clear()-- @overload- def __setitem__(self, index: SupportsIndex, value: T) -> None: ...- @overload- def __setitem__(self, index: slice, value: Iterable[T]) -> None: ...- def __setitem__(self, index: Any, value: Any) -> None:- with self._lock:- self._list[index] = value-- def __delitem__(self, index: SupportsIndex | slice) -> None:- with self._lock:- del self._list[index]-- @overload- def __getitem__(self, index: SupportsIndex) -> T: ...- @overload- def __getitem__(self, index: slice) -> list[T]: ...- def __getitem__(self, index: Any) -> Any:- return self._list[index]-- def __len__(self) -> int:- return len(self._list)-- def __iter__(self) -> Iterator[T]:- return iter(self._list)-- def __contains__(self, item: object) -> bool:- return item in self._list-- def __repr__(self) -> str:- return repr(self._list)-- def __bool__(self) -> bool:- return bool(self._list)-- def index(- self, value: T, start: SupportsIndex = 0, stop: SupportsIndex | None = None- ) -> int:- if stop is None:- return self._list.index(value, start)- return self._list.index(value, start, stop)-- def count(self, value: T) -> int:- return self._list.count(value)-- def sort(self, *, key: Any = None, reverse: bool = False) -> None:- with self._lock:- self._list.sort(key=key, reverse=reverse)-- def reverse(self) -> None:- with self._lock:- self._list.reverse()-- def copy(self) -> list[T]:- return self._list.copy()-- def __add__(self, other: list[T]) -> list[T]: # type: ignore[override]- return self._list + other-- def __radd__(self, other: list[T]) -> list[T]:- return other + self._list-- def __iadd__(self, other: Iterable[T]) -> LockedListProxy[T]: # type: ignore[override]- with self._lock:- self._list += list(other)- return self-- def __mul__(self, n: SupportsIndex) -> list[T]:- return self._list * n-- def __rmul__(self, n: SupportsIndex) -> list[T]:- return self._list * n-- def __imul__(self, n: SupportsIndex) -> LockedListProxy[T]:- with self._lock:- self._list *= n- return self-- def __reversed__(self) -> Iterator[T]:- return reversed(self._list)-- def __eq__(self, other: object) -> bool:- """Compare based on the underlying list contents."""- if isinstance(other, LockedListProxy):- # Avoid deadlocks by acquiring locks in a consistent order.- first, second = (self, other) if id(self) <= id(other) else (other, self)- with first._lock:- with second._lock:- return first._list == second._list- with self._lock:- return self._list == other-- def __ne__(self, other: object) -> bool:- return not self.__eq__(other)---class LockedDictProxy(dict, Generic[T]): # type: ignore[type-arg]- """Thread-safe proxy for dict operations.-- Subclasses ``dict`` so that ``isinstance(proxy, dict)`` returns True,- which is required by libraries like Pydantic that do strict type checks.- All mutations go through the lock; reads delegate to the underlying dict.- """-- def __init__(self, d: dict[str, T], lock: threading.Lock) -> None:- super().__init__() # empty builtin dict; all access goes through self._dict- self._dict = d- self._lock = lock-- def __setitem__(self, key: str, value: T) -> None:- with self._lock:- self._dict[key] = value-- def __delitem__(self, key: str) -> None:- with self._lock:- del self._dict[key]-- def pop(self, key: str, *default: T) -> T: # type: ignore[override]- with self._lock:- return self._dict.pop(key, *default)-- def update(self, other: dict[str, T]) -> None: # type: ignore[override]- with self._lock:- self._dict.update(other)-- def clear(self) -> None:- with self._lock:- self._dict.clear()-- def setdefault(self, key: str, default: T) -> T: # type: ignore[override]- with self._lock:- return self._dict.setdefault(key, default)-- def __getitem__(self, key: str) -> T:- return self._dict[key]-- def __len__(self) -> int:- return len(self._dict)-- def __iter__(self) -> Iterator[str]:- return iter(self._dict)-- def __contains__(self, key: object) -> bool:- return key in self._dict-- def keys(self) -> KeysView[str]: # type: ignore[override]- return self._dict.keys()-- def values(self) -> ValuesView[T]: # type: ignore[override]- return self._dict.values()-- def items(self) -> ItemsView[str, T]: # type: ignore[override]- return self._dict.items()-- def get(self, key: str, default: T | None = None) -> T | None: # type: ignore[override]- return self._dict.get(key, default)-- def __repr__(self) -> str:- return repr(self._dict)-- def __bool__(self) -> bool:- return bool(self._dict)-- def copy(self) -> dict[str, T]:- return self._dict.copy()-- def __or__(self, other: dict[str, T]) -> dict[str, T]: # type: ignore[override]- return self._dict | other-- def __ror__(self, other: dict[str, T]) -> dict[str, T]: # type: ignore[override]- return other | self._dict-- def __ior__(self, other: dict[str, T]) -> LockedDictProxy[T]: # type: ignore[override]- with self._lock:- self._dict |= other- return self-- def __reversed__(self) -> Iterator[str]:- return reversed(self._dict)-- def __eq__(self, other: object) -> bool:- """Compare based on the underlying dict contents."""- if isinstance(other, LockedDictProxy):- # Avoid deadlocks by acquiring locks in a consistent order.- first, second = (self, other) if id(self) <= id(other) else (other, self)- with first._lock:- with second._lock:- return first._dict == second._dict- with self._lock:- return self._dict == other-- def __ne__(self, other: object) -> bool:- return not self.__eq__(other)---class StateProxy(Generic[T]):- """Proxy that provides thread-safe access to flow state.-- Wraps state objects (dict or BaseModel) and uses a lock for all write- operations to prevent race conditions when parallel listeners modify state.- """-- __slots__ = ("_proxy_lock", "_proxy_state")-- def __init__(self, state: T, lock: threading.Lock) -> None:- object.__setattr__(self, "_proxy_state", state)- object.__setattr__(self, "_proxy_lock", lock)-- def __getattr__(self, name: str) -> Any:- value = getattr(object.__getattribute__(self, "_proxy_state"), name)- lock = object.__getattribute__(self, "_proxy_lock")- if isinstance(value, list):- return LockedListProxy(value, lock)- if isinstance(value, dict):- return LockedDictProxy(value, lock)- return value-- def __setattr__(self, name: str, value: Any) -> None:- if name in ("_proxy_state", "_proxy_lock"):- object.__setattr__(self, name, value)- else:- if isinstance(value, LockedListProxy):- value = value._list- elif isinstance(value, LockedDictProxy):- value = value._dict- with object.__getattribute__(self, "_proxy_lock"):- setattr(object.__getattribute__(self, "_proxy_state"), name, value)-- def __getitem__(self, key: str) -> Any:- return object.__getattribute__(self, "_proxy_state")[key]-- def __setitem__(self, key: str, value: Any) -> None:- with object.__getattribute__(self, "_proxy_lock"):- object.__getattribute__(self, "_proxy_state")[key] = value-- def __delitem__(self, key: str) -> None:- with object.__getattribute__(self, "_proxy_lock"):- del object.__getattribute__(self, "_proxy_state")[key]-- def __contains__(self, key: str) -> bool:- return key in object.__getattribute__(self, "_proxy_state")-- def __repr__(self) -> str:- return repr(object.__getattribute__(self, "_proxy_state"))-- def _unwrap(self) -> T:- """Return the underlying state object."""- return cast(T, object.__getattribute__(self, "_proxy_state"))-- def model_dump(self, *args: Any, **kwargs: Any) -> dict[str, Any]:- """Return state as a dictionary.-- Works for both dict and BaseModel underlying states.- """- state = object.__getattribute__(self, "_proxy_state")- if isinstance(state, dict):- return state- result: dict[str, Any] = state.model_dump(*args, **kwargs)- return result---class FlowMeta(ModelMetaclass):- def __new__(- mcs,- name: str,- bases: tuple[type, ...],- namespace: dict[str, Any],- **kwargs: Any,- ) -> type:- parent_fields: set[str] = set()- for base in bases:- if hasattr(base, "model_fields"):- parent_fields.update(base.model_fields)-- annotations = namespace.get("__annotations__", {})- _skip_types = (classmethod, staticmethod, property)-- for base in bases:- if isinstance(base, ModelMetaclass):- continue- for attr_name in getattr(base, "__annotations__", {}):- if attr_name not in annotations and attr_name not in namespace:- annotations[attr_name] = ClassVar-- for attr_name, attr_value in namespace.items():- if isinstance(attr_value, property) and attr_name not in annotations:- for base in bases:- base_ann = getattr(base, "__annotations__", {})- if attr_name in base_ann:- annotations[attr_name] = ClassVar-- for attr_name, attr_value in list(namespace.items()):- if attr_name in annotations or attr_name.startswith("_"):- continue- if attr_name in parent_fields:- annotations[attr_name] = Any- if isinstance(attr_value, BaseModel):- namespace[attr_name] = Field(- default_factory=lambda v=attr_value: v, exclude=True- )- continue- if callable(attr_value) or isinstance(- attr_value, (*_skip_types, FlowMethod)- ):- continue- annotations[attr_name] = ClassVar[type(attr_value)]- namespace["__annotations__"] = annotations-- cls = super().__new__(mcs, name, bases, namespace)-- start_methods = []- listeners = {}- router_paths = {}- routers = set()-- 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- )-- 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] = []-- # 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] = []-- 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]-- return cls---class Flow(BaseModel, Generic[T], metaclass=FlowMeta):- """Base class for all flows.-- type parameter T must be either dict[str, Any] or a subclass of BaseModel."""-- model_config = ConfigDict(- arbitrary_types_allowed=True,- ignored_types=(StartMethod, ListenMethod, RouterMethod),- revalidate_instances="never",- )- __hash__ = object.__hash__-- _start_methods: ClassVar[list[FlowMethodName]] = []- _listeners: ClassVar[dict[FlowMethodName, SimpleFlowCondition | FlowCondition]] = {}- _routers: ClassVar[set[FlowMethodName]] = set()- _router_paths: ClassVar[dict[FlowMethodName, list[FlowMethodName]]] = {}-- entity_type: Literal["flow"] = "flow"-- initial_state: Annotated[ # type: ignore[type-arg]- type[BaseModel] | type[dict] | dict[str, Any] | BaseModel | None,- BeforeValidator(_deserialize_initial_state),- PlainSerializer(_serialize_initial_state, return_type=Any, when_used="json"),- ] = Field(default=None)- name: str | None = Field(default=None)- tracing: bool | None = Field(default=None)- stream: bool = Field(default=False)- memory: Annotated[- Annotated[- Memory | MemoryScope | MemorySlice, Field(discriminator="memory_kind")- ]- | None,- BeforeValidator(_ensure_memory_kind),- ] = Field(default=None)- input_provider: Annotated[- InputProvider | None,- BeforeValidator(_validate_input_provider),- PlainSerializer(- _serialize_input_provider, return_type=str | None, when_used="json"- ),- ] = Field(default=None)- suppress_flow_events: bool = Field(default=False)- human_feedback_history: list[HumanFeedbackResult] = Field(default_factory=list)- last_human_feedback: HumanFeedbackResult | None = Field(default=None)-- persistence: Annotated[- SerializeAsAny[FlowPersistence] | None,- BeforeValidator(lambda v, _: _resolve_persistence(v)),- PlainSerializer(- _serialize_persistence, return_type=dict | None, when_used="json"- ),- ] = Field(default=None)- max_method_calls: int = Field(default=100)-- execution_context: ExecutionContext | None = Field(default=None)- checkpoint: Annotated[- CheckpointConfig | bool | None,- BeforeValidator(_coerce_checkpoint),- ] = Field(default=None)-- @classmethod- def from_checkpoint(cls, config: CheckpointConfig) -> Flow: # type: ignore[type-arg]- """Restore a Flow from a checkpoint.-- Args:- config: Checkpoint configuration with ``restore_from`` set to- the path of the checkpoint to load.-- Returns:- A Flow instance ready to resume.- """- from crewai.context import apply_execution_context- from crewai.events.event_bus import crewai_event_bus- from crewai.state.runtime import RuntimeState-- state = RuntimeState.from_checkpoint(config, context={"from_checkpoint": True})- crewai_event_bus.set_runtime_state(state)- for entity in state.root:- if not isinstance(entity, Flow):- continue- if entity.execution_context is not None:- apply_execution_context(entity.execution_context)- if isinstance(entity, cls):- entity._restore_from_checkpoint()- return entity- instance = cls()- instance.checkpoint_completed_methods = entity.checkpoint_completed_methods- instance.checkpoint_method_outputs = entity.checkpoint_method_outputs- instance.checkpoint_method_counts = entity.checkpoint_method_counts- instance.checkpoint_state = entity.checkpoint_state- instance._restore_from_checkpoint()- return instance- raise ValueError(f"No Flow found in checkpoint: {config.restore_from}")-- @classmethod- def fork(- cls,- config: CheckpointConfig,- branch: str | None = None,- ) -> Flow: # type: ignore[type-arg]- """Fork a Flow from a checkpoint, creating a new execution branch.-- Args:- config: Checkpoint configuration with ``restore_from`` set.- branch: Branch label for the fork. Auto-generated if not provided.-- Returns:- A Flow instance on the new branch. Call kickoff() to run.- """- flow = cls.from_checkpoint(config)- state = crewai_event_bus.runtime_state- if state is None:- raise RuntimeError(- "Cannot fork: no runtime state on the event bus. "- "Ensure from_checkpoint() succeeded before calling fork()."- )- state.fork(branch)- new_id = str(uuid4())- if isinstance(flow._state, dict):- flow._state["id"] = new_id- else:- object.__setattr__(flow._state, "id", new_id)- return flow-- checkpoint_completed_methods: set[str] | None = Field(default=None)- checkpoint_method_outputs: list[Any] | None = Field(default=None)- checkpoint_method_counts: dict[str, int] | None = Field(default=None)- checkpoint_state: dict[str, Any] | None = Field(default=None)-- def _restore_from_checkpoint(self) -> None:- """Restore private execution state from checkpoint fields."""- if self.checkpoint_completed_methods is not None:- self._completed_methods = {- FlowMethodName(m) for m in self.checkpoint_completed_methods- }- if self.checkpoint_method_outputs is not None:- self._method_outputs = list(self.checkpoint_method_outputs)- if self.checkpoint_method_counts is not None:- self._method_execution_counts = {- FlowMethodName(k): v for k, v in self.checkpoint_method_counts.items()- }- if self.checkpoint_state is not None:- self._restore_state(self.checkpoint_state)- if (- isinstance(self.memory, MemoryScope | MemorySlice)- and self.memory._memory is None- ):- self.memory.bind(Memory())- restore_event_scope(())- reset_last_event_id()-- _methods: dict[FlowMethodName, FlowMethod[Any, Any]] = PrivateAttr(- default_factory=dict- )- _method_execution_counts: dict[FlowMethodName, int] = PrivateAttr(- default_factory=dict- )- _pending_and_listeners: dict[PendingListenerKey, set[FlowMethodName]] = PrivateAttr(- default_factory=dict- )- _fired_or_listeners: set[FlowMethodName] = PrivateAttr(default_factory=set)- _method_outputs: list[Any] = PrivateAttr(default_factory=list)- _state_lock: threading.Lock = PrivateAttr(default_factory=threading.Lock)- _or_listeners_lock: threading.Lock = PrivateAttr(default_factory=threading.Lock)- _completed_methods: set[FlowMethodName] = PrivateAttr(default_factory=set)- _method_call_counts: dict[FlowMethodName, int] = PrivateAttr(default_factory=dict)- _is_execution_resuming: bool = PrivateAttr(default=False)- _event_futures: list[Future[None]] = PrivateAttr(default_factory=list)- _pending_feedback_context: PendingFeedbackContext | None = PrivateAttr(default=None)- _human_feedback_method_outputs: dict[str, Any] = PrivateAttr(default_factory=dict)- _input_history: list[InputHistoryEntry] = PrivateAttr(default_factory=list)- _state: Any = PrivateAttr(default=None)-- def __class_getitem__(cls: type[Flow[T]], item: type[T]) -> type[Flow[T]]: # type: ignore[override]- class _FlowGeneric(cls): # type: ignore[valid-type,misc]- pass-- _FlowGeneric.__name__ = f"{cls.__name__}[{item.__name__}]"- _FlowGeneric._initial_state_t = item- return _FlowGeneric-- def __setattr__(self, name: str, value: Any) -> None:- """Allow arbitrary attribute assignment for backward compat with plain class."""- if name in self.model_fields or name in self.__private_attributes__:- super().__setattr__(name, value)- else:- object.__setattr__(self, name, value)-- def model_post_init(self, __context: Any) -> None:- self._flow_post_init()-- def _flow_post_init(self) -> None:- """Heavy initialization: state creation, events, memory, method registration."""- if getattr(self, "_flow_post_init_done", False):- return- object.__setattr__(self, "_flow_post_init_done", True)-- if self._state is None:- self._state = self._create_initial_state()-- tracing_enabled = should_enable_tracing(override=self.tracing)- set_tracing_enabled(tracing_enabled)-- trace_listener = TraceCollectionListener()- trace_listener.setup_listeners(crewai_event_bus)-- if not self.suppress_flow_events:- crewai_event_bus.emit(- self,- FlowCreatedEvent(- type="flow_created",- flow_name=self.name or self.__class__.__name__,- ),- )-- # Auto-create memory if not provided at class or instance level.- # Internal flows (RecallFlow, EncodingFlow) set _skip_auto_memory- # to avoid creating a wasteful standalone Memory instance.- if self.memory is None and not getattr(self, "_skip_auto_memory", False):- from crewai.memory.utils import sanitize_scope_name-- flow_name = sanitize_scope_name(self.name or self.__class__.__name__)- self.memory = Memory(root_scope=f"/flow/{flow_name}")-- for method_name in dir(self):- if not method_name.startswith("_"):- method = getattr(self, method_name)- if is_flow_method(method):- if not hasattr(method, "__self__"):- method = method.__get__(self, self.__class__)- self._methods[method.__name__] = method-- def recall(self, query: str, **kwargs: Any) -> Any:- """Recall relevant memories. Delegates to this flow's memory.-- Args:- query: Natural language query.- **kwargs: Passed to memory.recall (e.g. scope, categories, limit, depth).-- Returns:- Result of memory.recall(query, **kwargs).-- Raises:- ValueError: If no memory is configured for this flow.- """- if self.memory is None:- raise ValueError("No memory configured for this flow")- return self.memory.recall(query, **kwargs)-- def remember(self, content: str | list[str], **kwargs: Any) -> Any:- """Store one or more items in memory.-- Pass a single string for synchronous save (returns the MemoryRecord).- Pass a list of strings for non-blocking batch save (returns immediately).-- Args:- content: Text or list of texts to remember.- **kwargs: Passed to memory.remember / remember_many- (e.g. scope, categories, metadata, importance).-- Returns:- MemoryRecord for single item, empty list for batch (background save).-- Raises:- ValueError: If no memory is configured for this flow.- TypeError: If batch remember is attempted on a MemoryScope or MemorySlice.- """- if self.memory is None:- raise ValueError("No memory configured for this flow")- if isinstance(content, list):- if not isinstance(self.memory, Memory):- raise TypeError(- "Batch remember requires a Memory instance, "- f"got {type(self.memory).__name__}"- )- return self.memory.remember_many(content, **kwargs)- return self.memory.remember(content, **kwargs)-- def extract_memories(self, content: str) -> list[str]:- """Extract discrete memories from content. Delegates to this flow's memory.-- Args:- content: Raw text (e.g. task + result dump).-- Returns:- List of short, self-contained memory statements.-- Raises:- ValueError: If no memory is configured for this flow.- """- if self.memory is None:- raise ValueError("No memory configured for this flow")- result: list[str] = self.memory.extract_memories(content)- return result-- def _mark_or_listener_fired(self, listener_name: FlowMethodName) -> bool:- """Mark an OR listener as fired atomically.-- Args:- listener_name: The name of the OR listener to mark.-- Returns:- True if this call was the first to fire the listener.- False if the listener was already fired.- """- with self._or_listeners_lock:- if listener_name in self._fired_or_listeners:- return False- self._fired_or_listeners.add(listener_name)- return True-- def _clear_or_listeners(self) -> None:- """Clear fired OR listeners for cyclic flows."""- with self._or_listeners_lock:- self._fired_or_listeners.clear()-- def _discard_or_listener(self, listener_name: FlowMethodName) -> None:- """Discard a single OR listener from the fired set."""- with self._or_listeners_lock:- self._fired_or_listeners.discard(listener_name)-- def _build_racing_groups(self) -> dict[frozenset[FlowMethodName], FlowMethodName]:- """Identify groups of methods that race for the same OR listener.-- Analyzes the flow graph to find listeners with OR conditions that have- multiple trigger methods. These trigger methods form a "racing group"- where only the first to complete should trigger the OR listener.-- Only methods that are EXCLUSIVELY sources for the OR listener are included- in the racing group. Methods that are also triggers for other listeners- (e.g., AND conditions) are not cancelled when another racing source wins.-- Returns:- Dictionary mapping frozensets of racing method names to their- shared OR listener name.-- Example:- If we have `@listen(or_(method_a, method_b))` on `handler`,- and method_a/method_b aren't used elsewhere,- this returns: {frozenset({'method_a', 'method_b'}): 'handler'}- """- racing_groups: dict[frozenset[FlowMethodName], FlowMethodName] = {}-- method_to_listeners: dict[FlowMethodName, set[FlowMethodName]] = {}- for listener_name, condition_data in self._listeners.items():- if is_simple_flow_condition(condition_data):- _, methods = condition_data- for m in methods:- method_to_listeners.setdefault(m, set()).add(listener_name)- elif is_flow_condition_dict(condition_data):- all_methods = _extract_all_methods_recursive(condition_data)- for m in all_methods:- method_name = FlowMethodName(m) if isinstance(m, str) else m- method_to_listeners.setdefault(method_name, set()).add(- listener_name- )-- for listener_name, condition_data in self._listeners.items():- if listener_name in self._routers:- continue-- trigger_methods: set[FlowMethodName] = set()-- if is_simple_flow_condition(condition_data):- condition_type, methods = condition_data- if condition_type == OR_CONDITION and len(methods) > 1:- trigger_methods = set(methods)-- elif is_flow_condition_dict(condition_data):- top_level_type = condition_data.get("type", OR_CONDITION)- if top_level_type == OR_CONDITION:- all_methods = _extract_all_methods_recursive(condition_data)- if len(all_methods) > 1:- trigger_methods = set(- FlowMethodName(m) if isinstance(m, str) else m- for m in all_methods- )-- if trigger_methods:- exclusive_methods = {- m- for m in trigger_methods- if method_to_listeners.get(m, set()) == {listener_name}- }- if len(exclusive_methods) > 1:- racing_groups[frozenset(exclusive_methods)] = listener_name-- return racing_groups-- def _get_racing_group_for_listeners(- self,- listener_names: list[FlowMethodName],- ) -> tuple[frozenset[FlowMethodName], FlowMethodName] | None:- """Check if the given listeners form a racing group.-- Args:- listener_names: List of listener method names being executed.-- Returns:- Tuple of (racing_members, or_listener_name) if these listeners race,- None otherwise.- """- if not hasattr(self, "_racing_groups_cache"):- self._racing_groups_cache = self._build_racing_groups()-- listener_set = set(listener_names)-- for racing_members, or_listener in self._racing_groups_cache.items():- if racing_members & listener_set:- racing_subset = racing_members & listener_set- if len(racing_subset) > 1:- return (frozenset(racing_subset), or_listener)-- return None-- async def _execute_racing_listeners(- self,- racing_listeners: frozenset[FlowMethodName],- other_listeners: list[FlowMethodName],- result: Any,- triggering_event_id: str | None = None,- ) -> None:- """Execute racing listeners with first-wins semantics.-- Racing listeners are executed in parallel, but once the first one- completes, the others are cancelled. Non-racing listeners in the- same batch are executed normally in parallel.-- Args:- racing_listeners: Set of listener names that race for an OR condition.- other_listeners: Other listeners to execute in parallel (not racing).- result: The result from the triggering method.- triggering_event_id: The event_id of the event that triggered these listeners.- """- racing_tasks = [- asyncio.create_task(- self._execute_single_listener(name, result, triggering_event_id),- name=str(name),- )- for name in racing_listeners- ]-- other_tasks = [- asyncio.create_task(- self._execute_single_listener(name, result, triggering_event_id),- name=str(name),- )- for name in other_listeners- ]-- if racing_tasks:- for coro in asyncio.as_completed(racing_tasks):- try:- await coro- except Exception as e:- logger.debug(f"Racing listener failed: {e}")- continue- break-- for task in racing_tasks:- if not task.done():- task.cancel()-- if other_tasks:- await asyncio.gather(*other_tasks, return_exceptions=True)-- @classmethod- def from_pending(- cls,- flow_id: str,- persistence: FlowPersistence | None = None,- **kwargs: Any,- ) -> Flow[Any]:- """Create a Flow instance from a pending feedback state.-- This classmethod is used to restore a flow that was paused waiting- for async human feedback. It loads the persisted state and pending- feedback context, then returns a flow instance ready to resume.-- Args:- flow_id: The unique identifier of the paused flow (from state.id)- persistence: The persistence backend where the state was saved.- If not provided, defaults to SQLiteFlowPersistence().- **kwargs: Additional keyword arguments passed to the Flow constructor-- Returns:- A new Flow instance with restored state, ready to call resume()-- Raises:- ValueError: If no pending feedback exists for the given flow_id-- Example:- ```python- # Simple usage with default persistence:- flow = MyFlow.from_pending("abc-123")- result = flow.resume("looks good!")-- # Or with custom persistence:- persistence = SQLiteFlowPersistence("custom.db")- flow = MyFlow.from_pending("abc-123", persistence)- result = flow.resume("looks good!")- ```- """- if persistence is None:- from crewai.flow.persistence import SQLiteFlowPersistence-- persistence = SQLiteFlowPersistence()-- loaded = persistence.load_pending_feedback(flow_id)- if loaded is None:- raise ValueError(f"No pending feedback found for flow_id: {flow_id}")-- state_data, pending_context = loaded-- instance = cls(persistence=persistence, **kwargs)- instance._initialize_state(state_data)- instance._pending_feedback_context = pending_context- instance._is_execution_resuming = True-- return instance-- @property- def pending_feedback(self) -> PendingFeedbackContext | None:- """Get the pending feedback context if this flow is waiting for feedback.-- Returns:- The PendingFeedbackContext if the flow is paused waiting for feedback,- None otherwise.-- Example:- ```python- flow = MyFlow.from_pending("abc-123", persistence)- if flow.pending_feedback:- print(f"Waiting for feedback on: {flow.pending_feedback.method_name}")- ```- """- return self._pending_feedback_context-- def resume(self, feedback: str = "") -> Any:- """Resume flow execution, optionally with human feedback.-- This method continues flow execution after a flow was paused for- async human feedback. It processes the feedback (including LLM-based- outcome collapsing if emit was specified), stores the result, and- triggers downstream listeners.-- Note:- If called from within an async context (running event loop),- use `await flow.resume_async(feedback)` instead.-- Args:- feedback: The human's feedback as a string. If empty, uses- default_outcome or the first emit option.-- Returns:- The final output from the flow execution, or HumanFeedbackPending- if another feedback point is reached.-- Raises:- ValueError: If no pending feedback context exists (flow wasn't paused)- RuntimeError: If called from within a running event loop (use resume_async instead)-- Example:- ```python- # In a sync webhook handler:- def handle_feedback(flow_id: str, feedback: str):- flow = MyFlow.from_pending(flow_id)- result = flow.resume(feedback)- return result--- # In an async handler, use resume_async instead:- async def handle_feedback_async(flow_id: str, feedback: str):- flow = MyFlow.from_pending(flow_id)- result = await flow.resume_async(feedback)- return result- ```- """- try:- loop = asyncio.get_running_loop()- except RuntimeError:- loop = None-- if loop is not None:- raise RuntimeError(- "resume() cannot be called from within an async context. "- "Use 'await flow.resume_async(feedback)' instead."- )-- return asyncio.run(self.resume_async(feedback))-- async def resume_async(self, feedback: str = "") -> Any:- """Async version of resume.-- Resume flow execution, optionally with human feedback asynchronously.-- Args:- feedback: The human's feedback as a string. If empty, uses- default_outcome or the first emit option.-- Returns:- The final output from the flow execution, or HumanFeedbackPending- if another feedback point is reached.-- Raises:- ValueError: If no pending feedback context exists- """- from datetime import datetime-- from crewai.flow.human_feedback import HumanFeedbackResult-- if self._pending_feedback_context is None:- raise ValueError(- "No pending feedback context. Use from_pending() to restore a paused flow."- )-- if get_current_parent_id() is None:- reset_emission_counter()- reset_last_event_id()-- if not self.suppress_flow_events:- future = crewai_event_bus.emit(- self,- FlowStartedEvent(- type="flow_started",- flow_name=self.name or self.__class__.__name__,- inputs=None,- ),- )- if future and isinstance(future, Future):- try:- await asyncio.wrap_future(future)- except Exception:- logger.warning("FlowStartedEvent handler failed", exc_info=True)-- get_env_context()-- context = self._pending_feedback_context- emit = context.emit- default_outcome = context.default_outcome-- # Try to get the live LLM from the re-imported decorator first.- # This preserves the fully-configured object (credentials, safety_settings, etc.)- # for same-process resume. For cross-process resume, fall back to the- # serialized context.llm which is now a dict with full config (or a legacy string).- from crewai.flow.human_feedback import _deserialize_llm_from_context-- llm = None- method = self._methods.get(FlowMethodName(context.method_name))- if method is not None:- live_llm = getattr(method, "_hf_llm", None)- if live_llm is not None:- from crewai.llms.base_llm import BaseLLM as BaseLLMClass-- if isinstance(live_llm, BaseLLMClass):- llm = live_llm-- if llm is None:- llm = _deserialize_llm_from_context(context.llm)-- collapsed_outcome: str | None = None-- if not feedback.strip():- if default_outcome:- collapsed_outcome = default_outcome- elif emit:- collapsed_outcome = emit[0]- elif emit:- if llm is not None:- collapsed_outcome = self._collapse_to_outcome(- feedback=feedback,- outcomes=emit,- llm=llm,- )- else:- collapsed_outcome = emit[0]-- result = HumanFeedbackResult(- output=context.method_output,- feedback=feedback,- outcome=collapsed_outcome,- timestamp=datetime.now(),- method_name=context.method_name,- metadata=context.metadata,- )-- self.human_feedback_history.append(result)- self.last_human_feedback = result-- self._completed_methods.add(FlowMethodName(context.method_name))-- self._pending_feedback_context = None-- if self.persistence:- self.persistence.clear_pending_feedback(context.flow_id)-- crewai_event_bus.emit(- self,- MethodExecutionFinishedEvent(- type="method_execution_finished",- flow_name=self.name or self.__class__.__name__,- method_name=context.method_name,- result=collapsed_outcome if emit else result,- state=self._state,- ),- )-- # Clear resumption flag before triggering listeners- # This allows methods to re-execute in loops (e.g., implement_changes → suggest_changes → implement_changes)- self._is_execution_resuming = False-- if emit and collapsed_outcome is None:- collapsed_outcome = default_outcome or emit[0]- result.outcome = collapsed_outcome-- try:- if emit and collapsed_outcome:- self._method_outputs.append(collapsed_outcome)- await self._execute_listeners(- FlowMethodName(collapsed_outcome),- result,- )- else:- await self._execute_listeners(- FlowMethodName(context.method_name),- result,- )- except Exception as e:- # Check if flow was paused again for human feedback (loop case)- from crewai.flow.async_feedback.types import HumanFeedbackPending-- if isinstance(e, HumanFeedbackPending):- self._pending_feedback_context = e.context-- if self.persistence is None:- from crewai.flow.persistence import SQLiteFlowPersistence-- self.persistence = SQLiteFlowPersistence()-- state_data = (- self._state- if isinstance(self._state, dict)- else self._state.model_dump()- )- self.persistence.save_pending_feedback(- flow_uuid=e.context.flow_id,- context=e.context,- state_data=state_data,- )-- crewai_event_bus.emit(- self,- FlowPausedEvent(- type="flow_paused",- flow_name=self.name or self.__class__.__name__,- flow_id=e.context.flow_id,- method_name=e.context.method_name,- state=self._copy_and_serialize_state(),- message=e.context.message,- emit=e.context.emit,- ),- )- return e- raise+The implementation now lives in three modules, split by concern:- final_result = self._method_outputs[-1] if self._method_outputs else result+- ``crewai.flow.dsl`` -- authoring decorators (``@start`` / ``@listen`` /+ ``@router``, ``or_`` / ``and_``)+- ``crewai.flow.flow_definition`` -- the structural model extracted from the DSL+- ``crewai.flow.runtime`` -- the Flow execution engine and state- if self._event_futures:- await asyncio.gather(- *[- asyncio.wrap_future(f)- for f in self._event_futures- if isinstance(f, Future)- ]- )- self._event_futures.clear()-- if not self.suppress_flow_events:- future = crewai_event_bus.emit(- self,- FlowFinishedEvent(- type="flow_finished",- flow_name=self.name or self.__class__.__name__,- result=final_result,- state=self._copy_and_serialize_state(),- ),- )- if future and isinstance(future, Future):- try:- await asyncio.wrap_future(future)- except Exception:- logger.warning("FlowFinishedEvent handler failed", exc_info=True)-- trace_listener = TraceCollectionListener()- if trace_listener.batch_manager.batch_owner_type == "flow":- if trace_listener.first_time_handler.is_first_time:- trace_listener.first_time_handler.mark_events_collected()- trace_listener.first_time_handler.handle_execution_completion()- else:- trace_listener.batch_manager.finalize_batch()-- return final_result-- def _create_initial_state(self) -> T:- """Create and initialize flow state with UUID and default values.-- Returns:- New state instance with UUID and default values initialized-- Raises:- ValueError: If structured state model lacks 'id' field- TypeError: If state is neither BaseModel nor dictionary- """- init_state = self.initial_state-- if init_state is None and hasattr(self, "_initial_state_t"):- state_type = self._initial_state_t- if isinstance(state_type, type):- if issubclass(state_type, FlowState):- instance = state_type()- if not getattr(instance, "id", None):- object.__setattr__(instance, "id", str(uuid4()))- return cast(T, instance)- if issubclass(state_type, BaseModel):-- class StateWithId(FlowState, state_type): # type: ignore- pass-- instance = StateWithId()- if not getattr(instance, "id", None):- object.__setattr__(instance, "id", str(uuid4()))- return cast(T, instance)- if state_type is dict:- return cast(T, {"id": str(uuid4())})-- if init_state is None:- return cast(T, {"id": str(uuid4())})-- if isinstance(init_state, type):- state_class = init_state- if issubclass(state_class, FlowState):- return cast(T, state_class())- if issubclass(state_class, BaseModel):- model_fields = getattr(state_class, "model_fields", None)- if not model_fields or "id" not in model_fields:- raise ValueError("Flow state model must have an 'id' field")- model_instance = state_class()- if not getattr(model_instance, "id", None):- object.__setattr__(model_instance, "id", str(uuid4()))- return cast(T, model_instance)- if init_state is dict:- return cast(T, {"id": str(uuid4())})-- if isinstance(init_state, dict):- new_state = dict(init_state) # Copy to avoid mutations- if "id" not in new_state:- new_state["id"] = str(uuid4())- return cast(T, new_state)-- if isinstance(init_state, BaseModel):- model = init_state- if hasattr(model, "id"):- state_dict = model.model_dump()- if not state_dict.get("id"):- state_dict["id"] = str(uuid4())- model_class = type(model)- return cast(T, model_class(**state_dict))-- class StateWithId(FlowState, type(model)): # type: ignore- pass-- state_dict = model.model_dump()- state_dict["id"] = str(uuid4())- return cast(T, StateWithId(**state_dict))- raise TypeError(- f"Initial state must be dict or BaseModel, got {type(self.initial_state)}"- )-- def _copy_state(self) -> T:- """Create a copy of the current state.-- Returns:- A copy of the current state- """- if isinstance(self._state, BaseModel):- try:- return cast(T, self._state.model_copy(deep=True))- except (TypeError, AttributeError):- try:- state_dict = self._state.model_dump()- model_class = type(self._state)- return cast(T, model_class(**state_dict))- except Exception:- return cast(T, self._state.model_copy(deep=False))- else:- try:- return cast(T, copy.deepcopy(self._state))- except (TypeError, AttributeError):- return cast(T, self._state.copy())-- @property- def state(self) -> T:- return StateProxy(self._state, self._state_lock) # type: ignore[return-value]-- @property- def method_outputs(self) -> list[Any]:- """Returns the list of all outputs from executed methods."""- return self._method_outputs-- @property- def flow_id(self) -> str:- """Returns the unique identifier of this flow instance.-- This property provides a consistent way to access the flow's unique identifier- regardless of the underlying state implementation (dict or BaseModel).-- Returns:- str: The flow's unique identifier, or an empty string if not found-- Note:- This property safely handles both dictionary and BaseModel state types,- returning an empty string if the ID cannot be retrieved rather than raising- an exception.-- Example:- ```python- flow = MyFlow()- print(f"Current flow ID: {flow.flow_id}") # Safely get flow ID- ```- """- try:- if not hasattr(self, "_state"):- return ""-- if isinstance(self._state, dict):- return str(self._state.get("id", ""))- if isinstance(self._state, BaseModel):- return str(getattr(self._state, "id", ""))- return ""- except (AttributeError, TypeError):- return "" # Safely handle any unexpected attribute access issues-- def _initialize_state(self, inputs: dict[str, Any]) -> None:- """Initialize or update flow state with new inputs.-- Args:- inputs: Dictionary of state values to set/update-- Raises:- ValueError: If validation fails for structured state- TypeError: If state is neither BaseModel nor dictionary- """- if isinstance(self._state, dict):- # If inputs contains an id, use it (for restoring from persistence);- # otherwise preserve the current id or generate a new one.- current_id = self._state.get("id")- inputs_has_id = "id" in inputs-- for k, v in inputs.items():- self._state[k] = v-- if not inputs_has_id:- if current_id:- self._state["id"] = current_id- elif "id" not in self._state:- self._state["id"] = str(uuid4())- elif isinstance(self._state, BaseModel):- try:- model = self._state- if hasattr(model, "model_dump"):- current_state = model.model_dump()- elif hasattr(model, "dict"):- current_state = model.dict()- else:- current_state = {- k: v for k, v in model.__dict__.items() if not k.startswith("_")- }-- new_state = {**current_state, **inputs}-- model_class = type(model)- if hasattr(model_class, "model_validate"):- self._state = cast(T, model_class.model_validate(new_state))- elif hasattr(model_class, "parse_obj"):- self._state = cast(T, model_class.parse_obj(new_state))- else:- self._state = cast(T, model_class(**new_state))- except ValidationError as e:- raise ValueError(f"Invalid inputs for structured state: {e}") from e- else:- raise TypeError("State must be a BaseModel instance or a dictionary.")-- def _restore_state(self, stored_state: dict[str, Any]) -> None:- """Restore flow state from persistence.-- Args:- stored_state: Previously stored state to restore-- Raises:- ValueError: If validation fails for structured state- TypeError: If state is neither BaseModel nor dictionary- """- stored_id = stored_state.get("id")- if not stored_id:- raise ValueError("Stored state must have an 'id' field")-- if isinstance(self._state, dict):- self._state.clear()- self._state.update(stored_state)- elif isinstance(self._state, BaseModel):- model = self._state- if hasattr(model, "model_validate"):- self._state = cast(T, type(model).model_validate(stored_state))- elif hasattr(model, "parse_obj"):- self._state = cast(T, type(model).parse_obj(stored_state))- else:- self._state = cast(T, type(model)(**stored_state))- else:- raise TypeError(f"State must be dict or BaseModel, got {type(self._state)}")-- def reload(self, execution_data: FlowExecutionData) -> None:- """Reloads the flow from an execution data dict.-- This method restores the flow's execution ID, completed methods, and state,- allowing it to resume from where it left off.-- Args:- execution_data: Flow execution data containing:- - id: Flow execution ID- - flow: Flow structure- - completed_methods: list of successfully completed methods- - execution_methods: All execution methods with their status- """- flow_id = execution_data.get("id")- if flow_id:- self._update_state_field("id", flow_id)-- self._completed_methods = {- cast(FlowMethodName, name)- for method_data in execution_data.get("completed_methods", [])- if (name := method_data.get("flow_method", {}).get("name")) is not None- }-- execution_methods = execution_data.get("execution_methods", [])- if not execution_methods:- return-- sorted_methods = sorted(- execution_methods,- key=lambda m: m.get("started_at", ""),- )-- state_to_apply = None- for method in reversed(sorted_methods):- if method.get("final_state"):- state_to_apply = method["final_state"]- break-- if not state_to_apply and sorted_methods:- last_method = sorted_methods[-1]- if last_method.get("initial_state"):- state_to_apply = last_method["initial_state"]-- if state_to_apply:- self._apply_state_updates(state_to_apply)-- for method in sorted_methods[:-1]:- method_name = cast(- FlowMethodName | None, method.get("flow_method", {}).get("name")- )- if method_name:- self._completed_methods.add(method_name)-- def _update_state_field(self, field_name: str, value: Any) -> None:- """Update a single field in the state."""- if isinstance(self._state, dict):- self._state[field_name] = value- elif hasattr(self._state, field_name):- object.__setattr__(self._state, field_name, value)-- def _apply_state_updates(self, updates: dict[str, Any]) -> None:- """Apply multiple state updates efficiently."""- if isinstance(self._state, dict):- self._state.update(updates)- elif hasattr(self._state, "__dict__"):- for key, value in updates.items():- if hasattr(self._state, key):- object.__setattr__(self._state, key, value)-- def kickoff(- self,- inputs: dict[str, Any] | None = None,- input_files: dict[str, FileInput] | None = None,- from_checkpoint: CheckpointConfig | None = None,- restore_from_state_id: str | None = None,- ) -> Any | FlowStreamingOutput:- """Start the flow execution in a synchronous context.-- This method wraps kickoff_async so that all state initialization and event- emission is handled in the asynchronous method.-- Args:- inputs: Optional dictionary containing input values and/or a state ID.- input_files: Optional dict of named file inputs for the flow.- from_checkpoint: Optional checkpoint config. If ``restore_from``- is set, the flow resumes from that checkpoint.- restore_from_state_id: Optional UUID of a previously-persisted flow- whose latest snapshot should hydrate this run's state. The new- run is assigned a fresh ``state.id`` (or ``inputs["id"]`` if- pinned), so its ``@persist`` writes land under a separate- persistence key and the source flow's history is preserved.- If the referenced state is not found, the kickoff falls back- silently to baseline behavior. Cannot be combined with- ``from_checkpoint``; passing both raises ``ValueError``.-- Returns:- The final output from the flow or FlowStreamingOutput if streaming.- """- if from_checkpoint is not None and restore_from_state_id is not None:- raise ValueError(- "Cannot combine `from_checkpoint` and `restore_from_state_id`. "- "These parameters target different state systems "- "(Checkpointing and @persist) and cannot be used together."- )- restored = apply_checkpoint(self, from_checkpoint)- if restored is not None:- return restored.kickoff(inputs=inputs, input_files=input_files)- if self.stream:- result_holder: list[Any] = []- current_task_info: TaskInfo = {- "index": 0,- "name": "",- "id": "",- "agent_role": "",- "agent_id": "",- }-- state = create_streaming_state(- current_task_info, result_holder, use_async=False- )- output_holder: list[CrewStreamingOutput | FlowStreamingOutput] = []-- def run_flow() -> None:- try:- self.stream = False- result = self.kickoff(- inputs=inputs,- input_files=input_files,- restore_from_state_id=restore_from_state_id,- )- result_holder.append(result)- except Exception as e:- # HumanFeedbackPending is expected control flow, not an error- from crewai.flow.async_feedback.types import HumanFeedbackPending-- if isinstance(e, HumanFeedbackPending):- result_holder.append(e)- else:- signal_error(state, e)- finally:- self.stream = True- signal_end(state)-- streaming_output = FlowStreamingOutput(- sync_iterator=create_chunk_generator(state, run_flow, output_holder)- )- register_cleanup(streaming_output, state)- output_holder.append(streaming_output)-- return streaming_output-- async def _run_flow() -> Any:- return await self.kickoff_async(- inputs,- input_files,- restore_from_state_id=restore_from_state_id,- )-- try:- asyncio.get_running_loop()- ctx = contextvars.copy_context()- with ThreadPoolExecutor(max_workers=1) as pool:- return pool.submit(ctx.run, asyncio.run, _run_flow()).result()- except RuntimeError:- return asyncio.run(_run_flow())-- async def kickoff_async(- self,- inputs: dict[str, Any] | None = None,- input_files: dict[str, FileInput] | None = None,- from_checkpoint: CheckpointConfig | None = None,- restore_from_state_id: str | None = None,- ) -> Any | FlowStreamingOutput:- """Start the flow execution asynchronously.-- This method performs state restoration (if an 'id' is provided and persistence is available)- and updates the flow state with any additional inputs. It then emits the FlowStartedEvent,- logs the flow startup, and executes all start methods. Once completed, it emits the- FlowFinishedEvent and returns the final output.-- Args:- inputs: Optional dictionary containing input values and/or a state ID for restoration.- input_files: Optional dict of named file inputs for the flow.- from_checkpoint: Optional checkpoint config. If ``restore_from``- is set, the flow resumes from that checkpoint.- restore_from_state_id: Optional UUID of a previously-persisted flow- whose latest snapshot should hydrate this run's state. The new- run is assigned a fresh ``state.id`` (or ``inputs["id"]`` if- pinned), so subsequent ``@persist`` writes land under a- separate persistence key. If the referenced state is not- found, falls back silently to baseline. Cannot be combined- with ``from_checkpoint``; passing both raises ``ValueError``.-- Returns:- The final output from the flow, which is the result of the last executed method.- """- if from_checkpoint is not None and restore_from_state_id is not None:- raise ValueError(- "Cannot combine `from_checkpoint` and `restore_from_state_id`. "- "These parameters target different state systems "- "(Checkpointing and @persist) and cannot be used together."- )- restored = apply_checkpoint(self, from_checkpoint)- if restored is not None:- return await restored.kickoff_async(inputs=inputs, input_files=input_files)- if self.stream:- result_holder: list[Any] = []- current_task_info: TaskInfo = {- "index": 0,- "name": "",- "id": "",- "agent_role": "",- "agent_id": "",- }-- state = create_streaming_state(- current_task_info, result_holder, use_async=True- )- output_holder: list[CrewStreamingOutput | FlowStreamingOutput] = []-- async def run_flow() -> None:- try:- self.stream = False- result = await self.kickoff_async(- inputs=inputs,- input_files=input_files,- restore_from_state_id=restore_from_state_id,- )- result_holder.append(result)- except Exception as e:- # HumanFeedbackPending is expected control flow, not an error- from crewai.flow.async_feedback.types import HumanFeedbackPending-- if isinstance(e, HumanFeedbackPending):- result_holder.append(e)- else:- signal_error(state, e, is_async=True)- finally:- self.stream = True- signal_end(state, is_async=True)-- streaming_output = FlowStreamingOutput(- async_iterator=create_async_chunk_generator(- state, run_flow, output_holder- )- )- register_cleanup(streaming_output, state)- output_holder.append(streaming_output)-- return streaming_output-- ctx = baggage.set_baggage("flow_inputs", inputs or {})- ctx = baggage.set_baggage("flow_input_files", input_files or {}, context=ctx)- flow_token = attach(ctx)-- flow_id_token = None- request_id_token = None- if current_flow_id.get() is None:- flow_id_token = current_flow_id.set(self.flow_id)- if current_flow_request_id.get() is None:- request_id_token = current_flow_request_id.set(self.flow_id)-- try:- # Reset flow state for fresh execution unless restoring from persistence- is_restoring = (- inputs and "id" in inputs and self.persistence is not None- ) or self.checkpoint_completed_methods is not None- if not is_restoring:- # Clear completed methods and outputs for a fresh start- self._completed_methods.clear()- self._method_outputs.clear()- self._pending_and_listeners.clear()- self._clear_or_listeners()- self._method_call_counts.clear()- else:- # Only enter resumption mode if there are completed methods to- # replay. When _completed_methods is empty (e.g. a pure- # state-reload via kickoff(inputs={"id": ...})), the flow- # executes from scratch and the flag would incorrectly- # suppress cyclic re-execution on the second iteration.- if self._completed_methods:- self._is_execution_resuming = True-- # Fork hydration: when restore_from_state_id is set and persistence is- # available, hydrate self._state from the source UUID's latest snapshot- # and reassign state.id to a fresh value so subsequent @persist writes- # don't extend the source flow's history. If the source state is not- # found, fall through silently to the existing inputs handling.- fork_succeeded = False- if restore_from_state_id is not None and self.persistence is not None:- stored_state = self.persistence.load_state(restore_from_state_id)- if stored_state:- self._log_flow_event(- f"Forking flow state from UUID: {restore_from_state_id}"- )- self._restore_state(stored_state)- # Pin to inputs["id"] when provided, otherwise mint a fresh- # UUID. NOTE: pinning inputs.id while forking shares a- # persistence key with another flow — usually you want only- # restore_from_state_id.- new_state_id = (inputs.get("id") if inputs else None) or str(- uuid4()- )- if isinstance(self._state, dict):- self._state["id"] = new_state_id- elif isinstance(self._state, BaseModel):- setattr(self._state, "id", new_state_id) # noqa: B010- fork_succeeded = True- else:- self._log_flow_event(- "No flow state found for restore_from_state_id: "- f"{restore_from_state_id}; proceeding without hydration",- color="yellow",- )-- if inputs:- # Override the id in the state if it exists in inputs.- # Skip when the fork already assigned state.id above.- if "id" in inputs and not fork_succeeded:- if isinstance(self._state, dict):- self._state["id"] = inputs["id"]- elif isinstance(self._state, BaseModel):- setattr(self._state, "id", inputs["id"]) # noqa: B010-- # If persistence is enabled, attempt to restore the stored state using the provided id.- # Skip when the fork already restored self._state above.- if (- "id" in inputs- and self.persistence is not None- and not fork_succeeded- ):- restore_uuid = inputs["id"]- stored_state = self.persistence.load_state(restore_uuid)- if stored_state:- self._log_flow_event(- f"Loading flow state from memory for UUID: {restore_uuid}"- )- self._restore_state(stored_state)- else:- self._log_flow_event(- f"No flow state found for UUID: {restore_uuid}", color="red"- )-- # Update state with any additional inputs (ignoring the 'id' key)- filtered_inputs = {k: v for k, v in inputs.items() if k != "id"}- if filtered_inputs:- self._initialize_state(filtered_inputs)-- if get_current_parent_id() is None:- reset_emission_counter()- reset_last_event_id()-- if not self.suppress_flow_events:- future = crewai_event_bus.emit(- self,- FlowStartedEvent(- type="flow_started",- flow_name=self.name or self.__class__.__name__,- inputs=inputs,- ),- )- if future:- try:- await asyncio.wrap_future(future)- except Exception:- logger.warning("FlowStartedEvent handler failed", exc_info=True)- self._log_flow_event(- f"Flow started with ID: {self.flow_id}", color="bold magenta"- )-- # After FlowStarted (when not suppressed): env events must not pre-empt- # trace batch init with implicit "crew" execution_type.- get_env_context()-- if inputs is not None and "id" not in inputs:- self._initialize_state(inputs)-- if self._is_execution_resuming:- await self._replay_recorded_events()-- try:- # Determine which start methods to execute at kickoff- # Conditional start methods (with __trigger_methods__) are only triggered by their conditions- # UNLESS there are no unconditional starts (then all starts run as entry points)- unconditional_starts = [- start_method- for start_method in self._start_methods- if not getattr(- self._methods.get(start_method), "__trigger_methods__", None- )- ]- # If there are unconditional starts, only run those at kickoff- # If there are NO unconditional starts, run all starts (including conditional ones)- starts_to_execute = (- unconditional_starts- if unconditional_starts- else self._start_methods- )- tasks = [- self._execute_start_method(start_method)- for start_method in starts_to_execute- ]- await asyncio.gather(*tasks)- except Exception as e:- # Check if flow was paused for human feedback- from crewai.flow.async_feedback.types import HumanFeedbackPending-- if isinstance(e, HumanFeedbackPending):- # Auto-save pending feedback (create default persistence if needed)- if self.persistence is None:- from crewai.flow.persistence import SQLiteFlowPersistence-- self.persistence = SQLiteFlowPersistence()-- state_data = (- self._state- if isinstance(self._state, dict)- else self._state.model_dump()- )- self.persistence.save_pending_feedback(- flow_uuid=e.context.flow_id,- context=e.context,- state_data=state_data,- )-- # Emit flow paused event- future = crewai_event_bus.emit(- self,- FlowPausedEvent(- type="flow_paused",- flow_name=self.name or self.__class__.__name__,- flow_id=e.context.flow_id,- method_name=e.context.method_name,- state=self._copy_and_serialize_state(),- message=e.context.message,- emit=e.context.emit,- ),- )- if future and isinstance(future, Future):- self._event_futures.append(future)-- # Wait for events to be processed- if self._event_futures:- await asyncio.gather(- *[- asyncio.wrap_future(f)- for f in self._event_futures- if isinstance(f, Future)- ]- )- self._event_futures.clear()-- # Return the pending exception instead of raising- # This allows the caller to handle the paused state gracefully- return e-- # Re-raise other exceptions- raise-- # Clear the resumption flag after initial execution completes- self._is_execution_resuming = False-- final_output = self._method_outputs[-1] if self._method_outputs else None-- if self._event_futures:- await asyncio.gather(- *[asyncio.wrap_future(f) for f in self._event_futures]- )- self._event_futures.clear()-- if not self.suppress_flow_events:- future = crewai_event_bus.emit(- self,- FlowFinishedEvent(- type="flow_finished",- flow_name=self.name or self.__class__.__name__,- result=final_output,- state=self._copy_and_serialize_state(),- ),- )- if future:- try:- await asyncio.wrap_future(future)- except Exception:- logger.warning(- "FlowFinishedEvent handler failed", exc_info=True- )-- if not self.suppress_flow_events:- trace_listener = TraceCollectionListener()- if trace_listener.batch_manager.batch_owner_type == "flow":- if trace_listener.first_time_handler.is_first_time:- trace_listener.first_time_handler.mark_events_collected()- trace_listener.first_time_handler.handle_execution_completion()- else:- trace_listener.batch_manager.finalize_batch()-- return final_output- finally:- # Ensure all background memory saves complete before returning- if self.memory is not None and hasattr(self.memory, "drain_writes"):- self.memory.drain_writes()- if request_id_token is not None:- current_flow_request_id.reset(request_id_token)- if flow_id_token is not None:- current_flow_id.reset(flow_id_token)- detach(flow_token)-- async def akickoff(- self,- inputs: dict[str, Any] | None = None,- input_files: dict[str, FileInput] | None = None,- from_checkpoint: CheckpointConfig | None = None,- restore_from_state_id: str | None = None,- ) -> Any | FlowStreamingOutput:- """Native async method to start the flow execution. Alias for kickoff_async.-- Args:- inputs: Optional dictionary containing input values and/or a state ID for restoration.- input_files: Optional dict of named file inputs for the flow.- from_checkpoint: Optional checkpoint config. If ``restore_from``- is set, the flow resumes from that checkpoint.- restore_from_state_id: Optional UUID of a previously-persisted flow- whose latest snapshot should hydrate this run's state. See- ``kickoff_async`` for full semantics.-- Returns:- The final output from the flow, which is the result of the last executed method.- """- return await self.kickoff_async(- inputs,- input_files,- from_checkpoint,- restore_from_state_id=restore_from_state_id,- )-- async def _replay_recorded_events(self) -> None:- """Dispatch recorded ``MethodExecution*`` events from the event record."""- state = crewai_event_bus.runtime_state- if state is None:- return- record = state.event_record- if len(record) == 0:- return-- replayable = (- MethodExecutionStartedEvent,- MethodExecutionFinishedEvent,- MethodExecutionFailedEvent,- )- flow_name = self.name or self.__class__.__name__- nodes = sorted(- (- n- for n in record.all_nodes()- if isinstance(n.event, replayable)- and n.event.flow_name == flow_name- and n.event.method_name in self._completed_methods- ),- key=lambda n: n.event.emission_sequence or 0,- )-- for node in nodes:- future = crewai_event_bus.replay(self, node.event)- if future is not None:- try:- await asyncio.wrap_future(future)- except Exception:- logger.warning(- "Replayed event handler failed: %s",- node.event.type,- exc_info=True,- )-- async def _execute_start_method(self, start_method_name: FlowMethodName) -> None:- """Executes a flow's start method and its triggered listeners.-- This internal method handles the execution of methods marked with @start- decorator and manages the subsequent chain of listener executions.-- Args:- start_method_name: The name of the start method to execute.-- Note:- - Executes the start method and captures its result- - Triggers execution of any listeners waiting on this start method- - Part of the flow's initialization sequence- - Skips execution if method was already completed (e.g., after reload)- - Automatically injects crewai_trigger_payload if available in flow inputs- """- if start_method_name in self._completed_methods:- if self._is_execution_resuming:- # During resumption, skip execution but continue listeners- last_output = self._method_outputs[-1] if self._method_outputs else None- await self._execute_listeners(start_method_name, last_output)- return- # For cyclic flows, clear from completed to allow re-execution- self._completed_methods.discard(start_method_name)- # Also clear fired OR listeners to allow them to fire again in new cycle- self._clear_or_listeners()-- method = self._methods[start_method_name]- enhanced_method = self._inject_trigger_payload_for_start_method(method)-- result, finished_event_id = await self._execute_method(- start_method_name, enhanced_method- )-- # If start method is a router, use its result as an additional trigger- if start_method_name in self._routers and result is not None:- # Execute listeners for the start method name first- await self._execute_listeners(start_method_name, result, finished_event_id)- # Then execute listeners for the router result (e.g., "approved")- router_result_trigger = FlowMethodName(str(result))- listener_result = (- self.last_human_feedback- if self.last_human_feedback is not None- else result- )- await self._execute_listeners(- router_result_trigger, listener_result, finished_event_id- )- else:- await self._execute_listeners(start_method_name, result, finished_event_id)-- def _inject_trigger_payload_for_start_method(- self, original_method: Callable[..., Any]- ) -> Callable[..., Any]:- def prepare_kwargs(- *args: Any, **kwargs: Any- ) -> tuple[tuple[Any, ...], dict[str, Any]]:- inputs = cast(dict[str, Any], baggage.get_baggage("flow_inputs") or {})- trigger_payload = inputs.get("crewai_trigger_payload")-- sig = inspect.signature(original_method)- accepts_trigger_payload = "crewai_trigger_payload" in sig.parameters-- if trigger_payload is not None and accepts_trigger_payload:- kwargs["crewai_trigger_payload"] = trigger_payload- elif trigger_payload is not None:- self._log_flow_event(- f"Trigger payload available but {original_method.__name__} doesn't accept crewai_trigger_payload parameter"- )- return args, kwargs-- if asyncio.iscoroutinefunction(original_method):-- async def enhanced_method(*args: Any, **kwargs: Any) -> Any:- args, kwargs = prepare_kwargs(*args, **kwargs)- return await original_method(*args, **kwargs)- else:-- def enhanced_method(*args: Any, **kwargs: Any) -> Any: # type: ignore[misc]- args, kwargs = prepare_kwargs(*args, **kwargs)- return original_method(*args, **kwargs)-- enhanced_method.__name__ = original_method.__name__- enhanced_method.__doc__ = original_method.__doc__-- return enhanced_method-- async def _execute_method(- self,- method_name: FlowMethodName,- method: Callable[..., Any],- *args: Any,- **kwargs: Any,- ) -> tuple[Any, str | None]:- """Execute a method and emit events.-- Returns:- A tuple of (result, finished_event_id) where finished_event_id is- the event_id of the MethodExecutionFinishedEvent, or None if events- are suppressed.- """- try:- dumped_params = {f"_{i}": arg for i, arg in enumerate(args)} | (- kwargs or {}- )-- if not self.suppress_flow_events:- future = crewai_event_bus.emit(- self,- MethodExecutionStartedEvent(- type="method_execution_started",- method_name=method_name,- flow_name=self.name or self.__class__.__name__,- params=dumped_params,- state=self._copy_and_serialize_state(),- ),- )- if future:- self._event_futures.append(future)-- # Set method name in context so ask() can read it without- # stack inspection. Must happen before copy_context() so the- # value propagates into the thread pool for sync methods.- from crewai.flow.flow_context import current_flow_method_name-- method_name_token = current_flow_method_name.set(method_name)- try:- if asyncio.iscoroutinefunction(method):- result = await method(*args, **kwargs)- else:- # Run sync methods in thread pool for isolation- # This allows Agent.kickoff() to work synchronously inside Flow methods- ctx = contextvars.copy_context()- result = await asyncio.to_thread(ctx.run, method, *args, **kwargs)- finally:- current_flow_method_name.reset(method_name_token)-- # Auto-await coroutines returned from sync methods (enables AgentExecutor pattern)- if asyncio.iscoroutine(result):- result = await result-- self._method_outputs.append(result)-- # For @human_feedback methods with emit, the result is the collapsed outcome- # (e.g., "approved") used for routing. But we want the actual method output- # to be the stored result (for final flow output). Replace the last entry- # if a stashed output exists. Dict-based stash is concurrency-safe and- # handles None return values (presence in dict = stashed, not value).- if method_name in self._human_feedback_method_outputs:- self._method_outputs[-1] = self._human_feedback_method_outputs.pop(- method_name- )-- self._method_execution_counts[method_name] = (- self._method_execution_counts.get(method_name, 0) + 1- )-- self._completed_methods.add(method_name)-- finished_event_id: str | None = None- if not self.suppress_flow_events:- finished_event = MethodExecutionFinishedEvent(- type="method_execution_finished",- method_name=method_name,- flow_name=self.name or self.__class__.__name__,- state=self._copy_and_serialize_state(),- result=result,- )- finished_event_id = finished_event.event_id- future = crewai_event_bus.emit(self, finished_event)- if future:- self._event_futures.append(future)-- return result, finished_event_id- except Exception as e:- # Check if this is a HumanFeedbackPending exception (paused, not failed)- from crewai.flow.async_feedback.types import HumanFeedbackPending-- if isinstance(e, HumanFeedbackPending):- e.context.method_name = method_name-- if self.persistence is None:- from crewai.flow.persistence import SQLiteFlowPersistence-- self.persistence = SQLiteFlowPersistence()-- # Emit paused event (not failed)- if not self.suppress_flow_events:- future = crewai_event_bus.emit(- self,- MethodExecutionPausedEvent(- type="method_execution_paused",- method_name=method_name,- flow_name=self.name or self.__class__.__name__,- state=self._copy_and_serialize_state(),- flow_id=e.context.flow_id,- message=e.context.message,- emit=e.context.emit,- ),- )- if future:- self._event_futures.append(future)- elif not self.suppress_flow_events:- # Regular failure - emit failed event- future = crewai_event_bus.emit(- self,- MethodExecutionFailedEvent(- type="method_execution_failed",- method_name=method_name,- flow_name=self.name or self.__class__.__name__,- error=e,- ),- )- if future:- self._event_futures.append(future)- raise e-- def _copy_and_serialize_state(self) -> dict[str, Any]:- state_copy = self._copy_state()- if isinstance(state_copy, BaseModel):- try:- return state_copy.model_dump(mode="json")- except Exception:- return state_copy.model_dump()- else:- return state_copy-- async def _execute_listeners(- self,- trigger_method: FlowMethodName,- result: Any,- triggering_event_id: str | None = None,- ) -> None:- """Executes all listeners and routers triggered by a method completion.-- This internal method manages the execution flow by:- 1. First executing all triggered routers sequentially- 2. Then executing all triggered listeners in parallel-- Args:- trigger_method: The name of the method that triggered these listeners.- result: The result from the triggering method, passed to listeners that accept parameters.- triggering_event_id: The event_id of the MethodExecutionFinishedEvent that- triggered these listeners, used for causal chain tracking.-- Note:- - Routers are executed sequentially to maintain flow control- - Each router's result becomes a new trigger_method- - Normal listeners are executed in parallel for efficiency- - Listeners can receive the trigger method's result as a parameter- """- # First, handle routers repeatedly until no router triggers anymore- router_results = []- router_result_to_feedback: dict[- str, Any- ] = {} # Map outcome -> HumanFeedbackResult- current_trigger = trigger_method- current_result = result # Track the result to pass to each router- current_triggering_event_id = triggering_event_id-- while True:- routers_triggered = self._find_triggered_methods(- current_trigger, router_only=True- )- if not routers_triggered:- break-- for router_name in routers_triggered:- # For routers triggered by a router outcome, pass the HumanFeedbackResult- router_input = router_result_to_feedback.get(- str(current_trigger), current_result- )- (- router_result,- current_triggering_event_id,- ) = await self._execute_single_listener(- router_name, router_input, current_triggering_event_id- )- if router_result: # Only add non-None results- router_result_str = (- router_result.value- if isinstance(router_result, enum.Enum)- else str(router_result)- )- router_results.append(FlowMethodName(router_result_str))- # If this was a human_feedback router, map the outcome to the feedback- if self.last_human_feedback is not None:- router_result_to_feedback[router_result_str] = (- self.last_human_feedback- )- current_trigger = (- FlowMethodName(- router_result.value- if isinstance(router_result, enum.Enum)- else str(router_result)- )- if router_result is not None- else FlowMethodName("") # Update for next iteration of router chain- )-- # Now execute normal listeners for all router results and the original trigger- all_triggers = [trigger_method, *router_results]-- for current_trigger in all_triggers:- if current_trigger: # Skip None results- listeners_triggered = self._find_triggered_methods(- current_trigger, router_only=False- )- if listeners_triggered:- # Determine what result to pass to listeners- # For router outcomes, pass the HumanFeedbackResult if available- listener_result = router_result_to_feedback.get(- str(current_trigger), result- )- racing_group = self._get_racing_group_for_listeners(- listeners_triggered- )- if racing_group:- racing_members, _ = racing_group- other_listeners = [- name- for name in listeners_triggered- if name not in racing_members- ]- await self._execute_racing_listeners(- racing_members,- other_listeners,- listener_result,- current_triggering_event_id,- )- else:- tasks = [- self._execute_single_listener(- listener_name,- listener_result,- current_triggering_event_id,- )- for listener_name in listeners_triggered- ]- await asyncio.gather(*tasks)-- if current_trigger in router_results:- for method_name in self._start_methods:- if method_name in self._listeners:- condition_data = self._listeners[method_name]- should_trigger = False- if is_simple_flow_condition(condition_data):- _, trigger_methods = condition_data- should_trigger = current_trigger in trigger_methods- elif isinstance(condition_data, dict):- all_methods = _extract_all_methods(condition_data)- should_trigger = current_trigger in all_methods-- if should_trigger:- if method_name in self._completed_methods:- # Cyclic re-execution: temporarily clear resumption flag so the method actually re-runs- was_resuming = self._is_execution_resuming- self._is_execution_resuming = False- await self._execute_start_method(method_name)- self._is_execution_resuming = was_resuming- else:- await self._execute_start_method(method_name)-- def _evaluate_condition(- self,- condition: FlowMethodName | FlowCondition,- trigger_method: FlowMethodName,- listener_name: FlowMethodName,- ) -> bool:- """Recursively evaluate a condition (simple or nested).-- Args:- condition: Can be a string (method name) or dict (nested condition)- trigger_method: The method that just completed- listener_name: Name of the listener being evaluated-- Returns:- True if the condition is satisfied, False otherwise- """- if is_flow_method_name(condition):- return condition == trigger_method-- if is_flow_condition_dict(condition):- normalized = _normalize_condition(condition)- cond_type = normalized.get("type", OR_CONDITION)- sub_conditions = normalized.get("conditions", [])-- if cond_type == OR_CONDITION:- return any(- self._evaluate_condition(sub_cond, trigger_method, listener_name)- for sub_cond in sub_conditions- )-- if cond_type == AND_CONDITION:- pending_key = PendingListenerKey(f"{listener_name}:{id(condition)}")-- if pending_key not in self._pending_and_listeners:- all_methods = set(_extract_all_methods(condition))- self._pending_and_listeners[pending_key] = all_methods-- if trigger_method in self._pending_and_listeners[pending_key]:- self._pending_and_listeners[pending_key].discard(trigger_method)-- direct_methods_satisfied = not self._pending_and_listeners[pending_key]-- nested_conditions_satisfied = all(- (- self._evaluate_condition(- sub_cond, trigger_method, listener_name- )- if is_flow_condition_dict(sub_cond)- else True- )- for sub_cond in sub_conditions- )-- if direct_methods_satisfied and nested_conditions_satisfied:- self._pending_and_listeners.pop(pending_key, None)- return True-- return False-- return False-- def _find_triggered_methods(- self, trigger_method: FlowMethodName, router_only: bool- ) -> list[FlowMethodName]:- """Finds all methods that should be triggered based on conditions.-- This internal method evaluates both OR and AND conditions to determine- which methods should be executed next in the flow. Supports nested conditions.-- Args:- trigger_method: The name of the method that just completed execution.- router_only: If True, only consider router methods. If False, only consider non-router methods.-- Returns:- Names of methods that should be triggered.-- Note:- - Handles both OR and AND conditions, including nested combinations- - Maintains state for AND conditions using _pending_and_listeners- - Separates router and normal listener evaluation- """- triggered: list[FlowMethodName] = []-- for listener_name, condition_data in self._listeners.items():- is_router = listener_name in self._routers-- if router_only != is_router:- continue-- if not router_only and listener_name in self._start_methods:- continue-- if is_simple_flow_condition(condition_data):- condition_type, methods = condition_data-- if condition_type == OR_CONDITION:- # Only trigger multi-source OR listeners (or_(A, B, C)) once - skip if already fired- # Simple single-method listeners fire every time their trigger occurs- # Routers also fire every time - they're decision points- has_multiple_triggers = len(methods) > 1- should_check_fired = has_multiple_triggers and not is_router-- if (- not should_check_fired- or listener_name not in self._fired_or_listeners- ):- if trigger_method in methods:- triggered.append(listener_name)- # Only track multi-source OR listeners (not single-method or routers)- if should_check_fired:- self._fired_or_listeners.add(listener_name)- elif condition_type == AND_CONDITION:- pending_key = PendingListenerKey(listener_name)- if pending_key not in self._pending_and_listeners:- self._pending_and_listeners[pending_key] = set(methods)- if trigger_method in self._pending_and_listeners[pending_key]:- self._pending_and_listeners[pending_key].discard(trigger_method)-- if not self._pending_and_listeners[pending_key]:- triggered.append(listener_name)- self._pending_and_listeners.pop(pending_key, None)-- elif is_flow_condition_dict(condition_data):- # For complex conditions, check if top-level is OR and track accordingly- top_level_type = condition_data.get("type", OR_CONDITION)- is_or_based = top_level_type == OR_CONDITION-- # Only track multi-source OR conditions (multiple sub-conditions), not routers- sub_conditions = condition_data.get("conditions", [])- has_multiple_triggers = is_or_based and len(sub_conditions) > 1- should_check_fired = has_multiple_triggers and not is_router-- # Skip compound OR-based listeners that have already fired- if should_check_fired and listener_name in self._fired_or_listeners:- continue-- if self._evaluate_condition(- condition_data, trigger_method, listener_name- ):- triggered.append(listener_name)- # Track compound OR-based listeners so they only fire once- if should_check_fired:- self._fired_or_listeners.add(listener_name)-- return triggered-- async def _execute_single_listener(- self,- listener_name: FlowMethodName,- result: Any,- triggering_event_id: str | None = None,- ) -> tuple[Any, str | None]:- """Executes a single listener method with proper event handling.-- This internal method manages the execution of an individual listener,- including parameter inspection, event emission, and error handling.-- Args:- listener_name: The name of the listener method to execute.- result: The result from the triggering method, which may be passed to the listener if it accepts parameters.- triggering_event_id: The event_id of the event that triggered this listener,- used for causal chain tracking.-- Returns:- A tuple of (listener_result, event_id) where listener_result is the return- value of the listener method and event_id is the MethodExecutionFinishedEvent- id, or (None, None) if skipped during resumption.-- Note:- - Inspects method signature to determine if it accepts the trigger result- - Emits events for method execution start and finish- - Handles errors gracefully with detailed logging- - Recursively triggers listeners of this listener- - Supports both parameterized and parameter-less listeners- - Skips execution if method was already completed (e.g., after reload)- - Catches and logs any exceptions during execution, preventing individual listener failures from breaking the entire flow- """- count = self._method_call_counts.get(listener_name, 0) + 1- if count > self.max_method_calls:- raise RecursionError(- f"Method '{listener_name}' has been called {self.max_method_calls} times in "- f"this flow execution, which indicates an infinite loop. "- f"This commonly happens when a @listen label matches the "- f"method's own name."- )- self._method_call_counts[listener_name] = count-- if listener_name in self._completed_methods:- if self._is_execution_resuming:- # During resumption, skip execution but continue listeners- await self._execute_listeners(listener_name, None)-- # For routers, also check if any conditional starts they triggered are completed- # If so, continue their chains- if listener_name in self._routers:- for start_method_name in self._start_methods:- if (- start_method_name in self._listeners- and start_method_name in self._completed_methods- ):- # This conditional start was executed, continue its chain- await self._execute_start_method(start_method_name)- return (None, None)- # For cyclic flows, clear from completed to allow re-execution- self._completed_methods.discard(listener_name)- # Clear ALL fired OR listeners so they can fire again in the new cycle.- # This mirrors what _execute_start_method does for start-method cycles.- # Only discarding the individual listener is insufficient because- # downstream or_() listeners (e.g., method_a listening to- # or_(handler_a, handler_b)) would remain suppressed across iterations.- self._clear_or_listeners()-- try:- method = self._methods[listener_name]-- sig = inspect.signature(method)- params = list(sig.parameters.values())- method_params = [p for p in params if p.name != "self"]-- if triggering_event_id:- with triggered_by_scope(triggering_event_id):- if method_params:- listener_result, finished_event_id = await self._execute_method(- listener_name, method, result- )- else:- listener_result, finished_event_id = await self._execute_method(- listener_name, method- )- else:- if method_params:- listener_result, finished_event_id = await self._execute_method(- listener_name, method, result- )- else:- listener_result, finished_event_id = await self._execute_method(- listener_name, method- )-- await self._execute_listeners(- listener_name, listener_result, finished_event_id- )-- return (listener_result, finished_event_id)-- except Exception as e:- # Don't log HumanFeedbackPending as an error - it's expected control flow- from crewai.flow.async_feedback.types import HumanFeedbackPending-- if not isinstance(e, HumanFeedbackPending):- if not getattr(e, "_flow_listener_logged", False):- logger.error(f"Error executing listener {listener_name}: {e}")- e._flow_listener_logged = True # type: ignore[attr-defined]- raise-- def _resolve_input_provider(self) -> InputProvider:- """Resolve the input provider using the priority chain.-- Resolution order:- 1. ``self.input_provider`` (per-flow override)- 2. ``flow_config.input_provider`` (global default)- 3. ``ConsoleInputProvider()`` (built-in fallback)-- Returns:- An object implementing the ``InputProvider`` protocol.- """- from crewai.flow.async_feedback.providers import ConsoleProvider- from crewai.flow.flow_config import flow_config-- if self.input_provider is not None:- return self.input_provider- if flow_config.input_provider is not None:- return flow_config.input_provider- return ConsoleProvider()-- def _checkpoint_state_for_ask(self) -> None:- """Auto-checkpoint flow state before waiting for user input.-- If persistence is configured, saves the current state so that- ``self.state`` is recoverable even if the process crashes while- waiting for input.-- This is best-effort: if persistence is not configured, this is a no-op.- """- if self.persistence is None:- return- try:- state_data = (- self._state- if isinstance(self._state, dict)- else self._state.model_dump()- )- self.persistence.save_state(- flow_uuid=self.flow_id,- method_name="_ask_checkpoint",- state_data=state_data,- )- except Exception:- logger.debug("Failed to checkpoint state before ask()", exc_info=True)-- def ask(- self,- message: str,- timeout: float | None = None,- metadata: dict[str, Any] | None = None,- ) -> str | None:- """Request input from the user during flow execution.-- Blocks the current thread until the user provides input or the- timeout expires. Works in both sync and async flow methods (the- flow framework runs sync methods in a thread pool via- ``asyncio.to_thread``, so the event loop stays free).-- Timeout ensures flows always terminate. When timeout expires,- ``None`` is returned, enabling the pattern::-- while (msg := self.ask("You: ", timeout=300)) is not None:- process(msg)-- Before waiting for input, the current ``self.state`` is automatically- checkpointed to persistence (if configured) for durability.-- Args:- message: The question or prompt to display to the user.- timeout: Maximum seconds to wait for input. ``None`` means- wait indefinitely. When timeout expires, returns ``None``.- Note: timeout is best-effort for the provider call --- ``ask()`` returns ``None`` promptly, but the underlying- ``request_input()`` may continue running in a background- thread until it completes naturally. Network providers- should implement their own internal timeouts.- metadata: Optional metadata to send to the input provider,- such as user ID, channel, session context. The provider- can use this to route the question to the right recipient.-- Returns:- The user's input as a string, or ``None`` on timeout, disconnect,- or provider error. Empty string ``""`` means the user pressed- Enter without typing (intentional empty input).-- Example:- ```python- class MyFlow(Flow):- @start()- def gather_info(self):- topic = self.ask(- "What topic should we research?",- metadata={"user_id": "u123", "channel": "#research"},- )- if topic is None:- return "No input received"- return topic- ```- """- from concurrent.futures import (- ThreadPoolExecutor,- TimeoutError as FuturesTimeoutError,- )- from datetime import datetime-- from crewai.events.types.flow_events import (- FlowInputReceivedEvent,- FlowInputRequestedEvent,- )- from crewai.flow.flow_context import current_flow_method_name- from crewai.flow.input_provider import InputResponse-- method_name = current_flow_method_name.get("unknown")-- crewai_event_bus.emit(- self,- FlowInputRequestedEvent(- type="flow_input_requested",- flow_name=self.name or self.__class__.__name__,- method_name=method_name,- message=message,- metadata=metadata,- ),- )-- self._checkpoint_state_for_ask()-- provider = self._resolve_input_provider()- raw: str | InputResponse | None = None-- try:- if timeout is not None:- # Manual executor management to avoid shutdown(wait=True)- # deadlock when the provider call outlives the timeout.- executor = ThreadPoolExecutor(max_workers=1)- ctx = contextvars.copy_context()- future = executor.submit(- ctx.run, provider.request_input, message, self, metadata- )- try:- raw = future.result(timeout=timeout)- except FuturesTimeoutError:- future.cancel()- raw = None- finally:- # wait=False so we don't block if the provider is still- # running (e.g. input() stuck waiting for user).- # cancel_futures=True cleans up any queued-but-not-started tasks.- executor.shutdown(wait=False, cancel_futures=True)- else:- raw = provider.request_input(message, self, metadata=metadata)- except KeyboardInterrupt:- raise- except Exception:- logger.debug("Input provider error in ask()", exc_info=True)- raw = None-- response: str | None = None- response_metadata: dict[str, Any] | None = None-- if isinstance(raw, InputResponse):- response = raw.text- response_metadata = raw.metadata- elif isinstance(raw, str):- response = raw- else:- response = None-- self._input_history.append(- {- "message": message,- "response": response,- "method_name": method_name,- "timestamp": datetime.now(),- "metadata": metadata,- "response_metadata": response_metadata,- }- )-- crewai_event_bus.emit(- self,- FlowInputReceivedEvent(- type="flow_input_received",- flow_name=self.name or self.__class__.__name__,- method_name=method_name,- message=message,- response=response,- metadata=metadata,- response_metadata=response_metadata,- ),- )-- return response-- def _request_human_feedback(- self,- message: str,- output: Any,- metadata: dict[str, Any] | None = None,- emit: Sequence[str] | None = None,- ) -> str:- """Request feedback from a human.- Args:- message: The message to display when requesting feedback.- output: The method output to show the human for review.- metadata: Optional metadata for enterprise integrations.- emit: Optional list of possible outcomes for routing.-- Returns:- The human's feedback as a string. Empty string if no feedback provided.- """- from crewai.events.event_listener import event_listener- from crewai.events.types.flow_events import (- HumanFeedbackReceivedEvent,- HumanFeedbackRequestedEvent,- )-- crewai_event_bus.emit(- self,- HumanFeedbackRequestedEvent(- type="human_feedback_requested",- flow_name=self.name or self.__class__.__name__,- method_name="", # Will be set by decorator if needed- output=output,- message=message,- emit=list(emit) if emit else None,- ),- )-- formatter = event_listener.formatter- formatter.pause_live_updates()-- try:- formatter.console.print("\n" + "═" * 50, style="bold cyan")- formatter.console.print(" OUTPUT FOR REVIEW", style="bold cyan")- formatter.console.print("═" * 50 + "\n", style="bold cyan")- formatter.console.print(output)- formatter.console.print("\n" + "═" * 50 + "\n", style="bold cyan")-- formatter.console.print(message, style="yellow")- formatter.console.print(- "(Press Enter to skip, or type your feedback)\n", style="cyan"- )-- feedback = input("Your feedback: ").strip()-- crewai_event_bus.emit(- self,- HumanFeedbackReceivedEvent(- type="human_feedback_received",- flow_name=self.name or self.__class__.__name__,- method_name="", # Will be set by decorator if needed- feedback=feedback,- outcome=None, # Will be determined after collapsing- ),- )-- return feedback- finally:- formatter.resume_live_updates()-- def _collapse_to_outcome(- self,- feedback: str,- outcomes: Sequence[str],- llm: str | BaseLLM,- ) -> str:- """Collapse free-form feedback to a predefined outcome using LLM.-- This method uses the specified LLM to interpret the human's feedback- and map it to one of the predefined outcomes for routing purposes.-- Uses structured outputs (function calling) when supported by the LLM- to guarantee the response is one of the valid outcomes. Falls back- to simple prompting if structured outputs fail.-- Args:- feedback: The raw human feedback text.- outcomes: Sequence of valid outcome strings to choose from.- llm: The LLM model to use. Can be a model string or BaseLLM instance.-- Returns:- One of the outcome strings that best matches the feedback intent.- """- from typing import Literal-- from pydantic import BaseModel, Field-- from crewai.llm import LLM- from crewai.llms.base_llm import BaseLLM as BaseLLMClass- from crewai.utilities.i18n import I18N_DEFAULT-- llm_instance: BaseLLMClass- if isinstance(llm, str):- llm_instance = LLM(model=llm)- elif isinstance(llm, BaseLLMClass):- llm_instance = llm- else:- raise ValueError(f"Invalid llm type: {type(llm)}. Expected str or BaseLLM.")-- outcomes_tuple = tuple(outcomes)-- class FeedbackOutcome(BaseModel):- """The outcome that best matches the human's feedback intent."""-- outcome: Literal[outcomes_tuple] = Field( # type: ignore[valid-type]- description=f"The outcome that best matches the feedback. Must be one of: {', '.join(outcomes)}"- )-- prompt_template = I18N_DEFAULT.slice("human_feedback_collapse")-- prompt = prompt_template.format(- feedback=feedback,- outcomes=", ".join(outcomes),- )-- try:- # NOTE: LLM.call with response_model returns JSON string, not a Pydantic model- response = llm_instance.call(- messages=[{"role": "user", "content": prompt}],- response_model=FeedbackOutcome,- )-- if isinstance(response, str):- import json-- try:- parsed = json.loads(response)- return str(parsed.get("outcome", outcomes[0]))- except json.JSONDecodeError:- response_clean = response.strip()- for outcome in outcomes:- if outcome.lower() == response_clean.lower():- return outcome- return outcomes[0]- elif isinstance(response, FeedbackOutcome):- return str(response.outcome)- elif hasattr(response, "outcome"):- return str(response.outcome)- else:- logger.warning(f"Unexpected response type: {type(response)}")- return outcomes[0]-- except Exception as e:- logger.warning(- f"Structured output failed, falling back to simple prompting: {e}"- )- try:- response = llm_instance.call(- messages=[{"role": "user", "content": prompt}],- )- response_clean = str(response).strip()-- for outcome in outcomes:- if outcome.lower() == response_clean.lower():- return outcome-- # Partial match (longest wins, first on length ties)- response_lower = response_clean.lower()- best_outcome: str | None = None- best_len = -1- for outcome in outcomes:- if outcome.lower() in response_lower and len(outcome) > best_len:- best_outcome = outcome- best_len = len(outcome)- if best_outcome is not None:- return best_outcome-- logger.warning(- f"Could not match LLM response '{response_clean}' to outcomes {list(outcomes)}. "- f"Falling back to first outcome: {outcomes[0]}"- )- return outcomes[0]-- except Exception as fallback_err:- logger.warning(- f"Simple prompting also failed: {fallback_err}. "- f"Falling back to first outcome: {outcomes[0]}"- )- return outcomes[0]-- def _log_flow_event(- self,- message: str,- color: str = "yellow",- level: Literal["info", "warning"] = "info",- ) -> None:- """Centralized logging method for flow events.-- This method provides a consistent interface for logging flow-related events,- combining both console output with colors and proper logging levels.-- Args:- message: The message to log- color: Rich style for console output (default: "yellow")- Examples: "yellow", "red", "bold green", "bold magenta"- level: Log level to use (default: info)- Supported levels: info, warning-- Note:- This method uses the centralized Rich console formatter for output- and the standard logging module for log level support.- """- from crewai.events.event_listener import event_listener-- event_listener.formatter.console.print(message, style=color)- if level == "info":- logger.info(message)- else:- logger.warning(message)-- def plot(self, filename: str = "crewai_flow.html", show: bool = True) -> str:- """Create interactive HTML visualization of Flow structure.-- Args:- filename: Output HTML filename (default: "crewai_flow.html").- show: Whether to open in browser (default: True).-- Returns:- Absolute path to generated HTML file.- """- crewai_event_bus.emit(- self,- FlowPlotEvent(- type="flow_plot",- flow_name=self.name or self.__class__.__name__,- ),- )- structure = build_flow_structure(self)- return render_interactive(structure, filename=filename, show=show)-- @staticmethod- def _show_tracing_disabled_message() -> None:- """Show a message when tracing is disabled."""- if should_suppress_tracing_messages():- return-- console = Console()-- if has_user_declined_tracing():- message = """Info: Tracing is disabled.--To enable tracing, do any one of these:-• Set tracing=True in your Flow code-• Set CREWAI_TRACING_ENABLED=true in your project's .env file-• Run: crewai traces enable"""- else:- message = """Info: Tracing is disabled.--To enable tracing, do any one of these:-• Set tracing=True in your Flow code-• Set CREWAI_TRACING_ENABLED=true in your project's .env file-• Run: crewai traces enable"""+Prefer importing from those modules in new code; this module preserves the+historical ``crewai.flow.flow`` import path.+"""- panel = Panel(- message,- title="Tracing Status",- border_style="blue",- padding=(1, 2),- )- console.print(panel)+from crewai.flow.dsl import and_, listen, or_, router, start+from crewai.flow.runtime import (+ _INITIAL_STATE_CLASS_MARKER,+ Flow,+ FlowMeta,+ FlowState,+ LockedDictProxy,+ LockedListProxy,+ StateProxy,+)+++__all__ = [+ "_INITIAL_STATE_CLASS_MARKER",+ "Flow",+ "FlowMeta",+ "FlowState",+ "LockedDictProxy",+ "LockedListProxy",+ "StateProxy",+ "and_",+ "listen",+ "or_",+ "router",+ "start",+]diff --git a/lib/crewai/src/crewai/flow/flow_definition.py b/lib/crewai/src/crewai/flow/flow_definition.pynew file mode 100644index 000000000..cc0b2d9ff--- /dev/null+++ b/lib/crewai/src/crewai/flow/flow_definition.py@@ -0,0 +1,1036 @@+"""+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.++Example+-------+>>> flow = Flow()+>>> node_levels = calculate_node_levels(flow)+>>> ancestors = build_ancestor_dict(flow)+"""++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.++ Returns:+ List of string literals found in the annotation.+ """++ strings: list[str] = []++ if isinstance(node, ast.Constant) and isinstance(node.value, str):+ strings.append(node.value)++ 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)+ )++ 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++ 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)++ 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)+ )++ return strings+++def _unwrap_function(function: Any) -> Any:+ """Unwrap a function to get the original function with correct globals.++ 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.++ Returns:+ The unwrapped original function.+ """+ if hasattr(function, "__func__"):+ function = function.__func__++ if hasattr(function, "__wrapped__"):+ wrapped = function.__wrapped__+ if hasattr(wrapped, "unwrap"):+ return wrapped.unwrap()+ return wrapped++ return function+++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)++ Args:+ function: The function to analyze.++ 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++ 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++ return_values: set[str] = set()++ 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"+ """+ 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)++ StateAttributeVisitor().visit(class_ast)+ except Exception as e:+ if verbose:+ PRINTER.print(+ f"Could not analyze class context for {function.__name__}: {e}",+ color="yellow",+ )+ 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+ )+ 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+ )+ 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+ )+ else:+ continue++ if path in trigger_methods:+ if (+ listener_name not in levels+ or levels[listener_name] > current_level + 1+ ):+ 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 []+++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.++ 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()++ 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)++ 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] = []++ # 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_pathsdiff --git a/lib/crewai/src/crewai/flow/runtime.py b/lib/crewai/src/crewai/flow/runtime.pynew file mode 100644index 000000000..65efb2900--- /dev/null+++ b/lib/crewai/src/crewai/flow/runtime.py@@ -0,0 +1,3272 @@+"""Flow runtime: the Flow execution engine, its metaclass, and state proxies.++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``.+"""++from __future__ import annotations++import asyncio+from collections.abc import (+ Callable,+ ItemsView,+ Iterable,+ Iterator,+ KeysView,+ Sequence,+ ValuesView,+)+from concurrent.futures import Future, ThreadPoolExecutor+import contextvars+import copy+import enum+import inspect+import logging+import threading+from typing import (+ TYPE_CHECKING,+ Annotated,+ Any,+ ClassVar,+ Generic,+ Literal,+ ParamSpec,+ SupportsIndex,+ TypeVar,+ cast,+ overload,+)+from uuid import uuid4++from opentelemetry import baggage+from opentelemetry.context import attach, detach+from pydantic import (+ BaseModel,+ BeforeValidator,+ ConfigDict,+ Field,+ PlainSerializer,+ PrivateAttr,+ SerializeAsAny,+ ValidationError,+)+from pydantic._internal._model_construction import ModelMetaclass+from rich.console import Console+from rich.panel import Panel++from crewai.events.base_events import reset_emission_counter+from crewai.events.event_bus import crewai_event_bus+from crewai.events.event_context import (+ get_current_parent_id,+ reset_last_event_id,+ restore_event_scope,+ triggered_by_scope,+)+from crewai.events.listeners.tracing.trace_listener import (+ TraceCollectionListener,+)+from crewai.events.listeners.tracing.utils import (+ has_user_declined_tracing,+ set_tracing_enabled,+ should_enable_tracing,+ should_suppress_tracing_messages,+)+from crewai.events.types.flow_events import (+ FlowCreatedEvent,+ FlowFinishedEvent,+ FlowPausedEvent,+ FlowPlotEvent,+ FlowStartedEvent,+ MethodExecutionFailedEvent,+ MethodExecutionFinishedEvent,+ MethodExecutionPausedEvent,+ MethodExecutionStartedEvent,+)+from 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 (+ _extract_all_methods,+ _extract_all_methods_recursive,+ _normalize_condition,+ extract_flow_definition,+ is_flow_condition_dict,+ is_flow_method,+ is_flow_method_name,+ is_simple_flow_condition,+)+from crewai.flow.flow_wrappers import (+ FlowCondition,+ FlowMethod,+ ListenMethod,+ RouterMethod,+ SimpleFlowCondition,+ StartMethod,+)+from crewai.flow.human_feedback import HumanFeedbackResult+from crewai.flow.input_provider import InputProvider+from crewai.flow.persistence.base import FlowPersistence+from crewai.flow.types import (+ FlowExecutionData,+ FlowMethodName,+ InputHistoryEntry,+ PendingListenerKey,+)+from crewai.memory.memory_scope import MemoryScope, MemorySlice, _ensure_memory_kind+from crewai.memory.unified_memory import Memory+from crewai.state.checkpoint_config import (+ CheckpointConfig,+ _coerce_checkpoint,+ apply_checkpoint,+)+++if TYPE_CHECKING:+ from crewai_files import FileInput++ from crewai.context import ExecutionContext+ from crewai.flow.async_feedback.types import PendingFeedbackContext+ from crewai.llms.base_llm import BaseLLM++from crewai.flow.visualization import build_flow_structure, render_interactive+from crewai.types.streaming import CrewStreamingOutput, FlowStreamingOutput+from crewai.utilities.env import get_env_context+from crewai.utilities.streaming import (+ TaskInfo,+ create_async_chunk_generator,+ create_chunk_generator,+ create_streaming_state,+ register_cleanup,+ signal_end,+ signal_error,+)+++logger = logging.getLogger(__name__)+++def _resolve_persistence(value: Any) -> Any:+ if value is None or isinstance(value, FlowPersistence):+ return value+ if isinstance(value, dict):+ from crewai.flow.persistence.base import _persistence_registry++ type_name = value.get("persistence_type", "SQLiteFlowPersistence")+ cls = _persistence_registry.get(type_name)+ if cls is not None:+ return cls.model_validate(value)+ return value+++def _serialize_persistence(value: Any) -> dict[str, Any] | None:+ if value is None:+ return None+ if isinstance(value, FlowPersistence):+ return value.model_dump(mode="json")+ raise TypeError(+ f"Cannot serialize Flow.persistence of type {type(value).__name__}: "+ "expected FlowPersistence or None."+ )+++def _validate_input_provider(value: Any) -> Any:+ if value is None or isinstance(value, InputProvider):+ return value+ from crewai.types.callback import _dotted_path_to_instance++ resolved = _dotted_path_to_instance(value)+ if resolved is None or isinstance(resolved, InputProvider):+ return resolved+ raise ValueError(+ f"Resolved input_provider {resolved!r} does not implement the "+ "InputProvider protocol (missing request_input)."+ )+++def _serialize_input_provider(value: Any) -> str | None:+ if value is None:+ return None+ from crewai.types.callback import _instance_to_dotted_path++ return _instance_to_dotted_path(value)+++_INITIAL_STATE_CLASS_MARKER = "__crewai_pydantic_class_schema__"+++def _serialize_initial_state(value: Any) -> Any:+ """Make ``initial_state`` safe for JSON checkpoint serialization.++ ``BaseModel`` class refs are emitted as their JSON schema under a sentinel+ marker key so deserialization can round-trip them back to a class.+ ``BaseModel`` instances are dumped to JSON (round-trip as plain dicts,+ which ``_create_initial_state`` accepts). Bare ``type`` values that are+ not ``BaseModel`` subclasses (e.g. ``dict``) are dropped since they+ can't be represented in JSON.+ """+ if isinstance(value, type):+ if issubclass(value, BaseModel):+ return {_INITIAL_STATE_CLASS_MARKER: value.model_json_schema()}+ return None+ if isinstance(value, BaseModel):+ return value.model_dump(mode="json")+ return value+++def _deserialize_initial_state(value: Any) -> Any:+ """Rehydrate a class ref serialized by :func:`_serialize_initial_state`."""+ if isinstance(value, dict) and _INITIAL_STATE_CLASS_MARKER in value:+ from crewai.utilities.pydantic_schema_utils import create_model_from_schema++ return create_model_from_schema(value[_INITIAL_STATE_CLASS_MARKER])+ return value+++class FlowState(BaseModel):+ """Base model for all flow states, ensuring each state has a unique ID."""++ id: str = Field(+ default_factory=lambda: str(uuid4()),+ description="Unique identifier for the flow state",+ )+++T = TypeVar("T", bound=dict[str, Any] | BaseModel)+P = ParamSpec("P")+R = TypeVar("R")+F = TypeVar("F", bound=Callable[..., Any])+++class LockedListProxy(list, Generic[T]): # type: ignore[type-arg]+ """Thread-safe proxy for list operations.++ Subclasses ``list`` so that ``isinstance(proxy, list)`` returns True,+ which is required by libraries like LanceDB and Pydantic that do strict+ type checks. All mutations go through the lock; reads delegate to the+ underlying list.+ """++ def __init__(self, lst: list[T], lock: threading.Lock) -> None:+ super().__init__() # empty builtin list; all access goes through self._list+ self._list = lst+ self._lock = lock++ def append(self, item: T) -> None:+ with self._lock:+ self._list.append(item)++ def extend(self, items: Iterable[T]) -> None:+ with self._lock:+ self._list.extend(items)++ def insert(self, index: SupportsIndex, item: T) -> None:+ with self._lock:+ self._list.insert(index, item)++ def remove(self, item: T) -> None:+ with self._lock:+ self._list.remove(item)++ def pop(self, index: SupportsIndex = -1) -> T:+ with self._lock:+ return self._list.pop(index)++ def clear(self) -> None:+ with self._lock:+ self._list.clear()++ @overload+ def __setitem__(self, index: SupportsIndex, value: T) -> None: ...+ @overload+ def __setitem__(self, index: slice, value: Iterable[T]) -> None: ...+ def __setitem__(self, index: Any, value: Any) -> None:+ with self._lock:+ self._list[index] = value++ def __delitem__(self, index: SupportsIndex | slice) -> None:+ with self._lock:+ del self._list[index]++ @overload+ def __getitem__(self, index: SupportsIndex) -> T: ...+ @overload+ def __getitem__(self, index: slice) -> list[T]: ...+ def __getitem__(self, index: Any) -> Any:+ return self._list[index]++ def __len__(self) -> int:+ return len(self._list)++ def __iter__(self) -> Iterator[T]:+ return iter(self._list)++ def __contains__(self, item: object) -> bool:+ return item in self._list++ def __repr__(self) -> str:+ return repr(self._list)++ def __bool__(self) -> bool:+ return bool(self._list)++ def index(+ self, value: T, start: SupportsIndex = 0, stop: SupportsIndex | None = None+ ) -> int:+ if stop is None:+ return self._list.index(value, start)+ return self._list.index(value, start, stop)++ def count(self, value: T) -> int:+ return self._list.count(value)++ def sort(self, *, key: Any = None, reverse: bool = False) -> None:+ with self._lock:+ self._list.sort(key=key, reverse=reverse)++ def reverse(self) -> None:+ with self._lock:+ self._list.reverse()++ def copy(self) -> list[T]:+ return self._list.copy()++ def __add__(self, other: list[T]) -> list[T]: # type: ignore[override]+ return self._list + other++ def __radd__(self, other: list[T]) -> list[T]:+ return other + self._list++ def __iadd__(self, other: Iterable[T]) -> LockedListProxy[T]: # type: ignore[override]+ with self._lock:+ self._list += list(other)+ return self++ def __mul__(self, n: SupportsIndex) -> list[T]:+ return self._list * n++ def __rmul__(self, n: SupportsIndex) -> list[T]:+ return self._list * n++ def __imul__(self, n: SupportsIndex) -> LockedListProxy[T]:+ with self._lock:+ self._list *= n+ return self++ def __reversed__(self) -> Iterator[T]:+ return reversed(self._list)++ def __eq__(self, other: object) -> bool:+ """Compare based on the underlying list contents."""+ if isinstance(other, LockedListProxy):+ # Avoid deadlocks by acquiring locks in a consistent order.+ first, second = (self, other) if id(self) <= id(other) else (other, self)+ with first._lock:+ with second._lock:+ return first._list == second._list+ with self._lock:+ return self._list == other++ def __ne__(self, other: object) -> bool:+ return not self.__eq__(other)+++class LockedDictProxy(dict, Generic[T]): # type: ignore[type-arg]+ """Thread-safe proxy for dict operations.++ Subclasses ``dict`` so that ``isinstance(proxy, dict)`` returns True,+ which is required by libraries like Pydantic that do strict type checks.+ All mutations go through the lock; reads delegate to the underlying dict.+ """++ def __init__(self, d: dict[str, T], lock: threading.Lock) -> None:+ super().__init__() # empty builtin dict; all access goes through self._dict+ self._dict = d+ self._lock = lock++ def __setitem__(self, key: str, value: T) -> None:+ with self._lock:+ self._dict[key] = value++ def __delitem__(self, key: str) -> None:+ with self._lock:+ del self._dict[key]++ def pop(self, key: str, *default: T) -> T: # type: ignore[override]+ with self._lock:+ return self._dict.pop(key, *default)++ def update(self, other: dict[str, T]) -> None: # type: ignore[override]+ with self._lock:+ self._dict.update(other)++ def clear(self) -> None:+ with self._lock:+ self._dict.clear()++ def setdefault(self, key: str, default: T) -> T: # type: ignore[override]+ with self._lock:+ return self._dict.setdefault(key, default)++ def __getitem__(self, key: str) -> T:+ return self._dict[key]++ def __len__(self) -> int:+ return len(self._dict)++ def __iter__(self) -> Iterator[str]:+ return iter(self._dict)++ def __contains__(self, key: object) -> bool:+ return key in self._dict++ def keys(self) -> KeysView[str]: # type: ignore[override]+ return self._dict.keys()++ def values(self) -> ValuesView[T]: # type: ignore[override]+ return self._dict.values()++ def items(self) -> ItemsView[str, T]: # type: ignore[override]+ return self._dict.items()++ def get(self, key: str, default: T | None = None) -> T | None: # type: ignore[override]+ return self._dict.get(key, default)++ def __repr__(self) -> str:+ return repr(self._dict)++ def __bool__(self) -> bool:+ return bool(self._dict)++ def copy(self) -> dict[str, T]:+ return self._dict.copy()++ def __or__(self, other: dict[str, T]) -> dict[str, T]: # type: ignore[override]+ return self._dict | other++ def __ror__(self, other: dict[str, T]) -> dict[str, T]: # type: ignore[override]+ return other | self._dict++ def __ior__(self, other: dict[str, T]) -> LockedDictProxy[T]: # type: ignore[override]+ with self._lock:+ self._dict |= other+ return self++ def __reversed__(self) -> Iterator[str]:+ return reversed(self._dict)++ def __eq__(self, other: object) -> bool:+ """Compare based on the underlying dict contents."""+ if isinstance(other, LockedDictProxy):+ # Avoid deadlocks by acquiring locks in a consistent order.+ first, second = (self, other) if id(self) <= id(other) else (other, self)+ with first._lock:+ with second._lock:+ return first._dict == second._dict+ with self._lock:+ return self._dict == other++ def __ne__(self, other: object) -> bool:+ return not self.__eq__(other)+++class StateProxy(Generic[T]):+ """Proxy that provides thread-safe access to flow state.++ Wraps state objects (dict or BaseModel) and uses a lock for all write+ operations to prevent race conditions when parallel listeners modify state.+ """++ __slots__ = ("_proxy_lock", "_proxy_state")++ def __init__(self, state: T, lock: threading.Lock) -> None:+ object.__setattr__(self, "_proxy_state", state)+ object.__setattr__(self, "_proxy_lock", lock)++ def __getattr__(self, name: str) -> Any:+ value = getattr(object.__getattribute__(self, "_proxy_state"), name)+ lock = object.__getattribute__(self, "_proxy_lock")+ if isinstance(value, list):+ return LockedListProxy(value, lock)+ if isinstance(value, dict):+ return LockedDictProxy(value, lock)+ return value++ def __setattr__(self, name: str, value: Any) -> None:+ if name in ("_proxy_state", "_proxy_lock"):+ object.__setattr__(self, name, value)+ else:+ if isinstance(value, LockedListProxy):+ value = value._list+ elif isinstance(value, LockedDictProxy):+ value = value._dict+ with object.__getattribute__(self, "_proxy_lock"):+ setattr(object.__getattribute__(self, "_proxy_state"), name, value)++ def __getitem__(self, key: str) -> Any:+ return object.__getattribute__(self, "_proxy_state")[key]++ def __setitem__(self, key: str, value: Any) -> None:+ with object.__getattribute__(self, "_proxy_lock"):+ object.__getattribute__(self, "_proxy_state")[key] = value++ def __delitem__(self, key: str) -> None:+ with object.__getattribute__(self, "_proxy_lock"):+ del object.__getattribute__(self, "_proxy_state")[key]++ def __contains__(self, key: str) -> bool:+ return key in object.__getattribute__(self, "_proxy_state")++ def __repr__(self) -> str:+ return repr(object.__getattribute__(self, "_proxy_state"))++ def _unwrap(self) -> T:+ """Return the underlying state object."""+ return cast(T, object.__getattribute__(self, "_proxy_state"))++ def model_dump(self, *args: Any, **kwargs: Any) -> dict[str, Any]:+ """Return state as a dictionary.++ Works for both dict and BaseModel underlying states.+ """+ state = object.__getattribute__(self, "_proxy_state")+ if isinstance(state, dict):+ return state+ result: dict[str, Any] = state.model_dump(*args, **kwargs)+ return result+++class FlowMeta(ModelMetaclass):+ def __new__(+ mcs,+ name: str,+ bases: tuple[type, ...],+ namespace: dict[str, Any],+ **kwargs: Any,+ ) -> type:+ parent_fields: set[str] = set()+ for base in bases:+ if hasattr(base, "model_fields"):+ parent_fields.update(base.model_fields)++ annotations = namespace.get("__annotations__", {})+ _skip_types = (classmethod, staticmethod, property)++ for base in bases:+ if isinstance(base, ModelMetaclass):+ continue+ for attr_name in getattr(base, "__annotations__", {}):+ if attr_name not in annotations and attr_name not in namespace:+ annotations[attr_name] = ClassVar++ for attr_name, attr_value in namespace.items():+ if isinstance(attr_value, property) and attr_name not in annotations:+ for base in bases:+ base_ann = getattr(base, "__annotations__", {})+ if attr_name in base_ann:+ annotations[attr_name] = ClassVar++ for attr_name, attr_value in list(namespace.items()):+ if attr_name in annotations or attr_name.startswith("_"):+ continue+ if attr_name in parent_fields:+ annotations[attr_name] = Any+ if isinstance(attr_value, BaseModel):+ namespace[attr_name] = Field(+ default_factory=lambda v=attr_value: v, exclude=True+ )+ continue+ if callable(attr_value) or isinstance(+ attr_value, (*_skip_types, FlowMethod)+ ):+ continue+ annotations[attr_name] = ClassVar[type(attr_value)]+ namespace["__annotations__"] = annotations++ cls = super().__new__(mcs, name, bases, namespace)++ start_methods, listeners, routers, router_paths = extract_flow_definition(+ namespace+ )++ 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]++ return cls+++class Flow(BaseModel, Generic[T], metaclass=FlowMeta):+ """Base class for all flows.++ type parameter T must be either dict[str, Any] or a subclass of BaseModel."""++ model_config = ConfigDict(+ arbitrary_types_allowed=True,+ ignored_types=(StartMethod, ListenMethod, RouterMethod),+ revalidate_instances="never",+ )+ __hash__ = object.__hash__++ _start_methods: ClassVar[list[FlowMethodName]] = []+ _listeners: ClassVar[dict[FlowMethodName, SimpleFlowCondition | FlowCondition]] = {}+ _routers: ClassVar[set[FlowMethodName]] = set()+ _router_paths: ClassVar[dict[FlowMethodName, list[FlowMethodName]]] = {}++ entity_type: Literal["flow"] = "flow"++ initial_state: Annotated[ # type: ignore[type-arg]+ type[BaseModel] | type[dict] | dict[str, Any] | BaseModel | None,+ BeforeValidator(_deserialize_initial_state),+ PlainSerializer(_serialize_initial_state, return_type=Any, when_used="json"),+ ] = Field(default=None)+ name: str | None = Field(default=None)+ tracing: bool | None = Field(default=None)+ stream: bool = Field(default=False)+ memory: Annotated[+ Annotated[+ Memory | MemoryScope | MemorySlice, Field(discriminator="memory_kind")+ ]+ | None,+ BeforeValidator(_ensure_memory_kind),+ ] = Field(default=None)+ input_provider: Annotated[+ InputProvider | None,+ BeforeValidator(_validate_input_provider),+ PlainSerializer(+ _serialize_input_provider, return_type=str | None, when_used="json"+ ),+ ] = Field(default=None)+ suppress_flow_events: bool = Field(default=False)+ human_feedback_history: list[HumanFeedbackResult] = Field(default_factory=list)+ last_human_feedback: HumanFeedbackResult | None = Field(default=None)++ persistence: Annotated[+ SerializeAsAny[FlowPersistence] | None,+ BeforeValidator(lambda v, _: _resolve_persistence(v)),+ PlainSerializer(+ _serialize_persistence, return_type=dict | None, when_used="json"+ ),+ ] = Field(default=None)+ max_method_calls: int = Field(default=100)++ execution_context: ExecutionContext | None = Field(default=None)+ checkpoint: Annotated[+ CheckpointConfig | bool | None,+ BeforeValidator(_coerce_checkpoint),+ ] = Field(default=None)++ @classmethod+ def from_checkpoint(cls, config: CheckpointConfig) -> Flow: # type: ignore[type-arg]+ """Restore a Flow from a checkpoint.++ Args:+ config: Checkpoint configuration with ``restore_from`` set to+ the path of the checkpoint to load.++ Returns:+ A Flow instance ready to resume.+ """+ from crewai.context import apply_execution_context+ from crewai.events.event_bus import crewai_event_bus+ from crewai.state.runtime import RuntimeState++ state = RuntimeState.from_checkpoint(config, context={"from_checkpoint": True})+ crewai_event_bus.set_runtime_state(state)+ for entity in state.root:+ if not isinstance(entity, Flow):+ continue+ if entity.execution_context is not None:+ apply_execution_context(entity.execution_context)+ if isinstance(entity, cls):+ entity._restore_from_checkpoint()+ return entity+ instance = cls()+ instance.checkpoint_completed_methods = entity.checkpoint_completed_methods+ instance.checkpoint_method_outputs = entity.checkpoint_method_outputs+ instance.checkpoint_method_counts = entity.checkpoint_method_counts+ instance.checkpoint_state = entity.checkpoint_state+ instance._restore_from_checkpoint()+ return instance+ raise ValueError(f"No Flow found in checkpoint: {config.restore_from}")++ @classmethod+ def fork(+ cls,+ config: CheckpointConfig,+ branch: str | None = None,+ ) -> Flow: # type: ignore[type-arg]+ """Fork a Flow from a checkpoint, creating a new execution branch.++ Args:+ config: Checkpoint configuration with ``restore_from`` set.+ branch: Branch label for the fork. Auto-generated if not provided.++ Returns:+ A Flow instance on the new branch. Call kickoff() to run.+ """+ flow = cls.from_checkpoint(config)+ state = crewai_event_bus.runtime_state+ if state is None:+ raise RuntimeError(+ "Cannot fork: no runtime state on the event bus. "+ "Ensure from_checkpoint() succeeded before calling fork()."+ )+ state.fork(branch)+ new_id = str(uuid4())+ if isinstance(flow._state, dict):+ flow._state["id"] = new_id+ else:+ object.__setattr__(flow._state, "id", new_id)+ return flow++ checkpoint_completed_methods: set[str] | None = Field(default=None)+ checkpoint_method_outputs: list[Any] | None = Field(default=None)+ checkpoint_method_counts: dict[str, int] | None = Field(default=None)+ checkpoint_state: dict[str, Any] | None = Field(default=None)++ def _restore_from_checkpoint(self) -> None:+ """Restore private execution state from checkpoint fields."""+ if self.checkpoint_completed_methods is not None:+ self._completed_methods = {+ FlowMethodName(m) for m in self.checkpoint_completed_methods+ }+ if self.checkpoint_method_outputs is not None:+ self._method_outputs = list(self.checkpoint_method_outputs)+ if self.checkpoint_method_counts is not None:+ self._method_execution_counts = {+ FlowMethodName(k): v for k, v in self.checkpoint_method_counts.items()+ }+ if self.checkpoint_state is not None:+ self._restore_state(self.checkpoint_state)+ if (+ isinstance(self.memory, MemoryScope | MemorySlice)+ and self.memory._memory is None+ ):+ self.memory.bind(Memory())+ restore_event_scope(())+ reset_last_event_id()++ _methods: dict[FlowMethodName, FlowMethod[Any, Any]] = PrivateAttr(+ default_factory=dict+ )+ _method_execution_counts: dict[FlowMethodName, int] = PrivateAttr(+ default_factory=dict+ )+ _pending_and_listeners: dict[PendingListenerKey, set[FlowMethodName]] = PrivateAttr(+ default_factory=dict+ )+ _fired_or_listeners: set[FlowMethodName] = PrivateAttr(default_factory=set)+ _method_outputs: list[Any] = PrivateAttr(default_factory=list)+ _state_lock: threading.Lock = PrivateAttr(default_factory=threading.Lock)+ _or_listeners_lock: threading.Lock = PrivateAttr(default_factory=threading.Lock)+ _completed_methods: set[FlowMethodName] = PrivateAttr(default_factory=set)+ _method_call_counts: dict[FlowMethodName, int] = PrivateAttr(default_factory=dict)+ _is_execution_resuming: bool = PrivateAttr(default=False)+ _event_futures: list[Future[None]] = PrivateAttr(default_factory=list)+ _pending_feedback_context: PendingFeedbackContext | None = PrivateAttr(default=None)+ _human_feedback_method_outputs: dict[str, Any] = PrivateAttr(default_factory=dict)+ _input_history: list[InputHistoryEntry] = PrivateAttr(default_factory=list)+ _state: Any = PrivateAttr(default=None)++ def __class_getitem__(cls: type[Flow[T]], item: type[T]) -> type[Flow[T]]: # type: ignore[override]+ class _FlowGeneric(cls): # type: ignore[valid-type,misc]+ pass++ _FlowGeneric.__name__ = f"{cls.__name__}[{item.__name__}]"+ _FlowGeneric._initial_state_t = item+ return _FlowGeneric++ def __setattr__(self, name: str, value: Any) -> None:+ """Allow arbitrary attribute assignment for backward compat with plain class."""+ if name in self.model_fields or name in self.__private_attributes__:+ super().__setattr__(name, value)+ else:+ object.__setattr__(self, name, value)++ def model_post_init(self, __context: Any) -> None:+ self._flow_post_init()++ def _flow_post_init(self) -> None:+ """Heavy initialization: state creation, events, memory, method registration."""+ if getattr(self, "_flow_post_init_done", False):+ return+ object.__setattr__(self, "_flow_post_init_done", True)++ if self._state is None:+ self._state = self._create_initial_state()++ tracing_enabled = should_enable_tracing(override=self.tracing)+ set_tracing_enabled(tracing_enabled)++ trace_listener = TraceCollectionListener()+ trace_listener.setup_listeners(crewai_event_bus)++ if not self.suppress_flow_events:+ crewai_event_bus.emit(+ self,+ FlowCreatedEvent(+ type="flow_created",+ flow_name=self.name or self.__class__.__name__,+ ),+ )++ # Auto-create memory if not provided at class or instance level.+ # Internal flows (RecallFlow, EncodingFlow) set _skip_auto_memory+ # to avoid creating a wasteful standalone Memory instance.+ if self.memory is None and not getattr(self, "_skip_auto_memory", False):+ from crewai.memory.utils import sanitize_scope_name++ flow_name = sanitize_scope_name(self.name or self.__class__.__name__)+ self.memory = Memory(root_scope=f"/flow/{flow_name}")++ for method_name in dir(self):+ if not method_name.startswith("_"):+ method = getattr(self, method_name)+ if is_flow_method(method):+ if not hasattr(method, "__self__"):+ method = method.__get__(self, self.__class__)+ self._methods[method.__name__] = method++ def recall(self, query: str, **kwargs: Any) -> Any:+ """Recall relevant memories. Delegates to this flow's memory.++ Args:+ query: Natural language query.+ **kwargs: Passed to memory.recall (e.g. scope, categories, limit, depth).++ Returns:+ Result of memory.recall(query, **kwargs).++ Raises:+ ValueError: If no memory is configured for this flow.+ """+ if self.memory is None:+ raise ValueError("No memory configured for this flow")+ return self.memory.recall(query, **kwargs)++ def remember(self, content: str | list[str], **kwargs: Any) -> Any:+ """Store one or more items in memory.++ Pass a single string for synchronous save (returns the MemoryRecord).+ Pass a list of strings for non-blocking batch save (returns immediately).++ Args:+ content: Text or list of texts to remember.+ **kwargs: Passed to memory.remember / remember_many+ (e.g. scope, categories, metadata, importance).++ Returns:+ MemoryRecord for single item, empty list for batch (background save).++ Raises:+ ValueError: If no memory is configured for this flow.+ TypeError: If batch remember is attempted on a MemoryScope or MemorySlice.+ """+ if self.memory is None:+ raise ValueError("No memory configured for this flow")+ if isinstance(content, list):+ if not isinstance(self.memory, Memory):+ raise TypeError(+ "Batch remember requires a Memory instance, "+ f"got {type(self.memory).__name__}"+ )+ return self.memory.remember_many(content, **kwargs)+ return self.memory.remember(content, **kwargs)++ def extract_memories(self, content: str) -> list[str]:+ """Extract discrete memories from content. Delegates to this flow's memory.++ Args:+ content: Raw text (e.g. task + result dump).++ Returns:+ List of short, self-contained memory statements.++ Raises:+ ValueError: If no memory is configured for this flow.+ """+ if self.memory is None:+ raise ValueError("No memory configured for this flow")+ result: list[str] = self.memory.extract_memories(content)+ return result++ def _mark_or_listener_fired(self, listener_name: FlowMethodName) -> bool:+ """Mark an OR listener as fired atomically.++ Args:+ listener_name: The name of the OR listener to mark.++ Returns:+ True if this call was the first to fire the listener.+ False if the listener was already fired.+ """+ with self._or_listeners_lock:+ if listener_name in self._fired_or_listeners:+ return False+ self._fired_or_listeners.add(listener_name)+ return True++ def _clear_or_listeners(self) -> None:+ """Clear fired OR listeners for cyclic flows."""+ with self._or_listeners_lock:+ self._fired_or_listeners.clear()++ def _discard_or_listener(self, listener_name: FlowMethodName) -> None:+ """Discard a single OR listener from the fired set."""+ with self._or_listeners_lock:+ self._fired_or_listeners.discard(listener_name)++ def _build_racing_groups(self) -> dict[frozenset[FlowMethodName], FlowMethodName]:+ """Identify groups of methods that race for the same OR listener.++ Analyzes the flow graph to find listeners with OR conditions that have+ multiple trigger methods. These trigger methods form a "racing group"+ where only the first to complete should trigger the OR listener.++ Only methods that are EXCLUSIVELY sources for the OR listener are included+ in the racing group. Methods that are also triggers for other listeners+ (e.g., AND conditions) are not cancelled when another racing source wins.++ Returns:+ Dictionary mapping frozensets of racing method names to their+ shared OR listener name.++ Example:+ If we have `@listen(or_(method_a, method_b))` on `handler`,+ and method_a/method_b aren't used elsewhere,+ this returns: {frozenset({'method_a', 'method_b'}): 'handler'}+ """+ racing_groups: dict[frozenset[FlowMethodName], FlowMethodName] = {}++ method_to_listeners: dict[FlowMethodName, set[FlowMethodName]] = {}+ for listener_name, condition_data in self._listeners.items():+ if is_simple_flow_condition(condition_data):+ _, methods = condition_data+ for m in methods:+ method_to_listeners.setdefault(m, set()).add(listener_name)+ elif is_flow_condition_dict(condition_data):+ all_methods = _extract_all_methods_recursive(condition_data)+ for m in all_methods:+ method_name = FlowMethodName(m) if isinstance(m, str) else m+ method_to_listeners.setdefault(method_name, set()).add(+ listener_name+ )++ for listener_name, condition_data in self._listeners.items():+ if listener_name in self._routers:+ continue++ trigger_methods: set[FlowMethodName] = set()++ if is_simple_flow_condition(condition_data):+ condition_type, methods = condition_data+ if condition_type == OR_CONDITION and len(methods) > 1:+ trigger_methods = set(methods)++ elif is_flow_condition_dict(condition_data):+ top_level_type = condition_data.get("type", OR_CONDITION)+ if top_level_type == OR_CONDITION:+ all_methods = _extract_all_methods_recursive(condition_data)+ if len(all_methods) > 1:+ trigger_methods = set(+ FlowMethodName(m) if isinstance(m, str) else m+ for m in all_methods+ )++ if trigger_methods:+ exclusive_methods = {+ m+ for m in trigger_methods+ if method_to_listeners.get(m, set()) == {listener_name}+ }+ if len(exclusive_methods) > 1:+ racing_groups[frozenset(exclusive_methods)] = listener_name++ return racing_groups++ def _get_racing_group_for_listeners(+ self,+ listener_names: list[FlowMethodName],+ ) -> tuple[frozenset[FlowMethodName], FlowMethodName] | None:+ """Check if the given listeners form a racing group.++ Args:+ listener_names: List of listener method names being executed.++ Returns:+ Tuple of (racing_members, or_listener_name) if these listeners race,+ None otherwise.+ """+ if not hasattr(self, "_racing_groups_cache"):+ self._racing_groups_cache = self._build_racing_groups()++ listener_set = set(listener_names)++ for racing_members, or_listener in self._racing_groups_cache.items():+ if racing_members & listener_set:+ racing_subset = racing_members & listener_set+ if len(racing_subset) > 1:+ return (frozenset(racing_subset), or_listener)++ return None++ async def _execute_racing_listeners(+ self,+ racing_listeners: frozenset[FlowMethodName],+ other_listeners: list[FlowMethodName],+ result: Any,+ triggering_event_id: str | None = None,+ ) -> None:+ """Execute racing listeners with first-wins semantics.++ Racing listeners are executed in parallel, but once the first one+ completes, the others are cancelled. Non-racing listeners in the+ same batch are executed normally in parallel.++ Args:+ racing_listeners: Set of listener names that race for an OR condition.+ other_listeners: Other listeners to execute in parallel (not racing).+ result: The result from the triggering method.+ triggering_event_id: The event_id of the event that triggered these listeners.+ """+ racing_tasks = [+ asyncio.create_task(+ self._execute_single_listener(name, result, triggering_event_id),+ name=str(name),+ )+ for name in racing_listeners+ ]++ other_tasks = [+ asyncio.create_task(+ self._execute_single_listener(name, result, triggering_event_id),+ name=str(name),+ )+ for name in other_listeners+ ]++ if racing_tasks:+ for coro in asyncio.as_completed(racing_tasks):+ try:+ await coro+ except Exception as e:+ logger.debug(f"Racing listener failed: {e}")+ continue+ break++ for task in racing_tasks:+ if not task.done():+ task.cancel()++ if other_tasks:+ await asyncio.gather(*other_tasks, return_exceptions=True)++ @classmethod+ def from_pending(+ cls,+ flow_id: str,+ persistence: FlowPersistence | None = None,+ **kwargs: Any,+ ) -> Flow[Any]:+ """Create a Flow instance from a pending feedback state.++ This classmethod is used to restore a flow that was paused waiting+ for async human feedback. It loads the persisted state and pending+ feedback context, then returns a flow instance ready to resume.++ Args:+ flow_id: The unique identifier of the paused flow (from state.id)+ persistence: The persistence backend where the state was saved.+ If not provided, defaults to SQLiteFlowPersistence().+ **kwargs: Additional keyword arguments passed to the Flow constructor++ Returns:+ A new Flow instance with restored state, ready to call resume()++ Raises:+ ValueError: If no pending feedback exists for the given flow_id++ Example:+ ```python+ # Simple usage with default persistence:+ flow = MyFlow.from_pending("abc-123")+ result = flow.resume("looks good!")++ # Or with custom persistence:+ persistence = SQLiteFlowPersistence("custom.db")+ flow = MyFlow.from_pending("abc-123", persistence)+ result = flow.resume("looks good!")+ ```+ """+ if persistence is None:+ from crewai.flow.persistence import SQLiteFlowPersistence++ persistence = SQLiteFlowPersistence()++ loaded = persistence.load_pending_feedback(flow_id)+ if loaded is None:+ raise ValueError(f"No pending feedback found for flow_id: {flow_id}")++ state_data, pending_context = loaded++ instance = cls(persistence=persistence, **kwargs)+ instance._initialize_state(state_data)+ instance._pending_feedback_context = pending_context+ instance._is_execution_resuming = True++ return instance++ @property+ def pending_feedback(self) -> PendingFeedbackContext | None:+ """Get the pending feedback context if this flow is waiting for feedback.++ Returns:+ The PendingFeedbackContext if the flow is paused waiting for feedback,+ None otherwise.++ Example:+ ```python+ flow = MyFlow.from_pending("abc-123", persistence)+ if flow.pending_feedback:+ print(f"Waiting for feedback on: {flow.pending_feedback.method_name}")+ ```+ """+ return self._pending_feedback_context++ def resume(self, feedback: str = "") -> Any:+ """Resume flow execution, optionally with human feedback.++ This method continues flow execution after a flow was paused for+ async human feedback. It processes the feedback (including LLM-based+ outcome collapsing if emit was specified), stores the result, and+ triggers downstream listeners.++ Note:+ If called from within an async context (running event loop),+ use `await flow.resume_async(feedback)` instead.++ Args:+ feedback: The human's feedback as a string. If empty, uses+ default_outcome or the first emit option.++ Returns:+ The final output from the flow execution, or HumanFeedbackPending+ if another feedback point is reached.++ Raises:+ ValueError: If no pending feedback context exists (flow wasn't paused)+ RuntimeError: If called from within a running event loop (use resume_async instead)++ Example:+ ```python+ # In a sync webhook handler:+ def handle_feedback(flow_id: str, feedback: str):+ flow = MyFlow.from_pending(flow_id)+ result = flow.resume(feedback)+ return result+++ # In an async handler, use resume_async instead:+ async def handle_feedback_async(flow_id: str, feedback: str):+ flow = MyFlow.from_pending(flow_id)+ result = await flow.resume_async(feedback)+ return result+ ```+ """+ try:+ loop = asyncio.get_running_loop()+ except RuntimeError:+ loop = None++ if loop is not None:+ raise RuntimeError(+ "resume() cannot be called from within an async context. "+ "Use 'await flow.resume_async(feedback)' instead."+ )++ return asyncio.run(self.resume_async(feedback))++ async def resume_async(self, feedback: str = "") -> Any:+ """Async version of resume.++ Resume flow execution, optionally with human feedback asynchronously.++ Args:+ feedback: The human's feedback as a string. If empty, uses+ default_outcome or the first emit option.++ Returns:+ The final output from the flow execution, or HumanFeedbackPending+ if another feedback point is reached.++ Raises:+ ValueError: If no pending feedback context exists+ """+ from datetime import datetime++ from crewai.flow.human_feedback import HumanFeedbackResult++ if self._pending_feedback_context is None:+ raise ValueError(+ "No pending feedback context. Use from_pending() to restore a paused flow."+ )++ if get_current_parent_id() is None:+ reset_emission_counter()+ reset_last_event_id()++ if not self.suppress_flow_events:+ future = crewai_event_bus.emit(+ self,+ FlowStartedEvent(+ type="flow_started",+ flow_name=self.name or self.__class__.__name__,+ inputs=None,+ ),+ )+ if future and isinstance(future, Future):+ try:+ await asyncio.wrap_future(future)+ except Exception:+ logger.warning("FlowStartedEvent handler failed", exc_info=True)++ get_env_context()++ context = self._pending_feedback_context+ emit = context.emit+ default_outcome = context.default_outcome++ # Try to get the live LLM from the re-imported decorator first.+ # This preserves the fully-configured object (credentials, safety_settings, etc.)+ # for same-process resume. For cross-process resume, fall back to the+ # serialized context.llm which is now a dict with full config (or a legacy string).+ from crewai.flow.human_feedback import _deserialize_llm_from_context++ llm = None+ method = self._methods.get(FlowMethodName(context.method_name))+ if method is not None:+ live_llm = getattr(method, "_hf_llm", None)+ if live_llm is not None:+ from crewai.llms.base_llm import BaseLLM as BaseLLMClass++ if isinstance(live_llm, BaseLLMClass):+ llm = live_llm++ if llm is None:+ llm = _deserialize_llm_from_context(context.llm)++ collapsed_outcome: str | None = None++ if not feedback.strip():+ if default_outcome:+ collapsed_outcome = default_outcome+ elif emit:+ collapsed_outcome = emit[0]+ elif emit:+ if llm is not None:+ collapsed_outcome = self._collapse_to_outcome(+ feedback=feedback,+ outcomes=emit,+ llm=llm,+ )+ else:+ collapsed_outcome = emit[0]++ result = HumanFeedbackResult(+ output=context.method_output,+ feedback=feedback,+ outcome=collapsed_outcome,+ timestamp=datetime.now(),+ method_name=context.method_name,+ metadata=context.metadata,+ )++ self.human_feedback_history.append(result)+ self.last_human_feedback = result++ self._completed_methods.add(FlowMethodName(context.method_name))++ self._pending_feedback_context = None++ if self.persistence:+ self.persistence.clear_pending_feedback(context.flow_id)++ crewai_event_bus.emit(+ self,+ MethodExecutionFinishedEvent(+ type="method_execution_finished",+ flow_name=self.name or self.__class__.__name__,+ method_name=context.method_name,+ result=collapsed_outcome if emit else result,+ state=self._state,+ ),+ )++ # Clear resumption flag before triggering listeners+ # This allows methods to re-execute in loops (e.g., implement_changes → suggest_changes → implement_changes)+ self._is_execution_resuming = False++ if emit and collapsed_outcome is None:+ collapsed_outcome = default_outcome or emit[0]+ result.outcome = collapsed_outcome++ try:+ if emit and collapsed_outcome:+ self._method_outputs.append(collapsed_outcome)+ await self._execute_listeners(+ FlowMethodName(collapsed_outcome),+ result,+ )+ else:+ await self._execute_listeners(+ FlowMethodName(context.method_name),+ result,+ )+ except Exception as e:+ # Check if flow was paused again for human feedback (loop case)+ from crewai.flow.async_feedback.types import HumanFeedbackPending++ if isinstance(e, HumanFeedbackPending):+ self._pending_feedback_context = e.context++ if self.persistence is None:+ from crewai.flow.persistence import SQLiteFlowPersistence++ self.persistence = SQLiteFlowPersistence()++ state_data = (+ self._state+ if isinstance(self._state, dict)+ else self._state.model_dump()+ )+ self.persistence.save_pending_feedback(+ flow_uuid=e.context.flow_id,+ context=e.context,+ state_data=state_data,+ )++ crewai_event_bus.emit(+ self,+ FlowPausedEvent(+ type="flow_paused",+ flow_name=self.name or self.__class__.__name__,+ flow_id=e.context.flow_id,+ method_name=e.context.method_name,+ state=self._copy_and_serialize_state(),+ message=e.context.message,+ emit=e.context.emit,+ ),+ )+ return e+ raise++ final_result = self._method_outputs[-1] if self._method_outputs else result++ if self._event_futures:+ await asyncio.gather(+ *[+ asyncio.wrap_future(f)+ for f in self._event_futures+ if isinstance(f, Future)+ ]+ )+ self._event_futures.clear()++ if not self.suppress_flow_events:+ future = crewai_event_bus.emit(+ self,+ FlowFinishedEvent(+ type="flow_finished",+ flow_name=self.name or self.__class__.__name__,+ result=final_result,+ state=self._copy_and_serialize_state(),+ ),+ )+ if future and isinstance(future, Future):+ try:+ await asyncio.wrap_future(future)+ except Exception:+ logger.warning("FlowFinishedEvent handler failed", exc_info=True)++ trace_listener = TraceCollectionListener()+ if trace_listener.batch_manager.batch_owner_type == "flow":+ if trace_listener.first_time_handler.is_first_time:+ trace_listener.first_time_handler.mark_events_collected()+ trace_listener.first_time_handler.handle_execution_completion()+ else:+ trace_listener.batch_manager.finalize_batch()++ return final_result++ def _create_initial_state(self) -> T:+ """Create and initialize flow state with UUID and default values.++ Returns:+ New state instance with UUID and default values initialized++ Raises:+ ValueError: If structured state model lacks 'id' field+ TypeError: If state is neither BaseModel nor dictionary+ """+ init_state = self.initial_state++ if init_state is None and hasattr(self, "_initial_state_t"):+ state_type = self._initial_state_t+ if isinstance(state_type, type):+ if issubclass(state_type, FlowState):+ instance = state_type()+ if not getattr(instance, "id", None):+ object.__setattr__(instance, "id", str(uuid4()))+ return cast(T, instance)+ if issubclass(state_type, BaseModel):++ class StateWithId(FlowState, state_type): # type: ignore+ pass++ instance = StateWithId()+ if not getattr(instance, "id", None):+ object.__setattr__(instance, "id", str(uuid4()))+ return cast(T, instance)+ if state_type is dict:+ return cast(T, {"id": str(uuid4())})++ if init_state is None:+ return cast(T, {"id": str(uuid4())})++ if isinstance(init_state, type):+ state_class = init_state+ if issubclass(state_class, FlowState):+ return cast(T, state_class())+ if issubclass(state_class, BaseModel):+ model_fields = getattr(state_class, "model_fields", None)+ if not model_fields or "id" not in model_fields:+ raise ValueError("Flow state model must have an 'id' field")+ model_instance = state_class()+ if not getattr(model_instance, "id", None):+ object.__setattr__(model_instance, "id", str(uuid4()))+ return cast(T, model_instance)+ if init_state is dict:+ return cast(T, {"id": str(uuid4())})++ if isinstance(init_state, dict):+ new_state = dict(init_state) # Copy to avoid mutations+ if "id" not in new_state:+ new_state["id"] = str(uuid4())+ return cast(T, new_state)++ if isinstance(init_state, BaseModel):+ model = init_state+ if hasattr(model, "id"):+ state_dict = model.model_dump()+ if not state_dict.get("id"):+ state_dict["id"] = str(uuid4())+ model_class = type(model)+ return cast(T, model_class(**state_dict))++ class StateWithId(FlowState, type(model)): # type: ignore+ pass++ state_dict = model.model_dump()+ state_dict["id"] = str(uuid4())+ return cast(T, StateWithId(**state_dict))+ raise TypeError(+ f"Initial state must be dict or BaseModel, got {type(self.initial_state)}"+ )++ def _copy_state(self) -> T:+ """Create a copy of the current state.++ Returns:+ A copy of the current state+ """+ if isinstance(self._state, BaseModel):+ try:+ return cast(T, self._state.model_copy(deep=True))+ except (TypeError, AttributeError):+ try:+ state_dict = self._state.model_dump()+ model_class = type(self._state)+ return cast(T, model_class(**state_dict))+ except Exception:+ return cast(T, self._state.model_copy(deep=False))+ else:+ try:+ return cast(T, copy.deepcopy(self._state))+ except (TypeError, AttributeError):+ return cast(T, self._state.copy())++ @property+ def state(self) -> T:+ return StateProxy(self._state, self._state_lock) # type: ignore[return-value]++ @property+ def method_outputs(self) -> list[Any]:+ """Returns the list of all outputs from executed methods."""+ return self._method_outputs++ @property+ def flow_id(self) -> str:+ """Returns the unique identifier of this flow instance.++ This property provides a consistent way to access the flow's unique identifier+ regardless of the underlying state implementation (dict or BaseModel).++ Returns:+ str: The flow's unique identifier, or an empty string if not found++ Note:+ This property safely handles both dictionary and BaseModel state types,+ returning an empty string if the ID cannot be retrieved rather than raising+ an exception.++ Example:+ ```python+ flow = MyFlow()+ print(f"Current flow ID: {flow.flow_id}") # Safely get flow ID+ ```+ """+ try:+ if not hasattr(self, "_state"):+ return ""++ if isinstance(self._state, dict):+ return str(self._state.get("id", ""))+ if isinstance(self._state, BaseModel):+ return str(getattr(self._state, "id", ""))+ return ""+ except (AttributeError, TypeError):+ return "" # Safely handle any unexpected attribute access issues++ def _initialize_state(self, inputs: dict[str, Any]) -> None:+ """Initialize or update flow state with new inputs.++ Args:+ inputs: Dictionary of state values to set/update++ Raises:+ ValueError: If validation fails for structured state+ TypeError: If state is neither BaseModel nor dictionary+ """+ if isinstance(self._state, dict):+ # If inputs contains an id, use it (for restoring from persistence);+ # otherwise preserve the current id or generate a new one.+ current_id = self._state.get("id")+ inputs_has_id = "id" in inputs++ for k, v in inputs.items():+ self._state[k] = v++ if not inputs_has_id:+ if current_id:+ self._state["id"] = current_id+ elif "id" not in self._state:+ self._state["id"] = str(uuid4())+ elif isinstance(self._state, BaseModel):+ try:+ model = self._state+ if hasattr(model, "model_dump"):+ current_state = model.model_dump()+ elif hasattr(model, "dict"):+ current_state = model.dict()+ else:+ current_state = {+ k: v for k, v in model.__dict__.items() if not k.startswith("_")+ }++ new_state = {**current_state, **inputs}++ model_class = type(model)+ if hasattr(model_class, "model_validate"):+ self._state = cast(T, model_class.model_validate(new_state))+ elif hasattr(model_class, "parse_obj"):+ self._state = cast(T, model_class.parse_obj(new_state))+ else:+ self._state = cast(T, model_class(**new_state))+ except ValidationError as e:+ raise ValueError(f"Invalid inputs for structured state: {e}") from e+ else:+ raise TypeError("State must be a BaseModel instance or a dictionary.")++ def _restore_state(self, stored_state: dict[str, Any]) -> None:+ """Restore flow state from persistence.++ Args:+ stored_state: Previously stored state to restore++ Raises:+ ValueError: If validation fails for structured state+ TypeError: If state is neither BaseModel nor dictionary+ """+ stored_id = stored_state.get("id")+ if not stored_id:+ raise ValueError("Stored state must have an 'id' field")++ if isinstance(self._state, dict):+ self._state.clear()+ self._state.update(stored_state)+ elif isinstance(self._state, BaseModel):+ model = self._state+ if hasattr(model, "model_validate"):+ self._state = cast(T, type(model).model_validate(stored_state))+ elif hasattr(model, "parse_obj"):+ self._state = cast(T, type(model).parse_obj(stored_state))+ else:+ self._state = cast(T, type(model)(**stored_state))+ else:+ raise TypeError(f"State must be dict or BaseModel, got {type(self._state)}")++ def reload(self, execution_data: FlowExecutionData) -> None:+ """Reloads the flow from an execution data dict.++ This method restores the flow's execution ID, completed methods, and state,+ allowing it to resume from where it left off.++ Args:+ execution_data: Flow execution data containing:+ - id: Flow execution ID+ - flow: Flow structure+ - completed_methods: list of successfully completed methods+ - execution_methods: All execution methods with their status+ """+ flow_id = execution_data.get("id")+ if flow_id:+ self._update_state_field("id", flow_id)++ self._completed_methods = {+ cast(FlowMethodName, name)+ for method_data in execution_data.get("completed_methods", [])+ if (name := method_data.get("flow_method", {}).get("name")) is not None+ }++ execution_methods = execution_data.get("execution_methods", [])+ if not execution_methods:+ return++ sorted_methods = sorted(+ execution_methods,+ key=lambda m: m.get("started_at", ""),+ )++ state_to_apply = None+ for method in reversed(sorted_methods):+ if method.get("final_state"):+ state_to_apply = method["final_state"]+ break++ if not state_to_apply and sorted_methods:+ last_method = sorted_methods[-1]+ if last_method.get("initial_state"):+ state_to_apply = last_method["initial_state"]++ if state_to_apply:+ self._apply_state_updates(state_to_apply)++ for method in sorted_methods[:-1]:+ method_name = cast(+ FlowMethodName | None, method.get("flow_method", {}).get("name")+ )+ if method_name:+ self._completed_methods.add(method_name)++ def _update_state_field(self, field_name: str, value: Any) -> None:+ """Update a single field in the state."""+ if isinstance(self._state, dict):+ self._state[field_name] = value+ elif hasattr(self._state, field_name):+ object.__setattr__(self._state, field_name, value)++ def _apply_state_updates(self, updates: dict[str, Any]) -> None:+ """Apply multiple state updates efficiently."""+ if isinstance(self._state, dict):+ self._state.update(updates)+ elif hasattr(self._state, "__dict__"):+ for key, value in updates.items():+ if hasattr(self._state, key):+ object.__setattr__(self._state, key, value)++ def kickoff(+ self,+ inputs: dict[str, Any] | None = None,+ input_files: dict[str, FileInput] | None = None,+ from_checkpoint: CheckpointConfig | None = None,+ restore_from_state_id: str | None = None,+ ) -> Any | FlowStreamingOutput:+ """Start the flow execution in a synchronous context.++ This method wraps kickoff_async so that all state initialization and event+ emission is handled in the asynchronous method.++ Args:+ inputs: Optional dictionary containing input values and/or a state ID.+ input_files: Optional dict of named file inputs for the flow.+ from_checkpoint: Optional checkpoint config. If ``restore_from``+ is set, the flow resumes from that checkpoint.+ restore_from_state_id: Optional UUID of a previously-persisted flow+ whose latest snapshot should hydrate this run's state. The new+ run is assigned a fresh ``state.id`` (or ``inputs["id"]`` if+ pinned), so its ``@persist`` writes land under a separate+ persistence key and the source flow's history is preserved.+ If the referenced state is not found, the kickoff falls back+ silently to baseline behavior. Cannot be combined with+ ``from_checkpoint``; passing both raises ``ValueError``.++ Returns:+ The final output from the flow or FlowStreamingOutput if streaming.+ """+ if from_checkpoint is not None and restore_from_state_id is not None:+ raise ValueError(+ "Cannot combine `from_checkpoint` and `restore_from_state_id`. "+ "These parameters target different state systems "+ "(Checkpointing and @persist) and cannot be used together."+ )+ restored = apply_checkpoint(self, from_checkpoint)+ if restored is not None:+ return restored.kickoff(inputs=inputs, input_files=input_files)+ if self.stream:+ result_holder: list[Any] = []+ current_task_info: TaskInfo = {+ "index": 0,+ "name": "",+ "id": "",+ "agent_role": "",+ "agent_id": "",+ }++ state = create_streaming_state(+ current_task_info, result_holder, use_async=False+ )+ output_holder: list[CrewStreamingOutput | FlowStreamingOutput] = []++ def run_flow() -> None:+ try:+ self.stream = False+ result = self.kickoff(+ inputs=inputs,+ input_files=input_files,+ restore_from_state_id=restore_from_state_id,+ )+ result_holder.append(result)+ except Exception as e:+ # HumanFeedbackPending is expected control flow, not an error+ from crewai.flow.async_feedback.types import HumanFeedbackPending++ if isinstance(e, HumanFeedbackPending):+ result_holder.append(e)+ else:+ signal_error(state, e)+ finally:+ self.stream = True+ signal_end(state)++ streaming_output = FlowStreamingOutput(+ sync_iterator=create_chunk_generator(state, run_flow, output_holder)+ )+ register_cleanup(streaming_output, state)+ output_holder.append(streaming_output)++ return streaming_output++ async def _run_flow() -> Any:+ return await self.kickoff_async(+ inputs,+ input_files,+ restore_from_state_id=restore_from_state_id,+ )++ try:+ asyncio.get_running_loop()+ ctx = contextvars.copy_context()+ with ThreadPoolExecutor(max_workers=1) as pool:+ return pool.submit(ctx.run, asyncio.run, _run_flow()).result()+ except RuntimeError:+ return asyncio.run(_run_flow())++ async def kickoff_async(+ self,+ inputs: dict[str, Any] | None = None,+ input_files: dict[str, FileInput] | None = None,+ from_checkpoint: CheckpointConfig | None = None,+ restore_from_state_id: str | None = None,+ ) -> Any | FlowStreamingOutput:+ """Start the flow execution asynchronously.++ This method performs state restoration (if an 'id' is provided and persistence is available)+ and updates the flow state with any additional inputs. It then emits the FlowStartedEvent,+ logs the flow startup, and executes all start methods. Once completed, it emits the+ FlowFinishedEvent and returns the final output.++ Args:+ inputs: Optional dictionary containing input values and/or a state ID for restoration.+ input_files: Optional dict of named file inputs for the flow.+ from_checkpoint: Optional checkpoint config. If ``restore_from``+ is set, the flow resumes from that checkpoint.+ restore_from_state_id: Optional UUID of a previously-persisted flow+ whose latest snapshot should hydrate this run's state. The new+ run is assigned a fresh ``state.id`` (or ``inputs["id"]`` if+ pinned), so subsequent ``@persist`` writes land under a+ separate persistence key. If the referenced state is not+ found, falls back silently to baseline. Cannot be combined+ with ``from_checkpoint``; passing both raises ``ValueError``.++ Returns:+ The final output from the flow, which is the result of the last executed method.+ """+ if from_checkpoint is not None and restore_from_state_id is not None:+ raise ValueError(+ "Cannot combine `from_checkpoint` and `restore_from_state_id`. "+ "These parameters target different state systems "+ "(Checkpointing and @persist) and cannot be used together."+ )+ restored = apply_checkpoint(self, from_checkpoint)+ if restored is not None:+ return await restored.kickoff_async(inputs=inputs, input_files=input_files)+ if self.stream:+ result_holder: list[Any] = []+ current_task_info: TaskInfo = {+ "index": 0,+ "name": "",+ "id": "",+ "agent_role": "",+ "agent_id": "",+ }++ state = create_streaming_state(+ current_task_info, result_holder, use_async=True+ )+ output_holder: list[CrewStreamingOutput | FlowStreamingOutput] = []++ async def run_flow() -> None:+ try:+ self.stream = False+ result = await self.kickoff_async(+ inputs=inputs,+ input_files=input_files,+ restore_from_state_id=restore_from_state_id,+ )+ result_holder.append(result)+ except Exception as e:+ # HumanFeedbackPending is expected control flow, not an error+ from crewai.flow.async_feedback.types import HumanFeedbackPending++ if isinstance(e, HumanFeedbackPending):+ result_holder.append(e)+ else:+ signal_error(state, e, is_async=True)+ finally:+ self.stream = True+ signal_end(state, is_async=True)++ streaming_output = FlowStreamingOutput(+ async_iterator=create_async_chunk_generator(+ state, run_flow, output_holder+ )+ )+ register_cleanup(streaming_output, state)+ output_holder.append(streaming_output)++ return streaming_output++ ctx = baggage.set_baggage("flow_inputs", inputs or {})+ ctx = baggage.set_baggage("flow_input_files", input_files or {}, context=ctx)+ flow_token = attach(ctx)++ flow_id_token = None+ request_id_token = None+ if current_flow_id.get() is None:+ flow_id_token = current_flow_id.set(self.flow_id)+ if current_flow_request_id.get() is None:+ request_id_token = current_flow_request_id.set(self.flow_id)++ try:+ # Reset flow state for fresh execution unless restoring from persistence+ is_restoring = (+ inputs and "id" in inputs and self.persistence is not None+ ) or self.checkpoint_completed_methods is not None+ if not is_restoring:+ # Clear completed methods and outputs for a fresh start+ self._completed_methods.clear()+ self._method_outputs.clear()+ self._pending_and_listeners.clear()+ self._clear_or_listeners()+ self._method_call_counts.clear()+ else:+ # Only enter resumption mode if there are completed methods to+ # replay. When _completed_methods is empty (e.g. a pure+ # state-reload via kickoff(inputs={"id": ...})), the flow+ # executes from scratch and the flag would incorrectly+ # suppress cyclic re-execution on the second iteration.+ if self._completed_methods:+ self._is_execution_resuming = True++ # Fork hydration: when restore_from_state_id is set and persistence is+ # available, hydrate self._state from the source UUID's latest snapshot+ # and reassign state.id to a fresh value so subsequent @persist writes+ # don't extend the source flow's history. If the source state is not+ # found, fall through silently to the existing inputs handling.+ fork_succeeded = False+ if restore_from_state_id is not None and self.persistence is not None:+ stored_state = self.persistence.load_state(restore_from_state_id)+ if stored_state:+ self._log_flow_event(+ f"Forking flow state from UUID: {restore_from_state_id}"+ )+ self._restore_state(stored_state)+ # Pin to inputs["id"] when provided, otherwise mint a fresh+ # UUID. NOTE: pinning inputs.id while forking shares a+ # persistence key with another flow — usually you want only+ # restore_from_state_id.+ new_state_id = (inputs.get("id") if inputs else None) or str(+ uuid4()+ )+ if isinstance(self._state, dict):+ self._state["id"] = new_state_id+ elif isinstance(self._state, BaseModel):+ setattr(self._state, "id", new_state_id) # noqa: B010+ fork_succeeded = True+ else:+ self._log_flow_event(+ "No flow state found for restore_from_state_id: "+ f"{restore_from_state_id}; proceeding without hydration",+ color="yellow",+ )++ if inputs:+ # Override the id in the state if it exists in inputs.+ # Skip when the fork already assigned state.id above.+ if "id" in inputs and not fork_succeeded:+ if isinstance(self._state, dict):+ self._state["id"] = inputs["id"]+ elif isinstance(self._state, BaseModel):+ setattr(self._state, "id", inputs["id"]) # noqa: B010++ # If persistence is enabled, attempt to restore the stored state using the provided id.+ # Skip when the fork already restored self._state above.+ if (+ "id" in inputs+ and self.persistence is not None+ and not fork_succeeded+ ):+ restore_uuid = inputs["id"]+ stored_state = self.persistence.load_state(restore_uuid)+ if stored_state:+ self._log_flow_event(+ f"Loading flow state from memory for UUID: {restore_uuid}"+ )+ self._restore_state(stored_state)+ else:+ self._log_flow_event(+ f"No flow state found for UUID: {restore_uuid}", color="red"+ )++ # Update state with any additional inputs (ignoring the 'id' key)+ filtered_inputs = {k: v for k, v in inputs.items() if k != "id"}+ if filtered_inputs:+ self._initialize_state(filtered_inputs)++ if get_current_parent_id() is None:+ reset_emission_counter()+ reset_last_event_id()++ if not self.suppress_flow_events:+ future = crewai_event_bus.emit(+ self,+ FlowStartedEvent(+ type="flow_started",+ flow_name=self.name or self.__class__.__name__,+ inputs=inputs,+ ),+ )+ if future:+ try:+ await asyncio.wrap_future(future)+ except Exception:+ logger.warning("FlowStartedEvent handler failed", exc_info=True)+ self._log_flow_event(+ f"Flow started with ID: {self.flow_id}", color="bold magenta"+ )++ # After FlowStarted (when not suppressed): env events must not pre-empt+ # trace batch init with implicit "crew" execution_type.+ get_env_context()++ if inputs is not None and "id" not in inputs:+ self._initialize_state(inputs)++ if self._is_execution_resuming:+ await self._replay_recorded_events()++ try:+ # Determine which start methods to execute at kickoff+ # Conditional start methods (with __trigger_methods__) are only triggered by their conditions+ # UNLESS there are no unconditional starts (then all starts run as entry points)+ unconditional_starts = [+ start_method+ for start_method in self._start_methods+ if not getattr(+ self._methods.get(start_method), "__trigger_methods__", None+ )+ ]+ # If there are unconditional starts, only run those at kickoff+ # If there are NO unconditional starts, run all starts (including conditional ones)+ starts_to_execute = (+ unconditional_starts+ if unconditional_starts+ else self._start_methods+ )+ tasks = [+ self._execute_start_method(start_method)+ for start_method in starts_to_execute+ ]+ await asyncio.gather(*tasks)+ except Exception as e:+ # Check if flow was paused for human feedback+ from crewai.flow.async_feedback.types import HumanFeedbackPending++ if isinstance(e, HumanFeedbackPending):+ # Auto-save pending feedback (create default persistence if needed)+ if self.persistence is None:+ from crewai.flow.persistence import SQLiteFlowPersistence++ self.persistence = SQLiteFlowPersistence()++ state_data = (+ self._state+ if isinstance(self._state, dict)+ else self._state.model_dump()+ )+ self.persistence.save_pending_feedback(+ flow_uuid=e.context.flow_id,+ context=e.context,+ state_data=state_data,+ )++ # Emit flow paused event+ future = crewai_event_bus.emit(+ self,+ FlowPausedEvent(+ type="flow_paused",+ flow_name=self.name or self.__class__.__name__,+ flow_id=e.context.flow_id,+ method_name=e.context.method_name,+ state=self._copy_and_serialize_state(),+ message=e.context.message,+ emit=e.context.emit,+ ),+ )+ if future and isinstance(future, Future):+ self._event_futures.append(future)++ # Wait for events to be processed+ if self._event_futures:+ await asyncio.gather(+ *[+ asyncio.wrap_future(f)+ for f in self._event_futures+ if isinstance(f, Future)+ ]+ )+ self._event_futures.clear()++ # Return the pending exception instead of raising+ # This allows the caller to handle the paused state gracefully+ return e++ # Re-raise other exceptions+ raise++ # Clear the resumption flag after initial execution completes+ self._is_execution_resuming = False++ final_output = self._method_outputs[-1] if self._method_outputs else None++ if self._event_futures:+ await asyncio.gather(+ *[asyncio.wrap_future(f) for f in self._event_futures]+ )+ self._event_futures.clear()++ if not self.suppress_flow_events:+ future = crewai_event_bus.emit(+ self,+ FlowFinishedEvent(+ type="flow_finished",+ flow_name=self.name or self.__class__.__name__,+ result=final_output,+ state=self._copy_and_serialize_state(),+ ),+ )+ if future:+ try:+ await asyncio.wrap_future(future)+ except Exception:+ logger.warning(+ "FlowFinishedEvent handler failed", exc_info=True+ )++ if not self.suppress_flow_events:+ trace_listener = TraceCollectionListener()+ if trace_listener.batch_manager.batch_owner_type == "flow":+ if trace_listener.first_time_handler.is_first_time:+ trace_listener.first_time_handler.mark_events_collected()+ trace_listener.first_time_handler.handle_execution_completion()+ else:+ trace_listener.batch_manager.finalize_batch()++ return final_output+ finally:+ # Ensure all background memory saves complete before returning+ if self.memory is not None and hasattr(self.memory, "drain_writes"):+ self.memory.drain_writes()+ if request_id_token is not None:+ current_flow_request_id.reset(request_id_token)+ if flow_id_token is not None:+ current_flow_id.reset(flow_id_token)+ detach(flow_token)++ async def akickoff(+ self,+ inputs: dict[str, Any] | None = None,+ input_files: dict[str, FileInput] | None = None,+ from_checkpoint: CheckpointConfig | None = None,+ restore_from_state_id: str | None = None,+ ) -> Any | FlowStreamingOutput:+ """Native async method to start the flow execution. Alias for kickoff_async.++ Args:+ inputs: Optional dictionary containing input values and/or a state ID for restoration.+ input_files: Optional dict of named file inputs for the flow.+ from_checkpoint: Optional checkpoint config. If ``restore_from``+ is set, the flow resumes from that checkpoint.+ restore_from_state_id: Optional UUID of a previously-persisted flow+ whose latest snapshot should hydrate this run's state. See+ ``kickoff_async`` for full semantics.++ Returns:+ The final output from the flow, which is the result of the last executed method.+ """+ return await self.kickoff_async(+ inputs,+ input_files,+ from_checkpoint,+ restore_from_state_id=restore_from_state_id,+ )++ async def _replay_recorded_events(self) -> None:+ """Dispatch recorded ``MethodExecution*`` events from the event record."""+ state = crewai_event_bus.runtime_state+ if state is None:+ return+ record = state.event_record+ if len(record) == 0:+ return++ replayable = (+ MethodExecutionStartedEvent,+ MethodExecutionFinishedEvent,+ MethodExecutionFailedEvent,+ )+ flow_name = self.name or self.__class__.__name__+ nodes = sorted(+ (+ n+ for n in record.all_nodes()+ if isinstance(n.event, replayable)+ and n.event.flow_name == flow_name+ and n.event.method_name in self._completed_methods+ ),+ key=lambda n: n.event.emission_sequence or 0,+ )++ for node in nodes:+ future = crewai_event_bus.replay(self, node.event)+ if future is not None:+ try:+ await asyncio.wrap_future(future)+ except Exception:+ logger.warning(+ "Replayed event handler failed: %s",+ node.event.type,+ exc_info=True,+ )++ async def _execute_start_method(self, start_method_name: FlowMethodName) -> None:+ """Executes a flow's start method and its triggered listeners.++ This internal method handles the execution of methods marked with @start+ decorator and manages the subsequent chain of listener executions.++ Args:+ start_method_name: The name of the start method to execute.++ Note:+ - Executes the start method and captures its result+ - Triggers execution of any listeners waiting on this start method+ - Part of the flow's initialization sequence+ - Skips execution if method was already completed (e.g., after reload)+ - Automatically injects crewai_trigger_payload if available in flow inputs+ """+ if start_method_name in self._completed_methods:+ if self._is_execution_resuming:+ # During resumption, skip execution but continue listeners+ last_output = self._method_outputs[-1] if self._method_outputs else None+ await self._execute_listeners(start_method_name, last_output)+ return+ # For cyclic flows, clear from completed to allow re-execution+ self._completed_methods.discard(start_method_name)+ # Also clear fired OR listeners to allow them to fire again in new cycle+ self._clear_or_listeners()++ method = self._methods[start_method_name]+ enhanced_method = self._inject_trigger_payload_for_start_method(method)++ result, finished_event_id = await self._execute_method(+ start_method_name, enhanced_method+ )++ # If start method is a router, use its result as an additional trigger+ if start_method_name in self._routers and result is not None:+ # Execute listeners for the start method name first+ await self._execute_listeners(start_method_name, result, finished_event_id)+ # Then execute listeners for the router result (e.g., "approved")+ router_result_trigger = FlowMethodName(str(result))+ listener_result = (+ self.last_human_feedback+ if self.last_human_feedback is not None+ else result+ )+ await self._execute_listeners(+ router_result_trigger, listener_result, finished_event_id+ )+ else:+ await self._execute_listeners(start_method_name, result, finished_event_id)++ def _inject_trigger_payload_for_start_method(+ self, original_method: Callable[..., Any]+ ) -> Callable[..., Any]:+ def prepare_kwargs(+ *args: Any, **kwargs: Any+ ) -> tuple[tuple[Any, ...], dict[str, Any]]:+ inputs = cast(dict[str, Any], baggage.get_baggage("flow_inputs") or {})+ trigger_payload = inputs.get("crewai_trigger_payload")++ sig = inspect.signature(original_method)+ accepts_trigger_payload = "crewai_trigger_payload" in sig.parameters++ if trigger_payload is not None and accepts_trigger_payload:+ kwargs["crewai_trigger_payload"] = trigger_payload+ elif trigger_payload is not None:+ self._log_flow_event(+ f"Trigger payload available but {original_method.__name__} doesn't accept crewai_trigger_payload parameter"+ )+ return args, kwargs++ if asyncio.iscoroutinefunction(original_method):++ async def enhanced_method(*args: Any, **kwargs: Any) -> Any:+ args, kwargs = prepare_kwargs(*args, **kwargs)+ return await original_method(*args, **kwargs)+ else:++ def enhanced_method(*args: Any, **kwargs: Any) -> Any: # type: ignore[misc]+ args, kwargs = prepare_kwargs(*args, **kwargs)+ return original_method(*args, **kwargs)++ enhanced_method.__name__ = original_method.__name__+ enhanced_method.__doc__ = original_method.__doc__++ return enhanced_method++ async def _execute_method(+ self,+ method_name: FlowMethodName,+ method: Callable[..., Any],+ *args: Any,+ **kwargs: Any,+ ) -> tuple[Any, str | None]:+ """Execute a method and emit events.++ Returns:+ A tuple of (result, finished_event_id) where finished_event_id is+ the event_id of the MethodExecutionFinishedEvent, or None if events+ are suppressed.+ """+ try:+ dumped_params = {f"_{i}": arg for i, arg in enumerate(args)} | (+ kwargs or {}+ )++ if not self.suppress_flow_events:+ future = crewai_event_bus.emit(+ self,+ MethodExecutionStartedEvent(+ type="method_execution_started",+ method_name=method_name,+ flow_name=self.name or self.__class__.__name__,+ params=dumped_params,+ state=self._copy_and_serialize_state(),+ ),+ )+ if future:+ self._event_futures.append(future)++ # Set method name in context so ask() can read it without+ # stack inspection. Must happen before copy_context() so the+ # value propagates into the thread pool for sync methods.+ from crewai.flow.flow_context import current_flow_method_name++ method_name_token = current_flow_method_name.set(method_name)+ try:+ if asyncio.iscoroutinefunction(method):+ result = await method(*args, **kwargs)+ else:+ # Run sync methods in thread pool for isolation+ # This allows Agent.kickoff() to work synchronously inside Flow methods+ ctx = contextvars.copy_context()+ result = await asyncio.to_thread(ctx.run, method, *args, **kwargs)+ finally:+ current_flow_method_name.reset(method_name_token)++ # Auto-await coroutines returned from sync methods (enables AgentExecutor pattern)+ if asyncio.iscoroutine(result):+ result = await result++ self._method_outputs.append(result)++ # For @human_feedback methods with emit, the result is the collapsed outcome+ # (e.g., "approved") used for routing. But we want the actual method output+ # to be the stored result (for final flow output). Replace the last entry+ # if a stashed output exists. Dict-based stash is concurrency-safe and+ # handles None return values (presence in dict = stashed, not value).+ if method_name in self._human_feedback_method_outputs:+ self._method_outputs[-1] = self._human_feedback_method_outputs.pop(+ method_name+ )++ self._method_execution_counts[method_name] = (+ self._method_execution_counts.get(method_name, 0) + 1+ )++ self._completed_methods.add(method_name)++ finished_event_id: str | None = None+ if not self.suppress_flow_events:+ finished_event = MethodExecutionFinishedEvent(+ type="method_execution_finished",+ method_name=method_name,+ flow_name=self.name or self.__class__.__name__,+ state=self._copy_and_serialize_state(),+ result=result,+ )+ finished_event_id = finished_event.event_id+ future = crewai_event_bus.emit(self, finished_event)+ if future:+ self._event_futures.append(future)++ return result, finished_event_id+ except Exception as e:+ # Check if this is a HumanFeedbackPending exception (paused, not failed)+ from crewai.flow.async_feedback.types import HumanFeedbackPending++ if isinstance(e, HumanFeedbackPending):+ e.context.method_name = method_name++ if self.persistence is None:+ from crewai.flow.persistence import SQLiteFlowPersistence++ self.persistence = SQLiteFlowPersistence()++ # Emit paused event (not failed)+ if not self.suppress_flow_events:+ future = crewai_event_bus.emit(+ self,+ MethodExecutionPausedEvent(+ type="method_execution_paused",+ method_name=method_name,+ flow_name=self.name or self.__class__.__name__,+ state=self._copy_and_serialize_state(),+ flow_id=e.context.flow_id,+ message=e.context.message,+ emit=e.context.emit,+ ),+ )+ if future:+ self._event_futures.append(future)+ elif not self.suppress_flow_events:+ # Regular failure - emit failed event+ future = crewai_event_bus.emit(+ self,+ MethodExecutionFailedEvent(+ type="method_execution_failed",+ method_name=method_name,+ flow_name=self.name or self.__class__.__name__,+ error=e,+ ),+ )+ if future:+ self._event_futures.append(future)+ raise e++ def _copy_and_serialize_state(self) -> dict[str, Any]:+ state_copy = self._copy_state()+ if isinstance(state_copy, BaseModel):+ try:+ return state_copy.model_dump(mode="json")+ except Exception:+ return state_copy.model_dump()+ else:+ return state_copy++ async def _execute_listeners(+ self,+ trigger_method: FlowMethodName,+ result: Any,+ triggering_event_id: str | None = None,+ ) -> None:+ """Executes all listeners and routers triggered by a method completion.++ This internal method manages the execution flow by:+ 1. First executing all triggered routers sequentially+ 2. Then executing all triggered listeners in parallel++ Args:+ trigger_method: The name of the method that triggered these listeners.+ result: The result from the triggering method, passed to listeners that accept parameters.+ triggering_event_id: The event_id of the MethodExecutionFinishedEvent that+ triggered these listeners, used for causal chain tracking.++ Note:+ - Routers are executed sequentially to maintain flow control+ - Each router's result becomes a new trigger_method+ - Normal listeners are executed in parallel for efficiency+ - Listeners can receive the trigger method's result as a parameter+ """+ # First, handle routers repeatedly until no router triggers anymore+ router_results = []+ router_result_to_feedback: dict[+ str, Any+ ] = {} # Map outcome -> HumanFeedbackResult+ current_trigger = trigger_method+ current_result = result # Track the result to pass to each router+ current_triggering_event_id = triggering_event_id++ while True:+ routers_triggered = self._find_triggered_methods(+ current_trigger, router_only=True+ )+ if not routers_triggered:+ break++ for router_name in routers_triggered:+ # For routers triggered by a router outcome, pass the HumanFeedbackResult+ router_input = router_result_to_feedback.get(+ str(current_trigger), current_result+ )+ (+ router_result,+ current_triggering_event_id,+ ) = await self._execute_single_listener(+ router_name, router_input, current_triggering_event_id+ )+ if router_result: # Only add non-None results+ router_result_str = (+ router_result.value+ if isinstance(router_result, enum.Enum)+ else str(router_result)+ )+ router_results.append(FlowMethodName(router_result_str))+ # If this was a human_feedback router, map the outcome to the feedback+ if self.last_human_feedback is not None:+ router_result_to_feedback[router_result_str] = (+ self.last_human_feedback+ )+ current_trigger = (+ FlowMethodName(+ router_result.value+ if isinstance(router_result, enum.Enum)+ else str(router_result)+ )+ if router_result is not None+ else FlowMethodName("") # Update for next iteration of router chain+ )++ # Now execute normal listeners for all router results and the original trigger+ all_triggers = [trigger_method, *router_results]++ for current_trigger in all_triggers:+ if current_trigger: # Skip None results+ listeners_triggered = self._find_triggered_methods(+ current_trigger, router_only=False+ )+ if listeners_triggered:+ # Determine what result to pass to listeners+ # For router outcomes, pass the HumanFeedbackResult if available+ listener_result = router_result_to_feedback.get(+ str(current_trigger), result+ )+ racing_group = self._get_racing_group_for_listeners(+ listeners_triggered+ )+ if racing_group:+ racing_members, _ = racing_group+ other_listeners = [+ name+ for name in listeners_triggered+ if name not in racing_members+ ]+ await self._execute_racing_listeners(+ racing_members,+ other_listeners,+ listener_result,+ current_triggering_event_id,+ )+ else:+ tasks = [+ self._execute_single_listener(+ listener_name,+ listener_result,+ current_triggering_event_id,+ )+ for listener_name in listeners_triggered+ ]+ await asyncio.gather(*tasks)++ if current_trigger in router_results:+ for method_name in self._start_methods:+ if method_name in self._listeners:+ condition_data = self._listeners[method_name]+ should_trigger = False+ if is_simple_flow_condition(condition_data):+ _, trigger_methods = condition_data+ should_trigger = current_trigger in trigger_methods+ elif isinstance(condition_data, dict):+ all_methods = _extract_all_methods(condition_data)+ should_trigger = current_trigger in all_methods++ if should_trigger:+ if method_name in self._completed_methods:+ # Cyclic re-execution: temporarily clear resumption flag so the method actually re-runs+ was_resuming = self._is_execution_resuming+ self._is_execution_resuming = False+ await self._execute_start_method(method_name)+ self._is_execution_resuming = was_resuming+ else:+ await self._execute_start_method(method_name)++ def _evaluate_condition(+ self,+ condition: FlowMethodName | FlowCondition,+ trigger_method: FlowMethodName,+ listener_name: FlowMethodName,+ ) -> bool:+ """Recursively evaluate a condition (simple or nested).++ Args:+ condition: Can be a string (method name) or dict (nested condition)+ trigger_method: The method that just completed+ listener_name: Name of the listener being evaluated++ Returns:+ True if the condition is satisfied, False otherwise+ """+ if is_flow_method_name(condition):+ return condition == trigger_method++ if is_flow_condition_dict(condition):+ normalized = _normalize_condition(condition)+ cond_type = normalized.get("type", OR_CONDITION)+ sub_conditions = normalized.get("conditions", [])++ if cond_type == OR_CONDITION:+ return any(+ self._evaluate_condition(sub_cond, trigger_method, listener_name)+ for sub_cond in sub_conditions+ )++ if cond_type == AND_CONDITION:+ pending_key = PendingListenerKey(f"{listener_name}:{id(condition)}")++ if pending_key not in self._pending_and_listeners:+ all_methods = set(_extract_all_methods(condition))+ self._pending_and_listeners[pending_key] = all_methods++ if trigger_method in self._pending_and_listeners[pending_key]:+ self._pending_and_listeners[pending_key].discard(trigger_method)++ direct_methods_satisfied = not self._pending_and_listeners[pending_key]++ nested_conditions_satisfied = all(+ (+ self._evaluate_condition(+ sub_cond, trigger_method, listener_name+ )+ if is_flow_condition_dict(sub_cond)+ else True+ )+ for sub_cond in sub_conditions+ )++ if direct_methods_satisfied and nested_conditions_satisfied:+ self._pending_and_listeners.pop(pending_key, None)+ return True++ return False++ return False++ def _find_triggered_methods(+ self, trigger_method: FlowMethodName, router_only: bool+ ) -> list[FlowMethodName]:+ """Finds all methods that should be triggered based on conditions.++ This internal method evaluates both OR and AND conditions to determine+ which methods should be executed next in the flow. Supports nested conditions.++ Args:+ trigger_method: The name of the method that just completed execution.+ router_only: If True, only consider router methods. If False, only consider non-router methods.++ Returns:+ Names of methods that should be triggered.++ Note:+ - Handles both OR and AND conditions, including nested combinations+ - Maintains state for AND conditions using _pending_and_listeners+ - Separates router and normal listener evaluation+ """+ triggered: list[FlowMethodName] = []++ for listener_name, condition_data in self._listeners.items():+ is_router = listener_name in self._routers++ if router_only != is_router:+ continue++ if not router_only and listener_name in self._start_methods:+ continue++ if is_simple_flow_condition(condition_data):+ condition_type, methods = condition_data++ if condition_type == OR_CONDITION:+ # Only trigger multi-source OR listeners (or_(A, B, C)) once - skip if already fired+ # Simple single-method listeners fire every time their trigger occurs+ # Routers also fire every time - they're decision points+ has_multiple_triggers = len(methods) > 1+ should_check_fired = has_multiple_triggers and not is_router++ if (+ not should_check_fired+ or listener_name not in self._fired_or_listeners+ ):+ if trigger_method in methods:+ triggered.append(listener_name)+ # Only track multi-source OR listeners (not single-method or routers)+ if should_check_fired:+ self._fired_or_listeners.add(listener_name)+ elif condition_type == AND_CONDITION:+ pending_key = PendingListenerKey(listener_name)+ if pending_key not in self._pending_and_listeners:+ self._pending_and_listeners[pending_key] = set(methods)+ if trigger_method in self._pending_and_listeners[pending_key]:+ self._pending_and_listeners[pending_key].discard(trigger_method)++ if not self._pending_and_listeners[pending_key]:+ triggered.append(listener_name)+ self._pending_and_listeners.pop(pending_key, None)++ elif is_flow_condition_dict(condition_data):+ # For complex conditions, check if top-level is OR and track accordingly+ top_level_type = condition_data.get("type", OR_CONDITION)+ is_or_based = top_level_type == OR_CONDITION++ # Only track multi-source OR conditions (multiple sub-conditions), not routers+ sub_conditions = condition_data.get("conditions", [])+ has_multiple_triggers = is_or_based and len(sub_conditions) > 1+ should_check_fired = has_multiple_triggers and not is_router++ # Skip compound OR-based listeners that have already fired+ if should_check_fired and listener_name in self._fired_or_listeners:+ continue++ if self._evaluate_condition(+ condition_data, trigger_method, listener_name+ ):+ triggered.append(listener_name)+ # Track compound OR-based listeners so they only fire once+ if should_check_fired:+ self._fired_or_listeners.add(listener_name)++ return triggered++ async def _execute_single_listener(+ self,+ listener_name: FlowMethodName,+ result: Any,+ triggering_event_id: str | None = None,+ ) -> tuple[Any, str | None]:+ """Executes a single listener method with proper event handling.++ This internal method manages the execution of an individual listener,+ including parameter inspection, event emission, and error handling.++ Args:+ listener_name: The name of the listener method to execute.+ result: The result from the triggering method, which may be passed to the listener if it accepts parameters.+ triggering_event_id: The event_id of the event that triggered this listener,+ used for causal chain tracking.++ Returns:+ A tuple of (listener_result, event_id) where listener_result is the return+ value of the listener method and event_id is the MethodExecutionFinishedEvent+ id, or (None, None) if skipped during resumption.++ Note:+ - Inspects method signature to determine if it accepts the trigger result+ - Emits events for method execution start and finish+ - Handles errors gracefully with detailed logging+ - Recursively triggers listeners of this listener+ - Supports both parameterized and parameter-less listeners+ - Skips execution if method was already completed (e.g., after reload)+ - Catches and logs any exceptions during execution, preventing individual listener failures from breaking the entire flow+ """+ count = self._method_call_counts.get(listener_name, 0) + 1+ if count > self.max_method_calls:+ raise RecursionError(+ f"Method '{listener_name}' has been called {self.max_method_calls} times in "+ f"this flow execution, which indicates an infinite loop. "+ f"This commonly happens when a @listen label matches the "+ f"method's own name."+ )+ self._method_call_counts[listener_name] = count++ if listener_name in self._completed_methods:+ if self._is_execution_resuming:+ # During resumption, skip execution but continue listeners+ await self._execute_listeners(listener_name, None)++ # For routers, also check if any conditional starts they triggered are completed+ # If so, continue their chains+ if listener_name in self._routers:+ for start_method_name in self._start_methods:+ if (+ start_method_name in self._listeners+ and start_method_name in self._completed_methods+ ):+ # This conditional start was executed, continue its chain+ await self._execute_start_method(start_method_name)+ return (None, None)+ # For cyclic flows, clear from completed to allow re-execution+ self._completed_methods.discard(listener_name)+ # Clear ALL fired OR listeners so they can fire again in the new cycle.+ # This mirrors what _execute_start_method does for start-method cycles.+ # Only discarding the individual listener is insufficient because+ # downstream or_() listeners (e.g., method_a listening to+ # or_(handler_a, handler_b)) would remain suppressed across iterations.+ self._clear_or_listeners()++ try:+ method = self._methods[listener_name]++ sig = inspect.signature(method)+ params = list(sig.parameters.values())+ method_params = [p for p in params if p.name != "self"]++ if triggering_event_id:+ with triggered_by_scope(triggering_event_id):+ if method_params:+ listener_result, finished_event_id = await self._execute_method(+ listener_name, method, result+ )+ else:+ listener_result, finished_event_id = await self._execute_method(+ listener_name, method+ )+ else:+ if method_params:+ listener_result, finished_event_id = await self._execute_method(+ listener_name, method, result+ )+ else:+ listener_result, finished_event_id = await self._execute_method(+ listener_name, method+ )++ await self._execute_listeners(+ listener_name, listener_result, finished_event_id+ )++ return (listener_result, finished_event_id)++ except Exception as e:+ # Don't log HumanFeedbackPending as an error - it's expected control flow+ from crewai.flow.async_feedback.types import HumanFeedbackPending++ if not isinstance(e, HumanFeedbackPending):+ if not getattr(e, "_flow_listener_logged", False):+ logger.error(f"Error executing listener {listener_name}: {e}")+ e._flow_listener_logged = True # type: ignore[attr-defined]+ raise++ def _resolve_input_provider(self) -> InputProvider:+ """Resolve the input provider using the priority chain.++ Resolution order:+ 1. ``self.input_provider`` (per-flow override)+ 2. ``flow_config.input_provider`` (global default)+ 3. ``ConsoleInputProvider()`` (built-in fallback)++ Returns:+ An object implementing the ``InputProvider`` protocol.+ """+ from crewai.flow.async_feedback.providers import ConsoleProvider+ from crewai.flow.flow_config import flow_config++ if self.input_provider is not None:+ return self.input_provider+ if flow_config.input_provider is not None:+ return flow_config.input_provider+ return ConsoleProvider()++ def _checkpoint_state_for_ask(self) -> None:+ """Auto-checkpoint flow state before waiting for user input.++ If persistence is configured, saves the current state so that+ ``self.state`` is recoverable even if the process crashes while+ waiting for input.++ This is best-effort: if persistence is not configured, this is a no-op.+ """+ if self.persistence is None:+ return+ try:+ state_data = (+ self._state+ if isinstance(self._state, dict)+ else self._state.model_dump()+ )+ self.persistence.save_state(+ flow_uuid=self.flow_id,+ method_name="_ask_checkpoint",+ state_data=state_data,+ )+ except Exception:+ logger.debug("Failed to checkpoint state before ask()", exc_info=True)++ def ask(+ self,+ message: str,+ timeout: float | None = None,+ metadata: dict[str, Any] | None = None,+ ) -> str | None:+ """Request input from the user during flow execution.++ Blocks the current thread until the user provides input or the+ timeout expires. Works in both sync and async flow methods (the+ flow framework runs sync methods in a thread pool via+ ``asyncio.to_thread``, so the event loop stays free).++ Timeout ensures flows always terminate. When timeout expires,+ ``None`` is returned, enabling the pattern::++ while (msg := self.ask("You: ", timeout=300)) is not None:+ process(msg)++ Before waiting for input, the current ``self.state`` is automatically+ checkpointed to persistence (if configured) for durability.++ Args:+ message: The question or prompt to display to the user.+ timeout: Maximum seconds to wait for input. ``None`` means+ wait indefinitely. When timeout expires, returns ``None``.+ Note: timeout is best-effort for the provider call --+ ``ask()`` returns ``None`` promptly, but the underlying+ ``request_input()`` may continue running in a background+ thread until it completes naturally. Network providers+ should implement their own internal timeouts.+ metadata: Optional metadata to send to the input provider,+ such as user ID, channel, session context. The provider+ can use this to route the question to the right recipient.++ Returns:+ The user's input as a string, or ``None`` on timeout, disconnect,+ or provider error. Empty string ``""`` means the user pressed+ Enter without typing (intentional empty input).++ Example:+ ```python+ class MyFlow(Flow):+ @start()+ def gather_info(self):+ topic = self.ask(+ "What topic should we research?",+ metadata={"user_id": "u123", "channel": "#research"},+ )+ if topic is None:+ return "No input received"+ return topic+ ```+ """+ from concurrent.futures import (+ ThreadPoolExecutor,+ TimeoutError as FuturesTimeoutError,+ )+ from datetime import datetime++ from crewai.events.types.flow_events import (+ FlowInputReceivedEvent,+ FlowInputRequestedEvent,+ )+ from crewai.flow.flow_context import current_flow_method_name+ from crewai.flow.input_provider import InputResponse++ method_name = current_flow_method_name.get("unknown")++ crewai_event_bus.emit(+ self,+ FlowInputRequestedEvent(+ type="flow_input_requested",+ flow_name=self.name or self.__class__.__name__,+ method_name=method_name,+ message=message,+ metadata=metadata,+ ),+ )++ self._checkpoint_state_for_ask()++ provider = self._resolve_input_provider()+ raw: str | InputResponse | None = None++ try:+ if timeout is not None:+ # Manual executor management to avoid shutdown(wait=True)+ # deadlock when the provider call outlives the timeout.+ executor = ThreadPoolExecutor(max_workers=1)+ ctx = contextvars.copy_context()+ future = executor.submit(+ ctx.run, provider.request_input, message, self, metadata+ )+ try:+ raw = future.result(timeout=timeout)+ except FuturesTimeoutError:+ future.cancel()+ raw = None+ finally:+ # wait=False so we don't block if the provider is still+ # running (e.g. input() stuck waiting for user).+ # cancel_futures=True cleans up any queued-but-not-started tasks.+ executor.shutdown(wait=False, cancel_futures=True)+ else:+ raw = provider.request_input(message, self, metadata=metadata)+ except KeyboardInterrupt:+ raise+ except Exception:+ logger.debug("Input provider error in ask()", exc_info=True)+ raw = None++ response: str | None = None+ response_metadata: dict[str, Any] | None = None++ if isinstance(raw, InputResponse):+ response = raw.text+ response_metadata = raw.metadata+ elif isinstance(raw, str):+ response = raw+ else:+ response = None++ self._input_history.append(+ {+ "message": message,+ "response": response,+ "method_name": method_name,+ "timestamp": datetime.now(),+ "metadata": metadata,+ "response_metadata": response_metadata,+ }+ )++ crewai_event_bus.emit(+ self,+ FlowInputReceivedEvent(+ type="flow_input_received",+ flow_name=self.name or self.__class__.__name__,+ method_name=method_name,+ message=message,+ response=response,+ metadata=metadata,+ response_metadata=response_metadata,+ ),+ )++ return response++ def _request_human_feedback(+ self,+ message: str,+ output: Any,+ metadata: dict[str, Any] | None = None,+ emit: Sequence[str] | None = None,+ ) -> str:+ """Request feedback from a human.+ Args:+ message: The message to display when requesting feedback.+ output: The method output to show the human for review.+ metadata: Optional metadata for enterprise integrations.+ emit: Optional list of possible outcomes for routing.++ Returns:+ The human's feedback as a string. Empty string if no feedback provided.+ """+ from crewai.events.event_listener import event_listener+ from crewai.events.types.flow_events import (+ HumanFeedbackReceivedEvent,+ HumanFeedbackRequestedEvent,+ )++ crewai_event_bus.emit(+ self,+ HumanFeedbackRequestedEvent(+ type="human_feedback_requested",+ flow_name=self.name or self.__class__.__name__,+ method_name="", # Will be set by decorator if needed+ output=output,+ message=message,+ emit=list(emit) if emit else None,+ ),+ )++ formatter = event_listener.formatter+ formatter.pause_live_updates()++ try:+ formatter.console.print("\n" + "═" * 50, style="bold cyan")+ formatter.console.print(" OUTPUT FOR REVIEW", style="bold cyan")+ formatter.console.print("═" * 50 + "\n", style="bold cyan")+ formatter.console.print(output)+ formatter.console.print("\n" + "═" * 50 + "\n", style="bold cyan")++ formatter.console.print(message, style="yellow")+ formatter.console.print(+ "(Press Enter to skip, or type your feedback)\n", style="cyan"+ )++ feedback = input("Your feedback: ").strip()++ crewai_event_bus.emit(+ self,+ HumanFeedbackReceivedEvent(+ type="human_feedback_received",+ flow_name=self.name or self.__class__.__name__,+ method_name="", # Will be set by decorator if needed+ feedback=feedback,+ outcome=None, # Will be determined after collapsing+ ),+ )++ return feedback+ finally:+ formatter.resume_live_updates()++ def _collapse_to_outcome(+ self,+ feedback: str,+ outcomes: Sequence[str],+ llm: str | BaseLLM,+ ) -> str:+ """Collapse free-form feedback to a predefined outcome using LLM.++ This method uses the specified LLM to interpret the human's feedback+ and map it to one of the predefined outcomes for routing purposes.++ Uses structured outputs (function calling) when supported by the LLM+ to guarantee the response is one of the valid outcomes. Falls back+ to simple prompting if structured outputs fail.++ Args:+ feedback: The raw human feedback text.+ outcomes: Sequence of valid outcome strings to choose from.+ llm: The LLM model to use. Can be a model string or BaseLLM instance.++ Returns:+ One of the outcome strings that best matches the feedback intent.+ """+ from typing import Literal++ from pydantic import BaseModel, Field++ from crewai.llm import LLM+ from crewai.llms.base_llm import BaseLLM as BaseLLMClass+ from crewai.utilities.i18n import I18N_DEFAULT++ llm_instance: BaseLLMClass+ if isinstance(llm, str):+ llm_instance = LLM(model=llm)+ elif isinstance(llm, BaseLLMClass):+ llm_instance = llm+ else:+ raise ValueError(f"Invalid llm type: {type(llm)}. Expected str or BaseLLM.")++ outcomes_tuple = tuple(outcomes)++ class FeedbackOutcome(BaseModel):+ """The outcome that best matches the human's feedback intent."""++ outcome: Literal[outcomes_tuple] = Field( # type: ignore[valid-type]+ description=f"The outcome that best matches the feedback. Must be one of: {', '.join(outcomes)}"+ )++ prompt_template = I18N_DEFAULT.slice("human_feedback_collapse")++ prompt = prompt_template.format(+ feedback=feedback,+ outcomes=", ".join(outcomes),+ )++ try:+ # NOTE: LLM.call with response_model returns JSON string, not a Pydantic model+ response = llm_instance.call(+ messages=[{"role": "user", "content": prompt}],+ response_model=FeedbackOutcome,+ )++ if isinstance(response, str):+ import json++ try:+ parsed = json.loads(response)+ return str(parsed.get("outcome", outcomes[0]))+ except json.JSONDecodeError:+ response_clean = response.strip()+ for outcome in outcomes:+ if outcome.lower() == response_clean.lower():+ return outcome+ return outcomes[0]+ elif isinstance(response, FeedbackOutcome):+ return str(response.outcome)+ elif hasattr(response, "outcome"):+ return str(response.outcome)+ else:+ logger.warning(f"Unexpected response type: {type(response)}")+ return outcomes[0]++ except Exception as e:+ logger.warning(+ f"Structured output failed, falling back to simple prompting: {e}"+ )+ try:+ response = llm_instance.call(+ messages=[{"role": "user", "content": prompt}],+ )+ response_clean = str(response).strip()++ for outcome in outcomes:+ if outcome.lower() == response_clean.lower():+ return outcome++ # Partial match (longest wins, first on length ties)+ response_lower = response_clean.lower()+ best_outcome: str | None = None+ best_len = -1+ for outcome in outcomes:+ if outcome.lower() in response_lower and len(outcome) > best_len:+ best_outcome = outcome+ best_len = len(outcome)+ if best_outcome is not None:+ return best_outcome++ logger.warning(+ f"Could not match LLM response '{response_clean}' to outcomes {list(outcomes)}. "+ f"Falling back to first outcome: {outcomes[0]}"+ )+ return outcomes[0]++ except Exception as fallback_err:+ logger.warning(+ f"Simple prompting also failed: {fallback_err}. "+ f"Falling back to first outcome: {outcomes[0]}"+ )+ return outcomes[0]++ def _log_flow_event(+ self,+ message: str,+ color: str = "yellow",+ level: Literal["info", "warning"] = "info",+ ) -> None:+ """Centralized logging method for flow events.++ This method provides a consistent interface for logging flow-related events,+ combining both console output with colors and proper logging levels.++ Args:+ message: The message to log+ color: Rich style for console output (default: "yellow")+ Examples: "yellow", "red", "bold green", "bold magenta"+ level: Log level to use (default: info)+ Supported levels: info, warning++ Note:+ This method uses the centralized Rich console formatter for output+ and the standard logging module for log level support.+ """+ from crewai.events.event_listener import event_listener++ event_listener.formatter.console.print(message, style=color)+ if level == "info":+ logger.info(message)+ else:+ logger.warning(message)++ def plot(self, filename: str = "crewai_flow.html", show: bool = True) -> str:+ """Create interactive HTML visualization of Flow structure.++ Args:+ filename: Output HTML filename (default: "crewai_flow.html").+ show: Whether to open in browser (default: True).++ Returns:+ Absolute path to generated HTML file.+ """+ crewai_event_bus.emit(+ self,+ FlowPlotEvent(+ type="flow_plot",+ flow_name=self.name or self.__class__.__name__,+ ),+ )+ structure = build_flow_structure(self)+ return render_interactive(structure, filename=filename, show=show)++ @staticmethod+ def _show_tracing_disabled_message() -> None:+ """Show a message when tracing is disabled."""+ if should_suppress_tracing_messages():+ return++ console = Console()++ if has_user_declined_tracing():+ message = """Info: Tracing is disabled.++To enable tracing, do any one of these:+• Set tracing=True in your Flow code+• Set CREWAI_TRACING_ENABLED=true in your project's .env file+• Run: crewai traces enable"""+ else:+ message = """Info: Tracing is disabled.++To enable tracing, do any one of these:+• Set tracing=True in your Flow code+• Set CREWAI_TRACING_ENABLED=true in your project's .env file+• Run: crewai traces enable"""++ panel = Panel(+ message,+ title="Tracing Status",+ border_style="blue",+ padding=(1, 2),+ )+ console.print(panel)diff --git a/lib/crewai/src/crewai/flow/utils.py b/lib/crewai/src/crewai/flow/utils.pyindex 8943bf531..e23354784 100644--- a/lib/crewai/src/crewai/flow/utils.py+++ b/lib/crewai/src/crewai/flow/utils.py@@ -1,954 +1,53 @@-"""-Utility functions for flow visualization and dependency analysis.--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.+"""Backwards-compatible shim. The implementation moved to ``crewai.flow.flow_definition``.-Example--------->>> flow = Flow()->>> node_levels = calculate_node_levels(flow)->>> ancestors = build_ancestor_dict(flow)+Import from ``crewai.flow.flow_definition`` directly in new code."""-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.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,)-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.-- Returns:- List of string literals found in the annotation.- """-- strings: list[str] = []-- if isinstance(node, ast.Constant) and isinstance(node.value, str):- strings.append(node.value)-- 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)- )-- 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-- 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)-- 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)- )-- return strings---def _unwrap_function(function: Any) -> Any:- """Unwrap a function to get the original function with correct globals.-- 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.-- Returns:- The unwrapped original function.- """- if hasattr(function, "__func__"):- function = function.__func__-- if hasattr(function, "__wrapped__"):- wrapped = function.__wrapped__- if hasattr(wrapped, "unwrap"):- return wrapped.unwrap()- return wrapped-- return function---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)-- Args:- function: The function to analyze.-- 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-- 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-- return_values: set[str] = set()-- 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"- """- 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)-- StateAttributeVisitor().visit(class_ast)- except Exception as e:- if verbose:- PRINTER.print(- f"Could not analyze class context for {function.__name__}: {e}",- color="yellow",- )- 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- )- 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- )- 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- )- else:- continue-- if path in trigger_methods:- if (- listener_name not in levels- or levels[listener_name] > current_level + 1- ):- 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 []+__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/tests/test_async_human_feedback.py b/lib/crewai/tests/test_async_human_feedback.pyindex 54a235f5d..fbd047ccf 100644--- a/lib/crewai/tests/test_async_human_feedback.py+++ b/lib/crewai/tests/test_async_human_feedback.py@@ -569,13 +569,13 @@ class TestFlowResumeWithFeedback:flow = TestFlow.from_pending("async-direct-test", persistence)- with patch("crewai.flow.flow.crewai_event_bus.emit"):+ with patch("crewai.flow.runtime.crewai_event_bus.emit"):result = await flow.resume_async("async feedback")assert flow.last_human_feedback is not Noneassert flow.last_human_feedback.feedback == "async feedback"- @patch("crewai.flow.flow.crewai_event_bus.emit")+ @patch("crewai.flow.runtime.crewai_event_bus.emit")def test_resume_basic(self, mock_emit: MagicMock) -> None:"""Test basic resume functionality."""with tempfile.TemporaryDirectory() as tmpdir:@@ -615,7 +615,7 @@ class TestFlowResumeWithFeedback:assert persistence.load_pending_feedback("resume-test-123") is None- @patch("crewai.flow.flow.crewai_event_bus.emit")+ @patch("crewai.flow.runtime.crewai_event_bus.emit")def test_resume_routing(self, mock_emit: MagicMock) -> None:"""Test resume with routing."""with tempfile.TemporaryDirectory() as tmpdir:@@ -697,7 +697,7 @@ class TestAsyncHumanFeedbackIntegration:assert hasattr(method, "__human_feedback_config__")assert method.__human_feedback_config__.provider is not None- @patch("crewai.flow.flow.crewai_event_bus.emit")+ @patch("crewai.flow.runtime.crewai_event_bus.emit")def test_async_provider_pauses_flow(self, mock_emit: MagicMock) -> None:"""Test that async provider pauses flow execution."""with tempfile.TemporaryDirectory() as tmpdir:@@ -743,7 +743,7 @@ class TestAsyncHumanFeedbackIntegration:persisted = persistence.load_pending_feedback(flow_id)assert persisted is not None- @patch("crewai.flow.flow.crewai_event_bus.emit")+ @patch("crewai.flow.runtime.crewai_event_bus.emit")def test_full_async_flow_cycle(self, mock_emit: MagicMock) -> None:"""Test complete async flow: start -> pause -> resume."""with tempfile.TemporaryDirectory() as tmpdir:@@ -804,7 +804,7 @@ class TestAsyncHumanFeedbackIntegration:class TestAutoPersistence:"""Tests for automatic persistence when no persistence is provided."""- @patch("crewai.flow.flow.crewai_event_bus.emit")+ @patch("crewai.flow.runtime.crewai_event_bus.emit")def test_auto_persistence_when_none_provided(self, mock_emit: MagicMock) -> None:"""Test that persistence is auto-created when HumanFeedbackPending is raised."""@@ -925,7 +925,7 @@ class TestCollapseToOutcomeJsonParsing:class TestLLMObjectPreservedInContext:"""Tests that BaseLLM objects have their model string preserved in PendingFeedbackContext."""- @patch("crewai.flow.flow.crewai_event_bus.emit")+ @patch("crewai.flow.runtime.crewai_event_bus.emit")def test_basellm_object_model_string_survives_roundtrip(self, mock_emit: MagicMock) -> None:"""Test that when llm is a BaseLLM object, its model string is stored in contextso that outcome collapsing works after async pause/resume.@@ -1125,7 +1125,7 @@ class TestAsyncHumanFeedbackEdgeCases:flow = TestFlow.from_pending("default-test", persistence)- with patch("crewai.flow.flow.crewai_event_bus.emit"):+ with patch("crewai.flow.runtime.crewai_event_bus.emit"):result = flow.resume("")assert flow.last_human_feedback.outcome == "approved"@@ -1159,7 +1159,7 @@ class TestAsyncHumanFeedbackEdgeCases:flow = TestFlow.from_pending("no-feedback-test", persistence)- with patch("crewai.flow.flow.crewai_event_bus.emit"):+ with patch("crewai.flow.runtime.crewai_event_bus.emit"):result = flow.resume()assert flow.last_human_feedback.outcome == "approved"@@ -1213,7 +1213,7 @@ class TestLiveLLMPreservationOnResume:assert hasattr(method, "_hf_llm")assert method._hf_llm == "gpt-4o-mini"- @patch("crewai.flow.flow.crewai_event_bus.emit")+ @patch("crewai.flow.runtime.crewai_event_bus.emit")def test_resume_async_uses_live_basellm_over_serialized_string(self, mock_emit: MagicMock) -> None:@@ -1286,7 +1286,7 @@ class TestLiveLLMPreservationOnResume:# And verify it's a BaseLLM instance, not a stringassert isinstance(captured_llm[0], BaseLLM)- @patch("crewai.flow.flow.crewai_event_bus.emit")+ @patch("crewai.flow.runtime.crewai_event_bus.emit")def test_resume_async_falls_back_to_serialized_string_when_no_hf_llm(self, mock_emit: MagicMock) -> None:@@ -1344,7 +1344,7 @@ class TestLiveLLMPreservationOnResume:assert isinstance(captured_llm[0], BaseLLMClass)assert captured_llm[0].model == "gpt-4o-mini"- @patch("crewai.flow.flow.crewai_event_bus.emit")+ @patch("crewai.flow.runtime.crewai_event_bus.emit")def test_resume_async_uses_string_from_context_when_hf_llm_is_string(self, mock_emit: MagicMock) -> None: