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

fastworkflow/workflow_agent.py

@@ -11,17 +11,16 @@ import fastworkflow
 from fastworkflow.utils.logging import logger
 from fastworkflow.utils import dspy_utils
 from fastworkflow.command_metadata_api import CommandMetadataAPI
-from fastworkflow.mcp_server import FastWorkflowMCPServer
+from fastworkflow.utils.react import fastWorkflowReAct
 
 
 class WorkflowAgentSignature(dspy.Signature):
     """
-    Carefully review the user request and conversation_history, then execute the todo list using available tools for building the final answer.
-    All the tasks in the todo list must be completed before returning the final answer.
+    Carefully review the user request, then execute the next steps using available tools for building the final answer.
+    Every user intent must be fully addressed before returning the final answer.
     """
     user_query = dspy.InputField(desc="The natural language user query.")
-    conversation_history: dspy.History = dspy.InputField()
-    final_answer = dspy.OutputField(desc="Comprehensive final answer with supporting evidence to demonstrate that all the tasks in the todo list have been completed.")
+    final_answer = dspy.OutputField(desc="Comprehensive final answer with supporting evidence to demonstrate that every user intent has been fully addressed.")
 
 def _what_can_i_do(chat_session_obj: fastworkflow.ChatSession) -> str:
     """
@@ -34,44 +33,13 @@ def _what_can_i_do(chat_session_obj: fastworkflow.ChatSession) -> str:
         active_context_name=current_workflow.current_command_context_name,
     )
 
-def _clarify_ambiguous_intent(
-        correct_command_name: str,
-        chat_session_obj: fastworkflow.ChatSession) -> str:
-    """
-    Call this tool ONLY in the intent detection error state (ambiguous or misunderstood intent) to provide the exact command name.
-    The intent detection error message will list the command names to pick from.
-    """
-    return _execute_workflow_query(correct_command_name, chat_session_obj = chat_session_obj)
-
-def _provide_missing_or_corrected_parameters(
-        missing_or_corrected_parameter_values: list[str|int|float|bool],
-        chat_session_obj: fastworkflow.ChatSession) -> str:
-    """
-    Call this tool ONLY in the parameter extraction error state to provide missing or corrected parameter values.
-    Missing parameter values may be found in the user query, or information already available, or by aborting and executing a different command (refer to the optional 'available_from' hint for guidance on appropriate commands to use to get the information).
-    If the error message indicates parameter values are improperly formatted, correct using your internal knowledge and command metadata information.
-    """
-    if missing_or_corrected_parameter_values:
-        command = ', '.join(missing_or_corrected_parameter_values)
-    else:
-        return "Provide missing or corrected parameter values or abort"
-    
-    return _execute_workflow_query(command, chat_session_obj = chat_session_obj)
-
-def _abort_current_command_to_exit_parameter_extraction_error_state(
-        chat_session_obj: fastworkflow.ChatSession) -> str:
-    """
-    Call this tool ONLY in the parameter extraction error state when you want to get out of the parameter extraction error state and execute a different command.
-    """
-    return _execute_workflow_query('abort', chat_session_obj = chat_session_obj)
-
 def _intent_misunderstood(
         chat_session_obj: fastworkflow.ChatSession) -> str:
     """
     Shows the full list of available command names so you can specify the command name you really meant
     Call this tool when your intent is misunderstood (i.e. the wrong command name is executed).
     """
-    return _execute_workflow_query('you misunderstood', chat_session_obj = chat_session_obj)
+    return _what_can_i_do(chat_session_obj = chat_session_obj)
 
 def _execute_workflow_query(command: str, chat_session_obj: fastworkflow.ChatSession) -> str:
     """
