fastworkflow 3.1.0__tar.gz → 3.1.2__tar.gz

{fastworkflow-3.1.0 → fastworkflow-3.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastworkflow
-Version: 3.1.0
+Version: 3.1.2
 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
@@ -15,7 +15,7 @@ Provides-Extra: training
 Requires-Dist: aiohttp (>=3.14.3)
 Requires-Dist: colorama (>=0.4.6,<0.5.0)
 Requires-Dist: cryptography (>=50.0.0)
-Requires-Dist: datasets (>=4.0.0,<5.0.0) ; extra == "training"
+Requires-Dist: datasets (>=5.0.1,<6.0.0) ; extra == "training"
 Requires-Dist: dspy (>=3.0.1,<4.0.0)
 Requires-Dist: fastapi (>=0.120.1) ; extra == "server" or extra == "fastapi"
 Requires-Dist: fastapi-mcp (>=0.4.0,<0.5.0) ; extra == "server" or extra == "fastapi"

{fastworkflow-3.1.0 → fastworkflow-3.1.2}/fastworkflow/_workflows/command_metadata_extraction/intent_detection.py

@@ -111,12 +111,29 @@ class CommandNamePrediction:
             command = command.replace(f"{tentative_command_name}", "").strip().replace("  ", " ")
         else:
             # Use Levenshtein distance for fuzzy matching with the full command part after @
+            # No match is ([], None), never (None, None) — len() here is safe.
             best_matched_commands, _ = find_best_matches(
                 command.replace(" ", "_"),
                 command_name_dict.keys(),
                 threshold=0.3  # Adjust threshold as needed
             )
-            if best_matched_commands:
+            if (
+                len(best_matched_commands) > 1
+                and nlu_pipeline_stage == NLUPipelineStage.INTENT_DETECTION
+            ):
+                # Commands sharing a prefix tie at distance 0, because scoring
+                # compares only the leading len(input) characters, and
+                # command_name_dict iterates a set — so picking [0] would choose
+                # nondeterministically between them across processes. Leave the
+                # name unset so the classifier and its ambiguity prompt decide.
+                # The clarification stages are deliberately excluded: they have
+                # no classifier to fall back to.
+                logger.warning(
+                    f"Fuzzy pre-match tied across {best_matched_commands} for "
+                    f"utterance '{command}' in context '{command_context_name}'. "
+                    "Deferring to the classifier instead of picking one."
+                )
+            elif best_matched_commands:
                 command_name = best_matched_commands[0]
 
         if nlu_pipeline_stage == NLUPipelineStage.INTENT_DETECTION:

{fastworkflow-3.1.0 → fastworkflow-3.1.2}/fastworkflow/docs/integrate-chat-agent/reference.md

@@ -168,7 +168,11 @@ class ResponseGenerator:
 ```
 - Use `default="NOT_FOUND"` for parameters so missing values are detected, not hallucinated.
 - Use `Field` `description` + `examples` (and `pattern`/`min_length` where helpful) to drive accurate parameter extraction.
-- Optional hooks: `db_lookup(workflow_snapshot, command)`, `process_extracted_parameters(...)`.
+- Optional hooks: `db_lookup(workflow, field_name, field_value) -> tuple[bool, str | None, list[str]]`,
+  `process_extracted_parameters(...)`. `db_lookup` runs for fields marked
+  `json_schema_extra={'db_lookup': True}` and has three return states: `(True, value, [])`
+  overwrites the field, `(False, None, [suggestions])` fails validation, and
+  `(False, None, [])` does neither — use that last one for a value your hook does not own.
 - For LLM-generated responses, use `fastworkflow.utils.dspy_utils.dspySignature(Signature.Input, Signature.Output)` with `dspy.Predict`.
 
 ### Context model — `_commands/context_inheritance_model.json`

fastworkflow-3.1.2/fastworkflow/utils/fuzzy_match.py

@@ -0,0 +1,170 @@
+import re
+import sys
+from typing import Optional
+import Levenshtein
+
+# Windows are the (normalized) input length. db_lookup scores catalogue
+# fields — names, emails, ids — tens to a few hundred characters, not
+# megabytes. Rounding error on max_normalized * max_length is about
+# sys.float_info.epsilon * max_length; at one million characters that is
+# still ~2e-10. The nudge must exceed that scaled error so a product one
+# ulp below an integer (e.g. (1/49)*49) is not floored, and stay << 1 so
+# a fractional edit count such as 0.8 (bound 0.2 on a 4-char window) is
+# not promoted to the next integer.
+_MAX_SCORED_WINDOW = 1_000_000
+_SCORE_CUTOFF_NUDGE = 8 * sys.float_info.epsilon * _MAX_SCORED_WINDOW
+
+def normalize_text(text):
+        """
+        Normalize text by removing spaces, @ symbol, underscores, and converting to lowercase
+        """
+        return re.sub(r'[@\s_]', '', str(text).lower())
+
+def normalized_levenshtein_distance(
+        s1, s2, max_normalized: Optional[float] = None):
+        """Calculate normalized Levenshtein distance.
+
+        ``max_normalized`` is an optional upper bound. Distances that cannot
+        beat it are not fully computed; a value strictly greater than
+        ``max_normalized`` is returned instead. Callers must treat that
+        sentinel as "worse", never as a tie at the bound.
+        """
+        max_length = max(len(s1), len(s2))
+        if max_length == 0:
+            return 0.0
+        if max_normalized is None:
+            return Levenshtein.distance(s1, s2) / max_length
+        cutoff = int(max_normalized * max_length + _SCORE_CUTOFF_NUDGE)
+        distance = Levenshtein.distance(s1, s2, score_cutoff=cutoff)
+        if distance > cutoff:
+            return max_normalized + 1.0
+        return distance / max_length
+
+def best_window_distance(
+        normalized_input: str,
+        normalized_candidate: str,
+        max_normalized: float = 1.0,
+        ) -> float:
+    """Smallest normalized distance between the input and any equal-length window
+    of the candidate.
+
+    Exact containment is distance 0.0 and returns immediately. Remaining
+    windows use Levenshtein's ``score_cutoff`` so a window that cannot beat
+    ``max_normalized`` (or the best window seen so far) is abandoned early.
+    If no window beats ``max_normalized``, a value strictly greater than it
+    is returned so the caller does not invent a tie at the bound.
+    """
+    if normalized_input in normalized_candidate:
+        return 0.0
+
+    len_input = len(normalized_input)
+    n_windows = max(len(normalized_candidate) - len_input, 0) + 1
+    best: Optional[float] = None
+    bound = max_normalized
+    for i in range(n_windows):
+        dist = normalized_levenshtein_distance(
+            normalized_input,
+            normalized_candidate[i:i + len_input],
+            max_normalized=bound,
+        )
+        if dist > bound:
+            continue
+        if best is None or dist < best:
+            best = dist
+            bound = dist
+            if best == 0.0:
+                return 0.0
+    return best if best is not None else max_normalized + 1.0
+
+def find_best_matches(input_text: str, 
+                    text_list: list[str], 
+                    threshold: float=0.4,
+                    best_window: bool=False
+                    ) -> tuple[list[str], Optional[float]]:
+    """Find best match(es) using normalized Levenshtein distance.
+
+    The function now returns *all* entries whose normalized Levenshtein
+    distance equals the minimum distance computed for the provided
+    ``input_text``. This is useful when multiple candidates tie for the
+    smallest distance.
+
+    Parameters
+    ----------
+    best_window
+        By default each candidate is scored on its *leading* ``len(input_text)``
+        characters, so a candidate that contains the input anywhere else is
+        scored as though it did not contain it at all: searching for
+        ``Garrison`` scores ``Barry Jones`` (0.375) ahead of ``Aaron Garrison``
+        (0.750). When true, every window of that length is scored and the best
+        one wins, so a containing candidate always reaches distance 0.0.
+
+        This is opt-in rather than the default because it can only *lower*
+        distances, and therefore admits strictly more matches at any fixed
+        threshold. Callers that route on the first match instead of treating
+        ties as ambiguity depend on the narrower leading-window behaviour.
+
+    Returns
+    -------
+    tuple[list[str], Optional[float]]
+        A tuple containing the list of best-matching original strings
+        and the corresponding distance. If the best distance exceeds
+        the ``threshold`` value, or if ``text_list`` is empty,
+        ``([], None)`` is returned — never ``(None, None)``. Callers
+        must treat an empty list as "no match" (truthiness or ``len``);
+        ``best_matches is None`` is always false.
+    """
+
+    # Ensure we have a concrete list (e.g., when a generator is passed)
+    text_list = list(text_list)
+
+    normalized_input = normalize_text(input_text)
+    normalized_list = [normalize_text(text) for text in text_list]
+
+    if not normalized_list:
+        return ([], None)
+
+    if best_window:
+        # Containment is distance 0.0. Once any candidate contains the
+        # input, later candidates can only tie by also containing it —
+        # there is no need to slide windows over the rest of the list.
+        contained = [
+            text for text, normalized in zip(text_list, normalized_list)
+            if normalized_input in normalized
+        ]
+        if contained:
+            return (contained, 0.0)
+
+        normalized_distances = []
+        best_so_far = 1.0
+        for normalized in normalized_list:
+            dist = best_window_distance(
+                normalized_input, normalized, max_normalized=best_so_far)
+            if dist < best_so_far:
+                best_so_far = dist
+            normalized_distances.append(dist)
+    else:
+        len_input = len(normalized_input)
+        # Compute distances between the input and every candidate truncated to len of input
+        normalized_distances = [
+            normalized_levenshtein_distance(normalized_input, normalized[:len_input])
+            for normalized in normalized_list
+        ]
+
+    # Determine the minimal distance observed
+    best_distance = min(normalized_distances)
+
+    # Gather *all* indices whose distance equals the minimal distance
+    # Use a small tolerance to account for floating-point precision issues
+    tolerance = 1e-12
+    best_match_indices = [
+        i for i, dist in enumerate(normalized_distances)
+        if abs(dist - best_distance) <= tolerance
+    ]
+
+    # Map indices back to the original (non-normalized) texts
+    best_matches = [text_list[i] for i in best_match_indices]
+
+    if best_distance <= threshold:
+        return (best_matches, best_distance)
+
+    return ([], None)

{fastworkflow-3.1.0 → fastworkflow-3.1.2}/fastworkflow/utils/signatures.py

@@ -68,8 +68,38 @@ class DatabaseValidator:
     """Generic validator for database lookups with fuzzy matching"""
     
     @staticmethod
-    def fuzzy_match(value: str, key_values: list[str], threshold: float = 0.2) -> Tuple[bool, Optional[str], List[str]]:
-        """Find the closest matching value in the specified database."""
+    def fuzzy_match(value: str, key_values: list[str], threshold: float = 0.6,
+                    suggest_threshold: float = 0.7,
+                    auto_apply_threshold: float = 0.2) -> Tuple[bool, Optional[str], List[str]]:
+        """Find the closest matching value in the specified database.
+
+        Three stages run in order, and each one short-circuits: a
+        case-insensitive exact match, then Levenshtein, then ``difflib``.
+
+        Parameters
+        ----------
+        threshold
+            ``difflib`` cutoff for the final suggestion-only stage. Only values
+            that no candidate came within ``suggest_threshold`` of reach it, so
+            a loose cutoff here yields unrelated suggestions rather than useful
+            ones — and because any non-empty suggestion list fails validation,
+            those unrelated suggestions reject values that are merely absent
+            from this particular candidate list.
+        suggest_threshold
+            Maximum Levenshtein distance at which a candidate is considered at
+            all. Beyond this the value falls through to ``difflib``.
+        auto_apply_threshold
+            Maximum Levenshtein distance at which a *unique* match is reported
+            as matched, which makes the framework overwrite the user's value.
+            Kept strict deliberately: the distance at which a real typo lands
+            and the distance at which an unrelated value lands are separable,
+            and being generous here silently substitutes non-members (``Batman``
+            scores 0.333 against a customer list). Note the metric is
+            edits/length, so a one-edit typo on a value shorter than about five
+            characters exceeds this and is offered as a suggestion instead.
+            Raise it per command if an extra clarification turn costs more than
+            a wrong substitution.
+        """
         global NOT_FOUND
         if not NOT_FOUND:
             NOT_FOUND = fastworkflow.get_env_var("NOT_FOUND")
@@ -84,10 +114,12 @@ class DatabaseValidator:
         if match is not None:
             return True, match, []
 
-        best_matches, _ = find_best_matches(value, key_values, threshold = 0.7)
-        if len(best_matches) == 1:
-            return True, best_matches[0], []
-        elif len(best_matches) > 1:
+        best_matches, best_distance = find_best_matches(
+            value, key_values, threshold = suggest_threshold, best_window = True)
+        if best_matches:
+            if len(best_matches) == 1 and best_distance <= auto_apply_threshold:
+                return True, best_matches[0], []
+            # Ambiguous, or close enough to offer but too far to apply unannounced.
             return False, None, best_matches
 
         lowercase_matches = get_close_matches(
@@ -634,6 +666,11 @@ Today's date is {today}.
                 # matched, corrected_value, field_suggestions = DatabaseValidator.fuzzy_match(field_value, key_values)
 
                 if matched:
+                    if corrected_value != field_value:
+                        logger.debug(
+                            f"db_lookup substituted {subject_command_name}.{field_name}: "
+                            f"'{field_value}' -> '{corrected_value}'"
+                        )
                     setattr(cmd_parameters, field_name, corrected_value)
                 elif field_suggestions:
                     invalid_fields.append(f"{field_name} '{field_value}'")

{fastworkflow-3.1.0 → fastworkflow-3.1.2}/pyproject.toml

@@ -9,7 +9,7 @@ repository = "https://github.com/radiantlogicinc/fastworkflow"
 
 [tool.poetry]
 name = "fastworkflow"
-version = "3.1.0"
+version = "3.1.2"
 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"
@@ -76,7 +76,7 @@ starlette = {version = ">=1.3.1", optional = true}  # CVE-2025-62727, CVE-2025-5
 # and future starlette releases will require httpx2. Floor matches starlette's `full` extra (httpx2>=2.0.0).
 httpx2 = {version = ">=2.0.0", optional = true}
 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}
+datasets = {version = "^5.0.1", optional = true}  # CVE-2026-66007 / PYSEC-2026-3716 (path traversal via unsanitized file_name; fixed 5.0.1)
 
 # Security floor constraints for transitive dependencies of the CORE (client) install.
 # These ensure users get patched versions even though these are not direct deps.

fastworkflow-3.1.0/fastworkflow/utils/fuzzy_match.py

@@ -1,70 +0,0 @@
-import re
-from typing import Optional
-import Levenshtein
-
-def normalize_text(text):
-        """
-        Normalize text by removing spaces, @ symbol, underscores, and converting to lowercase
-        """
-        return re.sub(r'[@\s_]', '', str(text).lower())
-
-def normalized_levenshtein_distance(s1, s2):
-        """Calculate normalized Levenshtein distance"""
-        distance = Levenshtein.distance(s1, s2)
-        max_length = max(len(s1), len(s2))
-        return 0.0 if max_length == 0 else distance / max_length
-
-def find_best_matches(input_text: str, 
-                    text_list: list[str], 
-                    threshold: float=0.4
-                    ) -> tuple[list[str], float] | tuple[None, None]:
-    """Find best match(es) using normalized Levenshtein distance.
-
-    The function now returns *all* entries whose normalized Levenshtein
-    distance equals the minimum distance computed for the provided
-    ``input_text``. This is useful when multiple candidates tie for the
-    smallest distance.
-
-    Returns
-    -------
-    tuple[list[str], float] | tuple[None, None]
-        A tuple containing the list of best-matching original strings
-        and the corresponding distance. If the best distance exceeds
-        the ``threshold`` value, ``(None, None)`` is returned.
-    """
-
-    # Ensure we have a concrete list (e.g., when a generator is passed)
-    text_list = list(text_list)
-
-    normalized_input = normalize_text(input_text)
-    normalized_list = [normalize_text(text) for text in text_list]
-
-    # If empty list, return None
-    if not normalized_list:
-        return ([], None)
-
-    len_input = len(normalized_input)
-    # Compute distances between the input and every candidate truncated to len of input
-    normalized_distances = [
-        normalized_levenshtein_distance(normalized_input, normalized[:len_input])
-        for normalized in normalized_list
-    ]
-
-    # Determine the minimal distance observed
-    best_distance = min(normalized_distances)
-
-    # Gather *all* indices whose distance equals the minimal distance
-    # Use a small tolerance to account for floating-point precision issues
-    tolerance = 1e-12
-    best_match_indices = [
-        i for i, dist in enumerate(normalized_distances)
-        if abs(dist - best_distance) <= tolerance
-    ]
-
-    # Map indices back to the original (non-normalized) texts
-    best_matches = [text_list[i] for i in best_match_indices]
-
-    if best_distance <= threshold:
-        return (best_matches, best_distance)
-
-    return ([], None)