mammoth-cli 2.0.70__tar.gz → 2.0.72__tar.gz

{mammoth_cli-2.0.70 → mammoth_cli-2.0.72}/PKG-INFO

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

{mammoth_cli-2.0.70 → mammoth_cli-2.0.72}/mammoth_cli/app.py

@@ -44,6 +44,7 @@ from mammoth_cli.output.policy import (
 from mammoth_cli.runtime import executor, validate
 from mammoth_cli.runtime.invocation import Invocation
 from mammoth_cli.runtime.strict import validate_extra_args
+from mammoth_cli.runtime.verify import with_verify
 from mammoth_cli.services.positionals import PositionalSpec, resolve_positionals
 
 OUTPUT_MODES = VALID_OUTPUTS
@@ -823,7 +824,8 @@ def _execute(invocation: Invocation) -> None:
             raise not_implemented_error(invocation.command_id, sdk_symbol)
         if invocation.dry_run:
             return _dry_run(handler, invocation)
-        return handler(invocation)
+        data, meta = handler(invocation)
+        return _apply_verify(invocation.command_id, data), meta
 
     executor.run(
         invocation.command_id,
@@ -835,6 +837,19 @@ def _execute(invocation: Invocation) -> None:
     )
 
 
+def _apply_verify(command_id: str, data: Any) -> Any:
+    """Add the automatic write read-back to a real, mutating, API-backed result.
+
+    A read command and a command with no reviewed ``sdk_symbol`` (a local or
+    not-yet-backed command) are returned unchanged; ``--dry-run`` never
+    reaches this at all, since it returns before the handler's real call.
+    """
+    record = command_by_id(command_id) or {}
+    if record.get("mutation_class") == "read" or not record.get("sdk_symbol"):
+        return data
+    return with_verify(data)
+
+
 def _dry_run(handler: Handler, invocation: Invocation) -> tuple[Any, dict[str, Any]]:
     """Run ``handler`` until its request would leave; report that request.
 

{mammoth_cli-2.0.70 → mammoth_cli-2.0.72}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mammoth-cli
-version: 2.0.70
+version: 2.0.72
 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."
 ---
 
@@ -81,7 +81,7 @@ mammoth view transform --help              # every data transformation
 | Change a column's type | `view transform convert-type` |
 | Rename a column, sort the rows (view settings, not tasks) | `view transform rename-columns`, `view transform sort` |
 | Rank, running total, previous row | `view transform window` |
-| A dashboard | `dashboard create-blank` ([dashboards](references/recipes/dashboards.md)) |
+| A dashboard | `dashboard v3 generate`, then `chat edit` ([dashboards](references/recipes/dashboards.md)) |
 | Deliver the rows | `view export csv`, `view export postgres` (and other destinations), `view export dataset` |
 | Run something on a schedule or on new data (refresh, append, alert) | `automation create`: a condition (`at_specific_time`, new file in a folder, ...) and tasks (`run_data_retrieval`, `append_data`, `send_an_alert`, `pull_cloud_files`). `schedule create` only pulls a connector's data. A dataset made from an uploaded file has no source to refresh from; say so. Full recipe, including a known `automation get` backend caveat: [recurring work](references/recipes/scheduling.md) |
 
@@ -122,11 +122,10 @@ dashboard from t_a and t_b"). Work it out from the data before you build:
 6. If the data has money, add it before you make the dashboard: `revenue`
    (`math`, `qty * price`, `new_column`), the `fix` in `before_dashboard`.
    A dashboard sees only the columns the view had when it was made.
-7. Build the dashboard from the joined view
-   ([dashboards](references/recipes/dashboards.md)) and chart the sum of
-   revenue. Do not sum a unit price. `create-blank`, `canvas save` and
-   `pages add` return `deliverable_check`: fix each warning, or say in the
-   report why not.
+7. Build the dashboard from the joined view with one sentence
+   ([dashboards](references/recipes/dashboards.md)) that charts the sum of
+   revenue. Do not sum a unit price. Fix each `deliverable_check` warning,
+   or say in the report why not.
 
 For the defaults that most pipelines use (new column or overwrite, `LEFT`
 joins, date steps), see

{mammoth_cli-2.0.70 → mammoth_cli-2.0.72}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/dashboards.md

@@ -2,18 +2,23 @@
 
 `dashboard create` (the legacy AI-generation engine) does not exist as a
 command: it has no handler in current apiv2 (always 404s; historically HTTP
-409 `4DASH012 DASHBOARD_LEGACY_CREATION_RETIRED`). Create with `create-blank`
-(or `v3 generate` when the task allows an AI route).
+409 `4DASH012 DASHBOARD_LEGACY_CREATION_RETIRED`). Build a board from one
+sentence with `v3 generate`, and change it with `chat edit`; author a canvas by
+hand (`create-blank`, `canvas save`, `pages add`) only when asked to.
 `dashboard source list` is an observed blocker on release (see
 capabilities); verify the view binding with `dashboard get DASHBOARD_ID`
 (`data.dataview_id`) instead.
 
 ```bash
-mammoth schema get dashboard.create-blank
-mammoth dashboard create-blank --input INPUT_JSON --project PROJECT_ID
+mammoth dashboard v3 generate --input '{"body": {"params": {"intent": "Monthly revenue by region, with top customers", "dataview_id": VIEW_ID}}}'
+mammoth dashboard chat edit DASHBOARD_ID --input '{"body": {"params": {"prompt": "Add a chart of orders by status"}}}'
 mammoth dashboard get DASHBOARD_ID
 ```
 
+`v3 generate` waits for the bake (about 30 s) and returns the baked canvas;
+`chat edit` returns `changed` and a one-line `message`. Quote one number from
+the board before you report it done.
+
 Discover page/widget/publish routes and verify the binding, draft/published
 data and terminal jobs. Use only returned IDs and schema confirmation policy;
 do not invent dashboard JSON or opaque task specs.

{mammoth_cli-2.0.70 → mammoth_cli-2.0.72}/mammoth_cli/commands/schema.py

@@ -281,6 +281,14 @@ _COMMAND_DISCOVERY_PURPOSES = {
         "url app post posts events rows straight in"
     ),
     "dataset.create-from-pdf": "pdf table document extract get the table out of into a dataset",
+    "dashboard.v3.generate": (
+        "create build make new generate dashboard board report from a view description "
+        "intent sentence ai combined showing"
+    ),
+    "dashboard.chat.edit": (
+        "add change edit update chart charts kpi to an existing dashboard board "
+        "by description sentence ai show instead"
+    ),
     "dashboard.pdf.export": "pdf of a board dashboard download print meeting export",
     "view.checkpoint.create": (
         "stop halt pause pipeline alert notify flag when rows match a rule condition checkpoint"

{mammoth_cli-2.0.70 → mammoth_cli-2.0.72}/mammoth_cli/commands/view_ops.py

@@ -25,6 +25,7 @@ from datetime import UTC, datetime, timedelta
 from typing import Any
 
 from mammoth_cli.commands.view import (
+    _DATAVIEW_GET_SYMBOL,
     _FIND_DATASET_SYMBOL,
     BRIEF_VIEW_FIELDS,
     _dataview_metadata,
@@ -245,6 +246,17 @@ def _meta(invocation: Invocation, workspace_id: int) -> dict[str, Any]:
     }
 
 
+def _view_row_count(service: Any, dataset_id: int, view_id: int, project_id: int | None) -> Any:
+    """Return a view's current row count via the cheapest read (best effort)."""
+    try:
+        info = service.call(
+            _DATAVIEW_GET_SYMBOL, dataset_id=dataset_id, dataview_id=view_id, project_id=project_id
+        )
+    except Exception:  # noqa: BLE001 -- the check is advice; the write already ran
+        return None
+    return info.get("row_count") if isinstance(info, dict) else None
+
+
 def _dispatch_view(
     invocation: Invocation,
     view_id: int,
@@ -262,7 +274,13 @@ def _dispatch_view(
     result to emit. ``prepare(service, dataset_id, kwargs)`` may edit the call
     arguments in place; when it returns a value, that value is emitted and no
     call is made. All three need the exact parent; without one they are skipped.
+
+    When neither ``before`` nor ``after`` is given (every plain transform),
+    the view's row count is read before and after the call and added to the
+    result as ``row_check``, so a caller always sees whether the write changed
+    the row count -- the join path builds its own richer ``join_check`` instead.
     """
+    auto_row_check = before is None and after is None
     # ``dataset_id`` is invocation-local resource context.  It is not a View
     # transform argument, but passing it through lets the service fetch the
     # exact parent endpoint and prevents the SDK's legacy bare-view resolver
@@ -287,6 +305,11 @@ def _dispatch_view(
             if early is not None:
                 return early, _meta(invocation, auth.workspace_id)
         state = before(service, int(dataset_id)) if before and dataset_id is not None else None
+        rows_before = (
+            _view_row_count(service, int(dataset_id), view_id, invocation.project)
+            if auto_row_check and dataset_id is not None
+            else None
+        )
         try:
             if dataset_id is None:
                 _require_discovery_allowed(invocation, view_id)
@@ -306,6 +329,9 @@ def _dispatch_view(
             )
         if after is not None and dataset_id is not None:
             data = after(service, int(dataset_id), state, data)
+        elif auto_row_check and dataset_id is not None and isinstance(data, dict):
+            rows_after = _view_row_count(service, int(dataset_id), view_id, invocation.project)
+            data["row_check"] = {"rows_before": rows_before, "rows_after": rows_after}
     return data, _meta(invocation, auth.workspace_id)
 
 

mammoth_cli-2.0.72/mammoth_cli/runtime/verify.py

@@ -0,0 +1,111 @@
+"""Automatic write read-back for every real, non-read API-backed command.
+
+A backend write returns whatever shape that particular endpoint returns —
+some carry ``has_error``, some a bare ``status``, some a pipeline job with its
+own nested ``status``. :func:`with_verify` reads those backend-specific
+signals once and adds one small, uniform ``verify`` block to the result, so
+the agent that issued the write always has an explicit answer to "did this do
+what it should" instead of re-deriving it per command.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+#: 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
+
+_FAILURE_STATUSES = frozenset({"error", "failed", "failure"})
+_FAILURE_PIPELINE_STATES = frozenset({"error", "ref_error"})
+
+
+def with_verify(data: Any) -> Any:
+    """Return ``data`` with a ``verify`` read-back block added.
+
+    ``data`` that is not a dict (a dry-run report, a bare list, ...) is
+    returned unchanged.
+    """
+    if not isinstance(data, dict):
+        return data
+    verified = _verified(data)
+    state = _state(data)
+    rows_before, rows_after = _row_counts(data)
+    verify: dict[str, Any] = {"verified": verified, "state": state}
+    if rows_before is not None or rows_after is not None:
+        verify["rows_before"] = rows_before
+        verify["rows_after"] = rows_after
+    verify["warnings"] = _warnings(data)
+    verify["needs_user"] = _needs_user(
+        data, verified=verified, state=state, rows_before=rows_before, rows_after=rows_after
+    )
+    return {**data, "verify": verify}
+
+
+def _job_status(data: dict[str, Any]) -> str | None:
+    job = data.get("job")
+    status = job.get("status") if isinstance(job, dict) else None
+    return status if isinstance(status, str) else None
+
+
+def _verified(data: dict[str, Any]) -> bool:
+    if data.get("has_error"):
+        return False
+    for status in (data.get("status"), _job_status(data)):
+        if isinstance(status, str) and status.lower() in _FAILURE_STATUSES:
+            return False
+    pipeline_state = data.get("pipeline_state")
+    if isinstance(pipeline_state, str) and pipeline_state.lower() in _FAILURE_PIPELINE_STATES:
+        return False
+    return data.get("bake_ok") is not False
+
+
+def _state(data: dict[str, Any]) -> str:
+    for key in ("pipeline_state", "status"):
+        value = data.get(key)
+        if value is not None:
+            return str(value)
+    return "done"
+
+
+def _row_counts(data: dict[str, Any]) -> tuple[int | None, int | None]:
+    for key in ("row_check", "join_check"):
+        check = data.get(key)
+        if isinstance(check, dict):
+            return check.get("rows_before"), check.get("rows_after")
+    return None, None
+
+
+def _warnings(data: dict[str, Any]) -> list[str]:
+    notes: list[str] = []
+    for key, value in data.items():
+        if not key.endswith("_check") or not isinstance(value, dict):
+            continue
+        for list_key in ("notes", "warnings"):
+            items = value.get(list_key)
+            if isinstance(items, list):
+                notes.extend(item if isinstance(item, str) else str(item) for item in items)
+    return notes
+
+
+def _needs_user(
+    data: dict[str, Any],
+    *,
+    verified: bool,
+    state: str,
+    rows_before: int | None,
+    rows_after: int | None,
+) -> str | None:
+    if not verified:
+        return f"The change failed: {state}."
+    if rows_after == 0 and isinstance(rows_before, int) and rows_before > 0:
+        return f"The change left the view with no rows (was {rows_before})."
+    join_check = data.get("join_check")
+    match_rate = join_check.get("match_rate") if isinstance(join_check, dict) else None
+    if isinstance(match_rate, (int, float)) and match_rate < JOIN_MATCH_RATE_THRESHOLD:
+        percent = round(match_rate * 100)
+        return (
+            f"Only {percent}% of rows found a match in the join; the user should "
+            "confirm before building on it."
+        )
+    return None

{mammoth_cli-2.0.70 → mammoth_cli-2.0.72}/pyproject.toml

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

{mammoth_cli-2.0.70 → mammoth_cli-2.0.72}/spec/manifests/commands/dashboard.yaml

@@ -490,7 +490,7 @@ commands:
   - CT-DASHBOARD-CHAT-EDIT-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: null
+  known_restrictions: 'Changes an existing board from one sentence (add, remove or change a chart, KPI or page): {"body": {"params": {"prompt": "<the change>"}}}; returns changed, a one-line message and the rebaked canvas. Use it rather than dashboard pages add or canvas save.'
   reviewed_by: primary
 - command_id: dashboard.chat.history
   command_path: dashboard chat history
@@ -749,7 +749,7 @@ commands:
   - CT-DASHBOARD-CREATE-BLANK-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: 'Input is {"params": {"dataview_id": VIEW_ID, "title": ...}} with --yes; returns {id, sequence}. The blank canvas has one page (p1) and no figures: author it with dashboard canvas get -> edit -> dashboard canvas save or dashboard pages add. One dataview per dashboard.'
+  known_restrictions: 'To build a board from a description, use dashboard v3 generate instead. Input is {"params": {"dataview_id": VIEW_ID, "title": ...}} with --yes; returns {id, sequence}. The blank canvas has one page (p1) and no figures: author it with dashboard chat edit, or by hand with dashboard canvas get -> edit -> dashboard canvas save or dashboard pages add. One dataview per dashboard.'
   reviewed_by: primary
 - command_id: dashboard.data.draft
   command_path: dashboard data draft
@@ -1673,7 +1673,7 @@ commands:
   - CT-DASHBOARD-PAGES-ADD-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: 'Requires --yes --confirm DASHBOARD_ID. body.params.pages is a list of PageAdd objects: {title, focus: {measure, dim, kpis: [...]}, charts: [{kind, title, dim, measure, agg}]}; the schema example''''s {} entry is not a usable page. The route runs through the LLM control guard: in the ILG simulation it dropped unit.prefix on a money card ("nothing in this data says which currency") that dashboard canvas save had kept, and reports that in data.message.'
+  known_restrictions: 'To add or change content by description, use dashboard chat edit instead. Requires --yes --confirm DASHBOARD_ID. body.params.pages is a list of PageAdd objects: {title, focus: {measure, dim, kpis: [...]}, charts: [{kind, title, dim, measure, agg}]}; the schema example''''s {} entry is not a usable page. The route runs through the LLM control guard: in the ILG simulation it dropped unit.prefix on a money card ("nothing in this data says which currency") that dashboard canvas save had kept, and reports that in data.message.'
   reviewed_by: primary
 - command_id: dashboard.pdf-artifact
   command_path: dashboard pdf-artifact
@@ -4397,7 +4397,7 @@ commands:
   - CT-DASHBOARD-V3-GENERATE-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: null
+  known_restrictions: 'This is how to make a dashboard: it builds and bakes a whole board from one sentence on one view. Input {"body": {"params": {"intent": "<what the board should show>", "dataview_id": VIEW_ID, "title": "<optional name>"}}}; waits (about 30 s) and returns the baked canvas. Change it afterwards with dashboard chat edit. dashboard create-blank is only for authoring a canvas by hand.'
   reviewed_by: primary
 - command_id: dashboard.video-state
   command_path: dashboard video-state