fastworkflow 2.22.3__tar.gz → 2.23.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastworkflow
-Version: 2.22.3
+Version: 2.23.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>

{fastworkflow-2.22.3 → fastworkflow-2.23.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>

{fastworkflow-2.22.3 → fastworkflow-2.23.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.23.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.23.0}/fastworkflow/cli.py

@@ -273,6 +273,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):