@@ -100,95 +68,168 @@ def _execute_workflow_query(command: str, chat_session_obj: fastworkflow.ChatSes
     # Extract command name and parameters from command_output
     name = command_output.command_name
     params = command_output.command_parameters
-    
+
     # Handle parameter serialization
     params_dict = params.model_dump() if params else None
-    
+
     # Extract response text
-    resp_text = ""
+    response_text = ""
     if command_output.command_responses:
-        response_parts = [
+        response_parts = []
+        response_parts.extend(
             cmd_response.response
             for cmd_response in command_output.command_responses
             if cmd_response.response
-        ]
-        resp_text = "\n".join(response_parts)
-    
+        )
+        response_text = "\n".join(response_parts) \
+            if response_parts else "Command executed successfully but produced no output."
+
     chat_session_obj.command_trace_queue.put(fastworkflow.CommandTraceEvent(
         direction=fastworkflow.CommandTraceEventDirection.WORKFLOW_TO_AGENT,
         raw_command=None,
         command_name=name,
         parameters=params_dict,
-        response_text=resp_text or "",
+        response_text=response_text,
         success=bool(command_output.success),
         timestamp_ms=int(time.time() * 1000),
     ))
 
-    # Append executed action to action.json for external consumers (agent mode only)
+    # Append executed action to action.jsonl for external consumers (agent mode only)
     record = {
-        "command" if command_output.success else "failing command": command,
+        "command": command,
         "command_name": name,
         "parameters": params_dict,
-        "response": resp_text if command_output.success else ""
+        "response": response_text
     }
-    with open("action.json", "a", encoding="utf-8") as f:
+    with open("action.jsonl", "a", encoding="utf-8") as f:
         f.write(json.dumps(record, ensure_ascii=False) + "\n")
 
-    # Format output - extract text from command response
-    if command_output.command_responses:
-        response_parts = []
-        response_parts.extend(
-            cmd_response.response
-            for cmd_response in command_output.command_responses
-            if cmd_response.response
-        )
-        return "\n".join(response_parts) if response_parts else "Command executed successfully."
-
-    return "Command executed but produced no output."
-
-def _missing_information_guidance_tool(
-        how_to_find_request: str, 
-        chat_session_obj: fastworkflow.ChatSession) -> str:
-    """
-    Request guidance on finding missing information. 
-    The how_to_find_request must be plain text without any formatting.
-    """
-    lm = dspy_utils.get_lm("LLM_AGENT", "LITELLM_API_KEY_AGENT")
-    with dspy.context(lm=lm):
-        guidance_func = dspy.ChainOfThought(
-            "command_info, missing_information_guidance_request -> guidance: str")
-        prediction = guidance_func(
-            command_info=_what_can_i_do(chat_session_obj), 
-            missing_information_guidance_request=how_to_find_request)
-        return prediction.guidance
+    # Check workflow context to determine if we're in an error state that needs specialized handling
+    cme_workflow = chat_session_obj.cme_workflow
+    nlu_stage = cme_workflow.context.get("NLU_Pipeline_Stage")
+
+    # Handle intent ambiguity clarification state with specialized agent
+    if nlu_stage == fastworkflow.NLUPipelineStage.INTENT_AMBIGUITY_CLARIFICATION:
+        if intent_agent := chat_session_obj.intent_clarification_agent:
+            from fastworkflow.utils.chat_adapter import CommandsSystemPreludeAdapter    
+            # Use CommandsSystemPreludeAdapter specifically for workflow agent calls
+            agent_adapter = CommandsSystemPreludeAdapter()
+
+            # Get suggested commands from intent detection system
+            from fastworkflow._workflows.command_metadata_extraction.intent_detection import CommandNamePrediction
+            predictor = CommandNamePrediction(cme_workflow)
+            suggested_commands = predictor._get_suggested_commands(predictor.path)
+
+            suggested_commands = list(suggested_commands) if suggested_commands is not None else []
+
+            # Get metadata for only the suggested commands
+            current_workflow = chat_session_obj.get_active_workflow()
+            suggested_commands_metadata = CommandMetadataAPI.get_suggested_commands_metadata(
+                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,
+                suggested_command_names=suggested_commands
+            )
+
+            # Get the workflow agent's trajectory and inputs for context
+            workflow_tool_agent = chat_session_obj.workflow_tool_agent
+            agent_inputs = workflow_tool_agent.inputs if workflow_tool_agent else {}
+            agent_trajectory = workflow_tool_agent.current_trajectory if workflow_tool_agent else {}
+
+            lm = dspy_utils.get_lm("LLM_AGENT", "LITELLM_API_KEY_AGENT")
+            with dspy.context(lm=lm, adapter=agent_adapter):
+                result = intent_agent(
+                    original_command=command,
+                    error_message=response_text,
+                    agent_inputs=agent_inputs,
+                    agent_trajectory=agent_trajectory,
+                    available_commands=suggested_commands_metadata  # Note that this is not part of the signature. It is extra metadata that will be picked up by the CommandsSystemPreludeAdapter
+                )
+            # The clarified command should have the correct name with all original parameters
+            clarified_cmd = result.clarified_command if hasattr(result, 'clarified_command') else str(result)
+            # Execute the clarified command
+            return _execute_workflow_query(clarified_cmd, chat_session_obj=chat_session_obj)
+        else:
+            # No intent clarification agent available, fall back to abort
+            abort_confirmation = _execute_workflow_query('abort', chat_session_obj=chat_session_obj)
+            return f'{response_text}\n{abort_confirmation}'
+
+    # Handle intent misunderstanding clarification state with specialized agent
+    if nlu_stage == fastworkflow.NLUPipelineStage.INTENT_MISUNDERSTANDING_CLARIFICATION:
+        if intent_agent := chat_session_obj.intent_clarification_agent:
+            # Get the workflow agent's trajectory and inputs for context
+            workflow_tool_agent = chat_session_obj.workflow_tool_agent
+            agent_inputs = workflow_tool_agent.inputs if workflow_tool_agent else {}
+            agent_trajectory = workflow_tool_agent.current_trajectory if workflow_tool_agent else {}
+
+            lm = dspy_utils.get_lm("LLM_AGENT", "LITELLM_API_KEY_AGENT")
+            with dspy.context(lm=lm):
+                result = intent_agent(
+                    original_command=command,
+                    error_message=response_text,
+                    agent_inputs=agent_inputs,
+                    agent_trajectory=agent_trajectory,
+                )
+
+            clarified_cmd = result.clarified_command if hasattr(result, 'clarified_command') else str(result)
+
+            return _execute_workflow_query(clarified_cmd, chat_session_obj=chat_session_obj)
+        else:
+            # No intent clarification agent available, fall back to abort
+            abort_confirmation = _execute_workflow_query('abort', chat_session_obj=chat_session_obj)
+            return f'{response_text}\n{abort_confirmation}'
+
+    # Handle parameter extraction errors with abort
+    if nlu_stage == fastworkflow.NLUPipelineStage.PARAMETER_EXTRACTION:
+        abort_confirmation = _execute_workflow_query('abort', chat_session_obj=chat_session_obj)
+        return f'{response_text}\n{abort_confirmation}'
+
+    # Clean up the context flag after command execution
+    workflow = chat_session_obj.get_active_workflow()
+    if workflow and "is_user_command" in workflow.context:
+        del workflow.context["is_user_command"]
+    
+    return response_text
 
 def _ask_user_tool(clarification_request: str, chat_session_obj: fastworkflow.ChatSession) -> str:
     """
-    As a last resort, request clarification for missing information (only after using the missing_information_guidance_tool) or error correction from the human user. 
+    If the missing_information_guidance_tool does not help and only as the last resort, request clarification for missing information from the human user. 
     The clarification_request must be plain text without any formatting.
+    Note that using the wrong command name can produce missing information errors. Double-check with the missing_information_guidance_tool to verify that the correct command name is being used 
     """
     command_output = fastworkflow.CommandOutput(
-        command_responses=[fastworkflow.CommandResponse(response=clarification_request)]
-    )
+        command_responses=[fastworkflow.CommandResponse(response=clarification_request)],
+        workflow_name = chat_session_obj.get_active_workflow().folderpath.split('/')[-1]
+    )    
     chat_session_obj.command_output_queue.put(command_output)
