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

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

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

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

{mammoth_cli-2.2.18 → mammoth_cli-2.2.19}/mammoth_cli/bundled_skill/mammoth-cli/references/command-index.md

@@ -1,6 +1,6 @@
 # Published CLI command catalog
 
-This generated catalog is a lookup table for every command in the published CLI manifest, currently 645; each entry carries its release status line. It is a command-contract index, not an assertion that every backend/OpenAPI operation has a CLI binding. For an exact local CLI contract, run `mammoth schema get COMMAND_ID`; `mammoth capability list` is an API-binding inventory and can omit typed/local CLI routes. For focused workflows, read the [recipes index](recipes/index.md). Sensitive structured input must come from a private file or pipe; never put secrets in literal argv.
+This generated catalog is a lookup table for every command in the published CLI manifest, currently 646; each entry carries its release status line. It is a command-contract index, not an assertion that every backend/OpenAPI operation has a CLI binding. For an exact local CLI contract, run `mammoth schema get COMMAND_ID`; `mammoth capability list` is an API-binding inventory and can omit typed/local CLI routes. For focused workflows, read the [recipes index](recipes/index.md). Sensitive structured input must come from a private file or pipe; never put secrets in literal argv.
 
 Load only the applicable domain file:
 
@@ -26,7 +26,7 @@ Load only the applicable domain file:
 - [dashboard-style](commands/dashboard-style.md) — 10 published commands
 - [dashboard](commands/dashboard.md) — 96 published commands
 - [data-app](commands/data-app.md) — 12 published commands
-- [dataset](commands/dataset.md) — 21 published commands
+- [dataset](commands/dataset.md) — 22 published commands
 - [doctor](commands/doctor.md) — 1 published commands
 - [external-key](commands/external-key.md) — 4 published commands
 - [file](commands/file.md) — 9 published commands

{mammoth_cli-2.2.18 → mammoth_cli-2.2.19}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/dataset.md

@@ -192,6 +192,16 @@ Result: `DatasetRestoreResult`; mutation `benign_mutation`, confirmation `none`,
 
 Status on release: ran once on CLI 2.0.14 — write sweep 2026-09-18: exit 0 on release with CLI 2.0.14. job 312 restore_datasource -> status success. dataset list --project 21 confirms dataset 49 (name 'stores.csv 2') is back and visible alongside 48. Single invocation only.
 
+### `dataset.search`
+
+Run: `mammoth dataset search`. Exact input fields: `mammoth schema get dataset.search`.
+
+Example: `mammoth dataset search 'New Year Sale'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `DatasetSearchResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
 ### `dataset.trash`
 
 Run: `mammoth dataset trash`. Exact input fields: `mammoth schema get dataset.trash`.

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

