ag2 0.10.2__py3-none-any.whl

autogen/agentchat/group/guardrails.py

@@ -0,0 +1,179 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import json
+import re
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ...oai.client import OpenAIWrapper
+
+if TYPE_CHECKING:
+    from ...llm_config import LLMConfig
+    from .targets.transition_target import TransitionTarget
+
+
+class Guardrail(ABC):
+    """Abstract base class for guardrails."""
+
+    def __init__(
+        self, name: str, condition: str, target: "TransitionTarget", activation_message: str | None = None
+    ) -> None:
+        self.name = name
+        self.condition = condition
+        self.target = target
+        self.activation_message = (
+            activation_message if activation_message else f"Guardrail '{name}' has been activated."
+        )
+
+    @abstractmethod
+    def check(
+        self,
+        context: str | list[dict[str, Any]],
+    ) -> "GuardrailResult":
+        """Checks the text against the guardrail and returns a GuardrailResult.
+
+        Args:
+            context (Union[str, list[dict[str, Any]]]): The context to check against the guardrail.
+
+        Returns:
+            GuardrailResult: The result of the guardrail check.
+        """
+        pass
+
+
+class LLMGuardrail(Guardrail):
+    """Guardrail that uses an LLM to check the context."""
+
+    def __init__(
+        self,
+        name: str,
+        condition: str,
+        target: "TransitionTarget",
+        llm_config: "LLMConfig",
+        activation_message: str | None = None,
+    ) -> None:
+        super().__init__(name, condition, target, activation_message)
+
+        if not llm_config:
+            raise ValueError("LLMConfig is required.")
+
+        self.llm_config = llm_config.deepcopy()
+        setattr(self.llm_config, "response_format", GuardrailResult)
+        self.client = OpenAIWrapper(**self.llm_config.model_dump())
+
+        self.check_prompt = f"""You are a guardrail that checks if a condition is met in the conversation you are given.
+You will activate the guardrail only if the condition is met.
+
+**Condition: {self.condition}**"""
+
+    def check(
+        self,
+        context: str | list[dict[str, Any]],
+    ) -> "GuardrailResult":
+        """Checks the context against the guardrail using an LLM.
+
+        Args:
+            context (Union[str, list[dict[str, Any]]]): The context to check against the guardrail.
+
+        Returns:
+            GuardrailResult: The result of the guardrail check.
+        """
+        # Set the check prompt as the system message
+        check_messages = [{"role": "system", "content": self.check_prompt}]
+        # If context is a string, wrap it in a user message and append it
+        if isinstance(context, str):
+            check_messages.append({"role": "user", "content": context})
+        # If context is a list of messages, append them
+        elif isinstance(context, list):
+            check_messages.extend(context)
+        else:
+            raise ValueError("Context must be a string or a list of messages.")
+        # Call the LLM with the check messages
+        response = self.client.create(messages=check_messages)
+        return GuardrailResult.parse(response.choices[0].message.content, guardrail=self)  # type: ignore
+
+
+class RegexGuardrail(Guardrail):
+    """Guardrail that checks the context against a regular expression."""
+
+    def __init__(
+        self,
+        name: str,
+        condition: str,
+        target: "TransitionTarget",
+        activation_message: str | None = None,
+    ) -> None:
+        super().__init__(name, condition, target, activation_message)
+        # Compile the regular expression condition
+        try:
+            self.regex = re.compile(condition)
+        except re.error as e:
+            raise ValueError(f"Invalid regex pattern '{condition}': {str(e)}")
+
+    def check(
+        self,
+        context: str | list[dict[str, Any]],
+    ) -> "GuardrailResult":
+        """Checks the context against the guardrail using a regular expression.
+
+        Args:
+            context (Union[str, list[dict[str, Any]]]): The context to check against the guardrail.
+
+        Returns:
+            GuardrailResult: The result of the guardrail check.
+        """
+        # Create a list of the messages to check
+        if isinstance(context, str):
+            messages = [context]
+        elif isinstance(context, list):
+            messages = [message.get("content", "") for message in context]
+        else:
+            raise ValueError("Context must be a string or a list of messages.")
+
+        # Check each message against the regex
+        for message in messages:
+            match = self.regex.search(message)
+            # If a match is found, activate the guardrail and return the result
+            if match:
+                activated = True
+                justification = f"Match found -> {match.group(0)}"
+                return GuardrailResult(activated=activated, justification=justification, guardrail=self)
+        return GuardrailResult(activated=False, justification="No match found in the context.", guardrail=self)
+
+
+class GuardrailResult(BaseModel):
+    """Represents the outcome of a guardrail check."""
+
+    activated: bool
+    guardrail: Guardrail
+    justification: str = Field(default="No justification provided")
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def __str__(self) -> str:
+        return f"Guardrail Result: {self.activated}\nJustification: {self.justification}"
+
+    @property
+    def reply(self) -> str:
+        return f"{self.guardrail.activation_message}\nJustification: {self.justification}"
+
+    @staticmethod
+    def parse(text: str, guardrail: "Guardrail") -> "GuardrailResult":
+        """Parses a JSON string into a GuardrailResult object.
+
+        Args:
+            text (str): The JSON string to parse.
+            guardrail (Guardrail): The guardrail that the result is for.
+
+        Returns:
+            GuardrailResult: The parsed GuardrailResult object.
+        """
+        try:
+            data = json.loads(text)
+            return GuardrailResult(**data, guardrail=guardrail)
+        except (json.JSONDecodeError, ValueError) as e:
+            raise ValueError(f"Failed to parse GuardrailResult from text: {text}") from e

