mammoth-cli 2.2.19__tar.gz → 2.2.20__tar.gz

{mammoth_cli-2.2.19 → mammoth_cli-2.2.20}/PKG-INFO

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

{mammoth_cli-2.2.19 → mammoth_cli-2.2.20}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/view.md

@@ -116,7 +116,7 @@ Status on release: ran once on CLI 2.0.18 — fixture-lifecycle sweep 2026-09-19
 
 Run: `mammoth view conditional-format create`. Exact input fields: `mammoth schema get view.conditional-format.create`.
 
-Example: `mammoth view conditional-format create 123 123 --input '{"rule": {"cf_type": "RULE", "payload": {"FORMAT": {"name": "Flag open orders", "color": "red", "applies_to": "row", "column_ids": "[]"}, "CONDITION": {"OR": [{"column_1": {"CONTAINS": {"VALUE": ["Open"]}}}]}}}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+Example: `mammoth view conditional-format create 123 123 --input '{"columns": ["Q1", "Q2", "Q3"], "operator": "<", "value": 55, "color": "red"}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
 
 Result: `ViewConditionalFormatCreateResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
 

{mammoth_cli-2.2.19 → mammoth_cli-2.2.20}/mammoth_cli/bundled_skill/mammoth-cli/references/operations.md

@@ -176,6 +176,15 @@ them, so never report them as access denied. Pass `include_non_members: true`
 only when the user asks about projects they are not in; each row then carries
 `member`.
 
+## Conditional formatting
+
+Colour cells in many columns by one threshold in a single command:
+`view conditional-format create --input '{"columns": ["Q1", "Q2"], "operator": "<", "value": 55, "color": "red"}'`
+(display names). Each cell is judged by its own value, so this makes one rule
+per column in that one call and returns every created rule id. `applies_to: "row"`
+makes one rule that colours whole rows when any (`match: "any"`, default) or all
+(`"all"`) of the columns match. A raw `rule` body still works.
+
 ## Exports
 
 First inspect `view.export.list/get` for existing configuration and the exact

{mammoth_cli-2.2.19 → mammoth_cli-2.2.20}/mammoth_cli/commands/view.py

@@ -50,8 +50,10 @@ from mammoth_cli.runtime.confirm import (
     POLICY_YES_ALWAYS,
     enforce_confirmation,
 )
+from mammoth_cli.runtime.dryrun import DryRunStop
 from mammoth_cli.runtime.invocation import Invocation
 from mammoth_cli.runtime.session import open_service, require_project
+from mammoth_cli.services import conditional_format as cf_rules
 from mammoth_cli.services import read_queries, text_dates
 from mammoth_cli.services.conditions import CONDITION_KWARG, compile_condition
 from mammoth_cli.services.dashboard_review import UPLOAD_NOTE, upload_hints
@@ -2132,24 +2134,89 @@ def view_exportable_config_apply(invocation: Invocation) -> HandlerResult:
 
 
 def view_conditional_format_create(invocation: Invocation) -> HandlerResult:
-    """Create a conditional-format rule on a dataview. ``rule`` is required."""
+    """Colour cells in many columns by one threshold in a single command (columns + operator + value + color): each cell is judged by its own value. applies_to=row colours whole rows when any/all of the columns match.
+
+    Per-cell means one rule per column, all made in this one call. A raw ``rule`` body still
+    works instead.
+    """  # noqa: E501
     project_id = require_project(invocation)
     dataview_id = _require_int_positional_at(invocation, 0, "view id")
-    document = invocation.load_input()
-    rule = _require_field(document, "rule")
-    assert document is not None
+    document = invocation.load_input() or {}
+    has_typed = any(field in document for field in cf_rules.TYPED_FIELDS)
+    if "rule" in document and has_typed:
+        raise CliError(
+            code=cf_rules.CODE_INVALID_RULE,
+            message="Pass either 'rule' or the typed fields (columns, operator, value, color).",
+            exit_status=EXIT_USAGE,
+        )
+    if "rule" not in document and not has_typed:
+        _require_field(document, "rule")
     with open_service(invocation) as (service, auth):
         dataset_id = _resolve_dataset_id(service, invocation, dataview_id, document)
-        data = service.call(
-            _symbol(invocation),
-            dataset_id=dataset_id,
-            dataview_id=dataview_id,
-            rule=rule,
-            project_id=project_id,
-        )
+        if has_typed:
+            metadata = _dataview_metadata(service, dataset_id, dataview_id, project_id)
+            column_map, column_types = _column_maps(metadata)
+            rules = cf_rules.build_rules(document, column_map, column_types)
+        else:
+            cf_rules.validate_rule(document["rule"])
+            rules = [document["rule"]]
+        data = _create_cf_rules(service, invocation, rules, (dataset_id, dataview_id, project_id))
     return data, _meta(invocation, auth.workspace_id, project_id)
 
 
+def _cf_sequence(rule: Any) -> int:
+    return rule.get("SEQUENCE", -1) if isinstance(rule, dict) else -1
+
+
+def _create_cf_rules(
+    service: Any, invocation: Invocation, rules: list[dict[str, Any]], scope: tuple[Any, ...]
+) -> Any:
+    """POST each rule in turn; a mid-way failure names the rule ids already created.
+
+    Every response is the dataview's whole rule map; the new rule has the highest SEQUENCE.
+    """
+    dataset_id, dataview_id, project_id = scope
+    ids: list[str] = []
+    data: Any = None
+    for rule in rules:
+        try:
+            data = service.call(
+                _symbol(invocation),
+                dataset_id=dataset_id,
+                dataview_id=dataview_id,
+                rule=rule,
+                project_id=project_id,
+            )
+        except DryRunStop as stop:
+            stop.record["rules"] = rules  # every body that would be sent, not just the first
+            raise
+        except CliError as error:
+            if ids:
+                error.details = {**error.details, "created_rule_ids": ids}
+                error.message += f" Rules already created before the failure: {ids}."
+            raise
+        if isinstance(data, dict) and data:
+            ids.append(max(data, key=lambda k: _cf_sequence(data[k])))
+    if len(rules) == 1:
+        return data
+    note = f"{len(rules)} rules, one per column, so each cell is coloured by its own value."
+    return {"created_rule_ids": ids, "rules_created": len(rules), "note": note}
+
+
+def _column_maps(metadata: list[dict[str, Any]]) -> tuple[dict[str, str], dict[str, str]]:
+    """Display -> internal name and display -> type maps from a view's column metadata."""
+    names: dict[str, str] = {}
+    types: dict[str, str] = {}
+    for column in metadata:
+        internal = column.get(_INTERNAL_NAME_KEY)
+        display = column.get(_DISPLAY_NAME_KEY)
+        if isinstance(internal, str) and isinstance(display, str):
+            names[display] = internal
+            if isinstance(column.get("type"), str):
+                types[display] = column["type"]
+    return names, types
+
+
 def view_conditional_format_delete_all(invocation: Invocation) -> HandlerResult:
     """Delete a conditional-format rule on a dataview. Prompt or ``--yes``.
 

{mammoth_cli-2.2.19 → mammoth_cli-2.2.20}/mammoth_cli/errors/envelope.py

@@ -111,6 +111,7 @@ ERROR_SUMMARIES: dict[str, str] = {
     "invalid_argument": _S_BAD_REQUEST,
     "invalid_argument_combination": _S_BAD_REQUEST,
     "invalid_arguments": _S_BAD_REQUEST,
+    "invalid_rule": "A conditional-format rule wasn't valid.",
     "invalid_condition": "A filter condition wasn't valid.",
     "invalid_condition_value": "A filter condition used a value that isn't valid.",
     "invalid_config_value": _S_SETUP,

{mammoth_cli-2.2.19 → mammoth_cli-2.2.20}/mammoth_cli/services/command_contract.py

@@ -350,6 +350,24 @@ _VIEW_DATA_PROFILE_FIELDS = (
     FieldSpec("limit", required=False, annotation=int, default=50),
 )
 
+# view.conditional-format.create: ``rule`` (raw body) stays accepted; the typed fields build one
+# rule per column (per-cell threshold) or one row rule (see
+# mammoth_cli.services.conditional_format). ``rule`` is therefore optional here -- the handler
+# requires one form or the other.
+_VIEW_CF_CREATE_FIELDS = (
+    FieldSpec("dataset_id", required=True, annotation=int),
+    FieldSpec("rule", required=False, annotation=dict[str, Any] | None, default=None),
+    FieldSpec("columns", required=False, annotation=list[str] | None, default=None),
+    FieldSpec("operator", required=False, annotation=str | None, default=None),
+    FieldSpec("value", required=False, annotation=Any, default=None),
+    FieldSpec("color", required=False, annotation=str | None, default=None),
+    FieldSpec("name", required=False, annotation=str | None, default=None),
+    FieldSpec(
+        "applies_to", required=False, annotation=Literal["row", "columns"] | None, default=None
+    ),
+    FieldSpec("match", required=False, annotation=Literal["any", "all"] | None, default=None),
+)
+
 # dashboard.filter.add/remove are CLI composites over canvas get + canvas save
 # (DashboardsAPI.canvas_save is named in the manifest as the SDK anchor); the
 # canvas body is built by the handler, so the document carries only the filter.
@@ -760,6 +778,8 @@ def resolve_command_contract(command_id: str) -> ResolvedCommandContract | None:
         special_fields = _DASHBOARD_FILTER_ADD_FIELDS
     elif command_id == "dashboard.filter.remove":
         special_fields = _DASHBOARD_FILTER_REMOVE_FIELDS
+    elif command_id == "view.conditional-format.create":
+        special_fields = _VIEW_CF_CREATE_FIELDS
     elif command_id == "dashboard.filter.list":
         special_fields = ()
     local_fields = _LOCAL_CONTRACT_FIELDS.get(command_id, ()) if is_local else None

mammoth_cli-2.2.20/mammoth_cli/services/conditional_format.py

@@ -0,0 +1,131 @@
+"""Build and check the conditional-format rule body ``view conditional-format create`` sends.
+
+The release route takes ``{"cf_type": "RULE", "payload": {"FORMAT", "CONDITION"}}``. One
+rule is ``FORMAT.applies_to`` ``"columns"`` with ``column_ids`` (a JSON-encoded list of
+internal names) or ``"row"``, plus a ``CONDITION`` group. The evaluator checks CONDITION per row
+and colours every ``column_ids`` cell, so the typed fields build one rule per column for a
+per-cell threshold, or one row rule.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from mammoth_cli.errors.envelope import EXIT_USAGE, CliError
+from mammoth_cli.services.conditions import compile_condition
+
+CODE_INVALID_RULE = "invalid_rule"
+APPLIES_TO = ("row", "columns")
+_EMPTY_COLUMN_IDS = "[]"
+MATCH = ("any", "all")
+TYPED_FIELDS = ("columns", "operator", "value", "color", "name", "applies_to", "match")
+_NO_VALUE_OPERATORS = frozenset({"IS_EMPTY", "IS_NOT_EMPTY"})
+
+
+def _invalid(message: str, hint: str | None = None) -> CliError:
+    return CliError(code=CODE_INVALID_RULE, message=message, exit_status=EXIT_USAGE, hint=hint)
+
+
+def _check_format(fmt: Any) -> None:
+    """Mirror the backend's FORMAT validation so a bad rule fails before any request."""
+    if not isinstance(fmt, dict):
+        raise _invalid("A RULE payload needs a FORMAT object.")
+    applies_to = fmt.get("applies_to")
+    if applies_to not in APPLIES_TO:
+        raise _invalid(
+            f"FORMAT.applies_to must be one of {', '.join(APPLIES_TO)}; got {applies_to!r}.",
+            "Use 'row' to colour whole rows, or 'columns' with column_ids.",
+        )
+    column_ids = fmt.get("column_ids", _EMPTY_COLUMN_IDS)
+    empty = column_ids == _EMPTY_COLUMN_IDS
+    if applies_to == "row" and not empty:
+        raise _invalid("FORMAT.column_ids must be '[]' when applies_to is 'row'.")
+    if applies_to == "columns" and empty:
+        raise _invalid("FORMAT.column_ids must not be '[]' when applies_to is 'columns'.")
+
+
+def validate_rule(rule: Any) -> None:
+    """Raise ``invalid_rule`` when a raw rule's FORMAT has a bad ``applies_to``/``column_ids``.
+
+    Everything else about the body (cf_type, CONDITION) is left to the backend, which
+    owns those shapes; only the FORMAT enum was reaching it unchecked.
+    """
+    payload = rule.get("payload") if isinstance(rule, dict) else None
+    if isinstance(payload, dict) and "FORMAT" in payload:
+        _check_format(payload["FORMAT"])
+
+
+def _resolve_columns(names: Any, column_map: dict[str, str]) -> list[str]:
+    if not isinstance(names, list) or not names or not all(isinstance(n, str) for n in names):
+        raise _invalid("'columns' must be a non-empty list of column names.")
+    missing = [name for name in names if name not in column_map]
+    if missing:
+        raise _invalid(
+            f"Unknown column(s): {', '.join(missing)}.",
+            "Use display names of the view's columns: " + ", ".join(sorted(column_map)),
+        )
+    return list(dict.fromkeys(names))
+
+
+def _leaf(column: str, document: dict[str, Any]) -> dict[str, Any]:
+    leaf: dict[str, Any] = {"column": column, "operator": document["operator"]}
+    if "value" in document:
+        leaf["value"] = document["value"]
+    return leaf
+
+
+def _require_typed(document: dict[str, Any]) -> None:
+    for field in ("columns", "operator", "color"):
+        if document.get(field) is None:
+            raise _invalid(
+                f"The typed form needs '{field}'.",
+                'Many columns, one command: --input \'{"columns": ["A", "B"], '
+                '"operator": "<", "value": 55, "color": "red"}\'.',
+            )
+
+
+def _label(document: dict[str, Any]) -> str:
+    operator = str(document["operator"])
+    if operator.upper() in _NO_VALUE_OPERATORS:
+        return operator
+    return f"{operator} {document.get('value')}"
+
+
+def _rule(fmt: dict[str, Any], condition: dict[str, Any]) -> dict[str, Any]:
+    rule = {"cf_type": "RULE", "payload": {"FORMAT": fmt, "CONDITION": condition}}
+    validate_rule(rule)
+    return rule
+
+
+def build_rules(
+    document: dict[str, Any], column_map: dict[str, str], column_types: dict[str, str]
+) -> list[dict[str, Any]]:
+    """RULE entries for the typed fields.
+
+    The evaluator judges CONDITION once per ROW and then colours every ``column_ids`` cell, so a
+    threshold per cell needs one rule per column (each condition on its own column). Only
+    ``applies_to: row`` is one rule: ``match`` any (OR, default) or all (AND) of the columns.
+    """
+    _require_typed(document)
+    names = _resolve_columns(document["columns"], column_map)
+    color, label = document["color"], _label(document)
+
+    def condition(name: str) -> dict[str, Any]:
+        return compile_condition(_leaf(name, document)).build(column_map, column_types)
+
+    if document.get("applies_to") == "row":
+        match = document.get("match") or "any"
+        if match not in MATCH:
+            raise _invalid(f"match must be one of {', '.join(MATCH)}; got {match!r}.")
+        fmt = {"name": document.get("name") or f"{', '.join(names)} {label}"[:80]}
+        fmt |= {"color": color, "applies_to": "row", "column_ids": "[]"}
+        group = {"OR" if match == "any" else "AND": [condition(n) for n in names]}
+        return [_rule(fmt, group)]
+    rules = []
+    for name in names:
+        title = f"{document['name']}: {name}" if document.get("name") else f"{name} {label}"
+        fmt = {"name": title, "color": color, "applies_to": "columns"}
+        fmt["column_ids"] = json.dumps([column_map[name]])
+        rules.append(_rule(fmt, {"OR": [condition(name)]}))
+    return rules

{mammoth_cli-2.2.19 → mammoth_cli-2.2.20}/mammoth_cli/services/input_fields.py

@@ -226,22 +226,13 @@ _EXAMPLE_INPUT_HINTS: dict[str, dict[str, Any]] = {
     },
     "view.ai.profile": {"dataset_id": 456, "action": "insights"},
     "connector.query.generate": {"query": "Total sales for January"},
-    # HighlightEntry: cf_type + payload{FORMAT, CONDITION keyed by internal
-    # column name}; the create response and ``conditional-format list`` carry
-    # the generated rule_id that delete-all needs.
+    # One rule over many columns; the create response and ``conditional-format
+    # list`` carry the generated rule_id that delete-all needs.
     "view.conditional-format.create": {
-        "rule": {
-            "cf_type": "RULE",
-            "payload": {
-                "FORMAT": {
-                    "name": "Flag open orders",
-                    "color": "red",
-                    "applies_to": "row",
-                    "column_ids": "[]",
-                },
-                "CONDITION": {"OR": [{"column_1": {"CONTAINS": {"VALUE": ["Open"]}}}]},
-            },
-        }
+        "columns": ["Q1", "Q2", "Q3"],
+        "operator": "<",
+        "value": 55,
+        "color": "red",
     },
     "view.conditional-format.delete-all": {"rule_id": "bca0ff33bd6f8ed1"},
     "dataset.bulk-delete": {"dataset_ids": [456, 457]},

{mammoth_cli-2.2.19 → mammoth_cli-2.2.20}/pyproject.toml

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

{mammoth_cli-2.2.19 → mammoth_cli-2.2.20}/spec/manifests/commands/view.yaml

@@ -593,9 +593,8 @@ commands:
   required_fixture_guard: null
   secret_fields: []
   human_example: mammoth view conditional-format create VIEW_ID --help
-  agent_example: 'mammoth view conditional-format create 123 123 --input ''{"rule": {"cf_type": "RULE",
-    "payload": {"FORMAT": {"name": "Flag open orders", "color": "red", "applies_to": "row", "column_ids":
-    "[]"}, "CONDITION": {"OR": [{"column_1": {"CONTAINS": {"VALUE": ["Open"]}}}]}}}}'''
+  agent_example: 'mammoth view conditional-format create 123 123 --input ''{"columns": ["Q1", "Q2",
+    "Q3"], "operator": "<", "value": 55, "color": "red"}'''
   unit_tests:
   - UT-VIEW-CONDITIONAL-FORMAT-CREATE
   contract_tests:
@@ -604,9 +603,10 @@ commands:
   - CT-VIEW-CONDITIONAL-FORMAT-CREATE-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: 'rule is forwarded verbatim and dispatches. The release backend requires {"cf_type":
-    "RULE"|"COLOR_SCALE", "payload": {...}} with a CONDITION (RULE) or scale (COLOR_SCALE) inside payload;
-    other shapes return HTTP 400 4GENR007. Untyped; no working payload observed yet.'
+  known_restrictions: 'columns + operator + value + color colour each cell by its own value: one RULE
+    per column, created in this one call (applies_to columns, the default). applies_to row makes
+    one rule over any/all (match) of the columns. A raw rule body ({"cf_type": "RULE"|"COLOR_SCALE",
+    "payload": {...}}) still works instead; applies_to must be row or columns.'
   reviewed_by: primary
 - command_id: view.conditional-format.delete-all
   command_path: view conditional-format delete-all