lionagi 0.13.2__py3-none-any.whl → 0.13.4__py3-none-any.whl

lionagi/operations/flow.py

@@ -0,0 +1,436 @@
+# Copyright (c) 2023 - 2025, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import asyncio
+from typing import Any
+
+from lionagi.operations.node import Operation
+from lionagi.protocols.types import Graph, Node
+from lionagi.session.branch import Branch
+from lionagi.session.session import Session
+from lionagi.utils import to_dict
+
+
+async def flow(
+    branch: Branch,
+    graph: Graph,
+    *,
+    context: dict[str, Any] | None = None,
+    parallel: bool = True,
+    max_concurrent: int = 5,
+    verbose: bool = False,
+    session: Session | None = None,
+) -> dict[str, Any]:
+    """
+    Execute a graph-based workflow using the branch's operations.
+
+    For simple graphs, executes directly on the branch.
+    For parallel execution, uses session for coordination.
+
+    Args:
+        branch: The branch to execute operations on
+        graph: The workflow graph containing Operation nodes
+        context: Initial context
+        parallel: Whether to execute independent operations in parallel
+        max_concurrent: Max concurrent operations
+        verbose: Enable verbose logging
+        session: Optional session for multi-branch parallel execution
+
+    Returns:
+        Execution results with completed operations and final context
+    """
+    # Validate graph
+    if not graph.is_acyclic():
+        raise ValueError("Graph must be acyclic for flow execution")
+
+    # Simple sequential execution on single branch
+    if not parallel or max_concurrent == 1:
+        return await _execute_sequential(branch, graph, context, verbose)
+
+    # Parallel execution using session
+    if session is None:
+        # Create temporary session for this flow
+        from lionagi.session.session import Session
+
+        session = Session()
+        session.branches.include(branch)
+        session.default_branch = branch
+
+    return await _execute_parallel(
+        session, graph, context, max_concurrent, verbose
+    )
+
+
+async def _execute_sequential(
+    branch: Branch, graph: Graph, context: dict[str, Any] | None, verbose: bool
+) -> dict[str, Any]:
+    """Execute graph sequentially on a single branch."""
+    completed = []
+    results = {}
+    execution_context = context or {}
+
+    # Get execution order (topological sort)
+    execution_order = _topological_sort(graph)
+
+    for node_id in execution_order:
+        node = graph.internal_nodes[node_id]
+
+        if not isinstance(node, Operation):
+            continue
+
+        # Check dependencies using set for fast lookup
+        completed_set = set(completed)
+
+        # Check if dependencies and conditions are satisfied
+        if not await _dependencies_satisfied_async(
+            node, graph, completed_set, results, execution_context
+        ):
+            continue
+
+        predecessors = graph.get_predecessors(node)
+
+        # Update operation context with predecessors
+        if predecessors:
+            pred_context = {}
+            for pred in predecessors:
+                if pred.id in results:
+                    result = results[pred.id]
+                # Use to_dict for proper serialization of complex types only
+                if result is not None and not isinstance(
+                    result, (str, int, float, bool)
+                ):
+                    result = to_dict(result, recursive=True)
+                pred_context[f"{pred.id}_result"] = result
+
+            if "context" not in node.parameters:
+                node.parameters["context"] = pred_context
+            else:
+                node.parameters["context"].update(pred_context)
+
+        # Add execution context
+        if execution_context:
+            if "context" not in node.parameters:
+                node.parameters["context"] = execution_context.copy()
+            else:
+                node.parameters["context"].update(execution_context)
+
+        # Execute operation
+        if verbose:
+            print(f"Executing operation: {node.id}")
+
+        await node.invoke(branch)
+
+        completed.append(node.id)
+        results[node.id] = node.response
+
+        # Update execution context
+        if isinstance(node.response, dict) and "context" in node.response:
+            execution_context.update(node.response["context"])
+
+    return {
+        "completed_operations": completed,
+        "operation_results": results,
+        "final_context": execution_context,
+    }
+
+
+async def _execute_parallel(
+    session: Session,
+    graph: Graph,
+    context: dict[str, Any] | None,
+    max_concurrent: int,
+    verbose: bool,
+) -> dict[str, Any]:
+    """Execute graph in parallel using multiple branches."""
+    results = {}
+    execution_context = context or {}
+    completed = []  # Track completed operations
+
+    # Get operation nodes in topological order
+    operation_nodes = []
+    execution_order = _topological_sort(graph)
+    for node_id in execution_order:
+        node = graph.internal_nodes.get(node_id)
+        if isinstance(node, Operation):
+            operation_nodes.append(node)
+
+    # Use session branches context manager for safe parallel execution
+    async with session.branches:
+        # Create a pool of worker branches
+        worker_branches = []
+        for i in range(min(max_concurrent, len(operation_nodes))):
+            if i == 0:
+                worker_branches.append(session.default_branch)
+            else:
+                worker_branches.append(session.split(session.default_branch))
+
+        # Process nodes in dependency order
+        remaining_nodes = {node.id for node in operation_nodes}
+        executing_tasks = {}  # node_id -> asyncio.Task
+        blocked_nodes = set()  # Nodes that have been checked and found blocked
+
+        max_iterations = 1000  # Prevent infinite loops
+        iteration = 0
+
+        while (
+            remaining_nodes or executing_tasks
+        ) and iteration < max_iterations:
+            iteration += 1
+
+            # Check for completed tasks
+            completed_in_round = []
+            for node_id, task in list(executing_tasks.items()):
+                if task.done():
+                    try:
+                        result = await task
+                        results[node_id] = result
+                        completed.append(node_id)
+                        completed_in_round.append(node_id)
+                        if verbose:
+                            print(f"Completed operation: {node_id}")
+                    except Exception as e:
+                        if verbose:
+                            print(f"Operation {node_id} failed: {e}")
+                        results[node_id] = {"error": str(e)}
+                        completed.append(node_id)
+                        completed_in_round.append(node_id)
+                    finally:
+                        del executing_tasks[node_id]
+
+            # Remove completed from remaining
+            remaining_nodes -= set(completed_in_round)
+
+            # If new completions, clear blocked nodes to re-check
+            if completed_in_round:
+                blocked_nodes.clear()
+
+            # Find nodes ready to execute (skip already blocked nodes)
+            ready_nodes = []
+            completed_set = set(completed)
+            newly_blocked = []
+
+            for node in operation_nodes:
+                if (
+                    node.id in remaining_nodes
+                    and node.id not in executing_tasks
+                    and node.id not in blocked_nodes
+                    and len(executing_tasks) < max_concurrent
+                ):
+                    if await _dependencies_satisfied_async(
+                        node, graph, completed_set, results, execution_context
+                    ):
+                        ready_nodes.append(node)
+                    else:
+                        newly_blocked.append(node.id)
+
+            # Update blocked nodes
+            blocked_nodes.update(newly_blocked)
+
+            # If no ready nodes but we have remaining and no executing tasks, we're stuck
+            if not ready_nodes and remaining_nodes and not executing_tasks:
+                if verbose:
+                    print(
+                        f"Deadlock detected: {len(remaining_nodes)} nodes cannot execute"
+                    )
+                    remaining_node_names = [
+                        n.operation
+                        for n in operation_nodes
+                        if n.id in remaining_nodes
+                    ]
+                    print(f"Remaining operations: {remaining_node_names}")
+                # Mark remaining nodes as failed
+                for node in operation_nodes:
+                    if node.id in remaining_nodes:
+                        results[node.id] = {
+                            "error": "Blocked by unsatisfied conditions"
+                        }
+                        completed.append(node.id)
+                break
+
+            # Start execution for ready nodes
+            started_count = 0
+            for node in ready_nodes:
+                if len(executing_tasks) >= max_concurrent:
+                    break
+
+                # Get an available branch (round-robin)
+                branch_idx = len(executing_tasks) % len(worker_branches)
+                node_branch = worker_branches[branch_idx]
+
+                # Check if node specifies a branch
+                branch_id = node.parameters.get("branch_id")
+                if branch_id:
+                    try:
+                        node_branch = session.branches[branch_id]
+                    except:
+                        pass  # Use the selected worker branch
+
+                # Create task for this node
+                task = asyncio.create_task(
+                    _execute_node_async(
+                        node,
+                        node_branch,
+                        graph,
+                        results,
+                        execution_context,
+                        verbose,
+                    )
+                )
+                executing_tasks[node.id] = task
+                started_count += 1
+
+                if verbose:
+                    branch_name = (
+                        getattr(node_branch, "name", None) or node_branch.id
+                    )
+                    print(
+                        f"Started operation {node.id} on branch: {branch_name}"
+                    )
+
+            # If we started new tasks or have executing tasks, wait for some to complete
+            if started_count > 0 or executing_tasks:
+                # Wait for at least one task to complete before next iteration
+                if executing_tasks:
+                    done, pending = await asyncio.wait(
+                        executing_tasks.values(),
+                        return_when=asyncio.FIRST_COMPLETED,
+                    )
+                else:
+                    await asyncio.sleep(0.01)
+            elif not remaining_nodes:
+                # All done
+                break
+
+        if iteration >= max_iterations:
+            raise RuntimeError(
+                f"Flow execution exceeded maximum iterations ({max_iterations})"
+            )
+
+    return {
+        "completed_operations": completed,
+        "operation_results": results,
+        "final_context": execution_context,
+    }
+
+
+async def _execute_node_async(
+    node: Operation,
+    branch: Branch,
+    graph: Graph,
+    results: dict[str, Any],
+    execution_context: dict[str, Any],
+    verbose: bool,
+) -> Any:
+    """Execute a single node asynchronously."""
+    # Update operation context with predecessors
+    predecessors = graph.get_predecessors(node)
+    if predecessors:
+        pred_context = {}
+        for pred in predecessors:
+            if pred.id in results:
+                result = results[pred.id]
+                # Use to_dict for proper serialization of complex types only
+                if result is not None and not isinstance(
+                    result, (str, int, float, bool)
+                ):
+                    result = to_dict(result, recursive=True)
+                pred_context[f"{pred.id}_result"] = result
+
+        if "context" not in node.parameters:
+            node.parameters["context"] = pred_context
+        else:
+            node.parameters["context"].update(pred_context)
+
+    # Add execution context
+    if execution_context:
+        if "context" not in node.parameters:
+            node.parameters["context"] = execution_context.copy()
+        else:
+            node.parameters["context"].update(execution_context)
+
+    # Execute the operation
+    await node.invoke(branch)
+    result = node.response
+
+    # Update execution context if needed
+    if isinstance(result, dict) and "context" in result:
+        execution_context.update(result["context"])
+
+    return result
+
+
+def _topological_sort(graph: Graph) -> list[str]:
+    """Get topological ordering of graph nodes."""
+    visited = set()
+    stack = []
+
+    def visit(node_id: str):
+        if node_id in visited:
+            return
+        visited.add(node_id)
+
+        successors = graph.get_successors(graph.internal_nodes[node_id])
+        for successor in successors:
+            visit(successor.id)
+
+        stack.append(node_id)
+
+    for node in graph.internal_nodes:
+        if node.id not in visited:
+            visit(node.id)
+
+    return stack[::-1]
+
+
+async def _dependencies_satisfied_async(
+    node: Node,
+    graph: Graph,
+    completed: set[str],
+    results: dict[str, Any],
+    execution_context: dict[str, Any] | None = None,
+) -> bool:
+    """Check if node dependencies are satisfied and edge conditions pass."""
+    # Get all incoming edges to this node
+    incoming_edges = []
+    for edge in graph.internal_edges:
+        if edge.tail == node.id:
+            incoming_edges.append(edge)
+
+    # If no incoming edges, node can execute
+    if not incoming_edges:
+        return True
+
+    # Check each incoming edge
+    at_least_one_satisfied = False
+    for edge in incoming_edges:
+        # Check if predecessor is completed
+        if edge.head not in completed:
+            # If edge has no condition, we need to wait for predecessor
+            if not edge.condition:
+                continue
+            # If edge has condition but predecessor not complete, skip
+            continue
+
+        # Predecessor is completed
+        if edge.condition:
+            # Evaluate condition
+            # Get the result - don't use to_dict if it's already a simple type
+            result_value = results.get(edge.head)
+            if result_value is not None and not isinstance(
+                result_value, (str, int, float, bool)
+            ):
+                result_value = to_dict(result_value, recursive=True)
+
+            ctx = {"result": result_value, "context": execution_context or {}}
+            try:
+                if await edge.condition.apply(ctx):
+                    at_least_one_satisfied = True
+            except Exception as e:
+                # Condition evaluation failed
+                continue
+        else:
+            # No condition, edge is satisfied
+            at_least_one_satisfied = True
+
+    return at_least_one_satisfied