autogen/agentchat/group/handoffs.py

@@ -0,0 +1,303 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import overload
+
+from pydantic import BaseModel, Field
+
+from .on_condition import OnCondition
+from .on_context_condition import OnContextCondition
+from .targets.transition_target import TransitionTarget
+
+__all__ = ["Handoffs"]
+
+
+class Handoffs(BaseModel):
+    """Container for all handoff transition conditions of a ConversableAgent.\n
+    \n
+        Three types of conditions can be added, each with a different order and time of use:\n
+        1. OnContextConditions (evaluated without an LLM)\n
+        2. OnConditions (evaluated with an LLM)\n
+        3. After work TransitionTarget (if no other transition is triggered)\n
+    \n
+        Supports method chaining:\n
+        agent.handoffs.add_context_conditions([condition1])\n
+                       .add_llm_condition(condition2)\n
+                       .set_after_work(after_work)\n
+    """
+
+    context_conditions: list[OnContextCondition] = Field(default_factory=list)
+    llm_conditions: list[OnCondition] = Field(default_factory=list)
+    after_works: list[OnContextCondition] = Field(default_factory=list)
+
+    def add_context_condition(self, condition: OnContextCondition) -> "Handoffs":
+        """Add a single context condition.
+
+        Args:
+            condition: The OnContextCondition to add
+
+        Returns:
+            Self for method chaining
+        """
+        # Validate that it is an OnContextCondition
+        if not isinstance(condition, OnContextCondition):
+            raise TypeError(f"Expected an OnContextCondition instance, got {type(condition).__name__}")
+
+        self.context_conditions.append(condition)
+        return self
+
+    def add_context_conditions(self, conditions: list[OnContextCondition]) -> "Handoffs":
+        """Add multiple context conditions.
+
+        Args:
+            conditions: List of OnContextConditions to add
+
+        Returns:
+            Self for method chaining
+        """
+        # Validate that it is a list of OnContextConditions
+        if not all(isinstance(condition, OnContextCondition) for condition in conditions):
+            raise TypeError("All conditions must be of type OnContextCondition")
+
+        self.context_conditions.extend(conditions)
+        return self
+
+    def add_llm_condition(self, condition: OnCondition) -> "Handoffs":
+        """Add a single LLM condition.
+
+        Args:
+            condition: The OnCondition to add
+
+        Returns:
+            Self for method chaining
+        """
+        # Validate that it is an OnCondition
+        if not isinstance(condition, OnCondition):
+            raise TypeError(f"Expected an OnCondition instance, got {type(condition).__name__}")
+
+        self.llm_conditions.append(condition)
+        return self
+
+    def add_llm_conditions(self, conditions: list[OnCondition]) -> "Handoffs":
+        """Add multiple LLM conditions.
+
+        Args:
+            conditions: List of OnConditions to add
+
+        Returns:
+            Self for method chaining
+        """
+        # Validate that it is a list of OnConditions
+        if not all(isinstance(condition, OnCondition) for condition in conditions):
+            raise TypeError("All conditions must be of type OnCondition")
+
+        self.llm_conditions.extend(conditions)
+        return self
+
+    def set_after_work(self, target: TransitionTarget) -> "Handoffs":
+        """Set the after work target (replaces all after_works with single entry).
+
+        For backward compatibility, this creates an OnContextCondition with no condition (always true).
+
+        Args:
+            target: The after work TransitionTarget to set
+
+        Returns:
+            Self for method chaining
+        """
+        if not isinstance(target, TransitionTarget):
+            raise TypeError(f"Expected a TransitionTarget instance, got {type(target).__name__}")
+
+        # Create OnContextCondition with no condition (always true)
+        after_work_condition = OnContextCondition(target=target, condition=None)
+        self.after_works = [after_work_condition]
+        return self
+
+    def add_after_work(self, condition: OnContextCondition) -> "Handoffs":
+        """Add a single after-work condition.
+
+        If the condition has condition=None, it will replace any existing
+        condition=None entry and be placed at the end.
+
+        Args:
+            condition: The OnContextCondition to add
+
+        Returns:
+            Self for method chaining
+        """
+        if not isinstance(condition, OnContextCondition):
+            raise TypeError(f"Expected an OnContextCondition instance, got {type(condition).__name__}")
+
+        if condition.condition is None:
+            # Remove any existing condition=None entries
+            self.after_works = [c for c in self.after_works if c.condition is not None]
+            # Add the new one at the end
+            self.after_works.append(condition)
+        else:
+            # For regular conditions, check if we need to move condition=None to the end
+            none_conditions = [c for c in self.after_works if c.condition is None]
+            if none_conditions:
+                # Remove the None condition temporarily
+                self.after_works = [c for c in self.after_works if c.condition is not None]
+                # Add the new regular condition
+                self.after_works.append(condition)
+                # Re-add the None condition at the end
+                self.after_works.append(none_conditions[0])
+            else:
+                # No None condition exists, just append
+                self.after_works.append(condition)
+
+        return self
+
+    def add_after_works(self, conditions: list[OnContextCondition]) -> "Handoffs":
+        """Add multiple after-work conditions.
+
+        Special handling for condition=None entries:
+        - Only one condition=None entry is allowed (the fallback)
+        - It will always be placed at the end of the list
+        - If multiple condition=None entries are provided, only the last one is kept
+
+        Args:
+            conditions: List of OnContextConditions to add
+
+        Returns:
+            Self for method chaining
+        """
+        # Validate that it is a list of OnContextConditions
+        if not all(isinstance(condition, OnContextCondition) for condition in conditions):
+            raise TypeError("All conditions must be of type OnContextCondition")
+
+        # Separate conditions with None and without None
+        none_conditions = [c for c in conditions if c.condition is None]
+        regular_conditions = [c for c in conditions if c.condition is not None]
+
+        # Remove any existing condition=None entries
+        self.after_works = [c for c in self.after_works if c.condition is not None]
+
+        # Add regular conditions
+        self.after_works.extend(regular_conditions)
+
+        # Add at most one None condition at the end
+        if none_conditions:
+            self.after_works.append(none_conditions[-1])  # Use the last one if multiple provided
+
+        return self
+
+    @overload
+    def add(self, condition: OnContextCondition) -> "Handoffs": ...
+
+    @overload
+    def add(self, condition: OnCondition) -> "Handoffs": ...
+
+    def add(self, condition: OnContextCondition | OnCondition) -> "Handoffs":
+        """Add a single condition (OnContextCondition or OnCondition).
+
+        Args:
+            condition: The condition to add (OnContextCondition or OnCondition)
+
+        Raises:
+            TypeError: If the condition type is not supported
+
+        Returns:
+            Self for method chaining
+        """
+        # This add method is a helper method designed to make it easier for
+        # adding handoffs without worrying about the specific type.
+        if isinstance(condition, OnContextCondition):
+            return self.add_context_condition(condition)
+        elif isinstance(condition, OnCondition):
+            return self.add_llm_condition(condition)
+        else:
+            raise TypeError(f"Unsupported condition type: {type(condition).__name__}")
+
+    def add_many(self, conditions: list[OnContextCondition | OnCondition]) -> "Handoffs":
+        """Add multiple conditions of any supported types (OnContextCondition and OnCondition).
+
+        Args:
+            conditions: List of conditions to add
+
+        Raises:
+            TypeError: If an unsupported condition type is provided
+
+        Returns:
+            Self for method chaining
+        """
+        # This add_many method is a helper method designed to make it easier for
+        # adding handoffs without worrying about the specific type.
+        context_conditions = []
+        llm_conditions = []
+
+        for condition in conditions:
+            if isinstance(condition, OnContextCondition):
+                context_conditions.append(condition)
+            elif isinstance(condition, OnCondition):
+                llm_conditions.append(condition)
+            else:
+                raise TypeError(f"Unsupported condition type: {type(condition).__name__}")
+
+        if context_conditions:
+            self.add_context_conditions(context_conditions)
+        if llm_conditions:
+            self.add_llm_conditions(llm_conditions)
+
+        return self
+
+    def clear(self) -> "Handoffs":
+        """Clear all handoff conditions.
+
+        Returns:
+            Self for method chaining
+        """
+        self.context_conditions.clear()
+        self.llm_conditions.clear()
+        self.after_works.clear()
+        return self
+
+    def get_llm_conditions_by_target_type(self, target_type: type) -> list[OnCondition]:
+        """Get OnConditions for a specific target type.
+
+        Args:
+            target_type: The type of condition to retrieve
+
+        Returns:
+            List of conditions of the specified type, or None if none exist
+        """
+        return [on_condition for on_condition in self.llm_conditions if on_condition.has_target_type(target_type)]
+
+    def get_context_conditions_by_target_type(self, target_type: type) -> list[OnContextCondition]:
+        """Get OnContextConditions for a specific target type.
+
+        Args:
+            target_type: The type of condition to retrieve
+
+        Returns:
+            List of conditions of the specified type, or None if none exist
+        """
+        return [
+            on_context_condition
+            for on_context_condition in self.context_conditions
+            if on_context_condition.has_target_type(target_type)
+        ]
+
+    def get_llm_conditions_requiring_wrapping(self) -> list[OnCondition]:
+        """Get LLM conditions that have targets that require wrapping.
+
+        Returns:
+            List of LLM conditions that require wrapping
+        """
+        return [condition for condition in self.llm_conditions if condition.target_requires_wrapping()]
+
+    def get_context_conditions_requiring_wrapping(self) -> list[OnContextCondition]:
+        """Get context conditions that have targets that require wrapping.
+
+        Returns:
+            List of context conditions that require wrapping
+        """
+        return [condition for condition in self.context_conditions if condition.target_requires_wrapping()]
+
+    def set_llm_function_names(self) -> None:
+        """Set the LLM function names for all LLM conditions, creating unique names for each function."""
+        for i, condition in enumerate(self.llm_conditions):
+            # Function names are made unique and allow multiple OnCondition's to the same agent
+            condition.llm_function_name = f"transfer_to_{condition.target.normalized_name()}_{i + 1}"

