fastworkflow 2.22.3__tar.gz → 2.24.0__tar.gz

{fastworkflow-2.22.3 → fastworkflow-2.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastworkflow
-Version: 2.22.3
+Version: 2.24.0
 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
@@ -54,7 +54,7 @@ Description-Content-Type: text/markdown
 <!-- Logo and Title -->
 <img src="logo.png" height="64" alt="fastWorkflow Logo and Title">
 
-[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE) [![PyPI](https://img.shields.io/pypi/v/fastworkflow)](https://pypi.org/project/fastworkflow/) [![CI](https://img.shields.io/badge/ci-passing-brightgreen)](https://github.com/radiantlogicinc/fastworkflow/actions) [![Discord](https://img.shields.io/badge/Discord-Join-5865F2)](https://discord.gg/k2g58dDjYR)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE) [![PyPI](https://img.shields.io/pypi/v/fastworkflow)](https://pypi.org/project/fastworkflow/) [![CI](https://img.shields.io/badge/ci-passing-brightgreen)](https://github.com/radiantlogicinc/fastworkflow/actions) [![Discord](https://img.shields.io/badge/Discord-Join-5865F2)](https://discord.gg/k2g58dDjYR) [![Paper](https://img.shields.io/badge/Paper-alphaXiv-red)](https://www.alphaxiv.org/abs/2605.fastworkflow)
 
 **Build AI agents your application can actually trust in production — with small models cheaply, or frontier models more reliably.**
 
@@ -138,11 +138,11 @@ fastWorkflow was benchmarked on [Tau Bench](https://github.com/sierra-research/t
   <table>
     <tr>
       <td align="center" width="50%">
-        <img src="fastWorkflow - Tau Bench Retail.jpg" alt="fastWorkflow Tau Bench Retail results" style="max-width: 100%; height: auto;"/>
+        <img src="tau_bench_retail_performance.png" alt="fastWorkflow Tau Bench Retail results" style="max-width: 100%; height: auto;"/>
         <br/><em>Retail: orders, returns, account operations</em>
       </td>
       <td align="center" width="50%">
-        <img src="fastWorkflow - TauBench Airline.jpg" alt="fastWorkflow Tau Bench Airline results" style="max-width: 100%; height: auto;"/>
+        <img src="tau_bench_airline_performance.png" alt="fastWorkflow Tau Bench Airline results" style="max-width: 100%; height: auto;"/>
         <br/><em>Airline: rebooking, baggage, loyalty workflows</em>
       </td>
     </tr>
@@ -209,6 +209,14 @@ You'll get a `User >` prompt. Try **"what can you do?"** or **"add 49 + 51"**. R
 
 > [!note]
 > **"Train" doesn't mean GPUs or fine-tuning a foundation model.** `fastworkflow train` is closer to *compiling a conversational interface*: it generates synthetic utterances and fits small BERT-class intent classifiers for your commands. You run it once per command set, re-run it only when commands change, ship the resulting artifacts with your app, and need **no GPU at runtime**.
+>
+> Training manages its own safety and incremental work. It checks command seeds for
+> duplicate capabilities before making LLM calls, warns when commands have thin seed
+> coverage, reuses cached utterances, and retrains only affected contexts when that is
+> provably safe. Global changes or an incomplete baseline automatically trigger a full
+> retrain. Models are published atomically; fastWorkflow retains only the current model
+> set and one previous recovery point. Use `--regenerate-utterances` only when you
+> intentionally want to discard the generated-data caches.
 
 > [!tip]
 > Get a free API key from [Mistral AI](https://mistral.ai) (works with `mistral-small-latest`) or [OpenRouter](https://openrouter.ai/openai/gpt-oss-20b:free). You can assign different models to different roles in the same workflow.
@@ -291,6 +299,15 @@ class ResponseGenerator:
 
 Then `fastworkflow train` and `fastworkflow run` against your workflow directory. That's the entire integration pattern: a thin command layer over code you already have.
 
+> [!TIP]
+> `plain_utterances` is the highest-leverage thing you write. Training expands your seeds
+> into the synthetic corpus the intent classifier learns from, so seed count and phrasing
+> variety matter more to routing accuracy than any other dial. The two above are enough to
+> get started; before you ship, grow each command to roughly eight varied phrasings —
+> imperative, question, colloquial, terse — rather than paraphrases of one sentence. (The
+> "roughly eight" figure is where returns flattened on one large internal workflow, not a
+> universal constant.)
+
 > [!tip]
 > Prefer to learn by building the smallest possible workflow by hand first? `fastworkflow examples fetch messaging_app_1` is a minimal, fully-worked single-command workflow you can read end-to-end.
 

{fastworkflow-2.22.3 → fastworkflow-2.24.0}/README.md

@@ -1,7 +1,7 @@
 <!-- Logo and Title -->
 <img src="logo.png" height="64" alt="fastWorkflow Logo and Title">
 
-[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE) [![PyPI](https://img.shields.io/pypi/v/fastworkflow)](https://pypi.org/project/fastworkflow/) [![CI](https://img.shields.io/badge/ci-passing-brightgreen)](https://github.com/radiantlogicinc/fastworkflow/actions) [![Discord](https://img.shields.io/badge/Discord-Join-5865F2)](https://discord.gg/k2g58dDjYR)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE) [![PyPI](https://img.shields.io/pypi/v/fastworkflow)](https://pypi.org/project/fastworkflow/) [![CI](https://img.shields.io/badge/ci-passing-brightgreen)](https://github.com/radiantlogicinc/fastworkflow/actions) [![Discord](https://img.shields.io/badge/Discord-Join-5865F2)](https://discord.gg/k2g58dDjYR) [![Paper](https://img.shields.io/badge/Paper-alphaXiv-red)](https://www.alphaxiv.org/abs/2605.fastworkflow)
 
 **Build AI agents your application can actually trust in production — with small models cheaply, or frontier models more reliably.**
 
@@ -85,11 +85,11 @@ fastWorkflow was benchmarked on [Tau Bench](https://github.com/sierra-research/t
   <table>
     <tr>
       <td align="center" width="50%">
-        <img src="fastWorkflow - Tau Bench Retail.jpg" alt="fastWorkflow Tau Bench Retail results" style="max-width: 100%; height: auto;"/>
+        <img src="tau_bench_retail_performance.png" alt="fastWorkflow Tau Bench Retail results" style="max-width: 100%; height: auto;"/>
         <br/><em>Retail: orders, returns, account operations</em>
       </td>
       <td align="center" width="50%">
-        <img src="fastWorkflow - TauBench Airline.jpg" alt="fastWorkflow Tau Bench Airline results" style="max-width: 100%; height: auto;"/>
+        <img src="tau_bench_airline_performance.png" alt="fastWorkflow Tau Bench Airline results" style="max-width: 100%; height: auto;"/>
         <br/><em>Airline: rebooking, baggage, loyalty workflows</em>
       </td>
     </tr>
@@ -156,6 +156,14 @@ You'll get a `User >` prompt. Try **"what can you do?"** or **"add 49 + 51"**. R
 
 > [!note]
 > **"Train" doesn't mean GPUs or fine-tuning a foundation model.** `fastworkflow train` is closer to *compiling a conversational interface*: it generates synthetic utterances and fits small BERT-class intent classifiers for your commands. You run it once per command set, re-run it only when commands change, ship the resulting artifacts with your app, and need **no GPU at runtime**.
+>
+> Training manages its own safety and incremental work. It checks command seeds for
+> duplicate capabilities before making LLM calls, warns when commands have thin seed
+> coverage, reuses cached utterances, and retrains only affected contexts when that is
+> provably safe. Global changes or an incomplete baseline automatically trigger a full
+> retrain. Models are published atomically; fastWorkflow retains only the current model
+> set and one previous recovery point. Use `--regenerate-utterances` only when you
+> intentionally want to discard the generated-data caches.
 
 > [!tip]
 > Get a free API key from [Mistral AI](https://mistral.ai) (works with `mistral-small-latest`) or [OpenRouter](https://openrouter.ai/openai/gpt-oss-20b:free). You can assign different models to different roles in the same workflow.
@@ -238,6 +246,15 @@ class ResponseGenerator:
 
 Then `fastworkflow train` and `fastworkflow run` against your workflow directory. That's the entire integration pattern: a thin command layer over code you already have.
 
+> [!TIP]
+> `plain_utterances` is the highest-leverage thing you write. Training expands your seeds
+> into the synthetic corpus the intent classifier learns from, so seed count and phrasing
+> variety matter more to routing accuracy than any other dial. The two above are enough to
+> get started; before you ship, grow each command to roughly eight varied phrasings —
+> imperative, question, colloquial, terse — rather than paraphrases of one sentence. (The
+> "roughly eight" figure is where returns flattened on one large internal workflow, not a
+> universal constant.)
+
 > [!tip]
 > Prefer to learn by building the smallest possible workflow by hand first? `fastworkflow examples fetch messaging_app_1` is a minimal, fully-worked single-command workflow you can read end-to-end.
 

{fastworkflow-2.22.3 → fastworkflow-2.24.0}/fastworkflow/_workflows/command_metadata_extraction/_commands/ErrorCorrection/you_misunderstood.py

@@ -60,8 +60,10 @@ class ResponseGenerator:
             ])
         )
         response = (
-            "Please select the correct command name from the list below:\n"
-            f"{response}\n\nor type 'abort' to cancel"
+            "I couldn't determine which available command matches your request.\n"
+            "If one of these options applies, enter its command name:\n"
+            f"{response}\n\n"
+            "Otherwise, type 'abort' to cancel, then rephrase your request."
         )
 
         return CommandOutput(

{fastworkflow-2.22.3 → fastworkflow-2.24.0}/fastworkflow/_workflows/command_metadata_extraction/_commands/wildcard.py

@@ -1,27 +1,27 @@
 import fastworkflow
 from fastworkflow import Action, CommandOutput, CommandResponse, NLUPipelineStage
 from fastworkflow.command_executor import CommandExecutor
+from fastworkflow.nlu_labels import PARAMETER_VALUE_PLACEHOLDERS
 
 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",
-    ]
+    # These are the PARAMETER_EXTRACTION stage's bare-value literals. They belong
+    # to nlu_labels.PARAMETER_VALUE_LABEL, not to this command's INTENT_DETECTION
+    # escalation class; see fastworkflow/nlu_labels.py for the stage split.
+    plain_utterances = list(PARAMETER_VALUE_PLACEHOLDERS)
 
     @staticmethod
     def generate_utterances(workflow: fastworkflow.Workflow, command_name: str) -> list[str]:
+        # Only the humanised command name. The placeholders above are excluded on
+        # purpose: training them into the 'wildcard' label taught the escalation
+        # classifier that a bare value like "france" means "escalate to my
+        # parent". The trainer labels them under PARAMETER_VALUE_LABEL instead.
         return [
             command_name.split('/')[-1].lower().replace('_', ' ')
-        ] + Signature.plain_utterances
+        ]
 
 
 class ResponseGenerator:

{fastworkflow-2.22.3 → fastworkflow-2.24.0}/fastworkflow/_workflows/command_metadata_extraction/intent_detection.py

@@ -13,10 +13,16 @@ from fastworkflow.cache_matching import cache_match, store_utterance_cache
 from fastworkflow.model_pipeline_training import (
     CommandRouter
 )
+from fastworkflow.nlu_labels import is_escalation, is_non_routable
 
 from fastworkflow.utils.fuzzy_match import find_best_matches
 
 
+# A low-confidence top-k prediction containing an escalation label remains an
+# ambiguity: prompt with the local command candidates and log that the parent signal
+# was discarded. This is product behaviour, not workflow configuration.
+
+
 class CommandNamePrediction:
     class Output(BaseModel):
         command_name: Optional[str] = None
@@ -125,6 +131,17 @@ class CommandNamePrediction:
                         command_name = predictions[0].split('/')[-1]
                     else:
                         # If confidence is low, treat as ambiguous command (type 1)
+                        if escalation_signals := self.escalation_signals_in(predictions):
+                            logger.warning(
+                                f"Top-k escalation signal discarded in "
+                                f"context '{command_context_name}' for utterance "
+                                f"'{command}'. predictions={predictions}, "
+                                f"suppressed={escalation_signals}. The classifier ranked "
+                                "an escalation label alongside local candidates; the user "
+                                "will be prompted with the local candidates only and the "
+                                "'this belongs to an ancestor context' signal is dropped."
+                            )
+
                         error_msg = self._formulate_ambiguous_command_error_message(
                             predictions, "run_as_agent" in self.app_workflow.context)
 
@@ -138,11 +155,11 @@ class CommandNamePrediction:
         ) and not command_name:
             command_name = "what can i do?"
 
-        if not command_name or command_name == "wildcard":
-            fully_qualified_command_name=None
+        fully_qualified_command_name = self.resolve_fully_qualified_command_name(
+            command_name, command_name_dict)
+        if fully_qualified_command_name is None:
             is_cme_command=False
         else:
-            fully_qualified_command_name = command_name_dict[command_name]
             is_cme_command=(
                 fully_qualified_command_name in cme_command_names or 
                 fully_qualified_command_name in crd.get_command_names('ErrorCorrection')
@@ -154,6 +171,9 @@ class CommandNamePrediction:
                 NLUPipelineStage.INTENT_AMBIGUITY_CLARIFICATION,
                 NLUPipelineStage.INTENT_MISUNDERSTANDING_CLARIFICATION,
             )
+            # A reserved label resolves to None; the clarification cache keys on a
+            # real command name, so there is nothing to store for it.
+            and fully_qualified_command_name is not None
             and not fully_qualified_command_name.endswith('abort')
             and not fully_qualified_command_name.endswith('what_can_i_do')
             and not fully_qualified_command_name.endswith('you_misunderstood')
@@ -277,13 +297,35 @@ class CommandNamePrediction:
         finally:
             db.close()
 
+    @staticmethod
+    def resolve_fully_qualified_command_name(
+        command_name: Optional[str], command_name_dict: dict[str, str]) -> Optional[str]:
+        """Map a predicted label to a fully qualified command name, or None.
+
+        Reserved labels (`wildcard`, `parameter_value`) name no command, so they
+        must resolve to None rather than be looked up in `command_name_dict` —
+        which would raise KeyError. None is what drives the parent-chain walk in
+        the CME wildcard command.
+        """
+        if not command_name or is_non_routable(command_name):
+            return None
+        return command_name_dict[command_name]
+
+    @staticmethod
+    def escalation_signals_in(route_choice_list: list[str]) -> list[str]:
+        """Return the escalation labels present in a prediction list."""
+        return [
+            route_choice for route_choice in route_choice_list
+            if is_escalation(route_choice)
+        ]
+
     @staticmethod
     def _formulate_ambiguous_command_error_message(
         route_choice_list: list[str], run_as_agent: bool) -> str:
         command_list = (
             "\n".join([
                 f"{route_choice.split('/')[-1].lower()}"
-                for route_choice in route_choice_list if route_choice != 'wildcard'
+                for route_choice in route_choice_list if not is_non_routable(route_choice)
             ])
         )
 

{fastworkflow-2.22.3 → fastworkflow-2.24.0}/fastworkflow/_workflows/command_metadata_extraction/parameter_extraction.py

@@ -1,7 +1,9 @@
 import contextlib
 import sys
 import re
-from typing import Dict, List, Optional
+import json
+import ast
+from typing import Dict, List, Optional, Union, get_origin, get_args
 
 from pydantic import BaseModel
 from pydantic_core import PydanticUndefined
@@ -24,6 +26,24 @@ INVALID = fastworkflow.get_env_var("INVALID")
 PARAMETER_EXTRACTION_ERROR_MSG = None
 
 
+def _unwrap_optional(field_type):
+    """
+    Unwrap ``Optional[X]`` / ``Union[X, None]`` to its underlying type.
+
+    Returns ``(inner_type, origin)`` where ``origin`` is ``get_origin`` of the
+    unwrapped type (e.g. ``list`` for ``Optional[List[str]]``). Non-optional
+    types are returned unchanged.
+    """
+    origin = get_origin(field_type)
+    if origin is Union:
+        if non_none_types := [
+            t for t in get_args(field_type) if t is not type(None)
+        ]:
+            field_type = non_none_types[0]
+            origin = get_origin(field_type)
+    return field_type, origin
+
+
 class ParameterExtraction:
     class Output(BaseModel):
         parameters_are_valid: bool
@@ -90,14 +110,22 @@ class ParameterExtraction:
             self.app_workflow, self.command_name, new_params
         )
 
-        # Set all the missing and invalid fields to None before storing
+        # Set all the missing and invalid fields to appropriate sentinel values before storing
         current_values = {
             field_name: getattr(new_params, field_name, None)
             for field_name in list(type(new_params).model_fields.keys())
         }
         for field_name in missing_invalid_fields:
             if field_name in current_values:
-                current_values[field_name] = NOT_FOUND
+                # Determine appropriate sentinel value based on field type
+                field_info = type(new_params).model_fields[field_name]
+                _, origin = _unwrap_optional(field_info.annotation)
+
+                # Use empty list for list fields, NOT_FOUND for others
+                if origin in (list, List):
+                    current_values[field_name] = []
+                else:
+                    current_values[field_name] = NOT_FOUND
         # Reconstruct the model instance without validation
         new_params = new_params.__class__.model_construct(**current_values)
 
@@ -233,13 +261,17 @@ class ParameterExtraction:
             value = getattr(params, field_name, None)
 
             if value in [
-                NOT_FOUND, 
+                NOT_FOUND,
                 None,
                 INVALID_INT_VALUE,
                 INVALID_FLOAT_VALUE
             ]:
                 continue
 
+            # Skip empty lists (sentinel for missing list fields)
+            if isinstance(value, list) and len(value) == 0:
+                continue
+
             display_name = " ".join(word.capitalize() for word in field_name.split('_'))
 
             # Format fields appropriately based on type
@@ -320,7 +352,22 @@ class ParameterExtraction:
             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):
+                # For list-typed fields, an agent may repeat the tag once per item
+                # (e.g. <item_ids>a</item_ids> <item_ids>b</item_ids>). re.search
+                # would keep only the first, silently dropping the rest, so collect
+                # ALL occurrences with findall and hand the list parser every value.
+                _, forigin = _unwrap_optional(
+                    command_parameters_class.model_fields[field_name].annotation
+                )
+                if forigin in (list, List):
+                    matches = re.findall(pattern, command, re.DOTALL)
+                    if len(matches) > 1:
+                        # Multiple repeated tags -> JSON array so the list parser
+                        # below collects every value (not just the first).
+                        extracted_data[field_name] = json.dumps([m.strip() for m in matches])
+                    elif len(matches) == 1:
+                        extracted_data[field_name] = matches[0].strip()
+                elif match := re.search(pattern, command, re.DOTALL):
                     parameter_value = match[1].strip()
                     extracted_data[field_name] = parameter_value
 
@@ -348,8 +395,66 @@ class ParameterExtraction:
                 else:
                     params_data[field_name] = None
 
-            # Update with extracted values
-            params_data |= extracted_data
+            # Parse and type-correct extracted values
+            for field_name, raw_value in extracted_data.items():
+                field_info = command_parameters_class.model_fields[field_name]
+                field_type, origin = _unwrap_optional(field_info.annotation)
+
+                # Handle list types with robust parsing
+                if origin in (list, List):
+                    inner_type = get_args(field_type)[0] if get_args(field_type) else str
+                    parsed_list = None
+
+                    # Try JSON array format
+                    if raw_value.startswith('[') and raw_value.endswith(']'):
+                        with contextlib.suppress(Exception):
+                            parsed = json.loads(raw_value)
+                            if isinstance(parsed, list):
+                                parsed_list = parsed
+
+                    # Try Python literal format
+                    if parsed_list is None:
+                        with contextlib.suppress(Exception):
+                            parsed = ast.literal_eval(raw_value)
+                            if isinstance(parsed, list):
+                                parsed_list = parsed
+
+                    # Try comma-separated format
+                    if parsed_list is None and ',' in raw_value:
+                        parsed_list = [item.strip().strip('"').strip("'") for item in raw_value.split(',')]
+
+                    # Try space-separated format
+                    if parsed_list is None and ' ' in raw_value and not any(c in raw_value for c in ['[', ']', '{', '}', '"', "'"]):
+                        parsed_list = [item.strip() for item in raw_value.split() if item.strip()]
+
+                    # Single value treated as single-item list
+                    if parsed_list is None:
+                        cleaned = raw_value.strip().strip('"').strip("'")
+                        parsed_list = [cleaned] if cleaned else []
+
+                    # Type-convert list items to match the inner type
+                    if parsed_list:
+                        typed_list = []
+                        for item in parsed_list:
+                            if inner_type is str:
+                                typed_list.append(str(item))
+                            elif inner_type is int:
+                                with contextlib.suppress(ValueError, TypeError):
+                                    typed_list.append(int(item))
+                            elif inner_type is float:
+                                with contextlib.suppress(ValueError, TypeError):
+                                    typed_list.append(float(item))
+                            elif isinstance(inner_type, type) and issubclass(inner_type, BaseModel) and isinstance(item, dict):
+                                with contextlib.suppress(Exception):
+                                    typed_list.append(inner_type(**item))
+                            else:
+                                typed_list.append(item)
+                        params_data[field_name] = typed_list
+                    else:
+                        params_data[field_name] = []
+                else:
+                    # Non-list types: use raw value as-is
+                    params_data[field_name] = raw_value
 
             # Construct model without validation
             return command_parameters_class.model_construct(**params_data)
@@ -380,7 +485,7 @@ class ParameterExtraction:
                 None,
                 INVALID_INT_VALUE,
                 INVALID_FLOAT_VALUE,
-            ]:
+            ] or (isinstance(value, list) and len(value) == 0):
                 fields_to_fill.append(field_name)
 
         if not fields_to_fill:

