waldiez 0.4.6__py3-none-any.whl → 0.4.8__py3-none-any.whl

waldiez/models/agents/group_manager/group_manager.py

@@ -2,9 +2,10 @@
 # Copyright (c) 2024 - 2025 Waldiez and contributors.
 """Group chat manager agent."""
 
-from typing import List, Literal
+import warnings
+from typing import Literal
 
-from pydantic import Field
+from pydantic import Field, field_validator
 from typing_extensions import Annotated
 
 from ..agent import WaldiezAgent
@@ -21,36 +22,125 @@ class WaldiezGroupManager(WaldiezAgent):
 
     Attributes
     ----------
-    agent_type : Literal["manager"]
-        The agent type: 'manager' for a group manager agent
+    agent_type : Literal["group_manager"]
+        The agent type: 'group_manager' for a group manager agent
     data : WaldiezGroupManagerData
         The group manager agent's data.
 
     Functions
     ---------
-    validate_transitions(agent_ids: List[str])
+    validate_transitions(agent_ids: list[str])
         Validate the transitions.
     """
 
-    agent_type: Annotated[
-        Literal["manager"],
+    agent_type: Annotated[  # pyright: ignore
+        Literal["group_manager", "manager"],
         Field(
             "manager",
             title="Agent type",
-            description="The agent type: 'manager' for a group manager agent",
+            description=(
+                "The agent type: 'group_manager' for a group manager agent"
+            ),
             alias="agentType",
         ),
-    ]
-    data: Annotated[
+    ] = "group_manager"
+    data: Annotated[  # pyright: ignore
         WaldiezGroupManagerData,
         Field(
             title="Data",
             description="The group manager agent's data",
-            default_factory=WaldiezGroupManagerData,
+            default_factory=WaldiezGroupManagerData,  # pyright: ignore
         ),
     ]
 
-    def validate_transitions(self, agent_ids: List[str]) -> None:
+    @field_validator("agent_type", mode="before")
+    @classmethod
+    def validate_agent_type(cls, v: str) -> Literal["group_manager"]:
+        """Validate the agent type.
+
+        The agent type must be `group_manager`.
+        The other two are deprecated and will be removed in the future.
+
+        Parameters
+        ----------
+        v : str
+            The agent type.
+
+        Returns
+        -------
+        str
+            The validated agent type.
+
+        Raises
+        ------
+        ValueError
+            If the agent type is not `group_manager`.
+        """
+        if v in ["groupManager", "manager"]:  # pragma: no cover
+            # Deprecated agent type names
+            warnings.warn(
+                (
+                    "The agent types 'groupManager' and 'manager' are "
+                    "deprecated. Use 'group_manager' instead."
+                ),
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        if v != "group_manager":  # pragma: no cover
+            raise ValueError(
+                "The agent type must be 'group_manager'. "
+                "Use 'group_manager' instead."
+            )
+        return "group_manager"
+
+    def validate_initial_agent_id(self, all_agent_ids: list[str]) -> None:
+        """Validate the initial agent ID.
+
+        The initial agent ID must be in the list of agent IDs.
+
+        Parameters
+        ----------
+        all_agent_ids : list[str]
+            The list of agent IDs.
+
+        Raises
+        ------
+        ValueError
+            If the initial agent ID is not in the list of agent IDs.
+        """
+        initial_agent_id = self.data.initial_agent_id
+        if initial_agent_id not in all_agent_ids:
+            raise ValueError(
+                f"Initial agent ID '{initial_agent_id}' "
+                f"is not in the list of agent IDs: {all_agent_ids}"
+            )
+
+    def get_speakers_order(self) -> list[str]:
+        """Get the order of the speakers.
+
+        Returns
+        -------
+        list[str]
+            The order of the speakers.
+
+        Raises
+        ------
+        RuntimeError
+            If the order is not set.
+        """
+        return self.data.speakers.get_order()
+
+    def set_speakers_order(self, group_members: list[str]) -> None:
+        """Set the order of the speakers.
+
+        Parameters
+        ----------
+        group_members : list[str]
+            The group members' IDs.
+        """
+        self.data.speakers.set_order(self.data.initial_agent_id, group_members)
+
+    def validate_transitions(self, agent_ids: list[str]) -> None:
         """Validate the transitions.
 
         If the selection mode is `transition`:
@@ -62,7 +152,7 @@ class WaldiezGroupManager(WaldiezAgent):
 
         Parameters
         ----------
-        agent_ids : List[str]
+        agent_ids : list[str]
             The list of agent IDs.
 
         Raises

waldiez/models/agents/group_manager/group_manager_data.py

@@ -22,8 +22,8 @@ class WaldiezGroupManagerData(WaldiezAgentData):
     ----------
     human_input_mode : Literal["ALWAYS", "NEVER", "TERMINATE"]
         The human input mode, Defaults to `NEVER`
-    max_round : Optional[int]
-        The maximum number of rounds to have in the group.
+    max_round : int
+        The maximum number of rounds to have in the group. Defaults to 20.
     admin_name : Optional[str]
         The name of the group's admin.
         Make sure you use a name of an agent in the group.
@@ -33,30 +33,34 @@ class WaldiezGroupManagerData(WaldiezAgentData):
         Enable clearing the history in the chat group.
     send_introductions : bool
         Send the group members' introductions.
+    group_name : Optional[str]
+        The name of the group.
+    initial_agent_id: str
+        The ID of the initial agent to be used in the group.
     """
 
     human_input_mode: Annotated[
         Literal["ALWAYS", "NEVER", "TERMINATE"],
         Field(
-            "NEVER",
+            default="NEVER",
             title="Human input mode",
             description="The human input mode, Defaults to `NEVER`",
             alias="humanInputMode",
         ),
-    ]
+    ] = "NEVER"
     max_round: Annotated[
-        Optional[int],
+        int,
         Field(
-            None,
+            default=20,
             title="Max round",
             description="The maximum number of rounds to have in the group.",
             alias="maxRound",
         ),
-    ]
+    ] = 20
     admin_name: Annotated[
         Optional[str],
         Field(
-            None,
+            default=None,
             title="Group Admin name",
             description=(
                 "The name of the group's admin. "
@@ -64,30 +68,48 @@ class WaldiezGroupManagerData(WaldiezAgentData):
             ),
             alias="adminName",
         ),
-    ]
+    ] = None
     speakers: Annotated[
         WaldiezGroupManagerSpeakers,
         Field(
             title="Speakers",
             description="The rules for the speaker selection and repetition",
-            default_factory=WaldiezGroupManagerSpeakers,
+            default_factory=WaldiezGroupManagerSpeakers,  # pyright: ignore
         ),
     ]
     enable_clear_history: Annotated[
         Optional[bool],
         Field(
-            None,
+            default=None,
             title="Enable clear history",
-            description="Enable clearing hte history in the chat group.",
+            description="Enable clearing the history in the chat group.",
             alias="enableClearHistory",
         ),
-    ]
+    ] = None
     send_introductions: Annotated[
         bool,
         Field(
-            False,
+            default=False,
             title="Send Introductions",
             description="Send the group members' introductions.",
             alias="sendIntroductions",
         ),
+    ] = False
+    group_name: Annotated[
+        Optional[str],
+        Field(
+            default=None,
+            title="Group name",
+            description="The name of the group.",
+            alias="groupName",
+        ),
+    ] = None
+    initial_agent_id: Annotated[
+        str,
+        Field(
+            ...,
+            title="Initial agent ID",
+            description="The ID of the agent that starts the conversation.",
+            alias="initialAgentId",
+        ),
     ]

waldiez/models/agents/group_manager/speakers.py

@@ -2,7 +2,7 @@
 # Copyright (c) 2024 - 2025 Waldiez and contributors.
 """Group chat speakers."""
 
-from typing import Dict, List, Optional, Tuple, Union
+from typing import Optional, Union
 
 from pydantic import Field, model_validator
 from typing_extensions import Annotated, Literal, Self
@@ -14,6 +14,7 @@ WaldiezGroupManagerSpeakersSelectionMethod = Literal[
     "manual",
     "random",
     "round_robin",
+    "default",
     "custom",
 ]
 """Possible methods for the speaker selection."""
@@ -66,13 +67,13 @@ class WaldiezGroupManagerSpeakers(WaldiezBase):
         Max retries for selecting a speaker.
     selection_mode : WaldiezGroupManagerSpeakersSelectionMode
         Selection mode.
-    allow_repeat : Union[bool, List[str]]
+    allow_repeat : Union[bool, list[str]]
         Allow repeat.
-    allowed_or_disallowed_transitions : Dict[str, List[str]]
+    allowed_or_disallowed_transitions : dict[str, list[str]]
         Allowed or disallowed transitions.
     transitions_type : WaldiezGroupManagerSpeakersTransitionsType
         The type of transition rules to use if
-        if a mapping (agent => List[agents]) is used:
+        if a mapping (agent => list[agents]) is used:
         `allowed` (default) or `disallowed`
     custom_method_string : Optional[str]
         The custom method string.
@@ -86,16 +87,16 @@ class WaldiezGroupManagerSpeakers(WaldiezBase):
     selection_method: Annotated[
         WaldiezGroupManagerSpeakersSelectionMethod,
         Field(
-            "auto",
+            default="auto",
             title="Selection Method",
             description="The next speaker selection method",
             alias="selectionMethod",
         ),
-    ]
+    ] = "auto"
     selection_custom_method: Annotated[
         Optional[str],
         Field(
-            None,
+            default=None,
             title="Method for custom selection.",
             description=(
                 "If the method for the speaker selection if `custom`"
@@ -108,11 +109,11 @@ class WaldiezGroupManagerSpeakers(WaldiezBase):
             ),
             alias="selectionCustomMethod",
         ),
-    ]
+    ] = None
     max_retries_for_selecting: Annotated[
         Optional[int],
         Field(
-            None,
+            default=None,
             title="Max retries for a selecting",
             description=(
                 "The maximum number of retries for the group manager "
@@ -120,11 +121,11 @@ class WaldiezGroupManagerSpeakers(WaldiezBase):
             ),
             alias="maxRetriesForSelecting",
         ),
-    ]
+    ] = None
     selection_mode: Annotated[
         WaldiezGroupManagerSpeakersSelectionMode,
         Field(
-            "repeat",
+            default="repeat",
             title="Selection Mode",
             description=(
                 "The method to use for selecting a next speaker: "
@@ -133,11 +134,11 @@ class WaldiezGroupManagerSpeakers(WaldiezBase):
             ),
             alias="selectionMode",
         ),
-    ]
+    ] = "repeat"
     allow_repeat: Annotated[
-        Union[bool, List[str]],
+        Union[bool, list[str]],
         Field(
-            True,
+            default=True,
             title="Allow repeat",
             description=(
                 "The speakers' repetition mode: "
@@ -145,34 +146,46 @@ class WaldiezGroupManagerSpeakers(WaldiezBase):
             ),
             alias="allowRepeat",
         ),
-    ]
+    ] = True
     allowed_or_disallowed_transitions: Annotated[
-        Dict[str, List[str]],
+        dict[str, list[str]],
         Field(
             default_factory=dict,
             title="Allowed or disallowed transitions",
             description=(
-                "A mapping (agent.id => List[agent.ids])"
+                "A mapping (agent.id => list[agent.ids])"
                 "with the allowed or disallowed transitions."
             ),
             alias="allowedOrDisallowedTransitions",
         ),
-    ]
+    ] = {}
     transitions_type: Annotated[
         WaldiezGroupManagerSpeakersTransitionsType,
         Field(
-            "allowed",
+            default="allowed",
             title="Transitions type",
             description=(
                 "The type of transition rules to use if "
-                "if a mapping (agent => List[agents]) is used: "
+                "if a mapping (agent => list[agents]) is used: "
                 "`allowed` (default) or `disallowed`"
             ),
             alias="transitionsType",
         ),
-    ]
-
+    ] = "allowed"
+    order: Annotated[
+        list[str],
+        Field(
+            default_factory=list,
+            title="Order",
+            description=(
+                "The order of the speakers in the group "
+                "(if round_robin is used). If empty, the order  "
+                "will be determined by the order of the agents in the flow."
+            ),
+        ),
+    ] = []
     _custom_method_string: Optional[str] = None
+    _order: Optional[list[str]] = None
 
     @property
     def custom_method_string(self) -> Optional[str]:
@@ -189,7 +202,7 @@ class WaldiezGroupManagerSpeakers(WaldiezBase):
         self,
         name_prefix: Optional[str] = None,
         name_suffix: Optional[str] = None,
-    ) -> Tuple[str, str]:
+    ) -> tuple[str, str]:
         """Get the custom method function.
 
         Parameters