+
     user_query = chat_session_obj.user_message_queue.get()
-    return _think_and_plan(user_query, chat_session_obj)
 
-def initialize_workflow_tool_agent(mcp_server: FastWorkflowMCPServer, max_iters: int = 25):
+    # add the agent user dialog to the log
+    with open("action.jsonl", "a", encoding="utf-8") as f:
+        agent_user_dialog = {
+            "agent_query": clarification_request,
+            "user_response": user_query
+        }
+        f.write(json.dumps(agent_user_dialog, ensure_ascii=False) + "\n")
+
+    return build_query_with_next_steps(user_query, chat_session_obj, with_agent_inputs_and_trajectory = True)
+
+def initialize_workflow_tool_agent(chat_session: fastworkflow.ChatSession, max_iters: int = 25):
     """
     Initialize and return a DSPy ReAct agent that exposes individual MCP tools.
     Each tool expects a single query string for its specific tool.
     
     Args:
-        mcp_server: FastWorkflowMCPServer instance
+        chat_session: fastworkflow.ChatSession instance
         max_iters: Maximum iterations for the ReAct agent
         
     Returns:
         DSPy ReAct agent configured with workflow tools
     """
-    chat_session_obj = mcp_server.chat_session
+    chat_session_obj = chat_session
     if not chat_session_obj:
-        return None
+        raise ValueError("chat session cannot be null")
 
     def what_can_i_do() -> str:
         """
@@ -196,46 +237,28 @@ def initialize_workflow_tool_agent(mcp_server: FastWorkflowMCPServer, max_iters:
         """
         return _what_can_i_do(chat_session_obj=chat_session_obj)
 
-    def clarify_ambiguous_intent(
-            correct_command_name: str) -> str:
-        """
-        Call this tool ONLY in the intent detection error state to provide the exact command name.
-        The intent detection error message will list the command names to pick from.
-        """
-        return _clarify_ambiguous_intent(correct_command_name, chat_session_obj = chat_session_obj)
-
-    def provide_missing_or_corrected_parameters(
-            missing_or_corrected_parameter_values: list[str|int|float|bool]) -> str:
-        """
-        Call this tool ONLY in the parameter extraction error state to provide missing or corrected parameter values.
-        Missing parameter values may be found in the user query, or information already available, or by executing a different command (refer to the optional 'available_from' hint for guidance on appropriate commands to use to get the information).
-        If the error message indicates parameter values are improperly formatted, correct using your internal knowledge.
-        """
-        return _provide_missing_or_corrected_parameters(missing_or_corrected_parameter_values, chat_session_obj=chat_session_obj)
-
-    def abort_current_command_to_exit_parameter_extraction_error_state() -> str:
-        """
-        Call this tool ONLY when you need to execute a different command to get missing parameters.
-        DO NOT execute the same failing command over and over. Either provide_missing_or_corrected_parameters or abort 
-        """
-        return _abort_current_command_to_exit_parameter_extraction_error_state(
-            chat_session_obj=chat_session_obj)
-
     def intent_misunderstood() -> str:
         """
         Shows the full list of available command names so you can specify the command name you really meant
         Call this tool when your intent is misunderstood (i.e. the wrong command name is executed).
-        Do not use this tool if its a missing or invalid parameter issue. Use the provide_missing_or_corrected_parameters tool instead
         """
         return _intent_misunderstood(chat_session_obj = chat_session_obj)
 
     def execute_workflow_query(command: str) -> str:
         """
+        Takes just a single argument called 'command'.
         Executes the command and returns either a response, or a clarification request.
         Use the "what_can_i_do" tool to get details on available commands, including their names and parameters. Fyi, values in the 'examples' field are fake and for illustration purposes only.
         Commands must be formatted using plain text for command name followed by XML tags enclosing parameter values (if any) as follows: command_name <param1_name>param1_value</param1_name> <param2_name>param2_value</param2_name> ...
         Don't use this tool to respond to a clarification requests in PARAMETER EXTRACTION ERROR state
         """
+        # Check if this command originated from user input (iteration_counter == 0)
+        # Set flag in workflow context so validate_extracted_parameters can access it
+        is_user_command = chat_session_obj.workflow_tool_agent.iteration_counter <= 0 
+        workflow = chat_session_obj.get_active_workflow()
+        if workflow:
+            workflow.context["is_user_command"] = is_user_command
+        
         # Retry logic for workflow execution
         max_retries = 2
         for attempt in range(max_retries):
