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

waldiez/models/agents/agent/agent_data.py

@@ -2,20 +2,23 @@
 # Copyright (c) 2024 - 2025 Waldiez and contributors.
 """Common data structures for agents."""
 
-from typing import List, Optional, Union
+from typing import Any, Optional, Union
 
-from pydantic import ConfigDict, Field
+from pydantic import ConfigDict, Field, model_validator
 from pydantic.alias_generators import to_camel
-from typing_extensions import Annotated, Literal
+from typing_extensions import Annotated, Literal, Self
 
-from ...common import WaldiezBase
+from ...common import WaldiezBase, WaldiezTransitionTarget, update_dict
 from .code_execution import WaldiezAgentCodeExecutionConfig
-from .linked_skill import WaldiezAgentLinkedSkill
+from .human_input_mode import WaldiezAgentHumanInputMode
+from .linked_tool import WaldiezAgentLinkedTool
 from .nested_chat import WaldiezAgentNestedChat
-from .teachability import WaldiezAgentTeachability
 from .termination_message import WaldiezAgentTerminationMessage
+from .update_system_message import WaldiezAgentUpdateSystemMessage
 
 
+# noqa: E501
+# pylint: disable=line-too-long
 class WaldiezAgentData(WaldiezBase):
     """Waldiez Agent Data.
 
@@ -34,16 +37,24 @@ class WaldiezAgentData(WaldiezBase):
         before ending the chat. Default: None (no limit).
     termination : WaldiezAgentTerminationMessage
         The message termination check to use (keyword, method, none)
-    teachability : WaldiezAgentTeachability
-        The agent teachability configuration.
     model_ids: List[str]
-        A list of models (their ids) to link with the agent.
-    skills : List[WaldiezAgentLinkedSkill]
-        A list of skills (id and executor) to register.
-    nested_chats : List[WaldiezAgentNestedChat]
+        The ids of the models to link with the agent.
+    tools : list[WaldiezAgentLinkedTool]
+        A list of tools (id and executor) to register.
+    nested_chats : list[WaldiezAgentNestedChat]
         A list of nested chats (triggered_by, messages), to register.
-    is_multimodal: bool
-        A flag to indicate if the agent is multimodal.
+    context_variables : Optional[dict[str, Any]]
+        Context variables that provide a persistent context
+        for the agent. Note: This will be a reference to a shared
+        context for multi-agent chats. Behaves like a dictionary
+        with keys and values (akin to dict[str, Any]).
+    update_agent_state_before_reply : list[str |WaldiezAgentUpdateSystemMessage]
+        A list of functions, including UpdateSystemMessage,
+        called to update the agent's state before it replies.
+        Each function is called when the agent is selected
+        and before it speaks.
+    handoffs : list[WaldiezAgentHandoff]
+        A list of handoffs (conditions, targets) to register.
     """
 
     model_config = ConfigDict(
@@ -63,16 +74,16 @@ class WaldiezAgentData(WaldiezBase):
             description="The agent's system message.",
             alias="systemMessage",
         ),
-    ]
+    ] = None
     human_input_mode: Annotated[
-        Literal["ALWAYS", "NEVER", "TERMINATE"],
+        WaldiezAgentHumanInputMode,
         Field(
             "NEVER",
             title="Human input mode",
             description="The human input mode to use for the agent.",
             alias="humanInputMode",
         ),
-    ]
+    ] = "NEVER"
     code_execution_config: Annotated[
         Union[WaldiezAgentCodeExecutionConfig, Literal[False]],
         Field(
@@ -84,7 +95,7 @@ class WaldiezAgentData(WaldiezBase):
             ),
             alias="codeExecutionConfig",
         ),
-    ]
+    ] = False
     agent_default_auto_reply: Annotated[
         Optional[str],
         Field(
@@ -95,7 +106,7 @@ class WaldiezAgentData(WaldiezBase):
             ),
             alias="agentDefaultAutoReply",
         ),