autogen/agentchat/group/llm_condition.py

@@ -0,0 +1,93 @@
+# 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_str import ContextStr
+
+if TYPE_CHECKING:
+    # Avoid circular import
+    from ..conversable_agent import ConversableAgent
+
+__all__ = ["ContextStrLLMCondition", "LLMCondition", "StringLLMCondition"]
+
+
+class LLMCondition(BaseModel):
+    """Protocol for conditions evaluated by an LLM."""
+
+    def get_prompt(self, agent: "ConversableAgent", messages: list[dict[str, Any]]) -> str:
+        """Get the prompt text for LLM evaluation.
+
+        Args:
+            agent: The agent evaluating the condition
+            messages: The conversation history
+
+        Returns:
+            The prompt text to be evaluated by the LLM
+        """
+        raise NotImplementedError("Requires subclasses to implement.")
+
+
+class StringLLMCondition(LLMCondition):
+    """Simple string-based LLM condition.
+
+    This condition provides a static string prompt to be evaluated by an LLM.
+    """
+
+    prompt: str
+
+    def __init__(self, prompt: str, **data: Any) -> None:
+        """Initialize with a prompt string as a positional parameter.
+
+        Args:
+            prompt: The static prompt string to evaluate
+            data: Additional data for the parent class
+        """
+        super().__init__(prompt=prompt, **data)
+
+    def get_prompt(self, agent: "ConversableAgent", messages: list[dict[str, Any]]) -> str:
+        """Return the static prompt string.
+
+        Args:
+            agent: The agent evaluating the condition (not used)
+            messages: The conversation history (not used)
+
+        Returns:
+            The static prompt string
+        """
+        return self.prompt
+
+
+class ContextStrLLMCondition(LLMCondition):
+    """Context variable-based LLM condition.
+
+    This condition uses a ContextStr object with context variable placeholders that
+    will be substituted before being evaluated by an LLM.
+    """
+
+    context_str: ContextStr
+
+    def __init__(self, context_str: ContextStr, **data: Any) -> None:
+        """Initialize with a context string as a positional parameter.
+
+        Args:
+            context_str: The ContextStr object with variable placeholders
+            data: Additional data for the parent class
+        """
+        super().__init__(context_str=context_str, **data)
+
+    def get_prompt(self, agent: "ConversableAgent", messages: list[dict[str, Any]]) -> str:
+        """Return the prompt with context variables substituted.
+
+        Args:
+            agent: The agent evaluating the condition (provides context variables)
+            messages: The conversation history (not used)
+
+        Returns:
+            The prompt with context variables substituted
+        """
+        result = self.context_str.format(agent.context_variables)
+        return result if result is not None else ""