@@ -249,49 +272,61 @@ def initialize_workflow_tool_agent(mcp_server: FastWorkflowMCPServer, max_iters:
                 # Continue to next attempt
                 logger.warning(f"Attempt {attempt + 1} failed for command '{command}': {str(e)}")
 
-    def missing_information_guidance(how_to_find_request: str) -> str:
-        """
-        Request guidance on finding missing information. 
-        The how_to_find_request must be plain text without any formatting.
-        """
-        return _missing_information_guidance_tool(how_to_find_request, chat_session_obj=chat_session_obj)
-
     def ask_user(clarification_request: str) -> str:
         """
-        As a last resort, request clarification for missing information (only after using the missing_information_guidance_tool) or error correction from the human user. 
+        Only as the last resort, request clarification for missing information from the human user. 
         The clarification_request must be plain text without any formatting.
+        Note that using the wrong command name can produce missing information errors. Double-check with the what_can_i_do tool to verify that the correct command name is being used 
         """
+        # reset iteration counter, everytime we ask the user
+        # reset to -1, because we are dual purposing (iteration_counter <= 0) to check
+        # if command passed to execute_workflow_query() originated either:
+        # externally or inside agent loop immediately after an ask_user()_call 
+        chat_session_obj.workflow_tool_agent.iteration_counter = -1
         return _ask_user_tool(clarification_request, chat_session_obj=chat_session_obj)
 
     tools = [
         what_can_i_do,
         execute_workflow_query,
-        missing_information_guidance,
-        clarify_ambiguous_intent,
+        # missing_information_guidance,
         intent_misunderstood,
         ask_user,
-        provide_missing_or_corrected_parameters,
-        abort_current_command_to_exit_parameter_extraction_error_state,
     ]
 
-    return dspy.ReAct(
+    return fastWorkflowReAct(
         WorkflowAgentSignature,
         tools=tools,
         max_iters=max_iters,
     )
 
-def _think_and_plan(user_query: str, chat_session_obj: fastworkflow.ChatSession) -> str:
+
+def build_query_with_next_steps(user_query: str, 
+    chat_session_obj: fastworkflow.ChatSession, with_agent_inputs_and_trajectory: bool = False) -> str:
     """
-    Returns a refined plan by breaking down a user_query into simpler tasks based only on available commands and returns a todo list.
+    Generate a todo list.
+    Return a string that combine the user query and todo list
     """
     class TaskPlannerSignature(dspy.Signature):
         """
-        Break down a user_query into simpler tasks based only on available commands and return a todo list.
-        If user_query is simple, return a single todo that is the user_query as-is
+        Carefully review the user_query and generate a next steps sequence based only on available commands.
+        Walk the graph of commands based on the 'available_from' hints to build the most appropriate command sequence
+        Avoid specifying 'ask user' because 9 times out of 10, you can find the information via available commands. 
         """
         user_query: str = dspy.InputField()
         available_commands: list[str] = dspy.InputField()
-        todo_list: list[str] = dspy.OutputField(desc="task descriptions as short sentences")
+        next_steps: list[str] = dspy.OutputField(desc="task descriptions as short sentences")
+
+    class TaskPlannerWithTrajectoryAndAgentInputsSignature(dspy.Signature):
+        """
+        Carefully review agent inputs, agent trajectory and user response and generate a next steps sequence based only on available commands.
+        Walk the graph of commands based on the 'available_from' hints to build the most appropriate command sequence
+        Avoid specifying 'ask user' because 9 times out of 10, you can find the information via available commands. 
+        """
+        agent_inputs: dict = dspy.InputField()
+        agent_trajectory: dict = dspy.InputField()
+        user_response: str = dspy.InputField()
+        available_commands: list[str] = dspy.InputField()
+        next_steps: list[str] = dspy.OutputField(desc="task descriptions as short sentences")
 
     current_workflow = chat_session_obj.get_active_workflow()
     available_commands = CommandMetadataAPI.get_command_display_text(
@@ -302,10 +337,27 @@ def _think_and_plan(user_query: str, chat_session_obj: fastworkflow.ChatSession)
 
     planner_lm = dspy_utils.get_lm("LLM_PLANNER", "LITELLM_API_KEY_PLANNER")
     with dspy.context(lm=planner_lm):
-        task_planner_func = dspy.ChainOfThought(TaskPlannerSignature)
-        prediction = task_planner_func(user_query=user_query, available_commands=available_commands)
-
-        if not prediction.todo_list or (len(prediction.todo_list) == 1 and prediction.todo_list[0] == user_query):
+        if with_agent_inputs_and_trajectory:
+            workflow_tool_agent = chat_session_obj.workflow_tool_agent
+            task_planner_func = dspy.ChainOfThought(TaskPlannerWithTrajectoryAndAgentInputsSignature)
+            prediction = task_planner_func(
+                agent_inputs = workflow_tool_agent.inputs,
+                agent_trajectory = workflow_tool_agent.current_trajectory,
+                user_response = user_query,
+                available_commands=available_commands)
+        else:
+            task_planner_func = dspy.ChainOfThought(TaskPlannerSignature)
+            prediction = task_planner_func(
+                user_query=user_query,
+                available_commands=available_commands)
+
+        if not prediction.next_steps:
             return user_query
 
-        return f"{user_query}\nNext steps:\n{'\n'.join([f'{i + 1}. {task}' for i, task in enumerate(prediction.todo_list)])}"
+        steps_list = '\n'.join([f'{i + 1}. {task}' for i, task in enumerate(prediction.next_steps)])
+        user_query_and_next_steps = f"{user_query}\n\nExecute these next steps:\n{steps_list}"
+        return (
+            f'User Query:\n{user_query_and_next_steps}'
+            if with_agent_inputs_and_trajectory else
+            user_query_and_next_steps
+        )

{fastworkflow-2.15.5.dist-info → fastworkflow-2.17.13.dist-info}/METADATA

@@ -1,19 +1,22 @@
 Metadata-Version: 2.1
 Name: fastworkflow
-Version: 2.15.5
+Version: 2.17.13
 Summary: A framework for rapidly building large-scale, deterministic, interactive workflows with a fault-tolerant, conversational UX
 License: Apache-2.0
 Keywords: fastworkflow,ai,workflow,llm,openai
 Author: Dhar Rawal
 Author-email: drawal@radiantlogic.com
-Requires-Python: >=3.11
+Requires-Python: >=3.11,<3.14
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Provides-Extra: fastapi
 Requires-Dist: colorama (>=0.4.6,<0.5.0)
 Requires-Dist: datasets (>=4.0.0,<5.0.0)
 Requires-Dist: dspy (>=3.0.1,<4.0.0)
+Requires-Dist: fastapi (>=0.115.5,<0.116.0) ; extra == "fastapi"
+Requires-Dist: fastapi-mcp (>=0.4.0,<0.5.0) ; extra == "fastapi"
 Requires-Dist: libcst (>=1.8.2,<2.0.0)
 Requires-Dist: litellm[proxy] (>=1.75.8,<2.0.0)
 Requires-Dist: mmh3 (>=5.1.0,<6.0.0)
@@ -21,12 +24,14 @@ Requires-Dist: openai (>=1.99.5,<1.100.0)
 Requires-Dist: prompt_toolkit (>=3.0.43,<4.0.0)
 Requires-Dist: pydantic (>=2.9.2,<3.0.0)
 Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
+Requires-Dist: python-jose[cryptography] (>=3.3.0,<4.0.0) ; extra == "fastapi"
 Requires-Dist: python-levenshtein (>=0.27.1,<0.28.0)
 Requires-Dist: scikit-learn (>=1.6.1,<2.0.0)
 Requires-Dist: sentence-transformers (>=3.4.1,<4.0.0)
 Requires-Dist: speedict (>=0.3.12,<0.4.0)
 Requires-Dist: torch (>=2.7.1,<3.0.0)
 Requires-Dist: transformers (>=4.48.2,<5.0.0)
+Requires-Dist: uvicorn (>=0.29.0,<0.30.0) ; extra == "fastapi"
 Project-URL: homepage, https://github.com/radiantlogicinc/fastworkflow
 Project-URL: repository, https://github.com/radiantlogicinc/fastworkflow
 Description-Content-Type: text/markdown
@@ -50,7 +55,7 @@ While [DSPy](https://dspy.ai) ([Why DSPy](https://x.com/lateinteraction/status/1
 
 ### Why fastWorkflow?
 
-- ✅ **Unlimited Tool Scaling**: fastworkflow can scale to an unlimited number of tools
+- ✅ **Unlimited Tool Scaling**: fastworkflow organizes tools into context hierarchies so use any number of tools without sacrificing performance or efficiency
 - ✅ **Cost-Effective Performance**: fastWorkFlow with small, free models can match the quality of large expensive models
 - ✅ **Reliable Tool Execution**: fastworkflow validation pipeline virtually eliminates incorrect tool calling or parameter extraction, ensuring a reliable tool response
 - ✅ **Adaptive Learning**: 1-shot learning from intent detection mistakes. It learns your conversational vocabulary as you interact with it
@@ -202,14 +207,14 @@ LITELLM_API_KEY_PLANNER=your-mistral-api-key
 LITELLM_API_KEY_AGENT=your-mistral-api-key
 ```
 
-You can get a free API key from [Mistral AI](https://mistral.ai) - the example is configured to use the `mistral-small-latest` model which is available on their free tier.
+You can get a free API key from [Mistral AI](https://mistral.ai) for the mistral small model. Or a free API key from [OpenRouter](https://openrouter.ai/openai/gpt-oss-20b:free) for the GPT-OSS-20B:free model. You can use different models for different LLM roles in the same workflow if you wish.
 
 ### Step 3: Train the Example
 
 Train the intent-detection models for the workflow:
 
 ```sh
-fastworkflow examples train hello_world
+fastworkflow train ./examples/hello_world ./examples/fastworkflow.env ./examples/fastworkflow.passwords.env
 ```
 
 This step builds the NLP models that help the workflow understand user commands.
@@ -219,7 +224,7 @@ This step builds the NLP models that help the workflow understand user commands.
 Once training is complete, run the interactive assistant:
 
 ```sh
-fastworkflow examples run hello_world
+fastworkflow run ./examples/hello_world ./examples/fastworkflow.env ./examples/fastworkflow.passwords.env
 ```
 
 You will be greeted with a `User >` prompt. Try it out by asking "what can you do?" or "add 49 + 51"!
@@ -240,12 +245,6 @@ fastworkflow examples list
 
 # Fetch an example to your local directory
 fastworkflow examples fetch <example_name>
-
-# Train an example workflow
-fastworkflow examples train <example_name>
-
-# Run an example workflow
-fastworkflow examples run <example_name>
 ```
 
 ### Workflow Operations
@@ -261,11 +260,8 @@ fastworkflow train <workflow_dir> <env_file> <passwords_file>
 fastworkflow run <workflow_dir> <env_file> <passwords_file>
 ```
 
-To run a workflow in agentic mode, add the `--run_as_agent` flag:
-
-```sh
-fastworkflow run <workflow_dir> <env_file> <passwords_file> --run_as_agent
-```
+> [!tip]
+> **Deterministic execution:** Prefix a natural language command with `/` to execute it deterministically (non‑agentic) during an interactive run.
 
 Each command has additional options that can be viewed with the `--help` flag:
 
@@ -590,6 +586,7 @@ This single command will generate the `greet.py` command, `get_properties` and `
 | `LLM_RESPONSE_GEN` | LiteLLM model string for response generation | `run` | `mistral/mistral-small-latest` |
 | `LLM_PLANNER` | LiteLLM model string for the agent's task planner | `run` (agent mode) | `mistral/mistral-small-latest` |
 | `LLM_AGENT` | LiteLLM model string for the DSPy agent | `run` (agent mode) | `mistral/mistral-small-latest` |
+| `LLM_CONVERSATION_STORE` | LiteLLM model string for conversation topic/summary generation | FastAPI service | `mistral/mistral-small-latest` |
 | `NOT_FOUND` | Placeholder value for missing parameters during extraction | Always | `"NOT_FOUND"` |
 | `MISSING_INFORMATION_ERRMSG` | Error message prefix for missing parameters | Always | `"Missing required..."` |
 | `INVALID_INFORMATION_ERRMSG` | Error message prefix for invalid parameters | Always | `"Invalid information..."` |
@@ -603,6 +600,7 @@ This single command will generate the `greet.py` command, `get_properties` and `
 | `LITELLM_API_KEY_RESPONSE_GEN`| API key for the `LLM_RESPONSE_GEN` model | `run` | *required* |
 | `LITELLM_API_KEY_PLANNER`| API key for the `LLM_PLANNER` model | `run` (agent mode) | *required* |
 | `LITELLM_API_KEY_AGENT`| API key for the `LLM_AGENT` model | `run` (agent mode) | *required* |
+| `LITELLM_API_KEY_CONVERSATION_STORE`| API key for the `LLM_CONVERSATION_STORE` model | FastAPI service | *required* |
 
 > [!tip]
 > The example workflows are configured to use Mistral's models by default. You can get a free API key from [Mistral AI](https://mistral.ai) that works with the `mistral-small-latest` model.
@@ -638,7 +636,7 @@ Interested in contributing to `fastWorkflow` itself? Great!
 1.  **Clone the repository:** `git clone https://github.com/your-repo/fastworkflow.git`
 2.  **Set up the environment:** Create a virtual environment using your preferred tool (venv, uv, conda, poetry, etc.) with Python 3.11+
 3.  **Install in editable mode with dev dependencies:** `pip install -e .` or `uv pip install -e ".[dev]"`
-4.  **[Join our Discord](https://discord.gg/CCpNujh2):** Ask questions, discuss functionality, showcase your fastWorkflows
+4.  **[Join our Discord](https://discord.gg/k2g58dDjYR):** Ask questions, discuss functionality, showcase your fastWorkflows
 
 ---