ag2 0.9.1__py3-none-any.whl → 0.9.1.post0__py3-none-any.whl

autogen/agentchat/group/__init__.py

@@ -0,0 +1,64 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+__all__: list[str] = []
+
+from .available_condition import ExpressionAvailableCondition, StringAvailableCondition
+from .context_condition import ExpressionContextCondition, StringContextCondition
+from .context_expression import ContextExpression
+from .context_str import ContextStr
+from .context_variables import ContextVariables
+from .handoffs import Handoffs
+from .llm_condition import ContextStrLLMCondition, StringLLMCondition
+from .on_condition import OnCondition
+from .on_context_condition import OnContextCondition
+from .reply_result import ReplyResult
+from .speaker_selection_result import SpeakerSelectionResult
+from .targets.group_chat_target import GroupChatConfig, GroupChatTarget
+
+"""
+from .targets.group_manager_target import (
+    GroupManagerSelectionMessageContextStr,
+    GroupManagerSelectionMessageString,
+    GroupManagerTarget,
+)
+"""
+from .targets.transition_target import (
+    AgentNameTarget,
+    AgentTarget,
+    AskUserTarget,
+    NestedChatTarget,
+    RevertToUserTarget,
+    StayTarget,
+    TerminateTarget,
+)
+
+__all__ = [
+    "AgentNameTarget",
+    "AgentTarget",
+    "AskUserTarget",
+    "ContextExpression",
+    "ContextStr",
+    "ContextStrLLMCondition",
+    "ContextVariables",
+    "ExpressionAvailableCondition",
+    "ExpressionContextCondition",
+    "GroupChatConfig",
+    "GroupChatTarget",
+    # "GroupManagerSelectionMessageContextStr",
+    # "GroupManagerSelectionMessageString",
+    # "GroupManagerTarget",
+    "Handoffs",
+    "NestedChatTarget",
+    "OnCondition",
+    "OnContextCondition",
+    "ReplyResult",
+    "RevertToUserTarget",
+    "SpeakerSelectionResult",
+    "StayTarget",
+    "StringAvailableCondition",
+    "StringContextCondition",
+    "StringLLMCondition",
+    "TerminateTarget",
+]

autogen/agentchat/group/available_condition.py

@@ -0,0 +1,91 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
+
+from .context_expression import ContextExpression
+
+if TYPE_CHECKING:
+    # Avoid circular import
+    from ..conversable_agent import ConversableAgent
+
+__all__ = ["AvailableCondition", "ExpressionAvailableCondition", "StringAvailableCondition"]
+
+
+class AvailableCondition(BaseModel):
+    """Protocol for determining if a condition is available to be evaluated."""
+
+    def is_available(self, agent: "ConversableAgent", messages: list[dict[str, Any]]) -> bool:
+        """Determine if the condition should be considered for evaluation.
+
+        Args:
+            agent: The agent evaluating the condition
+            messages: The conversation history
+
+        Returns:
+            True if the condition should be evaluated, False otherwise
+        """
+        raise NotImplementedError("Requires subclasses to implement.")
+
+
+class StringAvailableCondition(AvailableCondition):
+    """String-based available condition.
+
+    This condition checks if a named context variable exists and is truthy.
+    """
+
+    context_variable: str
+
+    def __init__(self, context_variable: str, **data: Any) -> None:
+        """Initialize with a context variable name as a positional parameter.
+
+        Args:
+            context_variable: The name of the context variable to check
+            data: Additional data for the parent class
+        """
+        super().__init__(context_variable=context_variable, **data)
+
+    def is_available(self, agent: "ConversableAgent", messages: list[dict[str, Any]]) -> bool:
+        """Check if the named context variable is truthy.
+
+        Args:
+            agent: The agent with context variables
+            messages: The conversation history (not used)
+
+        Returns:
+            True if the variable exists and is truthy, False otherwise
+        """
+        return bool(agent.context_variables.get(self.context_variable, False))
+
+
+class ExpressionAvailableCondition(AvailableCondition):
+    """Expression-based available condition.
+
+    This condition evaluates a ContextExpression against the context variables.
+    """
+
+    expression: ContextExpression
+
+    def __init__(self, expression: ContextExpression, **data: Any) -> None:
+        """Initialize with an expression as a positional parameter.
+
+        Args:
+            expression: The context expression to evaluate
+            data: Additional data for the parent class
+        """
+        super().__init__(expression=expression, **data)
+
+    def is_available(self, agent: "ConversableAgent", messages: list[dict[str, Any]]) -> bool:
+        """Evaluate the expression against the context variables.
+
+        Args:
+            agent: The agent with context variables
+            messages: The conversation history (not used)
+
+        Returns:
+            Boolean result of the expression evaluation
+        """
+        return self.expression.evaluate(agent.context_variables)

