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

waldiez/models/flow/flow.py

@@ -1,18 +1,20 @@
 # SPDX-License-Identifier: Apache-2.0.
 # Copyright (c) 2024 - 2025 Waldiez and contributors.
+# pyright: reportCallIssue=false
 """Waldiez flow model."""
 
-import uuid
-from typing import List, Optional, Tuple
+from functools import cached_property
+from typing import Optional
 
 from pydantic import Field, model_validator
 from typing_extensions import Annotated, Literal, Self
 
-from ..agents import WaldiezAgent, WaldiezSwarmAgent
+from ..agents import WaldiezAgent, WaldiezGroupManager
 from ..chat import WaldiezChat
-from ..common import WaldiezBase, now
+from ..common import WaldiezBase, get_id, get_waldiez_version, now
+from .connection import WaldiezAgentConnection
 from .flow_data import WaldiezFlowData
-from .utils import check_handoff_to_nested_chat, id_factory
+from .naming import WaldiezUniqueNames, ensure_unique_names
 
 
 class WaldiezFlow(WaldiezBase):
@@ -28,9 +30,9 @@ class WaldiezFlow(WaldiezBase):
         The name of the flow.
     description : str
         The description of the flow.
-    tags : List[str]
+    tags : list[str]
         The tags of the flow.
-    requirements : List[str]
+    requirements : list[str]
         The requirements of the flow.
     storage_id : str
         The storage ID of the flow (ignored, UI related).
@@ -47,9 +49,17 @@ class WaldiezFlow(WaldiezBase):
         Field(
             description="The ID of the flow",
             title="ID",
-            default_factory=id_factory,
+            default_factory=get_id,
         ),
     ]
