mammoth-cli 2.0.38__tar.gz → 2.0.39__tar.gz

{mammoth_cli-2.0.38 → mammoth_cli-2.0.39}/PKG-INFO

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

{mammoth_cli-2.0.38 → mammoth_cli-2.0.39}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mammoth-cli
-version: 2.0.38
+version: 2.0.39
 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,21 +93,29 @@ 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. Read every view first: `view get VIEW_ID` (columns, types, row count) and
-   `view data get VIEW_ID --input '{"limit": 20}'`.
+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.
 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.
 3. Make the keys match before the join: same type (`convert-type`), same
    case and padding (`text`), no blanks (`set-values`, `filter`).
-4. Fix what the deliverable needs: numbers stored as text (`convert-type`
-   to `NUMERIC`), dates stored as text (`convert-type` to `DATE`), blanks.
-5. `view transform join` the lookup view into the main view (`LEFT`), then
-   read back and check the match rate
-   ([worked example](references/recipes/end-to-end.md), step 5).
+4. Act on every `column_warnings` entry for a column the deliverable uses:
+   run its `fix` (`convert-type` to `NUMERIC` or `DATE`; the values that are
+   not numbers become empty), then decide on blanks (fill, filter, or keep and
+   say so). A text `price` cannot be summed on a dashboard.
+5. `view transform join` the lookup view into the main view (`LEFT`). The
+   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)).
 
