fastworkflow 2.22.0__tar.gz → 2.22.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastworkflow
-Version: 2.22.0
+Version: 2.22.3
 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
@@ -32,6 +32,7 @@ Requires-Dist: prompt_toolkit (>=3.0.43,<4.0.0)
 Requires-Dist: pyarrow (>=23.0.1)
 Requires-Dist: pyasn1 (>=0.6.3)
 Requires-Dist: pydantic (>=2.9.2,<3.0.0)
+Requires-Dist: pydantic-settings (>=2.14.2) ; extra == "server" or extra == "fastapi"
 Requires-Dist: pygments (>=2.20.0)
 Requires-Dist: pyjwt[crypto] (>=2.13.0) ; extra == "server" or extra == "fastapi"
 Requires-Dist: python-dotenv (>=1.2.2,<2.0.0)

{fastworkflow-2.22.0 → fastworkflow-2.22.3}/fastworkflow/command_directory.py

@@ -1,4 +1,5 @@
 import contextlib
+import hashlib
 import os
 from typing import Optional
 from pathlib import Path
@@ -121,6 +122,9 @@ class CommandDirectory(BaseModel):
     core_command_names: list[str] = Field(default_factory=list)
     # Mapping of context name to its metadata containing callback class module information
     map_context_2_metadata: dict[str, "ContextMetadata"] = Field(default_factory=dict)
+    # Fingerprint of the command sources this snapshot was built from. Used to
+    # invalidate the persisted cache when commands are added/removed/renamed/edited.
+    source_fingerprint: Optional[str] = None
 
     def register_command_metadata(self, command_name: str, metadata: CommandMetadata):
         if not (command_name and metadata):
@@ -165,6 +169,9 @@ class CommandDirectory(BaseModel):
 
     def save(self):
         commandroutinginfo_folderpath = CommandDirectory.get_commandinfo_folderpath(self.workflow_folderpath)
+        # Stamp the current source fingerprint so the persisted snapshot can be
+        # validated (and invalidated) against the live _commands tree on reload.
+        self.source_fingerprint = compute_commands_source_fingerprint(self.workflow_folderpath)
         with open(Path(commandroutinginfo_folderpath) / "command_directory.json", "w") as f:
             f.write(self.model_dump_json(indent=4))
 
@@ -593,16 +600,71 @@ def _lazy_hydrate_metadata(module_path: str, metadata: CommandMetadata, director
             module,
         )
 
+# Files (beyond *.py) that the command/routing snapshots derive from. Changes
+# to these must also invalidate the persisted caches.
+_CONTEXT_MODEL_BASENAMES = ("context_inheritance_model.json",)
+
+
+def _command_source_roots(workflow_folderpath: str) -> list[Path]:
+    """Return every `_commands` root that contributes to this workflow.
+
+    This includes the workflow's own `_commands` plus any base-workflow
+    `_commands` declared via `workflow_inheritance_model.json`. Base resolution
+    is best-effort: if it fails we still fingerprint the local sources so the
+    cache never silently goes stale.
+    """
+    roots: list[Path] = []
+    with contextlib.suppress(Exception):
+        inheritance_model = WorkflowInheritanceModel.load(workflow_folderpath)
+        roots.extend(
+            Path(base_path) / "_commands"
+            for base_path in inheritance_model.resolve_base_paths(workflow_folderpath)
+        )
+    roots.append(Path(workflow_folderpath) / "_commands")
+    return roots
+
+
+def compute_commands_source_fingerprint(workflow_folderpath: str) -> str:
+    """Fingerprint the command sources a snapshot is derived from.
+
+    The fingerprint is a hash over the *set* of source files and their
+    `(size, mtime_ns)`. Unlike a "newest mtime" comparison, this detects
+    additions, deletions, renames, and edits uniformly, which is required to
+    safely invalidate `command_directory.json` and `routing_definition.json`.
+    """
+    workflow_folderpath = str(Path(workflow_folderpath).resolve())
+    entries: list[tuple[str, int, int]] = []
+
+    for root in _command_source_roots(workflow_folderpath):
+        if not root.is_dir():
+            continue
+        for p in root.rglob("*"):
+            if not p.is_file():
+                continue
+            if p.suffix == ".py" or p.name in _CONTEXT_MODEL_BASENAMES:
+                st = p.stat()
+                entries.append((str(p), st.st_size, st.st_mtime_ns))
+
+    # Routing also depends on the hierarchy model at the workflow root.
+    hierarchy = Path(workflow_folderpath) / "context_hierarchy_model.json"
+    if hierarchy.is_file():
+        st = hierarchy.stat()
+        entries.append((str(hierarchy), st.st_size, st.st_mtime_ns))
+
+    return hashlib.sha256(repr(sorted(entries)).encode("utf-8")).hexdigest()
+
+
 @lru_cache(maxsize=32)
 def get_cached_command_directory(workflow_folderpath: str) -> CommandDirectory:
     """Return a cached CommandDirectory, rebuilding only when sources change.
 
     The cache key is the *resolved* workflow path so that duplicate relative
-    paths share the same entry.  We compare the modification time of the
-    persisted `command_directory.json` file against the most recent `.py`
-    timestamp in the `_commands` tree.  When the cache is fresh we deserialize
-    the JSON directly; otherwise we rebuild via `CommandDirectory.load()` and
-    persist the new snapshot.
+    paths share the same entry. We validate the persisted `command_directory.json`
+    against a fingerprint of the live `_commands` tree (see
+    `compute_commands_source_fingerprint`). When the fingerprint matches we
+    deserialize the JSON directly; otherwise we rebuild via
+    `CommandDirectory.load()` and persist the new snapshot. The fingerprint is
+    deletion- and rename-aware, unlike a plain mtime comparison.
     """
 
     workflow_folderpath = str(Path(workflow_folderpath).resolve())