+    version: Annotated[
+        str,
+        Field(
+            default_factory=get_waldiez_version,
+            description="The version waldiez that was used to create the flow",
+            title="Version",
+        ),
+    ] = "0.0.0"  # default to 0.0.0 if not found
     type: Annotated[
         Literal["flow"],
         Field(
@@ -75,7 +85,7 @@ class WaldiezFlow(WaldiezBase):
         ),
     ]
     tags: Annotated[
-        List[str],
+        list[str],
         Field(
             description="The tags of the flow",
             title="Tags",
@@ -83,7 +93,7 @@ class WaldiezFlow(WaldiezBase):
         ),
     ]
     requirements: Annotated[
-        List[str],
+        list[str],
         Field(
             description="The requirements of the flow",
             title="Requirements",
@@ -101,7 +111,7 @@ class WaldiezFlow(WaldiezBase):
     storage_id: Annotated[
         str,
         Field(
-            uuid.uuid4(),
+            default_factory=get_id,
             description="The storage ID of the flow (ignored, UI related)",
             title="Storage ID",
             alias="storageId",
@@ -123,10 +133,9 @@ class WaldiezFlow(WaldiezBase):
             description="The date and time when the flow was last updated.",
         ),
     ]
-    _ordered_flow: Optional[
-        List[Tuple[WaldiezChat, WaldiezAgent, WaldiezAgent]]
-    ] = None
+    _ordered_flow: Optional[list[WaldiezAgentConnection]] = None
     _single_agent_mode: bool = False
+    _is_group_chat: bool = False
 
     @property
     def is_async(self) -> bool:
@@ -150,19 +159,6 @@ class WaldiezFlow(WaldiezBase):
         """
         return self.data.cache_seed
 
-    @property
-    def is_swarm_flow(self) -> bool:
-        """Check if the flow is a swarm flow.
-
-        Returns
-        -------
-        bool
-            True if the flow is a swarm flow, False otherwise.
-        """
-        return any(
-            agent.agent_type == "swarm" for agent in self.data.agents.members
-        )
-
     @property
     def is_single_agent_mode(self) -> bool:
         """Check if the flow is in single agent mode.
@@ -177,12 +173,30 @@ class WaldiezFlow(WaldiezBase):
     @property
     def ordered_flow(
         self,
-    ) -> List[Tuple[WaldiezChat, WaldiezAgent, WaldiezAgent]]:
+    ) -> list[WaldiezAgentConnection]:
         """Get the ordered flow."""
-        if not self._ordered_flow:
+        if self._ordered_flow is None:
             self._ordered_flow = self._get_flow_order()
         return self._ordered_flow
 
+    @cached_property
+    def unique_names(self) -> WaldiezUniqueNames:
+        """Get the unique names for the flow.
+
+        Returns
+        -------
+        WaldiezUniqueNames
+            The unique names for the flow.
+        """
+        return ensure_unique_names(
+            flow_id=self.id,
+            flow_name=self.name,
+            flow_agents=self.data.agents.members,
+            flow_chats=self.data.chats,
+            flow_tools=self.data.tools,
+            flow_models=self.data.models,
+        )
+
     def get_agent_by_id(self, agent_id: str) -> WaldiezAgent:
         """Get the agent by ID.
 
@@ -206,89 +220,51 @@ class WaldiezFlow(WaldiezBase):
                 return agent
         raise ValueError(f"Agent with ID {agent_id} not found.")
 
-    def _get_flow_order(
-        self,
-    ) -> List[Tuple[WaldiezChat, WaldiezAgent, WaldiezAgent]]:
-        """Get the ordered flow."""
-        # in the chats, there is the 'order' field, we use this,
-        # we only keep the ones with order >=0
-        # and sort them by this property
-        ordered_flow: List[Tuple[WaldiezChat, WaldiezAgent, WaldiezAgent]] = []
-        # if swarm, we only keep the first chat
-        if self.is_swarm_flow:
-            ordered_flow = self._get_swarm_flow()
-        if ordered_flow:
-            return ordered_flow
-        for chat in self.data.chats:
-            if chat.data.order < 0:
-                continue
-            source = self.get_agent_by_id(chat.source)
-            target = self.get_agent_by_id(chat.target)
-            ordered_flow.append((chat, source, target))
-        if not ordered_flow:
-            if len(self.data.chats) == 1:
-                chat = self.data.chats[0]
-                source = self.get_agent_by_id(chat.source)
-                target = self.get_agent_by_id(chat.target)
-                ordered_flow.append((chat, source, target))
-        return ordered_flow
+    @classmethod
+    def default(cls) -> "WaldiezFlow":
+        """Get the default flow.
 
-    def _get_swarm_flow(
-        self,
-    ) -> List[Tuple[WaldiezChat, WaldiezAgent, WaldiezAgent]]:
-        # valid "first" chat:
-        # - source is a user|rag_user and target is a swarm
-        # - source is a swarm and target is a  (and source.is_initial)
-        valid_chats: List[WaldiezChat] = []
-        for chat in self.data.chats:
-            target = self.get_agent_by_id(chat.target)
-            source = self.get_agent_by_id(chat.source)
-            if (
-                source.agent_type in ["user", "rag_user"]
-                and target.agent_type == "swarm"
-            ):
-                return [(chat, source, target)]
-            if source.agent_type == "swarm" and target.agent_type == "swarm":
-                valid_chats.append(chat)
-        if not valid_chats:
-            return []
-        for valid_chat in valid_chats:
-            source = self.get_agent_by_id(valid_chat.source)
-            if isinstance(source, WaldiezSwarmAgent) and source.is_initial:
-                return [
-                    (
-                        valid_chat,
-                        source,
-                        self.get_agent_by_id(valid_chat.target),
-                    )
-                ]
-        first_chat: Optional[WaldiezChat] = None
-        # first check the order
-        by_order = sorted(
-            filter(lambda edge: edge.data.order >= 0, valid_chats),
-            key=lambda edge: edge.data.order,
+        Returns
+        -------
+        WaldiezFlow
+            The default flow.
+        """
+        an_id = get_id()
+        return cls(
+            id=an_id,
+            storage_id=an_id,
+            created_at=now(),
+            updated_at=now(),
+            type="flow",
+            name="Default Flow",
+            description="Default Flow",
+            tags=[],
+            requirements=[],
+            data=WaldiezFlowData.default(),
         )
-        if not by_order:
-            # let's order by position
-            by_position = sorted(
-                valid_chats,
-                key=lambda chat: chat.data.position,
-            )
-            if by_position:
-                first_chat = by_position[0]
-            else:
-                first_chat = valid_chats[0]
-        else:
-            first_chat = by_order[0]
-        if first_chat:
-            source = self.get_agent_by_id(first_chat.source)
-            target = self.get_agent_by_id(first_chat.target)
-            return [(first_chat, source, target)]
-        return []
+
+    def get_group_members(self, group_id: str) -> list[WaldiezAgent]:
+        """Get the group members.
+
+        Parameters
+        ----------
+        group_id : str
+            The ID of the group.
+
+        Returns
+        -------
+        list[WaldiezAgent]
+            The list of group members.
+        """
+        return [
+            agent
+            for agent in self.data.agents.members
+            if agent.data.parent_id == group_id
+        ]
 
     def get_agent_connections(
         self, agent_id: str, all_chats: bool = True
-    ) -> List[str]:
+    ) -> list[str]:
         """Get the agent connections.
 
         Parameters
@@ -301,10 +277,10 @@ class WaldiezFlow(WaldiezBase):
 
         Returns
         -------
-        List[str]
+        list[str]
             The list of agent ids that the agent with the given ID connects to.
         """
-        connections: List[str] = []
+        connections: list[str] = []
         if all_chats:
             for chat in self.data.chats:
                 if chat.source == agent_id:
@@ -312,7 +288,9 @@ class WaldiezFlow(WaldiezBase):
                 if chat.target == agent_id:
                     connections.append(chat.source)
         else:
-            for _, source, target in self.ordered_flow:
+            for entry in self.ordered_flow:
+                source = entry["source"]
+                target = entry["target"]
                 if source.id == agent_id:
                     connections.append(target.id)
                 if target.id == agent_id:
@@ -321,7 +299,7 @@ class WaldiezFlow(WaldiezBase):
 
     def get_group_chat_members(
         self, group_manager_id: str
-    ) -> List[WaldiezAgent]:
+    ) -> list[WaldiezAgent]:
         """Get the group chat members.
 
         Parameters
@@ -331,89 +309,142 @@ class WaldiezFlow(WaldiezBase):
 
         Returns
         -------
-        List[WaldiezAgent]
-            The list of group chat
+        list[WaldiezAgent]
+            The list of group chat members.
         """
         agent = self.get_agent_by_id(group_manager_id)
-        if agent.agent_type != "manager":
+        if not agent.is_group_manager or not isinstance(
+            agent, WaldiezGroupManager
+        ):
             return []
-        connections = self.get_agent_connections(
-            group_manager_id,
-            all_chats=True,
-        )
-        return [self.get_agent_by_id(member_id) for member_id in connections]
+        members = [
+            agent
+            for agent in self.data.agents.members
+            if agent.data.parent_id == group_manager_id
+        ]
+        if agent.data.speakers.selection_method != "round_robin":
+            return members
+        ordered_ids = agent.get_speakers_order()
+        if not ordered_ids:
+            return members
+        members_dict = {member.id: member for member in members}
+        ordered_members = [
+            members_dict[member_id]
+            for member_id in ordered_ids
+            if member_id in members_dict
+        ]
+        return ordered_members
 
-    def get_initial_swarm_agent(self) -> Optional[WaldiezAgent]:
-        """Get the initial swarm agent.
+    def _get_flow_order(
+        self,
+    ) -> list[WaldiezAgentConnection]:
+        """Get the ordered flow."""
+        if self._is_group_chat:
+            return self._get_group_chat_flow()
+        # in the chats, there is the 'order' field, we use this,
+        # we only keep the ones with order >=0
+        # and sort them by this property
+        ordered_flow: list[WaldiezAgentConnection] = []
+        for chat in self.data.chats:
+            if chat.data.order < 0:
+                continue
+            source = self.get_agent_by_id(chat.source)
+            target = self.get_agent_by_id(chat.target)
+            ordered_flow.append(
+                {
+                    "source": source,
+                    "target": target,
+                    "chat": chat,
+                }
+            )
+            # ordered_flow.append((chat, source, target))
+        if not ordered_flow:
+            if len(self.data.chats) == 1:
+                chat = self.data.chats[0]
+                source = self.get_agent_by_id(chat.source)
+                target = self.get_agent_by_id(chat.target)
+                ordered_flow.append(
+                    {
+                        "source": source,
+                        "target": target,
+                        "chat": chat,
+                    }
+                )
+        return ordered_flow
+
+    def get_root_group_manager(self) -> WaldiezGroupManager:
+        """Get the root group manager.
 
         Returns
         -------
-        Optional[WaldiezAgent]
-            The initial swarm agent if found, None otherwise.
+        WaldiezGroupManager
+            The root group manager.
+
+        Raises
+        ------
+        ValueError
+            If no group manager is found.
         """
-        fallback_agent = None
-        for chat in self.data.chats:
-            source_agent = self.get_agent_by_id(chat.source)
-            target_agent = self.get_agent_by_id(chat.target)
-            if (
-                target_agent.agent_type == "swarm"
-                and source_agent.agent_type != "swarm"
-            ):
-                return target_agent
-            if (
-                source_agent.agent_type == "swarm"
-                and target_agent.agent_type == "swarm"
-            ):
-                fallback_agent = source_agent
-                break
-        for swarm_agent in self.data.agents.swarm_agents:
-            if swarm_agent.is_initial:
-                return swarm_agent
-        return fallback_agent
-
-    def get_swarm_chat_members(
-        self,
-        initial_agent: WaldiezAgent,
-    ) -> Tuple[List[WaldiezAgent], Optional[WaldiezAgent]]:
-        """Get the swarm chat members.
+        for agent in self.data.agents.groupManagerAgents:
+            if agent.data.parent_id is None:
+                return agent
+        raise ValueError("No group manager found.")
 
-        Parameters
-        ----------
-        initial_agent : WaldiezAgent
-            The initial agent.
+    def _get_group_chat_flow(
+        self,
+    ) -> list[WaldiezAgentConnection]:
+        """Get the ordered flow for group chat.
 
         Returns
         -------
-        Tuple[List[WaldiezAgent], Optional[WaldiezAgent]]
-            The list of swarm chat members and the user agent if any.
+        list[tuple[WaldiezChat, WaldiezAgent, WaldiezAgent]]
+            The ordered flow for group chat.
         """
-        if initial_agent.agent_type != "swarm":
-            return [], None
-        members: List[WaldiezAgent] = [initial_agent]
+        # in a group chat there is no "order", the group manager
+        # handles the conversation (using the group "pattern")
+        # the only thin to check is if there is a user agent that connects
+        # to the group manager agent (so that would be the first chat)
+        # if found, we must then check if the message from the user
+        # to the group manager is:
+        #  - "text" or "none" => no need to create a group manager on ag2
+        #  - "function/method" => create a group manager and a group chat on ag2
+        # in the first case, the chat would be:
+        # result, context, last_agent = initiate_group_chat(
+        #     pattern=pattern,
+        #     messages=...,
+        #     max_rounds=10
+        # )
+        # in the second case, the chat would be:
+        # user.initiate_chat(manager, ...)
         user_agent: Optional[WaldiezAgent] = None
-        visited_agents = set()
-        visited_agents.add(initial_agent.id)
-        connections = self.get_agent_connections(
-            initial_agent.id,
-            all_chats=True,
-        )
-        while connections:
-            agent_id = connections.pop()
-            if agent_id in visited_agents:
-                continue
-            agent = self.get_agent_by_id(agent_id)
-            visited_agents.add(agent_id)
-            if agent.agent_type == "swarm":
-                members.append(agent)
-                connections.extend(
-                    self.get_agent_connections(agent_id, all_chats=True)
-                )
-            if agent.agent_type in ["user", "rag_user"] and not user_agent:
-                user_agent = agent
-        return members, user_agent
+        to_root_manager: Optional[WaldiezChat] = None
+        root_manager: WaldiezGroupManager = self.get_root_group_manager()
+        for chat in self.data.chats:
+            if chat.target == root_manager.id:
+                # check if the source is a user agent
+                source = self.get_agent_by_id(chat.source)
+                if source.is_user:
+                    user_agent = source
+                    to_root_manager = chat
+                    break
+        if not to_root_manager or not user_agent:
+            return []
+        return [
+            {
+                "source": user_agent,
+                "target": root_manager,
+                "chat": to_root_manager,
+            }
+        ]
 
     def _validate_agent_connections(self) -> None:
         for agent in self.data.agents.members:
+            if agent.is_group_member:
+                # group members are allowed
+                # to not connect to any other node
+                # the group manager will take care of
+                # the agent/speaker connections
+                continue
             if not any(
                 agent.id in (chat.source, chat.target)
                 for chat in self.data.chats
@@ -429,15 +460,15 @@ class WaldiezFlow(WaldiezBase):
 
         - unique node ids
         - there are at least two agents
-            - (or a single agent but not a group manager or a swarm agent)
+            - (or a single agent but not a group manager)
         - all the agents connect to at least one other agent
-        - all the linked agent skills are found in the flow
+        - all the linked agent tools are found in the flow
         - all the linked agent models are found in the flow
         - all the managers have at least one member in the chat group
         - the ordered flow (chats with position >=0) is not empty
-        - all agents' code execution config functions exist in the flow skills
-        - if swarm flow, there is at least one swarm agent
-        - if swarm flow, there is an initial swarm agent
+        - all agents' code execution config functions exist in the flow tools
+        - if group chat flow, there is at least one group manager agent
+        - if group chat flow, there is an initial group member agent
 
         Returns
         -------
@@ -449,34 +480,35 @@ class WaldiezFlow(WaldiezBase):
         ValueError
             If the ordered flow is empty.
             If the model IDs are not unique.
-            If the skill IDs are not unique.
+            If the tool IDs are not unique.
             If the agents do not connect to any other node.
             If the manager's group chat has no members.
         """
         all_members = list(self.data.agents.members)
+        all_chats = list(self.data.chats)
+        for agent in all_members:
+            agent.gather_nested_chats(
+                all_agents=all_members, all_chats=all_chats
+            )
+            agent.gather_handoffs(all_agents=all_members, all_chats=all_chats)
+        self._validate_group_chat(all_members)
         if len(all_members) == 1:
-            return self.validate_single_agent_mode(all_members[0])
-        if not self.ordered_flow:
+            return self._validate_single_agent_mode(all_members[0])
+        ordered_flow = self.ordered_flow  # could be empty (if group chat)
+        if not ordered_flow and self._ordered_flow is None:
             raise ValueError("The ordered flow is empty.")
-        model_ids = self.validate_flow_models()
-        skills_ids = self.validate_flow_skills()
-        self.data.agents.validate_flow(model_ids, skills_ids)
+        model_ids = self._validate_flow_models()
+        tools_ids = self._validate_flow_tools()
+        self.data.agents.validate_flow(model_ids, tools_ids)
         self._validate_agent_connections()
-        if self.is_swarm_flow:
-            for swarm_agent in self.data.agents.swarm_agents:
-                check_handoff_to_nested_chat(
-                    swarm_agent,
-                    all_agents=list(self.data.agents.members),
-                    all_chats=self.data.chats,
-                )
         return self
 
-    def validate_flow_models(self) -> List[str]:
+    def _validate_flow_models(self) -> list[str]:
         """Validate the flow models.
 
         Returns
         -------
-        List[str]
+        list[str]
             The list of model IDs.
 
         Raises
@@ -489,25 +521,25 @@ class WaldiezFlow(WaldiezBase):
             raise ValueError("Model IDs must be unique.")
         return model_ids
 
-    def validate_flow_skills(self) -> List[str]:
-        """Validate the flow skills.
+    def _validate_flow_tools(self) -> list[str]:
+        """Validate the flow tools.
 
         Returns
         -------
-        List[str]
-            The list of skill IDs.
+        list[str]
+            The list of tool IDs.
 
         Raises
         ------
         ValueError
-            If the skill IDs are not unique.
+            If the tool IDs are not unique.
         """
-        skill_ids = [skill.id for skill in self.data.skills]
-        if len(skill_ids) != len(set(skill_ids)):
-            raise ValueError("Skill IDs must be unique.")
-        return skill_ids
+        tool_ids = [tool.id for tool in self.data.tools]
+        if len(tool_ids) != len(set(tool_ids)):
+            raise ValueError("Tool IDs must be unique.")
+        return tool_ids
 
-    def validate_single_agent_mode(self, member: WaldiezAgent) -> Self:
+    def _validate_single_agent_mode(self, member: WaldiezAgent) -> Self:
         """Flow validation for single agent mode.
 
         Parameters
@@ -523,17 +555,81 @@ class WaldiezFlow(WaldiezBase):
         Raises
         ------
         ValueError
-            - If the only agent is a group manager or a swarm agent.
+            - If the only agent is a group manager.
             - If the model IDs are not unique.
-            - If the skill IDs are not unique.
+            - If the tool IDs are not unique.
         """
-        if member.agent_type in ["manager", "swarm"]:
+        if member.is_group_manager:
             raise ValueError(
-                "In single agent mode, "
-                "the agent must not be a group manager or a swarm agent."
+                "In single agent mode, the agent must not be a group manager."
             )
-        model_ids = self.validate_flow_models()
-        skills_ids = self.validate_flow_skills()
-        self.data.agents.validate_flow(model_ids, skills_ids)
+        model_ids = self._validate_flow_models()
+        tools_ids = self._validate_flow_tools()
+        self.data.agents.validate_flow(model_ids, tools_ids)
         self._single_agent_mode = True
         return self
+
+    def _validate_group_manager(
+        self, group_manager: WaldiezGroupManager, all_member_ids: list[str]
+    ) -> None:
+        """Validate the group manager agents.
+
+        Raises
+        ------
+        ValueError
+            If there are no group manager agents.
+        """
+        if not group_manager.data.initial_agent_id:
+            raise ValueError(
+                "The flow is a group chat but the group manager agent "
+                f"{group_manager.id} has no initial agent ID."
+            )
+        if group_manager.data.initial_agent_id not in all_member_ids:
+            raise ValueError(
+                "The flow is a group chat but the initial agent ID "
+                f"{group_manager.data.initial_agent_id} is not in the flow."
+            )
+        group_members = self.get_group_members(group_manager.id)
+        if not group_members:
+            raise ValueError(
+                "The flow is a group chat but the group manager agent "
+                f"{group_manager.id} has no members in the group."
+            )
+        group_manager.set_speakers_order(
+            [member.id for member in group_members]
+        )
+
+    def _validate_group_chat(self, all_members: list[WaldiezAgent]) -> None:
+        """Check if the flow is a group chat and validate it.
+
+        Raises
+        ------
+        ValueError
+            If the flow is a group chat and there is no group manager agent,
+            if the group has no members,
+            or if the group has no initial member agent.
+        """
+        if not self.data.agents.groupManagerAgents:
+            # no group manager agents, not a group chat
+            return
+        self._is_group_chat = True
+        if not any(agent.is_group_member for agent in self.data.agents.members):
+            raise ValueError(
+                "The flow is a group chat but has no members in the group."
+            )
+        # check if the group manager agents are the flow
+        group_manager_ids = [
+            agent.id for agent in self.data.agents.groupManagerAgents
+        ]
+        all_member_ids = [agent.id for agent in all_members]
+        if not all(
+            group_manager_id in all_member_ids
+            for group_manager_id in group_manager_ids
+        ):
+            raise ValueError(
+                "The flow is a group chat but not all group manager agents are "
+                "in the flow."
+            )
+        # check the initial_agent_id for each group
+        for group_manager in self.data.agents.groupManagerAgents:
+            self._validate_group_manager(group_manager, all_member_ids)