@@ -201,7 +214,7 @@ class WaldiezGroupManagerSpeakers(WaldiezBase):
 
         Returns
         -------
-        Tuple[str, str]
+        tuple[str, str]
             The custom method function and the function name.
         """
         function_name = CUSTOM_SPEAKER_SELECTION
@@ -219,6 +232,46 @@ class WaldiezGroupManagerSpeakers(WaldiezBase):
             function_name,
         )
 
+    def get_order(self) -> list[str]:
+        """Get the order of the speakers.
+
+        Returns
+        -------
+        list[str]
+            The order of the speakers.
+
+        Raises
+        ------
+        RuntimeError
+            If the order is not set.
+        """
+        if self._order is None:
+            raise RuntimeError("Order is not set. Call `set_order` first.")
+        return self._order
+
+    def set_order(
+        self, initial_agent_id: str, group_members: list[str]
+    ) -> None:
+        """Generate the order of the speakers.
+
+        Parameters
+        ----------
+        initial_agent_id : str
+            The ID of the initial agent.
+        group_members : list[str]
+            The group members' IDs.
+        """
+        # make sure all the members are in the order
+        # also make sure the initial agent is first
+        order_copy = self.order.copy() if self.order else []
+        all_members = [initial_agent_id] + [
+            member for member in order_copy if member != initial_agent_id
+        ]
+        for member in group_members:
+            if member not in all_members:
+                all_members.append(member)
+        self._order = all_members
+
     @model_validator(mode="after")
     def validate_group_speakers_config(self) -> Self:
         """Validate the speakers config.