@@ -610,18 +672,16 @@ def get_cached_command_directory(workflow_folderpath: str) -> CommandDirectory:
     cache_folder = Path(CommandDirectory.get_commandinfo_folderpath(workflow_folderpath))
     cache_file = cache_folder / "command_directory.json"
 
-    commands_root = Path(workflow_folderpath) / "_commands"
-    if commands_root.exists():
-        # Use a generator expression with a default to handle empty directories
-        latest_src_mtime = max((p.stat().st_mtime for p in commands_root.rglob("*.py")), default=0.0)
-    else:
-        latest_src_mtime = 0.0
+    current_fingerprint = compute_commands_source_fingerprint(workflow_folderpath)
 
-    # Fast-path: load JSON if it is newer than any source file
-    if cache_file.exists() and cache_file.stat().st_mtime > latest_src_mtime:
-        return CommandDirectory.model_validate_json(cache_file.read_text())
-            
-    # (Re)build and persist
+    # Fast-path: load JSON if its stamped fingerprint matches the live sources
+    if cache_file.exists():
+        with contextlib.suppress(Exception):
+            cached = CommandDirectory.model_validate_json(cache_file.read_text())
+            if cached.source_fingerprint == current_fingerprint:
+                return cached
+
+    # (Re)build and persist (save() re-stamps the fingerprint)
     directory = CommandDirectory.load(workflow_folderpath)
     directory.save()
     return directory

{fastworkflow-2.22.0 → fastworkflow-2.22.3}/fastworkflow/command_routing.py

@@ -23,7 +23,12 @@ from typing import Any, Dict, Optional, Set, Type, ClassVar
 from pydantic import BaseModel, ConfigDict
 
 from fastworkflow import ModuleType
-from fastworkflow.command_directory import CommandDirectory, UtteranceMetadata, get_cached_command_directory
+from fastworkflow.command_directory import (
+    CommandDirectory,
+    UtteranceMetadata,
+    compute_commands_source_fingerprint,
+    get_cached_command_directory,
+)
 from fastworkflow.command_context_model import CommandContextModel
 from fastworkflow.utils import python_utils
 from fastworkflow.utils.logging import logger
@@ -192,7 +197,12 @@ class RoutingDefinition(BaseModel):
             save_dict['command_directory_map'] = {k: list(v) for k, v in save_dict['command_directory_map'].items()}
         if 'routing_definition_map' in save_dict:
             save_dict['routing_definition_map'] = {k: list(v) for k, v in save_dict['routing_definition_map'].items()}
-        
+
+        # Stamp the source fingerprint so the persisted routing definition can be
+        # invalidated when commands/contexts change. Unlike command_directory.json,
+        # this file previously had no staleness check at all.
+        save_dict['source_fingerprint'] = compute_commands_source_fingerprint(self.workflow_folderpath)
+
         with open(save_path, "w", encoding="utf-8") as f:
             json.dump(save_dict, f, indent=4)
 
@@ -348,10 +358,20 @@ class RoutingRegistry:
             if workflow_folderpath in cls._definitions:
                 return cls._definitions[workflow_folderpath]
 
-            # Attempt to load; if missing, build and save
-            try:
-                definition = RoutingDefinition.load(workflow_folderpath)
-            except Exception:
+            # Attempt to load the persisted definition, but only trust it when its
+            # stamped source fingerprint still matches the live _commands tree.
+            # This is the staleness check the persisted routing definition
+            # previously lacked: without it, adding/removing/renaming a command
+            # left routing_definition.json pointing at the old command set until
+            # it was manually deleted.
+            definition = None
+            if cls._persisted_definition_is_fresh(workflow_folderpath):
+                try:
+                    definition = RoutingDefinition.load(workflow_folderpath)
+                except Exception:
+                    definition = None
+
+            if definition is None:
                 definition = RoutingDefinition.build(workflow_folderpath)
                 definition.save()
             cls._definitions[workflow_folderpath] = definition
