fastworkflow 2.15.5__py3-none-any.whl → 2.17.13__py3-none-any.whl

fastworkflow/cli.py

@@ -12,7 +12,6 @@ import time
 from pathlib import Path
 import importlib.resources
 from rich import print as rprint
-from rich.console import Console
 from rich.live import Live
 from rich.spinner import Spinner
 
@@ -175,72 +174,6 @@ def fetch_example(args):
         traceback.print_exc(file=sys.stderr)
         sys.exit(1)
 
-def train_example(args):
-    # sourcery skip: extract-duplicate-method, extract-method, remove-redundant-fstring, split-or-ifs
-    """Train an existing example workflow."""
-    # Create a spinner for the initial check
-    spinner = Spinner("dots", text="[bold green]Preparing to train example...[/bold green]")
-
-    with Live(spinner, refresh_per_second=10):
-        # Check if example exists in the local examples directory
-        local_examples_dir = Path("./examples")
-        workflow_path = local_examples_dir / args.name
-
-        if workflow_path.is_dir():
-            # Get the appropriate env files for this example workflow
-            env_file_path, passwords_file_path = find_default_env_files(local_examples_dir)
-
-            # Check if the files exist
-            env_file = Path(env_file_path)
-            passwords_file = Path(passwords_file_path)
-
-            # Create args object for train_main
-            train_args = argparse.Namespace(
-                workflow_folderpath=str(workflow_path),
-                env_file_path=str(env_file),
-                passwords_file_path=str(passwords_file)
-            )
-
-    # After the spinner, handle any errors or proceed with training
-    if not workflow_path.is_dir():
-        rprint(f"[bold red]Error:[/bold red] Example '{args.name}' not found in '{local_examples_dir}'.")
-        rprint(f"Use 'fastworkflow examples fetch {args.name}' to fetch the example first.")
-        rprint("Or use 'fastworkflow examples list' to see available examples.")
-        sys.exit(1)
-
-    if not env_file.exists() or not passwords_file.exists():
-        rprint(f"[bold red]Error:[/bold red] Required environment files not found:")
-        if not env_file.exists():
-            rprint(f"  - {env_file} (not found)")
-        if not passwords_file.exists():
-            rprint(f"  - {passwords_file} (not found)")
-        rprint("\nPlease run the following command to fetch the example and its environment files:")
-        rprint(f"  fastworkflow examples fetch {args.name}")
-        rprint("\nAfter fetching, edit the passwords file to add your API keys:")
-        rprint(f"  {local_examples_dir}/fastworkflow.passwords.env")
-        sys.exit(1)
-
-    rprint(f"[bold green]Training example[/bold green] '{args.name}' in '{workflow_path}'...")
-
-    try:
-        # Lazy import train_main only when actually training
-        from .train.__main__ import train_main as _train_main
-        # Call train_main directly instead of using subprocess
-        result = _train_main(train_args)
-
-        if result is None or result == 0:
-            rprint(f"\n✅ Successfully trained example '{args.name}'.")
-            rprint(f"You can now run it with:\nfastworkflow examples run {args.name}")
-        else:
-            rprint(f"\n❌ Training failed.")
-            sys.exit(1)
-
-    except Exception as e:
-        rprint(f"[bold red]An unexpected error occurred during training:[/bold red] {e}")
-        import traceback
-        traceback.print_exc(file=sys.stderr)
-        sys.exit(1)
-
 def find_default_env_files(workflow_path):
     """Find the appropriate default env files based on context.
     
@@ -338,14 +271,34 @@ def add_run_parser(subparsers):
     parser_run.add_argument("--startup_action", help="Optional startup action", default="")
     parser_run.add_argument("--keep_alive", help="Optional keep_alive", default=True)
     parser_run.add_argument("--project_folderpath", help="Optional path to project folder containing application code", default=None)
-    parser_run.add_argument(
-        "--run_as_agent",
-        help="Run in agent mode (uses DSPy for tool selection)",
-        action="store_true",
-        default=False,
-    )
     parser_run.set_defaults(func=lambda args: run_with_defaults(args))
 
+def add_run_fastapi_mcp_parser(subparsers):
+    """Add subparser for the 'run_fastapi_mcp' command."""
+    parser_run_fastapi_mcp = subparsers.add_parser("run_fastapi_mcp", help="Run a workflow as a FastAPI server with MCP support.")
+    parser_run_fastapi_mcp.add_argument("workflow_path", help="Path to the workflow folder")
+    
+    # Default env files will be determined at runtime based on the workflow path
+    parser_run_fastapi_mcp.add_argument(
+        "env_file_path",
+        nargs='?',
+        default=None,
+        help="Path to the environment file (default: .env in current directory, or bundled env file for examples)",
+    )
+    parser_run_fastapi_mcp.add_argument(
+        "passwords_file_path",
+        nargs='?',
+        default=None,
+        help="Path to the passwords file (default: passwords.env in current directory, or bundled env file for examples)",
+    )
+    parser_run_fastapi_mcp.add_argument("--context", help="Optional context (JSON string)", default=None)
+    parser_run_fastapi_mcp.add_argument("--startup_command", help="Optional startup command", default=None)
+    parser_run_fastapi_mcp.add_argument("--startup_action", help="Optional startup action (JSON string)", default=None)
+    parser_run_fastapi_mcp.add_argument("--project_folderpath", help="Optional path to project folder containing application code", default=None)
+    parser_run_fastapi_mcp.add_argument("--port", type=int, default=8000, help="Port to run the FastAPI server on (default: 8000)")
+    parser_run_fastapi_mcp.add_argument("--host", default="0.0.0.0", help="Host to bind the FastAPI server to (default: 0.0.0.0)")
+    parser_run_fastapi_mcp.set_defaults(func=lambda args: run_fastapi_mcp_with_defaults(args))
+
 def train_with_defaults(args):  # sourcery skip: extract-duplicate-method
     """Wrapper for train_main that sets default env file paths based on context."""
     if args.env_file_path is None or args.passwords_file_path is None:
@@ -363,7 +316,7 @@ def train_with_defaults(args):  # sourcery skip: extract-duplicate-method
             example_name = os.path.basename(args.workflow_folderpath)
             print("\nThis appears to be an example workflow. Please run:")
             print(f"  fastworkflow examples fetch {example_name}")
-            print(f"  fastworkflow examples train {example_name}")
+            print(f"  fastworkflow train ./examples/{example_name} ./examples/fastworkflow.env ./examples/fastworkflow.passwords.env")
         else:
             print("\nPlease ensure this file exists with required environment variables.")
             print("You can create a basic .env file in your current directory.")
@@ -376,7 +329,7 @@ def train_with_defaults(args):  # sourcery skip: extract-duplicate-method
             example_name = os.path.basename(args.workflow_folderpath)
             print("\nThis appears to be an example workflow. Please run:")
             print(f"  fastworkflow examples fetch {example_name}")
-            print(f"  fastworkflow examples train {example_name}")
+            print(f"  fastworkflow train ./examples/{example_name} ./examples/fastworkflow.env ./examples/fastworkflow.passwords.env")
         else:
             print("\nPlease ensure this file exists with required API keys.")
             print("You can create a basic passwords.env file in your current directory.")
@@ -403,7 +356,7 @@ def run_with_defaults(args):  # sourcery skip: extract-duplicate-method
             example_name = os.path.basename(args.workflow_path)
             print("\nThis appears to be an example workflow. Please run:")
             print(f"  fastworkflow examples fetch {example_name}")
-            print(f"  fastworkflow examples train {example_name}")
+            print(f"  fastworkflow train ./examples/{example_name} ./examples/fastworkflow.env ./examples/fastworkflow.passwords.env")
         else:
             print("\nPlease ensure this file exists with required environment variables.")
             print("You can create a basic .env file in your current directory.")
@@ -416,7 +369,7 @@ def run_with_defaults(args):  # sourcery skip: extract-duplicate-method
             example_name = os.path.basename(args.workflow_path)
             print("\nThis appears to be an example workflow. Please run:")
             print(f"  fastworkflow examples fetch {example_name}")
-            print(f"  fastworkflow examples train {example_name}")
+            print(f"  fastworkflow train ./examples/{example_name} ./examples/fastworkflow.env ./examples/fastworkflow.passwords.env")
         else:
             print("\nPlease ensure this file exists with required API keys.")
             print("You can create a basic passwords.env file in your current directory.")
@@ -426,85 +379,62 @@ def run_with_defaults(args):  # sourcery skip: extract-duplicate-method
     from .run.__main__ import run_main as _run_main
     return _run_main(args)
 
-def run_example(args):
-    # sourcery skip: extract-duplicate-method, extract-method, remove-redundant-fstring, split-or-ifs
-    """Run an existing example workflow."""
-    # Create a spinner for the initial check
-    spinner = Spinner("dots", text="[bold green]Preparing to run example...[/bold green]")
+def run_fastapi_mcp_with_defaults(args):  # sourcery skip: extract-duplicate-method
+    """Wrapper for fastapi mcp server that sets default env file paths based on context."""
+    if args.env_file_path is None or args.passwords_file_path is None:
+        default_env, default_passwords = find_default_env_files(args.workflow_path)
+    if args.env_file_path is None:
+        args.env_file_path = default_env
+    if args.passwords_file_path is None:
+        args.passwords_file_path = default_passwords
 
-    with Live(spinner, refresh_per_second=10):
-        # Check if example exists in the local examples directory
-        local_examples_dir = Path("./examples")
-        workflow_path = local_examples_dir / args.name
-
-        if workflow_path.is_dir():
-            # Get the appropriate env files for this example workflow
-            env_file_path, passwords_file_path = find_default_env_files(local_examples_dir)
-
-            # Check if the files exist
-            env_file = Path(env_file_path)
-            passwords_file = Path(passwords_file_path)
-
-            # Check if the example has been trained
-            command_info_dir = workflow_path / "___command_info"
-
-    # After the spinner, handle any errors or proceed with running
-    if not workflow_path.is_dir():
-        rprint(f"[bold red]Error:[/bold red] Example '{args.name}' not found in '{local_examples_dir}'.")
-        rprint(f"Use 'fastworkflow examples fetch {args.name}' to fetch the example first.")
-        rprint("Or use 'fastworkflow examples list' to see available examples.")
+    # Check if the files exist and provide helpful error messages
+    if not os.path.exists(args.env_file_path):
+        print(f"Error: Environment file not found at: {args.env_file_path}", file=sys.stderr)
+        # Check if this is an example workflow
+        if "/examples/" in str(args.workflow_path) or "\\examples\\" in str(args.workflow_path):
+            example_name = os.path.basename(args.workflow_path)
+            print("\nThis appears to be an example workflow. Please run:")
+            print(f"  fastworkflow examples fetch {example_name}")
+            print(f"  fastworkflow run_fastapi_mcp ./examples/{example_name} ./examples/fastworkflow.env ./examples/fastworkflow.passwords.env")
+        else:
+            print("\nPlease ensure this file exists with required environment variables.")
+            print("You can create a basic .env file in your current directory.")
         sys.exit(1)
 
-    if not env_file.exists() or not passwords_file.exists():
-        rprint(f"[bold red]Error:[/bold red] Required environment files not found:")
-        if not env_file.exists():
-            rprint(f"  - {env_file} (not found)")
-        if not passwords_file.exists():
-            rprint(f"  - {passwords_file} (not found)")
-        rprint("\nPlease run the following command to fetch the example and its environment files:")
-        rprint(f"  fastworkflow examples fetch {args.name}")
-        rprint("\nAfter fetching, edit the passwords file to add your API keys:")
-        rprint(f"  {local_examples_dir}/fastworkflow.passwords.env")
-        rprint("\nThen train the example before running it:")
-        rprint(f"  fastworkflow examples train {args.name}")
+    if not os.path.exists(args.passwords_file_path):
+        print(f"Error: Passwords file not found at: {args.passwords_file_path}", file=sys.stderr)
+        # Check if this is an example workflow
+        if "/examples/" in str(args.workflow_path) or "\\examples\\" in str(args.workflow_path):
+            example_name = os.path.basename(args.workflow_path)
+            print("\nThis appears to be an example workflow. Please run:")
+            print(f"  fastworkflow examples fetch {example_name}")
+            print(f"  fastworkflow run_fastapi_mcp ./examples/{example_name} ./examples/fastworkflow.env ./examples/fastworkflow.passwords.env")
+        else:
+            print("\nPlease ensure this file exists with required API keys.")
+            print("You can create a basic passwords.env file in your current directory.")
         sys.exit(1)
 
-    # Check if the example has been trained
-    if not command_info_dir.exists() or not any(command_info_dir.iterdir()):
-        rprint(f"[bold yellow]Warning:[/bold yellow] Example '{args.name}' does not appear to be trained yet.")
-        rprint(f"Please train the example first with:")
-        rprint(f"  fastworkflow examples train {args.name}")
-        response = input("Do you want to continue anyway? [y/N] ")
-        if response.lower() != 'y':
-            rprint("Operation cancelled.")
-            sys.exit(0)
-
-    rprint(f"[bold green]Running example[/bold green] '{args.name}'...")
-
-    # For interactive applications, we need to use os.execvp to replace the current process
-    # This ensures that stdin/stdout/stderr are properly connected for interactive use
+    # Use subprocess to run python -m fastworkflow.run_fastapi_mcp with the correct arguments
     cmd = [
-        sys.executable,
-        "-m", "fastworkflow.run",
-        str(workflow_path),
-        str(env_file),
-        str(passwords_file)
+        sys.executable, '-m', 'fastworkflow.run_fastapi_mcp',
+        '--workflow_path', args.workflow_path,
+        '--env_file_path', args.env_file_path,
+        '--passwords_file_path', args.passwords_file_path,
+        '--port', str(args.port),
+        '--host', args.host,
     ]
-
-    # Forward agent mode flag if requested
-    if getattr(args, "run_as_agent", False):
-        cmd.append("--run_as_agent")
-
-    try:
-        rprint(f"[bold green]Starting interactive session...[/bold green]")
-        # Replace the current process with the run command
-        # This ensures that the interactive prompt works correctly
-        os.execvp(sys.executable, cmd)
-    except Exception as e:
-        rprint(f"[bold red]An unexpected error occurred while running the example:[/bold red] {e}")
-        import traceback
-        traceback.print_exc(file=sys.stderr)
-        sys.exit(1)
+    if args.context:
+        cmd.extend(['--context', args.context])
+    if args.startup_command:
+        cmd.extend(['--startup_command', args.startup_command])
+    if args.startup_action:
+        cmd.extend(['--startup_action', args.startup_action])
+    if args.project_folderpath:
+        cmd.extend(['--project_folderpath', args.project_folderpath])
+    
+    # Run the subprocess
+    return subprocess.run(cmd).returncode
 
 def main():
     """Main function for the fastworkflow CLI."""
@@ -528,27 +458,12 @@ def main():
     parser_fetch.add_argument("--force", action="store_true", help="Force overwrite if example already exists")
     parser_fetch.set_defaults(func=fetch_example)
     
-    # 'examples train' command
-    parser_train_example = examples_subparsers.add_parser("train", help="Train a specific example")
-    parser_train_example.add_argument("name", help="The name of the example to train")
-    parser_train_example.set_defaults(func=train_example)
-    
-    # 'examples run' command
-    parser_run_example = examples_subparsers.add_parser("run", help="Run a specific example")
-    parser_run_example.add_argument("name", help="The name of the example to run")
-    parser_run_example.add_argument(
-        "--run_as_agent",
-        help="Run the example in agent mode (uses DSPy for tool selection)",
-        action="store_true",
-        default=False,
-    )
-    parser_run_example.set_defaults(func=run_example)
-    
     # Add top-level commands
     add_build_parser(subparsers)
     add_refine_parser(subparsers)
     add_train_parser(subparsers)
     add_run_parser(subparsers)
+    add_run_fastapi_mcp_parser(subparsers)
 
     try:
         args = parser.parse_args()

fastworkflow/command_context_model.py

@@ -2,11 +2,12 @@ from __future__ import annotations
 
 import json
 from dataclasses import dataclass, field
+from typing import Any
+import os
 from pathlib import Path
-from typing import Any, Optional, Type
 
 import fastworkflow
-from fastworkflow.command_directory import CommandDirectory, get_cached_command_directory
+from fastworkflow.command_directory import get_cached_command_directory
 from fastworkflow.utils import python_utils
 
 """Utility for loading and traversing the single-file workflow command context model.