-    ]
+    ] = None
     max_consecutive_auto_reply: Annotated[
         Optional[int],
         Field(
@@ -107,7 +118,7 @@ class WaldiezAgentData(WaldiezBase):
             ),
             alias="maxConsecutiveAutoReply",
         ),
-    ]
+    ] = None
     termination: Annotated[
         WaldiezAgentTerminationMessage,
         Field(
@@ -118,47 +129,108 @@ class WaldiezAgentData(WaldiezBase):
             default_factory=WaldiezAgentTerminationMessage,
         ),
     ]
-    teachability: Annotated[
-        Optional[WaldiezAgentTeachability],
-        Field(
-            title="Teachability",
-            description="The agent teachability configuration.",
-            default_factory=WaldiezAgentTeachability,
-        ),
-    ]
     model_ids: Annotated[
-        List[str],
+        list[str],
         Field(
             default_factory=list,
-            title="Model IDs",
-            description="A list of models (their ids) to link with the agent.",
+            title="Model ID",
+            description=(
+                "The id of the model to link with the agent. "
+                "This is a reference to a model in the models registry."
+            ),
             alias="modelIds",
         ),
-    ]
-    skills: Annotated[
-        List[WaldiezAgentLinkedSkill],
+    ] = []
+    tools: Annotated[
+        list[WaldiezAgentLinkedTool],
         Field(
             default_factory=list,
-            title="Skills",
-            description=("A list of skills (id and executor) to register."),
+            title="Tools",
+            description=("A list of tools (id and executor) to register."),
         ),
-    ]
+    ] = []
     nested_chats: Annotated[
-        List[WaldiezAgentNestedChat],
+        list[WaldiezAgentNestedChat],
         Field(
             default_factory=list,
             description=(
-                "A list of nested chats (triggered_by, messages), to register."
+                "A list of nested chats (triggers, messages, ...), to register."
             ),
             alias="nestedChats",
         ),
-    ]
-    is_multimodal: Annotated[
-        bool,
+    ] = []
+    context_variables: Annotated[
+        dict[str, Any],
         Field(
-            False,
-            title="Is multimodal",
-            description="A flag to indicate if the agent is multimodal.",
-            alias="isMultimodal",
+            default_factory=dict,  # pyright: ignore
+            title="Context variables",
+            description=(
+                "Context variables that provide a persistent context "
+                "for the agent. Note: This will be a reference to a shared "
+                "context for multi-agent chats. Behaves like a dictionary "
+                "with keys and values (akin to dict[str, Any])."
+            ),
+            alias="contextVariables",
         ),
-    ] = False
+    ] = {}
+
+    update_agent_state_before_reply: Annotated[
+        list[Union[str, WaldiezAgentUpdateSystemMessage]],
+        Field(
+            title="Update Agent State Before Reply",
+            alias="updateAgentStateBeforeReply",
+            description=(
+                "A list of functions, including UpdateSystemMessage,"
+                "called to update the agent's state before it replies. "
+                " Each function is called when the agent is selected "
+                "and before it speaks. If not an UpdateSystemMessage, "
+                "it should be a skill id."
+            ),
+            default_factory=list,
+        ),
+    ] = []
+    handoffs: Annotated[
+        list[str],
+        Field(
+            default_factory=list,
+            title="Handoffs",
+            description=("A list of handoffs (target ids) to register."),
+        ),
+    ] = []
+    after_work: Annotated[
+        Optional[WaldiezTransitionTarget],
+        Field(
+            None,
+            title="After work",
+            description=(
+                "The target to transfer control to after the agent"
+                " has finished its work. (used if in a group chat)"
+            ),
+            alias="afterWork",
+        ),
+    ] = None
+
+    parent_id: Annotated[
+        Optional[str],
+        Field(
+            None,
+            title="Parent ID",
+            description=(
+                "The id of the parent agent. This is used for group chats."
+            ),
+            alias="parentId",
+        ),
+    ] = None
+
+    @model_validator(mode="after")
+    def update_context_variables(self) -> Self:
+        """Update the context variables.
+
+        Returns
+        -------
+        Self
+            The updated instance of the class.
+        """
+        context_vars = update_dict(self.context_variables)
+        self.context_variables = context_vars
+        return self

