agno 2.4.7__py3-none-any.whl → 2.4.8__py3-none-any.whl

agno/workflow/cel.py

@@ -0,0 +1,299 @@
+"""CEL (Common Expression Language) support for workflow steps.
+
+CEL spec: https://github.com/google/cel-spec
+"""
+
+import json
+import re
+from typing import Any, Dict, List, Optional, Union
+
+from agno.utils.log import logger
+
+try:
+    import celpy
+    from celpy import celtypes
+
+    CEL_AVAILABLE = True
+    CelValue = Union[
+        celtypes.BoolType,
+        celtypes.IntType,
+        celtypes.DoubleType,
+        celtypes.StringType,
+        celtypes.ListType,
+        celtypes.MapType,
+    ]
+except ImportError:
+    CEL_AVAILABLE = False
+    celpy = None  # type: ignore
+    celtypes = None  # type: ignore
+    CelValue = Any  # type: ignore
+
+# Type alias for Python values that can be converted to CEL
+PythonValue = Union[None, bool, int, float, str, List[Any], Dict[str, Any]]
+
+# Regex for simple Python identifiers (function names)
+_IDENTIFIER_RE = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+
+# Characters/tokens that indicate a CEL expression rather than a function name
+_CEL_INDICATORS = [
+    ".",
+    "(",
+    ")",
+    "[",
+    "]",
+    "==",
+    "!=",
+    "<=",
+    ">=",
+    "<",
+    ">",
+    "&&",
+    "||",
+    "!",
+    "+",
+    "-",
+    "*",
+    "/",
+    "%",
+    "?",
+    ":",
+    '"',
+    "'",
+    "true",
+    "false",
+    " in ",
+]
+
+
+# ********** Public Functions **********
+def validate_cel_expression(expression: str) -> bool:
+    """Validate a CEL expression without evaluating it.
+
+    Useful for UI validation before saving a workflow configuration.
+    """
+    if not CEL_AVAILABLE:
+        logger.warning("cel-python is not installed. Install with: pip install cel-python")
+        return False
+
+    try:
+        env = celpy.Environment()
+        env.compile(expression)
+        return True
+    except Exception as e:
+        logger.debug(f"CEL expression validation failed: {e}")
+        return False
+
+
+def is_cel_expression(value: str) -> bool:
+    """Determine if a string is a CEL expression vs a function name.
+
+    Simple identifiers like ``my_evaluator`` return False.
+    Anything containing operators, dots, parens, etc. returns True.
+    """
+    if _IDENTIFIER_RE.match(value):
+        return False
+
+    return any(indicator in value for indicator in _CEL_INDICATORS)
+
+
+def evaluate_cel_condition_evaluator(
+    expression: str,
+    step_input: "StepInput",  # type: ignore  # noqa: F821
+    session_state: Optional[Dict[str, Any]] = None,
+) -> bool:
+    """Evaluate a CEL expression for a Condition evaluator.
+
+    Context variables:
+        - input: The workflow input as a string
+        - previous_step_content: Content from the previous step
+        - previous_step_outputs: Map of step name to content string from all previous steps
+        - additional_data: Map of additional data passed to the workflow
+        - session_state: Map of session state values
+    """
+    return _evaluate_cel(expression, _build_step_input_context(step_input, session_state))
+
+
+def evaluate_cel_loop_end_condition(
+    expression: str,
+    iteration_results: "List[StepOutput]",  # type: ignore  # noqa: F821
+    current_iteration: int = 0,
+    max_iterations: int = 3,
+) -> bool:
+    """Evaluate a CEL expression as a Loop end condition.
+
+    Context variables:
+        - current_iteration: Current iteration number (1-indexed, after completion)
+        - max_iterations: Maximum iterations configured for the loop
+        - all_success: True if all steps in this iteration succeeded
+        - last_step_content: Content string from the last step in this iteration
+        - step_outputs: Map of step name to content string from the current iteration
+    """
+    return _evaluate_cel(
+        expression, _build_loop_step_output_context(iteration_results, current_iteration, max_iterations)
+    )
+
+
+def evaluate_cel_router_selector(
+    expression: str,
+    step_input: "StepInput",  # type: ignore  # noqa: F821
+    session_state: Optional[Dict[str, Any]] = None,
+    step_choices: Optional[List[str]] = None,
+) -> str:
+    """Evaluate a CEL expression for a Router selector.
+
+    Returns the name of the step to execute as a string.
+
+    Context variables (same as Condition, plus step_choices):
+        - input: The workflow input as a string
+        - previous_step_content: Content from the previous step
+        - previous_step_outputs: Map of step name to content string from all previous steps
+        - additional_data: Map of additional data passed to the workflow
+        - session_state: Map of session state values
+        - step_choices: List of step names available to the selector
+    """
+    context = _build_step_input_context(step_input, session_state)
+    context["step_choices"] = step_choices or []
+    return _evaluate_cel_string(expression, context)
+
+
+# ********** Internal Functions **********
+def _evaluate_cel_raw(expression: str, context: Dict[str, Any]) -> Any:
+    """Core CEL evaluation: compile, run, and return the raw result."""
+    if not CEL_AVAILABLE:
+        raise RuntimeError("cel-python is not installed. Install with: pip install cel-python")
+
+    try:
+        env = celpy.Environment()
+        prog = env.program(env.compile(expression))
+        return prog.evaluate({k: _to_cel(v) for k, v in context.items()})
+    except Exception as e:
+        logger.error(f"CEL evaluation failed for '{expression}': {e}")
+        raise ValueError(f"Failed to evaluate CEL expression '{expression}': {e}") from e
+
+
+def _evaluate_cel(expression: str, context: Dict[str, Any]) -> bool:
+    """CEL evaluation that coerces the result to bool."""
+    result = _evaluate_cel_raw(expression, context)
+
+    if isinstance(result, celtypes.BoolType):
+        return bool(result)
+    if isinstance(result, bool):
+        return result
+
+    logger.warning(f"CEL expression '{expression}' returned {type(result).__name__}, converting to bool")
+    return bool(result)
+
+
+def _evaluate_cel_string(expression: str, context: Dict[str, Any]) -> str:
+    """CEL evaluation that coerces the result to string (for Router selector)."""
+    result = _evaluate_cel_raw(expression, context)
+
+    if isinstance(result, celtypes.StringType):
+        return str(result)
+    if isinstance(result, str):
+        return result
+
+    logger.warning(f"CEL expression '{expression}' returned {type(result).__name__}, converting to string")
+    return str(result)
+
+
+def _to_cel(value: PythonValue) -> Union["CelValue", None]:
+    """Convert a Python value to a CEL-compatible type.
+
+    Args:
+        value: A Python value (None, bool, int, float, str, list, or dict)
+
+    Returns:
+        The corresponding CEL type, or None if input is None
+    """
+    if value is None:
+        return None
+
+    if isinstance(value, bool):
+        return celtypes.BoolType(value)
+    if isinstance(value, int):
+        return celtypes.IntType(value)
+    if isinstance(value, float):
+        return celtypes.DoubleType(value)
+    if isinstance(value, str):
+        return celtypes.StringType(value)
+    if isinstance(value, list):
+        return celtypes.ListType([_to_cel(item) for item in value])
+    if isinstance(value, dict):
+        return celtypes.MapType({celtypes.StringType(k): _to_cel(v) for k, v in value.items()})
+
+    # Fallback for any other type - convert to string
+    return celtypes.StringType(str(value))
+
+
+def _build_step_input_context(
+    step_input: "StepInput",  # type: ignore  # noqa: F821
+    session_state: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """Build context for CEL evaluation of step input.
+
+    Maps directly to StepInput fields:
+        - input: from step_input.input (as string)
+        - previous_step_content: from step_input.previous_step_content (as string)
+        - previous_step_outputs: from step_input.previous_step_outputs (map of step name -> content string)
+        - additional_data: from step_input.additional_data
+        - session_state: passed separately
+    """
+    input_str = ""
+    if step_input.input is not None:
+        input_str = step_input.get_input_as_string() or ""
+
+    previous_content = ""
+    if step_input.previous_step_content is not None:
+        if hasattr(step_input.previous_step_content, "model_dump_json"):
+            previous_content = step_input.previous_step_content.model_dump_json()
+        elif isinstance(step_input.previous_step_content, dict):
+            previous_content = json.dumps(step_input.previous_step_content, default=str)
+        else:
+            previous_content = str(step_input.previous_step_content)
+
+    previous_step_outputs: Dict[str, str] = {}
+    if step_input.previous_step_outputs:
+        for name, output in step_input.previous_step_outputs.items():
+            previous_step_outputs[name] = str(output.content) if output.content else ""
+
+    return {
+        "input": input_str,
+        "previous_step_content": previous_content,
+        "previous_step_outputs": previous_step_outputs,
+        "additional_data": step_input.additional_data or {},
+        "session_state": session_state or {},
+    }
+
+
+def _build_loop_step_output_context(
+    iteration_results: "List[StepOutput]",  # type: ignore  # noqa: F821
+    current_iteration: int = 0,
+    max_iterations: int = 3,
+) -> Dict[str, Any]:
+    """Build context for CEL evaluation of loop end condition from iteration results.
+
+    Maps to StepOutput fields:
+        - step_outputs: map of StepOutput.step_name -> str(StepOutput.content)
+        - all_success: derived from StepOutput.success
+        - last_step_content: content from the last StepOutput of the current loop iteration
+    """
+    all_success = True
+    outputs: Dict[str, str] = {}
+    last_content = ""
+
+    for result in iteration_results:
+        content = str(result.content) if result.content else ""
+        name = result.step_name or f"step_{len(outputs)}"
+        outputs[name] = content
+        last_content = content
+        if not result.success:
+            all_success = False
+
+    return {
+        "current_iteration": current_iteration,
+        "max_iterations": max_iterations,
+        "all_success": all_success,
+        "last_step_content": last_content,
+        "step_outputs": outputs,
+    }

agno/workflow/condition.py

@@ -3,6 +3,7 @@ from dataclasses import dataclass
 from typing import Any, AsyncIterator, Awaitable, Callable, Dict, Iterator, List, Optional, Union
 from uuid import uuid4
 
+from agno.registry import Registry
 from agno.run.agent import RunOutputEvent
 from agno.run.base import RunContext
 from agno.run.team import TeamRunOutputEvent
@@ -14,6 +15,7 @@ from agno.run.workflow import (
 )
 from agno.session.workflow import WorkflowSession
 from agno.utils.log import log_debug, logger
+from agno.workflow.cel import CEL_AVAILABLE, evaluate_cel_condition_evaluator, is_cel_expression
 from agno.workflow.step import Step
 from agno.workflow.types import StepInput, StepOutput, StepType
 
@@ -43,13 +45,33 @@ class Condition:
     If the condition evaluates to True, the `steps` are executed.
     If the condition evaluates to False and `else_steps` is provided (and not empty),
     the `else_steps` are executed instead.
+
+    The evaluator can be:
+        - A callable function that returns bool
+        - A boolean literal (True/False)
+        - A CEL (Common Expression Language) expression string
+
+    CEL expressions have access to these variables:
+        - input: The workflow input as a string
+        - previous_step_content: Content from the previous step
+        - previous_step_outputs: Map of step name to content string from all previous steps
+        - additional_data: Map of additional data passed to the workflow
+        - session_state: Map of session state values
+
+    Example CEL expressions:
+        - 'input.contains("urgent")'
+        - 'session_state.retry_count < 3'
+        - 'additional_data.priority > 5'
+        - 'previous_step_outputs.research.contains("error")'
     """
 
     # Evaluator should only return boolean
+    # Can be a callable, a bool, or a CEL expression string
     evaluator: Union[
         Callable[[StepInput], bool],
         Callable[[StepInput], Awaitable[bool]],
         bool,
+        str,  # CEL expression
     ]
     steps: WorkflowSteps
 
@@ -59,6 +81,89 @@ class Condition:
     name: Optional[str] = None
     description: Optional[str] = None
 
+    def to_dict(self) -> Dict[str, Any]:
+        result: Dict[str, Any] = {
+            "type": "Condition",
+            "name": self.name,
+            "description": self.description,
+            "steps": [step.to_dict() for step in self.steps if hasattr(step, "to_dict")],
+            "else_steps": [step.to_dict() for step in (self.else_steps or []) if hasattr(step, "to_dict")],
+        }
+        if callable(self.evaluator):
+            result["evaluator"] = self.evaluator.__name__
+            result["evaluator_type"] = "function"
+        elif isinstance(self.evaluator, bool):
+            result["evaluator"] = self.evaluator
+            result["evaluator_type"] = "bool"
+        elif isinstance(self.evaluator, str):
+            # CEL expression string
+            result["evaluator"] = self.evaluator
+            result["evaluator_type"] = "cel"
+        else:
+            raise ValueError(f"Invalid evaluator type: {type(self.evaluator).__name__}")
+
+        return result
+
+    @classmethod
+    def from_dict(
+        cls,
+        data: Dict[str, Any],
+        registry: Optional["Registry"] = None,
+        db: Optional[Any] = None,
+        links: Optional[List[Dict[str, Any]]] = None,
+    ) -> "Condition":
+        from agno.workflow.loop import Loop
+        from agno.workflow.parallel import Parallel
+        from agno.workflow.router import Router
+        from agno.workflow.steps import Steps
+
+        def deserialize_step(step_data: Dict[str, Any]) -> Any:
+            step_type = step_data.get("type", "Step")
+            if step_type == "Loop":
+                return Loop.from_dict(step_data, registry=registry, db=db, links=links)
+            elif step_type == "Parallel":
+                return Parallel.from_dict(step_data, registry=registry, db=db, links=links)
+            elif step_type == "Steps":
+                return Steps.from_dict(step_data, registry=registry, db=db, links=links)
+            elif step_type == "Condition":
+                return cls.from_dict(step_data, registry=registry, db=db, links=links)
+            elif step_type == "Router":
+                return Router.from_dict(step_data, registry=registry, db=db, links=links)
+            else:
+                return Step.from_dict(step_data, registry=registry, db=db, links=links)
+
+        evaluator_data = data.get("evaluator", True)
+        evaluator_type = data.get("evaluator_type")
+        evaluator: Union[Callable[[StepInput], bool], Callable[[StepInput], Awaitable[bool]], bool, str]
+
+        if isinstance(evaluator_data, bool):
+            evaluator = evaluator_data
+        elif isinstance(evaluator_data, str):
+            # Determine if this is a CEL expression or a function name
+            # Use evaluator_type if provided, otherwise detect
+            if evaluator_type == "cel" or (evaluator_type is None and is_cel_expression(evaluator_data)):
+                # CEL expression - use as-is
+                evaluator = evaluator_data
+            else:
+                # Function name - look up in registry
+                if registry:
+                    func = registry.get_function(evaluator_data)
+                    if func is None:
+                        raise ValueError(f"Evaluator function '{evaluator_data}' not found in registry")
+                    evaluator = func
+                else:
+                    raise ValueError(f"Registry required to deserialize evaluator function '{evaluator_data}'")
+        else:
+            raise ValueError(f"Invalid evaluator type in data: {type(evaluator_data).__name__}")
+
+        return cls(
+            evaluator=evaluator,
+            steps=[deserialize_step(step) for step in data.get("steps", [])],
+            else_steps=[deserialize_step(step) for step in data.get("else_steps", [])],
+            name=data.get("name"),
+            description=data.get("description"),
+        )
+
     def _prepare_steps(self):
         """Prepare the steps for execution - mirrors workflow logic"""
         from agno.agent.agent import Agent
@@ -132,10 +237,29 @@ class Condition:
         )
 
     def _evaluate_condition(self, step_input: StepInput, session_state: Optional[Dict[str, Any]] = None) -> bool:
-        """Evaluate the condition and return boolean result"""
+        """Evaluate the condition and return boolean result.
+
+        Supports:
+            - Boolean literals (True/False)
+            - Callable functions
+            - CEL expression strings
+        """
         if isinstance(self.evaluator, bool):
             return self.evaluator
 
+        if isinstance(self.evaluator, str):
+            # CEL expression
+            if not CEL_AVAILABLE:
+                logger.error(
+                    "CEL expression used but cel-python is not installed. Install with: pip install cel-python"
+                )
+                return False
+            try:
+                return evaluate_cel_condition_evaluator(self.evaluator, step_input, session_state)
+            except Exception as e:
+                logger.error(f"CEL expression evaluation failed: {e}")
+                return False
+
         if callable(self.evaluator):
             if session_state is not None and self._evaluator_has_session_state_param():
                 result = self.evaluator(step_input, session_state=session_state)  # type: ignore[call-arg]
@@ -151,10 +275,29 @@ class Condition:
         return False
 
     async def _aevaluate_condition(self, step_input: StepInput, session_state: Optional[Dict[str, Any]] = None) -> bool:
-        """Async version of condition evaluation"""
+        """Async version of condition evaluation.
+
+        Supports:
+            - Boolean literals (True/False)
+            - Callable functions (sync and async)
+            - CEL expression strings
+        """
         if isinstance(self.evaluator, bool):
             return self.evaluator
 
+        if isinstance(self.evaluator, str):
+            # CEL expression - CEL evaluation is synchronous
+            if not CEL_AVAILABLE:
+                logger.error(
+                    "CEL expression used but cel-python is not installed. Install with: pip install cel-python"
+                )
+                return False
+            try:
+                return evaluate_cel_condition_evaluator(self.evaluator, step_input, session_state)
+            except Exception as e:
+                logger.error(f"CEL expression evaluation failed: {e}")
+                return False
+
         if callable(self.evaluator):
             has_session_state = session_state is not None and self._evaluator_has_session_state_param()