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

lionagi/core/agent/base_agent.py

@@ -19,7 +19,7 @@ class BaseAgent(Node):
 
     def __init__(
         self,
-        structure: StructureExecutor,
+        structure: BaseExecutor,
         executable: BaseExecutor,
         output_parser=None,
         **kwargs,
@@ -33,7 +33,7 @@ class BaseAgent(Node):
             output_parser: A function for parsing the agent's output (optional).
         """
         super().__init__()
-        self.structure: StructureExecutor = structure
+        self.structure: BaseExecutor = structure
         self.executable: BaseExecutor = executable
         for v, k in kwargs.items():
             executable.__setattr__(v, k)
@@ -87,4 +87,3 @@ class BaseAgent(Node):
 
         if self.output_parser:
             return self.output_parser(self)
-        

lionagi/core/branch/base.py

@@ -650,4 +650,4 @@ class BaseBranch(BaseNode, ABC):
         messages = self.messages["sender"] if use_sender else self.messages["role"]
         result = messages.value_counts().to_dict()
         result["total"] = len(self.messages)
-        return result
+        return result

lionagi/core/branch/branch.py

@@ -470,4 +470,5 @@ class Branch(BaseBranch, BranchFlowMixin):
             }:
                 return True
         except Exception:
-            return False
+            return False
+        return False

lionagi/core/branch/flow_mixin.py

@@ -93,4 +93,4 @@ class BranchFlowMixin(ABC):
             output_prompt=output_prompt,
             out=out,
             **kwargs,
-        )
+        )

lionagi/core/branch/util.py

@@ -320,4 +320,4 @@ class MessageUtil:
             else:
                 with contextlib.suppress(Exception):
                     answers.append(nested.nget(content, ["system_info"]))
-        return "\n".join(answers)
+        return "\n".join(answers)

lionagi/core/execute/base_executor.py

@@ -18,7 +18,7 @@ class BaseExecutor(BaseComponent, ABC):
     execute_stop: bool = Field(
         False, description="A flag indicating whether to stop execution."
     )
-    context: dict | str | None = Field(
+    context: dict | str | list | None = Field(
         None, description="The context buffer for the next instruction."
     )
     execution_responses: list = Field(
@@ -28,9 +28,6 @@ class BaseExecutor(BaseComponent, ABC):
     verbose: bool = Field(
         True, description="A flag indicating whether to provide verbose output."
     )
-    execute_stop: bool = Field(
-        False, description="A flag indicating whether to stop execution."
-    )
 
     def send(self, recipient_id: str, category: str, package: Any) -> None:
         """

lionagi/core/execute/branch_executor.py

@@ -11,6 +11,10 @@ from lionagi.core.execute.base_executor import BaseExecutor
 class BranchExecutor(Branch, BaseExecutor):
 
     async def forward(self) -> None:
+        """
+        Forwards the execution by processing all pending incoming mails in each branch. Depending on the category of the mail,
+        it processes starts, nodes, node lists, conditions, or ends, accordingly executing different functions.
+        """
         for key in list(self.pending_ins.keys()):
             while self.pending_ins[key]:
                 mail = self.pending_ins[key].popleft()
@@ -26,11 +30,27 @@ class BranchExecutor(Branch, BaseExecutor):
                     self._process_end(mail)
 
     async def execute(self, refresh_time=1) -> None:
+        """
+        Executes the forward process repeatedly at specified time intervals until execution is instructed to stop.
+
+        Args:
+            refresh_time (int): The interval, in seconds, at which the forward method is called repeatedly.
+        """
         while not self.execute_stop:
             await self.forward()
             await AsyncUtil.sleep(refresh_time)
 
     async def _process_node(self, mail: BaseMail):
+        """
+        Processes a single node based on the node type specified in the mail's package. It handles different types of nodes such as System,
+        Instruction, ActionNode, and generic nodes through separate processes.
+
+        Args:
+            mail (BaseMail): The mail containing the node to be processed along with associated details.
+
+        Raises:
+            ValueError: If an invalid mail is encountered or the process encounters errors.
+        """
         if isinstance(mail.package["package"], System):
             self._system_process(mail.package["package"], verbose=self.verbose)
             self.send(
@@ -74,11 +94,26 @@ class BranchExecutor(Branch, BaseExecutor):
                 raise ValueError(f"Invalid mail to process. Mail:{mail}")
 
     def _process_node_list(self, mail: BaseMail):
+        """
+        Processes a list of nodes provided in the mail, but currently only sends an end signal as multiple path selection is not supported.
+
+        Args:
+            mail (BaseMail): The mail containing a list of nodes to be processed.
+
+        Raises:
+            ValueError: When trying to process multiple paths which is currently unsupported.
+        """
         self.send(mail.sender_id, "end", {"request_source": self.id_, "package": "end"})
         self.execute_stop = True
         raise ValueError("Multiple path selection is currently not supported")
 
     def _process_condition(self, mail: BaseMail):
+        """
+        Processes a condition associated with an edge based on the mail's package, setting up the result of the condition check.
+
+        Args:
+            mail (BaseMail): The mail containing the condition to be processed.
+        """
         relationship: Edge = mail.package["package"]
         check_result = relationship.condition(self)
         back_mail = {
@@ -93,6 +128,14 @@ class BranchExecutor(Branch, BaseExecutor):
         )
 
     def _system_process(self, system: System, verbose=True, context_verbose=False):
+        """
+        Processes a system node, possibly displaying its content and context if verbose is enabled.
+
+        Args:
+            system (System): The system node to process.
+            verbose (bool): Flag to enable verbose output.
+            context_verbose (bool): Flag to enable verbose output specifically for context.
+        """
         from lionagi.libs import SysUtil
 
         SysUtil.check_import("IPython")
@@ -111,6 +154,14 @@ class BranchExecutor(Branch, BaseExecutor):
     async def _instruction_process(
         self, instruction: Instruction, verbose=True, **kwargs
     ):
+        """
+        Processes an instruction node, possibly displaying its content if verbose is enabled, and handling any additional keyword arguments.
+
+        Args:
+            instruction (Instruction): The instruction node to process.
+            verbose (bool): Flag to enable verbose output.
+            **kwargs: Additional keyword arguments that might affect how instructions are processed.
+        """
         from lionagi.libs import SysUtil
 
         SysUtil.check_import("IPython")
@@ -146,6 +197,13 @@ class BranchExecutor(Branch, BaseExecutor):
         self.execution_responses.append(result)
 
     async def _action_process(self, action: ActionNode, verbose=True):
+        """
+        Processes an action node, executing the defined action along with any tools specified within the node.
+
+        Args:
+            action (ActionNode): The action node to process.
+            verbose (bool): Flag to enable verbose output of the action results.
+        """
         from lionagi.libs import SysUtil
 
         SysUtil.check_import("IPython")
@@ -196,7 +254,7 @@ class BranchExecutor(Branch, BaseExecutor):
             agent: The agent to process.
             verbose (bool): A flag indicating whether to provide verbose output (default: True).
         """
-        context = self.responses
+        context = list(self.messages["content"])
         if verbose:
             print("*****************************************************")
         result = await agent.execute(context)
@@ -204,8 +262,13 @@ class BranchExecutor(Branch, BaseExecutor):
         if verbose:
             print("*****************************************************")
 
-        self.context = result
-        self.responses.append(result)
+        from pandas import DataFrame
+
+        if isinstance(result, DataFrame):
+            self.context = list(result["content"])
+        else:
+            self.context = result
+        self.execution_responses.append(result)
 
     def _process_start(self, mail):
         """

lionagi/core/execute/instruction_map_executor.py

@@ -10,6 +10,18 @@ from lionagi.core.execute.branch_executor import BranchExecutor
 
 
 class InstructionMapExecutor(BaseExecutor):
+    """
+    Manages the execution of a mapped set of instructions across multiple branches within an executable structure.
+
+    Attributes:
+        branches (dict[str, BranchExecutor]): A dictionary of branch executors managing individual instruction flows.
+        structure_id (str): The identifier for the structure within which these branches operate.
+        mail_transfer (MailTransfer): Handles the transfer of mail between branches and other components.
+        branch_kwargs (dict): Keyword arguments used for initializing branches.
+        num_end_branches (int): Tracks the number of branches that have completed execution.
+        mail_manager (MailManager): Manages the distribution and collection of mails across branches.
+    """
+
     branches: dict[str, BranchExecutor] = Field(
         default_factory=dict, description="The branches of the instruction mapping."
     )
@@ -27,10 +39,20 @@ class InstructionMapExecutor(BaseExecutor):
     )
 
     def __init__(self, **kwargs):
+        """
+        Initializes an InstructionMapExecutor with the given parameters.
+
+        Args:
+            **kwargs: Arbitrary keyword arguments passed to the base executor and used for initializing branch executors.
+        """
         super().__init__(**kwargs)
         self.mail_manager = MailManager([self.mail_transfer])
 
     def transfer_ins(self):
+        """
+        Processes incoming mails, directing them appropriately based on their categories, and handles the initial setup
+        of branches or the routing of node and condition mails.
+        """
         for key in list(self.pending_ins.keys()):
             while self.pending_ins[key]:
                 mail: BaseMail = self.pending_ins[key].popleft()
@@ -48,6 +70,10 @@ class InstructionMapExecutor(BaseExecutor):
                     self.mail_transfer.pending_outs.append(mail)
 
     def transfer_outs(self):
+        """
+        Processes outgoing mails from the central mail transfer, handling end-of-execution notifications and routing
+        other mails to appropriate recipients.
+        """
         for key in list(self.mail_transfer.pending_ins.keys()):
             while self.mail_transfer.pending_ins[key]:
                 mail: BaseMail = self.mail_transfer.pending_ins[key].popleft()
@@ -66,6 +92,12 @@ class InstructionMapExecutor(BaseExecutor):
                     self.pending_outs.append(mail)
 
     def _process_start(self, start_mail: BaseMail):
+        """
+        Processes a start mail to initialize a new branch executor and configures it based on the mail's package content.
+
+        Args:
+            start_mail (BaseMail): The mail initiating the start of a new branch execution.
+        """
         branch = BranchExecutor(verbose=self.verbose, **self.branch_kwargs)
         branch.context = start_mail.package["context"]
         self.branches[branch.id_] = branch
@@ -80,6 +112,13 @@ class InstructionMapExecutor(BaseExecutor):
         self.pending_outs.append(mail)
 
     def _process_node_list(self, nl_mail: BaseMail):
+        """
+        Processes a node list mail, setting up new branches or propagating the execution context based on the node list
+        provided in the mail.
+
+        Args:
+            nl_mail (BaseMail): The mail containing a list of nodes to be processed in subsequent branches.
+        """
         source_branch_id = nl_mail.package["request_source"]
         node_list = nl_mail.package["package"]
         shared_context = self.branches[source_branch_id].context
@@ -115,6 +154,9 @@ class InstructionMapExecutor(BaseExecutor):
             self.mail_transfer.pending_outs.append(node_mail)
 
     async def forward(self):
+        """
+        Forwards the execution by processing all incoming and outgoing mails and advancing the state of all active branches.
+        """
         self.transfer_ins()
         self.transfer_outs()
         self.mail_manager.collect_all()
@@ -126,6 +168,12 @@ class InstructionMapExecutor(BaseExecutor):
         return
 
     async def execute(self, refresh_time=1):
+        """
+        Continuously executes the forward process at specified intervals until instructed to stop.
+
+        Args:
+            refresh_time (int): The time in seconds between execution cycles.
+        """
         while not self.execute_stop:
             await self.forward()
             await asyncio.sleep(refresh_time)

lionagi/core/execute/neo4j_executor.py

@@ -0,0 +1,381 @@
+from collections import deque
+import json
+from typing import Callable
+
+from lionagi.core.execute.base_executor import BaseExecutor
+from lionagi.integrations.storage.neo4j import Neo4j
+from lionagi.integrations.storage.storage_util import ParseNode
+from lionagi.core.generic import ActionNode
+from lionagi.core.agent.base_agent import BaseAgent
+from lionagi.core.execute.instruction_map_executor import InstructionMapExecutor
+
+from lionagi.core.mail.schema import BaseMail
+from lionagi.core.tool import Tool
+from lionagi.core.generic import ActionSelection, Edge
+
+from lionagi.libs import AsyncUtil
+
+
+class Neo4jExecutor(BaseExecutor):
+    """
+    Executes tasks within a Neo4j graph database, handling dynamic instruction flows and conditional logic across various nodes and agents.
+
+    Attributes:
+        driver (Neo4j | None): Connection driver to the Neo4j database.
+        structure_id (str | None): Identifier for the structure being executed within the graph.
+        structure_name (str | None): Name of the structure being executed.
+        middle_agents (list | None): List of agents operating within the structure.
+        default_agent_executable (BaseExecutor): Default executor for running tasks not handled by specific agents.
+        condition_check_result (bool | None): Result of the last condition check performed during execution.
+    """
+
+    driver: Neo4j | None
+    structure_id: str = None
+    structure_name: str = None
+    middle_agents: list | None = None
+    default_agent_executable: BaseExecutor = InstructionMapExecutor()
+    condition_check_result: bool | None = None
+
+    async def check_edge_condition(
+        self, condition, executable_id, request_source, head, tail
+    ):
+        """
+        Evaluates the condition associated with an edge in the graph, determining if execution should proceed along that edge.
+
+        Args:
+            condition: The condition object or logic to be evaluated.
+            executable_id (str): ID of the executor responsible for this condition check.
+            request_source (str): Origin of the request prompting this check.
+            head (str): ID of the head node in the edge.
+            tail (str): ID of the tail node in the edge.
+
+        Returns:
+            bool: Result of the condition check.
+        """
+        if condition.source_type == "structure":
+            return condition(self)
+        elif condition.source_type == "executable":
+            return await self._check_executable_condition(
+                condition, executable_id, head, tail, request_source
+            )
+
+    def _process_edge_condition(self, edge_id):
+        """
+        Process the condition of a edge.
+
+        Args:
+            edge_id (str): The ID of the edge.
+        """
+        for key in list(self.pending_ins.keys()):
+            skipped_requests = deque()
+            while self.pending_ins[key]:
+                mail: BaseMail = self.pending_ins[key].popleft()
+                if (
+                    mail.category == "condition"
+                    and mail.package["package"]["edge_id"] == edge_id
+                ):
+                    self.condition_check_result = mail.package["package"][
+                        "check_result"
+                    ]
+                else:
+                    skipped_requests.append(mail)
+            self.pending_ins[key] = skipped_requests
+
+    async def _check_executable_condition(
+        self, condition, executable_id, head, tail, request_source
+    ):
+        """
+        Sends a condition to be checked by an external executable and awaits the result.
+
+        Args:
+            condition: The condition object to be evaluated.
+            executable_id (str): ID of the executable that will evaluate the condition.
+            head (str): Starting node of the edge.
+            tail (str): Ending node of the edge.
+            request_source (str): Source of the request for condition evaluation.
+
+        Returns:
+            bool: The result of the condition check.
+        """
+        edge = Edge(head=head, tail=tail, condition=condition)
+        self.send(
+            recipient_id=executable_id,
+            category="condition",
+            package={"request_source": request_source, "package": edge},
+        )
+        while self.condition_check_result is None:
+            await AsyncUtil.sleep(0.1)
+            self._process_edge_condition(edge.id_)
+            continue
+        check_result = self.condition_check_result
+        self.condition_check_result = None
+        return check_result
+
+    @staticmethod
+    def parse_bundled_to_action(instruction, bundle_list):
+        """
+        Parses bundled actions and tools from a list of nodes, creating a composite action node from them.
+
+        Args:
+            instruction: The initial instruction leading to this bundle.
+            bundle_list (list): List of nodes bundled together.
+
+        Returns:
+            ActionNode: A node representing a composite action constructed from the bundled nodes.
+        """
+        bundled_nodes = deque()
+        for node_labels, node_properties in bundle_list:
+            try:
+                if "ActionSelection" in node_labels:
+                    node = ParseNode.parse_actionSelection(node_properties)
+                    bundled_nodes.append(node)
+                elif "Tool" in node_labels:
+                    node = ParseNode.parse_tool(node_properties)
+                    bundled_nodes.append(node)
+                else:
+                    raise ValueError(
+                        f"Invalid bundle node {node_properties.id}. Valid nodes are ActionSelection or Tool"
+                    )
+            except Exception as e:
+                raise ValueError(
+                    f"Failed to parse ActionSelection or Tool node {node_properties.id}. Error: {e}"
+                )
+
+        action_node = ActionNode(instruction=instruction)
+        while bundled_nodes:
+            node = bundled_nodes.popleft()
+            if isinstance(node, ActionSelection):
+                action_node.action = node.action
+                action_node.action_kwargs = node.action_kwargs
+            elif isinstance(node, Tool):
+                action_node.tools.append(node)
+        return action_node
+
+    def parse_agent(self, node_properties):
+        """
+        Parses agent properties and creates an agent executor.
+
+        Args:
+            node_properties (dict): Properties defining the agent.
+
+        Returns:
+            BaseAgent: An agent executor configured with the given properties.
+        """
+        output_parser = ParseNode.convert_to_def(node_properties["outputParser"])
+
+        structure = Neo4jExecutor(
+            driver=self.driver, structure_id=node_properties["structureId"]
+        )
+        agent = BaseAgent(
+            structure=structure,
+            executable=self.default_agent_executable,
+            output_parser=output_parser,
+        )
+        agent.id_ = node_properties["id"]
+        agent.timestamp = node_properties["timestamp"]
+        return agent
+
+    async def _next_node(
+        self, query_list, node_id=None, executable_id=None, request_source=None
+    ):
+        """
+        Processes the next set of nodes based on the results of a query list, applying conditions and preparing nodes
+        for further execution.
+
+        Args:
+            query_list (list): List of nodes and their properties.
+            node_id (str | None): Current node ID, if applicable.
+            executable_id (str | None): ID of the executor handling these nodes.
+            request_source (str | None): Source of the node processing request.
+
+        Returns:
+            list: Next nodes ready for processing.
+        """
+        next_nodes = []
+        for edge_properties, node_labels, node_properties in query_list:
+            if "condition" in edge_properties.keys():
+                try:
+                    condition = json.loads(edge_properties["condition"])
+                    condition_cls = await self.driver.get_condition_cls_code(
+                        condition["class"]
+                    )
+                    condition_obj = ParseNode.parse_condition(condition, condition_cls)
+
+                    head = node_id
+                    tail = node_properties["id"]
+                    check = await self.check_edge_condition(
+                        condition_obj, executable_id, request_source, head, tail
+                    )
+                    if not check:
+                        continue
+                except Exception as e:
+                    raise ValueError(
+                        f"Failed to use condition {edge_properties['condition']} from {node_id} to {node_properties['id']}, Error: {e}"
+                    )
+
+            try:
+                if "System" in node_labels:
+                    node = ParseNode.parse_system(node_properties)
+                elif "Instruction" in node_labels:
+                    node = ParseNode.parse_instruction(node_properties)
+                elif "Agent" in node_labels:
+                    node = self.parse_agent(node_properties)
+
+                else:
+                    raise ValueError(
+                        f"Invalid start node {node_properties.id}. Valid nodes are System or Instruction"
+                    )
+            except Exception as e:
+                raise ValueError(
+                    f"Failed to parse System or Instruction node {node_properties.id}. Error: {e}"
+                )
+
+            bundle_list = await self.driver.get_bundle(node.id_)
+
+            if bundle_list and "System" in node_labels:
+                raise ValueError("System node does not support bundle edge")
+            if bundle_list:
+                node = self.parse_bundled_to_action(node, bundle_list)
+            next_nodes.append(node)
+        return next_nodes
+
+    async def _handle_start(self):
+        """
+        Handles the start of execution, fetching and processing head nodes from the structure.
+
+        Raises:
+            ValueError: If there is an issue with finding or starting the structure.
+        """
+        try:
+            id, head_list = await self.driver.get_heads(
+                self.structure_name, self.structure_id
+            )
+            self.structure_id = id
+            return await self._next_node(head_list)
+        except Exception as e:
+            raise ValueError(f"Error in searching for structure in Neo4j. Error: {e}")
+
+    async def _handle_node_id(self, node_id, executable_id, request_source):
+        """
+        Handles the processing of a specific node ID, fetching its forward connections and conditions.
+
+        Args:
+            node_id (str): The node ID to process.
+            executable_id (str): ID of the executor handling this node.
+            request_source (str): Source of the node processing request.
+
+        Returns:
+            list: Next nodes derived from the given node ID.
+        """
+        check = await self.driver.node_exist(node_id)
+        if not check:
+            raise ValueError(f"Node {node_id} if not found in the database")
+        node_list = await self.driver.get_forwards(node_id)
+        return await self._next_node(node_list, node_id, executable_id, request_source)
+
+    async def _handle_mail(self, mail: BaseMail):
+        """
+        Processes incoming mail, determining the next action based on the mail's category and content.
+
+        Args:
+            mail (BaseMail): The incoming mail to be processed.
+
+        Raises:
+            ValueError: If there is an error processing the mail.
+        """
+        if mail.category == "start":
+            try:
+                return await self._handle_start()
+            except Exception as e:
+                raise ValueError(f"Error in start. Error: {e}")
+
+        elif mail.category == "end":
+            self.execute_stop = True
+            return None
+
+        elif mail.category == "node_id":
+            try:
+                node_id = mail.package["package"]
+                executable_id = mail.sender_id
+                request_source = mail.package["request_source"]
+                return await self._handle_node_id(
+                    node_id, executable_id, request_source
+                )
+            except Exception as e:
+                raise ValueError(f"Error in handling node_id: {e}")
+        elif mail.category == "node":
+            try:
+                node_id = mail.package["package"].id_
+                executable_id = mail.sender_id
+                request_source = mail.package["request_source"]
+                return await self._handle_node_id(
+                    node_id, executable_id, request_source
+                )
+            except Exception as e:
+                raise ValueError(f"Error in handling node: {e}")
+        else:
+            raise ValueError(f"Invalid mail type for structure")
+
+    def _send_mail(self, next_nodes: list | None, mail: BaseMail):
+        """
+        Sends out mail to the next nodes or marks the execution as ended if there are no next nodes.
+
+        Args:
+            next_nodes (list | None): List of next nodes to which mail should be sent.
+            mail (BaseMail): The current mail being processed.
+        """
+        if not next_nodes:  # tail
+            self.send(
+                recipient_id=mail.sender_id,
+                category="end",
+                package={
+                    "request_source": mail.package["request_source"],
+                    "package": "end",
+                },
+            )
+        else:
+            if len(next_nodes) == 1:
+                self.send(
+                    recipient_id=mail.sender_id,
+                    category="node",
+                    package={
+                        "request_source": mail.package["request_source"],
+                        "package": next_nodes[0],
+                    },
+                )
+            else:
+                self.send(
+                    recipient_id=mail.sender_id,
+                    category="node_list",
+                    package={
+                        "request_source": mail.package["request_source"],
+                        "package": next_nodes,
+                    },
+                )
+
+    async def forward(self) -> None:
+        """
+        Forwards execution by processing all pending mails and advancing to next nodes or actions.
+        """
+        for key in list(self.pending_ins.keys()):
+            while self.pending_ins[key]:
+                mail: BaseMail = self.pending_ins[key].popleft()
+                try:
+                    if mail == "end":
+                        self.execute_stop = True
+                        return
+                    next_nodes = await self._handle_mail(mail)
+                    self._send_mail(next_nodes, mail)
+                except Exception as e:
+                    raise ValueError(f"Error handling mail: {e}") from e
+
+    async def execute(self, refresh_time=1):
+        """
+        Continuously executes the forward process at specified intervals until instructed to stop.
+
+        Args:
+            refresh_time (int): The time in seconds between execution cycles.
+        """
+        while not self.execute_stop:
+            await self.forward()
+            await AsyncUtil.sleep(refresh_time)