@@ -361,6 +381,31 @@ class RoutingRegistry:
         cls._definitions[workflow_folderpath] = RoutingDefinition.build(workflow_folderpath)
         return cls._definitions[workflow_folderpath]
 
+    @staticmethod
+    def _persisted_definition_is_fresh(workflow_folderpath: str) -> bool:
+        """Return True if routing_definition.json exists and its stamped
+        source fingerprint matches the current _commands tree.
+
+        A missing file, unreadable JSON, missing/legacy fingerprint, or a
+        fingerprint mismatch all count as *not fresh*, forcing a rebuild.
+        """
+        load_path = (
+            f"{CommandDirectory.get_commandinfo_folderpath(workflow_folderpath)}"
+            f"/routing_definition.json"
+        )
+        if not os.path.isfile(load_path):
+            return False
+        try:
+            with open(load_path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+        except (OSError, json.JSONDecodeError):
+            return False
+
+        if stored_fingerprint := data.get("source_fingerprint"):
+            return stored_fingerprint == compute_commands_source_fingerprint(workflow_folderpath)
+        else:
+            return False
+
     @classmethod
     def clear_registry(cls):
         """Clears the registry. Useful for testing."""

{fastworkflow-2.22.0 → fastworkflow-2.22.3}/fastworkflow/train/__main__.py

@@ -1,4 +1,5 @@
 import argparse
+import contextlib
 import os
 import json
 import shutil
@@ -11,7 +12,7 @@ import fastworkflow
 from fastworkflow.utils.logging import logger
 from fastworkflow.utils import python_utils
 from fastworkflow import ModuleType
-from fastworkflow.model_pipeline_training import train, get_route_layer_filepath_model
+from fastworkflow.model_pipeline_training import train, get_route_layer_filepath_model, GLOBAL_CONTEXT_FOLDER
 from fastworkflow.utils.generate_param_examples import generate_dspy_examples
 from fastworkflow.command_directory import CommandDirectory, get_cached_command_directory
 from fastworkflow.command_routing import RoutingDefinition, RoutingRegistry
@@ -81,6 +82,12 @@ def train_workflow(workflow_path: str):
     train(workflow)
     workflow.close()
 
+    # Only after training has successfully (re)generated artifacts do we prune
+    # leftovers from commands/contexts that no longer exist. Running this *after*
+    # the writes (rather than wiping up-front) means a failed train leaves the
+    # previous, complete ___command_info intact and runnable.
+    _prune_stale_artifacts(workflow_path)
+
 def _generate_dspy_examples_helper(workflow):
     json_path=get_route_layer_filepath_model(workflow.folderpath,"command_directory.json")
     # json_path = "./examples/sample_workflow/___command_info/command_directory.json"
@@ -123,6 +130,56 @@ def _generate_dspy_examples_helper(workflow):
         else:
             None
 
+def _prune_stale_artifacts(workflow_path: str):
+    """Remove orphaned per-command and per-context training artifacts.
+
+    An artifact is "orphaned" only when the command or context it belongs to no
+    longer exists in the freshly built routing definition / command directory.
+    This is intentionally conservative: it never touches the JSON snapshots
+    themselves, and it never removes a model folder whose context is still known
+    (so checked-in / still-valid models such as ErrorCorrection are preserved).
+
+    Because orphans are looked up by name/context at run time, they are harmless;
+    this is purely a cleanliness pass and is safe to run after a successful train.
+    """
+    info_dir = os.path.join(workflow_path, "___command_info")
+    if not os.path.isdir(info_dir):
+        return
+
+    # Expected per-command DSPy artifacts: one per command that has parameters.
+    cmd_dir_json = os.path.join(info_dir, "command_directory.json")
+    expected_param_files: set[str] = set()
+    if os.path.isfile(cmd_dir_json):
+        commands = _get_commands_with_parameters(cmd_dir_json)
+        expected_param_files = {f"{name}_param_labeled.json" for name in commands}
+
+    # Expected per-context model folders: every context known to routing, with
+    # "*" mapped to the global folder. Folders for unknown contexts are orphans.
+    crd = RoutingRegistry.get_definition(workflow_path)
+    expected_ctx_folders = {GLOBAL_CONTEXT_FOLDER}
+    for ctx_name in crd.contexts.keys():
+        expected_ctx_folders.add(GLOBAL_CONTEXT_FOLDER if ctx_name == "*" else ctx_name)
+
+    for entry in os.listdir(info_dir):
+        full_path = os.path.join(info_dir, entry)
+        if (
+            entry.endswith("_param_labeled.json")
+            and os.path.isfile(full_path)
+            and entry not in expected_param_files
+        ):
+            with contextlib.suppress(OSError):
+                os.remove(full_path)
+                logger.info(f"Pruned orphaned param artifact: {full_path}")
+        elif (
+            os.path.isdir(full_path)
+            and os.path.isfile(os.path.join(full_path, "threshold.json"))
+            and entry not in expected_ctx_folders
+        ):
+            with contextlib.suppress(OSError):
+                shutil.rmtree(full_path)
+                logger.info(f"Pruned orphaned context model folder: {full_path}")
+
+
 def _get_commands_with_parameters(json_path):
     """
     Parse command_directory.json file and create a mapping between command names 

{fastworkflow-2.22.0 → fastworkflow-2.22.3}/fastworkflow/workflow_agent.py

@@ -370,6 +370,12 @@ def _ask_user_tool(clarification_request: str, chat_session_obj: fastworkflow.Ch
     )
     if output_queue is not None:
         output_queue.put(command_output)
+        # Preserve the transport contract: the output must be visible before the
+        # trace sentinel releases the CLI to read it. In v3.0 the queued payload
+        # becomes a partial TurnOutput, but the pairing and ordering stay the same.
+        trace_queue = chat_session_obj.command_trace_queue
+        if trace_queue is not None:
+            trace_queue.put(None)
 
     # Topology A: append the unanswered ask_user entry before blocking.
     # (Topology B appends it inside the WEC core at AskUserSuspend time.)

{fastworkflow-2.22.0 → fastworkflow-2.22.3}/pyproject.toml

@@ -9,7 +9,7 @@ repository = "https://github.com/radiantlogicinc/fastworkflow"
 
 [tool.poetry]
 name = "fastworkflow"
-version = "2.22.0"
+version = "2.22.3"
 description = "A framework for rapidly building large-scale, deterministic, interactive workflows with a fault-tolerant, conversational UX"
 authors = ["Dhar Rawal <drawal@radiantlogic.com>"]
 license = "Apache-2.0"
@@ -69,6 +69,7 @@ fastapi-mcp = {version = "^0.4.0", optional = true}
 pyjwt = {extras = ["crypto"], version = ">=2.13.0", optional = true}  # Replaces python-jose (CVE-2024-23342); >=2.13.0 fixes alg allow-list bypass (PYSEC-2026-176) + DoS (PYSEC-2026-175/177/178/179)
 python-multipart = {version = ">=0.0.31", optional = true}  # CVE-2026-40347, CVE-2026-42561 (multipart parsing DoS) + CVE-2026-53540 (negative Content-Length unbounded read, fixed 0.0.31). Only pulled by the `server` extra (FastAPI form parsing); not needed by the client/core install.
 starlette = {version = ">=1.3.1", optional = true}  # CVE-2025-62727, CVE-2025-54121 (Range header DoS) + CVE-2026-54282 (request.url host spoof, 1.3.0) + CVE-2026-54283 (urlencoded form DoS, 1.3.1). Pulled transitively by fastapi (requires starlette>=0.46.0) in the `server` extra.
+pydantic-settings = {version = ">=2.14.2", optional = true}  # GHSA-4xgf-cpjx-pc3j (NestedSecretsSettingsSource follows symlinks outside secrets_dir -> local file read + secrets_dir_max_size bypass, fixed 2.14.2). Pulled transitively by mcp/fastapi-mcp in the `server` extra.
 datasets = {version = "^4.0.0", optional = true}
 
 # Security floor constraints for transitive dependencies of the CORE (client) install.
@@ -117,6 +118,6 @@ training = ["datasets"]
 # Full FastAPI-MCP server feature set (`fastworkflow run_fastapi_mcp`) with the
 # security-patched server deps. `litellm_proxy/` client routing does NOT require
 # this extra (plain litellm handles it via api_base).
-server = ["uvicorn", "fastapi", "fastapi-mcp", "pyjwt", "python-multipart", "starlette"]
+server = ["uvicorn", "fastapi", "fastapi-mcp", "pyjwt", "python-multipart", "starlette", "pydantic-settings"]
 # Backward-compatible alias for the pre-2.18.2 extra name.
-fastapi = ["uvicorn", "fastapi", "fastapi-mcp", "pyjwt", "python-multipart", "starlette"]
+fastapi = ["uvicorn", "fastapi", "fastapi-mcp", "pyjwt", "python-multipart", "starlette", "pydantic-settings"]