mammoth-cli 2.0.40__tar.gz → 2.0.41__tar.gz

{mammoth_cli-2.0.40 → mammoth_cli-2.0.41}/PKG-INFO

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

{mammoth_cli-2.0.40 → mammoth_cli-2.0.41}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mammoth-cli
-version: 2.0.40
+version: 2.0.41
 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."
 ---
 
@@ -93,10 +93,11 @@ report a real gap with the command you tried.
 Users often upload related files without saying how they relate ("make a
 dashboard from t_a and t_b"). Work it out from the data before you build:
 
-1. Upload every file, then read every view in Mammoth (not the local
-   files): `view get VIEW_ID` (columns, types, row count) and `view data get
-   VIEW_ID`. The data read lists `column_warnings`: numbers or dates stored
-   as text, and blanks, each with the fix.
+1. Upload every file. Each upload result carries a `view` preview of what
+   Mammoth made of the file (`view_id`, column types, sample rows,
+   `column_warnings`, and `before_dashboard`). Read every view in Mammoth, not
+   the local files: `view data get VIEW_ID` for each one. The warnings list
+   numbers or dates stored as text, and blanks, each with the fix.
 2. Find the keys. A column in one view whose values appear in a column of
    the other (`customer_id` and `id`, `order_ref` and `order_no`) is a
    foreign key; the view with many rows per key is the main one.
@@ -112,10 +113,14 @@ dashboard from t_a and t_b"). Work it out from the data before you build:
    result's `join_check` gives `match_rate`, `unmatched_rows` and
    `unmatched_keys`; put them in your report, and stop to compare the keys
    if more than a few rows found no match.
-6. Build the dashboard from the joined view
-   ([dashboards](references/recipes/dashboards.md)). If the data has money,
-   show it: add `revenue` (`math`, `qty * price`, `new_column`) and chart
-   its sum. Do not sum a unit price.
+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.
 
 For the defaults that most pipelines use (new column or overwrite, `LEFT`
 joins, date steps), see

{mammoth_cli-2.0.40 → mammoth_cli-2.0.41}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/dashboards.md

@@ -88,10 +88,19 @@ mammoth view transform math VIEW_ID --project PROJECT_ID \
   --input '{"dataset_id":DATASET_ID,"expression":"qty * price","new_column":"revenue"}'
 ```
 
+- Add every column the board needs before `create-blank`. A dashboard sees
+  only the columns the view had when the dashboard was made: `pages add`
+  refuses a later column ("isn't a measure in this data"). If you added it
+  after, make a new dashboard and delete the old one if you made it for this
+  task. The upload result's `before_dashboard` names the column to add.
 - Put revenue in a KPI (`focus.kpis`, `agg` `sum`, `unit.prefix` for the
   currency) and in one or more charts (revenue by product, by segment, by
   month). Rows with an empty price give an empty revenue. Say how many there
   are in your report.
+- `create-blank`, `canvas save` and `pages add` return `deliverable_check`:
+  `money_not_shown` (with the `math` command in `fix`), `unit_price_summed`,
+  and one `blank_values` entry for each column on the board that has blanks.
+  Fix each warning, or say in your report why you kept it.
 
 **Read the bindings back, then the numbers.** `dashboard canvas get` returns
 `data.meta.figures` — `"p1:kpi:2": {"descriptors": {"value": "<id>"}}` per

{mammoth_cli-2.0.40 → mammoth_cli-2.0.41}/mammoth_cli/commands/dashboard.py

@@ -16,6 +16,8 @@ from typing import Any
 from mammoth.models.dashboards import AddPagesSpec
 from pydantic import ValidationError
 
+from mammoth_cli.commands.view import view_profiles
+from mammoth_cli.context import profiles
 from mammoth_cli.errors.envelope import (
     CODE_INVALID_ARGUMENT,
     CODE_MISSING_ARGUMENT,
@@ -25,6 +27,7 @@ from mammoth_cli.errors.envelope import (
     CliError,
 )
 from mammoth_cli.manifest.loader import command_by_id
+from mammoth_cli.runtime import parents
 from mammoth_cli.runtime.confirm import (
     POLICY_CONFIRM_TARGET,
     POLICY_NONE,
@@ -33,10 +36,16 @@ from mammoth_cli.runtime.confirm import (
     enforce_confirmation,
 )
 from mammoth_cli.runtime.invocation import Invocation
-from mammoth_cli.runtime.session import open_service, require_project
+from mammoth_cli.runtime.session import open_service, require_project, resolved_project
 from mammoth_cli.services.argspec import arg_spec
 from mammoth_cli.services.command_contract import bind_command_inputs
 from mammoth_cli.services.dashboard_pages import check_added_pages
+from mammoth_cli.services.dashboard_review import (
+    CANVAS_GET,
+    NEW_COLUMN_NOTE,
+    has_profiles,
+    review,
+)
 from mammoth_cli.services.positionals import resolve_positionals
 
 HandlerResult = tuple[Any, dict[str, Any]]
@@ -675,9 +684,68 @@ def generated_dashboard(invocation: Invocation) -> HandlerResult:
         if invocation.command_id == "dashboard.pages.add" and "body" in kwargs:
             requested = kwargs["body"].get("params", {}).get("pages", [])
             data = check_added_pages(service, positionals["dashboard_id"], requested, data)
+        if invocation.command_id in _REVIEWED_COMMANDS:
+            data = _with_deliverable_check(invocation, service, auth, positionals, data)
     return data, _meta(invocation, auth.workspace_id)
 
 
+#: Authoring steps whose result carries ``deliverable_check``.
+_REVIEWED_COMMANDS = frozenset(
+    {"dashboard.create-blank", "dashboard.canvas.save", "dashboard.pages.add"}
+)
+
+
+def _with_deliverable_check(
+    invocation: Invocation, service: Any, auth: Any, positionals: dict[str, Any], data: Any
+) -> Any:
+    """Add ``deliverable_check`` (money shown? blanks decided?) to an authoring result.
+
+    One canvas read; advice only, so a failed read leaves the result as it was.
+    """
+    if hasattr(data, "model_dump"):
+        data = data.model_dump(mode="json")
+    if not isinstance(data, dict):
+        return data
+    dashboard_id = positionals.get("dashboard_id") or data.get("id")
+    if not isinstance(dashboard_id, int):
+        return data
+    try:
+        canvas_doc = service.call(CANVAS_GET, dashboard_id=dashboard_id)
+        if hasattr(canvas_doc, "model_dump"):
+            canvas_doc = canvas_doc.model_dump(mode="json")
+        source = (canvas_doc.get("canvas") or {}).get("dataset") or {}
+        view_id = source.get("dataview_id")
+        profile = invocation.profile or profiles.get_selected()
+        dataset_id = (
+            parents.lookup(profile, auth.workspace_id, view_id)
+            if isinstance(view_id, int)
+            else None
+        )
+        fallback = None
+        if not has_profiles(canvas_doc) and isinstance(view_id, int) and dataset_id is not None:
+            fallback = view_profiles(service, dataset_id, view_id, resolved_project(invocation))
+        warnings = review(canvas_doc, dataset_id, fallback)
+    except Exception:  # noqa: BLE001 -- advice must never fail the authoring step
+        return data
+    if warnings:
+        data = {
+            **data,
+            "deliverable_check": {
+                "warnings": warnings,
+                "note": (
+                    "Fix these before you report the dashboard as done, or say in your "
+                    "report why not."
+                    + (
+                        " " + NEW_COLUMN_NOTE
+                        if any("fix" in warning for warning in warnings)
+                        else ""
+                    )
+                ),
+            },
+        }
+    return data
+
+
 def dashboard_assess_twb(invocation: Invocation) -> HandlerResult:
     """Assess a local Tableau workbook through the SDK multipart seam."""
     file_path = _require_str_positional(invocation, "file")

{mammoth_cli-2.0.40 → mammoth_cli-2.0.41}/mammoth_cli/commands/file.py

@@ -15,6 +15,8 @@ from collections.abc import Callable
 from pathlib import Path
 from typing import Any
 
+from mammoth_cli.commands.view import upload_preview
+from mammoth_cli.context import profiles
 from mammoth_cli.errors.envelope import (
     CODE_INVALID_ARGUMENT,
     CODE_MISSING_ARGUMENT,
@@ -24,6 +26,7 @@ from mammoth_cli.errors.envelope import (
     CliError,
 )
 from mammoth_cli.manifest.loader import command_by_id
+from mammoth_cli.runtime import parents
 from mammoth_cli.runtime.confirm import (
     POLICY_CONFIRM_TARGET,
     POLICY_PROMPT_OR_YES,
@@ -226,6 +229,18 @@ def file_upload(invocation: Invocation) -> HandlerResult:
         # ambiguous date column lands in ``need_action`` with no view. Report
         # the status the platform holds for each dataset, not an assumed one.
         result = _upload_result(data, lambda dataset_id: _dataset_status(service, dataset_id))
+        project_id = resolved_project(invocation)
+        for entry in result["datasets"]:
+            if entry.get("status") != "ready":
+                continue
+            preview = upload_preview(service, int(entry["id"]), project_id)
+            if preview is not None:
+                entry["view"] = preview
+                parents.remember(
+                    invocation.profile or profiles.get_selected(),
+                    auth.workspace_id,
+                    {preview["view_id"]: int(entry["id"])},
+                )
     return result, _meta(invocation, auth.workspace_id, resolved_project(invocation))
 
 

{mammoth_cli-2.0.40 → mammoth_cli-2.0.41}/mammoth_cli/commands/view.py

@@ -46,6 +46,7 @@ from mammoth_cli.runtime.confirm import (
 from mammoth_cli.runtime.invocation import Invocation
 from mammoth_cli.runtime.session import open_service, require_project
 from mammoth_cli.services.conditions import CONDITION_KWARG, compile_condition
+from mammoth_cli.services.dashboard_review import UPLOAD_NOTE, upload_hints
 from mammoth_cli.services.data_quality import column_warnings
 
 HandlerResult = tuple[Any, dict[str, Any]]
@@ -2065,3 +2066,108 @@ def view_export_specialized(invocation: Invocation) -> HandlerResult:
             + (f" --project {int(target_project)}" if target_project is not None else ""),
         }
     return data, _meta(invocation, auth.workspace_id, project_id)
+
+
+_DATAVIEW_LIST_SYMBOL = "mammoth.api.dataviews.DataviewsAPI.list"
+#: Rows an upload shows of each new view (enough to see keys and formats).
+_UPLOAD_SAMPLE_ROWS = 3
+
+
+def upload_preview(service: Any, dataset_id: int, project_id: int | None) -> dict[str, Any] | None:
+    """The first view of a new dataset: columns, types, sample rows, warnings.
+
+    ``before_dashboard`` names the columns to add before any dashboard is
+    made (revenue from a unit price and a quantity), since a dashboard does
+    not see columns added after it.
+
+    An agent that has just uploaded files tends to read the local copies
+    instead of the data in Mammoth, and so misses what Mammoth made of them
+    (a price read as TEXT, blanks). The upload result carries the answer.
+    Best effort: any failure returns ``None`` and the upload result is
+    unchanged.
+    """
+    try:
+        listing = service.call(_DATAVIEW_LIST_SYMBOL, dataset_id=dataset_id, project_id=project_id)
+        views = listing.get("dataviews") if isinstance(listing, dict) else None
+        if not isinstance(views, list) or not views or not isinstance(views[0], dict):
+            return None
+        record = apply_column_renames(views[0])
+        view_id = record.get("id")
+        if not isinstance(view_id, int):
+            return None
+        mapping: dict[str, str] = {}
+        types: dict[str, str] = {}
+        for column in record.get(_METADATA_KEY) or []:
+            if not isinstance(column, dict):
+                continue
+            internal = column.get(_INTERNAL_NAME_KEY)
+            display = column.get(_DISPLAY_NAME_KEY)
+            if isinstance(internal, str) and isinstance(display, str):
+                mapping[internal] = display
+                types[display] = str(column.get("type") or "")
+        page = service.call(
+            _DATA_PAGE_SYMBOL, dataset_id=dataset_id, dataview_id=view_id, project_id=project_id
+        )
+        page = _relabel_columns(service, dataset_id, view_id, project_id, page, mapping)
+        rows = page.get(_ROWS_KEY) if isinstance(page, dict) else None
+        rows = [row for row in rows or [] if isinstance(row, dict)]
+    except Exception:  # noqa: BLE001 -- a preview must never fail the upload
+        return None
+    preview: dict[str, Any] = {
+        "view_id": view_id,
+        "row_count": record.get("row_count"),
+        "columns": types,
+        "sample_rows": rows[:_UPLOAD_SAMPLE_ROWS],
+    }
+    try:
+        warnings = column_warnings(rows, types, view_id) if rows else []
+    except Exception:  # noqa: BLE001
+        warnings = []
+    if warnings:
+        preview["column_warnings"] = warnings
+    try:
+        text_numbers = [
+            str(w.get("column"))
+            for w in warnings
+            if isinstance(w, dict) and w.get("issue") == "numbers_stored_as_text"
+        ]
+        hints = upload_hints(
+            view_id, record.get(_METADATA_KEY) or [], rows, dataset_id, text_numbers
+        )
+    except Exception:  # noqa: BLE001
+        hints = []
+    if hints:
+        preview["before_dashboard"] = {"warnings": hints, "note": UPLOAD_NOTE}
+    return preview
+
+
+def view_profiles(
+    service: Any, dataset_id: int, view_id: int, project_id: int | None
+) -> list[dict[str, Any]] | None:
+    """Column profile of a view (types and blank shares) for the dashboard check."""
+    from mammoth_cli.services.dashboard_review import profiles_from_view
+
+    try:
+        info = apply_column_renames(
+            service.call(
+                _DATAVIEW_GET_SYMBOL,
+                dataset_id=dataset_id,
+                dataview_id=view_id,
+                project_id=project_id,
+            )
+        )
+        metadata = [c for c in (info or {}).get(_METADATA_KEY) or [] if isinstance(c, dict)]
+        mapping = {
+            c[_INTERNAL_NAME_KEY]: c[_DISPLAY_NAME_KEY]
+            for c in metadata
+            if isinstance(c.get(_INTERNAL_NAME_KEY), str)
+            and isinstance(c.get(_DISPLAY_NAME_KEY), str)
+        }
+        page = service.call(
+            _DATA_PAGE_SYMBOL, dataset_id=dataset_id, dataview_id=view_id, project_id=project_id
+        )
+        page = _relabel_columns(service, dataset_id, view_id, project_id, page, mapping)
+        rows = page.get(_ROWS_KEY) if isinstance(page, dict) else None
+        return profiles_from_view(metadata, rows or [])
+    except Exception:  # noqa: BLE001 -- advice only
+        return None

{mammoth_cli-2.0.40 → mammoth_cli-2.0.41}/mammoth_cli/commands/view_ops.py

@@ -290,6 +290,11 @@ def _dispatch_view(
             reject_pipeline_reference_errors(service, view_id, dataset_id, response)
             raise
         reject_pipeline_reference_errors(service, view_id, dataset_id, data)
+        if dataset_id is not None:
+            # Later commands that know only the view (a dashboard's check) use it.
+            parents.remember(
+                _profile_name(invocation), auth.workspace_id, {view_id: int(dataset_id)}
+            )
         if after is not None and dataset_id is not None:
             data = after(service, int(dataset_id), state, data)
     return data, _meta(invocation, auth.workspace_id)
@@ -513,9 +518,12 @@ def view_get(invocation: Invocation) -> HandlerResult:
             "dataview_id": view_id,
             # Server-side projection; the brief set (plus the display
             # properties that carry column renames) unless the caller asks.
-            "fields": document.get("fields")
-            or ",".join(
-                [key for key in BRIEF_VIEW_FIELDS if key != "dataset_id"] + ["display_properties"]
+            "fields": (
+                document.get("fields")
+                or ",".join(
+                    [key for key in BRIEF_VIEW_FIELDS if key != "dataset_id"]
+                    + ["display_properties"]
+                )
             ),
         }
         with open_service(invocation) as (service, auth):

mammoth_cli-2.0.41/mammoth_cli/services/dashboard_review.py

@@ -0,0 +1,284 @@
+"""Check a dashboard against what its data holds, after each authoring step.
+
+The skill tells an agent to put the money on the board and to decide on
+blanks, but an agent that authors the canvas directly never reads that part
+(cold-agent eval, CLI 2.0.40: counts only, blanks undecided). The check runs
+where the agent already looks: the result of ``create-blank``, ``canvas
+save`` and ``pages add``. It uses the column profile the dashboard backend
+computes for the canvas (``plan.hints._profiles``), so it costs one read.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+CANVAS_GET = "mammoth.api.dashboards.DashboardsAPI.canvas_get"
+
+#: A dashboard reads the view as it was when the dashboard was made; a column
+#: added later is not a measure there (release, CLI 2.0.41: pages add refused
+#: ``revenue`` on a dashboard made before it, and ``swap-data`` did not always
+#: pick it up). A dashboard made after the column sees it.
+NEW_COLUMN_NOTE = (
+    "A dashboard sees only the columns the view had when the dashboard was made. "
+    "Run each fix first, then make a new dashboard (dashboard create-blank) and build "
+    "on that one; delete this one if you made it for this task."
+)
+#: The same fact, for the upload result, where no dashboard exists yet.
+UPLOAD_NOTE = (
+    "Run these before you make a dashboard: a dashboard sees only the columns "
+    "the view had when the dashboard was made."
+)
+
+_MONEY = re.compile(
+    r"price|amount|revenue|sales|cost|spend|fee|income|profit|margin|total|value|gmv|arr|mrr",
+    re.IGNORECASE,
+)
+_UNIT = re.compile(r"price|rate|unit|per[_ ]", re.IGNORECASE)
+_QUANTITY = re.compile(r"^(qty|quantity|units?|count|volume|pieces|items?)\b", re.IGNORECASE)
+_MEASURE_KEYS = ("measure", "measure2", "measure_x", "measure_y", "measure_size")
+_LIST_MEASURE_KEYS = ("measures", "extra_measures")
+
+
+def _profiles(canvas_doc: Mapping[str, Any]) -> list[dict[str, Any]]:
+    plan = canvas_doc.get("plan")
+    hints = plan.get("hints") if isinstance(plan, Mapping) else None
+    profiles = hints.get("_profiles") if isinstance(hints, Mapping) else None
+    return [p for p in profiles or [] if isinstance(p, dict) and isinstance(p.get("name"), str)]
+
+
+def _charts(canvas: Mapping[str, Any]) -> Iterable[tuple[Mapping[str, Any], Mapping[str, Any]]]:
+    """Yield ``(container, figure)`` for every authored figure and focus."""
+    containers = [canvas, *[p for p in canvas.get("pages") or [] if isinstance(p, Mapping)]]
+    for container in containers:
+        focus = container.get("focus")
+        if isinstance(focus, Mapping):
+            yield container, focus
+        for figure in container.get("added") or []:
+            if isinstance(figure, Mapping):
+                yield container, figure
+
+
+def _used(canvas: Mapping[str, Any]) -> tuple[set[str], set[str], list[tuple[str, str]]]:
+    """Measures and dimensions the board uses, and ``(measure, agg)`` pairs."""
+    derived = {
+        str(d.get("id")): [d.get("numerator"), d.get("denominator")]
+        for d in canvas.get("derived") or []
+        if isinstance(d, Mapping)
+    }
+    measures: set[str] = set()
+    dims: set[str] = set()
+    aggs: list[tuple[str, str]] = []
+
+    def add(name: Any, agg: Any) -> None:
+        if not isinstance(name, str):
+            return
+        for part in derived.get(name, [name]):
+            if isinstance(part, str):
+                measures.add(part)
+                aggs.append((part, str(agg or "sum").lower()))
+
+    for _, figure in _charts(canvas):
+        agg = figure.get("agg")
+        for key in _MEASURE_KEYS:
+            add(figure.get(key), agg)
+        for key in _LIST_MEASURE_KEYS:
+            for name in figure.get(key) or []:
+                add(name.get("field") if isinstance(name, Mapping) else name, agg)
+        for kpi in figure.get("kpis") or []:
+            if isinstance(kpi, Mapping):
+                add(kpi.get("field"), kpi.get("agg"))
+        for key in ("dim", "col_dim", "row_dim", "series", "date_field"):
+            if isinstance(figure.get(key), str):
+                dims.add(figure[key])
+    return measures, dims, aggs
+
+
+def _math_fix(view_id: Any, dataset_id: Any, quantity: str, price: str) -> str:
+    spec = json.dumps(
+        {
+            "dataset_id": dataset_id if dataset_id is not None else "DATASET_ID",
+            "expression": f"{quantity} * {price}",
+            "new_column": "revenue",
+        }
+    )
+    return f"mammoth view transform math {view_id} --input '{spec}'"
+
+
+def profiles_from_view(
+    metadata: Iterable[Mapping[str, Any]], rows: Iterable[Mapping[str, Any]]
+) -> list[dict[str, Any]]:
+    """A stand-in for ``plan.hints._profiles`` from view metadata and a data page.
+
+    A blank canvas has no profile until its first bake, so ``create-blank``
+    builds one: NUMERIC columns are measures, and ``nullRate`` is the share of
+    blank values in the rows given (display-name keyed).
+    """
+    materialised = [row for row in rows if isinstance(row, Mapping)]
+    profiles: list[dict[str, Any]] = []
+    for column in metadata:
+        name = column.get("display_name")
+        if not isinstance(name, str):
+            continue
+        kind = str(column.get("type") or "").upper()
+        profile: dict[str, Any] = {
+            "name": name,
+            "type": "measure" if kind == "NUMERIC" else "date" if kind == "DATE" else "dimension",
+        }
+        # Only rows that carry the column count; a column the page left out
+        # is unknown, not blank.
+        values = [row[name] for row in materialised if name in row]
+        blank = sum(1 for v in values if v is None or (isinstance(v, str) and not v.strip()))
+        if blank:
+            profile["nullRate"] = blank / len(values)
+        profiles.append(profile)
+    return profiles
+
+
+def review(
+    canvas_doc: Any,
+    dataset_id: int | None = None,
+    fallback_profiles: list[dict[str, Any]] | None = None,
+) -> list[dict[str, Any]]:
+    """Return warnings about money and blanks for a canvas read.
+
+    Args:
+        canvas_doc: A ``dashboard canvas get`` payload (``canvas``, ``plan``).
+        dataset_id: The view's parent dataset, for the suggested command.
+
+    Returns:
+        ``money_not_shown``, ``unit_price_summed`` and ``blank_values``
+        records (``issue``, ``detail``, optional ``fix``); empty when none.
+    """
+    if not isinstance(canvas_doc, Mapping):
+        return []
+    canvas = canvas_doc.get("canvas")
+    if not isinstance(canvas, Mapping):
+        return []
+    profiles = _profiles(canvas_doc) or list(fallback_profiles or [])
+    if not profiles:
+        return []
+    source = canvas.get("dataset")
+    view_id = source.get("dataview_id") if isinstance(source, Mapping) else None
+    view_ref = view_id if view_id is not None else "VIEW_ID"
+    measures, dims, aggs = _used(canvas)
+    numeric = [p for p in profiles if p.get("type") == "measure"]
+    unit_prices = [
+        p["name"]
+        for p in numeric
+        if p.get("perUnit") is True or (_UNIT.search(p["name"]) and _MONEY.search(p["name"]))
+    ]
+    money = [
+        p["name"] for p in numeric if _MONEY.search(p["name"]) and p["name"] not in unit_prices
+    ]
+    quantities = [
+        p["name"] for p in numeric if p.get("semantic") == "count" or _QUANTITY.search(p["name"])
+    ]
+    warnings: list[dict[str, Any]] = []
+    shows_money = any(name in measures for name in money + unit_prices)
+    if (money or unit_prices) and not shows_money:
+        if money:
+            detail = (
+                f"The view has money ({', '.join(money)}) but no chart or KPI shows it. "
+                f"Add a KPI and a chart with the sum of {money[0]}."
+            )
+            warnings.append({"issue": "money_not_shown", "detail": detail})
+        else:
+            record: dict[str, Any] = {
+                "issue": "money_not_shown",
+                "detail": (
+                    f"The view has a unit price ({', '.join(unit_prices)}) but no chart shows "
+                    "money. A unit price is not revenue: "
+                    + (
+                        f"add revenue = {quantities[0]} * {unit_prices[0]}, then chart its sum."
+                        if quantities
+                        else "chart revenue, not the sum of the price."
+                    )
+                ),
+            }
+            if quantities:
+                record["fix"] = _math_fix(view_ref, dataset_id, quantities[0], unit_prices[0])
+            warnings.append(record)
+    summed = sorted({name for name, agg in aggs if name in unit_prices and agg == "sum"})
+    if summed:
+        record = {
+            "issue": "unit_price_summed",
+            "detail": (
+                f"A chart sums the unit price {summed[0]}; that total means nothing. "
+                + (
+                    f"Chart the sum of revenue = {quantities[0]} * {summed[0]} instead."
+                    if quantities
+                    else "Use avg, or chart revenue instead."
+                )
+            ),
+        }
+        if quantities:
+            record["fix"] = _math_fix(view_ref, dataset_id, quantities[0], summed[0])
+        warnings.append(record)
+    shown = measures | dims
+    for profile in profiles:
+        name = profile["name"]
+        rate = profile.get("nullRate") or profile.get("emptyRate") or 0
+        if not isinstance(rate, (int, float)) or rate <= 0:
+            continue
+        if shown and name not in shown:
+            continue
+        warnings.append(
+            {
+                "issue": "blank_values",
+                "column": name,
+                "detail": (
+                    f"{round(rate * 100)}% of {name} is blank. Say in your report what you "
+                    "did: filled, filtered, or kept (and how the board shows them)."
+                ),
+            }
+        )
+    return warnings
+
+
+def upload_hints(
+    view_id: Any,
+    metadata: Iterable[Mapping[str, Any]],
+    rows: Iterable[Mapping[str, Any]],
+    dataset_id: Any = None,
+    text_numbers: Iterable[str] = (),
+) -> list[dict[str, Any]]:
+    """The money warnings for a new view, before any dashboard exists.
+
+    The fix is cheapest here: a column added before ``create-blank`` is on
+    the dashboard, one added after is not (``NEW_COLUMN_NOTE``).
+    ``text_numbers`` are the columns ``column_warnings`` found to be numbers
+    stored as text; they count as numbers here, and the warning says to
+    convert them first.
+    """
+    pending = set(text_numbers)
+    profiles = [
+        {**profile, "type": "measure"} if profile["name"] in pending else profile
+        for profile in profiles_from_view(metadata, rows)
+    ]
+    canvas_doc = {"canvas": {"dataset": {"dataview_id": view_id}}}
+    warnings = []
+    # Blanks are already in the upload's column_warnings.
+    for warning in review(canvas_doc, dataset_id, profiles):
+        if warning["issue"] == "blank_values":
+            continue
+        # No board exists yet: drop the "no chart shows it" clause.
+        detail = (
+            str(warning["detail"])
+            .replace(" but no chart shows money", "")
+            .replace(" but no chart or KPI shows it", "")
+        )
+        convert = sorted(name for name in pending if name in detail)
+        if convert:
+            detail = (
+                f"Convert {', '.join(convert)} to NUMERIC first (see column_warnings). " + detail
+            )
+        warnings.append({**warning, "detail": detail})
+    return warnings
+
+
+def has_profiles(canvas_doc: Any) -> bool:
+    """Whether a canvas read carries the backend's column profile."""
+    return isinstance(canvas_doc, Mapping) and bool(_profiles(canvas_doc))

{mammoth_cli-2.0.40 → mammoth_cli-2.0.41}/pyproject.toml

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