@@ -152,10 +153,10 @@ class CommandContextModel:
         hierarchy_model_path = Path(self._workflow_path) / "context_hierarchy_model.json"
         if not hierarchy_model_path.is_file():
             return {}
-        
+
         with hierarchy_model_path.open("r") as f:
             hierarchy_data = json.load(f)
-            
+
         return hierarchy_data
 
     def _resolve_ancestry(self, hierarchy: dict[str, dict[str, list[str]]]) -> None:
@@ -205,10 +206,10 @@ class CommandContextModel:
             all_ancestors.add(parent)
             grandparents = self.get_ancestor_contexts(parent, visiting.copy(), _hierarchy)
             all_ancestors.update(grandparents)
-        
+
         final_ancestors = sorted(list(all_ancestors))
         self._resolved_ancestors[context_name] = final_ancestors
-        
+
         visiting.remove(context_name)
 
         return final_ancestors
@@ -228,7 +229,7 @@ class CommandContextModel:
             # or by being part of a command inheritance structure. If it's not
             # in _command_contexts, it's an unknown/invalid context.
             raise CommandContextModelValidationError(f"Context '{context_name}' not found in model.")
-            
+
         if visiting is None:
             visiting = set()
 
@@ -294,3 +295,68 @@ class CommandContextModel:
             return getattr(module, context_metadata.context_class, None)
         else:
             return None
