ag2 0.10.2__py3-none-any.whl

autogen/agentchat/group/__init__.py

@@ -0,0 +1,67 @@
+# 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.function_target import FunctionTarget, FunctionTargetResult
+from .targets.transition_target import (
+    AgentNameTarget,
+    AgentTarget,
+    AskUserTarget,
+    NestedChatTarget,
+    RevertToUserTarget,
+    StayTarget,
+    TerminateTarget,
+)
+
+__all__ = [
+    "AgentNameTarget",
+    "AgentTarget",
+    "AskUserTarget",
+    "ContextExpression",
+    "ContextStr",
+    "ContextStrLLMCondition",
+    "ContextVariables",
+    "ExpressionAvailableCondition",
+    "ExpressionContextCondition",
+    "FunctionTarget",
+    "FunctionTargetResult",
+    "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.\n
+    \n
+        Args:\n
+            expression (str): A string containing a logical expression with context variable references.\n
+                - Variable references use ${var_name} syntax: ${logged_in}, ${attempts}\n
+                - String literals can use normal quotes: 'hello', "world"\n
+                - Supported operators:\n
+                    - Logical: not/!, and/&, or/|\n
+                    - Comparison: >, <, >=, <=, ==, !=\n
+                - Supported functions:\n
+                    - len(${var_name}): Gets the length of a list, string, or other collection\n
+                - Parentheses can be used for grouping\n
+                - Examples:\n
+                    - "not ${logged_in} and ${is_admin} or ${guest_checkout}"\n
+                    - "!${logged_in} & ${is_admin} | ${guest_checkout}"\n
+                    - "len(${orders}) > 0 & ${user_active}"\n
+                    - "len(${cart_items}) == 0 | ${checkout_started}"\n
+    \n
+        Raises:\n
+            SyntaxError: If the expression cannot be parsed\n
+            ValueError: If the expression contains disallowed operations\n
+    """
+
+    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,39 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+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) -> str | None:
+        """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}"

autogen/agentchat/group/context_variables.py

@@ -0,0 +1,182 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from collections.abc import Generator, Iterable
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+__all__ = ["ContextVariables"]
+
+# Parameter name for context variables
+# Use the value in functions and they will be substituted with the context variables:
+# e.g. def my_function(context_variables: ContextVariables, my_other_parameters: Any) -> Any:
+__CONTEXT_VARIABLES_PARAM_NAME__ = "context_variables"
+
+
+class ContextVariables(BaseModel):
+    """Stores and manages context variables for agentic workflows.
+
+    Utilises a dictionary-like interface for setting, getting, and removing variables.
+    """
+
+    # Internal storage for context variables
+    data: dict[str, Any] = Field(default_factory=dict)
+
+    def __init__(self, data: dict[str, Any] | None = None, **kwargs: Any) -> None:
+        """Initialize with data dictionary as an optional positional parameter.
+
+        Args:
+            data: Initial dictionary of context variables (optional)
+            kwargs: Additional keyword arguments for the parent class
+        """
+        init_data = data or {}
+        super().__init__(data=init_data, **kwargs)
+
+    def get(self, key: str, default: Any | None = None) -> Any | None:
+        """Get a value from the context by key.
+
+        Args:
+            key: The key to retrieve
+            default: The default value to return if key is not found
+
+        Returns:
+            The value associated with the key or default if not found
+        """
+        return self.data.get(key, default)
+
+    def set(self, key: str, value: Any) -> None:
+        """Set a value in the context by key.
+
+        Args:
+            key: The key to set
+            value: The value to store
+        """
+        self.data[key] = value
+
+    def remove(self, key: str) -> bool:
+        """Remove a key from the context.
+
+        Args:
+            key: The key to remove
+
+        Returns:
+            True if the key was removed, False if it didn't exist
+        """
+        if key in self.data:
+            del self.data[key]
+            return True
+        return False
+
+    def keys(self) -> Iterable[str]:
+        """Get all keys in the context.
+
+        Returns:
+            An iterable of all keys
+        """
+        return self.data.keys()
+
+    def values(self) -> Iterable[Any]:
+        """Get all values in the context.
+
+        Returns:
+            An iterable of all values
+        """
+        return self.data.values()
+
+    def items(self) -> Iterable[tuple[str, Any]]:
+        """Get all key-value pairs in the context.
+
+        Returns:
+            An iterable of all key-value pairs
+        """
+        return self.data.items()
+
+    def clear(self) -> None:
+        """Clear all keys and values from the context."""
+        self.data.clear()
+
+    def contains(self, key: str) -> bool:
+        """Check if a key exists in the context.
+
+        Args:
+            key: The key to check
+
+        Returns:
+            True if the key exists, False otherwise
+        """
+        return key in self.data
+
+    def update(self, other: dict[str, Any]) -> None:
+        """Update context with key-value pairs from another dictionary.
+
+        Args:
+            other: Dictionary containing key-value pairs to add
+        """
+        self.data.update(other)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert context variables to a dictionary.
+
+        Returns:
+            Dictionary representation of all context variables
+        """
+        return self.data.copy()
+
+    # Dictionary-compatible interface
+    def __getitem__(self, key: str) -> Any:
+        """Get a value using dictionary syntax: context[key]"""
+        try:
+            return self.data[key]
+        except KeyError:
+            raise KeyError(f"Context variable '{key}' not found")
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        """Set a value using dictionary syntax: context[key] = value"""
+        self.data[key] = value
+
+    def __delitem__(self, key: str) -> None:
+        """Delete a key using dictionary syntax: del context[key]"""
+        try:
+            del self.data[key]
+        except KeyError:
+            raise KeyError(f"Cannot delete non-existent context variable '{key}'")
+
+    def __contains__(self, key: str) -> bool:
+        """Check if key exists using 'in' operator: key in context"""
+        return key in self.data
+
+    def __len__(self) -> int:
+        """Get the number of items: len(context)"""
+        return len(self.data)
+
+    def __iter__(self) -> Generator[tuple[str, Any], None, None]:
+        """Iterate over keys: for key in context"""
+        for key in self.data:
+            yield (key, self.data[key])
+
+    def __str__(self) -> str:
+        """String representation of context variables."""
+        return f"ContextVariables({self.data})"
+
+    def __repr__(self) -> str:
+        """Detailed representation of context variables."""
+        return f"ContextVariables(data={self.data!r})"
+
+    # Utility methods
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ContextVariables":
+        """Create a new ContextVariables instance from a dictionary.
+
+        E.g.:
+        my_context = {"user_id": "12345", "settings": {"theme": "dark"}}
+        context = ContextVariables.from_dict(my_context)
+
+        Args:
+            data: Dictionary of key-value pairs
+
+        Returns:
+            New ContextVariables instance
+        """
+        return cls(data=data)