fastworkflow 2.15.2__tar.gz → 2.17.11__tar.gz

{fastworkflow-2.15.2 → fastworkflow-2.17.11}/PKG-INFO

@@ -1,19 +1,22 @@
 Metadata-Version: 2.1
 Name: fastworkflow
-Version: 2.15.2
+Version: 2.17.11
 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
 
 ---
 

{fastworkflow-2.15.2 → fastworkflow-2.17.11}/README.md

@@ -17,7 +17,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
@@ -169,14 +169,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.
@@ -186,7 +186,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"!
@@ -207,12 +207,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
@@ -228,11 +222,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:
 
@@ -557,6 +548,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..."` |
@@ -570,6 +562,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.
@@ -605,7 +598,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
 
 ---
 

{fastworkflow-2.15.2 → fastworkflow-2.17.11}/fastworkflow/__init__.py

@@ -1,6 +1,8 @@
 import contextlib
+from dataclasses import dataclass
 from enum import Enum
 import os
+import time
 from typing import Any, Optional, Union
 
 from pydantic import BaseModel
@@ -47,6 +49,20 @@ class MCPToolResult(BaseModel):
     content: list[MCPContent]
     isError: bool = False
 
+class CommandTraceEventDirection(str, Enum):
+    AGENT_TO_WORKFLOW = "agent_to_workflow"
+    WORKFLOW_TO_AGENT = "workflow_to_agent"
+
+@dataclass
+class CommandTraceEvent:
+    direction: CommandTraceEventDirection
+    raw_command: str | None               # for AGENT_TO_WORKFLOW
+    command_name: str | None              # for WORKFLOW_TO_AGENT
+    parameters: dict | str | None
+    response_text: str | None
+    success: bool | None
+    timestamp_ms: int
+
 class CommandOutput(BaseModel):
     command_responses: list[CommandResponse]
     workflow_name: str = ""

{fastworkflow-2.15.2 → fastworkflow-2.17.11}/fastworkflow/_workflows/command_metadata_extraction/_commands/ErrorCorrection/you_misunderstood.py

@@ -60,7 +60,7 @@ class ResponseGenerator:
             ])
         )
         response = (
-            "Please enter the correct command from the list below:\n"
+            "Please select the correct command name from the list below:\n"
             f"{response}\n\nor type 'abort' to cancel"
         )
 

{fastworkflow-2.15.2 → fastworkflow-2.17.11}/fastworkflow/_workflows/command_metadata_extraction/_commands/IntentDetection/what_can_i_do.py

@@ -8,6 +8,7 @@ import json
 
 import fastworkflow
 from fastworkflow.train.generate_synthetic import generate_diverse_utterances
+from fastworkflow.command_context_model import get_workflow_info
 from fastworkflow.command_metadata_api import CommandMetadataAPI
 
 class Signature:
@@ -139,20 +140,33 @@ class ResponseGenerator:
         with contextlib.suppress(Exception):
             if fastworkflow.chat_session:
                 is_agent_mode = fastworkflow.chat_session.run_as_agent
-        
+
         app_workflow = workflow.context["app_workflow"]