@@ -38,7 +38,11 @@ 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. 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,
+optional). To find the dataset that holds a value you were given (a campaign,
+a region, a product) when its name does not say, run `dataset search TERM`: it
+returns the project's datasets whose name, column names or sampled column
+values contain TERM, each with the matched column and value. `dataset find`
+and `browse` search match names only. A `browse` search hit carries `dataset_id` or `view_id`: use those,
 never the tree `id`.
 
 ```bash

{mammoth_cli-2.2.18 → mammoth_cli-2.2.19}/mammoth_cli/commands/dataset.py

@@ -395,6 +395,48 @@ def dataset_find(invocation: Invocation) -> HandlerResult:
     return result, meta
 
 
+#: Matches kept per dataset in a ``dataset search`` row; the rest are counted, not listed.
+_SEARCH_MATCHES_PER_DATASET = 5
+
+
+def _search_row(hit: dict[str, Any]) -> dict[str, Any]:
+    """One ``dataset search`` row: the dataset and the first places its content matched."""
+    matches = hit.get("matches") or []
+    row: dict[str, Any] = {
+        "id": hit.get("id"),
+        "name": hit.get("name"),
+        "matches": matches[:_SEARCH_MATCHES_PER_DATASET],
+    }
+    if len(matches) > _SEARCH_MATCHES_PER_DATASET:
+        row["more_matches"] = len(matches) - _SEARCH_MATCHES_PER_DATASET
+    return row
+
+
+def dataset_search(invocation: Invocation) -> HandlerResult:
+    """Find the project's datasets whose name, column names or sampled values hold TERM.
+
+    Read-only: one server call. Each match names where the term was found (``name``,
+    ``column`` or ``value``) with the column and the sampled value, so the dataset that
+    holds "New Year Sale" in a ``campaign`` column is found without knowing its name.
+    Sampled values come from the profile, which keeps up to 30 per text column, so a
+    dataset never profiled matches on name and columns only.
+    """
+    term = _require_string_positional(invocation, "term")
+    project_id = require_project(invocation)
+    with open_service(invocation) as (service, auth):
+        data = service.call(
+            "mammoth.api.datasets.DatasetsAPI.search", term=term, project_id=project_id
+        )
+    hits = data.get("datasets", []) if isinstance(data, dict) else []
+    kept, omitted = fit_budget([_search_row(h) for h in hits if isinstance(h, dict)])
+    result: dict[str, Any] = {"term": term, "datasets": kept, "matched": len(hits)}
+    if omitted:
+        result["omitted"] = omitted
+    if note := ambiguity_note(len(hits), term):
+        result["note"] = note
+    return result, _meta(invocation, auth.workspace_id, project_id)
+
+
 def dataset_list(invocation: Invocation) -> HandlerResult:
     """List datasets in the active project, newest first, each with what tells them apart.
 

{mammoth_cli-2.2.18 → mammoth_cli-2.2.19}/mammoth_cli/commands/registry.py

@@ -318,6 +318,7 @@ HANDLERS: dict[str, Handler] = {
     # dataset family
     "dataset.find": dataset_cmd.dataset_find,
     "dataset.list": dataset_cmd.dataset_list,
+    "dataset.search": dataset_cmd.dataset_search,
     "dataset.get": dataset_cmd.dataset_get,
     "dataset.batch-data": dataset_cmd.dataset_batch_data,
     "dataset.data": dataset_cmd.dataset_data,

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

@@ -388,6 +388,7 @@ _LOCAL_COMMANDS = frozenset(
         "context.project.status",
         "context.project.use",
         "dataset.find",
+        "dataset.search",
         "doctor",
         "project.check",
         "project.ensure",

{mammoth_cli-2.2.18 → mammoth_cli-2.2.19}/mammoth_cli/services/positionals.py

@@ -650,6 +650,16 @@ POSITIONAL_OVERRIDES: dict[str, tuple[PositionalSpec, ...]] = {
             example_value="sales",
         ),
     ),
+    "dataset.search": (
+        PositionalSpec(
+            name="term",
+            type=str,
+            required=True,
+            help="Text to find in dataset names, column names or sampled column values "
+            "(case-insensitive, at least 2 characters).",
+            example_value="New Year Sale",
+        ),
+    ),
     "folder.find": (
         PositionalSpec(
             name="name_substring",

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

@@ -1,13 +1,13 @@
 [project]
 name = "mammoth-cli"
-version = "2.2.18"
+version = "2.2.19"
 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.15,<0.9)",
+    "mammoth-io (>=0.8.16,<0.9)",
     "typer (>=0.27,<0.28)",
     "rich (>=15,<16)",
     "platformdirs (>=4.10,<5)",

{mammoth_cli-2.2.18 → mammoth_cli-2.2.19}/spec/manifests/commands/dataset.yaml

@@ -818,6 +818,46 @@ commands:
   undo_test: null
   known_restrictions: null
   reviewed_by: primary
+- command_id: dataset.search
+  command_path: dataset search
+  disposition: command
+  alias_of: null
+  operation_ids: []
+  positionals:
+  - name: term
+    type: str
+    required: true
+    metavar: TERM
+    falls_back_to_field: null
+    help: Text to find in dataset names, column names or sampled column values (case-insensitive,
+      at least 2 characters).
+  options: []
+  sdk_symbol: mammoth_cli.commands.dataset.search
+  sdk_conversion: Call mammoth_cli.commands.dataset.search with validated request fields.
+  request_model: DatasetSearchRequest
+  result_model: DatasetSearchResult
+  mutation_class: read
+  confirmation: none
+  wait_policy: not_async
+  pagination_policy: none
+  acceptance_evidence: live_read_only
+  live_test: null
+  live_exemption_reason: Read-only composite over the project's datasets search route.
+  contract_fixture: null
+  required_fixture_guard: null
+  secret_fields: []
+  human_example: mammoth dataset search TERM --help
+  agent_example: mammoth dataset search 'New Year Sale'
+  unit_tests:
+  - UT-DATASET-SEARCH
+  contract_tests:
+  - CT-DATASET-SEARCH-HUMAN
+  - CT-DATASET-SEARCH-JSON
+  - CT-DATASET-SEARCH-ERROR
+  draft_test: null
+  undo_test: null
+  known_restrictions: null
+  reviewed_by: primary
 - command_id: dataset.trash
   command_path: dataset trash
   disposition: command

{mammoth_cli-2.2.18 → mammoth_cli-2.2.19}/spec/manifests/sdk-methods.yaml

@@ -3833,6 +3833,18 @@ methods:
   pagination_policy: null
   secret_fields: []
   reviewed_by: primary
+- sdk_symbol: mammoth.api.datasets.DatasetsAPI.search
+  implementation_origin: mammoth.api.datasets.DatasetsAPI.search
+  signature: 'search(self, term: ''str'', workspace_id: ''int | None'' = None, project_id: ''int | None'' = None) -> ''dict[str, Any]'''
+  openapi_operation_ids: []
+  canonical_command: null
+  alias_of: null
+  no_command_reason: SDK-only helper; no reviewed CLI command.
+  mutation_class: null
+  wait_policy: null
+  pagination_policy: null
+  secret_fields: []
+  reviewed_by: primary
 - sdk_symbol: mammoth.api.datasets.DatasetsAPI.trash
   implementation_origin: mammoth.api.datasets.DatasetsAPI.trash
   signature: 'trash(self, dataset_id: ''int'', workspace_id: ''int | None'' = None, project_id: ''int | None'' = None) -> ''dict[str, Any]'''