waldiez/models/agents/{rag_user → rag_user_proxy}/__init__.py

@@ -2,8 +2,8 @@
 # Copyright (c) 2024 - 2025 Waldiez and contributors.
 """It extends a user agent and has RAG related parameters."""
 
-from .rag_user import WaldiezRagUser
-from .rag_user_data import WaldiezRagUserData
+from .rag_user_proxy import WaldiezRagUserProxy
+from .rag_user_proxy_data import WaldiezRagUserProxyData
 from .retrieve_config import (
     CUSTOM_EMBEDDING_FUNCTION,
     CUSTOM_EMBEDDING_FUNCTION_ARGS,
@@ -14,13 +14,13 @@ from .retrieve_config import (
     CUSTOM_TOKEN_COUNT_FUNCTION,
     CUSTOM_TOKEN_COUNT_FUNCTION_ARGS,
     CUSTOM_TOKEN_COUNT_FUNCTION_TYPES,
-    WaldiezRagUserChunkMode,
-    WaldiezRagUserModels,
-    WaldiezRagUserRetrieveConfig,
-    WaldiezRagUserTask,
-    WaldiezRagUserVectorDb,
+    WaldiezRagUserProxyChunkMode,
+    WaldiezRagUserProxyModels,
+    WaldiezRagUserProxyRetrieveConfig,
+    WaldiezRagUserProxyTask,
+    WaldiezRagUserProxyVectorDb,
 )
-from .vector_db_config import WaldiezRagUserVectorDbConfig
+from .vector_db_config import WaldiezRagUserProxyVectorDbConfig
 
 __all__ = [
     "CUSTOM_EMBEDDING_FUNCTION",
@@ -32,12 +32,12 @@ __all__ = [
     "CUSTOM_TOKEN_COUNT_FUNCTION",
     "CUSTOM_TOKEN_COUNT_FUNCTION_ARGS",
     "CUSTOM_TOKEN_COUNT_FUNCTION_TYPES",
-    "WaldiezRagUser",
-    "WaldiezRagUserData",
-    "WaldiezRagUserModels",
-    "WaldiezRagUserVectorDb",
-    "WaldiezRagUserChunkMode",
-    "WaldiezRagUserRetrieveConfig",
-    "WaldiezRagUserTask",
-    "WaldiezRagUserVectorDbConfig",
+    "WaldiezRagUserProxy",
+    "WaldiezRagUserProxyData",
+    "WaldiezRagUserProxyModels",
+    "WaldiezRagUserProxyVectorDb",
+    "WaldiezRagUserProxyChunkMode",
+    "WaldiezRagUserProxyRetrieveConfig",
+    "WaldiezRagUserProxyTask",
+    "WaldiezRagUserProxyVectorDbConfig",
 ]

waldiez/models/agents/rag_user_proxy/rag_user_proxy.py

@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""RAG user agent.
+
+It extends a user agent and has RAG related parameters (`retrieve_config`).
+"""
+
+from pydantic import Field
+from typing_extensions import Annotated, Literal
+
+from ..agent import WaldiezAgent
+from .rag_user_proxy_data import WaldiezRagUserProxyData
+from .retrieve_config import WaldiezRagUserProxyRetrieveConfig
+
+
+class WaldiezRagUserProxy(WaldiezAgent):
+    """RAG user agent.
+
+    It extends a user agent and has RAG related parameters.
+
+    Attributes
+    ----------
+    agent_type : Literal["rag_user", "rag_user_proxy"]
+        The agent type: 'rag_user' for a RAG user agent.
+    data : WaldiezRagUserProxyData
+        The RAG user agent's data.
+        See `WaldiezRagUserProxyData` for more info.
+    retrieve_config : WaldiezRagUserProxyRetrieveConfig
+        The RAG user agent's retrieve config.
+    """
+
+    agent_type: Annotated[  # pyright: ignore
+        Literal["rag_user", "rag_user_proxy"],
+        Field(
+            "rag_user_proxy",
+            title="Agent type",
+            description=(
+                "The agent type in a graph. "
+                "`rag_user` is deprecated and will be removed in "
+                "future versions. Use `rag_user_proxy` instead."
+            ),
+            alias="agentType",
+        ),
+    ] = "rag_user_proxy"
+
+    data: Annotated[  # pyright: ignore
+        WaldiezRagUserProxyData,
+        Field(
+            title="Data",
+            description="The RAG user agent's data",
+            default_factory=WaldiezRagUserProxyData,  # pyright: ignore
+        ),
+    ]
+
+    @property
+    def retrieve_config(self) -> WaldiezRagUserProxyRetrieveConfig:
+        """Get the retrieve config.
+
+        Returns
+        -------
+        WaldiezRagUserProxyRetrieveConfig
+            The RAG user agent's retrieve config.
+        """
+        return self.data.retrieve_config

waldiez/models/agents/{rag_user/rag_user_data.py → rag_user_proxy/rag_user_proxy_data.py}

@@ -6,10 +6,10 @@ from pydantic import Field
 from typing_extensions import Annotated
 
 from ..user_proxy import WaldiezUserProxyData
-from .retrieve_config import WaldiezRagUserRetrieveConfig
+from .retrieve_config import WaldiezRagUserProxyRetrieveConfig
 
 
-class WaldiezRagUserData(WaldiezUserProxyData):
+class WaldiezRagUserProxyData(WaldiezUserProxyData):
     """RAG user agent data.
 
     The data for a RAG user agent.
@@ -18,17 +18,18 @@ class WaldiezRagUserData(WaldiezUserProxyData):
     ----------
     use_message_generator: bool
         Whether to use the message generator in user's chats. Defaults to False.
-    retrieve_config : WaldiezRagUserRetrieveConfig
+    retrieve_config : WaldiezRagUserProxyRetrieveConfig
         The RAG user agent's retrieve config.
 
     """
 
+    # pylint: disable=line-too-long
     retrieve_config: Annotated[
-        WaldiezRagUserRetrieveConfig,
+        WaldiezRagUserProxyRetrieveConfig,
         Field(
             title="Retrieve Config",
             description="The RAG user agent's retrieve config",
-            default_factory=WaldiezRagUserRetrieveConfig,
+            default_factory=WaldiezRagUserProxyRetrieveConfig,  # pyright: ignore  # noqa: E501
             alias="retrieveConfig",
         ),
     ]