fastworkflow 2.13.5__py3-none-any.whl → 2.14.1__py3-none-any.whl

fastworkflow/command_routing.py

@@ -76,7 +76,10 @@ class RoutingDefinition(BaseModel):
         """Returns the list of command names available in the given context."""
         if context not in self.contexts:
             raise ValueError(f"Context '{context}' not found in the workflow.")
-        return self.contexts[context]
+        commands = self.contexts[context]
+        if 'wildcard' in commands:
+            commands = [cmd for cmd in commands if cmd != 'wildcard']
+        return commands
 
     def get_command_class(self, command_name: str, module_type: ModuleType) -> Optional[Type[Any]]:
         """

fastworkflow/examples/fastworkflow.env

@@ -1,7 +1,7 @@
 LLM_SYNDATA_GEN=mistral/mistral-small-latest
 LLM_PARAM_EXTRACTION=mistral/mistral-small-latest
 LLM_RESPONSE_GEN=mistral/mistral-small-latest
-LLM_AGENT=bedrock/us.anthropic.claude-3-7-sonnet-20250219-v1:0
+LLM_PLANNER=openrouter/openai/gpt-oss-20b:free
 LLM_AGENT=mistral/mistral-small-latest
 
 SPEEDDICT_FOLDERNAME=___workflow_contexts

fastworkflow/examples/fastworkflow.passwords.env

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

fastworkflow/examples/hello_world/_commands/add_two_numbers.py

@@ -11,6 +11,7 @@ from ..application.add_two_numbers import add_two_numbers
 
 
 class Signature:
+    """Takes two floating point numbers and returns their sum"""
     class Input(BaseModel):
         first_num: float = Field(description="First number")
         second_num: float = Field(description="Second number")

fastworkflow/examples/retail_workflow/_commands/calculate.py

@@ -0,0 +1,67 @@
+from typing import List
+
+import fastworkflow
+from pydantic import BaseModel, Field, ConfigDict
+from fastworkflow.workflow import Workflow
+from fastworkflow import CommandOutput, CommandResponse
+from fastworkflow.train.generate_synthetic import generate_diverse_utterances
+
+from ..retail_data import load_data
+from ..tools.calculate import Calculate
+
+
+class Signature:
+    """Calculate a mathematical expression"""
+
+    class Input(BaseModel):
+        expression: str = Field(
+            default="NOT_FOUND",
+            description=(
+                "The mathematical expression to calculate. Allowed characters: digits, "
+                "+, -, *, /, parentheses, spaces."
+            ),
+            pattern=r"^(NOT_FOUND|[0-9+\-*/().\s]+)$",
+            examples=["(2 + 3) * 4", "10 / 2 + 3", "(8-3)/5"],
+        )
+
+        model_config = ConfigDict(arbitrary_types_allowed=True, validate_assignment=True)
+
+    class Output(BaseModel):
+        result: str = Field(
+            description=(
+                "Calculated result as a string. Returns an error message for invalid input."
+            )
+        )
+
+    plain_utterances: List[str] = [
+        "What is 2 + 2?",
+        "Calculate (2 + 3) * 4",
+        "Can you compute 10 / 2 + 3?",
+        "Evaluate (8-3)/5",
+        "Please calculate 7 * (6 - 2)",
+    ]
+
+    template_utterances: List[str] = []
+
+    @staticmethod
+    def generate_utterances(workflow: fastworkflow.Workflow, command_name: str) -> List[str]:
+        return [
+            command_name.split('/')[-1].lower().replace('_', ' ')
+        ] + generate_diverse_utterances(Signature.plain_utterances, command_name)
+
+
+class ResponseGenerator:
+    def __call__(self, workflow: Workflow, command: str, command_parameters: Signature.Input) -> CommandOutput:
+        output = self._process_command(workflow, command_parameters)
+        response = f"Result: {output.result}"
+        return CommandOutput(
+            workflow_id=workflow.id,
+            command_responses=[CommandResponse(response=response)],
+        )
+
+    def _process_command(self, workflow: Workflow, input: Signature.Input) -> Signature.Output:
+        data = load_data()
+        result = Calculate.invoke(data=data, expression=input.expression)
+        return Signature.Output(result=result)
+
+

fastworkflow/examples/retail_workflow/_commands/cancel_pending_order.py

@@ -24,7 +24,10 @@ class Signature:
                 default="NOT_FOUND",
                 description="The order ID to cancel (must start with #)",
                 pattern=r"^(#[\w\d]+|NOT_FOUND)$",
-                examples=["#123", "#abc123", "#order456"]
+                examples=["#123", "#abc123", "#order456"],
+                json_schema_extra={
+                    "available_from": ["get_user_details"]
+                }
             )
         ]
 

fastworkflow/examples/retail_workflow/_commands/exchange_delivered_order_items.py

@@ -17,21 +17,33 @@ class Signature:
             description="The order ID to exchange (must start with #)",
             pattern=r"^(#[\w\d]+|NOT_FOUND)$",
             examples=["#W0000000"],
+            json_schema_extra={
+                "available_from": ["get_user_details"]
+            }
         )
         item_ids: List[str] = Field(
             default_factory=list,
             description="The item IDs to be exchanged",
             examples=["1008292230"],
+            json_schema_extra={
+                "available_from": ["get_order_details"]
+            }
         )
         new_item_ids: List[str] = Field(
             default_factory=list,
             description="The new item IDs to exchange for",
             examples=["1008292230"],
+            json_schema_extra={
+                "available_from": ["get_product_details"]
+            }
         )
         payment_method_id: str = Field(
             default="NOT_FOUND",
-            description="Payment method ID for price difference. You can get this from order details->payment_history",
+            description="Payment method ID for price difference.",
             examples=["gift_card_0000000", "credit_card_0000000"],
+            json_schema_extra={
+                "available_from": ["get_order_details", "get_user_details"]
+            }
         )
 
         model_config = ConfigDict(arbitrary_types_allowed=True, validate_assignment=True)

fastworkflow/examples/retail_workflow/_commands/find_user_id_by_email.py

@@ -28,7 +28,12 @@ class Signature:
         model_config = ConfigDict(arbitrary_types_allowed=True, validate_assignment=True)
 
     class Output(BaseModel):
-        user_id: str = Field(description="User identifier returned by lookup.")
+        user_id: str = Field(
+            description="User identifier returned by lookup.",
+            json_schema_extra={
+                "used_by": ["get_user_details"]
+            }
+        )
 
     plain_utterances: List[str] = [
         "Can you tell me the ID linked to john.doe@example.com?",

fastworkflow/examples/retail_workflow/_commands/find_user_id_by_name_zip.py

@@ -35,7 +35,12 @@ class Signature:
         model_config = ConfigDict(arbitrary_types_allowed=True, validate_assignment=True)
 
     class Output(BaseModel):
-        user_id: str = Field(description="User identifier returned by lookup.")
+        user_id: str = Field(
+            description="User identifier returned by lookup.",
+            json_schema_extra={
+                "used_by": ["get_user_details"]
+            }
+        )
 
     # ------------------------------------------------------------------
     # Utterances

fastworkflow/examples/retail_workflow/_commands/get_order_details.py

@@ -16,24 +16,36 @@ class Signature:
         order_id: str = Field(
             default="NOT_FOUND",
             description=(
-                "The order ID to get details for (must start with #). You can get order id's "
-                "from get_user_details, given a user id."
+                "The order ID to get details for (must start with #)"
             ),
             pattern=r"^(#[\w\d]+|NOT_FOUND)$",
             examples=["#W0000000"],
+            json_schema_extra={
+                "available_from": ["get_user_details"]
+            }
         )
 
         model_config = ConfigDict(arbitrary_types_allowed=True, validate_assignment=True)
 
     class Output(BaseModel):
-        order_details: str = Field(description=(
-            "Detailed information about the order such as "
-            "shipping address, "
-            "items ordered with details including name, product and item id, price and options, "
-            "fulfillments with details including tracking id and item ids, "
-            "order status, and"
-            "payment history with details including transaction type, amount and payment method id"
-        ))
+        order_details: str = Field(
+            description=(
+                "Detailed information about the order such as "
+                "shipping address, "
+                "items ordered with details including name, product and item id, price and options, "
+                "fulfillments with details including tracking id and item ids, "
+                "order status, and"
+                "payment history with details including transaction type, amount and payment method id"
+            ),
+            json_schema_extra={
+                "used_by": [
+                    "exchange_delivered_order_items",
+                    "get_product_details",
+                    "modify_pending_order_items",
+                    "return_delivered_order_items",
+                ]
+            },
+        )
 
     plain_utterances: List[str] = [
         "Can you tell me what's going on with my order #W1234567?",

fastworkflow/examples/retail_workflow/_commands/get_product_details.py

@@ -17,15 +17,23 @@ class Signature:
             description="The product ID (numeric string)",
             pattern=r"^(\d{10}|NOT_FOUND)$",
             examples=["6086499569"],
+            json_schema_extra={
+                "available_from": ["get_order_details", "list_all_product_types"]
+            }
         )
 
         model_config = ConfigDict(arbitrary_types_allowed=True, validate_assignment=True)
 
     class Output(BaseModel):
-        product_details: str = Field(description=(
-            "Detailed product information of all product variants "
-            "including item id, options, availability and price"
-        ))
+        product_details: str = Field(
+            description=(
+                "Detailed product information of all product variants of a given product type"
+                "including item id, options, availability and price"
+            ),
+            json_schema_extra={
+                "used_by": ["exchange_delivered_order_items", "modify_pending_order_items"]
+            }
+        )
 
     plain_utterances: List[str] = [
         "Can you give me more information about this product?",

fastworkflow/examples/retail_workflow/_commands/get_user_details.py

@@ -17,16 +17,32 @@ class Signature:
             description="The user ID to get details for",
             pattern=r"^([a-z]+_[a-z]+_\d+|NOT_FOUND)$",
             examples=["sara_doe_496"],
+            json_schema_extra={
+                "available_from": ["find_user_id_by_email", "find_user_id_by_name_zip"]
+            }
         )
 
         model_config = ConfigDict(arbitrary_types_allowed=True, validate_assignment=True)
 
     class Output(BaseModel):
-        user_details: str = Field(description=(
-            "Detailed user information such as "
-            "first and last name, address, email, payment methods and "
-            "the list of order id's"
-        ))
+        user_details: str = Field(
+            description=(
+                "Detailed user information such as "
+                "first and last name, address, email, payment methods and "
+                "the list of order id's"
+            ),
+            json_schema_extra={
+                "used_by": [
+                    "cancel_pending_order",
+                    "exchange_delivered_order_items",
+                    "get_order_details",
+                    "modify_pending_order_address",
+                    "modify_pending_order_items",
+                    "modify_pending_order_payment",
+                    "return_delivered_order_items",
+                ]
+            },
+        )
 
     plain_utterances: List[str] = [
         "Can you pull up my account info?",

fastworkflow/examples/retail_workflow/_commands/list_all_product_types.py

@@ -20,7 +20,10 @@ class Signature:
 
     class Output(BaseModel):
         status: str = Field(
-            description="List of product type names separated by comma, or a JSON string representation of that list.",
+            description="List of product type and product id tuples, or a JSON string representation of that list.",
+            json_schema_extra={
+                "used_by": ["get_product_details"]
+            }
         )
 
     # ---------------------------------------------------------------------

fastworkflow/examples/retail_workflow/_commands/modify_pending_order_address.py

@@ -17,6 +17,9 @@ class Signature:
             description="The order ID to modify (must start with #)",
             pattern=r"^(#W\d+|NOT_FOUND)$",
             examples=["#W0000000"],
+            json_schema_extra={
+                "available_from": ["get_user_details"]
+            }
         )
         address1: str = Field(default="NOT_FOUND", description="First line of address", examples=["123 Main St"])
         address2: str = Field(default="NOT_FOUND", description="Second line of address", examples=["Apt 1"])

fastworkflow/examples/retail_workflow/_commands/modify_pending_order_items.py

@@ -17,22 +17,34 @@ class Signature:
             description="The order ID to modify (must start with #)",
             pattern=r"^(#W\d+|NOT_FOUND)$",
             examples=["#W0000000"],
+            json_schema_extra={
+                "available_from": ["get_user_details"]
+            }
         )
         item_ids: List[str] = Field(
             default_factory=list,
             description="List of item IDs to be modified",
             examples=["1008292230", "2468135790"],
+            json_schema_extra={
+                "available_from": ["get_order_details"]
+            }
         )
         new_item_ids: List[str] = Field(
             default_factory=list,
             description="List of new item IDs to replace with",
             examples=["1008292231", "2468135791"],
+            json_schema_extra={
+                "available_from": ["get_product_details"]
+            }
         )
         payment_method_id: str = Field(
             default="NOT_FOUND",
             description="Payment method ID for price differences",
             pattern=r"^((gift_card|credit_card)_\d+|NOT_FOUND)$",
             examples=["gift_card_0000000", "credit_card_0000000"],
+            json_schema_extra={
+                "available_from": ["get_order_details", "get_user_details"]
+            }
         )
 
         model_config = ConfigDict(arbitrary_types_allowed=True, validate_assignment=True)

fastworkflow/examples/retail_workflow/_commands/modify_pending_order_payment.py

@@ -10,19 +10,25 @@ from ..tools.modify_pending_order_payment import ModifyPendingOrderPayment
 
 
 class Signature:
-    """Modify pending order payment"""
+    """Modify pending order payment method"""
     class Input(BaseModel):
         order_id: str = Field(
             default="NOT_FOUND",
             description="The order ID to modify (must start with #)",
             pattern=r"^(#W\d+|NOT_FOUND)$",
             examples=["#W0000000"],
+            json_schema_extra={
+                "available_from": ["get_user_details"]
+            }
         )
         payment_method_id: str = Field(
             default="NOT_FOUND",
             description="Payment method ID to switch to",
             pattern=r"^((gift_card|credit_card)_\d+|NOT_FOUND)$",
             examples=["gift_card_0000000", "credit_card_0000000"],
+            json_schema_extra={
+                "available_from": ["get_user_details"]
+            }
         )
 
         model_config = ConfigDict(arbitrary_types_allowed=True, validate_assignment=True)

fastworkflow/examples/retail_workflow/_commands/modify_user_address.py

@@ -17,6 +17,9 @@ class Signature:
             description="The user ID to modify",
             pattern=r"^([a-z]+_[a-z]+_\d+|NOT_FOUND)$",
             examples=["sara_doe_496"],
+            json_schema_extra={
+                "available_from": ["find_user_id_by_email", "find_user_id_by_name_zip"]
+            }
         )
         address1: str = Field(default="NOT_FOUND", description="First line of address", examples=["123 Main St"])
         address2: str = Field(default="NOT_FOUND", description="Second line of address", examples=["Apt 1"])

fastworkflow/examples/retail_workflow/_commands/return_delivered_order_items.py

@@ -16,18 +16,27 @@ class Signature:
             default="NOT_FOUND",
             description="The order ID for return (must start with #)",
             pattern=r"^(#W\d+|NOT_FOUND)$",
-            examples=["#W0000000"],
+            examples=["#W3456890"],
+            json_schema_extra={
+                "available_from": ["get_user_details"]
+            }
         )
         item_ids: List[str] = Field(
             default_factory=list,
             description="List of item IDs to be returned",
             examples=["1008292230"],
+            json_schema_extra={
+                "available_from": ["get_order_details"]
+            }
         )
         payment_method_id: str = Field(
             default="NOT_FOUND",
             description="Payment method ID for refund",
             pattern=r"^((gift_card|credit_card)_\d+|NOT_FOUND)$",
             examples=["gift_card_0000000", "credit_card_0000000"],
+            json_schema_extra={
+                "available_from": ["get_order_details"]
+            }
         )
 
         model_config = ConfigDict(arbitrary_types_allowed=True, validate_assignment=True)

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"""
+    """Transfer to a human agent as the last resort"""
     class Input(BaseModel):
         summary: str = Field(
             default="NOT_FOUND",

fastworkflow/examples/retail_workflow/tools/calculate.py

@@ -7,7 +7,7 @@ from .tool import Tool
 class Calculate(Tool):
     @staticmethod
     def invoke(data: Dict[str, Any], expression: str) -> str:
-        if not all(char in "0123456789+-*/(). " for char in expression):
+        if any(char not in "0123456789+-*/(). " for char in expression):
             return "Error: invalid characters in expression"
         try:
             # Evaluate the mathematical expression safely

fastworkflow/mcp_server.py

@@ -11,6 +11,7 @@ from fastworkflow.command_executor import CommandExecutor
 from fastworkflow.command_directory import CommandDirectory
 from fastworkflow.command_routing import RoutingDefinition, RoutingRegistry, ModuleType
 from uuid import uuid4
+from fastworkflow.command_metadata_api import CommandMetadataAPI
 
 
 class FastWorkflowMCPServer:
@@ -50,64 +51,68 @@ class FastWorkflowMCPServer:
         active_ctx = active_ctx_name if active_ctx_name in routing.contexts else '*'
         command_names = routing.get_command_names(active_ctx)
 
+        # Centralized command metadata (docstrings, inputs, plain_utterances)
+        cme_path = fastworkflow.get_internal_workflow_path("command_metadata_extraction")
+        enhanced_meta = CommandMetadataAPI.get_enhanced_command_info(
+            subject_workflow_path=workflow_folderpath,
+            cme_workflow_path=cme_path,
+            active_context_name=active_ctx_name,
+        )
+        meta_by_fq = {m.get("qualified_name"): m for m in enhanced_meta.get("commands", [])}
+
+        # Centralized parameters for building schemas
+        params_by_cmd = CommandMetadataAPI.get_params_for_all_commands(workflow_folderpath)
+
         tools = []
         for command_name in command_names:
-            # Get command parameters class to build schema
-            command_parameters_class = routing.get_command_class(
-                command_name,
-                ModuleType.COMMAND_PARAMETERS_CLASS
-            )
-
-            # Build JSON schema from Pydantic model
+            # Centralized metadata for this command (if any)
+            meta_for_cmd = meta_by_fq.get(command_name)
+            # Build JSON schema from centralized API params
             input_schema = {
                 "type": "object",
                 "properties": {},
                 "required": []
             }
 
-            description = f"Executes {command_name}"
-
-            if command_parameters_class:
-                field_descriptions = []
-                model_fields = command_parameters_class.model_fields
-                for field_name, field_info in model_fields.items():
-                    # Convert Pydantic field to JSON schema property
-                    prop = {"type": "string"}  # Default type
-                    if hasattr(field_info, 'description') and field_info.description:
-                        prop["description"] = field_info.description
-                        field_descriptions.append(field_info.description)
-                    else:
-                        field_descriptions.append(field_name)
-
-                    if hasattr(field_info, 'default') and field_info.default:
-                        prop["default"] = field_info.default
-                        # Add to required if default is NOT_FOUND
-                        if field_info.default == NOT_FOUND:
-                            input_schema["required"].append(field_name)
-                    elif field_info.is_required():
+            # Build input schema and required fields
+            field_descriptions = []
+            for param in params_by_cmd.get(command_name, {}).get("inputs", []):
+                field_name = param.get("name") or "param"
+                prop = {"type": "string"}
+                if desc := param.get("description"):
+                    prop["description"] = desc
+                    field_descriptions.append(desc)
+                else:
+                    field_descriptions.append(field_name)
+                if (default := param.get("default")) is not None:
+                    if default == NOT_FOUND:
                         input_schema["required"].append(field_name)
-
-                    input_schema["properties"][field_name] = prop
-
-                if field_descriptions:
-                    description = f"Input: {', '.join(field_descriptions)}"
-                if command_parameters_class.__doc__:
-                    description = f"{description}. {command_parameters_class.__doc__.strip()}"
+                input_schema["properties"][field_name] = prop
+
+            # Use centralized display generator for a single command for rich description
+            description = CommandMetadataAPI.get_command_display_text_for_command(
+                subject_workflow_path=workflow_folderpath,
+                cme_workflow_path=cme_path,
+                active_context_name=active_ctx_name,
+                qualified_command_name=command_name,
+                for_agents=True,
+                omit_command_name=True,
+            )
 
             # Add standard FastWorkflow parameters
-            input_schema["properties"]["command"] = {
-                "type": "string",
-                "description": "Natural language command or query"
-            }
+            # input_schema["properties"]["command"] = {
+            #     "type": "string",
+            #     "description": "Natural language command or query"
+            # }
 
-            input_schema["properties"]["workitem_path"] = {
-                "type": "string",
-                "description": "Command context (optional)",
-                "default": active_ctx
-            }
+            # input_schema["properties"]["workitem_path"] = {
+            #     "type": "string",
+            #     "description": "Command context (optional)",
+            #     "default": active_ctx
+            # }
 
             tool_def = {
-                "name": command_name,
+                "name": command_name.split("/")[-1],
                 "description": description,
                 "inputSchema": input_schema,
                 "annotations": {
@@ -118,6 +123,9 @@ class FastWorkflowMCPServer:
                     "openWorldHint": True  # FastWorkflow can interact with external systems
                 }
             }
+            # Attach plain_utterances from centralized metadata if present
+            if meta_for_cmd and meta_for_cmd.get("plain_utterances"):
+                tool_def["annotations"]["plain_utterances"] = meta_for_cmd["plain_utterances"]
             tools.append(tool_def)
 
         return tools

fastworkflow/run/__main__.py

@@ -73,14 +73,18 @@ def run_main(args):
             all_renderables.append(Rule(style="dim"))
         
         # Process each command response
+        num_responses = len(command_output.command_responses)
         for i, command_response in enumerate(command_output.command_responses, start=1):
             if command_response.response:
-                all_renderables.extend(
-                    (
-                        Text(f"Command Response {i}", style="bold green"),
-                        Text(command_response.response, style="green")
+                if num_responses > 1:
+                    all_renderables.extend(
+                        (
+                            Text(f"Command Response {i}", style="bold green"),
+                            Text(command_response.response, style="green")
+                        )
                     )
-                )
+                else:
+                    all_renderables.append(Text(command_response.response, style="green"))
 
             if command_response.artifacts:
                 all_renderables.extend(