+
+
+# ---------------------------------------------------------------------
+# Workflow info helper (module-level)
+# ---------------------------------------------------------------------
+
+def get_workflow_info(chat_session_or_path: fastworkflow.ChatSession | str) -> dict[str, Any]:
+    """
+    Return workflow-level metadata for the active workflow in the given chat session or workflow path.
+
+    Shape:
+    {
+      "workflow_name": str,
+      "available_contexts": list[str],
+      "context_inheritance_model": dict,
+      "context_hierarchy_model": dict
+    }
+
+    Notes:
+    - available_contexts are derived from CommandContextModel.load(workflow_path)
+      so they reflect filesystem + inheritance.
+    - current context and purpose/description are intentionally omitted.
+    - Raw JSON for inheritance (from _commands/context_inheritance_model.json)
+      and hierarchy (from context_hierarchy_model.json) is returned verbatim when present.
+    """
+    if isinstance(chat_session_or_path, str):
+        workflow_path_str = chat_session_or_path
+    else:
+        workflow_path_str = chat_session_or_path.get_active_workflow().folderpath
+    workflow_name = os.path.basename(os.path.abspath(workflow_path_str))
+
+    available_contexts: list[str]
+    inheritance_json: dict[str, Any] = {}
+    hierarchy_json: dict[str, Any] = {}
+
+    try:
+        # Derive contexts via consolidated model
+        context_model = CommandContextModel.load(workflow_path_str)
+        # Do not normalize names beyond keeping what the model exposes
+        available_contexts = sorted([key for key in context_model._command_contexts.keys() if key != 'IntentDetection'])
+    except Exception:
+        available_contexts = ["/"]
+
+    # Load raw context inheritance model (if present)
+    try:
+        inheritance_path = Path(workflow_path_str) / "_commands" / "context_inheritance_model.json"
+        if inheritance_path.is_file():
+            inheritance_json = json.loads(inheritance_path.read_text())
+    except Exception:
+        inheritance_json = {}
+
+    # Load raw context hierarchy model (if present)
+    try:
+        hierarchy_path = Path(workflow_path_str) / "context_hierarchy_model.json"
+        if hierarchy_path.is_file():
+            hierarchy_json = json.loads(hierarchy_path.read_text())
+    except Exception:
+        hierarchy_json = {}
+
+    return {
+        "workflow_name": workflow_name,
+        "available_contexts": available_contexts,
+        "context_inheritance_model": inheritance_json,
+        "context_hierarchy_model": hierarchy_json,
+    }

