mammoth-cli 2.3.0__tar.gz → 2.3.1__tar.gz

{mammoth_cli-2.3.0 → mammoth_cli-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.3.0
+Version: 2.3.1
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk

{mammoth_cli-2.3.0 → mammoth_cli-2.3.1}/mammoth_cli/__init__.py

@@ -6,7 +6,7 @@ not implement a second HTTP client and does not call private SDK members.
 
 from __future__ import annotations
 
-__version__ = "2.3.0"
+__version__ = "2.3.1"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.3.0 → mammoth_cli-2.3.1}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mammoth-cli
-version: 2.3.0
+version: 2.3.1
 description: "Use Mammoth Analytics from a terminal: install or authenticate the CLI, discover its live command contract, and safely manage projects, data, views, pipelines (join, merge, pivot, filter, clean), dashboards, exports, and handoffs."
 ---
 

{mammoth_cli-2.3.0 → mammoth_cli-2.3.1}/mammoth_cli/commands/how.py

@@ -60,6 +60,17 @@ _NOT_HERE_HINT = (
     "The recipe for this goal needs the user's machine (a local file or the run history), "
     "which the app does not have. Use the app's own tools for that part."
 )
+_TIED_HINT = (
+    "More than one recipe fits this goal equally well, and running the wrong one changes "
+    "data. Pick one from 'alternatives' (mammoth how \"...\" shows its steps), or say more "
+    "about what the goal changes."
+)
+_UNRESOLVED_HINT = (
+    "Part of this goal fits more than one recipe equally well, and running the wrong one "
+    "changes data, so nothing is matched. 'unresolved' names each such part with its "
+    "recipes; 'recipes' are the parts that are clear. Say which recipe the unclear part "
+    "means, or run the parts one by one with mammoth how."
+)
 _NOTHING_HINT = (
     "No recipe and no command matched this goal. Try other words, or run "
     "'mammoth schema list' for every command."
@@ -78,44 +89,129 @@ def _recipe_vocabulary(recipe_id: str) -> frozenset[str]:
 def _term_forms(term: str, compounds: frozenset[str]) -> frozenset[str]:
     from mammoth_cli.commands.schema.find import _token_aliases
 
+    return _token_aliases(term) | frozenset(_HOW_SYNONYMS.get(term, ())) | _stems(term) | compounds
+
+
+def _stems(term: str) -> frozenset[str]:
     # "refreshes", "joined", "building": the recipe words are the plain forms.
     stems = {term[: -len(end)] for end in ("es", "s", "ed", "ing") if term.endswith(end)}
-    stems = {stem for stem in stems if len(stem) >= 3}
-    return (
-        _token_aliases(term) | frozenset(_HOW_SYNONYMS.get(term, ())) | frozenset(stems) | compounds
+    return frozenset(stem for stem in stems if len(stem) >= 3)
+
+
+def _intent_met(recipe: dict[str, Any], action: list[_Form], rest: list[_Form]) -> bool:
+    """Whether the goal says what the recipe does, not only words it shares with it.
+
+    A recipe declares ``intent``: groups of words, the action first and then its object.
+    Each group needs one goal word (or a stem or synonym of one). Generic words
+    ("column", "view", "convert") sit in the vocabulary of many recipes, so overlap on
+    them proves nothing. A recipe marked ``bare_ok`` is also met by its action word alone
+    ("undo", "pivot this"): a goal with no other word names no other object. ``action``
+    is checked against the first group and ``rest`` against the others; they differ for
+    one clause of a longer goal, which may name its object elsewhere ("upload sales.csv,
+    then make a dashboard").
+    """
+    first, *others = recipe["intent"]
+    if recipe.get("bare_ok") and not _names_object(first, action):
+        return any(form & frozenset(first) for _, form in action)
+    return any(form & frozenset(first) and _distinct(others, rest, {word}) for word, form in action)
+
+
+def _names_object(first: list[str], forms: list[_Form]) -> bool:
+    """Whether the goal has a content word besides the recipe's action words."""
+    from mammoth_cli.commands.schema.find import _DISCOVERY_STOPWORDS
+
+    return any(not form & (frozenset(first) | _DISCOVERY_STOPWORDS) for _, form in forms)
+
+
+def _distinct(groups: list[list[str]], forms: list[_Form], used: set[str]) -> bool:
+    """Whether each group can be met by a different goal word.
+
+    Words are told apart by the word itself: the same word read in a clause and in the whole
+    goal has different compounds, so its form sets differ, but it is still one word.
+
+    One word that a synonym turns into two ("weekly" is also "refresh") must not meet the
+    action and the object of a recipe by itself.
+    """
+    if not groups:
+        return True
+    head, *tail = groups
+    return any(
+        word not in used and form & frozenset(head) and _distinct(tail, forms, used | {word})
+        for word, form in forms
     )
 
 
+def _rejected(
+    recipe: dict[str, Any], terms: tuple[str, ...], compounds: dict[str, frozenset[str]]
+) -> bool:
+    """Whether the goal has a word for the opposite job ("merge" for a split)."""
+    reject = frozenset(recipe.get("reject", ()))
+    return any(form & reject for _, form in _forms(terms, compounds))
+
+
+#: A goal word and its forms.
+_Form = tuple[str, frozenset[str]]
+
+
+def _forms(terms: tuple[str, ...], compounds: dict[str, frozenset[str]]) -> list[_Form]:
+    """Each word with its stems and compounds, but not the ``how`` synonyms or the
+    ``schema find`` aliases: those widen a word ("download" also means "csv", "weekly" also
+    means "refresh"), which is right for finding a recipe and wrong for deciding what the
+    user asked to have done to their data. Intent groups list the words they accept."""
+    return [(term, frozenset({term, *compounds.get(term, ())}) | _stems(term)) for term in terms]
+
+
 #: Where a goal with several parts splits: "join X and Y, then build a dashboard".
 _CLAUSE_SPLIT = re.compile(r"\s*(?:;|,|\band then\b|\bthen\b|\band\b|\bthat\b|\bwhich\b)\s*")
 
 
-def _clause_recipe(clause: str, prefer: str | None = None) -> dict[str, Any] | None:
-    """The one recipe a clause of a longer goal clearly asks for, or None.
+def _clause_fits(clause: str, prefer: str | None = None, goal: str = "") -> list[dict[str, Any]]:
+    """The recipe a clause of a longer goal clearly asks for, or the recipes tied for it.
+
+    One recipe is a clear ask; two or more fit the clause equally; none is an empty list.
 
     Two or more of its words match the recipe, or, in a clause of one or two
     words, one word the recipe itself uses ("join orders", "refresh daily").
     """
-    from mammoth_cli.commands.schema.find import _adjacent_compound_forms, _query_tokens, _tokens
+    from mammoth_cli.commands.schema.find import (
+        _adjacent_compound_forms,
+        _ordered_tokens,
+        _query_tokens,
+    )
 
-    terms = _query_tokens(clause) or tuple(_tokens(clause))
+    terms = _query_tokens(clause) or _ordered_tokens(clause)
     if not terms:
-        return None
+        return []
     compounds = _adjacent_compound_forms(terms)
-    best: tuple[int, int, int, int, dict[str, Any]] | None = None
+    whole = _query_tokens(goal) or _ordered_tokens(goal)
+    whole_compounds = _adjacent_compound_forms(whole)
+    # Intent reads every word, the small ones too ("by", "per"), as in _rank.
+    clause_words, whole_words = _ordered_tokens(clause), _ordered_tokens(goal)
+    clause_forms = _forms(clause_words, _adjacent_compound_forms(clause_words))
+    whole_forms = _forms(whole_words, _adjacent_compound_forms(whole_words))
+    fits: list[tuple[tuple[int, int, int, int], dict[str, Any]]] = []
     for order, recipe in enumerate(load_recipes()):
+        # The recipe that fits the whole goal is judged on all of it: "upload a csv" alone
+        # does not say "clean", and a "merge" anywhere in the goal rules out a split.
+        if _rejected(recipe, whole, whole_compounds) or not _intent_met(
+            recipe, clause_forms if recipe["id"] != prefer else whole_forms, whole_forms
+        ):
+            continue
         vocabulary = _recipe_vocabulary(recipe["id"])
         hits = [t for t in terms if _term_forms(t, compounds.get(t, frozenset())) & vocabulary]
         literal = sum(1 for term in hits if term in vocabulary)
         if not (len(hits) >= 2 or (len(terms) <= 2 and literal >= 1)):
             continue
         # The recipe that fits the whole goal wins any clause it also fits.
-        candidate = (int(recipe["id"] == prefer), len(hits), literal, -order, recipe)
-        if best is None or candidate[:4] > best[:4]:
-            best = candidate
-    return best[4] if best else None
+        fits.append(((int(recipe["id"] == prefer), len(hits), literal, -order), recipe))
+    fits.sort(key=lambda fit: fit[0], reverse=True)
+    # Recipes that fit equally well: file order must not pick one.
+    return [recipe for key, recipe in fits if key[:3] == fits[0][0][:3]]
 
 
+#: How well a recipe fits a goal: share of words matched, whole-phrase match, literal words.
+_Key = tuple[float, int, int]
+
 #: Where each recipe sits in a pipeline; a composed goal runs them in this order.
 _STAGE = {
     "append-rows": 0,
@@ -153,44 +249,73 @@ _STAGE = {
 }
 
 
-def _compose(goal: str, prefer: str | None = None) -> list[tuple[str, dict[str, Any]]]:
-    """Each clause of a several-part goal with its recipe, in pipeline order, no repeats."""
+def _compose(
+    goal: str, prefer: str | None = None
+) -> tuple[list[tuple[str, dict[str, Any]]], list[tuple[str, list[dict[str, Any]]]]]:
+    """Each clause of a several-part goal with its recipe, in pipeline order, no repeats.
+
+    Also the clauses that fit two or more recipes equally, each with those recipes: a
+    clause the goal does not settle is reported, not dropped.
+    """
     clauses = [part.strip() for part in _CLAUSE_SPLIT.split(goal) if part.strip()]
     if len(clauses) < 2:
-        return []  # one part: the whole-goal match decides
+        return [], []  # one part: the whole-goal match decides
     found: list[tuple[str, dict[str, Any]]] = []
+    unresolved: list[tuple[str, list[dict[str, Any]]]] = []
     for clause in clauses:
-        recipe = _clause_recipe(clause, prefer)
-        if recipe is not None and all(recipe["id"] != seen["id"] for _, seen in found):
-            found.append((clause, recipe))
-    return sorted(found, key=lambda item: _STAGE.get(item[1]["id"], 3))
-
-
-def _rank(goal: str) -> list[tuple[int, dict[str, Any]]]:
-    """Recipes that fit ``goal``, best first, each with how many goal words it matched."""
-    from mammoth_cli.commands.schema.find import _adjacent_compound_forms, _query_tokens, _tokens
+        fits = [r for r in _clause_fits(clause, prefer, goal) if not recipe_hidden_embedded(r)]
+        if len(fits) > 1:
+            unresolved.append((clause, fits))
+        elif fits and all(fits[0]["id"] != seen["id"] for _, seen in found):
+            found.append((clause, fits[0]))
+    return sorted(found, key=lambda item: _STAGE.get(item[1]["id"], 3)), unresolved
+
+
+def _rank(goal: str) -> list[tuple[_Key, dict[str, Any]]]:
+    """Recipes that fit ``goal``, best first, each with the key it was ranked by."""
+    from mammoth_cli.commands.schema.find import (
+        _adjacent_compound_forms,
+        _ordered_tokens,
+        _query_tokens,
+    )
 
-    terms = _query_tokens(goal) or tuple(_tokens(goal))
+    terms = _query_tokens(goal) or _ordered_tokens(goal)
     if not terms:
         return []
     compounds = _adjacent_compound_forms(terms)
     folded = " ".join(goal.casefold().split())
+    # Intent also reads the small words the search drops ("by", "per"): they say what is grouped.
+    every_word = _ordered_tokens(goal)
+    forms = _forms(every_word, _adjacent_compound_forms(every_word))
     ranked: list[tuple[float, int, int, int, dict[str, Any]]] = []
     for order, recipe in enumerate(load_recipes()):
+        if _rejected(recipe, every_word, {}) or not _intent_met(recipe, forms, forms):
+            continue
         vocabulary = _recipe_vocabulary(recipe["id"])
         matched = sum(
             1 for term in terms if _term_forms(term, compounds.get(term, frozenset())) & vocabulary
         )
-        # More than half the words, or half of them when that is at least two
-        # (the rest are usually the caller's own data words: "customer id").
-        if not (matched * 2 > len(terms) or (matched * 2 == len(terms) and matched >= 2)):
+        # The goal states the recipe's intent (above); two of its words in the recipe's
+        # vocabulary then suffice (one, for a one-word goal), since the rest are the
+        # caller's own data words ("Salesforce", "customer id").
+        if matched < min(2, len(terms)):
             continue
         # A word the recipe itself uses outranks one reached only through a synonym.
         literal = sum(1 for term in terms if term in vocabulary)
         phrase = int(any(folded == goal_text.casefold() for goal_text in recipe["goals"]))
         ranked.append((matched / len(terms), phrase, literal, -order, recipe))
     ranked.sort(key=lambda item: (item[0], item[1], item[2], item[3]), reverse=True)
-    return [(literal, recipe) for _, _, literal, _, recipe in ranked]
+    return [((fit, phrase, literal), recipe) for fit, phrase, literal, _, recipe in ranked]
+
+
+def _tied(ranked: list[tuple[_Key, dict[str, Any]]]) -> list[tuple[_Key, dict[str, Any]]]:
+    """The leading recipes that fit exactly as well as the best one; only file order separates them.
+
+    Two or more of them means the goal does not say which recipe is meant. A recipe run
+    changes data, so the caller must choose rather than take the first.
+    """
+    tied = [item for item in ranked if item[0] == ranked[0][0]]
+    return tied if len(tied) > 1 else []
 
 
 def runnable_for(goal: str, limit: int = 2) -> list[dict[str, Any]]:
@@ -203,6 +328,17 @@ def runnable_for(goal: str, limit: int = 2) -> list[dict[str, Any]]:
     Returns:
         Each recipe's id, title and ``run_command``.
     """
+    # Recipes that fit equally well are all returned: the caller chooses between them, so
+    # the limit never cuts inside a tie group.
+    fits = [
+        (key, recipe)
+        for key, recipe in _rank(goal)
+        if recipe.get("run") and not recipe_hidden_embedded(recipe)
+    ]
+    keys = [key for key, _ in fits]
+    cut = limit
+    while cut < len(fits) and keys[cut] == keys[cut - 1]:
+        cut += 1
     return [
         {
             "id": recipe["id"],
@@ -210,9 +346,8 @@ def runnable_for(goal: str, limit: int = 2) -> list[dict[str, Any]]:
             "run_command": run_command(recipe),
             "full_detail_command": f"mammoth how \"{recipe['goals'][0]}\"",
         }
-        for _, recipe in _rank(goal)
-        if recipe.get("run") and not recipe_hidden_embedded(recipe)
-    ][:limit]
+        for _, recipe in fits[:cut]
+    ]
 
 
 def _context(invocation: Invocation) -> dict[str, Any]:
@@ -312,11 +447,11 @@ def how(invocation: Invocation) -> HandlerResult:
     # weaker recipe that only shares a word with it; the parts it can do still are.
     best_unavailable = bool(ranked) and recipe_hidden_embedded(ranked[0][1])
     ranked = [item for item in ranked if not recipe_hidden_embedded(item[1])]
-    composed = [
-        part
-        for part in _compose(goal, ranked[0][1]["id"] if ranked else None)
-        if not recipe_hidden_embedded(part[1])
-    ]
+    tied = _tied(ranked)
+    composed, unresolved = _compose(goal, ranked[0][1]["id"] if ranked and not tied else None)
+    if unresolved:
+        # A part of the goal fits several recipes equally: the whole goal is not run on a guess.
+        return _unresolved_result(goal, composed, unresolved, context), {}
     if len(composed) >= 2 or (composed and not ranked):
         # A goal with several parts gets every part's steps, not only the best one's.
         return _composed_result(goal, composed, context), {}
@@ -327,9 +462,19 @@ def how(invocation: Invocation) -> HandlerResult:
             "context": context,
             "steps": [],
             "notes": [],
-            "alternatives": _alternatives(ranked),
+            "alternatives": _alternatives([r for _, r in ranked]),
             "hint": _NOT_HERE_HINT,
         }, {}
