lionagi 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

lionagi/core/execute/structure_executor.py

@@ -19,10 +19,32 @@ from lionagi.core.graph.graph import Graph
 
 
 class StructureExecutor(BaseExecutor, Graph):
+    """
+    Executes tasks within a graph structure, handling dynamic node flows and conditional edge logic.
+
+    Attributes:
+        condition_check_result (bool | None): Result of the last condition check performed during execution,
+            used to control flow based on dynamic conditions.
+    """
 
     condition_check_result: bool | None = None
 
     async def check_edge_condition(self, edge: Edge, executable_id, request_source):
+        """
+        Evaluates the condition associated with an edge, determining if execution should proceed along that edge based
+        on the condition's source type.
+
+        Args:
+            edge (Edge): The edge whose condition needs to be checked.
+            executable_id (str): ID of the executor handling this edge's condition.
+            request_source (str): Origin of the request prompting this condition check.
+
+        Returns:
+            bool: Result of the condition evaluation.
+
+        Raises:
+            ValueError: If the source_type of the condition is invalid.
+        """
         if edge.condition.source_type == "structure":
             return edge.condition(self)
 
@@ -59,6 +81,17 @@ class StructureExecutor(BaseExecutor, Graph):
     async def _check_executable_condition(
         self, edge: Edge, executable_id, request_source
     ):