fastworkflow/command_executor.py

@@ -45,16 +45,21 @@ class CommandExecutor(CommandExecutorInterface):
                 command = command)
         )
 
-        if command_output.command_handled or not command_output.success:           
+        if command_output.command_handled:       
+            # important to clear the current command mode from the workflow context
+            if "is_assistant_mode_command" in chat_session.cme_workflow._context:
+                del chat_session.cme_workflow._context["is_assistant_mode_command"]
+            return command_output
+        elif not command_output.success:       
             return command_output
 
         command_name = command_output.command_responses[0].artifacts["command_name"]
         input_obj = command_output.command_responses[0].artifacts["cmd_parameters"]
 
-        workflow = ChatSession.get_active_workflow()
+        workflow = chat_session.get_active_workflow()
         workflow_name = workflow.folderpath.split('/')[-1]
         context = workflow.current_command_context_displayname
-        
+
         command_routing_definition = fastworkflow.RoutingRegistry.get_definition(
             workflow.folderpath
         )
@@ -77,13 +82,17 @@ class CommandExecutor(CommandExecutorInterface):
             command_output = response_generation_object(workflow, command, input_obj)
         else:
             command_output = response_generation_object(workflow, command)
-            
+
         # Set the additional attributes
         command_output.workflow_name = workflow_name
         command_output.context = context
         command_output.command_name = command_name
         command_output.command_parameters = input_obj or None
 
