mammoth-cli 2.2.14__tar.gz → 2.2.16__tar.gz

{mammoth_cli-2.2.14 → mammoth_cli-2.2.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.2.14
+Version: 2.2.16
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk
@@ -17,7 +17,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: <3.15,>=3.12
 Requires-Dist: jsonschema>=4.20
 Requires-Dist: keyring<26,>=25.7
-Requires-Dist: mammoth-io<0.9,>=0.8.14
+Requires-Dist: mammoth-io<0.9,>=0.8.15
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.12.5
 Requires-Dist: pyyaml<7,>=6

{mammoth_cli-2.2.14 → mammoth_cli-2.2.16}/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.14"
+__version__ = "2.2.16"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.2.14 → mammoth_cli-2.2.16}/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.14 → mammoth_cli-2.2.16}/mammoth_cli/commands/activity.py

@@ -26,6 +26,7 @@ from mammoth_cli.manifest.loader import command_by_id
 from mammoth_cli.runtime.invocation import Invocation
 from mammoth_cli.runtime.session import open_service, resolved_project
 from mammoth_cli.services.command_contract import bind_command_inputs
+from mammoth_cli.services.local_time import local_time
 
 HandlerResult = tuple[Any, dict[str, Any]]
 
@@ -164,6 +165,9 @@ def _meta(invocation: Invocation, workspace_id: int, project_id: int | None) ->
 _WORKSPACE_USERS_SYMBOL = "mammoth.api.workspace.WorkspaceAPI.list_users"
 _TIME_FORMAT = "%Y-%m-%d %H:%M:%S"
 _EPOCH = "1970-01-01 00:00:00"
+# The route's default fields carry every entry's full details (tens of KB per page);
+# a change list needs only these. ``path`` names the dataset and view by name and id.
+_LIST_FIELDS = "id,category,name_key,primary_object,result,created_at,user_id,path"
 
 
 def _close_time_window(kwargs: dict[str, Any]) -> str | None:
@@ -184,19 +188,6 @@ def _close_time_window(kwargs: dict[str, Any]) -> str | None:
     return f"start_time was not given; the window starts at {_EPOCH} UTC."
 
 
-def _local_time(stamp: Any) -> str | None:
-    """A ``created_at`` (UTC if it has no offset) as ISO in this machine's timezone."""
-    if not isinstance(stamp, str):
-        return None
-    try:
-        moment = datetime.fromisoformat(stamp)
-    except ValueError:
-        return stamp
-    if moment.tzinfo is None:
-        moment = moment.replace(tzinfo=UTC)
-    return moment.astimezone().isoformat(timespec="seconds")
-
-
 def _user_emails(service: Any) -> dict[Any, str]:
     """Workspace users by id; empty when the caller may not list them."""
     try:
@@ -206,6 +197,11 @@ def _user_emails(service: Any) -> dict[Any, str]:
     return {u["id"]: u["email"] for u in users if isinstance(u, dict) and u.get("email")}
 
 
+def _readable_path(path: Any) -> str | None:
+    """The entry's ``workspace:name:id/project:name:id/dataset:name:id/...`` chain."""
+    return path.strip('{}"') if isinstance(path, str) else None
+
+
 def _change(entry: dict[str, Any], emails: dict[Any, str]) -> dict[str, Any]:
     """One log entry as a line of a change list: when, who, what, on which object."""
     raw_details = entry.get("details")
@@ -214,13 +210,14 @@ def _change(entry: dict[str, Any], emails: dict[Any, str]) -> dict[str, Any]:
     primary: dict[str, Any] = raw_primary if isinstance(raw_primary, dict) else {}
     user_id = entry.get("user_id")
     change = {
-        "when": _local_time(entry.get("created_at")),
+        "when": local_time(entry.get("created_at")),
         "user_id": user_id,
         "user": emails.get(user_id),
         "action": entry.get("name_key"),
         "category": entry.get("category"),
         "object": {"name": primary.get("name"), "resource_id": primary.get("resource_id")},
         "result": entry.get("result"),
+        "path": _readable_path(entry.get("path")),
     }
     if details.get("task_name"):
         change["task"] = details["task_name"]