waldiez/models/agents/agent/agent_type.py

@@ -6,6 +6,17 @@ from typing_extensions import Literal
 
 # pylint: disable=line-too-long
 # fmt: off
-WaldiezAgentType = Literal["user", "assistant", "manager", "rag_user", "swarm", "reasoning", "captain"]  # noqa: E501
-"""Possible types of a Waldiez Agent: user, assistant, manager, rag_user, swarm, reasoning, captain."""  # noqa: E501
+WaldiezAgentType = Literal["user_proxy", "assistant", "group_manager", "manager", "rag_user", "swarm", "reasoning", "captain", "user", "rag_user_proxy"]  # noqa: E501
+"""Possible types of a Waldiez Agent:
+    - user_proxy,
+    - assistant,
+    - group_manager,
+    - rag_user_proxy,
+    - reasoning,
+    - captain,
+    - swarm (deprecated: do not use it),
+    - user (deprecated: use user_proxy)
+    - rag_user (deprecated: user rag_user_proxy)
+    - manager (deprecated: use group_manager)
+"""  # noqa: W291
 # fmt: on

waldiez/models/agents/agent/code_execution.py

@@ -2,7 +2,7 @@
 # Copyright (c) 2024 - 2025 Waldiez and contributors.
 """Waldiez Agent Code Execution Configuration."""
 
-from typing import List, Optional
+from typing import Optional
 
 from pydantic import Field
 from typing_extensions import Annotated
@@ -23,51 +23,51 @@ class WaldiezAgentCodeExecutionConfig(WaldiezBase):
         The timeout for the code execution. By default None (no timeout).
     last_n_messages : Optional[int]
         The chat's last n messages to consider for the code execution.
-    functions : Optional[List[str]]
+    functions : Optional[list[str]]
         If not using docker, a list of function ids to use.
     """
 
     work_dir: Annotated[
         Optional[str],
         Field(
-            None,
+            default=None,
             title="Working directory",
             description="The working directory for the code execution.",
             alias="workDir",
         ),
-    ]
+    ] = None
     use_docker: Annotated[
         Optional[bool],
         Field(
-            None,
+            default=None,
             title="Use docker",
             description="Run the code in a docker container.",
             alias="useDocker",
         ),
-    ]
+    ] = None
     timeout: Annotated[
         Optional[float],
         Field(
-            None,
+            default=None,
             title="Timeout",
             description=(
                 "The timeout for the code execution.Default: No timeout"
             ),
         ),
-    ]
+    ] = None
     last_n_messages: Annotated[
         Optional[int],
         Field(
-            None,
+            default=None,
             title="Last N Messages",
             description="The number of previous messages in the chat to use.",
         ),
-    ]
+    ] = None
     functions: Annotated[
-        List[str],
+        list[str],
         Field(
             default_factory=list,
             title="Functions",
             description="If not using docker, the function ids to use",
         ),
-    ]
+    ] = []

waldiez/models/agents/agent/human_input_mode.py

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Waldiez Agent human input modes."""
+
+from typing_extensions import Literal
+
+WaldiezAgentHumanInputMode = Literal["ALWAYS", "NEVER", "TERMINATE"]
+"""Possible human input modes for agents: ALWAYS, NEVER, TERMINATE."""

waldiez/models/agents/agent/{linked_skill.py → linked_tool.py}

@@ -1,6 +1,6 @@
 # SPDX-License-Identifier: Apache-2.0.
 # Copyright (c) 2024 - 2025 Waldiez and contributors.
-"""Waldiez Agent Skill Model."""
+"""Waldiez Agent Tool Model."""
 
 from pydantic import Field
 from typing_extensions import Annotated
@@ -8,25 +8,25 @@ from typing_extensions import Annotated
 from ...common import WaldiezBase
 
 
-class WaldiezAgentLinkedSkill(WaldiezBase):
-    """Waldiez Agent Linked Skill.
+class WaldiezAgentLinkedTool(WaldiezBase):
+    """Waldiez Agent Linked Tool.
 
     Attributes
     ----------
     id : str