+        # important to clear the current command mode from the workflow context
+        if "is_assistant_mode_command" in chat_session.cme_workflow._context:
+            del chat_session.cme_workflow._context["is_assistant_mode_command"]
+
         return command_output
 
     @classmethod
@@ -134,7 +143,7 @@ class CommandExecutor(CommandExecutorInterface):
             input_obj = command_parameters_class(**action.parameters)
 
             input_for_param_extraction = InputForParamExtraction(command=action.command)
-            is_valid, error_msg, _ = input_for_param_extraction.validate_parameters(
+            is_valid, error_msg, _, _ = input_for_param_extraction.validate_parameters(
                 workflow, action.command_name, input_obj
             )
             if not is_valid:

fastworkflow/command_metadata_api.py

@@ -480,6 +480,58 @@ class CommandMetadataAPI:
 
         return f"{indent_str}{value}"
 
+    @staticmethod
+    def get_workflow_definition_display_text(workflow_info: Dict[str, Any]) -> str:
+        """
+        Convert workflow definition dict to human-readable text display.
+        
+        Args:
+            workflow_info: Workflow info dict from get_workflow_info()
+                {
+                    "workflow_name": str,
+                    "available_contexts": list[str],
+                    "context_inheritance_model": dict,
+                    "context_hierarchy_model": dict
+                }
+        
+        Returns:
+            Human-readable text representation of workflow definition
+        """
+        lines: List[str] = ["Workflow Definition:"]
+        
+        # Workflow name
+        if workflow_name := workflow_info.get("workflow_name"):
+            lines.append(f"  name: {workflow_name}")
+        
+        # Available contexts
+        if contexts := workflow_info.get("available_contexts"):
+            lines.append("  available_contexts:")
+            for ctx in contexts:
+                display_name = "global" if ctx == "*" else ctx
+                lines.append(f"    - {display_name}")
+        
+        # Context inheritance (if present and non-empty)
+        if inheritance := workflow_info.get("context_inheritance_model"):
+            if inheritance:  # Only show if not empty dict
+                lines.append("  context_inheritance:")
+                for ctx, parents in sorted(inheritance.items()):
+                    if parents:  # Only show if has parents
+                        display_ctx = "global" if ctx == "*" else ctx
+                        parent_list = ", ".join(["global" if p == "*" else p for p in parents])
+                        lines.append(f"    {display_ctx}: [{parent_list}]")
+        
+        # Context hierarchy (if present and non-empty)
+        if hierarchy := workflow_info.get("context_hierarchy_model"):
+            if hierarchy:  # Only show if not empty dict
+                lines.append("  context_hierarchy:")
+                for parent, children in sorted(hierarchy.items()):
+                    if children:  # Only show if has children
+                        display_parent = "global" if parent == "*" else parent
+                        children_list = ", ".join(["global" if c == "*" else c for c in children])
+                        lines.append(f"    {display_parent}: [{children_list}]")
+        
+        return "\n".join(lines)
+
     @staticmethod
     def get_command_display_text(
         subject_workflow_path: str,
@@ -499,7 +551,7 @@ class CommandMetadataAPI:
             cme_workflow_path=cme_workflow_path,
             active_context_name=active_context_name,
         )
-        
+
         # Build minimal context info (inheritance/containment if available)
         context_info: Dict[str, Any] = {
             "name": active_context_name,
@@ -529,10 +581,8 @@ class CommandMetadataAPI:
             empty_display = CommandMetadataAPI._prune_empty(empty_display, remove_keys={"default"})
             rendered = CommandMetadataAPI._to_yaml_like(empty_display, omit_command_name=False)
             # Ensure a visible header is present
-            header = "Commands available:"
-            if not rendered.strip():
-                return header
-            return f"{header}\n{rendered}"
+            header = "Commands available in the current context:"
+            return f"{header}\n{rendered}" if rendered.strip() else header
 
         # Build the combined display by stitching per-command strings while keeping
         # a single "Commands available:" header and blank lines between commands
@@ -553,7 +603,7 @@ class CommandMetadataAPI:
             empty_display = CommandMetadataAPI._prune_empty(empty_display, remove_keys={"default"})
             return CommandMetadataAPI._to_yaml_like(empty_display, omit_command_name=False)
 
-        combined_lines: List[str] = ["Commands available:"]
+        combined_lines: List[str] = [f"Commands available in the current context ({context_info['display_name']}):"]
         for idx, text in enumerate(parts):
             lines = text.splitlines()
             if idx > 0:
@@ -563,6 +613,56 @@ class CommandMetadataAPI:
 
         return "\n".join(combined_lines)
 
+    @staticmethod
+    def get_suggested_commands_metadata(
+        subject_workflow_path: str,
+        cme_workflow_path: str,
+        active_context_name: str,
+        suggested_command_names: list[str],
+        for_agents: bool = False,
+    ) -> str:
+        """
+        Get metadata display text for ONLY the suggested commands.
+
+        Args:
+            subject_workflow_path: Path to the subject workflow
+            cme_workflow_path: Path to the CME workflow
+            active_context_name: Active context name
+            suggested_command_names: List of suggested command names (can be short names or qualified)
+            for_agents: Include agent-specific fields
+
+        Returns:
+            YAML-like formatted string with metadata for suggested commands only
+        """
+        if not suggested_command_names:
+            return "No suggested commands provided."
+
+        parts: list[str] = []
+        for suggested_cmd in suggested_command_names:
+            # Try to get metadata for this command
+            # The command name could be qualified (Context/command) or short (command)
+            if part := CommandMetadataAPI.get_command_display_text_for_command(
+                subject_workflow_path=subject_workflow_path,
+                cme_workflow_path=cme_workflow_path,
+                active_context_name=active_context_name,
+                qualified_command_name=suggested_cmd,
+                for_agents=for_agents,
+            ):
+                parts.append(part)
+
+        if not parts:
+            return "No metadata available for suggested commands."
+
+        # Combine all parts with header
+        combined_lines: list[str] = ["Suggested commands with metadata:"]
+        for idx, text in enumerate(parts):
+            lines = text.splitlines()
+            if idx > 0:
+                combined_lines.append("")  # Blank line separator
+            combined_lines.extend(lines)
+
+        return "\n".join(combined_lines)
+
     @staticmethod
     def get_command_display_text_for_command(
         subject_workflow_path: str,

fastworkflow/examples/fastworkflow.env

@@ -1,8 +1,9 @@
 LLM_SYNDATA_GEN=mistral/mistral-small-latest
 LLM_PARAM_EXTRACTION=mistral/mistral-small-latest
 LLM_RESPONSE_GEN=mistral/mistral-small-latest
-LLM_PLANNER=openrouter/openai/gpt-oss-20b:free
+LLM_PLANNER=mistral/mistral-small-latest
 LLM_AGENT=mistral/mistral-small-latest
+LLM_CONVERSATION_STORE=mistral/mistral-small-latest
 
 SPEEDDICT_FOLDERNAME=___workflow_contexts
 SYNTHETIC_UTTERANCE_GEN_NUMOF_PERSONAS=4

fastworkflow/examples/fastworkflow.passwords.env

@@ -3,4 +3,5 @@ LITELLM_API_KEY_SYNDATA_GEN=<API KEY for synthetic data generation model>
 LITELLM_API_KEY_PARAM_EXTRACTION=<API KEY for parameter extraction model>
 LITELLM_API_KEY_RESPONSE_GEN=<API KEY for response generation model>
 LITELLM_API_KEY_PLANNER=<API KEY for the agent's task planner model>
-LITELLM_API_KEY_AGENT=<API KEY for the agent model>
+LITELLM_API_KEY_AGENT=<API KEY for the agent model>
+LITELLM_API_KEY_CONVERSATION_STORE=<API KEY for conversation topic/summary generation model>