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

quantalogic/flow/flow_mermaid.py

@@ -41,23 +41,28 @@ def generate_mermaid_diagram(
     workflow_def: WorkflowDefinition,
     include_subgraphs: bool = False,
     title: Optional[str] = None,
-    include_legend: bool = True
+    include_legend: bool = True,
+    diagram_type: str = "flowchart"
 ) -> str:
     """
-    Generate a Mermaid flowchart diagram from a WorkflowDefinition with pastel colors and optimal UX.
+    Generate a Mermaid diagram (flowchart or stateDiagram) from a WorkflowDefinition with pastel colors and optimal UX.
 
     Args:
         workflow_def: The workflow definition to visualize.
-        include_subgraphs: If True, nests sub-workflows in Mermaid subgraphs.
+        include_subgraphs: If True, nests sub-workflows in Mermaid subgraphs (flowchart only).
         title: Optional title for the diagram.
         include_legend: If True, adds a comment-based legend explaining node types.
+        diagram_type: Type of diagram to generate: "flowchart" (default) or "stateDiagram".
 
     Returns:
-        A string containing the Mermaid syntax for the flowchart.
+        A string containing the Mermaid syntax for the diagram.
 
     Raises:
-        ValueError: If node names contain invalid Mermaid characters.
+        ValueError: If node names contain invalid Mermaid characters or diagram_type is invalid.
     """
