mammoth-cli 2.0.79__tar.gz → 2.0.81__tar.gz

{mammoth_cli-2.0.79 → mammoth_cli-2.0.81}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.79
+Version: 2.0.81
 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.0.79 → mammoth_cli-2.0.81}/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.0.79"
+__version__ = "2.0.81"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.0.79 → mammoth_cli-2.0.81}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/connector.md

@@ -200,6 +200,8 @@ Example: `mammoth connector list`. Placeholders are illustrative; resolve IDs an
 
 Result: `ConnectorListResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
 
+`is_premium: true` with `is_added: false` means the connector must be enabled by Mammoth sales before this workspace can use it -- not that nobody has set it up yet. Such an item also carries `availability: "premium_not_enabled"` and an `availability_note` saying so. Tell the user why (premium, not enabled here) and offer to contact Mammoth sales; there is no CLI command that enables a premium connector or contacts sales on the user's behalf.
+
 Status on release: ran once on CLI 2.0.18 — fixture-lifecycle sweep 2026-09-19: exit 0 on release with CLI 2.0.18. Listed 42 available connectors (name_key, disp_name, api_type, is_added, is_premium). Single invocation only.
 
 ### `connector.query.generate`

{mammoth_cli-2.0.79 → mammoth_cli-2.0.81}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/scheduling.md

@@ -47,6 +47,43 @@ mammoth automation create 'Nightly refresh' --yes --input '{
 from an uploaded file or a URL (`weburl`) is a one-time copy with no source
 details to refresh from — say so rather than scheduling one.
 
+That is not the same as "this dataset can never be recurring." A
+file-backed dataset's pipeline re-runs on new data exactly like any other
+dataset's ([how Mammoth organises
+data](../about-mammoth.md#how-mammoth-organises-data)); the only difference
+is that nothing pulls the next file in for you — each new batch has to be
+uploaded with `append_to_ds_id` rather than fetched automatically. Once a
+new file lands that way, every view on that dataset recomputes over it
+automatically, so a monthly "email this view as CSV" delivery is buildable
+today, with no connector:
+
+```bash
+# each month, once the new file is ready (a person or an outside script runs this):
+mammoth file upload ./brand_spend_2026_10.csv --input '{"append_to_ds_id": DATASET_ID}'
+# one-time setup: the recurring delivery itself, via send_an_alert
+mammoth automation create 'Monthly brand spend to client' --yes --input '{
+  "tasks": [
+    {"task_type": "send_an_alert", "details": {
+      "alert_type": "email", "recipients": ["client@example.com"],
+      "subject": "Monthly brand spend report",
+      "attachments": {"dataview_ids": [VIEW_ID]}
+    }}
+  ],
+  "conditions": [
+    {"condition_type": "at_specific_time", "details": {
+      "frequency": "monthly", "interval": 1, "start_at": "2026-01-01T02:00:00Z"
+    }}
+  ]
+}'
+```
+
+`send_an_alert`'s CSV attachment is exported from the view's prepared rows
+at the moment the automation fires, not a copy taken at creation time (every
+output in Mammoth is computed from prepared data, never cached — see
+[about-mammoth.md](../about-mammoth.md)), so once this automation exists it
+delivers whatever the view currently holds each month; only the file-upload
+step above still needs to happen before each run.
+
 The other three task types take the shapes documented in `schema get
 automation.create` under `tasks[].details`:
 

{mammoth_cli-2.0.79 → mammoth_cli-2.0.81}/mammoth_cli/commands/connector.py

@@ -145,11 +145,51 @@ def connector_get(invocation: Invocation) -> HandlerResult:
     return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))
 
 
+#: ``availability`` a premium connector gets when it is not yet added to the
+#: workspace -- distinct from an ordinary connector nobody has added yet.
+_PREMIUM_NOT_ENABLED = "premium_not_enabled"
+
+
+_PREMIUM_NOT_ENABLED_NOTE = (
+    "Premium connector, not enabled in this workspace: Mammoth sales must enable"
+    " it before it can be connected. Tell the user so and offer to contact sales."
+)
+
+
+def _with_premium_availability(data: Any) -> Any:
+    """Mark each premium, not-yet-added connector with why it cannot be connected.
+
+    ``is_premium``/``is_added`` alone said a connector could not be connected
+    but never why: a premium connector must be enabled by Mammoth sales
+    before this workspace can use it, unlike an ordinary connector nobody has
+    added yet. Without this, an agent that reads ``connector list`` can route
+    a user to sales but never explain why (T2-WPP-W7). ``ConnectorsAPI.list``
+    returns a list, which stays a list.
+    """
+    if not isinstance(data, list):
+        return data
+    return [
+        (
+            {
+                **item,
+                "availability": _PREMIUM_NOT_ENABLED,
+                "availability_note": _PREMIUM_NOT_ENABLED_NOTE,
+            }
+            if isinstance(item, dict) and item.get("is_premium") and not item.get("is_added")
+            else item
+        )
+        for item in data
+    ]
+
+
 def connector_list(invocation: Invocation) -> HandlerResult:
     """List all available connectors (workspace-scoped, no project)."""
     with open_service(invocation) as (service, auth):
         data = service.call(_symbol(invocation))
-    return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))
+    return (
+        _with_premium_availability(data),
+        _meta(invocation, auth.workspace_id, resolved_project(invocation)),
+    )
 
 
 def connector_ai_chat(invocation: Invocation) -> HandlerResult:

{mammoth_cli-2.0.79 → mammoth_cli-2.0.81}/mammoth_cli/runtime/verify.py

@@ -10,15 +10,21 @@ what it should" instead of re-deriving it per command.
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import Any
 
-if TYPE_CHECKING:
-    from mammoth_cli.runtime.invocation import Invocation
+from mammoth_cli.runtime.invocation import Invocation
 
 #: Below this share of matched rows, a join has enough misses to flag before
 #: the caller builds anything further on it.
 JOIN_MATCH_RATE_THRESHOLD = 0.8
 
+#: The one ``mutation_class`` (see ``spec/manifests/commands/view.yaml``) a
+#: view write can carry that runs a pipeline -- the only kind that can leave a
+#: downstream export referencing something the write just changed or removed.
+_VIEW_PIPELINE_MUTATION_CLASS = "reversible_pipeline"
+
+_VIEW_EXPORT_LIST_COMMAND = "view.export.list"
+
 _FAILURE_STATUSES = frozenset({"error", "failed", "failure"})
 _FAILURE_PIPELINE_STATES = frozenset({"error", "ref_error"})
 
@@ -83,6 +89,7 @@ def with_verify(data: Any, invocation: Invocation | None = None) -> Any:
     verify["needs_user"] = _needs_user(
         data, verified=verified, rows_before=rows_before, rows_after=rows_after
     )
+    _apply_downstream_export_check(verify, invocation)
     return {**data, "verify": verify}
 
 
@@ -270,7 +277,10 @@ def _needs_user(
     ``needs_user`` means "a serious outcome the user must hear about before
     anything is built on it" -- never "something went wrong that you can
     retry". A failed write is reported through ``verified``/``reason``
-    instead (see :func:`_verify_and_reason`); it never sets this.
+    instead (see :func:`_verify_and_reason`); it never sets this -- except a
+    downstream export broken by this very write (see
+    :func:`_apply_downstream_export_check`), which is serious enough to set
+    both.
     """
     if not verified:
         return None
@@ -285,3 +295,135 @@ def _needs_user(
             "confirm before building on it."
         )
     return None
+
+
+# ---------------------------------------------------------------------------
+# A pipeline write can succeed on the view itself while leaving a saved
+# export broken -- its target_properties still reference a column the write
+# just deleted or renamed. The write's own response never carries that; only
+# a fresh read of the view's exports does (T2-WPP-W2: `view export dataset`
+# then `view transform delete-columns` left the export in error_info 7001,
+# but the delete's own verify said verified: true with no warnings).
+# ---------------------------------------------------------------------------
+
+
+def _apply_downstream_export_check(verify: dict[str, Any], invocation: Invocation | None) -> None:
+    """Flag a view-pipeline write that left one of its exports in error.
+
+    Runs at most once per write, and only when the write's own signals
+    already say a clean, settled success -- a write already reported
+    unverified for its own reason spends no extra read here.
+    """
+    if invocation is None or not verify["verified"] or verify["reason"] is not None:
+        return
+    view_id = _pipeline_view_id(invocation)
+    if view_id is None:
+        return
+    broken = _broken_downstream_exports(invocation, view_id)
+    if isinstance(broken, str):
+        verify["warnings"] = [*verify["warnings"], broken]
+        return
+    if not broken:
+        return
+    details = [_export_error_detail(item) for item in broken]
+    verify["verified"] = False
+    verify["reason"] = "a saved export on this view is in error: " + "; ".join(details)
+    verify["warnings"] = [*verify["warnings"], *details]
+    verify["needs_user"] = (
+        "A saved export on this view is in error after this change; its data will "
+        "not reach its destination until this is fixed: " + "; ".join(details)
+    )
+
+
+def _pipeline_view_id(invocation: Invocation) -> int | None:
+    """The view id a ``reversible_pipeline`` write acted on, or None otherwise."""
+    from mammoth_cli.manifest.loader import command_by_id
+
+    record = command_by_id(invocation.command_id) or {}
+    if record.get("mutation_class") != _VIEW_PIPELINE_MUTATION_CLASS:
+        return None
+    for name in ("view_id", "dataview_id"):
+        value = invocation.positional(name)
+        if isinstance(value, bool):
+            continue
+        if isinstance(value, int):
+            return value
+        if isinstance(value, str) and value.strip().lstrip("-").isdigit():
+            return int(value)
+    return None
+
+
+def _broken_downstream_exports(invocation: Invocation, view_id: int) -> list[dict[str, Any]] | str:
+    """Exports on ``view_id`` now in error, read via the existing ``view.export.list``.
+
+    Each export the backend hands back already carries its own ``error_info``
+    when it can no longer run (see ``mammoth.models.exports.ItemExportInfo``);
+    this is the one read that surfaces it. A read that itself fails returns
+    the warning to show instead: it must not hide the write's own,
+    already-settled success, nor pass silently.
+    """
+    from mammoth_cli.commands.registry import HANDLERS
+
+    handler = HANDLERS.get(_VIEW_EXPORT_LIST_COMMAND)
+    if handler is None:
+        return []
+    read_invocation = Invocation(
+        command_id=_VIEW_EXPORT_LIST_COMMAND,
+        output="json",
+        profile=invocation.profile,
+        project=invocation.project,
+        timeout=invocation.timeout,
+        job_timeout=invocation.job_timeout,
+        pipeline_timeout=invocation.pipeline_timeout,
+        no_input=True,
+        positionals={"dataview_id": view_id},
+        extra_args=[str(view_id)],
+    )
+    try:
+        read_data, _meta = handler(read_invocation)
+    except Exception as exc:  # noqa: BLE001 -- the write already succeeded
+        return f"could not check this view's saved exports: {exc}"
+    exports = read_data.get("exports") if isinstance(read_data, dict) else None
+    if not isinstance(exports, list):
+        return []
+    return [item for item in exports if isinstance(item, dict) and item.get("error_info")]
+
+
+def _export_error_detail(item: dict[str, Any]) -> str:
+    """Human-readable ``"export <id> (<handler>): ..."`` line for one broken export."""
+    error_info = item.get("error_info")
+    error_info = error_info if isinstance(error_info, dict) else {}
+    # the backend nests the details: error_info.additional_info.{error_code,
+    # reference_errors} (live `view export get`, T2-WPP-W2)
+    nested = error_info.get("additional_info")
+    error_info = {**error_info, **nested} if isinstance(nested, dict) else error_info
+    what = f"export {item.get('id')}"
+    handler_type = item.get("handler_type")
+    if handler_type:
+        what += f" ({handler_type})"
+    error_code = error_info.get("error_code")
+    detail = f"error {error_code}" if error_code is not None else "an error"
+    columns = _export_error_columns(error_info)
+    if columns:
+        detail += f", column(s) {', '.join(columns)}"
+    return f"{what} is in error: {detail}"
+
+
+def _export_error_columns(error_info: dict[str, Any]) -> list[str]:
+    """Column display names named by an export's ``error_info.reference_errors``."""
+    reference_errors = error_info.get("reference_errors")
+    if isinstance(reference_errors, dict):
+        entries = reference_errors.get("reference_errors") or []
+    elif isinstance(reference_errors, list):
+        entries = reference_errors
+    else:
+        entries = []
+    names: list[str] = []
+    for entry in entries:
+        if not isinstance(entry, dict):
+            continue
+        column = entry.get("column")
+        name = column.get("display_name") if isinstance(column, dict) else column
+        if isinstance(name, str):
+            names.append(name)
+    return names

{mammoth_cli-2.0.79 → mammoth_cli-2.0.81}/mammoth_cli/services/data_quality.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import json
 import re
+from collections import Counter
 from collections.abc import Iterable, Mapping
 from datetime import datetime
 from typing import Any
@@ -20,8 +21,14 @@ _MOSTLY = 0.8
 #: Fewer non-blank values than this are too few to call a pattern.
 _MIN_VALUES = 3
 _MAX_EXAMPLES = 3
+#: Most groups of variant spellings to name in one warning.
+_MAX_VARIANT_GROUPS = 5
 
 _NUMBER = re.compile(r"^[-+]?[$€£]?\s*\d[\d,]*(\.\d+)?\s*%?$|^[-+]?[$€£]?\s*\.\d+\s*%?$")
+#: Punctuation is normalised to a space, not dropped, so "Pepsi,Cola" and
+#: "Pepsi Cola" collapse the same way as "Pepsi Cola" itself.
+_PUNCTUATION = re.compile(r"[^\w\s]", re.UNICODE)
+_WHITESPACE = re.compile(r"\s+")
 _DATE_FORMATS = (
     "%Y-%m-%d",
     "%Y/%m/%d",
@@ -61,6 +68,82 @@ def _convert_hint(view_id: int | None, column: str, to: str) -> str:
     return f"mammoth view transform convert-type {target} --input '{spec}'"
 
 
+def _bulk_replace_hint(view_id: int | None, column: str, mapping: list[dict[str, Any]]) -> str:
+    target = str(view_id) if view_id is not None else "VIEW_ID"
+    spec = json.dumps({"columns": [column], "mapping": mapping})
+    return f"mammoth view transform bulk-replace {target} --input '{spec}'"
+
+
+def _spelling_key(text: str) -> str:
+    """Case-, whitespace- and punctuation-insensitive grouping key.
+
+    Punctuation is replaced with a space (not dropped) before whitespace is
+    collapsed, so inner punctuation ("Pepsi, Co.") normalises the same way
+    as a plain space ("Pepsi Co"). This is normalisation, not fuzzy
+    matching: different words ("pepsi cola") get a different key than
+    ("pepsi") and are never grouped.
+    """
+    despaced = _WHITESPACE.sub(" ", _PUNCTUATION.sub(" ", text))
+    return despaced.strip().lower()
+
+
+def _variant_spelling_groups(texts: list[str]) -> list[tuple[str, list[str]]]:
+    """Group distinct values that share a spelling key, keys sorted for stable output.
+
+    Only keys with more than one distinct raw value are a "group" worth
+    reporting; a single spelling of a value is not a finding.
+    """
+    by_key: dict[str, list[str]] = {}
+    for text in dict.fromkeys(texts):  # distinct values, first-seen order
+        key = _spelling_key(text)
+        if not key:
+            continue
+        by_key.setdefault(key, []).append(text)
+    groups = [(key, values) for key, values in by_key.items() if len(values) > 1]
+    return sorted(groups, key=lambda item: item[0])
+
+
+def _most_used_spelling(values: list[str], counts: Counter[str]) -> str:
+    """The group's most frequent real spelling (first seen on a tie), trimmed.
+
+    Never a synthesised form such as ``str.title()``, which would rewrite
+    "McDonald's" as "Mcdonald'S".
+    """
+    return max(values, key=lambda value: counts[value]).strip()
+
+
+def _variant_spellings_warning(
+    column: str,
+    texts: list[str],
+    view_id: int | None,
+    checked: int,
+) -> dict[str, Any] | None:
+    groups = _variant_spelling_groups(texts)
+    if not groups:
+        return None
+    shown = groups[:_MAX_VARIANT_GROUPS]
+    counts = Counter(texts)
+    canonical = {key: _most_used_spelling(values, counts) for key, values in shown}
+    mapping = [{"search": sorted(values), "replace": canonical[key]} for key, values in shown]
+    examples = "; ".join(
+        "{" + ", ".join(repr(v) for v in sorted(values)) + "}" + f" -> {canonical[key]!r}"
+        for key, values in shown
+    )
+    detail = (
+        f"{len(groups)} group(s) of values in this TEXT column differ only in case, "
+        f"whitespace or punctuation and will be counted separately unless unified: {examples}."
+    )
+    if len(groups) > _MAX_VARIANT_GROUPS:
+        detail += f" ({len(groups) - _MAX_VARIANT_GROUPS} more not shown)."
+    return {
+        "column": column,
+        "issue": "variant_spellings",
+        "detail": detail,
+        "fix": _bulk_replace_hint(view_id, column, mapping),
+        "rows_checked": checked,
+    }
+
+
 def _duplicate_rows_warning(
     rows: list[Mapping[str, Any]],
     view_id: int | None,
@@ -111,9 +194,10 @@ def column_warnings(
     Returns:
         One record per finding: ``column``, ``issue``
         (``numbers_stored_as_text``, ``dates_stored_as_text``,
-        ``blank_values`` or the table-level ``duplicate_rows``), ``detail``
-        and, where one command fixes it, ``fix``. Counts are over the rows
-        given (``rows_checked`` on each record).
+        ``variant_spellings``, ``blank_values`` or the table-level
+        ``duplicate_rows``), ``detail`` and, where one command fixes it,
+        ``fix``. Counts are over the rows given (``rows_checked`` on each
+        record).
     """
     materialised = [row for row in rows if isinstance(row, Mapping)]
     if not materialised:
@@ -166,6 +250,9 @@ def column_warnings(
                     }
                 )
                 break
+            variant_warning = _variant_spellings_warning(column, texts, view_id, checked)
+            if variant_warning is not None:
+                warnings.append(variant_warning)
         if blanks:
             warnings.append(
                 {

{mammoth_cli-2.0.79 → mammoth_cli-2.0.81}/mammoth_cli/services/sdk_service.py

@@ -489,6 +489,7 @@ class SdkMammothService:
         local_columns = getattr(view, "columns", {}) or {}
         local_internal = {value for value in local_columns.values() if isinstance(value, str)}
         local_display = set(local_columns)
+        local_types = getattr(view, "column_types", {}) or {}
 
         def check(value: Any, *, scope: str, columns: dict[str, str], display: set[str]) -> None:
             internal = {item for item in columns.values() if isinstance(item, str)}
@@ -583,6 +584,8 @@ class SdkMammothService:
                     columns=local_columns,
                     display=local_display,
                 )
+                if not spec.get("value_is_column") and "value" in spec:
+                    SdkMammothService._coerce_numeric_condition_value(spec, local_types)
             if spec.get("value_is_column") and "value" in spec:
                 check(
                     spec["value"],
@@ -639,6 +642,54 @@ class SdkMammothService:
                 display=foreign_display,
             )
 
+    @staticmethod
+    def _coerce_numeric_condition_value(spec: dict[str, Any], column_types: dict[str, str]) -> None:
+        """Convert a numeric-string condition value against a NUMERIC column.
+
+        The backend accepts a filter/set-values/pivot condition whose value is
+        a string even when the column is NUMERIC, then puts the whole pipeline
+        into ref_error (7003 "type mismatch") on the next read. The CLI already
+        knows the column's type, so it converts what it can and fails locally,
+        before any request, for what it can't. DATE columns are left as is.
+        """
+        column = spec.get("column")
+        if not isinstance(column, str) or column_types.get(column) != "NUMERIC":
+            return
+
+        def convert(item: Any) -> Any:
+            if not isinstance(item, str):
+                return item
+            try:
+                return int(item)
+            except ValueError:
+                pass
+            try:
+                number = float(item)
+            except ValueError:
+                raise SdkMammothService._condition_value_type_error(
+                    column, "NUMERIC", item
+                ) from None
+            return int(number) if number.is_integer() else number
+
+        value = spec["value"]
+        spec["value"] = (
+            [convert(item) for item in value] if isinstance(value, list) else convert(value)
+        )
+
+    @staticmethod
+    def _condition_value_type_error(column: str, column_type: str, value: str) -> CliError:
+        """Build a stable pre-mutation condition-value type error."""
+        return CliError(
+            code="invalid_condition_value",
+            message=(
+                f"Condition value {value!r} for column '{column}' ({column_type}) "
+                "is not a valid number."
+            ),
+            exit_status=EXIT_USAGE,
+            hint="Use a numeric value for a NUMERIC column.",
+            details={"column": column, "column_type": column_type, "value": value},
+        )
+
     @staticmethod
     def column_input_error(
         reference: str,

{mammoth_cli-2.0.79 → mammoth_cli-2.0.81}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mammoth-cli"
-version = "2.0.79"
+version = "2.0.81"
 description = "Command-line interface for the Mammoth Analytics platform"
 authors = [{name = "Mammoth Analytics", email = "support@mammoth.io"}]
 readme = "README.md"