mostlyright-data 0.29.13__tar.gz → 0.30.1__tar.gz

{mostlyright_data-0.29.13 → mostlyright_data-0.30.1}/PKG-INFO

@@ -1,13 +1,16 @@
 Metadata-Version: 2.4
 Name: mostlyright-data
-Version: 0.29.13
+Version: 0.30.1
 Summary: Mostly Right hosted CLI for reviewed datasets
 Project-URL: Homepage, https://mostlyright.md/
 Project-URL: Documentation, https://mostlyright.md/docs/guides/cli/
 Requires-Python: >=3.11
 Provides-Extra: build
+Requires-Dist: hatch-vcs==0.5.0; extra == 'build'
 Requires-Dist: hatchling==1.28.0; extra == 'build'
+Requires-Dist: setuptools-scm==10.3.4; extra == 'build'
 Requires-Dist: uv-build==0.11.3; extra == 'build'
+Requires-Dist: vcs-versioning==2.6.0; extra == 'build'
 Description-Content-Type: text/markdown
 
 # mostlyright-data

{mostlyright_data-0.29.13 → mostlyright_data-0.30.1}/pyproject.toml

@@ -1,6 +1,8 @@
 [project]
 name = "mostlyright-data"
-version = "0.29.13"
+# The release tag is the version. `hatch-vcs` reads it from git at build time, so a release is a
+# `v*` tag push and no file states the number. See docs/RELEASING.md.
+dynamic = ["version"]
 description = "Mostly Right hosted CLI for reviewed datasets"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -17,8 +19,11 @@ mr-data = "mostlyright.data_harness.thin.router:main"
 
 [project.optional-dependencies]
 build = [
+    "hatch-vcs==0.5.0",
     "hatchling==1.28.0",
+    "setuptools-scm==10.3.4",
     "uv-build==0.11.3",
+    "vcs-versioning==2.6.0",
 ]
 
 [dependency-groups]
