mammoth-cli 2.0.80__tar.gz → 2.0.82__tar.gz

{mammoth_cli-2.0.80 → mammoth_cli-2.0.82}/PKG-INFO

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

{mammoth_cli-2.0.80 → mammoth_cli-2.0.82}/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.80 → mammoth_cli-2.0.82}/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.80 → mammoth_cli-2.0.82}/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.80 → mammoth_cli-2.0.82}/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.80 → mammoth_cli-2.0.82}/mammoth_cli/services/data_quality.py

@@ -176,6 +176,58 @@ def _duplicate_rows_warning(
     return warning
 
 
+def _varying_numbers(rows: list[Mapping[str, Any]], column_types: Mapping[str, str]) -> list[str]:
+    """The NUMERIC columns whose non-blank values differ between rows: the row's figures."""
+    return [
+        column
+        for column, col_type in column_types.items()
+        if str(col_type).upper() == "NUMERIC"
+        and len({str(row.get(column)) for row in rows if not _blank(row.get(column))}) > 1
+    ]
+
+
+def _blank_values_warning(
+    column: str,
+    blanks: int,
+    total: int,
+    checked: int,
+    remove_fix: str | None,
+) -> dict[str, Any]:
+    """The ``blank_values`` record; *remove_fix* when a blank row holds no figure at all."""
+    detail = f"{blanks} of {total} rows are blank. "
+    if remove_fix is None:
+        detail += (
+            "Decide before you summarise: fill them (view transform set-values with "
+            "IS_EMPTY, or fill-missing), remove the rows (view transform filter), or "
+            "keep them and say so."
+        )
+        return {
+            "column": column,
+            "issue": "blank_values",
+            "detail": detail,
+            "rows_checked": checked,
+        }
+    detail += (
+        f"{column} is the only number that varies between rows, so these rows hold no "
+        "figure: removing them (fix) is the clean-up. Fill them only with a value the "
+        "user gave; keep them only when the user needs every row listed."
+    )
+    return {
+        "column": column,
+        "issue": "blank_values",
+        "detail": detail,
+        "fix": remove_fix,
+        "rows_checked": checked,
+    }
+
+
+def _remove_blank_rows_hint(view_id: int, dataset_id: int, column: str) -> str:
+    spec = json.dumps(
+        {"condition": {"column": column, "operator": "IS_NOT_EMPTY"}, "dataset_id": dataset_id}
+    )
+    return f"mammoth view transform filter {view_id} --input '{spec}'"
+
+
 def column_warnings(
     rows: Iterable[Mapping[str, Any]],
     column_types: Mapping[str, str],
@@ -204,6 +256,7 @@ def column_warnings(
         return []
     checked = len(materialised)
     warnings: list[dict[str, Any]] = []
+    figures = _varying_numbers(materialised, column_types)
     duplicate_warning = _duplicate_rows_warning(materialised, view_id, dataset_id)
     if duplicate_warning is not None:
         warnings.append(duplicate_warning)
@@ -254,17 +307,8 @@ def column_warnings(
             if variant_warning is not None:
                 warnings.append(variant_warning)
         if blanks:
-            warnings.append(
-                {
-                    "column": column,
-                    "issue": "blank_values",
-                    "detail": (
-                        f"{blanks} of {len(values)} rows are blank. Decide before you "
-                        "summarise: fill them (view transform set-values with "
-                        "IS_EMPTY, or fill-missing), remove the rows (view transform "
-                        "filter), or keep them and say so."
-                    ),
-                    "rows_checked": checked,
-                }
-            )
+            remove_fix = None
+            if figures == [column] and view_id is not None and dataset_id is not None:
+                remove_fix = _remove_blank_rows_hint(view_id, dataset_id, column)
+            warnings.append(_blank_values_warning(column, blanks, len(values), checked, remove_fix))
     return warnings

{mammoth_cli-2.0.80 → mammoth_cli-2.0.82}/pyproject.toml

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