+        """
+        Sends the edge's condition to an external executable for evaluation and waits for the result.
+
+        Args:
+            edge (Edge): The edge containing the condition to be checked.
+            executable_id (str): ID of the executable that will evaluate the condition.
+            request_source (str): Source of the request for condition evaluation.
+
+        Returns:
+            bool: The result of the condition check.
+        """
         self.send(
             recipient_id=executable_id,
             category="condition",
@@ -73,6 +106,16 @@ class StructureExecutor(BaseExecutor, Graph):
         return check_result
 
     async def _handle_node_id(self, mail: BaseMail):
+        """
+        Processes the node identified by its ID in the mail's package, ensuring it exists and retrieving the next set of
+        nodes based on the current node.
+
+        Args:
+            mail (BaseMail): The mail containing the node ID and related execution details.
+
+        Raises:
+            ValueError: If the node does not exist within the structure.
+        """
         if mail.package["package"] not in self.internal_nodes:
             raise ValueError(
                 f"Node {mail.package} does not exist in the structure {self.id_}"
@@ -84,6 +127,15 @@ class StructureExecutor(BaseExecutor, Graph):
         )
 
     async def _handle_node(self, mail: BaseMail):
+        """
+        Processes the node specified in the mail's package, ensuring it exists within the structure.
+
+        Args:
+            mail (BaseMail): The mail containing the node details to be processed.
+
+        Raises:
+            ValueError: If the node does not exist within the structure.
+        """
         if not self.node_exist(mail.package["package"]):
             raise ValueError(
                 f"Node {mail.package} does not exist in the structure {self.id_}"
@@ -93,7 +145,15 @@ class StructureExecutor(BaseExecutor, Graph):
         )
 
     async def _handle_mail(self, mail: BaseMail):
+        """
+        Processes incoming mail based on its category, initiating node execution or structure operations accordingly.
+
+        Args:
+            mail (BaseMail): The mail to be processed, containing category and package information.
 
+        Raises:
+            ValueError: If the mail type is invalid for the current structure or an error occurs in handling the node ID.
+        """
         if mail.category == "start":
             return self.get_heads()
 
@@ -116,7 +176,7 @@ class StructureExecutor(BaseExecutor, Graph):
         else:
             raise ValueError(f"Invalid mail type for structure")
 
-    async def _next_node(self, current_node: BaseNode, executable_id, request_source):
+    async def _next_node(self, current_node: Node, executable_id, request_source):
         """
         Get the next step nodes based on the current node.
 
@@ -128,7 +188,7 @@ class StructureExecutor(BaseExecutor, Graph):
             list[Node]: The next step nodes.
         """
         next_nodes = []
-        next_edges: dict[Edge] = self.get_node_edges(current_node, node_as="out")
+        next_edges = self.get_node_edges(current_node, node_as="out")
         for edge in convert.to_list(list(next_edges.values())):
             if edge.bundle:
                 continue
@@ -139,7 +199,7 @@ class StructureExecutor(BaseExecutor, Graph):
                 if not check:
                     continue
             node = self.internal_nodes[edge.tail]
-            further_edges: dict[Edge] = self.get_node_edges(node, node_as="out")
+            further_edges = self.get_node_edges(node, node_as="out")
             bundled_nodes = deque()
             for f_edge in convert.to_list(list(further_edges.values())):
                 if f_edge.bundle:
@@ -150,6 +210,13 @@ class StructureExecutor(BaseExecutor, Graph):
         return next_nodes
 
     def _send_mail(self, next_nodes: list | None, mail: BaseMail):
+        """
+        Sends mails to the next nodes or signals the end of execution if no next nodes exist.
+
+        Args:
+            next_nodes (list | None): List of next nodes to process or None if no further nodes are available.
+            mail (BaseMail): The base mail used for sending follow-up actions.
+        """
         if not next_nodes:  # tail
             self.send(
                 recipient_id=mail.sender_id,
@@ -181,6 +248,26 @@ class StructureExecutor(BaseExecutor, Graph):
 
     @staticmethod
     def parse_bundled_to_action(instruction: Node, bundled_nodes: deque):
+        """
+        Constructs an action node from a bundle of nodes, combining various types of nodes like ActionSelection or Tool
+        into a single actionable unit.
+
+        This method takes a bundle of nodes and systematically integrates their functionalities into a single `ActionNode`.
+        This is crucial in scenarios where multiple actions or tools need to be executed sequentially or in a coordinated
+        manner as part of a larger instruction flow.
+
+        Args:
+            instruction (Node): The initial instruction node leading to this action.
+            bundled_nodes (deque): A deque containing nodes to be bundled into the action. These nodes typically represent
+                either actions to be taken or tools to be utilized.
+
+        Returns:
+            ActionNode: An `ActionNode` that encapsulates the combined functionality of the bundled nodes, ready for execution.
+
+        Raises:
+            ValueError: If an unrecognized node type is encountered within the bundled nodes. Only `ActionSelection` and
+                `Tool` nodes are valid for bundling into an `ActionNode`.
+        """
         action_node = ActionNode(instruction=instruction)
         while bundled_nodes:
             node = bundled_nodes.popleft()
@@ -201,7 +288,7 @@ class StructureExecutor(BaseExecutor, Graph):
             while self.pending_ins[key]:
                 mail: BaseMail = self.pending_ins[key].popleft()
                 try:
-                    if mail == "end":
+                    if mail.category == "end":
                         self.execute_stop = True
                         return
                     next_nodes = await self._handle_mail(mail)
@@ -210,9 +297,38 @@ class StructureExecutor(BaseExecutor, Graph):
                     raise ValueError(f"Error handling mail: {e}") from e
 
     async def execute(self, refresh_time=1):
+        """
+        Executes the forward processing loop, checking conditions and processing nodes at defined intervals.
+
+        Args:
+            refresh_time (int): The delay between execution cycles, allowing for asynchronous operations to complete.
+
+        Raises:
+            ValueError: If the graph structure is found to be cyclic, which is unsupported.
+        """
         if not self.acyclic:
             raise ValueError("Structure is not acyclic")
 
         while not self.execute_stop:
             await self.forward()
             await AsyncUtil.sleep(refresh_time)
+
+    def to_excel(self, structure_name, dir="structure_storage"):
+        """
+        Exports the current structure to an Excel file using a specified structure name and directory.
+
+        This method utilizes the `to_excel` function from the `lionagi.integrations.storage.to_excel` module,
+        saving the current structure instance into an Excel file format. The Excel file will contain details
+        about nodes, edges, and other relevant data as separate sheets within the file.
+
+        Args:
+            structure_name (str): The name to assign to the structure within the Excel file. This name is
+                                  used as part of the file naming convention.
+            dir (str, optional): The directory where the Excel file will be saved. Defaults to "structure_storage".
+
+        Raises:
+            Exception: Propagates any exceptions raised by the `to_excel` function, which might occur during
+                       the file writing process or data formatting.
+        """
+        from lionagi.integrations.storage.to_excel import to_excel
+        to_excel(self, structure_name, dir)

lionagi/core/flow/monoflow/ReAct.py

@@ -46,8 +46,7 @@ class MonoReAct(MonoChat):
     """
 
     ACTION_PROMPT = """
-    You have {num_steps} steps left in the current task. If further actions are needed, invoke tool usage.
-    If you are done, present the final result to the user without further tool usage.
+    You have {num_steps} steps left in the current task. invoke tool usage.
     """
 
     OUTPUT_PROMPT = "Notice: Present the final output to the user. Original user instruction: {instruction}"
@@ -127,15 +126,15 @@ class MonoReAct(MonoChat):
 
     def _create_followup_config(self, tools, tool_choice="auto", **kwargs):
         """
-        Creates the configuration for the followup steps based on the provided tools and parameters.
+        Creates the configuration for the followup chat based on the provided tools and parameters.
 
         Args:
-            tools (Optional[Any]): Specifies tools to be invoked during the followup steps.
+            tools (Optional[Any]): Specifies tools to be invoked during the followup chat.
             tool_choice (str): The choice of tools to use (default: "auto").
-            **kwargs: Additional keyword arguments for the followup configuration.
+            **kwargs: Additional keyword arguments for the followup chat configuration.
 
         Returns:
-            dict: The configuration for the followup steps.
+            dict: The configuration for the followup chat.
 
         Raises:
             ValueError: If no tools are found and registered.
@@ -146,7 +145,9 @@ class MonoReAct(MonoChat):
         if not self.branch.tool_manager.has_tools:
             raise ValueError("No tools found. You need to register tools.")
 
-        config = self.branch.tool_manager.parse_tool(tools=True, **kwargs)
+        if tools is None:
+            tools = True
+        config = self.branch.tool_manager.parse_tool(tools=tools, **kwargs)
         config["tool_parsed"] = True
         config["tool_choice"] = tool_choice
         return config
@@ -159,7 +160,7 @@ class MonoReAct(MonoChat):
         system=None,
         tools=None,
         num_rounds: int = 1,
-        auto=False,
+        auto=True,
         reason_prompt=None,
         action_prompt=None,
         output_prompt=None,
@@ -188,6 +189,7 @@ class MonoReAct(MonoChat):
             The result of the reasoning and action steps.
         """
         config = self._create_followup_config(tools, **kwargs)
+        kwargs.pop("tools", None)
 
         i = 0
         _out = ""
@@ -220,19 +222,19 @@ class MonoReAct(MonoChat):
 
             _out = await self.chat(_prompt, sender=sender, **config)
 
-            if auto and not self.branch._is_invoked():
+            if not self.branch._is_invoked():
                 return _out if out else None
 
             i += 1
 
-        if auto:
-            if not self.branch._is_invoked():
-                return _out if out else None
 
-            _prompt = self._get_prompt(
-                prompt=output_prompt,
-                default=self.OUTPUT_PROMPT,
-                instruction=instruction,
-            )
-            _out = await self.chat(_prompt, sender=sender, **kwargs)
-            return _out if out else None
+        if not self.branch._is_invoked():
+            return _out if out else None
+
+        _prompt = self._get_prompt(
+            prompt=output_prompt,
+            default=self.OUTPUT_PROMPT,
+            instruction=instruction,
+        )
+        _out = await self.chat(_prompt, sender=sender, **kwargs)
+        return _out if out else None

lionagi/core/flow/monoflow/chat_mixin.py

@@ -250,4 +250,4 @@ class MonoChatMixin(MonoChatConfigMixin, MonoChatInvokeMixin, ABC):
     Mixin class that combines MonoChatConfigMixin and MonoChatInvokeMixin.
     """
 
-    pass
+    pass

lionagi/core/flow/monoflow/followup.py

@@ -137,7 +137,9 @@ class MonoFollowup(MonoChat):
         if not self.branch.tool_manager.has_tools:
             raise ValueError("No tools found. You need to register tools.")
 
-        config = self.branch.tool_manager.parse_tool(tools=True, **kwargs)
+        if tools is None:
+            tools = True
+        config = self.branch.tool_manager.parse_tool(tools=tools, **kwargs)
         config["tool_parsed"] = True
         config["tool_choice"] = tool_choice
         return config
@@ -150,7 +152,7 @@ class MonoFollowup(MonoChat):
         system=None,
         tools=None,
         max_followup: int = 1,
-        auto=False,
+        auto=True,
         followup_prompt=None,
         output_prompt=None,
         out=True,
@@ -196,19 +198,18 @@ class MonoFollowup(MonoChat):
             else:
                 _out = await self.chat(_prompt, sender=sender, **config)
 
-            if auto and not self.branch._is_invoked():
+            if not self.branch._is_invoked():
                 return _out if out else None
 
             i += 1
 
-        if auto:
-            if not self.branch._is_invoked():
-                return _out if out else None
+        if not self.branch._is_invoked():
+            return _out if out else None
 
-            _prompt = self._get_prompt(
-                prompt=output_prompt,
-                default=self.OUTPUT_PROMPT,
-                instruction=instruction,
-            )
-            _out = await self.chat(_prompt, sender=sender, **kwargs)
-            return _out if out else None
+        _prompt = self._get_prompt(
+            prompt=output_prompt,
+            default=self.OUTPUT_PROMPT,
+            instruction=instruction,
+        )
+        _out = await self.chat(_prompt, sender=sender, **kwargs)
+        return _out if out else None

lionagi/core/flow/polyflow/__init__.py

@@ -1 +1 @@
-from .chat import PolyChat
+from .chat import PolyChat