@@ -38,9 +43,34 @@ dev = [
 pypi-release = ["twine==6.2.0"]
 
 [build-system]
-requires = ["hatchling==1.28.0"]
+requires = [
+    "hatch-vcs==0.5.0",
+    "hatchling==1.28.0",
+    "setuptools-scm==10.3.4",
+    "vcs-versioning==2.6.0",
+]
 build-backend = "hatchling.build"
 
+# `uv sync` rebuilds the editable install when the commit or the tags change, so the installed
+# version follows a new release tag.
+[tool.uv]
+cache-keys = [{ file = "pyproject.toml" }, { git = { commit = true, tags = true } }]
+
+[tool.hatch.version]
+source = "vcs"
+
+# Only `v<digits>` tags are releases. A commit after the last one builds as that release's
+# version, as a checkout between releases always has: `mr-data propose` records the version as
+# plain X.Y.Z and refuses anything else. A tree without git history builds as 0.0.0.
+[tool.hatch.version.raw-options]
+tag_regex = "^v(?P<version>[0-9]+(?:\\.[0-9]+)*(?:(?:a|b|rc)[0-9]+)?)$"
+version_scheme = "only-version"
+local_scheme = "no-local-version"
+fallback_version = "0.0.0"
+
+[tool.hatch.version.raw-options.scm.git]
+describe_command = ["git", "describe", "--dirty", "--tags", "--long", "--match", "v[0-9]*"]
+
 [tool.hatch.build.targets.wheel]
 sources = ["src"]
 only-include = [

{mostlyright_data-0.29.13 → mostlyright_data-0.30.1}/skills/mr-data-build/references/commands.md

@@ -30,7 +30,7 @@ run in full.
 | `mr-data runs` | Report this workspace's own runs: identifier, mode, state and creation time, plus the failure triple of any that failed and whether that failure was the execution room's. `--dataset DATASET_ID` narrows it to one dataset's runs, so "what have I run for this dataset?" is one scoped read, and a value that is not an identifier is refused `THIN_ARGUMENT_INVALID`. `--status` and `--mode` narrow it too and are refused `THIN_ARGUMENT_INVALID` for a word outside the seven states or the six modes; the three combine. Studio narrows before it cuts a page, so a filtered page holds the newest runs that match however many runs the workspace has. `--limit` says how many, and pages are followed to reach it; a listing that does not end says how many were read and suggests a smaller `--limit` or a narrower filter. The answer prints `next_cursor`, and `--cursor` continues from it. |
 | `mr-data watch` | Stream one run's live progress under the durable event type of each stage, resuming across stream cuts. Exits non-zero when the run failed. |
 | `mr-data query` | Run one bounded read-only SQL statement over a finished run's own table and print the rows. Name the table `run_table` in the SQL, whatever the recipe called it. Bounded on rows, on answer bytes and on time, and refused by name when a bound is crossed. When no worker can answer, the refusal names `mr-data download RUN_ID` as `fallback_command`, which brings the table here to read locally. The question is asked through Mostly Right Cloud; while its usage paywall is on and the workspace is unsubscribed, each answered query counts toward the person's monthly allowance, and a spent allowance refuses `THIN_USAGE_LIMIT`. A refusal after the question was queued names its `query_id`; running the same command again reads that query back. |
-| `mr-data search` | `search VERB` prepares and tests versioned search for a new table through Studio; no model or index runs on this computer. The verbs are `inspect`, `sample`, `values`, `propose`, `configure`, `validate`, `add-cases`, `explain`, `preview`, `evaluate`, `estimate`, `build`, `status`, `activate`, `cancel` and `rollback`. `inspect`, `propose` and `validate` also take `--recipe FILE` before registration. A build returns promptly with job coordinates, and an operation Studio does not serve answers a typed capability error. [Prepare search](preparing-table-search.md) says how it fits a build. |
+| `mr-data search` | `search VERB` prepares and tests versioned search for a new table through Studio; no model or index runs on this computer. The verbs are `inspect`, `sample`, `values`, `propose`, `configure`, `validate`, `add-cases`, `explain`, `preview`, `evaluate`, `estimate`, `build`, `status`, `activate`, `cancel`, `rollback`, `locate` and `try`. `inspect`, `propose` and `validate` also take `--recipe FILE` before registration. `validate --spec` checks a spec and its evaluation cases against the pinned contract without sending anything. `locate` resolves evaluation-case rows to locators, and `try` runs one query against the live search. A build returns promptly with job coordinates, and an operation Studio does not serve answers a typed capability error. [Prepare search](preparing-table-search.md) says how it fits a build. |
 | `mr-data peek` | Print the columns, their logical types and the first rows of one run's table. The type comes off the run's own column profile where the preview carries none, so `type` is null only for a run that sealed no profile. |
 | `mr-data receipt` | Print what one run recorded about how it was built: every source it fetched and what those bytes hashed to, the coverage it delivered, and the members of its raw snapshot. |
 | `mr-data checks` | Report how each check the recipe declared came out — the name, whether it passed, what it found. Exits non-zero when one did not pass. |

mostlyright_data-0.30.1/skills/mr-data-build/references/preparing-table-search.md

@@ -0,0 +1,362 @@
+# Prepare table search
+
+This page takes a new table from declared columns to fast, well-ranked search. Studio does the
+work. No model, index or database runs on this computer. Every verb has its own help, for
+example `mr-data search validate --help`.
+
+The steps below build search at the level of a dedicated search site: typo-tolerant titles,
+person and brand lookups, category words that become filters, sort words that become sorts,
+meaning-based retrieval over descriptions, and a planner that turns a sentence into a plan.
+
+## The verbs
+
+| Verb | What it does |
+|---|---|
+| `search inspect --recipe FILE` | Probes whether the deployment serves search authoring. |
+| `search propose --recipe FILE` | Returns a starter spec. It never edits the file. |
+| `search validate` | Checks a spec and its evaluation cases against the pinned Studio contract, then asks Studio. |
+| `search locate` | Turns a title, a year or an id into the `[part, row]` locator an evaluation case needs. |
+| `search configure` | Stores a draft revision of the spec, with its evaluation cases. |
+| `search build` | Queues a search build for a sealed version, or for one revision with `--revision`. |
+| `search status` | Reports package readiness, job progress and the failure reason. |
+| `search try` | Runs one query against the table's live search and prints rows, plan and timings. |
+| `search activate` | Switches the version's live search to a built generation. |
+| `search rollback` | Switches back to an earlier generation. |
+| `search explain` | Shows how Studio parses one query into filters and sorts. |
+| `search cancel` | Cancels a search job. It never undoes a finished generation. |
+
+Exit codes are stable. 0 means complete. 1 means failed or invalid. 3 means still running or
+served by the fallback scan. 4 means ambiguous.
+
+## 1. Check the capability
+
+Probe the deployment before you add `table.search` to a recipe:
+
+```sh
+mr-data search inspect --recipe recipe.json --json
+```
+
+Read a refusal from stderr. Its `code` is the typed discriminator. Treat `THIN_NOT_FOUND` as
+missing search support only when `error` begins with
+`Studio has no such resource for /v4/search/recipe-inspection`. Treat
+`THIN_SEARCH_CAPABILITY_UNAVAILABLE` as a capability limit too. Any other refusal is not
+capability evidence. That includes 401, 403, 429, timeouts and invalid responses. Resolve it.
+
+When the brief does not mention search, search is optional only while the capability is missing.
+Then omit `table.search`, keep the drafted intent beside the recipe, and record the limit in the
+dataset's Sources and decisions note. Never put that limit in the description, title or topics.
+When the user explicitly requires semantic retrieval or the planner, do not register a recipe
+without it. Report the limit and wait.
+
+## 2. Choose keyword and semantic columns
+
+Keyword columns feed the lexical index. They give exact and typo-tolerant word matches. Use them
+for titles, names, people, brands, keywords and tags. The cap is 16 columns. Each must be a
+declared `string` or `json` column.
+
+Semantic columns feed meaning-based retrieval. Use them for prose that a user paraphrases: a
+title and a plot, a product description, an abstract. The cap is 16. Keep identifiers,
+measurements, dates and short codes out of them. Embeddings run on the hosted worker with a pinned
+multilingual model. Private table text does not leave the platform for them.
+
+A table with no useful prose keeps `semantic_columns` empty. A semantic-only table may keep
+`keyword_columns` empty. Its lexical capability then stays `unavailable`.
+
+## 3. Fill the field roles
+
+`field_roles` tells search what each column means. The ranking and the planner use it.
+
+| Role | Column type | Use |
+|---|---|---|
+| `title` | string | The name people type. It gets typo correction and the strongest boost. |
+| `person` | string | People. A query that names a person filters on this column. |
+| `brand` | string | Companies, studios, labels or makers. |
+| `category` | string | The main category, such as `genres`. |
+| `language`, `country` | string | Language and country codes or names. |
+| `date` | date, timestamp or integer | Release or event date. Decade words use it. |
+| `popularity`, `votes`, `rating` | integer, decimal or float | Tie-breaks and "best" or "most popular" sorts. |
+| `identifier` | any | The row's own id. `search locate --id` uses it. |
+| `description` | any | The main prose column. |
+| `image` | any | A poster or thumbnail URL for result cards. |
+| `emoji` | string | Each row's emojis. A query emoji finds the rows that carry it, and a word such as "shark" finds the rows that carry its emoji. |
+
+Set a role to `null` or leave it out when no column fits. Never point a role at a column of
+another type. Studio refuses it.
+
+## 4. Add derived text columns past the 16-column cap
+
+A wide table often has more searchable text than 16 columns. Fold related columns into one derived
+column in the recipe's transform. A movie table might fold director, cast, creators and writers
+into `people_text`. It might fold keywords, tagline, companies, networks and franchise into
+`meta_text`. Read [transforms](transforms.md) for the grammar. A transform step can write:
+
+```sql
+select *,
+  concat_ws(' ', director, cast_top10, created_by, writers) as people_text,
+  concat_ws(' ', keywords, tagline, production_companies, networks, franchise) as meta_text
+from movies
+```
+
+Then list `people_text` and `meta_text` in `keyword_columns`, and point the `person` role at
+`people_text` when no single person column covers everyone. Describe each derived column in its
+column description.
+
+## 5. Declare display, filter, sort and soft columns
+
+- `display_columns` (1 to 16) are the columns a result row carries. Include the title, the date,
+  the identifier and the image. `search try` and `search locate` read these columns. Without
+  `display_columns`, a package shows the identifier, the title and the keyword columns.
+- `filterable_columns` (up to 64) are the columns a plan may filter on. Include categories,
+  languages, dates and numbers. Every field-role column is filterable too.
+- `sortable_columns` are the columns a plan may sort on. Include popularity, rating, vote count,
+  date and money columns.
+- `soft_preference_columns` (up to 16, string only) are moods and tones. A match moves a row up and
+  never filters it out.
+- `soft_preference_sets` joins columns that hold the same preference, such as `mood_1` and
+  `mood_2`. Each key is a `soft_preference_columns` entry. Its value lists 1 to 7 other string
+  columns. A row matches when any column of the set holds the value. Up to 16 sets.
+- `multi_value_columns` (up to 16, string only) are columns whose cells are comma-separated lists,
+  such as genres `"Action, Comedy"`. Each trimmed item is a filter value. In a
+  `table-search-package.v2` package, `eq`, `in` and `ne` compare against the items, and the value
+  list shows items, not whole cells. Give such a column `eq` aliases.
+
+## 6. Add aliases for categories
+
+An alias maps a phrase to an exact filter. Use one for each category value a user says in words:
+
+```json
+{"phrase": "horror", "column": "genres", "operator": "eq", "value": "Horror"}
+{"phrase": "tv show", "column": "media_type", "operator": "eq", "value": "tv"}
+```
+
+Phrases are unique and casefolded. Take the values from the built table with `mr-data query`, not
+from documentation. Ordered comparisons need a numeric or date column. `contains` needs a text
+column. Decimal values travel as strings. Never invent a meaning such as "best" when the brief
+does not name a metric. Leave that word unresolved, or add an explicit alias such as
+"highest rated".
+
+## 7. Add sort aliases
+
+A sort alias maps a phrase to a sort:
+
+```json
+{"phrase": "most popular", "column": "popularity", "direction": "desc"}
+{"phrase": "newest", "column": "release_date", "direction": "desc"}
+```
+
+## 8. Turn the planner on for public tables
+
+The planner turns a sentence into filters, sorts and preferences. Set
+`"planner": {"enabled": true, "external_context_allowed": true}` on a public table. Keep
+`external_context_allowed` false on a private table unless the user or the workspace policy
+authorizes sending its context to the planner model. Data-read permission is not that consent.
+Queries with negation or "or" stay unresolved rather than becoming a guessed filter.
+
+A full spec looks like this:
+
+```json
+{
+  "schema_version": "table-search-spec.v1",
+  "keyword_columns": ["title", "original_title", "overview", "people_text", "meta_text"],
+  "semantic_columns": ["title", "overview"],
+  "aliases": [{"phrase": "horror", "column": "genres", "operator": "eq", "value": "Horror"}],
+  "sort_aliases": [{"phrase": "most popular", "column": "popularity", "direction": "desc"}],
+  "planner": {"enabled": true, "external_context_allowed": true},
+  "field_roles": {"title": "title", "person": "people_text", "date": "release_date",
+                  "popularity": "popularity", "rating": "vote_average", "identifier": "id",
+                  "description": "overview", "category": "genres", "image": "poster_url",
+                  "emoji": "emojis"},
+  "display_columns": ["id", "title", "release_date", "poster_url", "overview"],
+  "filterable_columns": ["id", "genres", "original_language", "release_date", "runtime"],
+  "sortable_columns": ["popularity", "vote_average", "vote_count", "release_date"],
+  "soft_preference_columns": ["mood_1"],
+  "soft_preference_sets": {"mood_1": ["mood_2"]},
+  "multi_value_columns": ["genres"]
+}
+```
+
+Put it in the recipe as `table.search`.
+
+## 9. Validate
+
+Validate before you register anything:
+
+```sh
+mr-data search validate --spec search.json --json
+mr-data search validate --recipe recipe.json --json
+```
+
+`--spec` alone checks the file against the pinned Studio contract and sends nothing. `--recipe`
+checks `table.search` the same way, then asks Studio to check it against the declared columns.
+`configure` runs the same local check. When Studio serves a newer spec member than this client
+knows, pass `configure --no-local-check` and let Studio decide.
+Studio also checks the column types: a `multi_value_columns` entry, an `emoji` role and every
+column of a soft preference set must name a declared string column.
+The `local` block lists each refusal with a JSON pointer. Repair every diagnostic, then run
+`mr-data recipe recipe.json --json` as usual.
+
+## 10. Build the data and watch search prepare
+
+Register and build the table as usual. A finished build of a table with `table.search` prepares
+search in the background. Data publication never waits for it. The live search package that
+`search try` uses exists only for a table published publicly. Read the version ID from the run
+receipt, then check readiness:
+
+```sh
+mr-data search status TABLE_ID --version VERSION_ID --json
+```
+
+`readiness` summarises the answer:
+
+- `preparation_state` is `ready` when a generation serves this spec.
+- `reason` says why not: `never_built`, `pending`, `failed`, `cancelled`, `not_activated` or
+  `spec_mismatch`. It is null while a job is dispatched, and when the version has no search spec.
+- `progress_rows`, `total_rows` and `percent` track a running build.
+- `failure` names the cause of a failed build.
+- `package_state` and `package_reason` describe the live search package that `search try` uses.
+- `generation_id` and `active_revision_id` are the coordinates `search activate` compares.
+
+Exit code 0 means a generation serves the spec. Exit code 3 means not ready yet: a build is
+running, or the version needs a build or an activation. Read `reason` before you wait.
+`never_built`, `not_activated` and `spec_mismatch` need an action, not time. Exit code 1 means the build failed or was cancelled. Never queue
+a duplicate build while one runs. A failed build leaves the data published. Never call a table
+partly ready.
+
+## 11. Try queries
+
+Run real queries against the live search once `package_state` is `ready`:
+
+```sh
+mr-data search try TABLE_ID --public-table PUBLIC_TABLE_ID --query "incepton" --json
+mr-data search try TABLE_ID --public-table PUBLIC_TABLE_ID --query "90s horror twist ending" --json
+mr-data search try TABLE_ID --public-table PUBLIC_TABLE_ID --plan plan.json --columns title --json
+```
+
+`TABLE_ID` is the Studio table ID from the run receipt. `PUBLIC_TABLE_ID` is the table's public
+ID, which `mr-data public tables DATASET_SLUG --json` lists. `try` refuses with
+`THIN_SEARCH_VERSION_MISMATCH` when the two do not serve the same live version. The public schema
+can lag a new live version by a few minutes. Retry then. A query holds at most 16 words.
+
+`try` prints the rows, the applied `plan`, the `planner` report, the `retrieval` mode, the
+`corrected` query after a typo fix, the service stage timings and the Cloud timings. `path: scan`
+means the package did not answer and the fallback scan did. The `note` says why. Fix that before
+you judge ranking. `try` runs on published tables only, against their live version.
+
+Check each kind of query the table should answer: an exact title, a misspelled title, a person, a
+brand, a category word, a decade, a sort word, and a plot paraphrase. Record a few checks with
+their actual results in the dataset's verification notes.
+
+## 12. Write evaluation cases
+
+A spec with semantic columns needs evaluation cases before a revision can activate. Each case is
+one query and the rows it must or must not return in its top `top_k`. You need at least one
+`paraphrase` case and one `hard_negative` case.
+
+- A paraphrase case describes a row without its title words: "thieves who steal secrets inside
+  dreams" must find Inception.
+- A hard-negative case names rows that look close but are wrong. It needs at least one forbidden
+  row: "a heist inside dreams" must not return a documentary about sleep.
+
+The evaluator runs each query through meaning-based retrieval alone, with no filters. Write
+queries that meaning can answer.
+
+Cases name rows by `[part_index, row]` locators of the sealed version. Draft them by title or id,
+then let `locate` resolve them:
+
+```json
+{"cases": [
+  {"case_id": "dream-heist", "kind": "paraphrase", "top_k": 10,
+   "query": "thieves who steal secrets inside dreams",
+   "required": [{"title": "Inception", "year": 2010}], "forbidden": []},
+  {"case_id": "not-a-documentary", "kind": "hard_negative", "top_k": 10,
+   "query": "a heist inside dreams",
+   "required": [{"title": "Inception", "year": 2010}], "forbidden": [{"id": 12345}]}
+]}
+```
+
+```sh
+mr-data search locate TABLE_ID --public-table PUBLIC_TABLE_ID --cases draft.json --out cases.json --json
+mr-data search locate TABLE_ID --public-table PUBLIC_TABLE_ID --title "Dune" --year 2021 --json
+mr-data search locate TABLE_ID --public-table PUBLIC_TABLE_ID --id 27205 --json
+```
+
+`locate` reads the public table's rows and maps each matching row to its locator. It needs no
+search package, so write the cases before the version has one. The table must be published
+publicly with its preview on. It reads the title, date and identifier columns from the field
+roles. Override them with `--title-column`, `--date-column` and `--id-column`. A title matches
+exactly, with the same case and spacing as the cell. A year matches the start of the date
+column's value. A title without a year can match several rows. `locate` then lists them all and
+exits 4. Add the year or use the id. It writes `--out` only when every target resolved and the
+cases meet the contract.
+
+Locators belong to one sealed version. `locate` resolves rows of the live version only. Configure
+the cases on that same version. A later version has a different row layout, so locate again after
+a rebuild. Check the result:
+
+```sh
+mr-data search validate TABLE_ID --version VERSION_ID --spec search.json --cases cases.json --json
+```
+
+This checks the cases against the contract and every locator against the version's parts.
+
+## 13. Configure, build and activate a revision
+
+A revision changes search on a sealed version without a data rebuild. Use one to add evaluation
+cases or to tune the spec.
+
+```sh
+mr-data search configure TABLE_ID --version VERSION_ID --spec search.json \
+  --cases cases.json --expected-revision none --json
+mr-data search build TABLE_ID --version VERSION_ID --revision REVISION_ID --json
+mr-data search status --job JOB_ID --json
+```
+
+Leave out `--spec` to declare the `table.search` spec of the recipe that sealed the version.
+Use that to add evaluation cases without retyping the spec. Without `--spec` the client cannot
+check locally that semantic cases include a paraphrase and a hard negative. Studio checks them
+against the recipe's spec. A recipe with no `table.search` answers 409 `SEARCH_NOT_CONFIGURED`.
+`search status --job` reads any search job: the build, its package and embed steps, the
+evaluator and a title job. A job still `queued`, `dispatched` or `running` exits 3.
+`--expected-revision` is the current draft from `search status` (`selected_draft_revision_id`),
+or `none`. Reuse `--idempotency-key` only to retry the same configuration. When the job succeeds,
+`search status TABLE_ID --version VERSION_ID --revision REVISION_ID` reports `not_activated` and
+the new `generation_id`. A semantic revision also runs the evaluator. Activation needs its
+measurements to pass.
+
+```sh
+mr-data search activate TABLE_ID --version VERSION_ID --revision REVISION_ID \
+  --generation GENERATION_ID --expected-active none \
+  --expected-active-generation none --json
+```
+
+The two `--expected-active` values are the revision and generation that serve now, from
+`search status`. Use `none` when nothing serves. Studio refuses the switch when they changed.
+Activation changes search only. It never changes which data version is live. Use `rollback` with
+the same coordinates to switch back. `--revision none` names the recipe's own spec.
+
+## 14. Query a published table directly
+
+`search try` wraps the public query route. You can call it yourself. Read the schema first:
+
+```sh
+mr-data public schema PUBLIC_TABLE_ID --json
+```
+
+`capabilities.search` carries `table_version_id`, `spec_digest`, `keyword_columns` and
+`semantic_columns`. Use `keyword_columns` for `search.columns`. The top-level `columns` is the
+output projection. This example uses an illustrative digest:
+
+```sh
+mr-data public query PUBLIC_TABLE_ID --body '{"columns":["title"],"search":{"text":"example","columns":["title"],"spec_digest":"sha256:0000000000000000000000000000000000000000000000000000000000000000","mode":"lexical"},"limit":10}' --json
+```
+
+Add `"engine": "resident"` and `"settled": true` to `search` to use the live package, as `try`
+does. Public query prints Cloud stage durations under `result.timings`, the HTTP status and the
+request ID. Keep a refusal's `detail` with its request ID.
+
+## Rules
+
+- Never emulate search locally, and never claim readiness from a declaration.
+- Never compute authoritative digests or bypass Studio's resource admission.
+- Source cells and model output stay untrusted.
+- This workflow opts in new tables. It does not migrate old datasets or rewrite a user's recipe.