lionagi/operations/interpret/interpret.py

@@ -23,10 +23,7 @@ async def interpret(
         "Return only the re-written prompt. Do not assume any details not mentioned in the input, nor "
         "give additional instruction than what is explicitly stated."
     )
-    guidance = (
-        f"Domain hint: {domain or 'general'}. "
-        f"Desired style: {style or 'concise'}. "
-    )
+    guidance = f"Domain hint: {domain or 'general'}. Desired style: {style or 'concise'}. "
     if sample_writing:
         guidance += f" Sample writing: {sample_writing}"
 

lionagi/operations/manager.py

@@ -8,7 +8,6 @@ experimental
 
 
 class OperationManager(Manager):
-
     def __init__(self, *args, **kwargs):
         super().__init__()
         self.registry: dict[str, Callable] = {}

lionagi/operations/node.py

@@ -0,0 +1,107 @@
+import asyncio
+import logging
+from typing import Any, Literal
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+from lionagi.protocols.types import ID, Event, EventStatus, IDType, Node
+from lionagi.session.branch import Branch
+
+BranchOperations = Literal[
+    "chat",
+    "operate",
+    "communicate",
+    "parse",
+    "ReAct",
+    "select",
+    "translate",
+    "interpret",
+    "act",
+    "ReActStream",
+    "instruct",
+]
+
+logger = logging.getLogger("operation")
+
+
+class Operation(Node, Event):
+    operation: BranchOperations
+    parameters: dict[str, Any] | BaseModel = Field(
+        default_factory=dict, description="Parameters for the operation"
+    )
+
+    @property
+    def branch_id(self) -> IDType | None:
+        if a := self.metadata.get("branch_id"):
+            return ID.get_id(a)
+
+    @branch_id.setter
+    def branch_id(self, value: str | UUID | IDType | None):
+        if value is None:
+            self.metadata.pop("branch_id", None)
+        else:
+            self.metadata["branch_id"] = str(value)
+
+    @property
+    def graph_id(self) -> str | None:
+        return self.metadata.get("graph_id")
+
+    @graph_id.setter
+    def graph_id(self, value: str | UUID | IDType | None):
+        if value is None:
+            self.metadata.pop("graph_id", None)
+        else:
+            self.metadata["graph_id"] = str(value)
+
+    @property
+    def request(self) -> dict:
+        # Convert parameters to dict if it's a BaseModel
+        params = self.parameters
+        if hasattr(params, "model_dump"):
+            params = params.model_dump()
+        elif hasattr(params, "dict"):
+            params = params.dict()
+
+        return params if isinstance(params, dict) else {}
+
+    @property
+    def response(self):
+        """Get the response from the execution."""
+        return self.execution.response if self.execution else None
+
+    async def invoke(self, branch: Branch):
+        meth = getattr(branch, self.operation, None)
+        if meth is None:
+            raise ValueError(f"Unsupported operation type: {self.operation}")
+
+        start = asyncio.get_event_loop().time()
+
+        try:
+            self.execution.status = EventStatus.PROCESSING
+            self.branch_id = branch.id
+            response = await self._invoke(meth)
+
+            self.execution.response = response
+            self.execution.status = EventStatus.COMPLETED
+
+        except asyncio.CancelledError:
+            self.execution.error = "Operation cancelled"
+            self.execution.status = EventStatus.FAILED
+            raise
+
+        except Exception as e:
+            self.execution.error = str(e)
+            self.execution.status = EventStatus.FAILED
+            logger.error(f"Operation failed: {e}")
+
+        finally:
+            self.execution.duration = asyncio.get_event_loop().time() - start
+
+    async def _invoke(self, meth):
+        if self.operation == "ReActStream":
+            res = []
+            async for i in meth(**self.request):
+                res.append(i)
+            return res
+        return await meth(**self.request)