+    if tied:
+        return {
+            "goal": goal,
+            "matched": False,
+            "context": context,
+            "steps": [],
+            "notes": [],
+            "alternatives": _alternatives([r for _, r in tied]),
+            "hint": _TIED_HINT,
+        }, {}
     if not ranked:
         steps = _fallback_steps(goal, context)
         return {
@@ -349,7 +494,7 @@ def how(invocation: Invocation) -> HandlerResult:
         "context": context,
         "steps": _recipe_steps(best, context),
         "notes": list(best.get("notes", [])),
-        "alternatives": _alternatives(ranked[1:]),
+        "alternatives": _alternatives([r for _, r in ranked[1:]]),
     }
     if best.get("run"):
         # The steps as one command: an agent runs it instead of chaining them by hand.
@@ -358,11 +503,11 @@ def how(invocation: Invocation) -> HandlerResult:
     return result, {}
 
 
-def _alternatives(ranked: list[tuple[int, dict[str, Any]]]) -> list[dict[str, Any]]:
-    """The first few recipes of ``ranked``, each with the ``how`` command that shows it.
+def _alternatives(recipes: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """The first few ``recipes``, each with the ``how`` command that shows it.
 
     Args:
-        ranked: Recipes from :func:`_rank`, best first.
+        recipes: Recipes, best first.
 
     Returns:
         At most ``_MAX_ALTERNATIVES`` records of id, title and command.