-        response = CommandMetadataAPI.get_command_display_text(
+        
+        # Get workflow definition
+        workflow_info = get_workflow_info(app_workflow.folderpath)
+        workflow_def_text = CommandMetadataAPI.get_workflow_definition_display_text(workflow_info)
+        
+        # Get available commands in current context
+        commands_text = CommandMetadataAPI.get_command_display_text(
             subject_workflow_path=app_workflow.folderpath,
             cme_workflow_path=workflow.folderpath,
             active_context_name=app_workflow.current_command_context_name,
             for_agents=is_agent_mode,
         )
+        
+        response = f"{workflow_def_text}\n\n{commands_text}"
 
+        nlu_pipeline_stage = workflow.context.get(
+            "NLU_Pipeline_Stage", 
+            fastworkflow.NLUPipelineStage.INTENT_DETECTION)
+        success = nlu_pipeline_stage == fastworkflow.NLUPipelineStage.INTENT_DETECTION
         return fastworkflow.CommandOutput(
             workflow_id=workflow.id,
             command_responses=[
                 fastworkflow.CommandResponse(
                     response=response,
+                    success=success
                 )
             ]
         ) 

fastworkflow-2.17.11/fastworkflow/_workflows/command_metadata_extraction/_commands/wildcard.py

@@ -0,0 +1,179 @@
+import fastworkflow
+from fastworkflow import Action, CommandOutput, CommandResponse, NLUPipelineStage
+from fastworkflow.command_executor import CommandExecutor
+
+from ..intent_detection import CommandNamePrediction
+from ..parameter_extraction import ParameterExtraction
+
+
+class Signature:
+    plain_utterances = [
+        "3",
+        "france",
+        "16.7,.002",
+        "John Doe, 56, 281-995-6423",
+        "/path/to/my/object",
+        "id=3636",
+        "25.73 and Howard St",
+    ]
+
+    @staticmethod
+    def generate_utterances(workflow: fastworkflow.Workflow, command_name: str) -> list[str]:
+        return [
+            command_name.split('/')[-1].lower().replace('_', ' ')
+        ] + Signature.plain_utterances
+
+
+class ResponseGenerator:
+    def __call__(
+        self, 
+        workflow: fastworkflow.Workflow, 
+        command: str,
+    ) -> CommandOutput:  # sourcery skip: hoist-if-from-if
+        app_workflow = workflow.context["app_workflow"]   # type: fastworkflow.Workflow
+        cmd_ctxt_obj_name = app_workflow.current_command_context_name
+        nlu_pipeline_stage = workflow.context.get(
+            "NLU_Pipeline_Stage", 
+            NLUPipelineStage.INTENT_DETECTION)
+
+        predictor = CommandNamePrediction(workflow)           
+        cnp_output = predictor.predict(cmd_ctxt_obj_name, command, nlu_pipeline_stage)
+
+        if cnp_output.error_msg:
+            workflow_context = workflow.context
+            workflow_context["NLU_Pipeline_Stage"] = NLUPipelineStage.INTENT_AMBIGUITY_CLARIFICATION
+            workflow_context["command"] = command
+            workflow.context = workflow_context
+            return CommandOutput(
+                command_responses=[
+                    CommandResponse(
+                        response=(
+                            f"Ambiguous intent error for command '{command}'\n"
+                            f"{cnp_output.error_msg}"
+                        ),
+                        success=False
+                    )
+                ]
+            )
+        else:
+            if nlu_pipeline_stage == NLUPipelineStage.INTENT_DETECTION and \
+                cnp_output.command_name != 'ErrorCorrection/you_misunderstood':
+                workflow_context = workflow.context
+                workflow_context["command"] = command
+                workflow.context = workflow_context
+        
+        if cnp_output.is_cme_command:
+            workflow_context = workflow.context
+            if cnp_output.command_name == 'ErrorCorrection/you_misunderstood':
+                workflow_context["NLU_Pipeline_Stage"] = NLUPipelineStage.INTENT_MISUNDERSTANDING_CLARIFICATION
+                workflow_context["command"] = command
+            elif (
+                nlu_pipeline_stage == fastworkflow.NLUPipelineStage.INTENT_DETECTION or
+                cnp_output.command_name == 'ErrorCorrection/abort'
+            ):
+                workflow.end_command_processing()
+            workflow.context = workflow_context
+
+            startup_action = Action(
+                command_name=cnp_output.command_name,
+                command=command,
+            )
+            command_output = CommandExecutor.perform_action(workflow, startup_action)
+            if (
+                nlu_pipeline_stage == fastworkflow.NLUPipelineStage.INTENT_DETECTION or
+                cnp_output.command_name == 'ErrorCorrection/abort'
+            ):
+                command_output.command_responses[0].artifacts["command_handled"] = True     
+                # Set the additional attributes
+                command_output.command_name = cnp_output.command_name
+            return command_output
+        
+        if nlu_pipeline_stage in {
+                NLUPipelineStage.INTENT_DETECTION,
+                NLUPipelineStage.INTENT_AMBIGUITY_CLARIFICATION,
+                NLUPipelineStage.INTENT_MISUNDERSTANDING_CLARIFICATION
+            }:
+            app_workflow.command_context_for_response_generation = \
+                app_workflow.current_command_context
+
+            if cnp_output.command_name is None:
+                while not cnp_output.command_name and \
+                    app_workflow.command_context_for_response_generation is not None and \
+                        not app_workflow.is_command_context_for_response_generation_root:
+                    app_workflow.command_context_for_response_generation = \
+                        app_workflow.get_parent(app_workflow.command_context_for_response_generation)
+                    cnp_output = predictor.predict(
+                        fastworkflow.Workflow.get_command_context_name(app_workflow.command_context_for_response_generation), 
+                        command, nlu_pipeline_stage)
+            
+                if cnp_output.command_name is None:
+                    if nlu_pipeline_stage == NLUPipelineStage.INTENT_DETECTION:
+                        # out of scope commands
+                        workflow_context = workflow.context
+                        workflow_context["NLU_Pipeline_Stage"] = \
+                            NLUPipelineStage.INTENT_MISUNDERSTANDING_CLARIFICATION
+                        workflow_context["command"] = command
+                        workflow.context = workflow_context
+
+                        startup_action = Action(
+                            command_name='ErrorCorrection/you_misunderstood',
+                            command=command,
+                        )
+                        command_output = CommandExecutor.perform_action(workflow, startup_action)
+                        command_output.command_responses[0].artifacts["command_handled"] = True
+                        return command_output
+
+                    return CommandOutput(
+                        command_responses=[
+                            CommandResponse(
+                                response=cnp_output.error_msg,
+                                success=False
+                            )
+                        ]
+                    )
+
+            # move to the parameter extraction stage
+            workflow_context = workflow.context
+            workflow_context["NLU_Pipeline_Stage"] = NLUPipelineStage.PARAMETER_EXTRACTION
+            workflow.context = workflow_context
+
+        if nlu_pipeline_stage == NLUPipelineStage.PARAMETER_EXTRACTION:
+            cnp_output.command_name = workflow.context["command_name"]
+        else:
+            workflow_context = workflow.context
+            workflow_context["command_name"] = cnp_output.command_name
+            workflow.context = workflow_context
+
+        command_name = cnp_output.command_name
+        # Use the preserved original command (with parameters) if available
+        preserved_command = f'{command_name}: {workflow.context.get("command", command)}'
+        extractor = ParameterExtraction(workflow, app_workflow, command_name, preserved_command)
+        pe_output = extractor.extract()
+        if not pe_output.parameters_are_valid:
+            return CommandOutput(
+                command_name = command_name,
+                command_responses=[
+                    CommandResponse(
+                        response=(
+                            f"PARAMETER EXTRACTION ERROR FOR COMMAND '{command_name}'\n"
+                            f"{pe_output.error_msg}"
+                        ),
+                        success=False
+                    )
+                ]
+            )
+
+        workflow.end_command_processing()
+
+        return CommandOutput(
+            command_responses=[
+                CommandResponse(
+                    response="",
+                    artifacts={
+                        "command": preserved_command,
+                        "command_name": command_name,
+                        "cmd_parameters": pe_output.cmd_parameters,
+                    },
+                )
+            ]
+        )