@@ -248,7 +245,7 @@ def activity_list(invocation: Invocation) -> HandlerResult:
     """
     document = _bound_document(invocation)
     _refuse_bare_resource_id(document)
-    kwargs: dict[str, Any] = {}
+    kwargs: dict[str, Any] = {"fields": _LIST_FIELDS}
     _forward_optional(document, kwargs, _LIST_OPTIONAL)
     note = _close_time_window(kwargs)
     with open_service(invocation) as (service, auth):

{mammoth_cli-2.2.14 → mammoth_cli-2.2.16}/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.14 → mammoth_cli-2.2.16}/mammoth_cli/commands/view.py

@@ -57,6 +57,7 @@ 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, duplicate_rows_fact
 from mammoth_cli.services.listing import DATASET_LIST_FIELDS, compact_view_list
+from mammoth_cli.services.local_time import local_time
 from mammoth_cli.services.read_queries import ReadContext
 
 HandlerResult = tuple[Any, dict[str, Any]]
@@ -2604,10 +2605,30 @@ def view_version_list(invocation: Invocation) -> HandlerResult:
     _forward_optional(document, kwargs, ("fields", "sort", "limit", "offset", "name"))
     with open_service(invocation) as (service, auth):
         kwargs["dataset_id"] = _resolve_dataset_id(service, invocation, dataview_id, document)
-        data = service.call(_symbol(invocation), **kwargs)
+        data = _with_version_times(service.call(_symbol(invocation), **kwargs))
     return data, _meta(invocation, auth.workspace_id, project_id)
 
 
+def _with_version_times(data: Any) -> Any:
+    """Give each version a ``when`` with an explicit offset.
+
+    ``created_at`` is naive UTC and the server-made ``name`` ("30-Sep-2026 11:17 AM")
+    is that same UTC wall time, so neither can be shown to a user as local time.
+    """
+    versions = data.get("versions") if isinstance(data, dict) else None
+    if not isinstance(versions, list):
+        return data
+    stamped = [
+        {**v, "when": local_time(v.get("created_at"))} if isinstance(v, dict) else v
+        for v in versions
+    ]
+    return {
+        **data,
+        "versions": stamped,
+        "time_note": "created_at and the version name are UTC; `when` carries its offset.",
+    }
+
+
 def view_version_update(invocation: Invocation) -> HandlerResult:
     """Update one pipeline version by id. ``body`` is required."""
     project_id = require_project(invocation)

mammoth_cli-2.2.16/mammoth_cli/services/local_time.py

@@ -0,0 +1,19 @@
+"""Timestamps from the backend are naive UTC; show them with an explicit offset."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+
+def local_time(stamp: Any) -> str | None:
+    """A timestamp (UTC if it has no offset) as ISO in this machine's timezone."""
+    if not isinstance(stamp, str):
+        return None
+    try:
+        moment = datetime.fromisoformat(stamp)
+    except ValueError:
+        return stamp
+    if moment.tzinfo is None:
+        moment = moment.replace(tzinfo=UTC)
+    return moment.astimezone().isoformat(timespec="seconds")

{mammoth_cli-2.2.14 → mammoth_cli-2.2.16}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "mammoth-cli"
-version = "2.2.14"
+version = "2.2.16"
 description = "Command-line interface for the Mammoth Analytics platform"
 authors = [{name = "Mammoth Analytics", email = "support@mammoth.io"}]
 readme = "README.md"
 license = "LicenseRef-Proprietary"
 requires-python = ">=3.12,<3.15"
 dependencies = [
-    "mammoth-io (>=0.8.14,<0.9)",
+    "mammoth-io (>=0.8.15,<0.9)",
     "typer (>=0.27,<0.28)",
     "rich (>=15,<16)",
     "platformdirs (>=4.10,<5)",

{mammoth_cli-2.2.14 → mammoth_cli-2.2.16}/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.14 → mammoth_cli-2.2.16}/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.14 → mammoth_cli-2.2.16}/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

{mammoth_cli-2.2.14 → mammoth_cli-2.2.16}/spec/manifests/sdk-methods.yaml

@@ -428,8 +428,8 @@ methods:
     ''int | None'' = None, categories: ''list[Any] | None'' = None, activities: ''list[Any] | None''
     = None, resource_id: ''str | None'' = None, result: ''str | None'' = None, start_time: ''str |
     None'' = None, end_time: ''str | None'' = None, origin: ''str | None'' = None, user_ids: ''list[Any]
-    | None'' = None, parent_id: ''int | None'' = None, search_text: ''str | None'' = None) -> ''dict[str,
-    Any]'''
+    | None'' = None, parent_id: ''int | None'' = None, search_text: ''str | None'' = None, fields: ''str | None'' = None)
+    -> ''dict[str, Any]'''
   openapi_operation_ids: []
   canonical_command: activity.list
   alias_of: null