mammoth-cli 2.2.15__tar.gz → 2.2.17__tar.gz

{mammoth_cli-2.2.15 → mammoth_cli-2.2.17}/PKG-INFO

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

{mammoth_cli-2.2.15 → mammoth_cli-2.2.17}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mammoth-cli
-version: 2.0.75
+version: 2.2.16
 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."
 ---
 

{mammoth_cli-2.2.15 → mammoth_cli-2.2.17}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/workflow.md

@@ -46,7 +46,7 @@ Status on release: untried; no live run recorded.
 
 Run: `mammoth workflow canvas`. Exact input fields: `mammoth schema get workflow.canvas`.
 
-Example: `mammoth workflow canvas 123 --input '{"canvas_state": {"sample_key": "Status"}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+Example: `mammoth workflow canvas 12 --input '{"canvas_state": {"proposed_changes": [{"op": "add_view", "dataset_id": 415, "name": "Urgent tickets", "ref": "urgent"}, {"op": "send_to_new_dataset", "dataset_id": 415, "view_ref": "urgent", "name": "Urgent tickets by team"}]}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
 
 Result: `WorkflowCanvasResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
 

{mammoth_cli-2.2.15 → mammoth_cli-2.2.17}/mammoth_cli/bundled_skill/mammoth-cli/references/operations.md

@@ -36,7 +36,10 @@ credentials because they call the live API. To find a dataset by name, run
 `dataset list --input '{"name": "NAME"}'` inside one project: a
 case-insensitive substring match over every page, returned as short rows
 (id, name, rows, cols) with `matched`. Do not page `dataset list` by hand;
-`limit` is at most 100.
+`limit` is at most 100. To find the dataset that holds given columns, pass
+`dataset find --input '{"columns": ["Order ID", "Region"]}'` (the name is then
+optional). A `browse` search hit carries `dataset_id` or `view_id`: use those,
+never the tree `id`.
 
 ```bash
 mammoth capability find "transform"