+    if diagram_type not in ("flowchart", "stateDiagram"):
+        raise ValueError(f"Invalid diagram_type '{diagram_type}'; must be 'flowchart' or 'stateDiagram'")
+
     # Pastel color scheme for a soft, user-friendly look
     node_styles: Dict[str, str] = {
         "function": "fill:#90CAF9,stroke:#42A5F5,stroke-width:2px",           # Pastel Blue
@@ -67,7 +72,7 @@ def generate_mermaid_diagram(
         "unknown": "fill:#CFD8DC,stroke:#B0BEC5,stroke-width:2px"            # Pastel Grey
     }
 
-    # Shape mappings for Mermaid syntax
+    # Shape mappings for flowchart syntax
     shape_syntax: Dict[str, Tuple[str, str]] = {
         "rect": ("[", "]"),      # Rectangle for standard nodes
         "diamond": ("{{", "}}")   # Diamond for decision points
@@ -100,89 +105,124 @@ def generate_mermaid_diagram(
         if trans.condition and isinstance(trans.to_node, str):
             conditional_nodes.add(trans.from_node)
 
-    # Generate node definitions and track types/shapes
-    node_defs: List[str] = []
+    # Shared node definitions and types
     node_types: Dict[str, str] = {}
-    node_shapes: Dict[str, str] = {}
-    for node in all_nodes:
-        node_def = workflow_def.nodes.get(node)
-        has_conditions = node in conditional_nodes
-        label, node_type, shape = get_node_label_and_type(node, node_def, has_conditions)
-        start_shape, end_shape = shape_syntax[shape]
-        node_defs.append(f'{node}{start_shape}"{label}"{end_shape}')
-        node_types[node] = node_type
-        node_shapes[node] = shape
-
-    # Generate arrows for transitions (all solid lines)
-    arrows: List[str] = []
-    for trans in workflow_def.workflow.transitions:
-        from_node = trans.from_node
-        if isinstance(trans.to_node, str):
-            to_node = trans.to_node
-            condition = trans.condition
-            if condition:
-                cond = condition.replace('"', '\\"')[:30] + ("..." if len(condition) > 30 else "")
-                arrows.append(f'{from_node} -->|"{cond}"| {to_node}')  # Solid arrow with condition
-            else:
-                arrows.append(f'{from_node} --> {to_node}')
-        else:
-            for to_node in trans.to_node:
-                arrows.append(f'{from_node} --> {to_node}')  # Solid arrow for parallel
+    node_shapes: Dict[str, str] = {}  # Only used for flowchart
 
     # Assemble the Mermaid syntax
     mermaid_code = "```mermaid\n"
-    mermaid_code += "graph TD\n"  # Top-down layout
+    if diagram_type == "flowchart":
+        mermaid_code += "graph TD\n"  # Top-down layout
+    else:  # stateDiagram
+        mermaid_code += "stateDiagram-v2\n"
+
     if title:
         mermaid_code += f"    %% Diagram: {title}\n"
 
     # Optional legend for UX
     if include_legend:
         mermaid_code += "    %% Legend:\n"
-        mermaid_code += "    %% - Rectangle: Process Step\n"
-        mermaid_code += "    %% - Diamond: Decision Point\n"
+        if diagram_type == "flowchart":
+            mermaid_code += "    %% - Rectangle: Process Step\n"
+            mermaid_code += "    %% - Diamond: Decision Point\n"
         mermaid_code += "    %% - Colors: Blue (Function), Green (Structured LLM), Purple (LLM), Orange (Sub-Workflow), Grey (Unknown)\n"
 
-    # Add node definitions
-    for node_def in node_defs:
-        mermaid_code += f"    {node_def}\n"
-
-    # Add transition arrows
-    for arrow in arrows:
-        mermaid_code += f"    {arrow}\n"
-
-    # Add styles for node types (no stroke-dasharray for solid appearance)
-    for node, node_type in node_types.items():
-        if node_type in node_styles:
-            mermaid_code += f"    style {node} {node_styles[node_type]}\n"
-
-    # Highlight the start node with a thicker border
-    if workflow_def.workflow.start and workflow_def.workflow.start in node_types:
-        mermaid_code += f"    style {workflow_def.workflow.start} stroke-width:4px\n"
-
-    # Optional: Subgraphs for sub-workflows
-    if include_subgraphs:
-        for node, node_def in workflow_def.nodes.items():
-            if node_def and node_def.sub_workflow:
-                mermaid_code += f"    subgraph {node}_sub[Sub-Workflow: {node}]\n"
-                sub_nodes = {node_def.sub_workflow.start} if node_def.sub_workflow.start else set()
-                for trans in node_def.sub_workflow.transitions:
-                    sub_nodes.add(trans.from_node)
-                    if isinstance(trans.to_node, str):
-                        sub_nodes.add(trans.to_node)
-                    else:
-                        sub_nodes.update(trans.to_node)
-                for sub_node in sub_nodes:
-                    mermaid_code += f"        {sub_node}[[{sub_node}]]\n"
-                mermaid_code += "    end\n"
+    if diagram_type == "flowchart":
+        # Flowchart-specific: Generate node definitions with shapes
+        node_defs: List[str] = []
+        for node in all_nodes:
+            node_def_flow: Optional[NodeDefinition] = workflow_def.nodes.get(node)
+            has_conditions = node in conditional_nodes
+            label, node_type, shape = get_node_label_and_type(node, node_def_flow, has_conditions)
+            start_shape, end_shape = shape_syntax[shape]
+            node_defs.append(f'{node}{start_shape}"{label}"{end_shape}')
+            node_types[node] = node_type
+            node_shapes[node] = shape
+
+        # Add node definitions
+        for node_def_str in node_defs:
+            mermaid_code += f"    {node_def_str}\n"
+
+        # Generate arrows for transitions (all solid lines)
+        for trans in workflow_def.workflow.transitions:
+            from_node = trans.from_node
+            if isinstance(trans.to_node, str):
+                to_node = trans.to_node
+                condition = trans.condition
+                if condition:
+                    cond = condition.replace('"', '\\"')[:30] + ("..." if len(condition) > 30 else "")
+                    mermaid_code += f'    {from_node} -->|"{cond}"| {to_node}\n'
+                else:
+                    mermaid_code += f'    {from_node} --> {to_node}\n'
+            else:
+                for to_node in trans.to_node:
+                    mermaid_code += f'    {from_node} --> {to_node}\n'
+
+        # Add styles for node types
+        for node, node_type in node_types.items():
+            if node_type in node_styles:
+                mermaid_code += f"    style {node} {node_styles[node_type]}\n"
+
+        # Highlight the start node
+        if workflow_def.workflow.start and workflow_def.workflow.start in node_types:
+            mermaid_code += f"    style {workflow_def.workflow.start} stroke-width:4px\n"
+
+        # Optional: Subgraphs for sub-workflows
+        if include_subgraphs:
+            for node, node_def_entry in workflow_def.nodes.items():
+                if node_def_entry and node_def_entry.sub_workflow:
+                    mermaid_code += f"    subgraph {node}_sub[Sub-Workflow: {node}]\n"
+                    sub_nodes: Set[str] = {node_def_entry.sub_workflow.start} if node_def_entry.sub_workflow.start else set()
+                    for trans in node_def_entry.sub_workflow.transitions:
+                        sub_nodes.add(trans.from_node)
+                        if isinstance(trans.to_node, str):
+                            sub_nodes.add(trans.to_node)
+                        else:
+                            sub_nodes.update(trans.to_node)
+                    for sub_node in sub_nodes:
+                        mermaid_code += f"        {sub_node}[[{sub_node}]]\n"
+                    mermaid_code += "    end\n"
+
+    else:  # stateDiagram
+        # StateDiagram-specific: Define states
+        for node in all_nodes:
+            node_def_state: Optional[NodeDefinition] = workflow_def.nodes.get(node)
+            has_conditions = node in conditional_nodes
+            label, node_type, _ = get_node_label_and_type(node, node_def_state, has_conditions)  # Shape unused
+            mermaid_code += f"    state \"{label}\" as {node}\n"
+            node_types[node] = node_type
+
+        # Start state
+        if workflow_def.workflow.start:
+            mermaid_code += f"    [*] --> {workflow_def.workflow.start}\n"
+
+        # Transitions
+        for trans in workflow_def.workflow.transitions:
+            from_node = trans.from_node
+            if isinstance(trans.to_node, str):
+                to_node = trans.to_node
+                condition = trans.condition
+                if condition:
+                    cond = condition.replace('"', '\\"')[:30] + ("..." if len(condition) > 30 else "")
+                    mermaid_code += f"    {from_node} --> {to_node} : {cond}\n"
+                else:
+                    mermaid_code += f"    {from_node} --> {to_node}\n"
+            else:
+                # Parallel transitions approximated with a note
+                for to_node in trans.to_node:
+                    mermaid_code += f"    {from_node} --> {to_node} : parallel\n"
+
+        # Add styles for node types
+        for node, node_type in node_types.items():
+            if node_type in node_styles:
+                mermaid_code += f"    style {node} {node_styles[node_type]}\n"
 
     mermaid_code += "```\n"
     return mermaid_code
 
 
 def main() -> None:
-    """
-    Create a complex workflow and print its improved Mermaid diagram representation.
-    """
+    """Create a complex workflow and print its improved Mermaid diagram representation."""
     manager = WorkflowManager()
 
     # Add functions
@@ -230,11 +270,13 @@ def main() -> None:
     manager.add_transition(from_node="sentiment_analysis", to_node="revise", condition="ctx['sentiment'] == 'negative'")
     manager.add_transition(from_node="keyword_extraction", to_node="publish")
 
-    # Generate and print the diagram
+    # Generate and print both diagrams
     workflow_def = manager.workflow
-    diagram = generate_mermaid_diagram(workflow_def, include_subgraphs=False, title="Content Processing Workflow")
-    print(diagram)
-
+    print("Flowchart (default):")
+    print(generate_mermaid_diagram(workflow_def, include_subgraphs=False, title="Content Processing Workflow"))
+    print("\nState Diagram:")
+    print(generate_mermaid_diagram(workflow_def, diagram_type="stateDiagram", title="Content Processing Workflow"))
+    
 
 if __name__ == "__main__":
     main()

quantalogic/flow/flow_validator.py

@@ -1,14 +1,12 @@
 import ast
 import re
 from collections import defaultdict
-from typing import Dict, List, Set, Optional
+from typing import Dict, List, Optional, Set
 
-from pydantic import ValidationError, BaseModel
+from pydantic import BaseModel
 
 from quantalogic.flow.flow_manager import WorkflowManager
 from quantalogic.flow.flow_manager_schema import (
-    FunctionDefinition,
-    LLMConfig,
     NodeDefinition,
     TransitionDefinition,
     WorkflowDefinition,
@@ -102,9 +100,7 @@ def validate_workflow_definition(workflow_def: WorkflowDefinition) -> List[NodeE
                     predecessors[to_node].append(from_node)
 
     # Define function to get ancestors, handling cycles with a visited set
-    def get_ancestors(node: str, visited: Set[str] = None) -> Set[str]:
-        if visited is None:
-            visited = set()
+    def get_ancestors(node: str, visited: Set[str] = set()) -> Set[str]:
         if node in visited or node not in all_nodes:
             return set()
         visited.add(node)
@@ -130,15 +126,20 @@ def validate_workflow_definition(workflow_def: WorkflowDefinition) -> List[NodeE
         full_node_name = node_name
 
         if node_def.function:
-            func_def = workflow_def.functions.get(node_def.function)
-            if func_def and func_def.type == "embedded" and func_def.code:
-                try:
-                    params = get_function_params(func_def.code, node_def.function)
-                    required_inputs = set(params)
-                except ValueError as e:
-                    issues.append(NodeError(node_name=node_name, description=f"Failed to parse function '{node_def.function}': {e}"))
+            maybe_func_def = workflow_def.functions.get(node_def.function)
+            if maybe_func_def is None:
+                issues.append(NodeError(
+                    node_name=node_name,
+                    description=f"Function '{node_def.function}' not found in workflow functions"
+                ))
             else:
-                pass
+                func_def = maybe_func_def  # Type is now definitely FunctionDefinition
+                if func_def.type == "embedded" and func_def.code:
+                    try:
+                        params = get_function_params(func_def.code, node_def.function)
+                        required_inputs = set(params)
+                    except ValueError as e:
+                        issues.append(NodeError(node_name=node_name, description=f"Failed to parse function '{node_def.function}': {e}"))
         elif node_def.llm_config:
             prompt_template = node_def.llm_config.prompt_template
             input_vars = set(re.findall(r"{{\s*([^}]+?)\s*}}", prompt_template))
@@ -154,13 +155,23 @@ def validate_workflow_definition(workflow_def: WorkflowDefinition) -> List[NodeE
                 if sub_node_def:
                     full_node_name = f"{node_name}/{sub_node_name}"
                     if sub_node_def.function:
-                        func_def = workflow_def.functions.get(sub_node_def.function)
-                        if func_def and func_def.type == "embedded" and func_def.code:
-                            try:
-                                params = get_function_params(func_def.code, sub_node_def.function)
-                                required_inputs = set(params)
-                            except ValueError as e:
-                                issues.append(NodeError(node_name=full_node_name, description=f"Failed to parse function '{sub_node_def.function}': {e}"))
+                        maybe_func_def = workflow_def.functions.get(sub_node_def.function)
+                        if maybe_func_def is None:
+                            issues.append(NodeError(
+                                node_name=full_node_name,
+                                description=f"Function '{sub_node_def.function}' not found in workflow functions"
+                            ))
+                        else:
+                            func_def = maybe_func_def  # Type is now definitely FunctionDefinition
+                            if func_def.type == "embedded" and func_def.code:
+                                try:
+                                    params = get_function_params(func_def.code, sub_node_def.function)
+                                    required_inputs = set(params)
+                                except ValueError as e:
+                                    issues.append(NodeError(
+                                        node_name=full_node_name,
+                                        description=f"Failed to parse function '{sub_node_def.function}': {e}"
+                                    ))
                     elif sub_node_def.llm_config:
                         prompt_template = sub_node_def.llm_config.prompt_template
                         input_vars = set(re.findall(r"{{\s*([^}]+?)\s*}}", prompt_template))
@@ -176,7 +187,10 @@ def validate_workflow_definition(workflow_def: WorkflowDefinition) -> List[NodeE
                         for input_name in required_inputs:
                             producer_node = output_to_node.get(input_name)
                             if producer_node is None or producer_node not in ancestors:
-                                issues.append(NodeError(node_name=full_node_name, description=f"Requires input '{input_name}', but it is not produced by any ancestor"))
+                                issues.append(NodeError(
+                                    node_name=full_node_name,
+                                    description=f"Requires input '{input_name}', but it is not produced by any ancestor"
+                                ))
             continue
 
         if not required_inputs:
@@ -186,7 +200,10 @@ def validate_workflow_definition(workflow_def: WorkflowDefinition) -> List[NodeE
         for input_name in required_inputs:
             producer_node = output_to_node.get(input_name)
             if producer_node is None or producer_node not in ancestors:
-                issues.append(NodeError(node_name=full_node_name, description=f"Requires input '{input_name}', but it is not produced by any ancestor"))
+                issues.append(NodeError(
+                    node_name=full_node_name,
+                    description=f"Requires input '{input_name}', but it is not produced by any ancestor"
+                ))
 
     for observer in workflow_def.observers:
         if observer not in workflow_def.functions:

quantalogic/flow/flow_yaml.md

@@ -32,11 +32,12 @@ graph TD
 
 ## 2. Workflow Structure 🗺️
 
-A workflow YAML file is divided into three core sections:
+A workflow YAML file is divided into four core sections:
 
 - **`functions`**: Python code definitions.
 - **`nodes`**: Task specifications.
 - **`workflow`**: Flow orchestration.
+- **`dependencies`**: Python module dependencies.
 
 Here’s the skeleton:
 
@@ -47,6 +48,8 @@ nodes:
   # Tasks 🎯
 workflow:
   # Flow control 🚦
+dependencies:
+  # Python module dependencies (optional)
 observers:
   # Event watchers 👀 (optional)
 ```
@@ -275,7 +278,33 @@ graph TD
 
 ---
 
-## 5. Nodes 🧩
+---
+
+## 5. Dependencies 🐍
+
+The `dependencies` section lists Python modules required by the workflow.
+
+### Fields 📋
+
+- `dependencies` (list, optional): A list of Python module dependencies. Each dependency can be a:
+    - PyPI package name (e.g., `requests>=2.28.0`).
+    - Local file path (e.g., `/path/to/module.py`).
+    - Remote URL (e.g., `https://example.com/module.py`).
+
+These dependencies are processed during workflow instantiation, ensuring that all required modules are available before the workflow starts.
+
+### Example 🌈
+
+```yaml
+dependencies:
+  - requests>=2.28.0
+  - /path/to/my_custom_module.py
+  - https://example.com/another_module.py
+```
+
+---
+
+## 6. Nodes 🧩
 
 Nodes are the tasks, powered by functions, sub-workflows, or LLMs.
 
@@ -288,6 +317,28 @@ Nodes are the tasks, powered by functions, sub-workflows, or LLMs.
   - `model` (string, default: `"gpt-3.5-turbo"`)
   - `system_prompt` (string, optional)
   - `prompt_template` (string, default: `"{{ input }}"`)
+  - `prompt_file` (string, optional): Path to an external Jinja2 template file. If provided, the template file will be loaded and rendered with the available context.
+
+To leverage the power of Jinja2 templating directly within your Quantalogic Flow YAML DSL, you can embed Jinja2 syntax within the `prompt_template` field of your `llm_config`. This allows you to dynamically generate prompts based on variables passed from previous nodes or defined within the flow itself. Simply enclose your Jinja2 expressions within `{{ ... }}`. Ensure that the variables you reference are accessible within the scope of the node execution.
+
+Here's an example:
+
+```yaml
+nodes:
+  - id: generate_email
+    type: llm
+    config:
+      llm_config:
+        model: "gpt-4"
+        prompt_template: "Write an email to {{ recipient }} about the upcoming {{ event }}."
+        temperature: 0.7
+    inputs:
+      recipient: ${get_user_details.outputs.email}
+      event: "Company Picnic"
+```
+
+In this example, the `prompt_template` will dynamically generate an email prompt using the `recipient` variable (fetched from the output of the `get_user_details` node) and the `event` variable, which is a hardcoded string in this case.  The LLM will then use the generated prompt to compose the email.
+
   - `temperature` (float, default: `0.7`)
   - `max_tokens` (int, optional)
   - `top_p` (float, default: `1.0`)
@@ -305,6 +356,29 @@ Nodes are the tasks, powered by functions, sub-workflows, or LLMs.
 - LLM inputs come from `prompt_template`.
 
 ### Examples 🌈
+To use an external Jinja2 template file for your `prompt_template` within a Quantalogic Flow YAML DSL node's `llm_config`, specify the path to your template file using the `prompt_file` field.  The Flow will then load and render this template using Jinja2 with the available context variables during execution. This promotes cleaner YAML and allows for easier template reuse and maintenance.
+
+Here's an example `llm_config` in your YAML:
+
+```yaml
+llm_config:
+  model: "gpt-3.5-turbo"
+  prompt_file: "templates/my_prompt.j2"
+  temperature: 0.7
+```
+
+And here's a corresponding example of the external Jinja2 template file (`templates/my_prompt.j2`):
+
+```jinja2
+You are a helpful assistant. The user has asked the following:
+
+{{ user_query }}
+
+Please provide a concise and accurate answer.
+```
+
+In this example, `{{ user_query }}` will be replaced by the value of the `user_query` variable available in the Flow's context when the template is rendered. Remember to ensure the path specified in `prompt_file` is relative to the Flow's execution directory or an absolute path.
+
 From the story generator:
 ```yaml
 nodes:

quantalogic/prompts/system_prompt.j2

@@ -1,5 +1,5 @@
 ### Agent Identity: QuantaLogic {{ version }}
-Expert ReAct AI Agent implementing OODA (Observe-Orient-Decide-Act) loop with advanced problem-solving capabilities.
+Expert ReAct AI Agent implementing OODA (Observe-Orient-Decide-Act) loop with concise, efficient problem-solving.
 
 ### Domain Expertise
 {{ expertise }}
@@ -8,65 +8,61 @@ Expert ReAct AI Agent implementing OODA (Observe-Orient-Decide-Act) loop with ad
 Task Format: <task>task_description</task>
 
 ### Cognitive Framework
-1. 🔍 OBSERVE: Gather and process information
-2. 🧭 ORIENT: Analyze context and evaluate options
-3. 🎯 DECIDE: Select optimal action path
-4. ⚡ ACT: Execute precise tool operations
+1. 🔍 **OBSERVE**: Gather essential data  
+2. 🧭 **ORIENT**: Analyze context briefly  
+3. 🎯 **DECIDE**: Select optimal action  
+4. ⚡ **ACT**: Execute precise operations  
 
 ### Response Schema [MANDATORY TWO-BLOCK FORMAT]
 
-1. 🧠 Analysis Block:
+#### 1. 🧠 Analysis Block:
 ```xml
 <thinking>
-  <!-- COGNITIVE PROCESSING MATRIX -->
+  <!-- CONCISE COGNITIVE PROCESSING -->
+  <!-  VERY IMPORTANT: Write the plan using draft, emojis and symbols to be as concise as possible, avoid full sentence and full words -->
 
   <!-- INITIAL TASK ANALYSIS - INCLUDE ONLY IF NO MESSAGE HISTORY EXISTS -->
   <context_analysis when="no_history">
-    • 📋 Task Decomposition based on task and history: Steps, Dependencies, Constraints
-    • 🎯 Success Metrics: Quantifiable Outcomes
-    • 🛠️ Resource Requirements: Tools, Data, Variables
-    • ⚠️ Risk Assessment: Potential Failures, Mitigations
+    • 📋 Task Decomposition: Key steps, dependencies
+    • 🎯 Success Metrics: Quantifiable outcomes
+    • 🛠️ Resources: Essential tools, data, variables
+    • ⚠️ Risks: Potential failures, mitigations
   </context_analysis>
 
   <!-- ALWAYS INCLUDE FOR ONGOING OPERATIONS -->
   <execution_analysis>
-    <!-- ONGOING OPERATIONS -->
-    • 🔄 Analyze Last Operation Results: Result, Impact, Effectiveness
-    • 📊 Progress Map: Completed%, Remaining%, Blockers
-    • 💾 Variable State: $var: short description of the content of each variable.
-    • 📈 Performance Metrics: Speed, Quality, Resource Usage
+    • 🔄 Last Operation: Result, impact
+    • 📊 Progress: Completed%, remaining%
+    • 💾 Variables: $var: brief content
+    • 📈 Metrics: Speed, quality, resource use
   </execution_analysis>
 
   <decision_matrix>
-    <!-- ACTION PLANNING -->
-    • 🎯 Next Action: Tool Selection + Rationale
-    • 📥 Input Parameters: Values + Variable Interpolation
-    • 🔄 Fallback Strategy: Alternative Approaches
-    • ✅ Exit Criteria: Completion Conditions
+    • 🎯 Next Action: Tool + rationale
+    • 📥 Parameters: Values + $var$
+    • 🔄 Fallback: Alternative approach
+    • ✅ Exit Criteria: Completion conditions
   </decision_matrix>
 
   <memory_pad>
-    <!-- OPERATIONAL NOTES -->
     • 📝 Key Observations
-    • ⚡ Quick Access Data
+    • ⚡ Quick Data
   </memory_pad>
 </thinking>
 ```
 
-2. ⚡ Action Block:
+#### 2. ⚡ Action Block:
 ```xml
 <action>
 <tool_name>
-  <!-- PRECISE TOOL EXECUTION -->
-  <param1>value1</param1> <!-- Use $var$ for variable interpolation -->
-  <param2>value2</param2> <!-- Keep parameters minimal but sufficient -->
+  <param1>value1</param1> <!-- Use $var$ for efficiency -->
+  <param2>value2</param2> <!-- Minimal but sufficient -->
 </tool_name>
 </action>
 ```
 
 ### Example Usage
-
- ✅ Completion:
+#### ✅ Completion:
 ```xml
 <action>
 <task_complete>
@@ -76,15 +72,15 @@ Task Format: <task>task_description</task>
 ```
 
 ### Operational Parameters
-🛠️ Tools: {{ tools }}
-🌐 Environment: {{ environment }}
+- 🛠️ **Tools**: {{ tools }}  
+- 🌐 **Environment**: {{ environment }}  
 
 ### Execution Guidelines
-1. 🎯 Maintain laser focus on task objectives
-2. 📊 Use data-driven decision making
-3. 🔄 Implement feedback loops for continuous optimization
-4. ⚡ Maximize efficiency through variable interpolation
-5. 🔍 Monitor and validate each action's impact
-6. 🛑 Fail fast and adapt when encountering blockers
-7. ✅ Verify completion criteria rigorously
-8. ✅ Return complete, full and usable results.
+. 🎯 Focus on task objectives  
+2. 📊 Use data-driven decisions  
+3. 🔄 Optimize with feedback loops  
+4. ⚡ Maximize efficiency via interpolation  
+5. 🔍 Validate each action's impact  
+6. 🛑 Adapt quickly to blockers  
+7. ✅ Verify completion rigorously  
+8. ✅ Return complete, usable results  

{quantalogic-0.52.0.dist-info → quantalogic-0.53.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: quantalogic
-Version: 0.52.0
+Version: 0.53.0
 Summary: QuantaLogic ReAct Agents
 Author: Raphaël MANSUY
 Author-email: raphael.mansuy@gmail.com
@@ -59,6 +59,8 @@ Picture this: a CLI that’s as easy as a snap, a Python API that’s pure magic
 ![Video Demo](./examples/generated_tutorials/python/quantalogic_8s.gif)
 
 ---
+[Chinese Version](./README_CN.md)
+[French Version](./README_FR.md)
 
 ## Why QuantaLogic?