fastworkflow 2.17.8__py3-none-any.whl → 2.17.10__py3-none-any.whl

fastworkflow/_workflows/command_metadata_extraction/parameter_extraction.py

@@ -1,8 +1,10 @@
 import contextlib
 import sys
+import re
 from typing import Dict, List, Optional
 
 from pydantic import BaseModel
+from pydantic_core import PydanticUndefined
 
 import fastworkflow
 from fastworkflow.utils.logging import logger
@@ -59,11 +61,29 @@ class ParameterExtraction:
         if stored_params:
             new_params = self._extract_and_merge_missing_parameters(stored_params, self.command)
         else:
-            # Otherwise use the LLM-based extraction
-            new_params = input_for_param_extraction.extract_parameters(
-                command_parameters_class, 
-                self.command_name, 
-                app_workflow_folderpath)
+            # Check if we're in agentic mode (not assistant mode command)
+            is_agentic_mode = (
+                "is_assistant_mode_command" not in self.cme_workflow.context
+                and "run_as_agent" in self.app_workflow.context
+                and self.app_workflow.context["run_as_agent"]
+            )
+
+            if is_agentic_mode:
+                # Try regex-based extraction first in agentic mode
+                new_params = self._extract_parameters_from_xml(self.command, command_parameters_class)
+
+                # If regex extraction fails, fall back to LLM-based extraction
+                if new_params is None:
+                    new_params = input_for_param_extraction.extract_parameters(
+                        command_parameters_class,
+                        self.command_name,
+                        app_workflow_folderpath)
+            else:
+                # Use LLM-based extraction for assistant mode
+                new_params = input_for_param_extraction.extract_parameters(
+                    command_parameters_class,
+                    self.command_name,
+                    app_workflow_folderpath)
 
         is_valid, error_msg, suggestions, missing_invalid_fields = \
             input_for_param_extraction.validate_parameters(
@@ -272,6 +292,62 @@ class ParameterExtraction:
         # Construct model without validation
         return default_params.__class__.model_construct(**params_data)
 
+    @staticmethod
+    def _extract_parameters_from_xml(command: str, command_parameters_class: type[BaseModel]) -> Optional[BaseModel]:
+        """
+        Extract parameters from XML-formatted command using regex.
+
+        Returns:
+            BaseModel instance with extracted parameters, or None if parsing fails
+        """
+        field_names = list(command_parameters_class.model_fields.keys())
+
+        # If no parameters are defined, return empty model immediately
+        if not field_names:
+            return command_parameters_class.model_construct()
+
+        extracted_data = {}
+
+        # Try to extract each parameter using XML tags
+        for field_name in field_names:
+            # Look for <field_name>value</field_name> pattern
+            pattern = rf'<{re.escape(field_name)}>(.+?)</{re.escape(field_name)}>'
+            if match := re.search(pattern, command, re.DOTALL):
+                parameter_value = match[1].strip()
+                extracted_data[field_name] = parameter_value
+
+        # Check if we extracted values for ALL fields (safest criteria for LLM fallback)
+        all_fields_extracted = len(extracted_data) == len(field_names)
+
+        # Check if agent used example values
+        if all_fields_extracted:
+            for field_name, extracted_value in extracted_data.items():
+                field_info = command_parameters_class.model_fields[field_name]
+                examples = getattr(field_info, "examples", None)
+                if examples and extracted_value in examples:
+                    all_fields_extracted = False
+                    break
+
+        if all_fields_extracted:
+            # Initialize all fields with their default values (if they exist) or None
+            params_data = {}
+            for field_name in field_names:
+                field_info = command_parameters_class.model_fields[field_name]
+                if field_info.default is not PydanticUndefined:
+                    params_data[field_name] = field_info.default
+                elif field_info.default_factory is not None:
+                    params_data[field_name] = field_info.default_factory()
+                else:
+                    params_data[field_name] = None
+
+            # Update with extracted values
+            params_data |= extracted_data
+
+            # Construct model without validation
+            return command_parameters_class.model_construct(**params_data)
+
+        return None
+
     @staticmethod
     def _extract_and_merge_missing_parameters(stored_params: BaseModel, command: str):
         """

fastworkflow/chat_session.py

@@ -8,6 +8,7 @@ import contextlib
 import uuid
 from pathlib import Path
 import os
+import time
 from datetime import datetime
 
 import dspy
@@ -133,7 +134,8 @@ class ChatSession:
         
         # Initialize agent-related attributes
         self._run_as_agent = run_as_agent
-        self._workflow_tool_agent = None            
+        self._workflow_tool_agent = None
+        self._intent_clarification_agent = None            
         
         # Create the command metadata extraction workflow with a unique ID
         self._cme_workflow = fastworkflow.Workflow.create(
@@ -272,13 +274,23 @@ class ChatSession:
         self._current_workflow.context["run_as_agent"] = True
 
         # Initialize the workflow tool agent
-        from fastworkflow.workflow_agent import initialize_workflow_tool_agent       
+        from fastworkflow.workflow_agent import initialize_workflow_tool_agent
         self._workflow_tool_agent = initialize_workflow_tool_agent(self)
 
+        # Initialize the intent clarification agent
+        from fastworkflow.intent_clarification_agent import initialize_intent_clarification_agent
+        self._intent_clarification_agent = initialize_intent_clarification_agent(self)
+
     @property
     def workflow_tool_agent(self):
         """Get the workflow tool agent for agent mode."""
         return self._workflow_tool_agent
+
+    @property
+    def intent_clarification_agent(self):
+        """Get the intent clarification agent for agent mode."""
+        return self._intent_clarification_agent
+
     @property
     def cme_workflow(self) -> fastworkflow.Workflow:
         """Get the command metadata extraction workflow."""
@@ -360,21 +372,23 @@ class ChatSession:
                 try:
                     message = self.user_message_queue.get()
 
-                    if ((
-                            "NLU_Pipeline_Stage" not in self._cme_workflow.context or
-                            self._cme_workflow.context["NLU_Pipeline_Stage"] == fastworkflow.NLUPipelineStage.INTENT_DETECTION) and
-                        message.startswith('/')
-                    ):
-                        self._cme_workflow.context["is_assistant_mode_command"] = True
-                    
-                    # Route based on mode and message type
-                    if self._run_as_agent and "is_assistant_mode_command" not in self._cme_workflow.context:
-                        # In agent mode, use workflow tool agent for processing
-                        last_output = self._process_agent_message(message)
-                    # elif self._is_mcp_tool_call(message):
-                    #     last_output = self._process_mcp_tool_call(message)
+                    # Handle Action objects directly
+                    if isinstance(message, fastworkflow.Action):
+                        last_output = self._process_action(message)
                     else:
-                        last_output = self._process_message(message)
+                        if ((
+                                "NLU_Pipeline_Stage" not in self._cme_workflow.context or
+                                self._cme_workflow.context["NLU_Pipeline_Stage"] == fastworkflow.NLUPipelineStage.INTENT_DETECTION) and
+                            message.startswith('/')
+                        ):
+                            self._cme_workflow.context["is_assistant_mode_command"] = True
+
+                        # Route based on mode and message type
+                        if self._run_as_agent and "is_assistant_mode_command" not in self._cme_workflow.context:
+                            # In agent mode, use workflow tool agent for processing
+                            last_output = self._process_agent_message(message)
+                        else:
+                            last_output = self._process_message(message)
                         
                 except Empty:
                     continue
@@ -543,13 +557,22 @@ class ChatSession:
 
     def _process_message(self, message: str) -> fastworkflow.CommandOutput:
         """Process a single message"""
-        # Use our specialized profiling method
-        # command_output = self.profile_invoke_command(message)
-        
+        # Pre-execution trace
+        if self.command_trace_queue:
+            self.command_trace_queue.put(fastworkflow.CommandTraceEvent(
+                direction=fastworkflow.CommandTraceEventDirection.AGENT_TO_WORKFLOW,
+                raw_command=message,
+                command_name=None,
+                parameters=None,
+                response_text=None,
+                success=None,
+                timestamp_ms=int(time.time() * 1000),
+            ))
+        
+        # Execute command
         command_output = self._CommandExecutor.invoke_command(self, message)
 
-        # Record assistant mode trace to action.jsonl (similar to agent mode in workflow_agent.py)
-        # This ensures assistant commands are captured even when interspersed with agent commands
+        # Extract response text and parameters for traces
         response_text = ""
         if command_output.command_responses:
             response_text = command_output.command_responses[0].response or ""
@@ -557,14 +580,30 @@ class ChatSession:
         # Convert parameters to dict if it's a Pydantic model or other complex object
         params = command_output.command_parameters or {}
         if hasattr(params, 'model_dump'):
-            params = params.model_dump()
+            params_dict = params.model_dump()
         elif hasattr(params, 'dict'):
-            params = params.dict()
+            params_dict = params.dict()
+        else:
+            params_dict = params
+        
+        # Post-execution trace
+        if self.command_trace_queue:
+            self.command_trace_queue.put(fastworkflow.CommandTraceEvent(
+                direction=fastworkflow.CommandTraceEventDirection.WORKFLOW_TO_AGENT,
+                raw_command=None,
+                command_name=command_output.command_name or "",
+                parameters=params_dict,
+                response_text=response_text,
+                success=bool(command_output.success),
+                timestamp_ms=int(time.time() * 1000),
+            ))
         
+        # Record assistant mode trace to action.jsonl (similar to agent mode in workflow_agent.py)
+        # This ensures assistant commands are captured even when interspersed with agent commands
         record = {
             "command": message,
             "command_name": command_output.command_name or "",
-            "parameters": params,
+            "parameters": params_dict,
             "response": response_text
         }
 
@@ -589,24 +628,54 @@ class ChatSession:
     def _process_action(self, action: fastworkflow.Action) -> fastworkflow.CommandOutput:
         """Process a startup action"""
         workflow = self.get_active_workflow()
+        
+        # Serialize action parameters for trace
+        params = action.parameters or {}
+        if hasattr(params, 'model_dump'):
+            params_dict = params.model_dump()
+        elif hasattr(params, 'dict'):
+            params_dict = params.dict()
+        else:
+            params_dict = params
+        
+        # Pre-execution trace: serialize action as raw_command
+        raw_command = f"{action.command_name} {json.dumps(params_dict)}"
+        if self.command_trace_queue:
+            self.command_trace_queue.put(fastworkflow.CommandTraceEvent(
+                direction=fastworkflow.CommandTraceEventDirection.AGENT_TO_WORKFLOW,
+                raw_command=raw_command,
+                command_name=None,
+                parameters=None,
+                response_text=None,
+                success=None,
+                timestamp_ms=int(time.time() * 1000),
+            ))
+        
+        # Execute the action
         command_output = self._CommandExecutor.perform_action(workflow, action)
 
-        # Record action trace to action.jsonl
+        # Extract response text for post-execution trace
         response_text = ""
         if command_output.command_responses:
             response_text = command_output.command_responses[0].response or ""
         
-        # Convert parameters to dict if it's a Pydantic model or other complex object
-        params = action.parameters or {}
-        if hasattr(params, 'model_dump'):
-            params = params.model_dump()
-        elif hasattr(params, 'dict'):
-            params = params.dict()
+        # Post-execution trace
+        if self.command_trace_queue:
+            self.command_trace_queue.put(fastworkflow.CommandTraceEvent(
+                direction=fastworkflow.CommandTraceEventDirection.WORKFLOW_TO_AGENT,
+                raw_command=None,
+                command_name=command_output.command_name,
+                parameters=params_dict,
+                response_text=response_text,
+                success=bool(command_output.success),
+                timestamp_ms=int(time.time() * 1000),
+            ))
         
+        # Record action trace to action.jsonl
         record = {
             "command": "process_action",
             "command_name": action.command_name,
-            "parameters": params,
+            "parameters": params_dict,
             "response": response_text
         }
 
@@ -647,7 +716,7 @@ class ChatSession:
     def _extract_conversation_summary(self, 
         user_query: str, workflow_actions: list[dict[str, str]], final_agent_response: str) -> str:
         """
-        Summarizes conversation based on original user query, workflow actions and agentt response.
+        Summarizes conversation based on original user query, workflow actions and agent response.
         Returns the conversation summary and the log entry
         """
         # Lets log everything to a file called action_log.jsonl, if it exists

fastworkflow/command_metadata_api.py

@@ -613,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/intent_clarification_agent.py

@@ -0,0 +1,132 @@
+"""
+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.")
+    suggested_commands_metadata = dspy.InputField(desc="Metadata for suggested commands (for ambiguity clarification), or empty string (for misunderstanding - use show_available_commands tool instead).")
+    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,
+    )