lionagi/operations/plan/plan.py

@@ -231,7 +231,6 @@ async def plan(
 
         # We now handle multiple strategies:
         match execution_strategy:
-
             # ---------------------------------------------------------
             # Strategy A: SEQUENTIAL
             # ---------------------------------------------------------

lionagi/operations/select/utils.py

@@ -65,7 +65,6 @@ def parse_to_representation(
 
 
 def get_choice_representation(choice: Any) -> str:
-
     if isinstance(choice, str):
         return choice
 
@@ -77,7 +76,6 @@ def get_choice_representation(choice: Any) -> str:
 
 
 def parse_selection(selection_str: str, choices: Any):
-
     select_from = []
 
     if isinstance(choices, dict):

lionagi/protocols/forms/flow.py

@@ -46,7 +46,9 @@ class FlowDefinition(BaseModel):
             ins_str, outs_str = seg.split("->", 1)
             inputs = [x.strip() for x in ins_str.split(",") if x.strip()]
             outputs = [y.strip() for y in outs_str.split(",") if y.strip()]
-            step = FlowStep(name=f"step_{i+1}", inputs=inputs, outputs=outputs)
+            step = FlowStep(
+                name=f"step_{i + 1}", inputs=inputs, outputs=outputs
+            )
             self.steps.append(step)
 
     def get_required_fields(self) -> set[str]:

lionagi/protocols/generic/pile.py

@@ -851,8 +851,7 @@ class Pile(Element, Collective[E], Generic[E]):
                 if self.strict_type:
                     if type(i) not in self.item_type:
                         raise TypeError(
-                            "Invalid item type in pile."
-                            f" Expected {self.item_type}",
+                            f"Invalid item type in pile. Expected {self.item_type}",
                         )
                 else:
                     if not any(issubclass(type(i), t) for t in self.item_type):

lionagi/protocols/generic/processor.py

@@ -149,7 +149,6 @@ class Processor(Observer):
                 next_event = await self.dequeue()
 
             if await self.request_permission(**next_event.request):
-
                 if next_event.streaming:
                     task = asyncio.create_task(next_event.stream())
                 else:

lionagi/protocols/graph/__init__.py

@@ -1,3 +1,9 @@
 # Copyright (c) 2023 - 2025, HaiyangLi <quantocean.li at gmail dot com>
 #
 # SPDX-License-Identifier: Apache-2.0
+
+from .edge import Edge, EdgeCondition
+from .graph import Graph
+from .node import Node
+
+__all__ = ["Edge", "EdgeCondition", "Graph", "Node"]

lionagi/protocols/graph/graph.py

@@ -21,7 +21,6 @@ __all__ = ("Graph",)
 
 
 class Graph(Element, Relational):
-
     internal_nodes: Pile[Node] = Field(
         default_factory=lambda: Pile(item_type={Node}, strict_type=False),
         title="Internal Nodes",
@@ -52,8 +51,7 @@ class Graph(Element, Relational):
         """Add a node to the graph."""
         if not isinstance(node, Relational):
             raise RelationError(
-                "Failed to add node: Invalid node type: "
-                "not a <Relational> entity."
+                "Failed to add node: Invalid node type: not a <Relational> entity."
             )
         _id = ID.get_id(node)
         try:

lionagi/protocols/mail/package.py

@@ -91,7 +91,6 @@ class Package(Observable):
         item: Any,
         request_source: ID[Communicatable] = None,
     ):
-
         super().__init__()
         self.id = IDType.create()
         self.created_at = time(type_="timestamp")

lionagi/protocols/messages/assistant_response.py

@@ -15,7 +15,6 @@ from .message import MessageRole, RoledMessage, Template, jinja_env
 def prepare_assistant_response(
     assistant_response: BaseModel | list[BaseModel] | dict | str | Any, /
 ) -> dict:
-
     assistant_response = (
         [assistant_response]
         if not isinstance(assistant_response, list)
@@ -26,7 +25,6 @@ def prepare_assistant_response(
     model_responses = []
 
     for i in assistant_response:
-
         if isinstance(i, BaseModel):
             i = i.model_dump(exclude_none=True, exclude_unset=True)
 

lionagi/protocols/messages/message.py

@@ -232,7 +232,6 @@ class RoledMessage(Node, Sendable):
             self.template = template
 
     def __str__(self) -> str:
-
         content_preview = (
             f"{str(self.content)[:75]}..."
             if len(str(self.content)) > 75