{fastworkflow-2.22.3 → fastworkflow-2.24.0}/fastworkflow/chat_session.py

@@ -101,14 +101,17 @@ class ChatSession:
     def __init__(
         self,
         run_as_agent: bool = False,
+        generate_insights: bool = False,
     ):
         """
         Initialize a chat session.
-        
+
         Args:
             run_as_agent: If True, use agent mode (DSPy-based tool selection).
                          If False (default), use traditional command execution.
-        
+            generate_insights: If True, enable teacher/student insights distillation
+                         on each agent turn (Topology A / CLI only).
+
         A chat session can run multiple workflows that share the same message queues.
         Use start_workflow() to start a specific workflow within this session.
         ChatSession is Topology A: ask_user blocks on the queue until the human answers.
@@ -116,6 +119,7 @@ class ChatSession:
         self._core = WorkflowExecutionContext(
             run_as_agent=run_as_agent,
             mirror_action_log_to_file=True,
+            generate_insights=generate_insights,
         )
 
         # Create queues for user messages and command outputs (CLI transport)
@@ -275,6 +279,11 @@ class ChatSession:
         """Check if running in agent mode."""
         return self._core.run_as_agent
 
+    @property
+    def _distillation_insights_count(self) -> int:
+        """Number of insights extracted so far in insights-distillation mode."""
+        return self._core._distillation_insights_count
+
     @property
     def user_message_queue(self) -> Queue:
         return self._user_message_queue

{fastworkflow-2.22.3 → fastworkflow-2.24.0}/fastworkflow/cli.py

@@ -244,8 +244,17 @@ def add_train_parser(subparsers):
         default=None,
         help="Path to the passwords file (default: passwords.env in current directory, or bundled env file for examples)",
     )
+    parser_train.add_argument(
+        "--regenerate-utterances",
+        action="store_true",
+        help="Ignore the generated-utterance and DSPy parameter-example caches and call "
+             "the LLM again. Costs money "
+             "and breaks reproducibility against previous runs; use after editing seed "
+             "utterances or when you suspect the cache is wrong.",
+    )
     parser_train.set_defaults(func=lambda args: train_with_defaults(args))
 
+
 def add_run_parser(subparsers):
     """Add subparser for the 'run' command."""
     parser_run = subparsers.add_parser("run", help="Run a workflow's interactive assistant.")
@@ -273,6 +282,10 @@ def add_run_parser(subparsers):
         "--assistant", action="store_true", default=False,
         help="Run in assistant (non-agentic) mode. Default is agentic mode.",
     )
+    parser_run.add_argument(
+        "--generate_insights", action="store_true", default=False,
+        help="Enable insights-distillation mode: compare teacher and student agents, extract planning and execution insights on divergence.",
+    )
     parser_run.set_defaults(func=lambda args: run_with_defaults(args))
 
 def add_run_fastapi_mcp_parser(subparsers):