@@ -373,7 +518,7 @@ def _alternatives(ranked: list[tuple[int, dict[str, Any]]]) -> list[dict[str, An
             "title": recipe["title"],
             "command": f'mammoth how "{recipe["goals"][0]}"',
         }
-        for _, recipe in ranked[:_MAX_ALTERNATIVES]
+        for recipe in recipes[:_MAX_ALTERNATIVES]
     ]
 
 
@@ -383,6 +528,31 @@ _SETUP_COMMANDS = frozenset(
 )
 
 
+def _unresolved_result(
+    goal: str,
+    composed: list[tuple[str, dict[str, Any]]],
+    unresolved: list[tuple[str, list[dict[str, Any]]]],
+    context: dict[str, Any],
+) -> dict[str, Any]:
+    """No match, with the clear parts of a several-part goal and the parts that are tied."""
+    return {
+        "goal": goal,
+        "matched": False,
+        "recipes": [
+            {"id": recipe["id"], "title": recipe["title"], "doc": recipe["doc"], "for": clause}
+            for clause, recipe in composed
+        ],
+        "unresolved": [
+            {"for": clause, "alternatives": _alternatives(fits)} for clause, fits in unresolved
+        ],
+        "context": context,
+        "steps": [],
+        "notes": [],
+        "alternatives": _alternatives([r for _, fits in unresolved for r in fits]),
+        "hint": _UNRESOLVED_HINT,
+    }
+
+
 def _composed_result(
     goal: str, composed: list[tuple[str, dict[str, Any]]], context: dict[str, Any]
 ) -> dict[str, Any]:

{mammoth_cli-2.3.0 → mammoth_cli-2.3.1}/mammoth_cli/commands/schema/find.py

@@ -212,26 +212,31 @@ _NO_MATCH_HINT_NO_SUGGESTIONS = (
 _TOKEN_RE = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*")
 
 
-def _tokens(value: str) -> frozenset[str]:
-    """Tokenize search text consistently across platforms and Python runs.
+def _ordered_tokens(value: str) -> tuple[str, ...]:
+    """The words of ``value`` in the order written, each once.
 
     A hyphenated word is kept whole and also split into its parts, so that
     ``date`` finds ``extract-date`` and ``date-diff`` as well as ``convert-type``'s
-    example text.
+    example text. The order is the text's, not a hash's: adjacent words make compounds.
     """
-    tokens: set[str] = set()
+    tokens: dict[str, None] = {}
     for token in _TOKEN_RE.findall(value.casefold()):
-        tokens.add(token)
+        tokens[token] = None
         if "-" in token:
-            tokens.update(token.split("-"))
-    return frozenset(tokens)
+            tokens.update(dict.fromkeys(token.split("-")))
+    return tuple(tokens)
+
+
+def _tokens(value: str) -> frozenset[str]:
+    """Tokenize search text consistently across platforms and Python runs."""
+    return frozenset(_ordered_tokens(value))
 
 
 def _query_tokens(query: str) -> tuple[str, ...]:
     # Bare numbers ("top 10") are values, not intent words.
     return tuple(
         token
-        for token in _tokens(query)
+        for token in _ordered_tokens(query)
         if token not in _DISCOVERY_STOPWORDS and not token.isdigit()
     )