+For the defaults that most pipelines use (new column or overwrite, `LEFT`
+joins, date steps), see
+[transforms](references/recipes/transforms.md#what-most-pipelines-look-like).
 Say what you inferred (which columns you joined on, what you converted) in
 your report. If no column links the files, ask before you combine them.
 
@@ -149,6 +157,10 @@ your report. If no column links the files, ask before you combine them.
   target column *before* the change so the after-read has a comparison.
 - A uniform result (every amount 0, every region "Unknown", most join rows
   unmatched) means the previous step went wrong; stop and re-inspect it.
+- `column_warnings` on a data read and `join_check` on a join are findings,
+  not decoration: fix each one the deliverable depends on, or say in the
+  report why you kept it. `view data get` pages with `{"offset": 51,
+  "limit": 50}`.
 - A timeout, exit 7 or interruption does not prove failure; reconcile an
   `outcome_unknown` (`job get`, `view task list`) before replaying.
 - Run the [report checklist](references/report-checklist.md) before stating

{mammoth_cli-2.0.38 → mammoth_cli-2.0.39}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/end-to-end.md

@@ -22,6 +22,8 @@ mammoth view list CUSTOMERS_DS --project PROJECT_ID # -> CUSTOMERS_VIEW
 # 2. look before you change: column names, types, row_count, a sample
 mammoth view get ORDERS_VIEW ORDERS_DS --project PROJECT_ID
 mammoth view data get ORDERS_VIEW ORDERS_DS --project PROJECT_ID
+#   data.column_warnings: text columns of numbers/dates (with the convert-type fix) and blanks;
+#   plan step 3 from them
 
 # 3. clean orders (each call waits for its job; read back after each value change)
 mammoth view transform discard-duplicates ORDERS_VIEW --project PROJECT_ID \
@@ -43,9 +45,10 @@ mammoth view get ORDERS_VIEW ORDERS_DS --project PROJECT_ID   # row_count before
 # 5. join, then check the match rate before building on it
 mammoth view transform join ORDERS_VIEW --project PROJECT_ID \
   --input '{"dataset_id": ORDERS_DS, "foreign_view": CUSTOMERS_VIEW, "foreign_dataset_id": CUSTOMERS_DS, "join_type": "LEFT", "on": [{"left": "customer_id", "right": "customer_id"}], "select": ["region"]}'
-mammoth view data get ORDERS_VIEW ORDERS_DS --project PROJECT_ID
-#   if region is empty/"Unknown" on most rows, the key does not match: compare the two key columns' values
+#   data.join_check: rows_before/rows_after, match_rate, unmatched_rows, unmatched_keys; report them
+#   if many rows are unmatched, the key does not match: compare the two key columns' values
 #   (type, padding, case) with view data get on both views; do not summarise unmatched data
+#   rows_after > rows_before: a key repeats in the other view (use lookup for one value per key)
 
 # 6. deliverable first: export the cleaned, joined rows before any step that replaces them
 mammoth view export csv ORDERS_VIEW --project PROJECT_ID \

{mammoth_cli-2.0.38 → mammoth_cli-2.0.39}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/transforms.md

@@ -73,6 +73,41 @@ mammoth schema get view.transform.join
 mammoth view transform join VIEW_ID --project PROJECT_ID --input INPUT_JSON
 ```
 
+## What most pipelines look like
+
+These patterns come from how Mammoth pipelines are usually built. Use them
+as defaults, and let the user's request override them:
+
+- Keep it short. Most pipelines have one to three steps and touch a few
+  columns. Add only the steps the deliverable needs.
+- New column or overwrite? `set-values`, `math` and `lookup` take
+  `new_column` (add a column) or `existing_column` (replace the values in
+  place), never both. Overwriting is as common as adding. If the user said
+  "fix", "clean" or "change" a column, use `existing_column`. If they said
+  "add", "calculate" or "flag", use `new_column`. If it is not clear, ask.
+- Joins are nearly always `LEFT` on one key column. Use `INNER`, `RIGHT`,
+  `OUTER` or a key of two or more columns only when the user asks for it or
+  the data needs it, and say why in your report.
+- Check the key before a join or lookup. Most keys go in without a prep
+  step, so a type, case or padding difference shows up as unmatched rows. Read
+  both key columns first (`view data get`) and act on `join_check`.
+- Date steps (`increment-date`, `extract-date`, and `text` on date columns)
+  fail more often than other steps. Before a date step, confirm that the
+  column type is `DATE` (`view get`); if it is `TEXT`, run `convert-type`
+  first. Check the result on a few rows.
+- Convert several columns to the same type in one `convert-type` call (one
+  `conversions` entry for each column), not one call for each column.
+- Remove duplicates near the end, after the cleanup and joins, so the check
+  uses the final columns.
+- `filter` also takes a plain-language `prompt` instead of a `condition`.
+  Use a `condition` when the rule is exact (a column, an operator, a value).
+  Use `prompt` only when the user described the rule in words and no exact
+  condition expresses it, then check the kept rows.
+- "Top N" means the largest values first. Use the smallest values first only
+  when the user says "bottom", "lowest" or "smallest".
+- The last step of a pipeline is not a signal that it is finished. Say that
+  the work is done only after you verify the deliverable.
+
 ## Aggregate or summarise
 
 For a grouped summary (totals per region, counts per status) use the typed

{mammoth_cli-2.0.38 → mammoth_cli-2.0.39}/mammoth_cli/bundled_skill/mammoth-cli/references/task-start.md

@@ -9,11 +9,13 @@ or secrets in an argument, prompt, transcript, or checkpoint.
    from PyPI into a fresh environment and verify it:
 
    ```bash
-   python3 -m venv .mammoth && .mammoth/bin/python -m pip install --upgrade mammoth-cli
+   python3 -m venv .mammoth && .mammoth/bin/python -m pip install --no-cache-dir --upgrade mammoth-cli
    .mammoth/bin/mammoth --version      # or: uv tool install mammoth-cli
    ```
 
-   Pin `mammoth-cli==X.Y.Z` when the task names an approved release. Use the
+   Pin `mammoth-cli==X.Y.Z` when the task names an approved release, and
+   check that `mammoth --version` prints it (a pip cache can serve an older
+   release for a few minutes after a new one is published). Use the
    host installer script (`installers/mammoth-install.sh` in the repository)
    only when the operator names it; do not pipe a remote script to a shell on
    your own initiative. The SDK (`mammoth-io`) comes with the CLI. If a later

{mammoth_cli-2.0.38 → mammoth_cli-2.0.39}/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.data_quality import column_warnings
 
 HandlerResult = tuple[Any, dict[str, Any]]
 
@@ -424,7 +425,7 @@ def _compile_query_filters(
     project_id: int | None,
     document: dict[str, Any],
     kwargs: dict[str, Any],
-) -> dict[str, str] | None:
+) -> tuple[dict[str, str] | None, dict[str, str] | None]:
     """Translate a data query's ``condition`` and ``columns`` to the wire format.
 
     The data route takes the backend condition shape (``{internal: {OP: ...}}``,
@@ -433,11 +434,11 @@ def _compile_query_filters(
     only have one key". The spec is compiled through the shared condition
     service and built against the view's display -> internal name and type
     maps, and ``columns`` given as display names are mapped the same way.
-    Returns the internal -> display map when metadata was fetched, so the row
-    relabelling can reuse it.
+    Returns the internal -> display map and the display -> type map when
+    metadata was fetched, so the row relabelling and checks can reuse them.
     """
     if CONDITION_KWARG not in document and "columns" not in document:
-        return None
+        return None, None
     metadata = _dataview_metadata(service, dataset_id, dataview_id, project_id)
     column_map: dict[str, str] = {}
     column_types: dict[str, str] = {}
@@ -454,7 +455,9 @@ def _compile_query_filters(
     columns = document.get("columns")
     if isinstance(columns, list):
         kwargs["columns"] = [column_map.get(c, c) if isinstance(c, str) else c for c in columns]
-    return {internal: display for display, internal in column_map.items()} if metadata else None
+    if not metadata:
+        return None, None
+    return {internal: display for display, internal in column_map.items()}, column_types
 
 
 def _relabel_columns(
@@ -610,11 +613,14 @@ def view_data_get(invocation: Invocation) -> HandlerResult:
     """Fetch a dataview's data, waiting for the backing job to complete.
 
     The dataset is resolved from the view unless given as a trailing positional
-    or a ``dataset_id`` --input field.
+    or a ``dataset_id`` --input field. ``offset`` (1-based) reads a later page
+    through the query route. The result carries ``column_warnings`` when the
+    rows show a text column of numbers or dates, or blanks.
     """
     project_id = require_project(invocation)
     view_id = _require_int_positional_at(invocation, 0, "view id")
     document = invocation.load_input() or {}
+    limit = document.get("limit", _DATA_GET_DEFAULT_LIMIT)
     with open_service(invocation) as (service, auth):
         dataset_id = _resolve_dataset_id(service, invocation, view_id, document)
         kwargs: dict[str, Any] = {
@@ -622,12 +628,165 @@ def view_data_get(invocation: Invocation) -> HandlerResult:
             "dataview_id": view_id,
             "project_id": project_id,
         }
-        _forward_optional(document, kwargs, ("timeout", "poll_interval", "sequence"))
-        data = service.call(_symbol(invocation), **kwargs)
-        data = _relabel_columns(service, dataset_id, view_id, project_id, data)
-    return _trim_rows(data, document.get("limit", _DATA_GET_DEFAULT_LIMIT)), _meta(
-        invocation, auth.workspace_id, project_id
-    )
+        if document.get("offset") is not None:
+            kwargs["offset"] = int(document["offset"])
+            kwargs["limit"] = int(limit) if int(limit) > 0 else 400
+            _forward_optional(document, kwargs, ("sequence",))
+            data = service.call(_QUERY_DATA_SYMBOL, **kwargs)
+        else:
+            _forward_optional(document, kwargs, ("timeout", "poll_interval", "sequence"))
+            data = service.call(_symbol(invocation), **kwargs)
+        data = _relabel_and_check(service, dataset_id, view_id, project_id, data)
+    return _trim_rows(data, limit), _meta(invocation, auth.workspace_id, project_id)
+
+
+_QUERY_DATA_SYMBOL = "mammoth.api.dataviews.DataviewsAPI.query_data"
+
+_DATA_PAGE_SYMBOL = "mammoth.api.dataviews.DataviewsAPI.get_data"
+_MAX_UNMATCHED_KEYS = 5
+
+
+def join_snapshot(
+    service: Any, dataset_id: int, dataview_id: int, project_id: int | None
+) -> dict[str, Any]:
+    """Row count, columns and the first data page of a view (best effort)."""
+    snapshot: dict[str, Any] = {"row_count": None, "columns": {}, "rows": []}
+    try:
+        info = apply_column_renames(
+            service.call(
+                _DATAVIEW_GET_SYMBOL,
+                dataset_id=dataset_id,
+                dataview_id=dataview_id,
+                project_id=project_id,
+            )
+        )
+        if isinstance(info, dict):
+            snapshot["row_count"] = info.get("row_count")
+            snapshot["columns"] = {
+                c.get(_INTERNAL_NAME_KEY): c.get(_DISPLAY_NAME_KEY)
+                for c in info.get(_METADATA_KEY) or []
+                if isinstance(c, dict)
+            }
+            page = service.call(
+                _DATA_PAGE_SYMBOL,
+                dataset_id=dataset_id,
+                dataview_id=dataview_id,
+                project_id=project_id,
+            )
+            page = _relabel_columns(
+                service, dataset_id, dataview_id, project_id, page, snapshot["columns"]
+            )
+            rows = page.get(_ROWS_KEY) if isinstance(page, dict) else None
+            snapshot["rows"] = [r for r in rows or [] if isinstance(r, dict)]
+    except Exception:  # noqa: BLE001 -- the check is advice; the join already ran
+        return snapshot
+    return snapshot
+
+
+def with_join_check(data: Any, before: Any, after: dict[str, Any], document: dict[str, Any]) -> Any:
+    """Add ``join_check`` (row counts, columns added, match rate) to a join result.
+
+    ``unmatched_rows`` counts rows where every added column is blank: for a
+    LEFT join these are rows whose key found no match in the other view.
+    """
+    if not isinstance(data, dict) or not isinstance(before, dict):
+        return data
+    added = [
+        name
+        for internal, name in after.get("columns", {}).items()
+        if internal not in before.get("columns", {}) and isinstance(name, str)
+    ]
+    rows = after.get("rows") or []
+    check: dict[str, Any] = {
+        "rows_before": before.get("row_count"),
+        "rows_after": after.get("row_count"),
+        "columns_added": added,
+        "rows_checked": len(rows),
+    }
+    notes: list[str] = []
+    on = document.get("on")
+    left_key = None
+    if isinstance(on, list) and on and isinstance(on[0], dict):
+        left_key = on[0].get("left")
+    if added and rows:
+        unmatched = [r for r in rows if all(r.get(c) in (None, "") for c in added)]
+        check["unmatched_rows"] = len(unmatched)
+        check["match_rate"] = round((len(rows) - len(unmatched)) / len(rows), 3)
+        if unmatched:
+            keys = sorted({str(r.get(left_key)) for r in unmatched if left_key in r})
+            check["unmatched_keys"] = keys[:_MAX_UNMATCHED_KEYS]
+            notes.append(
+                f"{len(unmatched)} of {len(rows)} rows found no match. If that is more "
+                "than a few, compare the key columns in both views (type, case, "
+                "padding) before you build on this; otherwise say so in your report."
+            )
+    before_n, after_n = check["rows_before"], check["rows_after"]
+    if isinstance(before_n, int) and isinstance(after_n, int):
+        if after_n > before_n:
+            notes.append(
+                f"The join added {after_n - before_n} rows: a key repeats in the other "
+                "view, so matching rows repeat. Totals over this view count them twice; "
+                "use view transform lookup for one value per key."
+            )
+        elif after_n < before_n:
+            notes.append(
+                f"{before_n - after_n} rows had no match and were dropped "
+                "(an INNER join keeps matched rows only)."
+            )
+    if isinstance(after_n, int) and len(rows) < after_n:
+        notes.append(f"Match rate is from the first {len(rows)} rows of {after_n}.")
+    if notes:
+        check["notes"] = notes
+    return {**data, "join_check": check}
+
+
+def _column_profile(
+    service: Any, dataset_id: int, dataview_id: int, project_id: int | None
+) -> tuple[dict[str, str], dict[str, str]]:
+    """One metadata read: internal-to-display names, and display name to type."""
+    mapping: dict[str, str] = {}
+    types: dict[str, str] = {}
+    for column in _dataview_metadata(service, dataset_id, dataview_id, project_id):
+        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 "")
+    return mapping, types
+
+
+def _relabel_and_check(
+    service: Any,
+    dataset_id: int,
+    view_id: int,
+    project_id: int | None,
+    data: Any,
+    mapping: dict[str, str] | None = None,
+    types: dict[str, str] | None = None,
+) -> Any:
+    """Relabel a data page to display names and add ``column_warnings``.
+
+    The metadata read happens only when the page has rows and the caller has
+    not read it already (one read serves both the names and the types).
+    """
+    rows = data.get(_ROWS_KEY) if isinstance(data, dict) else None
+    if not isinstance(rows, list) or not rows:
+        return _relabel_columns(service, dataset_id, view_id, project_id, data, mapping)
+    if mapping is None or types is None:
+        mapping, types = _column_profile(service, dataset_id, view_id, project_id)
+    data = _relabel_columns(service, dataset_id, view_id, project_id, data, mapping)
+    return _with_column_warnings(data, types, view_id)
+
+
+def _with_column_warnings(data: Any, types: dict[str, str], view_id: int) -> Any:
+    """Add ``column_warnings`` for the rows of a data page (never fatal)."""
+    if not isinstance(data, dict) or not isinstance(data.get(_ROWS_KEY), list) or not types:
+        return data
+    try:
+        warnings = column_warnings(data[_ROWS_KEY], types, view_id)
+    except Exception:  # noqa: BLE001 -- a presentation aid must not fail the read
+        return data
+    return {**data, "column_warnings": warnings} if warnings else data
 
 
 #: Rows a plain ``view data get`` returns unless ``limit`` says otherwise.
@@ -677,9 +836,11 @@ def view_data_query(invocation: Invocation) -> HandlerResult:
             "project_id": project_id,
         }
         _forward_optional(document, kwargs, ("sequence", "offset", "limit", "sort"))
-        mapping = _compile_query_filters(service, dataset_id, view_id, project_id, document, kwargs)
+        mapping, types = _compile_query_filters(
+            service, dataset_id, view_id, project_id, document, kwargs
+        )
         data = service.call(_symbol(invocation), **kwargs)
-        data = _relabel_columns(service, dataset_id, view_id, project_id, data, mapping)
+        data = _relabel_and_check(service, dataset_id, view_id, project_id, data, mapping, types)
     return data, _meta(invocation, auth.workspace_id, project_id)
 
 

{mammoth_cli-2.0.38 → mammoth_cli-2.0.39}/mammoth_cli/commands/view_ops.py

@@ -19,6 +19,7 @@ enum-typed fields are forwarded as the plain string given on ``--input``.
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from typing import Any
 
 from mammoth_cli.commands.view import (
@@ -26,6 +27,8 @@ from mammoth_cli.commands.view import (
     _require_discovery_allowed,
     apply_column_renames,
     brief_view_record,
+    join_snapshot,
+    with_join_check,
 )
 from mammoth_cli.context import profiles
 from mammoth_cli.errors.envelope import (
@@ -232,9 +235,20 @@ def _meta(invocation: Invocation, workspace_id: int) -> dict[str, Any]:
 
 
 def _dispatch_view(
-    invocation: Invocation, view_id: int, method: str, **kwargs: Any
+    invocation: Invocation,
+    view_id: int,
+    method: str,
+    *,
+    before: Callable[[Any, int], Any] | None = None,
+    after: Callable[[Any, int, Any, Any], Any] | None = None,
+    **kwargs: Any,
 ) -> HandlerResult:
-    """Open the service, dispatch a View method call, and build the envelope."""
+    """Open the service, dispatch a View method call, and build the envelope.
+
+    ``before(service, dataset_id)`` runs ahead of the call and its value is
+    handed to ``after(service, dataset_id, state, data)``, which returns the
+    result to emit. Both need the exact parent; without one they are skipped.
+    """
     # ``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
@@ -254,6 +268,7 @@ def _dispatch_view(
         if dataset_id is None:
             dataset_id = parents.lookup(_profile_name(invocation), auth.workspace_id, view_id)
         require_expected_task_count(service, view_id, dataset_id, document)
+        state = before(service, int(dataset_id)) if before and dataset_id is not None else None
         try:
             if dataset_id is None:
                 _require_discovery_allowed(invocation, view_id)
@@ -266,6 +281,8 @@ 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 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)
 
 
@@ -782,7 +799,17 @@ def view_transform_join(invocation: Invocation) -> HandlerResult:
     _require_field(document, "select")
     assert document is not None
     kwargs = _bind_transform_inputs(invocation, document)
-    return _dispatch_view(invocation, view_id, "join", **kwargs)
+    project_id = invocation.project
+
+    def before(service: Any, dataset_id: int) -> Any:
+        return join_snapshot(service, dataset_id, view_id, project_id)
+
+    def after(service: Any, dataset_id: int, state: Any, data: Any) -> Any:
+        return with_join_check(
+            data, state, join_snapshot(service, dataset_id, view_id, project_id), document
+        )
+
+    return _dispatch_view(invocation, view_id, "join", before=before, after=after, **kwargs)
 
 
 def view_transform_json_extract(invocation: Invocation) -> HandlerResult:

{mammoth_cli-2.0.38 → mammoth_cli-2.0.39}/mammoth_cli/runtime/strict.py

@@ -271,6 +271,17 @@ def _coerce_document_fields(
             ) from None
 
 
+#: Commands whose request nests the payload: name the nesting on a wrong key.
+_UNKNOWN_FIELD_HINTS: dict[str, str] = {
+    "dashboard.canvas.save": (
+        "Accepted field: body. Wrap the canvas: "
+        '{"body": {"params": {"canvas": CANVAS}}}, where CANVAS is data.canvas '
+        "from 'mammoth dashboard canvas get DASHBOARD_ID', edited. An --input file "
+        "takes the same wrapped document."
+    ),
+}
+
+
 def validate_input_fields(command_id: str, document: dict[str, Any] | None) -> None:
     """Reject unknown ``--input`` keys, then coerce known keys to their type.
 
@@ -319,7 +330,9 @@ def validate_input_fields(command_id: str, document: dict[str, Any] | None) -> N
                 f"{', '.join(unknown)}."
             ),
             exit_status=EXIT_USAGE,
-            hint=f"Accepted fields: {', '.join(sorted(fields_by_name)) or '(none)' }.",
+            hint=_UNKNOWN_FIELD_HINTS.get(
+                command_id, f"Accepted fields: {', '.join(sorted(fields_by_name)) or '(none)' }."
+            ),
             details={"unknown": unknown, "accepted": sorted(fields_by_name)},
         )
     if is_closed_zero_input(command_id) and document == {}:

{mammoth_cli-2.0.38 → mammoth_cli-2.0.39}/mammoth_cli/services/command_contract.py

@@ -584,7 +584,10 @@ S7_COMMANDS = frozenset(
 _S7_ADDITIONAL_INPUT_FIELDS: dict[str, tuple[FieldSpec, ...]] = {
     # The GET data route has no server-side page size; the CLI trims the row
     # list so a read-back costs a screen of tokens, not the whole view.
-    "view.data.get": (FieldSpec("limit", required=False, annotation=int, default=50),),
+    "view.data.get": (
+        FieldSpec("limit", required=False, annotation=int, default=50),
+        FieldSpec("offset", required=False, annotation=int, default=1),
+    ),
     # The dataview GET takes a server-side projection: "__min", "__standard",
     # "__full" or a comma-separated field list.
     "view.get": (FieldSpec("fields", required=False, annotation=str | None, default=None),),

mammoth_cli-2.0.39/mammoth_cli/services/data_quality.py

@@ -0,0 +1,136 @@
+"""Column warnings computed from a page of view rows.
+
+An agent that reads a view before building on it sees rows, not problems: a
+``price`` column of numbers with a few ``"N/A"`` values is TEXT, so a chart
+cannot sum it, and blanks drop out of totals. These checks name the problem
+and the command that fixes it, in the output the agent is already reading.
+They run on the rows a command already fetched and never make a request.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable, Mapping
+from datetime import datetime
+from typing import Any
+
+#: A share of non-blank values at or above this reads as "meant to be" that type.
+_MOSTLY = 0.8
+#: Fewer non-blank values than this are too few to call a pattern.
+_MIN_VALUES = 3
+_MAX_EXAMPLES = 3
+
+_NUMBER = re.compile(r"^[-+]?[$€£]?\s*\d[\d,]*(\.\d+)?\s*%?$|^[-+]?[$€£]?\s*\.\d+\s*%?$")
+_DATE_FORMATS = (
+    "%Y-%m-%d",
+    "%Y/%m/%d",
+    "%m/%d/%Y",
+    "%d/%m/%Y",
+    "%d-%m-%Y",
+    "%m-%d-%Y",
+    "%Y-%m-%d %H:%M:%S",
+    "%Y-%m-%dT%H:%M:%S",
+    "%d %b %Y",
+    "%b %d, %Y",
+)
+
+
+def _blank(value: Any) -> bool:
+    return value is None or (isinstance(value, str) and not value.strip())
+
+
+def _is_number(text: str) -> bool:
+    return bool(_NUMBER.match(text.strip()))
+
+
+def _is_date(text: str) -> bool:
+    candidate = text.strip()
+    for fmt in _DATE_FORMATS:
+        try:
+            datetime.strptime(candidate, fmt)
+        except ValueError:
+            continue
+        return True
+    return False
+
+
+def _convert_hint(view_id: int | None, column: str, to: str) -> str:
+    target = str(view_id) if view_id is not None else "VIEW_ID"
+    spec = json.dumps({"conversions": [{"column": column, "to": to}]})
+    return f"mammoth view transform convert-type {target} --input '{spec}'"
+
+
+def column_warnings(
+    rows: Iterable[Mapping[str, Any]],
+    column_types: Mapping[str, str],
+    view_id: int | None = None,
+) -> list[dict[str, Any]]:
+    """Return warnings for text columns that hold numbers or dates, and for blanks.
+
+    Args:
+        rows: Row objects keyed by display name (a data page after relabeling).
+        column_types: Display name to Mammoth type (``TEXT``, ``NUMERIC``, ...).
+        view_id: The view the rows came from, used in the suggested command.
+
+    Returns:
+        One record per finding: ``column``, ``issue``
+        (``numbers_stored_as_text``, ``dates_stored_as_text`` or
+        ``blank_values``), ``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:
+        return []
+    checked = len(materialised)
+    warnings: list[dict[str, Any]] = []
+    for column, col_type in column_types.items():
+        values = [row.get(column) for row in materialised if column in row]
+        if not values:
+            continue
+        present = [v for v in values if not _blank(v)]
+        blanks = len(values) - len(present)
+        if str(col_type).upper() == "TEXT" and len(present) >= _MIN_VALUES:
+            texts = [str(v) for v in present]
+            numbers = [t for t in texts if _is_number(t)]
+            dates = [t for t in texts if _is_date(t)]
+            for matched, issue, to, kind in (
+                (numbers, "numbers_stored_as_text", "NUMERIC", "numbers"),
+                (dates, "dates_stored_as_text", "DATE", "dates"),
+            ):
+                if len(matched) / len(texts) < _MOSTLY:
+                    continue
+                others = sorted({t for t in texts if t not in set(matched)})
+                detail = (
+                    f"{len(matched)} of {len(texts)} non-blank values are {kind}, "
+                    "but the column is TEXT: charts and totals cannot use it as a "
+                    f"{'number' if to == 'NUMERIC' else 'date'}."
+                )
+                if others:
+                    shown = ", ".join(repr(o) for o in others[:_MAX_EXAMPLES])
+                    detail += f" Other values: {shown} (the conversion makes them empty)."
+                warnings.append(
+                    {
+                        "column": column,
+                        "issue": issue,
+                        "detail": detail,
+                        "fix": _convert_hint(view_id, column, to),
+                        "rows_checked": checked,
+                    }
+                )
+                break
+        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,
+                }
+            )
+    return warnings