-        The id of the skill to use.
+        The id of the tool to use.
     executor_id: str
-        The id of the agent to use that skill.
+        The id of the agent to use that tool.
     """
 
     id: Annotated[
-        str, Field(..., title="ID", description="The id of the skill to use.")
+        str, Field(..., title="ID", description="The id of the tool to use.")
     ]
     executor_id: Annotated[
         str,
         Field(
             ...,
             title="Executor ID",
-            description="The id of the agent to use that skill.",
+            description="The id of the agent to use that tool.",
         ),
     ]

waldiez/models/agents/agent/nested_chat.py

@@ -2,12 +2,15 @@
 # Copyright (c) 2024 - 2025 Waldiez and contributors.
 """Waldiez Agent Nested Chat."""
 
-from typing import List
-
 from pydantic import Field
 from typing_extensions import Annotated
 
-from ...common import WaldiezBase
+from ...common import (
+    WaldiezBase,
+    WaldiezDefaultCondition,
+    WaldiezHandoffCondition,
+    WaldiezTransitionAvailability,
+)
 
 
 class WaldiezAgentNestedChatMessage(WaldiezBase):
@@ -42,15 +45,18 @@ class WaldiezAgentNestedChat(WaldiezBase):
 
     Attributes
     ----------
-    triggered_by : List[str]
+    triggered_by : list[str]
         A list of agent ids that trigger the nested chat.
-    messages : List[WaldiezAgentNestedChatMessage]
+    messages : list[WaldiezAgentNestedChatMessage]
         The list of messages (chat ids and 'is_reply'z)
         to include the in the nested chat registration.
+    order : int
+        The order of the nested chat (if used as a handoff).
+        Defaults to 0.
     """
 
     triggered_by: Annotated[
-        List[str],
+        list[str],
         Field(
             title="Triggered By",
             description=("A list of agent ids that trigger the nested chat."),
@@ -59,7 +65,7 @@ class WaldiezAgentNestedChat(WaldiezBase):
         ),
     ]
     messages: Annotated[
-        List[WaldiezAgentNestedChatMessage],
+        list[WaldiezAgentNestedChatMessage],
         Field(
             title="Messages",
             description=(
@@ -69,3 +75,25 @@ class WaldiezAgentNestedChat(WaldiezBase):
             default_factory=list,
         ),
     ]
+    condition: Annotated[
+        WaldiezHandoffCondition,
+        Field(
+            default_factory=WaldiezDefaultCondition.create,
+            title="Condition",
+            description=(
+                "The condition to use for the nested chat handoff. "
+                "If not provided, the nested chat will always be available."
+            ),
+        ),
+    ]
+    available: Annotated[
+        WaldiezTransitionAvailability,
+        Field(
+            default_factory=WaldiezTransitionAvailability,
+            title="Available",
+            description=(
+                "The availability of the nested chat. "
+                "If not provided, the nested chat will always be available."
+            ),
+        ),
+    ]

waldiez/models/agents/agent/termination_message.py

@@ -2,7 +2,7 @@
 # Copyright (c) 2024 - 2025 Waldiez and contributors.
 """Waldiez Agent Termination Message Check."""
 
-from typing import List, Optional, Tuple
+from typing import Optional
 
 from pydantic import Field, model_validator
 from typing_extensions import Annotated, Literal, Self
@@ -12,7 +12,7 @@ from ...common import WaldiezBase, check_function, generate_function
 IS_TERMINATION_MESSAGE = "is_termination_message"
 IS_TERMINATION_MESSAGE_ARGS = ["message"]
 IS_TERMINATION_MESSAGE_TYPES = (
-    ["Dict[str, Any]"],
+    ["dict[str, Any]"],
     "bool",
 )
 
@@ -24,7 +24,7 @@ class WaldiezAgentTerminationMessage(WaldiezBase):
     ----------
     type : Literal["none", "keyword", "method"]
         The type of the termination check to use: "none", "keyword", "method"
-    keywords : List[str]
+    keywords : list[str]
         If the type is "keyword", the keywords to search in the message.
     criterion : Optional[Literal["found", "ending", "exact"]] = None
         If the type is "keyword", the criterion to use (e.g.: in, endswith, ==)
@@ -52,9 +52,9 @@ class WaldiezAgentTerminationMessage(WaldiezBase):
                 "none, keyword, method"
             ),
         ),
