mammoth-cli 2.1.4__tar.gz → 2.1.5__tar.gz

{mammoth_cli-2.1.4 → mammoth_cli-2.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.1.4
+Version: 2.1.5
 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.1
+Requires-Dist: mammoth-io<0.9,>=0.8.2
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.12.5
 Requires-Dist: pyyaml<7,>=6

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

{mammoth_cli-2.1.4 → mammoth_cli-2.1.5}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/scheduling.md

@@ -23,6 +23,11 @@ request:
   an id you already have (for example from a dataset's own automation/task
   metadata) instead.
 
+PDF or image intake (`append_data` + `new_data_addition_in_folder`) needs one
+destination dataset that already has a saved extraction recipe and a name
+pattern the file name matches; a password-protected or unreadable file holds
+for input. Read `automation capabilities` before you promise it.
+
 `schema find "recurring work"` phrasing (e.g. "schedule a daily refresh",
 "run every week automatically") resolves to `automation create`.
 

{mammoth_cli-2.1.4 → mammoth_cli-2.1.5}/mammoth_cli/commands/activity.py

@@ -12,6 +12,7 @@ public SDK method named by the command's reviewed manifest ``sdk_symbol``.
 from __future__ import annotations
 
 import json
+from datetime import UTC, datetime
 from typing import Any
 
 from mammoth_cli.errors.envelope import (
@@ -157,14 +158,96 @@ 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"
+
+
+def _close_time_window(kwargs: dict[str, Any]) -> str | None:
+    """Give a lone ``start_time`` or ``end_time`` its missing bound; say so.
+
+    The backend applies the time filter only when BOTH bounds are present
+    (activity_logs/manager.py ``_get_time_filters``) and otherwise lists the
+    latest entries of all time -- so "what changed today" with only a
+    ``start_time`` answered from the wrong window.
+    """
+    start, end = kwargs.get("start_time"), kwargs.get("end_time")
+    if bool(start) == bool(end):
+        return None
+    if start:
+        kwargs["end_time"] = datetime.now(UTC).strftime(_TIME_FORMAT)
+        return f"end_time was not given; the window runs to now ({kwargs['end_time']} UTC)."
+    kwargs["start_time"] = _EPOCH
+    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:
+        users = service.call(_WORKSPACE_USERS_SYMBOL)
+    except Exception:  # noqa: BLE001 -- a name is a convenience; the id is always shown
+        return {}
+    return {u["id"]: u["email"] for u in users if isinstance(u, dict) and u.get("email")}
+
+
+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."""
+    details = entry.get("details") if isinstance(entry.get("details"), dict) else {}
+    primary = entry.get("primary_object") if isinstance(entry.get("primary_object"), dict) else {}
+    user_id = entry.get("user_id")
+    change = {
+        "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"),
+    }
+    if details.get("task_name"):
+        change["task"] = details["task_name"]
+    return change
+
+
+def _with_changes(service: Any, data: Any, note: str | None) -> Any:
+    """Add ``changes``: each entry with its time, user and action (no entry dropped)."""
+    logs = data.get("activity_logs") if isinstance(data, dict) else None
+    if not isinstance(logs, list):
+        return data
+    emails = _user_emails(service)
+    changes = [_change(entry, emails) for entry in logs if isinstance(entry, dict)]
+    extra = {"time_window_note": note} if note else {}
+    return {**data, "changes": changes, **extra}
+
+
 def activity_list(invocation: Invocation) -> HandlerResult:
-    """List activity logs in the active workspace, with optional filters."""
+    """List activity logs in the active workspace, with optional filters.
+
+    ``changes`` lists each entry with its ``when`` (ISO, this machine's UTC
+    offset), ``user_id`` and ``user``, ``action``, ``object`` and ``result``,
+    so "who changed this view today" is answered from the list, not from its
+    absence.
+    """
     document = _bound_document(invocation)
     _refuse_bare_resource_id(document)
     kwargs: dict[str, Any] = {}
     _forward_optional(document, kwargs, _LIST_OPTIONAL)
+    note = _close_time_window(kwargs)
     with open_service(invocation) as (service, auth):
-        data = service.call(_symbol(invocation), **kwargs)
+        data = _with_changes(service, service.call(_symbol(invocation), **kwargs), note)
     return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))
 
 

{mammoth_cli-2.1.4 → mammoth_cli-2.1.5}/mammoth_cli/commands/dashboard.py

@@ -17,7 +17,7 @@ from typing import Any, Literal, cast
 from mammoth.models.dashboards import AddPagesSpec
 from pydantic import ValidationError
 
-from mammoth_cli.commands.view import view_profiles
+from mammoth_cli.commands.view import _FIND_DATASET_SYMBOL, view_profiles
 from mammoth_cli.context import profiles
 from mammoth_cli.errors.envelope import (
     CODE_INVALID_ARGUMENT,
@@ -392,9 +392,48 @@ def dashboard_get(invocation: Invocation) -> HandlerResult:
         if not invocation.readback:
             data = _with_board_values(service, auth, {"dashboard_id": dashboard_id}, data)
             data = _with_board_project(data)
+            data = _with_source_datasets(service, invocation, auth.workspace_id, data)
     return data, _meta(invocation, auth.workspace_id)
 
 
+def _source_dataset(service: Any, invocation: Invocation, workspace_id: Any, view_id: int) -> Any:
+    """The dataset that owns ``view_id``: remembered, else looked up; never raises."""
+    profile_name = invocation.profile or profiles.get_selected()
+    remembered = parents.lookup(profile_name, workspace_id, view_id)
+    if remembered is not None:
+        return {"view_id": view_id, "dataset_id": remembered}
+    try:
+        dataset_id = int(service.call(_FIND_DATASET_SYMBOL, dataview_id=view_id))
+    except Exception as exc:  # noqa: BLE001 -- one unreadable source must not hide the others
+        return {"view_id": view_id, "dataset_id": None, "error": f"{type(exc).__name__}: {exc}"}
+    parents.remember(profile_name, workspace_id, {view_id: dataset_id})
+    return {"view_id": view_id, "dataset_id": dataset_id}
+
+
+def _with_source_datasets(
+    service: Any, invocation: Invocation, workspace_id: Any, data: Any
+) -> Any:
+    """Label each source: a board's ``sources`` are VIEW ids, never dataset ids.
+
+    An agent read 3882 from ``sources`` as a dataset id and got a 403
+    (RT21-01). ``source_views`` gives each source's ``view_id`` and the
+    ``dataset_id`` that owns it.
+    """
+    sources = data.get("sources") if isinstance(data, dict) else None
+    if not isinstance(sources, list) or not sources:
+        return data
+    views = [
+        _source_dataset(service, invocation, workspace_id, view_id)
+        for view_id in sources
+        if isinstance(view_id, int)
+    ]
+    return {
+        **data,
+        "source_views": views,
+        "sources_note": "sources are view ids; use a source's dataset_id for dataset commands.",
+    }
+
+
 def _with_board_project(data: Any) -> Any:
     """Name the project the board lives in; ``None`` when the backend does not say."""
     data = _dump_model(data)
@@ -714,7 +753,7 @@ def _with_board_values(service: Any, auth: Any, positionals: dict[str, Any], dat
     data = _dump_model(data)
     if not isinstance(data, dict):
         return data
-    dashboard_id = positionals.get("dashboard_id") or data.get("id") or data.get("dashboard_id")
+    dashboard_id = positionals.get("dashboard_id") or data.get("id")
     if not isinstance(dashboard_id, int):
         return {**data, "values": {"unavailable": "the result names no dashboard id"}}
     return {

{mammoth_cli-2.1.4 → mammoth_cli-2.1.5}/mammoth_cli/commands/dataset.py

@@ -32,8 +32,10 @@ from mammoth_cli.runtime.new_data import with_file_upload_path
 from mammoth_cli.runtime.session import open_service, require_project
 from mammoth_cli.services.listing import (
     DATASET_LIST_FIELDS,
+    ambiguity_note,
     dataset_summary,
     fit_budget,
+    name_hit,
     search_page,
 )
 
@@ -170,16 +172,31 @@ def _find_in_projects(
                     {
                         "project_id": project_id,
                         "project_name": project.get("name"),
-                        "id": dataset.get("id"),
-                        "name": name,
+                        **name_hit(dataset),
                     }
                 )
     return matches
 
 
-def _other_projects(service: Any, project_id: int) -> list[dict[str, Any]]:
+def _other_projects(visible: list[dict[str, Any]], project_id: int) -> list[dict[str, Any]]:
     """Every visible project except ``project_id``."""
-    return [p for p in _visible_projects(service) if p.get("id") != project_id]
+    return [p for p in visible if p.get("id") != project_id]
+
+
+def named_project(service: Any, project_id: int, visible: list[dict[str, Any]]) -> dict[str, Any]:
+    """``{"id", "name"}`` of ``project_id``, so a match can say where it was found.
+
+    A search scoped by ``--project`` knew only the id, and its matches came back
+    with ``project_name: None``: the agent could not tell the user which project
+    held the dataset.
+    """
+    for project in visible:
+        if project.get("id") == project_id:
+            return project
+    record = service.call("mammoth.api.projects.ProjectsAPI.get", project_id=project_id)
+    record = record.model_dump(mode="json") if hasattr(record, "model_dump") else record
+    record = record.get("project", record) if isinstance(record, dict) else {}
+    return {"id": project_id, "name": record.get("name")}
 
 
 def dataset_find(invocation: Invocation) -> HandlerResult:
@@ -195,26 +212,30 @@ def dataset_find(invocation: Invocation) -> HandlerResult:
     name_substring = _require_string_positional(invocation, "name substring")
     needle = name_substring.lower()
     with open_service(invocation) as (service, auth):
+        visible = _visible_projects(service)
         if invocation.project is not None:
-            projects: list[dict[str, Any]] = [{"id": invocation.project, "name": None}]
+            projects: list[dict[str, Any]] = [named_project(service, invocation.project, visible)]
             matches = _find_in_projects(service, needle, projects)
             if not matches:
-                others = _other_projects(service, invocation.project)
+                others = _other_projects(visible, invocation.project)
                 matches = _find_in_projects(service, needle, others)
                 projects += others
         else:
-            projects = _visible_projects(service)
+            projects = visible
             matches = _find_in_projects(service, needle, projects)
         meta = {
             "profile": invocation.profile,
             "workspace_id": auth.workspace_id,
             "project_id": invocation.project,
         }
-    return {
+    result: dict[str, Any] = {
         "matches": matches,
         "projects_searched": len(projects),
         "projects_truncated": len(projects) >= _MAX_PROJECTS_SEARCHED,
-    }, meta
+    }
+    if note := ambiguity_note(len(matches), name_substring):
+        result["note"] = note
+    return result, meta
 
 
 def dataset_list(invocation: Invocation) -> HandlerResult:
@@ -264,7 +285,7 @@ def _dataset_name_search(
         page = search_page(records, name, int(document.get("offset", 0)), document.get("limit"))
         if page["matched"] == 0:
             elsewhere = _find_in_projects(
-                service, name.lower(), _other_projects(service, project_id)
+                service, name.lower(), _other_projects(_visible_projects(service), project_id)
             )
             if elsewhere:
                 page["in_other_projects"] = elsewhere
@@ -504,14 +525,21 @@ def dataset_interpretation(invocation: Invocation) -> HandlerResult:
 
     ``--input`` carries ``user_instruction`` (plain English, e.g. one of the
     suggestions ``dataset get`` shows), a ``structure_map`` from an earlier
-    preview, or a ``destination_dataset_id``; at least one is required.
+    preview, or a ``destination_dataset_id``; at least one is required. ``confirm``
+    alone also takes ``mode``: ``"original"`` keeps the file in its uploaded layout
+    (no other field then), ``"interpreted"`` is the default.
     """
     project_id = require_project(invocation)
     dataset_id = _require_int_positional(invocation, "dataset id")
     document = invocation.load_input() or {}
     kwargs: dict[str, Any] = {"dataset_id": dataset_id, "project_id": project_id}
-    _forward_optional(document, kwargs, _INTERPRETATION_FIELDS)
-    if not any(field in kwargs for field in _INTERPRETATION_FIELDS):
+    confirming = invocation.command_id == "dataset.interpretation.confirm"
+    _forward_optional(
+        document,
+        kwargs,
+        (*_INTERPRETATION_FIELDS, "mode") if confirming else _INTERPRETATION_FIELDS,
+    )
+    if not any(field in kwargs for field in (*_INTERPRETATION_FIELDS, "mode")):
         raise CliError(
             code=CODE_MISSING_ARGUMENT,
             message="Say how to read the file: pass one of " + ", ".join(_INTERPRETATION_FIELDS),

{mammoth_cli-2.1.4 → mammoth_cli-2.1.5}/mammoth_cli/commands/folder.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 from typing import Any
 
+from mammoth_cli.commands.dataset import named_project
 from mammoth_cli.errors.envelope import (
     CODE_INVALID_ARGUMENT,
     CODE_MISSING_ARGUMENT,
@@ -121,11 +122,12 @@ def folder_find(invocation: Invocation) -> HandlerResult:
     needle = name_substring.lower()
     matches: list[dict[str, Any]] = []
     with open_service(invocation) as (service, auth):
+        listing = service.list_projects(limit=_MAX_PROJECTS_SEARCHED)
+        visible = list(listing.get("projects", [])) if isinstance(listing, dict) else []
         if invocation.project is not None:
-            projects: list[dict[str, Any]] = [{"id": invocation.project, "name": None}]
+            projects: list[dict[str, Any]] = [named_project(service, invocation.project, visible)]
         else:
-            listing = service.list_projects(limit=_MAX_PROJECTS_SEARCHED)
-            projects = list(listing.get("projects", [])) if isinstance(listing, dict) else []
+            projects = visible
         for project in projects:
             project_id = project.get("id")
             if project_id is None:
@@ -136,8 +138,7 @@ def folder_find(invocation: Invocation) -> HandlerResult:
             response = service.call(
                 "mammoth.api.folders.FoldersAPI.list", project_id=project_id, limit=100
             )
-            folders = response.get("folders", []) if isinstance(response, dict) else []
-            for folder in folders:
+            for folder in _folders_of(response):
                 name = folder.get("name") if isinstance(folder, dict) else None
                 if isinstance(name, str) and needle in name.lower():
                     matches.append(
@@ -265,9 +266,7 @@ def folder_move(invocation: Invocation) -> HandlerResult:
     if not any(field in kwargs for field in ("resource_ids", "dataset_ids", "view_ids")):
         raise CliError(
             code=CODE_MISSING_FIELD,
-            message=(
-                "This command requires one of 'resource_ids', 'dataset_ids', " "or 'view_ids'."
-            ),
+            message=("This command requires one of 'resource_ids', 'dataset_ids', or 'view_ids'."),
             exit_status=EXIT_USAGE,
             hint=(
                 "Pass it via --input, e.g. "
@@ -275,10 +274,67 @@ def folder_move(invocation: Invocation) -> HandlerResult:
             ),
         )
     with open_service(invocation) as (service, auth):
+        _resolve_folder_fields(service, project_id, kwargs)
         data = service.call(_symbol(invocation), **kwargs)
     return data, _meta(invocation, auth.workspace_id, project_id)
 
 
+_FOLDER_LIST_SYMBOL = "mammoth.api.folders.FoldersAPI.list"
+_FOLDER_PAGE = 100
+
+
+def _folders_of(page: Any) -> list[dict[str, Any]]:
+    """The folder records of a ``FoldersAPI.list`` page (a model or a dict)."""
+    page = page.model_dump(mode="json") if hasattr(page, "model_dump") else page
+    folders = page.get("folders", []) if isinstance(page, dict) else []
+    return [f for f in folders if isinstance(f, dict)]
+
+
+def _project_folders(service: Any, project_id: int) -> list[dict[str, Any]]:
+    """Every folder of the project (``id`` and ``resource_id`` each), page by page."""
+    folders: list[dict[str, Any]] = []
+    while True:
+        page = service.call(
+            _FOLDER_LIST_SYMBOL, project_id=project_id, limit=_FOLDER_PAGE, offset=len(folders)
+        )
+        batch = _folders_of(page)
+        folders += batch
+        if len(batch) < _FOLDER_PAGE:
+            return folders
+
+
+def _resolve_folder_fields(service: Any, project_id: int, kwargs: dict[str, Any]) -> None:
+    """Turn a folder's ``resource_id`` into the ``id`` the backend wants, in place.
+
+    ``target_folder_resource_id`` is named for a resource id but the backend
+    wants the folder's own ``id``. A value that is a folder's ``id`` is sent
+    as it is; one that is only some folder's ``resource_id`` is replaced by
+    that folder's ``id``; one that is both (two different folders) is refused.
+    """
+    for field in ("target_folder_resource_id", "source_folder_resource_id"):
+        value = kwargs.get(field)
+        if value in (None, "", "root"):
+            continue
+        folders = _project_folders(service, project_id)
+        by_id = [f for f in folders if str(f.get("id")) == str(value)]
+        by_resource = [f for f in folders if str(f.get("resource_id")) == str(value)]
+        if by_id and by_resource and by_id != by_resource:
+            raise CliError(
+                code=CODE_INVALID_ARGUMENT,
+                message=(
+                    f"'{field}' {value} is the id of folder '{by_id[0].get('name')}' and the "
+                    f"resource_id of folder '{by_resource[0].get('name')}'."
+                ),
+                exit_status=EXIT_USAGE,
+                hint=(
+                    f"Pass the folder's id ({by_id[0].get('id')} or {by_resource[0].get('id')}) "
+                    "as it appears in 'folder list'."
+                ),
+            )
+        if not by_id and by_resource:
+            kwargs[field] = by_resource[0].get("id")
+
+
 def folder_trash(invocation: Invocation) -> HandlerResult:
     """Move one folder to the project trash (reversible)."""
     project_id = require_project(invocation)