quantalogic 0.50.29__py3-none-any.whl → 0.52.0__py3-none-any.whl

quantalogic/flow/__init__.py

@@ -3,13 +3,26 @@ Flow Package Initialization
 
 This module initializes the flow package and provides package-level imports.
 Now supports nested workflows for hierarchical flow definitions.
+
+Key Visualization Utilities:
+- generate_mermaid_diagram(): Convert workflow definitions to visual Mermaid flowcharts
+    - Supports pastel-colored node styling
+    - Generates interactive, readable workflow diagrams
+    - Handles complex workflows with multiple node types
+
+    - Generates descriptive labels
+    - Supports conditional node detection
 """
 
 from loguru import logger
 
 # Expose key components for easy importing
 from .flow import Nodes, Workflow, WorkflowEngine
+from .flow_extractor import extract_workflow_from_file
+from .flow_generator import generate_executable_script
 from .flow_manager import WorkflowManager
+from .flow_mermaid import generate_mermaid_diagram
+from .flow_validator import validate_workflow_definition
 
 # Define which symbols are exported when using `from flow import *`
 __all__ = [
@@ -17,6 +30,10 @@ __all__ = [
     "Nodes",
     "Workflow",
     "WorkflowEngine",
+    "generate_mermaid_diagram",
+    "extract_workflow_from_file",
+    "generate_executable_script",
+    "validate_workflow_definition"
 ]
 
 # Package-level logger configuration

quantalogic/flow/flow.py

@@ -71,7 +71,7 @@ class WorkflowEngine:
     def __init__(self, workflow, parent_engine: Optional["WorkflowEngine"] = None):
         """Initialize the WorkflowEngine with a workflow and optional parent for sub-workflows."""
         self.workflow = workflow
-        self.context = {}
+        self.context: Dict[str, Any] = {}
         self.observers: List[WorkflowObserver] = []
         self.parent_engine = parent_engine  # Link to parent engine for sub-workflow observer propagation
 
@@ -302,7 +302,7 @@ class Workflow:
 
 
 class Nodes:
-    NODE_REGISTRY = {}  # Registry to hold node functions and metadata
+    NODE_REGISTRY: Dict[str, Tuple[Callable, List[str], Optional[str]]] = {}  # Registry to hold node functions and metadata
 
     @classmethod
     def define(cls, output: Optional[str] = None):
@@ -485,8 +485,8 @@ async def example_workflow():
     # Define Pydantic model for structured output
     class OrderDetails(BaseModel):
         order_id: str
-        items: List[str]
-        in_stock: bool
+        items_in_stock: List[str]
+        items_out_of_stock: List[str]
 
     # Define an example observer for progress
     async def progress_monitor(event: WorkflowEvent):
@@ -533,7 +533,9 @@ async def example_workflow():
         output="inventory_status",
     )
     async def check_inventory(items: List[str]) -> OrderDetails:
-        pass
+        # This is a placeholder function that would normally call an LLM
+        # The actual implementation is handled by the structured_llm_node decorator
+        return OrderDetails(order_id="123", items_in_stock=["item1"], items_out_of_stock=[])
 
     @Nodes.define(output="payment_status")
     async def process_payment(order: Dict[str, Any]) -> str:
@@ -572,11 +574,11 @@ async def example_workflow():
         .sequence("validate_order", "check_inventory")
         .then(
             "payment_shipping",
-            condition=lambda ctx: ctx.get("inventory_status").in_stock if ctx.get("inventory_status") else False,
+            condition=lambda ctx: len(ctx.get("inventory_status").items_out_of_stock) == 0 if ctx.get("inventory_status") else False,
         )
         .then(
             "notify_customer_out_of_stock",
-            condition=lambda ctx: not ctx.get("inventory_status").in_stock if ctx.get("inventory_status") else True,
+            condition=lambda ctx: len(ctx.get("inventory_status").items_out_of_stock) > 0 if ctx.get("inventory_status") else True,
         )
         .parallel("update_order_status", "send_confirmation_email")
         .node("update_order_status")

quantalogic/flow/flow_extractor.py

@@ -3,6 +3,7 @@ import os
 
 from loguru import logger
 
+from quantalogic.flow.flow_generator import generate_executable_script  # Import from flow_generator
 from quantalogic.flow.flow_manager import WorkflowManager  # Added for YAML saving
 from quantalogic.flow.flow_manager_schema import (
     FunctionDefinition,
@@ -396,7 +397,7 @@ class WorkflowExtractor(ast.NodeVisitor):
                     "sub_workflow": WorkflowStructure(
                         start=sub_extractor.start_node,
                         transitions=[
-                            TransitionDefinition(from_=t[0], to=t[1], condition=t[2]) for t in sub_extractor.transitions
+                            TransitionDefinition(from_node=t[0], to_node=t[1], condition=t[2]) for t in sub_extractor.transitions
                         ],
                     ),
                     "inputs": list(inputs.keys()),
@@ -494,7 +495,7 @@ def extract_workflow_from_file(file_path):
 
     # Construct TransitionDefinition objects
     transitions = [
-        TransitionDefinition(**{"from": from_node, "to": to_node, "condition": cond})
+        TransitionDefinition(from_node=from_node, to_node=to_node, condition=cond)
         for from_node, to_node, cond in extractor.transitions
     ]
 
@@ -509,92 +510,7 @@ def extract_workflow_from_file(file_path):
     return workflow_def, extractor.global_vars
 
 
-def generate_executable_script(workflow_def: WorkflowDefinition, global_vars: dict, output_file: str) -> None:
-    """
-    Generate an executable Python script from a WorkflowDefinition with global variables.
-
-    Args:
-        workflow_def: The WorkflowDefinition object containing the workflow details.
-        global_vars: Dictionary of global variables extracted from the source file.
-        output_file: The path where the executable script will be written.
-
-    The generated script includes:
-    - A shebang using `uv run` for environment management.
-    - Metadata specifying the required Python version and dependencies.
-    - Global variables from the original script.
-    - Embedded functions included directly in the script.
-    - Workflow instantiation using direct chaining syntax.
-    - A default initial_context matching the example.
-    """
-    with open(output_file, "w") as f:
-        # Write the shebang and metadata
-        f.write("#!/usr/bin/env -S uv run\n")
-        f.write("# /// script\n")
-        f.write('# requires-python = ">=3.12"\n')
-        f.write("# dependencies = [\n")
-        f.write('#     "loguru",\n')
-        f.write('#     "litellm",\n')
-        f.write('#     "pydantic>=2.0",\n')
-        f.write('#     "anyio",\n')
-        f.write('#     "quantalogic>=0.35",\n')
-        f.write('#     "jinja2",\n')
-        f.write('#     "instructor[litellm]",\n')  # Kept for potential structured LLM support
-        f.write("# ]\n")
-        f.write("# ///\n\n")
-
-        # Write necessary imports
-        f.write("import anyio\n")
-        f.write("from typing import List\n")
-        f.write("from loguru import logger\n")
-        f.write("from quantalogic.flow import Nodes, Workflow\n\n")
-
-        # Write global variables
-        for var_name, value in global_vars.items():
-            f.write(f"{var_name} = {repr(value)}\n")
-        f.write("\n")
-
-        # Embed functions from workflow_def
-        for func_name, func_def in workflow_def.functions.items():
-            if func_def.type == "embedded":
-                f.write(func_def.code + "\n\n")
-
-        # Define workflow using chaining syntax
-        f.write("# Define the workflow using simplified syntax with automatic node registration\n")
-        f.write("workflow = (\n")
-        f.write(f'    Workflow("{workflow_def.workflow.start}")\n')
-        for trans in workflow_def.workflow.transitions:
-            from_node = trans.from_
-            to_node = trans.to
-            condition = trans.condition or "None"
-            if condition != "None":
-                # Ensure condition is formatted as a lambda if not already
-                if not condition.startswith("lambda ctx:"):
-                    condition = f"lambda ctx: {condition}"
-            f.write(f'    .then("{to_node}", condition={condition})\n')
-        for observer in workflow_def.observers:
-            f.write(f"    .add_observer({observer})\n")
-        f.write(")\n\n")
-
-        # Main asynchronous function to run the workflow
-        f.write("async def main():\n")
-        f.write('    """Main function to run the story generation workflow."""\n')
-        f.write("    initial_context = {\n")
-        f.write('        "genre": "science fiction",\n')
-        f.write('        "num_chapters": 3,\n')
-        f.write('        "chapters": [],\n')
-        f.write('        "completed_chapters": 0,\n')
-        f.write('        "style": "descriptive"\n')
-        f.write("    }  # Customize initial_context as needed\n")
-        f.write("    engine = workflow.build()\n")
-        f.write("    result = await engine.run(initial_context)\n")
-        f.write('    logger.info(f"Workflow result: {result}")\n\n')
-
-        # Entry point to execute the main function
-        f.write('if __name__ == "__main__":\n')
-        f.write("    anyio.run(main)\n")
-
-    # Set executable permissions (rwxr-xr-x)
-    os.chmod(output_file, 0o755)
+# The generate_executable_script function has been moved to flow_generator.py
 
 
 def print_workflow_definition(workflow_def):
@@ -635,11 +551,11 @@ def print_workflow_definition(workflow_def):
     print("Transitions:")
     for trans in workflow_def.workflow.transitions:
         condition_str = f" [Condition: {trans.condition}]" if trans.condition else ""
-        if isinstance(trans.to, list):
-            for to_node in trans.to:
-                print(f"- {trans.from_} -> {to_node}{condition_str}")
+        if isinstance(trans.to_node, list):
+            for to_node in trans.to_node:
+                print(f"- {trans.from_node} -> {to_node}{condition_str}")
         else:
-            print(f"- {trans.from_} -> {trans.to}{condition_str}")
+            print(f"- {trans.from_node} -> {trans.to_node}{condition_str}")
 
     print("\n#### Observers:")
     for observer in workflow_def.observers:
@@ -647,23 +563,39 @@ def print_workflow_definition(workflow_def):
 
 
 def main():
-    """Demonstrate parsing the story_generator_agent.py workflow and saving it to YAML."""
-    from quantalogic.flow.flow_generator import generate_executable_script  # Ensure correct import
-
-    output_file_python = "./story_generator.py"
-    file_path = "examples/qflow/story_generator_agent.py"
-    yaml_output_path = "story_generator_workflow.yaml"  # Output YAML file path
+    """Demonstrate extracting a workflow from a Python file and saving it to YAML."""
+    import argparse
+    import sys
+    
+    parser = argparse.ArgumentParser(description='Extract workflow from a Python file')
+    parser.add_argument('file_path', nargs='?', default="examples/qflow/story_generator_agent.py",
+                        help='Path to the Python file containing the workflow')
+    parser.add_argument('--output', '-o', default="./generated_workflow.py",
+                        help='Output path for the executable Python script')
+    parser.add_argument('--yaml', '-y', default="workflow_definition.yaml",
+                        help='Output path for the YAML workflow definition')
+    
+    args = parser.parse_args()
+    file_path = args.file_path
+    output_file_python = args.output
+    yaml_output_path = args.yaml
+    
+    if not os.path.exists(file_path):
+        logger.error(f"File '{file_path}' not found. Please provide a valid file path.")
+        logger.info("Example usage: python -m quantalogic.flow.flow_extractor path/to/your/workflow_file.py")
+        sys.exit(1)
+        
     try:
         workflow_def, global_vars = extract_workflow_from_file(file_path)
         logger.info(f"Successfully extracted workflow from '{file_path}'")
         print_workflow_definition(workflow_def)
         generate_executable_script(workflow_def, global_vars, output_file_python)
+        logger.info(f"Executable script generated at '{output_file_python}'")
+        
         # Save the workflow to a YAML file
         manager = WorkflowManager(workflow_def)
         manager.save_to_yaml(yaml_output_path)
         logger.info(f"Workflow saved to YAML file '{yaml_output_path}'")
-    except FileNotFoundError:
-        logger.error(f"File '{file_path}' not found. Please ensure it exists in the specified directory.")
     except Exception as e:
         logger.error(f"Failed to parse or save workflow from '{file_path}': {e}")
 

quantalogic/flow/flow_generator.py

@@ -50,21 +50,28 @@ def generate_executable_script(workflow_def: WorkflowDefinition, global_vars: di
         # Embed functions from workflow_def
         for func_name, func_def in workflow_def.functions.items():
             if func_def.type == "embedded":
-                f.write(func_def.code + "\n\n")
+                if func_def.code is not None:
+                    f.write(func_def.code + "\n\n")
+                else:
+                    f.write("\n\n")
 
         # Define workflow using chaining syntax
         f.write("# Define the workflow using simplified syntax with automatic node registration\n")
         f.write("workflow = (\n")
         f.write(f'    Workflow("{workflow_def.workflow.start}")\n')
         for trans in workflow_def.workflow.transitions:
-            from_node = trans.from_
-            to_node = trans.to
+            _from_node = trans.from_node
+            to_node = trans.to_node
             condition = trans.condition or "None"
             if condition != "None":
                 # Ensure condition is formatted as a lambda if not already
                 if not condition.startswith("lambda ctx:"):
                     condition = f"lambda ctx: {condition}"
             f.write(f'    .then("{to_node}", condition={condition})\n')
+        # Add observers if any exist in the workflow definition
+        if hasattr(workflow_def, 'observers'):
+            for observer in workflow_def.observers:
+                f.write(f"    .add_observer({observer})\n")
         f.write(")\n\n")
 
         # Main asynchronous function to run the workflow

quantalogic/flow/flow_manager.py

@@ -8,7 +8,7 @@ import urllib
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional, Type, Union
 
-import yaml
+import yaml  # type: ignore
 from loguru import logger
 from pydantic import BaseModel, ValidationError
 
@@ -16,6 +16,7 @@ from pydantic import BaseModel, ValidationError
 from quantalogic.flow.flow import Nodes, Workflow
 from quantalogic.flow.flow_manager_schema import (
     FunctionDefinition,
+    LLMConfig,
     NodeDefinition,
     TransitionDefinition,
     WorkflowDefinition,
@@ -41,10 +42,13 @@ class WorkflowManager:
         parallel: bool = False,
     ) -> None:
         """Add a new node to the workflow definition, supporting sub-workflows and LLM nodes."""
+        # Convert dict to LLMConfig if provided
+        llm_config_obj = LLMConfig(**llm_config) if llm_config is not None else None
+        
         node = NodeDefinition(
             function=function,
             sub_workflow=sub_workflow,
-            llm_config=llm_config,
+            llm_config=llm_config_obj,
             output=output or (f"{name}_result" if function or llm_config else None),
             retries=retries,
             delay=delay,
@@ -61,7 +65,7 @@ class WorkflowManager:
         self.workflow.workflow.transitions = [
             t
             for t in self.workflow.workflow.transitions
-            if t.from_ != name and (isinstance(t.to, str) or name not in t.to)
+            if t.from_node != name and (isinstance(t.to_node, str) or name not in t.to_node)
         ]
         if self.workflow.workflow.start == name:
             self.workflow.workflow.start = None
@@ -95,22 +99,36 @@ class WorkflowManager:
 
     def add_transition(
         self,
-        from_: str,
-        to: Union[str, List[str]],
+        from_node: str,
+        to_node: Union[str, List[str]],
         condition: Optional[str] = None,
+        strict: bool = True,
     ) -> None:
-        """Add a transition between nodes, ensuring all nodes exist."""
-        if from_ not in self.workflow.nodes:
-            raise ValueError(f"Source node '{from_}' does not exist")
-        if isinstance(to, str):
-            if to not in self.workflow.nodes:
-                raise ValueError(f"Target node '{to}' does not exist")
-        else:
-            for t in to:
-                if t not in self.workflow.nodes:
-                    raise ValueError(f"Target node '{t}' does not exist")
-        # Use 'from' field name instead of the alias 'from_'
-        transition = TransitionDefinition(**{"from": from_, "to": to, "condition": condition})
+        """Add a transition between nodes.
+        
+        Args:
+            from_node: Source node name
+            to_node: Target node name or list of target node names
+            condition: Optional condition for the transition
+            strict: If True, validates that all nodes exist before adding the transition.
+                   If False, allows adding transitions to non-existent nodes.
+        """
+        if strict:
+            if from_node not in self.workflow.nodes:
+                raise ValueError(f"Source node '{from_node}' does not exist")
+            if isinstance(to_node, str):
+                if to_node not in self.workflow.nodes:
+                    raise ValueError(f"Target node '{to_node}' does not exist")
+            else:
+                for t in to_node:
+                    if t not in self.workflow.nodes:
+                        raise ValueError(f"Target node '{t}' does not exist")
+        # Create TransitionDefinition with named parameters
+        transition = TransitionDefinition(
+            from_node=from_node,
+            to_node=to_node,
+            condition=condition
+        )
         self.workflow.workflow.transitions.append(transition)
 
     def set_start_node(self, name: str) -> None:
@@ -174,8 +192,12 @@ class WorkflowManager:
                     temp_path = temp_file.name
                 module_name = f"temp_module_{hash(temp_path)}"
                 spec = importlib.util.spec_from_file_location(module_name, temp_path)
+                if spec is None:
+                    raise ValueError(f"Failed to create module spec from {temp_path}")
                 module = importlib.util.module_from_spec(spec)
                 sys.modules[module_name] = module
+                if spec.loader is None:
+                    raise ValueError(f"Module spec has no loader for {temp_path}")
                 spec.loader.exec_module(module)
                 os.remove(temp_path)
                 return module
@@ -186,8 +208,12 @@ class WorkflowManager:
             try:
                 module_name = f"local_module_{hash(source)}"
                 spec = importlib.util.spec_from_file_location(module_name, source)
+                if spec is None:
+                    raise ValueError(f"Failed to create module spec from {source}")
                 module = importlib.util.module_from_spec(spec)
                 sys.modules[module_name] = module
+                if spec.loader is None:
+                    raise ValueError(f"Module spec has no loader for {source}")
                 spec.loader.exec_module(module)
                 return module
             except Exception as e:
@@ -209,21 +235,40 @@ class WorkflowManager:
         functions: Dict[str, Callable] = {}
         for func_name, func_def in self.workflow.functions.items():
             if func_def.type == "embedded":
-                local_scope = {}
-                exec(func_def.code, local_scope)
-                if func_name not in local_scope:
-                    raise ValueError(f"Embedded function '{func_name}' not defined in code")
-                functions[func_name] = local_scope[func_name]
+                local_scope: Dict[str, Any] = {}
+                if func_def.code is not None:
+                    exec(func_def.code, local_scope)
+                    if func_name not in local_scope:
+                        raise ValueError(f"Embedded function '{func_name}' not defined in code")
+                    functions[func_name] = local_scope[func_name]
+                else:
+                    raise ValueError(f"Embedded function '{func_name}' has no code")
             elif func_def.type == "external":
                 try:
+                    if func_def.module is None:
+                        raise ValueError(f"External function '{func_name}' has no module specified")
                     module = self.import_module_from_source(func_def.module)
+                    if func_def.function is None:
+                        raise ValueError(f"External function '{func_name}' has no function name specified")
                     functions[func_name] = getattr(module, func_def.function)
                 except (ImportError, AttributeError) as e:
                     raise ValueError(f"Failed to import external function '{func_name}': {e}")
 
+        # Check if start node is set
         if not self.workflow.workflow.start:
             raise ValueError("Start node not set in workflow definition")
-        wf = Workflow(start_node=self.workflow.workflow.start)
+            
+        # We need to ensure we have a valid string for the start node
+        # First check if it's None and provide a fallback
+        if self.workflow.workflow.start is None:
+            logger.warning("Start node was None, using 'start' as default")
+            start_node_name = "start"
+        else:
+            # Otherwise convert to string
+            start_node_name = str(self.workflow.workflow.start)
+        
+        # Create the workflow with a valid start node
+        wf = Workflow(start_node=start_node_name)
 
         # Register observers
         for observer_name in self.workflow.observers:
@@ -235,12 +280,18 @@ class WorkflowManager:
         sub_workflows: Dict[str, Workflow] = {}
         for node_name, node_def in self.workflow.nodes.items():
             if node_def.sub_workflow:
-                sub_wf = Workflow(node_def.sub_workflow.start)
+                # Ensure we have a valid start node for the sub-workflow
+                if node_def.sub_workflow.start is None:
+                    logger.warning(f"Sub-workflow for node '{node_name}' has no start node, using '{node_name}_start' as default")
+                    start_node = f"{node_name}_start"
+                else:
+                    start_node = str(node_def.sub_workflow.start)
+                sub_wf = Workflow(start_node=start_node)
                 sub_workflows[node_name] = sub_wf
                 added_sub_nodes = set()
                 for trans in node_def.sub_workflow.transitions:
-                    from_node = trans.from_
-                    to_nodes = [trans.to] if isinstance(trans.to, str) else trans.to
+                    from_node = trans.from_node
+                    to_nodes = [trans.to_node] if isinstance(trans.to_node, str) else trans.to_node
                     if from_node not in added_sub_nodes:
                         sub_wf.node(from_node)
                         added_sub_nodes.add(from_node)
@@ -254,7 +305,9 @@ class WorkflowManager:
                     else:
                         sub_wf.then(to_nodes[0], condition=condition)
                 inputs = list(Nodes.NODE_REGISTRY[sub_wf.start_node][1])
-                wf.add_sub_workflow(node_name, sub_wf, inputs={k: k for k in inputs}, output=node_def.output)
+                # Ensure output is a string
+                output = node_def.output if node_def.output is not None else f"{node_name}_result"
+                wf.add_sub_workflow(node_name, sub_wf, inputs={k: k for k in inputs}, output=output)
             elif node_def.function:
                 if node_def.function not in functions:
                     raise ValueError(f"Function '{node_def.function}' for node '{node_name}' not found")
@@ -265,13 +318,15 @@ class WorkflowManager:
             elif node_def.llm_config:
                 llm_config = node_def.llm_config
                 # Extract inputs from prompt_template using regex
-                inputs = set(re.findall(r"{{\s*([^}]+?)\s*}}", llm_config.prompt_template))
+                # Extract inputs from prompt_template using regex
+                input_vars = set(re.findall(r"{{\s*([^}]+?)\s*}}", llm_config.prompt_template))
                 cleaned_inputs = set()
-                for input_var in inputs:
+                for input_var in input_vars:
                     base_var = re.split(r"\s*[\+\-\*/]\s*", input_var.strip())[0].strip()
                     if base_var.isidentifier():
                         cleaned_inputs.add(base_var)
-                inputs_list = list(cleaned_inputs)
+                # Convert set to list for type compatibility
+                inputs_list: List[str] = list(cleaned_inputs)
 
                 # Define a dummy function to be decorated
                 async def dummy_func(**kwargs):
@@ -316,8 +371,8 @@ class WorkflowManager:
 
         added_nodes = set()
         for trans in self.workflow.workflow.transitions:
-            from_node = trans.from_
-            to_nodes = [trans.to] if isinstance(trans.to, str) else trans.to
+            from_node = trans.from_node
+            to_nodes = [trans.to_node] if isinstance(trans.to_node, str) else trans.to_node
             if from_node not in added_nodes and from_node not in sub_workflows:
                 wf.node(from_node)
                 added_nodes.add(from_node)
@@ -395,7 +450,7 @@ def main():
     manager.add_node(name="start", function="greet")
     manager.add_node(name="end", function="farewell")
     manager.set_start_node("start")
-    manager.add_transition(from_="start", to="end")
+    manager.add_transition(from_node="start", to_node="end")
     manager.add_observer("monitor")  # Add the observer
     manager.save_to_yaml("workflow.yaml")
     new_manager = WorkflowManager()

quantalogic/flow/flow_manager_schema.py

@@ -128,12 +128,11 @@ class NodeDefinition(BaseModel):
 class TransitionDefinition(BaseModel):
     """Definition of a transition between nodes."""
 
-    from_: str = Field(
+    from_node: str = Field(
         ...,
         description="Source node name for the transition.",
-        alias="from",  # Supports YAML aliasing
     )
-    to: Union[str, List[str]] = Field(
+    to_node: Union[str, List[str]] = Field(
         ..., description="Target node(s). A string for sequential, a list for parallel execution."
     )
     condition: Optional[str] = Field(
@@ -158,7 +157,7 @@ class WorkflowDefinition(BaseModel):
     )
     nodes: Dict[str, NodeDefinition] = Field(default_factory=dict, description="Dictionary of node definitions.")
     workflow: WorkflowStructure = Field(
-        default_factory=WorkflowStructure, description="Main workflow structure with start node and transitions."
+        default_factory=lambda: WorkflowStructure(start=None), description="Main workflow structure with start node and transitions."
     )
     observers: List[str] = Field(
         default_factory=list, description="List of observer function names to monitor workflow execution."