autogen/agentchat/group/context_condition.py

@@ -0,0 +1,77 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+from typing import Any
+
+from pydantic import BaseModel
+
+from .context_expression import ContextExpression
+from .context_variables import ContextVariables
+
+__all__ = ["ContextCondition", "ExpressionContextCondition", "StringContextCondition"]
+
+
+class ContextCondition(BaseModel):
+    """Protocol for conditions evaluated directly using context variables."""
+
+    def evaluate(self, context_variables: ContextVariables) -> bool:
+        """Evaluate the condition to a boolean result.
+
+        Args:
+            context_variables: The context variables to evaluate against
+
+        Returns:
+            Boolean result of the condition evaluation
+        """
+        raise NotImplementedError("Requires subclasses to implement.")
+
+
+class StringContextCondition(ContextCondition):
+    """Simple string-based context condition.
+
+    This condition checks if a named context variable exists and is truthy.
+    """
+
+    variable_name: str
+
+    def evaluate(self, context_variables: ContextVariables) -> bool:
+        """Check if the named context variable is truthy.
+
+        Args:
+            context_variables: The context variables to check against
+
+        Returns:
+            True if the variable exists and is truthy, False otherwise
+        """
+        return bool(context_variables.get(self.variable_name, False))
+
+
+class ExpressionContextCondition(ContextCondition):
+    """Complex expression-based context condition.
+
+    This condition evaluates a ContextExpression against the context variables.
+    """
+
+    expression: ContextExpression
+
+    def __init__(self, expression: ContextExpression, **data: Any) -> None:
+        """Initialize with an expression as a positional parameter.
+
+        Args:
+            expression: The context expression to evaluate
+            data: Additional data for the parent class
+        """
+        super().__init__(expression=expression, **data)
+
+    def evaluate(self, context_variables: ContextVariables) -> bool:
+        """Evaluate the expression against the context variables.
+
+        Args:
+            context_variables: The context variables to evaluate against
+
+        Returns:
+            Boolean result of the expression evaluation
+        """
+        return self.expression.evaluate(context_variables)

autogen/agentchat/group/context_expression.py

