quantalogic 0.52.1__py3-none-any.whl → 0.53.0__py3-none-any.whl

quantalogic/flow/flow.py

@@ -2,22 +2,23 @@
 # /// script
 # requires-python = ">=3.12"
 # dependencies = [
-#     "loguru",
-#     "litellm",
-#     "pydantic>=2.0",
-#     "anyio",
-#     "jinja2",
-#     "instructor[litellm]"  # Required for structured_llm_node
+#     "loguru>=0.7.2",              # Logging utility
+#     "litellm>=1.0.0",             # LLM integration
+#     "pydantic>=2.0.0",            # Data validation and settings
+#     "anyio>=4.0.0",               # Async utilities
+#     "jinja2>=3.1.0",              # Templating engine
+#     "instructor[litellm]>=0.5.0"  # Structured LLM output with litellm integration
 # ]
 # ///
 
 import asyncio
 from dataclasses import dataclass
 from enum import Enum
+from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional, Tuple, Type
 
 import instructor
-from jinja2 import Template
+from jinja2 import Environment, FileSystemLoader, Template, TemplateNotFound
 from litellm import acompletion
 from loguru import logger
 from pydantic import BaseModel, ValidationError
@@ -348,13 +349,42 @@ class Nodes:
 
         return decorator
 
+    @staticmethod
+    def _load_prompt_from_file(prompt_file: str, context: Dict[str, Any]) -> str:
+        """Load and render a Jinja2 template from an external file."""
+        try:
+            file_path = Path(prompt_file).resolve()
+            directory = file_path.parent
+            filename = file_path.name
+            env = Environment(loader=FileSystemLoader(directory))
+            template = env.get_template(filename)
+            return template.render(**context)
+        except TemplateNotFound as e:
+            logger.error(f"Jinja2 template file '{prompt_file}' not found: {e}")
+            raise ValueError(f"Prompt file '{prompt_file}' not found")
+        except Exception as e:
+            logger.error(f"Error loading or rendering prompt file '{prompt_file}': {e}")
+            raise
+
+    @staticmethod
+    def _render_prompt(template: str, prompt_file: Optional[str], context: Dict[str, Any]) -> str:
+        """Render a prompt from either a template string or an external file."""
+        if prompt_file:
+            return Nodes._load_prompt_from_file(prompt_file, context)
+        try:
+            return Template(template).render(**context)
+        except Exception as e:
+            logger.error(f"Error rendering prompt template: {e}")
+            raise
+
     @classmethod
     def llm_node(
         cls,
         model: str,
         system_prompt: str,
-        prompt_template: str,
         output: str,
+        prompt_template: str = "",
+        prompt_file: Optional[str] = None,
         temperature: float = 0.7,
         max_tokens: int = 2000,
         top_p: float = 1.0,
@@ -362,11 +392,11 @@ class Nodes:
         frequency_penalty: float = 0.0,
         **kwargs,
     ):
-        """Decorator for creating LLM nodes with plain text output."""
+        """Decorator for creating LLM nodes with plain text output, supporting external prompt files."""
 
         def decorator(func: Callable) -> Callable:
             async def wrapped_func(**kwargs):
-                prompt = cls._render_prompt(prompt_template, kwargs)
+                prompt = cls._render_prompt(prompt_template, prompt_file, kwargs)
                 messages = [
                     {"role": "system", "content": system_prompt},
                     {"role": "user", "content": prompt},
@@ -409,9 +439,10 @@ class Nodes:
         cls,
         model: str,
         system_prompt: str,
-        prompt_template: str,
-        response_model: Type[BaseModel],
         output: str,
+        response_model: Type[BaseModel],
+        prompt_template: str = "",
+        prompt_file: Optional[str] = None,
         temperature: float = 0.7,
         max_tokens: int = 2000,
         top_p: float = 1.0,
@@ -419,7 +450,7 @@ class Nodes:
         frequency_penalty: float = 0.0,
         **kwargs,
     ):
-        """Decorator for creating LLM nodes with structured output using instructor."""
+        """Decorator for creating LLM nodes with structured output using instructor, supporting external prompt files."""
         try:
             client = instructor.from_litellm(acompletion)
         except ImportError:
@@ -428,7 +459,7 @@ class Nodes:
 
         def decorator(func: Callable) -> Callable:
             async def wrapped_func(**kwargs):
-                prompt = cls._render_prompt(prompt_template, kwargs)
+                prompt = cls._render_prompt(prompt_template, prompt_file, kwargs)
                 messages = [
                     {"role": "system", "content": system_prompt},
                     {"role": "user", "content": prompt},
@@ -470,15 +501,6 @@ class Nodes:
 
         return decorator
 
-    @staticmethod
-    def _render_prompt(template: str, context: Dict[str, Any]) -> str:
-        """Render a Jinja2 template with the given context."""
-        try:
-            return Template(template).render(**context)
-        except Exception as e:
-            logger.error(f"Error rendering prompt template: {e}")
-            raise
-
 
 # Example workflow with observer integration and updated structured node
 async def example_workflow():
@@ -528,9 +550,9 @@ async def example_workflow():
     @Nodes.structured_llm_node(
         model="gemini/gemini-2.0-flash",
         system_prompt="You are an inventory checker. Respond with a JSON object containing 'order_id', 'items', and 'in_stock' (boolean).",
-        prompt_template="Check if the following items are in stock: {{ items }}. Return the result in JSON format with 'order_id' set to '123'.",
-        response_model=OrderDetails,
         output="inventory_status",
+        response_model=OrderDetails,
+        prompt_template="Check if the following items are in stock: {{ items }}. Return the result in JSON format with 'order_id' set to '123'.",
     )
     async def check_inventory(items: List[str]) -> OrderDetails:
         # This is a placeholder function that would normally call an LLM
@@ -594,4 +616,4 @@ async def example_workflow():
 
 
 if __name__ == "__main__":
-    asyncio.run(example_workflow())
+    asyncio.run(example_workflow())

quantalogic/flow/flow_extractor.py

@@ -131,11 +131,11 @@ class WorkflowExtractor(ast.NodeVisitor):
                     llm_config = {
                         key: value
                         for key, value in kwargs.items()
-                        if key
-                        in [
+                        if key in [
                             "model",
                             "system_prompt",
                             "prompt_template",
+                            "prompt_file",  # Added to support external Jinja2 files
                             "temperature",
                             "max_tokens",
                             "top_p",
@@ -162,11 +162,11 @@ class WorkflowExtractor(ast.NodeVisitor):
                     llm_config = {
                         key: value
                         for key, value in kwargs.items()
-                        if key
-                        in [
+                        if key in [
                             "model",
                             "system_prompt",
                             "prompt_template",
+                            "prompt_file",  # Added to support external Jinja2 files
                             "temperature",
                             "max_tokens",
                             "top_p",
@@ -250,11 +250,11 @@ class WorkflowExtractor(ast.NodeVisitor):
                     llm_config = {
                         key: value
                         for key, value in kwargs.items()
-                        if key
-                        in [
+                        if key in [
                             "model",
                             "system_prompt",
                             "prompt_template",
+                            "prompt_file",  # Added to support external Jinja2 files
                             "temperature",
                             "max_tokens",
                             "top_p",
@@ -281,11 +281,11 @@ class WorkflowExtractor(ast.NodeVisitor):
                     llm_config = {
                         key: value
                         for key, value in kwargs.items()
-                        if key
-                        in [
+                        if key in [
                             "model",
                             "system_prompt",
                             "prompt_template",
+                            "prompt_file",  # Added to support external Jinja2 files
                             "temperature",
                             "max_tokens",
                             "top_p",
@@ -510,9 +510,6 @@ def extract_workflow_from_file(file_path):
     return workflow_def, extractor.global_vars
 
 
-# The generate_executable_script function has been moved to flow_generator.py
-
-
 def print_workflow_definition(workflow_def):
     """
     Utility function to print a WorkflowDefinition in a human-readable format.
@@ -541,6 +538,8 @@ def print_workflow_definition(workflow_def):
                 print("  Type: LLM")
             print(f"  Model: {node.llm_config.model}")
             print(f"  Prompt Template: {node.llm_config.prompt_template}")
+            if node.llm_config.prompt_file:  # Added to display external prompt file if present
+                print(f"  Prompt File: {node.llm_config.prompt_file}")
         elif node.sub_workflow:
             print("  Type: Sub-Workflow")
             print(f"  Start Node: {node.sub_workflow.start}")
@@ -601,4 +600,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    main()

quantalogic/flow/flow_generator.py

@@ -1,9 +1,18 @@
+import ast
 import os
+import re
+from typing import Dict, Optional
 
+from quantalogic.flow.flow import Nodes  # Import Nodes to access NODE_REGISTRY
 from quantalogic.flow.flow_manager_schema import WorkflowDefinition
 
 
-def generate_executable_script(workflow_def: WorkflowDefinition, global_vars: dict, output_file: str) -> None:
+def generate_executable_script(
+    workflow_def: WorkflowDefinition,
+    global_vars: Dict[str, object],
+    output_file: str,
+    initial_context: Optional[Dict[str, object]] = None,
+) -> None:
     """
     Generate an executable Python script from a WorkflowDefinition with global variables.
 
@@ -11,17 +20,74 @@ def generate_executable_script(workflow_def: WorkflowDefinition, global_vars: di
         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.
+        initial_context: Optional initial context; if None, inferred from the workflow.
 
     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.
+    - Embedded functions included directly in the script with node registration.
     - Workflow instantiation using direct chaining syntax.
-    - A default initial_context matching the example.
+    - A default initial_context inferred from the workflow with customization guidance.
     """
+    # Infer initial context if not provided
+    if initial_context is None:
+        initial_context = {}
+        start_node = workflow_def.workflow.start
+        if start_node and start_node in workflow_def.nodes:
+            node_def = workflow_def.nodes[start_node]
+            if node_def.function:
+                # Function node: Try NODE_REGISTRY first
+                if start_node in Nodes.NODE_REGISTRY:
+                    inputs = Nodes.NODE_REGISTRY[start_node][1]
+                    initial_context = {input_name: None for input_name in inputs}
+                # Fallback: Parse embedded function code
+                elif node_def.function in workflow_def.functions:
+                    func_def = workflow_def.functions[node_def.function]
+                    if func_def.type == "embedded" and func_def.code:
+                        try:
+                            tree = ast.parse(func_def.code)
+                            for node in ast.walk(tree):
+                                if isinstance(node, ast.AsyncFunctionDef) or isinstance(node, ast.FunctionDef):
+                                    inputs = [param.arg for param in node.args.args]
+                                    initial_context = {input_name: None for input_name in inputs}
+                                    break
+                        except SyntaxError:
+                            pass  # If parsing fails, leave context empty
+            elif node_def.llm_config:
+                # LLM node: Parse prompt template for variables
+                prompt = node_def.llm_config.prompt_template or ""
+                input_vars = set(re.findall(r"{{\s*([^}]+?)\s*}}", prompt))
+                cleaned_inputs = {
+                    re.split(r"\s*[\+\-\*/]\s*", var.strip())[0].strip()
+                    for var in input_vars
+                    if var.strip().isidentifier()
+                }
+                initial_context = {var: None for var in cleaned_inputs}
+            elif node_def.sub_workflow:
+                # Sub-workflow: Infer from sub-workflow's start node
+                sub_start = node_def.sub_workflow.start or f"{start_node}_start"
+                if sub_start in Nodes.NODE_REGISTRY:
+                    inputs = Nodes.NODE_REGISTRY[sub_start][1]
+                    initial_context = {input_name: None for input_name in inputs}
+                # Fallback: Check sub-workflow's start node function
+                elif sub_start in workflow_def.nodes:
+                    sub_node_def = workflow_def.nodes[sub_start]
+                    if sub_node_def.function in workflow_def.functions:
+                        func_def = workflow_def.functions[sub_node_def.function]
+                        if func_def.type == "embedded" and func_def.code:
+                            try:
+                                tree = ast.parse(func_def.code)
+                                for node in ast.walk(tree):
+                                    if isinstance(node, ast.AsyncFunctionDef) or isinstance(node, ast.FunctionDef):
+                                        inputs = [param.arg for param in node.args.args]
+                                        initial_context = {input_name: None for input_name in inputs}
+                                        break
+                            except SyntaxError:
+                                pass
+
     with open(output_file, "w") as f:
-        # Write the shebang and metadata
+        # Write the shebang and metadata (exact original style)
         f.write("#!/usr/bin/env -S uv run\n")
         f.write("# /// script\n")
         f.write('# requires-python = ">=3.12"\n')
@@ -32,65 +98,132 @@ def generate_executable_script(workflow_def: WorkflowDefinition, global_vars: di
         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('#     "instructor[litellm]",\n')
         f.write("# ]\n")
         f.write("# ///\n\n")
 
-        # Write necessary imports
+        # Write necessary imports (matching original)
         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
+        # Write global variables (preserving original feature)
         for var_name, value in global_vars.items():
             f.write(f"{var_name} = {repr(value)}\n")
         f.write("\n")
 
-        # Embed functions from workflow_def
+        # Embed functions from workflow_def without decorators
         for func_name, func_def in workflow_def.functions.items():
-            if func_def.type == "embedded":
-                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")
+            if func_def.type == "embedded" and func_def.code:
+                f.write(func_def.code + "\n\n")
+
+        # Register nodes explicitly with their intended names
+        f.write("# Register nodes with their workflow names\n")
+        for node_name, node_def in workflow_def.nodes.items():
+            if node_def.function and node_def.function in workflow_def.functions:
+                output = node_def.output or f"{node_name}_result"
+                f.write(f"Nodes.NODE_REGISTRY['{node_name}'] = (greet if '{node_name}' == 'start' else end, ")
+                # Extract inputs using ast parsing
+                func_def = workflow_def.functions[node_def.function]
+                inputs = []
+                if func_def.code:
+                    try:
+                        tree = ast.parse(func_def.code)
+                        for node in ast.walk(tree):
+                            if isinstance(node, ast.AsyncFunctionDef) or isinstance(node, ast.FunctionDef):
+                                inputs = [param.arg for param in node.args.args]
+                                break
+                    except SyntaxError:
+                        pass
+                f.write(f"{repr(inputs)}, {repr(output)})\n")
+
+        # Define workflow using chaining syntax (original style with enhancements)
+        f.write("\n# Define the workflow using simplified syntax with automatic node registration\n")
         f.write("workflow = (\n")
         f.write(f'    Workflow("{workflow_def.workflow.start}")\n')
+        # Add all nodes explicitly
+        for node_name, node_def in workflow_def.nodes.items():
+            if node_def.sub_workflow:
+                sub_start = node_def.sub_workflow.start or f"{node_name}_start"
+                f.write(f'    .add_sub_workflow("{node_name}", Workflow("{sub_start}"), ')
+                inputs = Nodes.NODE_REGISTRY.get(sub_start, ([], None))[0] if sub_start in Nodes.NODE_REGISTRY else []
+                f.write(f'inputs={{{", ".join(f"{k!r}: {k!r}" for k in inputs)}}}, ')
+                f.write(f'output="{node_def.output or f"{node_name}_result"}")\n')
+            else:
+                f.write(f'    .node("{node_name}")\n')
+        # Add transitions (original style preserved)
         for trans in workflow_def.workflow.transitions:
-            _from_node = trans.from_node
+            _from_node = trans.from_node  # Original used `_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 condition != "None" and not condition.startswith("lambda ctx:"):
+                condition = f"lambda ctx: {condition}"
+            if isinstance(to_node, str):
+                f.write(f'    .then("{to_node}", condition={condition})\n')
+            else:
+                f.write(f'    .parallel({", ".join(f"{n!r}" for n in to_node)})\n')
+        # Add observers (original feature)
         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
+        # Main asynchronous function (updated with inferred context)
         f.write("async def main():\n")
         f.write('    """Main function to run the story generation workflow."""\n')
+        f.write("    # Customize initial_context as needed based on the workflow's nodes\n")
+        f.write("    # Inferred required inputs:\n")
+        inferred_inputs = list(initial_context.keys())
+        f.write(f"    # {', '.join(inferred_inputs) if inferred_inputs else 'None detected'}\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')
+        for key, value in initial_context.items():
+            f.write(f"        {repr(key)}: {repr(value)},\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
+        # Entry point (original style)
         f.write('if __name__ == "__main__":\n')
         f.write("    anyio.run(main)\n")
 
-    # Set executable permissions (rwxr-xr-x)
+    # Set executable permissions (original feature)
     os.chmod(output_file, 0o755)
+
+
+# Example usage (consistent with original structure)
+if __name__ == "__main__":
+    from quantalogic.flow.flow_manager import WorkflowManager
+
+    # Create the workflow manager
+    manager = WorkflowManager()
+
+    # Define and add functions
+    manager.add_function(
+        name="greet",
+        type_="embedded",
+        code="async def greet(name): return f'Hello, {name}!'",
+    )
+    manager.add_function(
+        name="end",
+        type_="embedded",
+        code="async def end(greeting): return f'{greeting} Goodbye!'",
+    )
+
+    # Add nodes to the workflow
+    manager.add_node(name="start", function="greet", output="greeting")
+    manager.add_node(name="end", function="end", output="farewell")
+
+    # Set start node and transitions
+    manager.set_start_node("start")
+    manager.add_transition("start", "end")
+
+    # Get the WorkflowDefinition
+    wf_def = manager.workflow
+
+    # Define global variables
+    global_vars = {"MY_CONSTANT": 42}
+
+    # Generate the script with inferred context
+    generate_executable_script(wf_def, global_vars, "workflow_script.py")

quantalogic/flow/flow_manager.py

@@ -2,6 +2,7 @@ import importlib
 import importlib.util
 import os
 import re
+import subprocess
 import sys
 import tempfile
 import urllib
@@ -28,6 +29,34 @@ class WorkflowManager:
     def __init__(self, workflow: Optional[WorkflowDefinition] = None):
         """Initialize the WorkflowManager with an optional workflow definition."""
         self.workflow = workflow or WorkflowDefinition()
+        self._ensure_dependencies()
+
+    def _ensure_dependencies(self) -> None:
+        """Ensure all specified dependencies are installed or available."""
+        if not self.workflow.dependencies:
+            return
+
+        for dep in self.workflow.dependencies:
+            if dep.startswith("http://") or dep.startswith("https://"):
+                # Remote URL: handled by import_module_from_source later
+                logger.debug(f"Dependency '{dep}' is a remote URL, will be fetched during instantiation")
+            elif os.path.isfile(dep):
+                # Local file: handled by import_module_from_source later
+                logger.debug(f"Dependency '{dep}' is a local file, will be loaded during instantiation")
+            else:
+                # Assume PyPI package
+                try:
+                    # Check if the module is already installed
+                    module_name = dep.split(">")[0].split("<")[0].split("=")[0].strip()
+                    importlib.import_module(module_name)
+                    logger.debug(f"Dependency '{dep}' is already installed")
+                except ImportError:
+                    logger.info(f"Installing dependency '{dep}' via pip")
+                    try:
+                        subprocess.check_call([sys.executable, "-m", "pip", "install", dep])
+                        logger.debug(f"Successfully installed '{dep}'")
+                    except subprocess.CalledProcessError as e:
+                        raise ValueError(f"Failed to install dependency '{dep}': {e}")
 
     def add_node(
         self,
@@ -232,6 +261,9 @@ class WorkflowManager:
 
     def instantiate_workflow(self) -> Workflow:
         """Instantiates a Workflow object based on the definitions stored in the WorkflowManager."""
+        # Ensure dependencies are available before instantiation
+        self._ensure_dependencies()
+
         functions: Dict[str, Callable] = {}
         for func_name, func_def in self.workflow.functions.items():
             if func_def.type == "embedded":
@@ -317,15 +349,13 @@ class WorkflowManager:
                 )(func)
             elif node_def.llm_config:
                 llm_config = node_def.llm_config
-                # Extract inputs from prompt_template using regex
-                # Extract inputs from prompt_template using regex
-                input_vars = set(re.findall(r"{{\s*([^}]+?)\s*}}", llm_config.prompt_template))
+                # Extract inputs from prompt_template if no prompt_file, otherwise assume inputs will be inferred at runtime
+                input_vars = set(re.findall(r"{{\s*([^}]+?)\s*}}", llm_config.prompt_template)) if not llm_config.prompt_file else set()
                 cleaned_inputs = set()
                 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)
-                # Convert set to list for type compatibility
                 inputs_list: List[str] = list(cleaned_inputs)
 
                 # Define a dummy function to be decorated
@@ -339,6 +369,7 @@ class WorkflowManager:
                         model=llm_config.model,
                         system_prompt=llm_config.system_prompt or "",
                         prompt_template=llm_config.prompt_template,
+                        prompt_file=llm_config.prompt_file,  # Pass prompt_file if provided
                         response_model=response_model,
                         output=node_def.output or f"{node_name}_result",
                         temperature=llm_config.temperature,
@@ -354,6 +385,7 @@ class WorkflowManager:
                         model=llm_config.model,
                         system_prompt=llm_config.system_prompt or "",
                         prompt_template=llm_config.prompt_template,
+                        prompt_file=llm_config.prompt_file,  # Pass prompt_file if provided
                         output=node_def.output or f"{node_name}_result",
                         temperature=llm_config.temperature,
                         max_tokens=llm_config.max_tokens or 2000,
@@ -397,6 +429,7 @@ class WorkflowManager:
             data = yaml.safe_load(f)
         try:
             self.workflow = WorkflowDefinition.model_validate(data)
+            self._ensure_dependencies()  # Ensure dependencies after loading
         except ValidationError as e:
             raise ValueError(f"Invalid workflow YAML: {e}")
 
@@ -427,6 +460,7 @@ class WorkflowManager:
 def main():
     """Demonstrate usage of WorkflowManager with observer support."""
     manager = WorkflowManager()
+    manager.workflow.dependencies = ["requests>=2.28.0"]  # Example dependency
     manager.add_function(
         name="greet",
         type_="embedded",
@@ -459,4 +493,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    main()

quantalogic/flow/flow_manager_schema.py

@@ -61,7 +61,10 @@ class LLMConfig(BaseModel):
     )
     system_prompt: Optional[str] = Field(None, description="System prompt defining the LLM's role or context.")
     prompt_template: str = Field(
-        default="{{ input }}", description="Jinja2 template for the user prompt (e.g., 'Summarize {{ text }}')."
+        default="{{ input }}", description="Jinja2 template for the user prompt (e.g., 'Summarize {{ text }}'). Ignored if prompt_file is set."
+    )
+    prompt_file: Optional[str] = Field(
+        None, description="Path to an external Jinja2 template file (e.g., 'prompts/summary.j2'). Takes precedence over prompt_template if provided."
     )
     temperature: float = Field(
         default=0.7, ge=0.0, le=1.0, description="Controls randomness of LLM output (0.0 to 1.0)."
@@ -84,6 +87,15 @@ class LLMConfig(BaseModel):
     )
     api_key: Optional[str] = Field(None, description="Custom API key for the LLM provider, if required.")
 
+    @model_validator(mode="before")
+    @classmethod
+    def check_prompt_source(cls, data: Any) -> Any:
+        """Ensure prompt_file and prompt_template are used appropriately."""
+        prompt_file = data.get("prompt_file")
+        if prompt_file and not isinstance(prompt_file, str):
+            raise ValueError("prompt_file must be a string path to a Jinja2 template file")
+        return data
+
 
 class NodeDefinition(BaseModel):
     """
@@ -162,7 +174,15 @@ class WorkflowDefinition(BaseModel):
     observers: List[str] = Field(
         default_factory=list, description="List of observer function names to monitor workflow execution."
     )
+    dependencies: List[str] = Field(
+        default_factory=list,
+        description=(
+            "List of Python module dependencies required by the workflow. "
+            "Examples: PyPI packages ('requests>=2.28.0'), local paths ('/path/to/module.py'), "
+            "or remote URLs ('https://example.com/module.py'). Processed during workflow instantiation."
+        ),
+    )
 
 
 # Resolve forward reference for sub_workflow in NodeDefinition
-NodeDefinition.model_rebuild()
+NodeDefinition.model_rebuild()