-    ]
+    ] = "none"
     keywords: Annotated[
-        List[str],
+        list[str],
         Field(
             default_factory=list,
             title="Keywords",
@@ -63,9 +63,9 @@ class WaldiezAgentTerminationMessage(WaldiezBase):
                 " the keywords to search in the message."
             ),
         ),
-    ]
+    ] = []
     criterion: Annotated[
-        Optional[Literal["found", "ending", "exact"]],
+        Optional[Literal["found", "ending", "starting", "exact"]],
         Field(
             "exact",
             title="Criterion",
@@ -74,7 +74,7 @@ class WaldiezAgentTerminationMessage(WaldiezBase):
                 "the criterion to use (e.g.: in, endswith, ==)"
             ),
         ),
-    ]
+    ] = "exact"
     method_content: Annotated[
         Optional[str],
         Field(
@@ -87,7 +87,7 @@ class WaldiezAgentTerminationMessage(WaldiezBase):
                 "bool (whether the message is a termination message or not.)"
             ),
         ),
-    ]
+    ] = None
 
     _string: str = "None"
 
@@ -95,7 +95,7 @@ class WaldiezAgentTerminationMessage(WaldiezBase):
         self,
         name_prefix: Optional[str] = None,
         name_suffix: Optional[str] = None,
-    ) -> Tuple[str, str]:
+    ) -> tuple[str, str]:
         """Get the termination function.
 
         Parameters
@@ -107,7 +107,7 @@ class WaldiezAgentTerminationMessage(WaldiezBase):
 
         Returns
         -------
-        Tuple[str, str]
+        tuple[str, str]
             The termination function and the function name.
         """
         function_name = "is_termination_message"
@@ -162,26 +162,34 @@ class WaldiezAgentTerminationMessage(WaldiezBase):
         """Validate the keyword termination configuration."""
         if not self.keywords:
             raise ValueError("Keywords are required for keyword termination.")
-        if self.criterion not in ["found", "ending", "exact"]:
+        if self.criterion not in ["found", "ending", "starting", "exact"]:
             raise ValueError(f"Invalid criterion: {self.criterion}")
         # pylint: disable=inconsistent-quotes
         keywords_str = ", ".join([f'"{keyword}"' for keyword in self.keywords])
+        common_start = (
+            "lambda x: any(isinstance(x, dict) and "
+            'x.get("content", "") and '
+            'isinstance(x.get("content", ""), str) and '
+        )
+        common_end = f"for keyword in [{keywords_str}])"
         if self.criterion == "found":
             self._string = (
-                'lambda x: any(x.get("content", "") and '
-                'keyword in x.get("content", "") '
-                f"for keyword in [{keywords_str}])"
+                f'{common_start}keyword in x.get("content", "") {common_end}'
+            )
+        elif self.criterion == "ending":
+            self._string = (
+                f'{common_start}x.get("content", "").endswith(keyword) '
+                f"{common_end}"
             )
-        if self.criterion == "ending":
+        elif self.criterion == "starting":
             self._string = (
-                'lambda x: any(x.get("content", "") and '
-                'x.get("content", "").endswith(keyword) '
-                f"for keyword in [{keywords_str}])"
+                f'{common_start}x.get("content", "").startswith(keyword) '
+                f"{common_end}"
             )
-        if self.criterion == "exact":
+
+        elif self.criterion == "exact":  # pragma: no branch
             self._string = (
-                'lambda x: any(x.get("content", "") == keyword '
-                f"for keyword in [{keywords_str}])"
+                f'{common_start}x.get("content", "") == keyword {common_end}'
             )
 
     @model_validator(mode="after")