@@ -0,0 +1,238 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import ast
+import re
+from dataclasses import dataclass
+
+from ...doc_utils import export_module
+from .context_variables import ContextVariables
+
+
+@dataclass
+@export_module("autogen")
+class ContextExpression:
+    """A class to evaluate logical expressions using context variables.
+
+    Args:
+        expression (str): A string containing a logical expression with context variable references.
+            - Variable references use ${var_name} syntax: ${logged_in}, ${attempts}
+            - String literals can use normal quotes: 'hello', "world"
+            - Supported operators:
+                - Logical: not/!, and/&, or/|
+                - Comparison: >, <, >=, <=, ==, !=
+            - Supported functions:
+                - len(${var_name}): Gets the length of a list, string, or other collection
+            - Parentheses can be used for grouping
+            - Examples:
+                - "not ${logged_in} and ${is_admin} or ${guest_checkout}"
+                - "!${logged_in} & ${is_admin} | ${guest_checkout}"
+                - "len(${orders}) > 0 & ${user_active}"
+                - "len(${cart_items}) == 0 | ${checkout_started}"
+
+    Raises:
+        SyntaxError: If the expression cannot be parsed
+        ValueError: If the expression contains disallowed operations
+    """
+
+    expression: str
+
+    def __post_init__(self) -> None:
+        # Validate the expression immediately upon creation
+        try:
+            # Extract variable references and replace with placeholders
+            self._variable_names = self._extract_variable_names(self.expression)
+
+            # Convert symbolic operators to Python keywords
+            python_expr = self._convert_to_python_syntax(self.expression)
+
+            # Sanitize for AST parsing
+            sanitized_expr = self._prepare_for_ast(python_expr)
+
+            # Use ast to parse and validate the expression
+            self._ast = ast.parse(sanitized_expr, mode="eval")
+
+            # Verify it only contains allowed operations
+            self._validate_operations(self._ast.body)
+
+            # Store the Python-syntax version for evaluation
+            self._python_expr = python_expr
+
+        except SyntaxError as e:
+            raise SyntaxError(f"Invalid expression syntax in '{self.expression}': {str(e)}")
+        except Exception as e:
+            raise ValueError(f"Error validating expression '{self.expression}': {str(e)}")
+
+    def _extract_variable_names(self, expr: str) -> list[str]:
+        """Extract all variable references ${var_name} from the expression."""
+        # Find all patterns like ${var_name}
+        matches = re.findall(r"\${([^}]*)}", expr)
+        return matches
+
+    def _convert_to_python_syntax(self, expr: str) -> str:
+        """Convert symbolic operators to Python keywords."""
+        # We need to be careful about operators inside string literals
+        # First, temporarily replace string literals with placeholders
+        string_literals = []
+
+        def replace_string_literal(match: re.Match[str]) -> str:
+            string_literals.append(match.group(0))
+            return f"__STRING_LITERAL_{len(string_literals) - 1}__"
+
+        # Replace both single and double quoted strings
+        expr_without_strings = re.sub(r"'[^']*'|\"[^\"]*\"", replace_string_literal, expr)
+
+        # Handle the NOT operator (!) - no parentheses handling needed
+        # Replace standalone ! before variables or expressions
+        expr_without_strings = re.sub(r"!\s*(\${|\()", "not \\1", expr_without_strings)
+
+        # Handle AND and OR operators - simpler approach without parentheses handling
+        expr_without_strings = re.sub(r"\s+&\s+", " and ", expr_without_strings)
+        expr_without_strings = re.sub(r"\s+\|\s+", " or ", expr_without_strings)
+
+        # Now put string literals back
+        for i, literal in enumerate(string_literals):
+            expr_without_strings = expr_without_strings.replace(f"__STRING_LITERAL_{i}__", literal)
+
+        return expr_without_strings
+
+    def _prepare_for_ast(self, expr: str) -> str:
+        """Convert the expression to valid Python for AST parsing by replacing variables with placeholders."""
+        # Replace ${var_name} with var_name for AST parsing
+        processed_expr = expr
+        for var_name in self._variable_names:
+            processed_expr = processed_expr.replace(f"${{{var_name}}}", var_name)
+
+        return processed_expr
+
+    def _validate_operations(self, node: ast.AST) -> None:
+        """Recursively validate that only allowed operations exist in the AST."""
+        allowed_node_types = (
+            # Boolean operations
+            ast.BoolOp,
+            ast.UnaryOp,
+            ast.And,
+            ast.Or,
+            ast.Not,
+            # Comparison operations
+            ast.Compare,
+            ast.Eq,
+            ast.NotEq,
+            ast.Lt,
+            ast.LtE,
+            ast.Gt,
+            ast.GtE,
+            # Basic nodes
+            ast.Name,
+            ast.Load,
+            ast.Constant,
+            ast.Expression,
+            # Support for basic numeric operations in comparisons
+            ast.Num,
+            ast.NameConstant,
+            # Support for negative numbers
+            ast.USub,
+            ast.UnaryOp,
+            # Support for string literals
+            ast.Str,
+            ast.Constant,
+            # Support for function calls (specifically len())
+            ast.Call,
+        )
+
+        if not isinstance(node, allowed_node_types):
+            raise ValueError(f"Operation type {type(node).__name__} is not allowed in logical expressions")
+
+        # Special validation for function calls - only allow len()
+        if isinstance(node, ast.Call):
+            if not (isinstance(node.func, ast.Name) and node.func.id == "len"):
+                raise ValueError(f"Only the len() function is allowed, got: {getattr(node.func, 'id', 'unknown')}")
+            if len(node.args) != 1:
+                raise ValueError(f"len() function must have exactly one argument, got {len(node.args)}")
+
+        # Special validation for Compare nodes
+        if isinstance(node, ast.Compare):
+            for op in node.ops:
+                if not isinstance(op, (ast.Eq, ast.NotEq, ast.Lt, ast.LtE, ast.Gt, ast.GtE)):
+                    raise ValueError(f"Comparison operator {type(op).__name__} is not allowed")
+
+        # Recursively check child nodes
+        for child in ast.iter_child_nodes(node):
+            self._validate_operations(child)
+
+    def evaluate(self, context_variables: ContextVariables) -> bool:
+        """Evaluate the expression using the provided context variables.
+
+        Args:
+            context_variables: Dictionary of context variables to use for evaluation
+
+        Returns:
+            bool: The result of evaluating the expression
+
+        Raises:
+            KeyError: If a variable referenced in the expression is not found in the context
+        """
+        # Create a modified expression that we can safely evaluate
+        eval_expr = self._python_expr  # Use the Python-syntax version
+
+        # First, handle len() functions with variable references inside
+        len_pattern = r"len\(\${([^}]*)}\)"
+        len_matches = list(re.finditer(len_pattern, eval_expr))
+
+        # Process all len() operations first
+        for match in len_matches:
+            var_name = match.group(1)
+            # Check if variable exists in context, raise KeyError if not
+            if not context_variables.contains(var_name):
+                raise KeyError(f"Missing context variable: '{var_name}'")
+
+            var_value = context_variables.get(var_name)
+
+            # Calculate the length - works for lists, strings, dictionaries, etc.
+            try:
+                length_value = len(var_value)  # type: ignore[arg-type]
+            except TypeError:
+                # If the value doesn't support len(), treat as 0
+                length_value = 0
+
+            # Replace the len() expression with the actual length
+            full_match = match.group(0)
+            eval_expr = eval_expr.replace(full_match, str(length_value))
+
+        # Then replace remaining variable references with their values
+        for var_name in self._variable_names:
+            # Skip variables that were already processed in len() expressions
+            if any(m.group(1) == var_name for m in len_matches):
+                continue
+
+            # Check if variable exists in context, raise KeyError if not
+            if not context_variables.contains(var_name):
+                raise KeyError(f"Missing context variable: '{var_name}'")
+
+            # Get the value from context
+            var_value = context_variables.get(var_name)
+
+            # Format the value appropriately based on its type
+            if isinstance(var_value, (bool, int, float)):
+                formatted_value = str(var_value)
+            elif isinstance(var_value, str):
+                formatted_value = f"'{var_value}'"  # Quote strings
+            elif isinstance(var_value, (list, dict, tuple)):
+                # For collections, convert to their boolean evaluation
+                formatted_value = str(bool(var_value))
+            else:
+                formatted_value = str(var_value)
+
+            # Replace the variable reference with the formatted value
+            eval_expr = eval_expr.replace(f"${{{var_name}}}", formatted_value)
+
+        try:
+            return eval(eval_expr)  # type: ignore[no-any-return]
+        except Exception as e:
+            raise ValueError(
+                f"Error evaluating expression '{self.expression}' (are you sure you're using ${{my_context_variable_key}}): {str(e)}"
+            )
+
+    def __str__(self) -> str:
+        return f"ContextExpression('{self.expression}')"

autogen/agentchat/group/context_str.py

@@ -0,0 +1,41 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Optional
+
+from pydantic import BaseModel
+
+from .context_variables import ContextVariables
+
+__all__ = ["ContextStr"]
+
+
+class ContextStr(BaseModel):
+    """A string that requires context variable substitution.
+
+    Use the format method to substitute context variables into the string.
+    """
+
+    """The string to be substituted with context variables. It is expected that the string will contain `{var}` placeholders and that string format will be able to replace all values."""
+    template: str
+
+    def format(self, context_variables: ContextVariables) -> Optional[str]:
+        """Substitute context variables into the string.
+
+        Args:
+            context_variables (ContextVariables): The context variables to substitute into the string.
+
+        Returns:
+            Optional[str]: The formatted string with context variables substituted.
+        """
+
+        context = context_variables.to_dict()
+
+        if not context:
+            return self.template
+
+        return self.template.format(**context)
+
+    def __str__(self) -> str:
+        return f"ContextStr, unformatted: {self.template}"