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

fastworkflow/examples/retail_workflow/_commands/exchange_delivered_order_items.py

@@ -24,7 +24,7 @@ class Signature:
         item_ids: List[str] = Field(
             default_factory=list,
             description="The item IDs to be exchanged",
-            examples=["1008292230"],
+            examples=["'34742388', '59475928'"],
             json_schema_extra={
                 "available_from": ["get_order_details"]
             }
@@ -32,7 +32,7 @@ class Signature:
         new_item_ids: List[str] = Field(
             default_factory=list,
             description="The new item IDs to exchange for",
-            examples=["1008292230"],
+            examples=["'45854949', '68789960'"],
             json_schema_extra={
                 "available_from": ["get_product_details"]
             }
@@ -75,7 +75,36 @@ class Signature:
     ) -> tuple[bool, str]:
         if not cmd_parameters.order_id.startswith('#'):
             cmd_parameters.order_id = f'#{cmd_parameters.order_id}'
-        return (True, '')
+
+        error_message = ''
+        if len(cmd_parameters.item_ids) == 0:
+            error_message = 'item ids must be specified\n'
+        for item_id in cmd_parameters.item_ids:
+            try:
+                int(item_id)
+            except ValueError:
+                error_message += 'item ids must be integers\n'
+                break
+
+        if len(cmd_parameters.new_item_ids) == 0:
+            error_message += 'new item ids must be specified\n'
+        for item_id in cmd_parameters.new_item_ids:
+            try:
+                int(item_id)
+            except ValueError:
+                error_message += 'new item ids must be integers\n'
+                break
+
+        if len(cmd_parameters.new_item_ids) != len(cmd_parameters.item_ids):
+            error_message += 'the number of item ids and new item ids must match for a valid exchange\n'
+
+        if common_items := set(cmd_parameters.item_ids).intersection(
+            set(cmd_parameters.new_item_ids)
+        ):
+            common_items_str = ', '.join(common_items)
+            error_message += f'cannot exchange items for themselves: {common_items_str}. new item ids must differ from item ids\n'
+
+        return (False, error_message) if error_message else (True, '')
 
 
 class ResponseGenerator:

fastworkflow/examples/retail_workflow/_commands/find_user_id_by_email.py

@@ -11,16 +11,17 @@ from ..tools.find_user_id_by_email import FindUserIdByEmail
 
 
 class Signature:
-    """Find user id by email"""
+    """
+    Find user id by email. 
+    If email is not available, use `find_user_id_by_name_zip` instead.
+    As a last resort transfer to a human agent
+    """
     class Input(BaseModel):
         """Parameters taken from user utterance."""
 
         email: str = Field(
             default="NOT_FOUND",
-            description=(
-                "The email address to search for. If email is not available, "
-                "use `find_user_id_by_name_zip` instead. As a last resort transfer to a human agent"
-            ),
+            description="The email address to search for",
             pattern=r"^(NOT_FOUND|[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$",
             examples=["user@example.com"],
         )

fastworkflow/examples/retail_workflow/_commands/modify_pending_order_items.py

@@ -24,7 +24,7 @@ class Signature:
         item_ids: List[str] = Field(
             default_factory=list,
             description="List of item IDs to be modified",
-            examples=["1008292230", "2468135790"],
+            examples=["'62727828', '76938178'"],
             json_schema_extra={
                 "available_from": ["get_order_details"]
             }
@@ -32,7 +32,7 @@ class Signature:
         new_item_ids: List[str] = Field(
             default_factory=list,
             description="List of new item IDs to replace with",
-            examples=["1008292231", "2468135791"],
+            examples=["'2352352', '42674747'"],
             json_schema_extra={
                 "available_from": ["get_product_details"]
             }
@@ -75,7 +75,36 @@ class Signature:
     ) -> tuple[bool, str]:
         if not cmd_parameters.order_id.startswith('#'):
             cmd_parameters.order_id = f'#{cmd_parameters.order_id}'
-        return (True, '')
+
+        error_message = ''
+        if len(cmd_parameters.item_ids) == 0:
+            error_message = 'item ids must be specified\n'
+        for item_id in cmd_parameters.item_ids:
+            try:
+                int(item_id)
+            except ValueError:
+                error_message += 'item ids must be integers\n'
+                break
+
+        if len(cmd_parameters.new_item_ids) == 0:
+            error_message += 'new item ids must be specified\n'
+        for item_id in cmd_parameters.new_item_ids:
+            try:
+                int(item_id)
+            except ValueError:
+                error_message += 'new item ids must be integers\n'
+                break
+
+        if len(cmd_parameters.new_item_ids) != len(cmd_parameters.item_ids):
+            error_message += 'the number of item ids and new item ids must match for a valid exchange\n'
+
+        if common_items := set(cmd_parameters.item_ids).intersection(
+            set(cmd_parameters.new_item_ids)
+        ):
+            common_items_str = ', '.join(common_items)
+            error_message += f'cannot modify items for themselves: {common_items_str}. new item ids must differ from item ids\n'
+
+        return (False, error_message) if error_message else (True, '')
 
 
 class ResponseGenerator:

fastworkflow/examples/retail_workflow/_commands/return_delivered_order_items.py

@@ -24,7 +24,7 @@ class Signature:
         item_ids: List[str] = Field(
             default_factory=list,
             description="List of item IDs to be returned",
-            examples=["1008292230"],
+            examples=["'57347828', '8646987326'"],
             json_schema_extra={
                 "available_from": ["get_order_details"]
             }
@@ -69,7 +69,18 @@ class Signature:
     ) -> tuple[bool, str]:
         if not cmd_parameters.order_id.startswith('#'):
             cmd_parameters.order_id = f'#{cmd_parameters.order_id}'
-        return (True, '')
+
+        error_message = ''
+        if len(cmd_parameters.item_ids) == 0:
+            error_message = 'item ids must be specified\n'
+        for item_id in cmd_parameters.item_ids:
+            try:
+                int(item_id)
+            except ValueError:
+                error_message += 'item ids must be integers\n'
+                break
+
+        return (False, error_message) if error_message else (True, '')
 
 
 class ResponseGenerator:

fastworkflow/examples/retail_workflow/_commands/transfer_to_human_agents.py

@@ -10,7 +10,7 @@ from ..tools.transfer_to_human_agents import TransferToHumanAgents
 
 
 class Signature:
-    """Transfer to a human agent ONLY AS THE LAST RESORT"""
+    """Transfer to a human agent ONLY if the user demands it explicitly."""
     class Input(BaseModel):
         summary: str = Field(
             default="NOT_FOUND",

fastworkflow/intent_clarification_agent.py

@@ -0,0 +1,131 @@
+"""
+Intent detection error state agent module for fastWorkflow.
+Specialized agent for handling intent detection errors.
+"""
+
+import json
+import dspy
+
+import fastworkflow
+from fastworkflow.utils.react import fastWorkflowReAct
+from fastworkflow.command_metadata_api import CommandMetadataAPI
+
+
+class IntentClarificationAgentSignature(dspy.Signature):
+    """
+    Handle intent detection errors by clarifying user intent.
+    You are provided with:
+    1. The workflow agent's inputs and trajectory - showing what the agent has been trying to do
+    2. Suggested commands metadata (for intent ambiguity) or empty (for intent misunderstanding - use show_available_commands tool)
+
+    Review the agent trajectory to understand the context and what led to this error.
+    If suggested_commands_metadata is provided, review it carefully to understand each command's purpose, parameters, and usage.
+    If suggested_commands_metadata is empty, use the show_available_commands tool to get the full list of available commands.
+    IMPORTANT: When clarifying intent, preserve ALL parameters from the original command.
+    Use available tools to resolve ambiguous or misunderstood commands. Use the ask_user tool ONLY as a last resort. Return the complete clarified command with the correct name and all original parameters.
+    """
+    original_command = dspy.InputField(desc="The original command with all parameters that caused the error.")
+    error_message = dspy.InputField(desc="The intent detection error message from the workflow.")
+    agent_inputs = dspy.InputField(desc="The original inputs to the workflow agent.")
+    agent_trajectory = dspy.InputField(desc="The workflow agent's trajectory showing all actions taken so far leading to this error.")
+    clarified_command = dspy.OutputField(desc="The complete command with correct command name AND all original parameters preserved.")
+
+
+# def _show_available_commands(chat_session: fastworkflow.ChatSession) -> str:
+#     """
+#     Show available commands to help resolve intent detection errors.
+
+#     Args:
+#         chat_session: The chat session instance
+
+#     Returns:
+#         List of available commands
+#     """
+
+#     current_workflow = chat_session.get_active_workflow()
+#     return CommandMetadataAPI.get_command_display_text(
+#         subject_workflow_path=current_workflow.folderpath,
+#         cme_workflow_path=fastworkflow.get_internal_workflow_path("command_metadata_extraction"),
+#         active_context_name=current_workflow.current_command_context_name,
+#     )
+
+
+def _ask_user_for_clarification(
+    clarification_request: str,
+    chat_session: fastworkflow.ChatSession
+) -> str:
+    """
+    Ask user for clarification when intent is unclear.
+
+    Args:
+        clarification_request: The question to ask the user
+        chat_session: The chat session instance
+
+    Returns:
+        User's response
+    """
+    command_output = fastworkflow.CommandOutput(
+        command_responses=[fastworkflow.CommandResponse(response=clarification_request)],
+        workflow_name=chat_session.get_active_workflow().folderpath.split('/')[-1]
+    )
+    chat_session.command_output_queue.put(command_output)
+
+    user_response = chat_session.user_message_queue.get()
+
+    # Log to action.jsonl (shared with main agent)
+    with open("action.jsonl", "a", encoding="utf-8") as f:
+        agent_user_dialog = {
+            "intent_clarification_agent": True,
+            "agent_query": clarification_request,
+            "user_response": user_response
+        }
+        f.write(json.dumps(agent_user_dialog, ensure_ascii=False) + "\n")
+
+    return user_response
+
+
+def initialize_intent_clarification_agent(
+    chat_session: fastworkflow.ChatSession,
+    max_iters: int = 20
+):
+    """
+    Initialize a specialized agent for handling intent detection errors.
+    This agent has a limited tool set and shares traces with the main execution agent.
+
+    Args:
+        chat_session: The chat session instance
+        max_iters: Maximum iterations for the agent (default: 10)
+
+    Returns:
+        DSPy ReAct agent configured for intent detection error handling
+    """
+    if not chat_session:
+        raise ValueError("chat_session cannot be null")
+
+    # def show_available_commands() -> str:
+    #     """
+    #     Show all available commands to help resolve intent ambiguity.
+    #     """
+    #     return _show_available_commands(chat_session)
+
+    def ask_user(clarification_request: str) -> str:
+        """
+        Ask the user for clarification when the intent is unclear.
+        Use this as a last resort when you cannot determine the correct command.
+
+        Args:
+            clarification_request: Clear question to ask the user
+        """
+        return _ask_user_for_clarification(clarification_request, chat_session)
+
+    # Limited tool set for intent detection errors
+    tools = [
+        # show_available_commands,
+        ask_user,
+    ]
+
+    return fastWorkflowReAct(
+        IntentClarificationAgentSignature,
+        tools=tools,
+        max_iters=max_iters,
+    )

fastworkflow/mcp_server.py

@@ -41,7 +41,7 @@ class FastWorkflowMCPServer:
         NOT_FOUND = fastworkflow.get_env_var('NOT_FOUND')
 
         # Get available commands from workflow
-        workflow = fastworkflow.ChatSession.get_active_workflow()
+        workflow = fastworkflow.chat_session.get_active_workflow()
         workflow_folderpath = workflow.folderpath
         # Use cached routing definition instead of rebuilding every time
         routing = RoutingRegistry.get_definition(workflow_folderpath)
@@ -147,7 +147,7 @@ class FastWorkflowMCPServer:
             arguments=arguments
         )
         
-        workflow = fastworkflow.ChatSession.get_active_workflow()
+        workflow = fastworkflow.chat_session.get_active_workflow()
         # Execute using MCP-compliant method
         return CommandExecutor.perform_mcp_tool_call(
             workflow,
@@ -203,7 +203,7 @@ class FastWorkflowMCPServer:
 
         Falls back to the first available path if the active context is none.
         """
-        workflow = fastworkflow.ChatSession.get_active_workflow()
+        workflow = fastworkflow.chat_session.get_active_workflow()
         return workflow.current_command_context_name
 
 

fastworkflow/run/__main__.py

@@ -19,14 +19,13 @@ def run_main(args):
     from rich.table import Table
     from rich.text import Text
     from rich.console import Group
-    from rich.live import Live
     from rich.spinner import Spinner
     from prompt_toolkit import PromptSession
     from prompt_toolkit.patch_stdout import patch_stdout
+    from prompt_toolkit.formatted_text import HTML
 
     import fastworkflow
     from fastworkflow.utils.logging import logger
-    from fastworkflow.command_executor import CommandExecutor
 
     # Progress bar helper
     from fastworkflow.utils.startup_progress import StartupProgress
@@ -34,7 +33,7 @@ def run_main(args):
     # Instantiate a global console for consistent styling
     global console
     console = Console()
-    prompt_session = PromptSession("User > ")
+    prompt_session = PromptSession(HTML('<b>User ></b> '))
 
     def _build_artifact_table(artifacts: dict[str, str]) -> Table:
         """Return a rich.Table representation for artifact key-value pairs."""
@@ -60,7 +59,7 @@ def run_main(args):
         if command_output.command_name:
             command_info_table.add_row("Command:", Text(command_output.command_name, style="yellow"))
         if command_output.command_parameters:
-            command_info_table.add_row("Parameters:", Text(command_output.command_parameters, style="yellow"))
+            command_info_table.add_row("Parameters:", Text(str(command_output.command_parameters.model_dump()), style="yellow"))
         
         # Add command info section if we have any rows
         if command_info_table.row_count > 0:
@@ -138,15 +137,13 @@ def run_main(args):
         raise ValueError("Cannot provide both startup_command and startup_action")
 
     console.print(Panel(f"Running fastWorkflow: [bold]{args.workflow_path}[/bold]", title="[bold green]fastworkflow[/bold green]", border_style="green"))
-    console.print("[bold green]Tip:[/bold green] Type 'exit' to quit the application.")
+    console.print(
+        "[bold green]Tips:[/bold green] Type '//exit' to quit the application. Type '//new' to start a new conversation. " 
+        "[bold green]Tips:[/bold green] Prefix natural language commands with a single '/' to execute them in deterministic (non-agentic) mode")
 
     # ------------------------------------------------------------------
     # Startup progress bar ------------------------------------------------
     # ------------------------------------------------------------------
-    command_info_root = os.path.join(args.workflow_path, "___command_info")
-    subdir_count = 0
-    if os.path.isdir(command_info_root):
-        subdir_count = len([d for d in os.listdir(command_info_root) if os.path.isdir(os.path.join(command_info_root, d))])
 
     # 3 coarse CLI steps + per-directory warm-up (handled inside ChatSession) + 1 global warm-up
     StartupProgress.begin(total=3)
@@ -168,9 +165,9 @@ def run_main(args):
         with open(args.context_file_path, 'r') as file:
             context_dict = json.load(file)
 
-    # Create the chat session with agent mode if specified
-    run_as_agent = args.run_as_agent if hasattr(args, 'run_as_agent') else False
-    fastworkflow.chat_session = fastworkflow.ChatSession(run_as_agent=run_as_agent)
+    # Create the chat session in agent mode always
+    # run_as_agent = args.run_as_agent if hasattr(args, 'run_as_agent') else False
+    fastworkflow.chat_session = fastworkflow.ChatSession(run_as_agent=True)
     
     # Start the workflow within the chat session
     fastworkflow.chat_session.start_workflow(
@@ -193,8 +190,12 @@ def run_main(args):
     while not fastworkflow.chat_session.workflow_is_complete or args.keep_alive:
         with patch_stdout():
             user_command = prompt_session.prompt()
-        if user_command == "exit":
+        if user_command.startswith("//exit"):
             break
+        if user_command.startswith("//new"):
+            fastworkflow.chat_session.clear_conversation_history()
+            console.print("[bold]Agent >[/bold] New conversation started!\n", end="")
+            user_command = prompt_session.prompt()
 
         fastworkflow.chat_session.user_message_queue.put(user_command)
 
@@ -219,28 +220,25 @@ def run_main(args):
         with console.status("[bold cyan]Processing command...[/bold cyan]", spinner="dots") as status:
             counter = 0
             while wait_thread.is_alive():
-                # Check for agent traces if in agent mode
-                if args.run_as_agent:
-                    while True:
-                        try:
-                            evt = fastworkflow.chat_session.command_trace_queue.get_nowait()
-                        except queue.Empty:
-                            break
-                        
-                        # Choose styles based on success
-                        info_style = "dim orange3" if (evt.success is False) else "dim yellow"
-                        resp_style = "dim orange3" if (evt.success is False) else "dim green"
+                # Always show agent traces (run mode is always agentic)
+                while True:
+                    try:
+                        evt = fastworkflow.chat_session.command_trace_queue.get_nowait()
+                    except queue.Empty:
+                        break
+                    
+                    # Choose styles based on success
+                    info_style = "dim orange3" if (evt.success is False) else "dim yellow"
+                    resp_style = "dim orange3" if (evt.success is False) else "dim green"
 
-                        if evt.direction == fastworkflow.CommandTraceEventDirection.AGENT_TO_WORKFLOW:
-                            console.print(Text("Agent -> Workflow: ", style=info_style), end="")
-                            console.print(Text(str(evt.raw_command or ""), style=info_style))
-                        else:
-                            # command info (dim yellow or dim orange3)
-                            info = f"{evt.command_name or ''}, {evt.parameters}: "
-                            console.print(Text("Workflow -> Agent: ", style=info_style), end="")
-                            console.print(Text(info, style=info_style), end="")
-                            # response (dim green or dim orange3)
-                            console.print(Text(str(evt.response_text or ""), style=resp_style))
+                    if evt.direction == fastworkflow.CommandTraceEventDirection.AGENT_TO_WORKFLOW:
+                        console.print(f'[bold]Agent >[/bold] {evt.raw_command}', style=info_style)
+                    else:
+                        # command info (dim yellow or dim orange3)
+                        info = f"[bold]Workflow >[/bold] {evt.command_name or ''}, {evt.parameters}: "
+                        console.print(info, style=info_style, end="")
+                        # response (dim green or dim orange3)
+                        console.print(f'[bold]Workflow >[/bold] {evt.response_text}', style=resp_style)
 
                 time.sleep(0.5)
                 counter += 1
@@ -273,11 +271,6 @@ if __name__ == "__main__":
     parser.add_argument(
         "--project_folderpath", help="Optional path to project folder containing application code", default=None
     )
-    parser.add_argument(
-        "--run_as_agent", 
-        help="Run in agent mode (uses DSPy for tool selection)", 
-        action="store_true",
-        default=False
-    )
+    # run mode is always agentic; deterministic NL execution can be forced by prefixing '/' to a command
     args = parser.parse_args()
     run_main(args)