@@ -116,11 +119,45 @@ mammoth workflow create "Revenue report"
 mammoth workflow get WORKFLOW_ID
 ```
 
+`WORKFLOW_ID` is the workflow's record id (URL id `w12` is record 12). An
+unnamed workflow (long base64 URL id) has no record: list the workflows and
+root datasets with `workflow graph`, then name it with `workflow create
+NAME --input '{"seed_datasource_id": ROOT_DATASET_ID}'`, which returns its
+record id. `workflow cleanup` deletes the project's orphaned skeleton
+("ghost") workflows (destructive; needs `--yes`).
+
+To only *suggest* a workflow's shape for the user to review, use `workflow
+canvas WORKFLOW_ID --input '{"canvas_state": {"proposed_changes": [...]}}'`.
+Nothing is built until the user presses Save on the Workflows canvas; tell
+them the changes are waiting there. Changes are `add_view`, `rename_view`,
+`trash_view`, `rename_dataset`, `trash_dataset`, `send_to_new_dataset`,
+`send_to_dataset`, `join` and `export` (fields per op: `schema get
+workflow.canvas`). A later change in the same call can point at an earlier
+one: give the earlier change a `ref`, then use `view_ref`, `dataset_ref` or
+`target_dataset_ref` instead of an id. It cannot add filters, calculations or
+other tasks; if the request needs those, build it with `view` commands.
+
 Draft mode is server-side batching for view pipeline edits. Enter, inspect
 status, submit, and verify pipeline state; discard only with the required
 confirmation. A draft submit result is not proof that every intended task was
 applied.
 
+## Reading data and history without changing the pipeline
+
+- A trend, distribution or top-values answer: `view data explore VIEW_ID
+  COLUMN` (read-only; `level` sets the date bucket). `{"cumulative": true}`
+  adds a running total per bucket, whatever `sort` or `limit` shows. Figures
+  from `explore` and `view data aggregate` are rounded for display (2
+  decimals; 4 below 1); `view data compare` keeps full precision.
+- "Who changed X": `activity list` (a change list of time, user, action and a
+  `path` naming the dataset and view). Filter with `resource_id` in the log's
+  typed form, `dataview_<id>` or `datasource_<id>` (a bare number matches
+  nothing and is refused), plus `start_time`, `end_time`, `user_ids`; page
+  with `limit` and `offset`.
+- `view export dataset` that returns `status: pending` was accepted and is
+  still being written. Do not export again (that makes a second dataset); run
+  its `next` command (`dataset find NAME`) to get the new dataset id.
+
 ## Response shapes
 
 Response shapes are not uniform; never reuse one `jq` path across commands.

{mammoth_cli-2.2.15 → mammoth_cli-2.2.17}/mammoth_cli/commands/schema.py

@@ -47,6 +47,27 @@ _PROTECTED_INPUT_PATH = "/private/path/request.json"
 _FIXED_EXAMPLES: dict[str, tuple[tuple[str, ...], dict[str, Any]]] = {
     "project.check": (("123", "456"), {}),
     "view.data.profile": (("123",), {"target": "Churn"}),
+    "workflow.canvas": (
+        ("12",),
+        {
+            "canvas_state": {
+                "proposed_changes": [
+                    {
+                        "op": "add_view",
+                        "dataset_id": 415,
+                        "name": "Urgent tickets",
+                        "ref": "urgent",
+                    },
+                    {
+                        "op": "send_to_new_dataset",
+                        "dataset_id": 415,
+                        "view_ref": "urgent",
+                        "name": "Urgent tickets by team",
+                    },
+                ]
+            }
+        },
+    ),
     "view.data.compare": (
         ("111", "222"),
         {
@@ -564,6 +585,16 @@ _COMMAND_DISCOVERY_PURPOSES = {
     ),
     "project.memory.list": "remembered saved preferences what do you remember memory",
     "project.memory.remove": "forget remove delete saved preference memory",
+    # A workflow's shape can be proposed for the user to review and Save on the
+    # canvas; neither this nor naming a workflow was findable from the way users
+    # ask (Workflow Zoo QA 10-02: "rename workflow" found column renames).
+    "workflow.canvas": (
+        "propose suggest sketch draft plan review approve save structural changes "
+        "to a workflow pipeline shape on the canvas new views datasets send to join "
+        "export for the user to review"
+    ),
+    "workflow.update": "rename name describe a workflow pipeline purpose notes summary",
+    "workflow.create": "name an unnamed workflow pipeline from the root dataset new workflow",
 }
 
 # A compact string scope is retained for existing discovery consumers.  These

{mammoth_cli-2.2.15 → mammoth_cli-2.2.17}/pyproject.toml

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

{mammoth_cli-2.2.15 → mammoth_cli-2.2.17}/spec/manifests/commands/workflow.yaml

@@ -222,6 +222,7 @@ commands:
   result_model: WorkflowCanvasResult
   mutation_class: benign_mutation
   edits_target: true
+  proposal_input: canvas_state.proposed_changes
   confirmation: none
   wait_policy: not_async
   pagination_policy: none
@@ -232,7 +233,7 @@ commands:
   required_fixture_guard: null
   secret_fields: []
   human_example: mammoth workflow canvas WORKFLOW_ID --help
-  agent_example: 'mammoth workflow canvas 123 --input ''{"canvas_state": {"sample_key": "Status"}}'''
+  agent_example: "mammoth workflow canvas 12 --input '{\"canvas_state\": {\"proposed_changes\": [{\"op\": \"add_view\", \"dataset_id\": 415, \"name\": \"Urgent tickets\", \"ref\": \"urgent\"}, {\"op\": \"send_to_new_dataset\", \"dataset_id\": 415, \"view_ref\": \"urgent\", \"name\": \"Urgent tickets by team\"}]}}'"
   unit_tests:
   - UT-WORKFLOW-CANVAS
   contract_tests:
@@ -241,7 +242,7 @@ commands:
   - CT-WORKFLOW-CANVAS-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: null
+  known_restrictions: "Proposes structural changes to a workflow for the user to review and Save on the Workflows canvas; nothing is built until they Save. Use it when the user asks to suggest, sketch or draft a workflow's shape, or wants to review first. It cannot add filters, calculations or other tasks: when any part of the request needs tasks or data, build the whole request with view commands instead. WORKFLOW_ID is the workflow's record id (URL id w12 is record 12); an unnamed workflow has none, so name it first with workflow create --seed_datasource_id. Input: {\"canvas_state\": {\"proposed_changes\": [...]}}, each change one of (integer ids from workflow graph): {op: add_view, dataset_id, name, ref?}; {op: rename_view, dataset_id, view_id, name}; {op: trash_view, dataset_id, view_id}; {op: rename_dataset, dataset_id, name}; {op: trash_dataset, dataset_id}; {op: send_to_new_dataset, dataset_id, view_id, name, ref?}; {op: send_to_dataset, dataset_id, view_id, target_dataset_id}; {op: join, dataset_id, view_id, with_dataset_id, with_view_id}; {op: export, dataset_id, view_id, connector}. A later change in the same call can point at something an earlier one proposes: give the earlier change a ref, then use view_ref, dataset_ref or target_dataset_ref in place of the id (a new dataset's ref also names its first view), so a whole shape is proposed in one call. Join and export arrive needing setup. Tell the user the changes wait on the canvas for their review."
   reviewed_by: primary
   readback:
     command: workflow.get
@@ -326,7 +327,7 @@ commands:
   - CT-WORKFLOW-CREATE-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: null
+  known_restrictions: "With seed_datasource_id set to a workflow's root dataset id (workflow graph lists each workflow's datasets), names that existing unnamed workflow and returns its record id; without it, starts a new empty workflow."
   reviewed_by: primary
   readback:
     command: workflow.get
@@ -571,7 +572,7 @@ commands:
   - CT-WORKFLOW-UPDATE-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: null
+  known_restrictions: "WORKFLOW_ID is the workflow's record id: URL id w12 is record 12. An unnamed workflow (base64 URL id) has no record; name it with workflow create --seed_datasource_id <its root dataset id> instead."
   reviewed_by: primary
   readback:
     command: workflow.get

{mammoth_cli-2.2.15 → mammoth_cli-2.2.17}/spec/manifests/schema-v1.json

@@ -210,7 +210,7 @@
         "contract_tests": {"type": "array", "items": {"$ref": "#/$defs/no_placeholder"}, "minItems": 1},
         "draft_test": {"type": ["string", "null"]},
         "undo_test": {"type": ["string", "null"]},
-        "known_restrictions": {"type": ["string", "null"]},
+        "known_restrictions": {"type": ["string", "null"]}, "proposal_input": {"type": "string", "minLength": 1},
         "reviewed_by": {"$ref": "#/$defs/no_placeholder"}
       },
       "allOf": [

{mammoth_cli-2.2.15 → mammoth_cli-2.2.17}/spec/manifests/sdk-catalog.source.yaml

@@ -3875,11 +3875,14 @@ sdk_methods:
   openapi_operation_ids: []
 - sdk_symbol: mammoth.api.workflows.WorkflowsAPI.canvas
   canonical_command: workflow.canvas
+  proposal_input: canvas_state.proposed_changes
   alias_of: null
   mutation_class: null
   wait_policy: null
   pagination_policy: null
   openapi_operation_ids: []
+  agent_example: "mammoth workflow canvas 12 --input '{\"canvas_state\": {\"proposed_changes\": [{\"op\": \"add_view\", \"dataset_id\": 415, \"name\": \"Urgent tickets\", \"ref\": \"urgent\"}, {\"op\": \"send_to_new_dataset\", \"dataset_id\": 415, \"view_ref\": \"urgent\", \"name\": \"Urgent tickets by team\"}]}}'"
+  notes: "Proposes structural changes to a workflow for the user to review and Save on the Workflows canvas; nothing is built until they Save. Use it when the user asks to suggest, sketch or draft a workflow's shape, or wants to review first. It cannot add filters, calculations or other tasks: when any part of the request needs tasks or data, build the whole request with view commands instead. WORKFLOW_ID is the workflow's record id (URL id w12 is record 12); an unnamed workflow has none, so name it first with workflow create --seed_datasource_id. Input: {\"canvas_state\": {\"proposed_changes\": [...]}}, each change one of (integer ids from workflow graph): {op: add_view, dataset_id, name, ref?}; {op: rename_view, dataset_id, view_id, name}; {op: trash_view, dataset_id, view_id}; {op: rename_dataset, dataset_id, name}; {op: trash_dataset, dataset_id}; {op: send_to_new_dataset, dataset_id, view_id, name, ref?}; {op: send_to_dataset, dataset_id, view_id, target_dataset_id}; {op: join, dataset_id, view_id, with_dataset_id, with_view_id}; {op: export, dataset_id, view_id, connector}. A later change in the same call can point at something an earlier one proposes: give the earlier change a ref, then use view_ref, dataset_ref or target_dataset_ref in place of the id (a new dataset's ref also names its first view), so a whole shape is proposed in one call. Join and export arrive needing setup. Tell the user the changes wait on the canvas for their review."
 - sdk_symbol: mammoth.api.workflows.WorkflowsAPI.cleanup
   canonical_command: workflow.cleanup
   alias_of: null
@@ -3894,6 +3897,7 @@ sdk_methods:
   wait_policy: null
   pagination_policy: null
   openapi_operation_ids: []
+  notes: "With seed_datasource_id set to a workflow's root dataset id (workflow graph lists each workflow's datasets), names that existing unnamed workflow and returns its record id; without it, starts a new empty workflow."
 - sdk_symbol: mammoth.api.workflows.WorkflowsAPI.delete
   canonical_command: workflow.delete
   alias_of: null
@@ -3936,6 +3940,7 @@ sdk_methods:
   wait_policy: null
   pagination_policy: null
   openapi_operation_ids: []
+  notes: "WORKFLOW_ID is the workflow's record id: URL id w12 is record 12. An unnamed workflow (base64 URL id) has no record; name it with workflow create --seed_datasource_id <its root dataset id> instead."
 - sdk_symbol: mammoth.api.workflows.WorkflowsAPI.workspace_datasets
   canonical_command: workflow.workspace-datasets
   alias_of: null