From 4a6106f4a3a7a91b31d5238993064eb351ff2809 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Thu, 5 Nov 2026 13:06:14 -0800 Subject: [PATCH 01/13] Teach the skills to run the models in this process Both skills assumed a NIM URL and mentioned SDMClient.in_process() only in passing, so an agent asked to load a model into a notebook had nothing to follow. Each skill now has a reference, tabular/references/in-process.md and relational/references/in-process.md, with the extra to install, the client opened without a URL, what a NIM does differently, and how to pass a model already loaded. Both SKILL.md files point at it and trigger on it, and the index lists it. The examples are real programs and the harness runs them: a new in_process marker, opted into with SDM_IN_PROCESS=1, loads the published weights and compares what each example prints to its Verified block. The blocks show the shape of the answer and not its numbers, because a CPU and a GPU disagree on those. The two SKILL.md files are checked for the link, and the index for the listing. Co-Authored-By: Claude Fable 5.1 Signed-off-by: Manush Murali --- AGENTS.md | 6 +- CONTRIBUTING.md | 4 + pyproject.toml | 1 + skills/README.md | 10 +- skills/relational/SKILL.md | 10 +- skills/relational/references/in-process.md | 135 +++++++++++++++++++++ skills/tabular/SKILL.md | 11 +- skills/tabular/references/in-process.md | 93 ++++++++++++++ tests/test_skills.py | 51 +++++++- 9 files changed, 311 insertions(+), 10 deletions(-) create mode 100644 skills/relational/references/in-process.md create mode 100644 skills/tabular/references/in-process.md diff --git a/AGENTS.md b/AGENTS.md index 3d82750d4..58f8f92cb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,8 +40,10 @@ The standalone Python PQL and relational-engine distributions are archived and a [`tests/test_skills.py`](tests/test_skills.py) reads the tables out of `skills/` and puts them to the client, and with `-m live_nim` it runs every complete example and compares what it printed to the block pasted beneath it. -A `**Verified**` block is a claim that an endpoint produced exactly that. Do -not write one by hand, and do not edit the numbers in one. +The two in-process references run the same way under `SDM_IN_PROCESS=1` with +`-m in_process`, loading the published weights here. A `**Verified**` block is +a claim that an endpoint, or this process, produced exactly that. Do not write +one by hand, and do not edit the numbers in one. An example is complete when every name it reads was bound by itself or by an earlier complete example. One that is not is a fragment: it is checked as code, diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 59034aa07..844664f67 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -130,6 +130,10 @@ SDM_RELATIONAL_URL=http://localhost:8001 \ .venv/bin/python -m pytest packages/structured-data-models-client/tests \ -m live_nim -q +# the published weights, fetched and run in this process; needs the +# in-process extra, and the relational one for the relational reference +SDM_IN_PROCESS=1 .venv/bin/python -m pytest tests/test_skills.py -m in_process -q + # real warehouses, with credentials in the environment .venv/bin/python -m pytest \ packages/structured-data-models-connectors/tests -m live_warehouse -q diff --git a/pyproject.toml b/pyproject.toml index 696708522..f34e70c2a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -157,6 +157,7 @@ tmp_path_retention_policy = "failed" markers = [ "live_nim: needs a running NIM", "live_warehouse: needs a real Snowflake or Databricks warehouse", + "in_process: loads the published weights and runs them in this process", "socket: binds a local socket; deselect where that is not permitted", "gpu: needs a CUDA GPU", "tooling: repository-tool tests run once in dedicated CI jobs, outside the Python version matrix", diff --git a/skills/README.md b/skills/README.md index 3ad61fba4..3468990c6 100644 --- a/skills/README.md +++ b/skills/README.md @@ -24,6 +24,8 @@ be loaded without the skill it belongs to: | [`tabular/references/pql.md`](tabular/references/pql.md) | The same language on one table, and what it refuses | | [`relational/references/warehouses.md`](relational/references/warehouses.md) | Tables that stay in a warehouse, and metric views | | [`relational/references/beyond-one-answer.md`](relational/references/beyond-one-answer.md) | Rankings, forecasts and explanations | +| [`tabular/references/in-process.md`](tabular/references/in-process.md) | Running kumo-tabular in this process, with no NIM | +| [`relational/references/in-process.md`](relational/references/in-process.md) | Running kumo-relational in this process, with no NIM | ## What these models are @@ -61,7 +63,10 @@ only check its imports get. Run with run and compares what it printed to the block pasted beneath it. An example that reads a name no example before it binds is a fragment -- a Databricks session, a Snowflake one -- and those are checked as code but executed -nowhere, so none of them is allowed to show output. +nowhere, so none of them is allowed to show output. The two in-process +references open no connection and load the published weights instead, so they +run under `SDM_IN_PROCESS=1` with `-m in_process`, and their output was pasted +from a CPU. Where a skill says the client allows something the endpoint refuses, that gap is the point and is stated as such. If a claim here contradicts the code, the @@ -72,4 +77,5 @@ code is right and the skill is stale: say so rather than working around it. - Training, fine-tuning, checkpoints, model registries. The models do not train. - The parser behind `PredictiveQuery`. It is part of the client's Rust core and has no Python API of its own. Write the query as a string. -- Deployment, authentication and endpoint operation. A skill assumes a URL. +- Deployment, authentication and endpoint operation. A skill assumes a URL, + or that the model runs in this process. diff --git a/skills/relational/SKILL.md b/skills/relational/SKILL.md index 90c6fab1c..5bf65cf85 100644 --- a/skills/relational/SKILL.md +++ b/skills/relational/SKILL.md @@ -1,6 +1,6 @@ --- name: sdm-relational -description: "Ask kumo-relational a question about an entity and the records linked to it: write the question as a predictive query over a schema of related tables, covering classification, regression, forecasting and ranking the candidates an entity may link to. Triggers: kumo-relational, KumoRelational, PREDICT, FOR EACH, predictive query, PQL, Schema.from_data, Schema.from_source, Relationship, ranking, forecast, link prediction, explanation, Snowflake, Databricks, warehouse, metric view, semantic view, SQL, catalog." +description: "Ask kumo-relational a question about an entity and the records linked to it: write the question as a predictive query over a schema of related tables, covering classification, regression, forecasting and ranking the candidates an entity may link to. Triggers: kumo-relational, KumoRelational, PREDICT, FOR EACH, predictive query, PQL, Schema.from_data, Schema.from_source, Relationship, ranking, forecast, link prediction, explanation, Snowflake, Databricks, warehouse, metric view, semantic view, SQL, catalog, SDMClient.in_process, run the model in this process, no NIM." --- # Asking kumo-relational @@ -121,6 +121,14 @@ print(answer.to_pandas()) `id` is the entity, `row_index` its position in `indices`. Join on the key when it is there, otherwise on `row_index`, and never on row order. +## Without a NIM + +Every example here points at a NIM. With none to point at, the same client +runs the model in this process: `SDMClient.in_process()` in place of the URL, +and the rest unchanged. It is a second extra, it loads the published weights, +and on a CPU its numbers differ from a GPU's. All of that is in +[`references/in-process.md`](references/in-process.md). + ## Describing the data A `Schema` says which tables exist, how they are keyed, which column carries diff --git a/skills/relational/references/in-process.md b/skills/relational/references/in-process.md new file mode 100644 index 000000000..d30b3ad1f --- /dev/null +++ b/skills/relational/references/in-process.md @@ -0,0 +1,135 @@ +# Running kumo-relational in this process + +Nothing deployed to point at, or tables that must not leave the machine: the +same client runs the model here instead, with the same calls. This is how a +notebook asks with no NIM at all. + +It takes two extras, the engine that gathers a request and the models that +answer one: + +``` +pip install 'structured-data-models-client[relational,in-process]' +``` + +The second brings structured-data-models and PyTorch, and needs Python 3.11 +or later. Without it, `SDMClient.in_process()` raises `MissingExtraError` +naming that command; on Python 3.10 the error names the Python it needs +instead. The first prediction fetches the published weights, +`nvidia/Kumo-Relational` on Hugging Face, into the Hugging Face cache, and +later ones read them from there. No Hugging Face account or token is needed; +a warning about unauthenticated requests is about rate limits, not access. The +model runs on a GPU when there is one, else on the CPU. + +Open the client with `SDMClient.in_process()` in place of a URL. Everything +else is [the whole interface](../SKILL.md): the schema, the query and +`materialize()` are unchanged, and gathering still happens there, in this +client. What moves is the model run, and `client.url` says where it answers +from. + +```python +import pandas as pd +from sdm_client import ( + KumoRelational, + PredictiveQuery, + Relationship, + SDMClient, + Schema, +) + +users = pd.DataFrame({'user_id': range(12), 'segment': ['a', 'b'] * 6}) +orders = pd.DataFrame( + { + 'order_id': range(120), + 'user_id': [i % 12 for i in range(120)], + 'item': [i % 4 for i in range(120)], + 'price': [10.0 + i for i in range(120)], + 'ordered_at': pd.date_range('2026-01-01', periods=120, freq='D'), + } +) +items = pd.DataFrame({'item': range(4), 'kind': list('abcd')}) + +schema = Schema.from_data( + {'users': users, 'orders': orders, 'items': items}, + primary_keys={'users': 'user_id', 'orders': 'order_id', 'items': 'item'}, + time_columns={'orders': 'ordered_at'}, + relationships=[ + Relationship('orders', 'user_id', 'users', 'user_id'), + Relationship('orders', 'item', 'items', 'item'), + ], +) +request = PredictiveQuery( + 'PREDICT COUNT(orders.*, 0, 30, days) FOR EACH users.user_id', schema +).materialize(indices=[1, 2, 3], model=KumoRelational()) + +with SDMClient.in_process() as client: + print(client.url, client.models()) + answer = client.predict(request, model=KumoRelational()) +print(list(answer.to_pandas().columns), len(answer.to_pandas()), 'rows') +``` + +**Verified** in this process, on a CPU: + +``` +in-process ['kumo-tabular', 'kumo-relational'] +['row_index', 'id', 'prediction'] 3 rows +``` + +The frame has the shape a NIM gives: `row_index`, the entity's `id` and the +`prediction`. The numbers are not shown because they depend on where it ran, +which is the first difference below. + +## An explanation, here + +The shipping deployment refuses `explanation` on every task. This process +serves it, with the same `result.explanations` a deployment that serves it +gives, keyed by the entity: + +```python +with SDMClient.in_process() as client: + explained = client.predict( + request, model=KumoRelational(), outputs=['prediction', 'explanation'] + ) +print(sorted(explained.explanations.gradients)) +``` + +**Verified** in this process, on a CPU: + +``` +[1, 2, 3] +``` + +Reading one entry is in [the whole interface](../SKILL.md), under +explanations. + +## What differs from a NIM + +- **Where it ran decides the numbers.** On a GPU, with the published weights, + the answers are a NIM's exactly. On a CPU the model computes at full + precision and draws its random numbers there, so a prediction can differ + from a GPU-hosted NIM's by more than rounding. Compare against a NIM on the + same device, or compare shapes rather than numbers, as above. +- **A deployment's limits are not applied.** This client's own still are: + every limit `materialize()` checks is checked as it would be for a NIM. A + deployment also protects a shared server with limits of its own, such as + the longest string a cell may hold, and nothing applies those here. +- **A refusal has no HTTP status.** It is a `StructuredDataError` carrying the + code a NIM would give, and never a `NimRequestError`, since nothing was + sent. Inside a session the code is the reason's own, where a NIM files the + refusal under `SESSION_CREATE_VALIDATION_FAILED`. Catching + `StructuredDataError` catches it as before. +- **A session is held in this process's memory** until `close()`, or until + the client closes, with no expiry. `fit()` works as it does against a NIM, + and the `with` block above is what lets go of what it holds. +- **`client.models()` lists what it can run**, rather than what an endpoint + advertises: both models when it loads them itself, or the ones passed in. + +## Choosing the device, or passing a loaded model + +`SDMClient.in_process(device='cuda')` places the models this client loads. A +model already loaded with structured-data-models is used as it is: +`SDMClient.in_process(loaded)`, where `loaded` is a +`sdm.models.KumoRelational`, shares its weights with every context the client +fits, and refuses `device=` beside it, since that model is already somewhere. +The quickstart's section on a model in this process, in +[`docs/get-started/quickstart.md`](../../../docs/get-started/quickstart.md), +shows it. diff --git a/skills/tabular/SKILL.md b/skills/tabular/SKILL.md index f4b921b5b..caba840f6 100644 --- a/skills/tabular/SKILL.md +++ b/skills/tabular/SKILL.md @@ -1,6 +1,6 @@ --- name: sdm-tabular -description: "Ask kumo-tabular a question about rows of one table: classification or regression over labelled rows and rows to score, with no relationships and no time windows. Triggers: kumo-tabular, KumoTabular, single table prediction, tabular classification, tabular regression, score these rows, Request(context=, predict=), PredictiveQuery on one table." +description: "Ask kumo-tabular a question about rows of one table: classification or regression over labelled rows and rows to score, with no relationships and no time windows. Triggers: kumo-tabular, KumoTabular, single table prediction, tabular classification, tabular regression, score these rows, Request(context=, predict=), PredictiveQuery on one table, SDMClient.in_process, run the model in this process, no NIM." --- # Asking kumo-tabular @@ -122,6 +122,14 @@ position, so a target of `'a'`, `'b'` and `'c'` gives `probability_a`, `probability_b` and `probability_c`. Read the class out of the column name rather than assuming an order. +## Without a NIM + +Every example here points at a NIM. With none to point at, the same client +runs the model in this process: `SDMClient.in_process()` in place of the URL, +and the rest unchanged. It is an extra, it loads the published weights, and on +a CPU its numbers differ from a GPU's. All of that is in +[`references/in-process.md`](references/in-process.md). + ## Choosing the task `task=` is yours to state, and it is worth stating. A target holding two whole @@ -249,4 +257,5 @@ Catch `StructuredDataError` to catch all of them. ## Then - [`references/pql.md`](references/pql.md) — the query language on one table +- [`references/in-process.md`](references/in-process.md) — the model in this process, with no NIM - [`../relational/SKILL.md`](../relational/SKILL.md) — when the question is about an entity and what it links to diff --git a/skills/tabular/references/in-process.md b/skills/tabular/references/in-process.md new file mode 100644 index 000000000..d45bbe5d7 --- /dev/null +++ b/skills/tabular/references/in-process.md @@ -0,0 +1,93 @@ +# Running kumo-tabular in this process + +Nothing deployed to point at, or rows that must not leave the machine: the +same client runs the model here instead, with the same calls. This is how a +notebook asks with no NIM at all. + +It is an extra: + +``` +pip install 'structured-data-models-client[in-process]' +``` + +That brings structured-data-models and PyTorch, and needs Python 3.11 or +later. Without it, `SDMClient.in_process()` raises `MissingExtraError` naming +that command; on Python 3.10 the error names the Python it needs instead. The +first prediction fetches the published weights, `nvidia/Kumo-Tabular` on +Hugging Face, into the Hugging Face cache, and later ones read them from +there. No Hugging Face account or token is needed; a warning about +unauthenticated requests is about rate limits, not access. The model runs on +a GPU when there is one, else on the CPU. + +Open the client with `SDMClient.in_process()` in place of a URL. Everything +else is [the whole interface](../SKILL.md): the request, the model handle and +the result are the same objects, and `client.url` says where it answers from. + +```python +import pandas as pd +from sdm_client import Request, SDMClient, KumoTabular + +labelled = pd.DataFrame( + { + 'age': [31.0, 44.5, 28.0, 51.0, 39.0], + 'spend': [120.0, 430.0, 90.0, 510.0, 260.0], + 'churn': [0, 1, 0, 1, 0], + } +) +to_score = pd.DataFrame({'age': [33.0, 47.0], 'spend': [150.0, 480.0]}) +request = Request( + context=labelled, predict=to_score, target='churn', task='classification' +) + +with SDMClient.in_process() as client: + print(client.url, client.models()) + answer = client.predict( + request, model=KumoTabular(), outputs=['prediction', 'probabilities'] + ) +print(list(answer.to_pandas().columns), len(answer.to_pandas()), 'rows') +``` + +**Verified** in this process, on a CPU: + +``` +in-process ['kumo-tabular', 'kumo-relational'] +['row_index', 'prediction', 'probability_0', 'probability_1'] 2 rows +``` + +The frame has the shape a NIM gives: `row_index`, `prediction` and a +probability column per class. The numbers are not shown because they depend +on where it ran, which is the first difference below. + +## What differs from a NIM + +- **Where it ran decides the numbers.** On a GPU, with the published weights, + the answers are a NIM's exactly. On a CPU the model computes at full + precision and draws its random numbers there, so a probability can differ + from a GPU-hosted NIM's by more than rounding: in one comparison a class + probability moved by 0.16. Compare against a NIM on the same device, or + compare shapes rather than numbers, as above. +- **A deployment's limits are not applied.** This client's own still are: a + context above 10,000 rows is refused as it would be for a NIM. A deployment + also protects a shared server with limits of its own, such as the longest + string a cell may hold, and nothing applies those here. +- **A refusal has no HTTP status.** It is a `StructuredDataError` carrying the + code a NIM would give, `UNSUPPORTED_OUTPUT` for `quantiles` on a + classification, and never a `NimRequestError`, since nothing was sent. + Catching `StructuredDataError` catches it as before. +- **A session is held in this process's memory** until `close()`, or until + the client closes, with no expiry. `fit()` works as it does against a NIM, + and the `with` block above is what lets go of what it holds. +- **`client.models()` lists what it can run**, rather than what an endpoint + advertises: both models when it loads them itself, or the ones passed in. + +## Choosing the device, or passing a loaded model + +`SDMClient.in_process(device='cuda')` places the models this client loads. A +model already loaded with structured-data-models is used as it is: +`SDMClient.in_process(loaded)`, where `loaded` is a `sdm.models.KumoTabular`, +shares its weights with every context the client fits, and refuses `device=` +beside it, since that model is already somewhere. Loading it yourself is also +how to pick a size: the client loads `'large'`, and `'medium'` and `'small'` +are published beside it. The quickstart's section on a model in this process, +in [`docs/get-started/quickstart.md`](../../../docs/get-started/quickstart.md), +shows the same for the relational model. diff --git a/tests/test_skills.py b/tests/test_skills.py index 36336fbe8..f5196dbbc 100644 --- a/tests/test_skills.py +++ b/tests/test_skills.py @@ -14,7 +14,9 @@ ``SDM_RELATIONAL_URL``. Those re-run every example that can be run -- see ``complete()`` -- and compare what it printed to the block pasted beneath it, and probe the handful of claims the skills make about a deployment rather than -about this client. +about this client. The in-process references need no endpoint but load the +published weights, so they are marked ``in_process`` and run only with +``SDM_IN_PROCESS`` set. """ from __future__ import annotations @@ -176,6 +178,20 @@ def test_a_skill_announces_itself(name): ) +@pytest.mark.parametrize('name', ['tabular', 'relational']) +def test_a_skill_says_how_to_run_its_model_here(name): + """A skill assumes a URL. Where there is none, the model runs in the + agent's own process, and the skill has to say so where it is found: in + the skill itself, and in the index an agent starts from.""" + reference = f'{name}/references/in-process.md' + assert '](references/in-process.md)' in rendered( + SKILLS / name / 'SKILL.md' + ), f'{name} never says how to run its model in this process' + assert f']({reference})' in rendered(SKILLS / 'README.md'), ( + f'the index does not list {reference}' + ) + + @pytest.mark.parametrize('path', documents(), ids=str) def test_a_document_is_written_in_the_one_markdown_this_file_reads(path): """Fences are ```` ``` ```` at the margin, and nothing is indented code. @@ -291,6 +307,7 @@ def test_a_document_is_written_in_the_one_markdown_this_file_reads(path): (['Refusal', 'Cause'], False), ], 'skills/relational/references/beyond-one-answer.md': [], + 'skills/relational/references/in-process.md': [], 'skills/relational/references/warehouses.md': [ (['Source', 'Connection it takes', 'Namespace', 'Extra'], True) ], @@ -304,6 +321,7 @@ def test_a_document_is_written_in_the_one_markdown_this_file_reads(path): (['', '`kumo-tabular`'], True), (['Refusal', 'Cause'], False), ], + 'skills/tabular/references/in-process.md': [], 'skills/tabular/references/pql.md': [(['Clause', 'On one table'], True)], } @@ -2069,6 +2087,7 @@ def test_the_tabular_model_refuses_a_second_table(schema): TABULAR_URL = os.environ.get('SDM_TABULAR_URL') RELATIONAL_URL = os.environ.get('SDM_RELATIONAL_URL') +IN_PROCESS = os.environ.get('SDM_IN_PROCESS') #: The placeholder every example points at, swapped for a real one below. PLACEHOLDER = 'http://localhost:8000' @@ -2099,11 +2118,15 @@ def examples(path: Path) -> list[tuple[str, str | None]]: ] -def assert_every_example_prints_what_it_shows(path: Path, url: str): +def assert_every_example_prints_what_it_shows( + path: Path, url: str | None = None +): """Output marked **Verified** has to be what that example printed. Pasted results are the first thing to rot, and a number that drifted is - worse than no number: it reads as measured. + worse than no number: it reads as measured. ``url`` replaces the + placeholder the examples point at; a document whose examples run the + model here points at none and passes none. """ import io from contextlib import redirect_stdout @@ -2123,7 +2146,9 @@ def assert_every_example_prints_what_it_shows(path: Path, url: str): with redirect_stdout(printed): exec( # noqa: S102 - running the documentation is the test compile( - code.replace(PLACEHOLDER, url), f'{path}#{index}', 'exec' + code if url is None else code.replace(PLACEHOLDER, url), + f'{path}#{index}', + 'exec', ), namespace, ) @@ -2203,6 +2228,24 @@ def test_the_relational_examples_print_what_the_skill_shows(name): assert_every_example_prints_what_it_shows(SKILLS / name, RELATIONAL_URL) +@pytest.mark.in_process +@pytest.mark.skipif( + not IN_PROCESS, + reason='set SDM_IN_PROCESS=1 to load the published weights and run them', +) +@pytest.mark.parametrize( + 'name', + ['tabular/references/in-process.md', 'relational/references/in-process.md'], +) +def test_the_in_process_examples_print_what_the_skill_shows(name): + """These examples open no connection: they fetch the published weights + and run the model here, which is what the reference claims they do.""" + pytest.importorskip('sdm', reason='needs the in-process extra') + if name.startswith('relational'): + pytest.importorskip('sdm_relational_engine') + assert_every_example_prints_what_it_shows(SKILLS / name) + + # --- What the tables in the skills claim ---------------------------------- From 68fb8b9ca10c979bfec1c0cc227d9c1bab2c4109 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Thu, 5 Nov 2026 13:56:56 -0800 Subject: [PATCH 02/13] Say what the first in-process run downloads, and that runs are seeded Two agents given only the skills got a working answer from each reference on the first attempt, and both asked the same two things of it: how large the first fetch of the weights is, and whether a CPU run repeats its numbers. Both models load both task checkpoints at construction, about 1.7 GB for the large tabular model and 240 MB for the relational one, and the draw is seeded, so the references now say so instead of leaving "draws its random numbers there" to read as run-to-run variation. Co-Authored-By: Claude Fable 5.1 Signed-off-by: Manush Murali --- skills/relational/references/in-process.md | 13 ++++++++----- skills/tabular/references/in-process.md | 13 ++++++++----- 2 files changed, 16 insertions(+), 10 deletions(-) diff --git a/skills/relational/references/in-process.md b/skills/relational/references/in-process.md index d30b3ad1f..1c48e993f 100644 --- a/skills/relational/references/in-process.md +++ b/skills/relational/references/in-process.md @@ -16,9 +16,10 @@ or later. Without it, `SDMClient.in_process()` raises `MissingExtraError` naming that command; on Python 3.10 the error names the Python it needs instead. The first prediction fetches the published weights, `nvidia/Kumo-Relational` on Hugging Face, into the Hugging Face cache, and -later ones read them from there. No Hugging Face account or token is needed; -a warning about unauthenticated requests is about rate limits, not access. The -model runs on a GPU when there is one, else on the CPU. +later ones read them from there. That is both task checkpoints, about 240 MB, +once. No Hugging Face account or token is needed; a warning about +unauthenticated requests is about rate limits, not access. The model runs on +a GPU when there is one, else on the CPU. Open the client with `SDMClient.in_process()` in place of a URL. Everything else is [the whole interface](../SKILL.md): the schema, the query and @@ -106,8 +107,10 @@ explanations. - **Where it ran decides the numbers.** On a GPU, with the published weights, the answers are a NIM's exactly. On a CPU the model computes at full precision and draws its random numbers there, so a prediction can differ - from a GPU-hosted NIM's by more than rounding. Compare against a NIM on the - same device, or compare shapes rather than numbers, as above. + from a GPU-hosted NIM's by more than rounding. The draw is seeded, so two + runs on one machine print the same numbers; it is the device that moves + them, not the run. Compare against a NIM on the same device, or compare + shapes rather than numbers, as above. - **A deployment's limits are not applied.** This client's own still are: every limit `materialize()` checks is checked as it would be for a NIM. A deployment also protects a shared server with limits of its own, such as diff --git a/skills/tabular/references/in-process.md b/skills/tabular/references/in-process.md index d45bbe5d7..a96d524e3 100644 --- a/skills/tabular/references/in-process.md +++ b/skills/tabular/references/in-process.md @@ -15,9 +15,10 @@ later. Without it, `SDMClient.in_process()` raises `MissingExtraError` naming that command; on Python 3.10 the error names the Python it needs instead. The first prediction fetches the published weights, `nvidia/Kumo-Tabular` on Hugging Face, into the Hugging Face cache, and later ones read them from -there. No Hugging Face account or token is needed; a warning about -unauthenticated requests is about rate limits, not access. The model runs on -a GPU when there is one, else on the CPU. +there. That is both task checkpoints of the large model, about 1.7 GB, once; +`size='small'`, below, is about 220 MB. No Hugging Face account or token is +needed; a warning about unauthenticated requests is about rate limits, not +access. The model runs on a GPU when there is one, else on the CPU. Open the client with `SDMClient.in_process()` in place of a URL. Everything else is [the whole interface](../SKILL.md): the request, the model handle and @@ -64,8 +65,10 @@ on where it ran, which is the first difference below. the answers are a NIM's exactly. On a CPU the model computes at full precision and draws its random numbers there, so a probability can differ from a GPU-hosted NIM's by more than rounding: in one comparison a class - probability moved by 0.16. Compare against a NIM on the same device, or - compare shapes rather than numbers, as above. + probability moved by 0.16. The draw is seeded, so two runs on one machine + print the same numbers; it is the device that moves them, not the run. + Compare against a NIM on the same device, or compare shapes rather than + numbers, as above. - **A deployment's limits are not applied.** This client's own still are: a context above 10,000 rows is refused as it would be for a NIM. A deployment also protects a shared server with limits of its own, such as the longest From f331e052baefafb387ddab0392dee6be2a7ecbf2 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Mon, 9 Nov 2026 00:07:42 -0800 Subject: [PATCH 03/13] Show the join, say how to run where the Hub is unreachable Both references told a reader to join the answers back on, the tabular one on `row_index` and the relational one on the entity's key, without ever showing it. An agent writing from the tabular skill lined the two frames up by row order instead. Each example now does the join it asks for and prints the columns that come back. `row_index` is a position, not an index label, so the tabular example drops the index before making it a column: on a frame that was filtered or sorted the labels are no longer the positions, and merging on them pairs a row with another row's answer, or drops it, without saying so. Both references gain what to do where huggingface.co cannot be reached: the cache `HF_HOME` names, carried in, with `HF_HUB_OFFLINE=1`, and the refusal that says the weights are not there. An opt-in in-process run that is missing an extra now fails naming the install command, rather than skipping as though it had nothing to do. Signed-off-by: Manush Murali Co-Authored-By: Claude Opus 5 --- skills/relational/references/in-process.md | 20 +++++++++++++++-- skills/tabular/references/in-process.md | 25 +++++++++++++++++++++- tests/test_skills.py | 23 +++++++++++++++++--- 3 files changed, 62 insertions(+), 6 deletions(-) diff --git a/skills/relational/references/in-process.md b/skills/relational/references/in-process.md index 1c48e993f..e1d55ce99 100644 --- a/skills/relational/references/in-process.md +++ b/skills/relational/references/in-process.md @@ -66,6 +66,9 @@ with SDMClient.in_process() as client: print(client.url, client.models()) answer = client.predict(request, model=KumoRelational()) print(list(answer.to_pandas().columns), len(answer.to_pandas()), 'rows') + +named = answer.to_pandas().merge(users, left_on='id', right_on='user_id') +print(list(named.columns)) ``` **Verified** in this process, on a CPU: @@ -73,11 +76,14 @@ print(list(answer.to_pandas().columns), len(answer.to_pandas()), 'rows') ``` in-process ['kumo-tabular', 'kumo-relational'] ['row_index', 'id', 'prediction'] 3 rows +['row_index', 'id', 'prediction', 'user_id', 'segment'] ``` The frame has the shape a NIM gives: `row_index`, the entity's `id` and the -`prediction`. The numbers are not shown because they depend on where it ran, -which is the first difference below. +`prediction`. `id` is the key the question was asked for, and merging on it +is how the answers go back onto those entities: never line them up by row +order. The numbers are not shown because they depend on where it ran, which +is the first difference below. ## An explanation, here @@ -126,6 +132,16 @@ explanations. - **`client.models()` lists what it can run**, rather than what an endpoint advertises: both models when it loads them itself, or the ones passed in. +## A machine that cannot reach Hugging Face + +The weights are read from the Hugging Face cache, and `HF_HOME` says where +that is. Fetch them once where the Hub is reachable, copy that cache to the +machine that cannot reach it, point `HF_HOME` at the copy and set +`HF_HUB_OFFLINE=1`: the model loads from it with no network at all. With +nothing there, an offline run refuses with `MODEL_NOT_READY` naming +`LocalEntryNotFoundError`, rather than waiting on a request that cannot +arrive. + ## Choosing the device, or passing a loaded model `SDMClient.in_process(device='cuda')` places the models this client loads. A diff --git a/skills/tabular/references/in-process.md b/skills/tabular/references/in-process.md index a96d524e3..b046616aa 100644 --- a/skills/tabular/references/in-process.md +++ b/skills/tabular/references/in-process.md @@ -46,6 +46,13 @@ with SDMClient.in_process() as client: request, model=KumoTabular(), outputs=['prediction', 'probabilities'] ) print(list(answer.to_pandas().columns), len(answer.to_pandas()), 'rows') + +scored = ( + to_score.reset_index(drop=True) + .reset_index(names='row_index') + .merge(answer.to_pandas(), on='row_index') +) +print(list(scored.columns)) ``` **Verified** in this process, on a CPU: @@ -53,10 +60,16 @@ print(list(answer.to_pandas().columns), len(answer.to_pandas()), 'rows') ``` in-process ['kumo-tabular', 'kumo-relational'] ['row_index', 'prediction', 'probability_0', 'probability_1'] 2 rows +['row_index', 'age', 'spend', 'prediction', 'probability_0', 'probability_1'] ``` The frame has the shape a NIM gives: `row_index`, `prediction` and a -probability column per class. The numbers are not shown because they depend +probability column per class. `row_index` is the *position* in the frame +passed as `predict`, not that frame's index label, so drop the index before +making it a column: a frame that was filtered or sorted carries labels that +are no longer its positions, and merging on those quietly pairs a row with +another row's answer, or drops it. Merge on `row_index`, never line the two +frames up by row order. The numbers are not shown because they depend on where it ran, which is the first difference below. ## What differs from a NIM @@ -83,6 +96,16 @@ on where it ran, which is the first difference below. - **`client.models()` lists what it can run**, rather than what an endpoint advertises: both models when it loads them itself, or the ones passed in. +## A machine that cannot reach Hugging Face + +The weights are read from the Hugging Face cache, and `HF_HOME` says where +that is. Fetch them once where the Hub is reachable, copy that cache to the +machine that cannot reach it, point `HF_HOME` at the copy and set +`HF_HUB_OFFLINE=1`: the model loads from it with no network at all. With +nothing there, an offline run refuses with `MODEL_NOT_READY` naming +`LocalEntryNotFoundError`, rather than waiting on a request that cannot +arrive. + ## Choosing the device, or passing a loaded model `SDMClient.in_process(device='cuda')` places the models this client loads. A diff --git a/tests/test_skills.py b/tests/test_skills.py index f5196dbbc..329686537 100644 --- a/tests/test_skills.py +++ b/tests/test_skills.py @@ -2228,6 +2228,17 @@ def test_the_relational_examples_print_what_the_skill_shows(name): assert_every_example_prints_what_it_shows(SKILLS / name, RELATIONAL_URL) +def installed(module: str, extra: str) -> None: + """Fail, rather than skip, when an opt-in run is missing what it needs.""" + try: + importlib.import_module(module) + except ImportError: # pragma: no cover + pytest.fail( + f'SDM_IN_PROCESS is set but {module} is not installed. ' + f"Install it with: pip install '{extra}'" + ) + + @pytest.mark.in_process @pytest.mark.skipif( not IN_PROCESS, @@ -2239,10 +2250,16 @@ def test_the_relational_examples_print_what_the_skill_shows(name): ) def test_the_in_process_examples_print_what_the_skill_shows(name): """These examples open no connection: they fetch the published weights - and run the model here, which is what the reference claims they do.""" - pytest.importorskip('sdm', reason='needs the in-process extra') + and run the model here, which is what the reference claims they do. + + ``SDM_IN_PROCESS`` is the reader asking for exactly this, so a missing + extra is a broken setup and fails here rather than skipping quietly. + """ + installed('sdm', 'structured-data-models-client[in-process]') if name.startswith('relational'): - pytest.importorskip('sdm_relational_engine') + installed( + 'sdm_relational_engine', 'structured-data-models-client[relational]' + ) assert_every_example_prints_what_it_shows(SKILLS / name) From f0ab9045c0457f3aeda74b0e63cf10738e7e96e5 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Mon, 9 Nov 2026 08:47:07 -0800 Subject: [PATCH 04/13] Say what the install needs, and what a second client costs Both in-process references told a reader to install an extra no release carries. Following that line installs a client with no `in_process()`, and the failure is an `AttributeError`, not the `MissingExtraError` the next paragraph promises. Each reference now gives the checkout install and names both symptoms of a client older than the feature. Closing a client lets go of the models it loaded, and the next one reads the checkpoints into memory again. The references recommended a `with` block without saying what one per notebook cell costs. The relational reference now keeps one client across its two examples and closes it at the end, which is the pattern it recommends, and both say it. Two refusals reach only a model the reader loaded: training mode, and a model loaded for one task asked the other. A NIM's model is never either, so neither was stated. Both references now state them. The tabular reference sent a reader wanting the small model to a relational example. It now carries a tabular one of its own, with the output it printed. `on a GPU when there is one` reads as any GPU, where the backend checks CUDA alone, so on Apple silicon it runs on the CPU. The 0.16 figure is the quickstart's comparison, not a measurement of the example above it, and now says so. The requests this backend answers where a NIM refuses them with `VALIDATION_FAILED` sit beside the limits it does not apply, and listing `kumo-relational` no longer reads as the relational extra being installed. Signed-off-by: Manush Murali Co-Authored-By: Claude Opus 5 --- skills/relational/references/in-process.md | 60 ++++++++++++++----- skills/tabular/references/in-process.md | 68 ++++++++++++++++++---- 2 files changed, 103 insertions(+), 25 deletions(-) diff --git a/skills/relational/references/in-process.md b/skills/relational/references/in-process.md index e1d55ce99..9f60d92fe 100644 --- a/skills/relational/references/in-process.md +++ b/skills/relational/references/in-process.md @@ -11,15 +11,30 @@ answer one: pip install 'structured-data-models-client[relational,in-process]' ``` -The second brings structured-data-models and PyTorch, and needs Python 3.11 -or later. Without it, `SDMClient.in_process()` raises `MissingExtraError` +No published release carries `in_process()` yet, so until one does, that +command installs a client without it. Install from a checkout instead: + +``` +git clone https://github.com/NVIDIA/structured-data-models-client +cd structured-data-models-client +pip install -e \ + './packages/structured-data-models-client[relational,in-process]' +``` + +A pip warning that the client `does not provide the extra 'in-process'`, or +an `AttributeError` saying `SDMClient` has no attribute `in_process`, is an +installed client older than the feature, whichever command installed it. + +The second extra brings structured-data-models and PyTorch, and needs Python +3.11 or later. Without it, `SDMClient.in_process()` raises `MissingExtraError` naming that command; on Python 3.10 the error names the Python it needs instead. The first prediction fetches the published weights, `nvidia/Kumo-Relational` on Hugging Face, into the Hugging Face cache, and later ones read them from there. That is both task checkpoints, about 240 MB, once. No Hugging Face account or token is needed; a warning about unauthenticated requests is about rate limits, not access. The model runs on -a GPU when there is one, else on the CPU. +a CUDA GPU when there is one, else on the CPU: the check is CUDA's alone, so +on Apple silicon it runs on the CPU. Open the client with `SDMClient.in_process()` in place of a URL. Everything else is [the whole interface](../SKILL.md): the schema, the query and @@ -62,9 +77,9 @@ request = PredictiveQuery( 'PREDICT COUNT(orders.*, 0, 30, days) FOR EACH users.user_id', schema ).materialize(indices=[1, 2, 3], model=KumoRelational()) -with SDMClient.in_process() as client: - print(client.url, client.models()) - answer = client.predict(request, model=KumoRelational()) +client = SDMClient.in_process() +print(client.url, client.models()) +answer = client.predict(request, model=KumoRelational()) print(list(answer.to_pandas().columns), len(answer.to_pandas()), 'rows') named = answer.to_pandas().merge(users, left_on='id', right_on='user_id') @@ -85,6 +100,11 @@ is how the answers go back onto those entities: never line them up by row order. The numbers are not shown because they depend on where it ran, which is the first difference below. +The client is kept open here rather than wrapped in a `with` block, because +the next section asks it a second question and closing it would read the +checkpoints into memory again. That is the notebook pattern: one client +across the cells, `close()` at the end. + ## An explanation, here The shipping deployment refuses `explanation` on every task. This process @@ -92,11 +112,11 @@ serves it, with the same `result.explanations` a deployment that serves it gives, keyed by the entity: ```python -with SDMClient.in_process() as client: - explained = client.predict( - request, model=KumoRelational(), outputs=['prediction', 'explanation'] - ) +explained = client.predict( + request, model=KumoRelational(), outputs=['prediction', 'explanation'] +) print(sorted(explained.explanations.gradients)) +client.close() ``` **Verified** in this process, on a CPU: @@ -120,15 +140,23 @@ explanations. - **A deployment's limits are not applied.** This client's own still are: every limit `materialize()` checks is checked as it would be for a NIM. A deployment also protects a shared server with limits of its own, such as - the longest string a cell may hold, and nothing applies those here. + the longest string a cell may hold, and nothing applies those here. A + request is also read for what the model needs rather than against every + rule of the request contract, so a name longer than the contract's 1,024 + characters, or a key the contract does not name in a request built by hand + and passed to `Request.materialized`, is answered here and refused by a NIM + with `VALIDATION_FAILED`. - **A refusal has no HTTP status.** It is a `StructuredDataError` carrying the code a NIM would give, and never a `NimRequestError`, since nothing was sent. Inside a session the code is the reason's own, where a NIM files the refusal under `SESSION_CREATE_VALIDATION_FAILED`. Catching `StructuredDataError` catches it as before. - **A session is held in this process's memory** until `close()`, or until - the client closes, with no expiry. `fit()` works as it does against a NIM, - and the `with` block above is what lets go of what it holds. + the client closes, with no expiry. `fit()` works as it does against a NIM. + Closing also lets go of the models the client loaded, and the next client + reads them from the cache into memory again, so a notebook that opens a + `with` block per cell pays that load per cell: open one client, use it + across the cells, and `close()` it at the end, as above. - **`client.models()` lists what it can run**, rather than what an endpoint advertises: both models when it loads them itself, or the ones passed in. @@ -152,3 +180,9 @@ fits, and refuses `device=` beside it, since that model is already somewhere. The quickstart's section on a model in this process, in [`docs/get-started/quickstart.md`](../../../docs/get-started/quickstart.md), shows it. + +A model loaded that way arrives in evaluation mode and loaded for both tasks, +which is what this client asks of it. One put back into training mode is +refused with `INVALID_CONFIGURATION` naming `.eval()`, and one loaded for a +single `task=` is refused with `UNSUPPORTED_TASK` for the other; a NIM's +model is never either. diff --git a/skills/tabular/references/in-process.md b/skills/tabular/references/in-process.md index b046616aa..55d200cfe 100644 --- a/skills/tabular/references/in-process.md +++ b/skills/tabular/references/in-process.md @@ -10,7 +10,20 @@ It is an extra: pip install 'structured-data-models-client[in-process]' ``` -That brings structured-data-models and PyTorch, and needs Python 3.11 or +No published release carries `in_process()` yet, so until one does, that +command installs a client without it. Install from a checkout instead: + +``` +git clone https://github.com/NVIDIA/structured-data-models-client +cd structured-data-models-client +pip install -e './packages/structured-data-models-client[in-process]' +``` + +A pip warning that the client `does not provide the extra 'in-process'`, or +an `AttributeError` saying `SDMClient` has no attribute `in_process`, is an +installed client older than the feature, whichever command installed it. + +The extra brings structured-data-models and PyTorch, and needs Python 3.11 or later. Without it, `SDMClient.in_process()` raises `MissingExtraError` naming that command; on Python 3.10 the error names the Python it needs instead. The first prediction fetches the published weights, `nvidia/Kumo-Tabular` on @@ -18,7 +31,8 @@ Hugging Face, into the Hugging Face cache, and later ones read them from there. That is both task checkpoints of the large model, about 1.7 GB, once; `size='small'`, below, is about 220 MB. No Hugging Face account or token is needed; a warning about unauthenticated requests is about rate limits, not -access. The model runs on a GPU when there is one, else on the CPU. +access. The model runs on a CUDA GPU when there is one, else on the CPU: the +check is CUDA's alone, so on Apple silicon it runs on the CPU. Open the client with `SDMClient.in_process()` in place of a URL. Everything else is [the whole interface](../SKILL.md): the request, the model handle and @@ -77,24 +91,33 @@ on where it ran, which is the first difference below. - **Where it ran decides the numbers.** On a GPU, with the published weights, the answers are a NIM's exactly. On a CPU the model computes at full precision and draws its random numbers there, so a probability can differ - from a GPU-hosted NIM's by more than rounding: in one comparison a class - probability moved by 0.16. The draw is seeded, so two runs on one machine - print the same numbers; it is the device that moves them, not the run. - Compare against a NIM on the same device, or compare shapes rather than - numbers, as above. + from a GPU-hosted NIM's by more than rounding: in the quickstart's + comparison a class probability moved by 0.16. The draw is seeded, so two + runs on one machine print the same numbers; it is the device that moves + them, not the run. Compare against a NIM on the same device, or compare + shapes rather than numbers, as above. - **A deployment's limits are not applied.** This client's own still are: a context above 10,000 rows is refused as it would be for a NIM. A deployment also protects a shared server with limits of its own, such as the longest - string a cell may hold, and nothing applies those here. + string a cell may hold, and nothing applies those here. A request is also + read for what the model needs rather than against every rule of the request + contract, so a name longer than the contract's 1,024 characters is answered + here and refused by a NIM with `VALIDATION_FAILED`. - **A refusal has no HTTP status.** It is a `StructuredDataError` carrying the code a NIM would give, `UNSUPPORTED_OUTPUT` for `quantiles` on a classification, and never a `NimRequestError`, since nothing was sent. Catching `StructuredDataError` catches it as before. - **A session is held in this process's memory** until `close()`, or until the client closes, with no expiry. `fit()` works as it does against a NIM, - and the `with` block above is what lets go of what it holds. + and the `with` block above is what lets go of what it holds. Closing also + lets go of the models the client loaded, and the next client reads them + from the cache into memory again, so a notebook that opens a `with` block + per cell pays that load per cell: open one client, use it across the + cells, and `close()` it at the end. - **`client.models()` lists what it can run**, rather than what an endpoint advertises: both models when it loads them itself, or the ones passed in. + Listing `kumo-relational` is not a report that the `relational` extra is + installed; building a relational request still needs it. ## A machine that cannot reach Hugging Face @@ -114,6 +137,27 @@ model already loaded with structured-data-models is used as it is: shares its weights with every context the client fits, and refuses `device=` beside it, since that model is already somewhere. Loading it yourself is also how to pick a size: the client loads `'large'`, and `'medium'` and `'small'` -are published beside it. The quickstart's section on a model in this process, -in [`docs/get-started/quickstart.md`](../../../docs/get-started/quickstart.md), -shows the same for the relational model. +are published beside it. + +```python +import sdm + +small = sdm.models.KumoTabular(size='small') +with SDMClient.in_process(small) as client: + print(client.models()) + smaller = client.predict(request, model=KumoTabular()) +print(list(smaller.to_pandas().columns)) +``` + +**Verified** in this process, on a CPU: + +``` +['kumo-tabular'] +['row_index', 'prediction', 'probability_0', 'probability_1'] +``` + +A model loaded that way arrives in evaluation mode and loaded for both tasks, +which is what this client asks of it. One put back into training mode is +refused with `INVALID_CONFIGURATION` naming `.eval()`, and one loaded for a +single `task=` is refused with `UNSUPPORTED_TASK` for the other; a NIM's +model is never either. From 87f539d3ac96e785c556b8348a796432a1ede160 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Mon, 9 Nov 2026 10:37:19 -0800 Subject: [PATCH 05/13] Drop the index before making it the join key `row_index` is a position in the frame passed as `predict`, and `reset_index(names='row_index')` keys on that frame's index labels. On a frame that was filtered or sorted those are no longer the same, so the merge pairs a row with another row's answer, or drops it, and says nothing either way. Both files passed a frame with a default index, where the two agree, so both printed the right answer while teaching the pattern that does not. Filtering the tabular notebook's own eight rows to the five above 200 and running them through the model, the line it showed returns three rows. Signed-off-by: Manush Murali Co-Authored-By: Claude Opus 5 --- docs/reference/prediction-output.md | 12 +++++++++++- examples/local/tabular.ipynb | 14 ++++++++++++-- 2 files changed, 23 insertions(+), 3 deletions(-) diff --git a/docs/reference/prediction-output.md b/docs/reference/prediction-output.md index 08a77929e..43b669e90 100644 --- a/docs/reference/prediction-output.md +++ b/docs/reference/prediction-output.md @@ -103,9 +103,19 @@ has one; a single-table request may have none. order.** The endpoint is not required to return rows in the order they were sent, and a request split across several calls certainly will not. +`row_index` is the *position* in the frame passed as `predict`, not that +frame's index label, so drop the index before making it a column. A frame that +was filtered or sorted carries labels that are no longer its positions, and +merging on those pairs a row with another row's answer, or drops it, without +saying so. + ```python answers = result.to_pandas() -joined = to_score.reset_index(names='row_index').merge(answers, on='row_index') +joined = ( + to_score.reset_index(drop=True) + .reset_index(names='row_index') + .merge(answers, on='row_index') +) ``` ## Columns diff --git a/examples/local/tabular.ipynb b/examples/local/tabular.ipynb index 700e5b0d8..7d12bc386 100644 --- a/examples/local/tabular.ipynb +++ b/examples/local/tabular.ipynb @@ -185,7 +185,13 @@ "source": [ "Join on the key the result carries, or on `row_index`. **Never on row\n", "order**. The endpoint is not required to answer in the order you asked, and a\n", - "request split across several calls certainly will not.\n" + "request split across several calls certainly will not.\n", + "\n", + "`row_index` is the *position* in the frame passed as `predict`, not that\n", + "frame's index label, so drop the index before making it a column. A frame\n", + "that was filtered or sorted carries labels that are no longer its positions,\n", + "and merging on those pairs a row with another row's answer, or drops it,\n", + "without saying so.\n" ] }, { @@ -266,7 +272,11 @@ ], "source": [ "answers = result.to_pandas()\n", - "to_score.reset_index(names='row_index').merge(answers, on='row_index')" + "(\n", + " to_score.reset_index(drop=True)\n", + " .reset_index(names='row_index')\n", + " .merge(answers, on='row_index')\n", + ")" ] }, { From 2d18137ca4e006f6d65ff39dd88bf60481d83dbc Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Mon, 9 Nov 2026 10:42:18 -0800 Subject: [PATCH 06/13] Target the base this branch merges into The client on `v2-candidate` carries the core as a native module and builds with maturin, so a checkout install compiles it and needs the pinned Rust toolchain. Both references give the command that works there. `sdm_relational_engine` is retired on that base: the relational extra is empty and both models run on the base runtime. The in-process test no longer asks for it, so an opted-in run is not failed over a package the tree does not ship. One extra still covers both references, so a missing setup still fails naming the install command. Signed-off-by: Manush Murali Co-Authored-By: Claude Opus 5 --- skills/relational/references/in-process.md | 8 ++++++-- skills/tabular/references/in-process.md | 9 +++++++-- tests/test_skills.py | 8 +++----- 3 files changed, 16 insertions(+), 9 deletions(-) diff --git a/skills/relational/references/in-process.md b/skills/relational/references/in-process.md index 9f60d92fe..3c6656331 100644 --- a/skills/relational/references/in-process.md +++ b/skills/relational/references/in-process.md @@ -12,12 +12,16 @@ pip install 'structured-data-models-client[relational,in-process]' ``` No published release carries `in_process()` yet, so until one does, that -command installs a client without it. Install from a checkout instead: +command installs a client without it. Install from a checkout instead. That +build compiles the client's native extension, so it needs rustup and the +toolchain `rust/rust-toolchain.toml` pins; pip runs the build from the +client's own directory, where rustup does not read that pin, which is what +the variable names: ``` git clone https://github.com/NVIDIA/structured-data-models-client cd structured-data-models-client -pip install -e \ +RUSTUP_TOOLCHAIN=1.97.0 pip install -e \ './packages/structured-data-models-client[relational,in-process]' ``` diff --git a/skills/tabular/references/in-process.md b/skills/tabular/references/in-process.md index 55d200cfe..a310c2bd3 100644 --- a/skills/tabular/references/in-process.md +++ b/skills/tabular/references/in-process.md @@ -11,12 +11,17 @@ pip install 'structured-data-models-client[in-process]' ``` No published release carries `in_process()` yet, so until one does, that -command installs a client without it. Install from a checkout instead: +command installs a client without it. Install from a checkout instead. That +build compiles the client's native extension, so it needs rustup and the +toolchain `rust/rust-toolchain.toml` pins; pip runs the build from the +client's own directory, where rustup does not read that pin, which is what +the variable names: ``` git clone https://github.com/NVIDIA/structured-data-models-client cd structured-data-models-client -pip install -e './packages/structured-data-models-client[in-process]' +RUSTUP_TOOLCHAIN=1.97.0 pip install -e \ + './packages/structured-data-models-client[in-process]' ``` A pip warning that the client `does not provide the extra 'in-process'`, or diff --git a/tests/test_skills.py b/tests/test_skills.py index 329686537..13a089a30 100644 --- a/tests/test_skills.py +++ b/tests/test_skills.py @@ -2253,13 +2253,11 @@ def test_the_in_process_examples_print_what_the_skill_shows(name): and run the model here, which is what the reference claims they do. ``SDM_IN_PROCESS`` is the reader asking for exactly this, so a missing - extra is a broken setup and fails here rather than skipping quietly. + extra is a broken setup and fails here rather than skipping quietly. One + extra covers both references: gathering a relational request is the base + client's own work, so nothing else has to be installed to run them. """ installed('sdm', 'structured-data-models-client[in-process]') - if name.startswith('relational'): - installed( - 'sdm_relational_engine', 'structured-data-models-client[relational]' - ) assert_every_example_prints_what_it_shows(SKILLS / name) From b2ba8132a758d47a4dc0a72a1d699b041b52878f Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Mon, 9 Nov 2026 10:51:13 -0800 Subject: [PATCH 07/13] Stop asking for the extra this base retired The relational extra is empty on `v2-candidate` and both models run on the base runtime, so the relational reference asked for an extra that installs nothing and the tabular one read `kumo-relational` in `models()` as a thing the reader had yet to install. Both now name one extra, and the contributor note for the in-process run names one too. The client also pins an API package version that is not published, which pip cannot resolve from an index, so the checkout install carries that package from the checkout beside the client. Signed-off-by: Manush Murali Co-Authored-By: Claude Opus 5 --- CONTRIBUTING.md | 2 +- skills/relational/references/in-process.md | 18 ++++++++++-------- skills/tabular/references/in-process.md | 10 +++++----- 3 files changed, 16 insertions(+), 14 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 844664f67..6ee784a3b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -131,7 +131,7 @@ SDM_RELATIONAL_URL=http://localhost:8001 \ -m live_nim -q # the published weights, fetched and run in this process; needs the -# in-process extra, and the relational one for the relational reference +# in-process extra SDM_IN_PROCESS=1 .venv/bin/python -m pytest tests/test_skills.py -m in_process -q # real warehouses, with credentials in the environment diff --git a/skills/relational/references/in-process.md b/skills/relational/references/in-process.md index 3c6656331..5ac38fe0d 100644 --- a/skills/relational/references/in-process.md +++ b/skills/relational/references/in-process.md @@ -4,11 +4,10 @@ Nothing deployed to point at, or tables that must not leave the machine: the same client runs the model here instead, with the same calls. This is how a notebook asks with no NIM at all. -It takes two extras, the engine that gathers a request and the models that -answer one: +It is an extra: ``` -pip install 'structured-data-models-client[relational,in-process]' +pip install 'structured-data-models-client[in-process]' ``` No published release carries `in_process()` yet, so until one does, that @@ -16,21 +15,24 @@ command installs a client without it. Install from a checkout instead. That build compiles the client's native extension, so it needs rustup and the toolchain `rust/rust-toolchain.toml` pins; pip runs the build from the client's own directory, where rustup does not read that pin, which is what -the variable names: +the variable names. The client pins the API package to a version that is not +published either, so install that from the checkout too: ``` git clone https://github.com/NVIDIA/structured-data-models-client cd structured-data-models-client -RUSTUP_TOOLCHAIN=1.97.0 pip install -e \ - './packages/structured-data-models-client[relational,in-process]' +RUSTUP_TOOLCHAIN=1.97.0 pip install \ + -e './packages/structured-data-models-api' \ + -e './packages/structured-data-models-client[in-process]' ``` A pip warning that the client `does not provide the extra 'in-process'`, or an `AttributeError` saying `SDMClient` has no attribute `in_process`, is an installed client older than the feature, whichever command installed it. -The second extra brings structured-data-models and PyTorch, and needs Python -3.11 or later. Without it, `SDMClient.in_process()` raises `MissingExtraError` +The extra brings structured-data-models and PyTorch, and needs Python 3.11 +or later. Gathering the request needs nothing beyond it: the client carries +that itself. Without it, `SDMClient.in_process()` raises `MissingExtraError` naming that command; on Python 3.10 the error names the Python it needs instead. The first prediction fetches the published weights, `nvidia/Kumo-Relational` on Hugging Face, into the Hugging Face cache, and diff --git a/skills/tabular/references/in-process.md b/skills/tabular/references/in-process.md index a310c2bd3..2bef75965 100644 --- a/skills/tabular/references/in-process.md +++ b/skills/tabular/references/in-process.md @@ -15,13 +15,15 @@ command installs a client without it. Install from a checkout instead. That build compiles the client's native extension, so it needs rustup and the toolchain `rust/rust-toolchain.toml` pins; pip runs the build from the client's own directory, where rustup does not read that pin, which is what -the variable names: +the variable names. The client pins the API package to a version that is not +published either, so install that from the checkout too: ``` git clone https://github.com/NVIDIA/structured-data-models-client cd structured-data-models-client -RUSTUP_TOOLCHAIN=1.97.0 pip install -e \ - './packages/structured-data-models-client[in-process]' +RUSTUP_TOOLCHAIN=1.97.0 pip install \ + -e './packages/structured-data-models-api' \ + -e './packages/structured-data-models-client[in-process]' ``` A pip warning that the client `does not provide the extra 'in-process'`, or @@ -121,8 +123,6 @@ on where it ran, which is the first difference below. cells, and `close()` it at the end. - **`client.models()` lists what it can run**, rather than what an endpoint advertises: both models when it loads them itself, or the ones passed in. - Listing `kumo-relational` is not a report that the `relational` extra is - installed; building a relational request still needs it. ## A machine that cannot reach Hugging Face From 0821f13f5d4d63476e51a1d3b2273db66c4e9ca7 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Mon, 9 Nov 2026 10:57:55 -0800 Subject: [PATCH 08/13] One extra, in the relational skill too The relational extra is empty on this base, so the skill's own summary of what running in process costs was still counting two. Signed-off-by: Manush Murali Co-Authored-By: Claude Opus 5 --- skills/relational/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/relational/SKILL.md b/skills/relational/SKILL.md index 5bf65cf85..f31902ffa 100644 --- a/skills/relational/SKILL.md +++ b/skills/relational/SKILL.md @@ -125,8 +125,8 @@ it is there, otherwise on `row_index`, and never on row order. Every example here points at a NIM. With none to point at, the same client runs the model in this process: `SDMClient.in_process()` in place of the URL, -and the rest unchanged. It is a second extra, it loads the published weights, -and on a CPU its numbers differ from a GPU's. All of that is in +and the rest unchanged. It is an extra, it loads the published weights, and on +a CPU its numbers differ from a GPU's. All of that is in [`references/in-process.md`](references/in-process.md). ## Describing the data From eb02f576b7d8f33602ff040b014b14d7f9dd24e0 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Mon, 9 Nov 2026 16:30:29 -0800 Subject: [PATCH 09/13] Clone the branch that carries in_process() The default branch builds with setuptools, pins the published API package and keeps the relational engine behind its own extra, so a checkout of it gives a client whose materialize() fails for want of that engine. Everything the paragraph above the block describes belongs to v2-candidate, so clone that. The working install also goes first now. The index install is the one that does not work yet, and a reader runs the first block that looks like theirs. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- skills/relational/references/in-process.md | 31 ++++++++++++---------- skills/tabular/references/in-process.md | 31 ++++++++++++---------- 2 files changed, 34 insertions(+), 28 deletions(-) diff --git a/skills/relational/references/in-process.md b/skills/relational/references/in-process.md index 5ac38fe0d..ac59d2530 100644 --- a/skills/relational/references/in-process.md +++ b/skills/relational/references/in-process.md @@ -4,28 +4,31 @@ Nothing deployed to point at, or tables that must not leave the machine: the same client runs the model here instead, with the same calls. This is how a notebook asks with no NIM at all. -It is an extra: +It is an extra, but no published release carries `in_process()` yet, so the +plain install gets a client without it. Until one does, install from a +checkout of `v2-candidate`, the branch the release is cut from. That build +compiles the client's native extension, so it needs rustup and the toolchain +`rust/rust-toolchain.toml` pins; pip runs the build from the client's own +directory, where rustup does not read that pin, which is what the variable +names. The client pins the API package to a version that is not published +either, so install that from the checkout too: ``` -pip install 'structured-data-models-client[in-process]' -``` - -No published release carries `in_process()` yet, so until one does, that -command installs a client without it. Install from a checkout instead. That -build compiles the client's native extension, so it needs rustup and the -toolchain `rust/rust-toolchain.toml` pins; pip runs the build from the -client's own directory, where rustup does not read that pin, which is what -the variable names. The client pins the API package to a version that is not -published either, so install that from the checkout too: - -``` -git clone https://github.com/NVIDIA/structured-data-models-client +git clone -b v2-candidate \ + https://github.com/NVIDIA/structured-data-models-client cd structured-data-models-client RUSTUP_TOOLCHAIN=1.97.0 pip install \ -e './packages/structured-data-models-api' \ -e './packages/structured-data-models-client[in-process]' ``` +Once a release carries it, that build goes away and the extra is the whole +install: + +``` +pip install 'structured-data-models-client[in-process]' +``` + A pip warning that the client `does not provide the extra 'in-process'`, or an `AttributeError` saying `SDMClient` has no attribute `in_process`, is an installed client older than the feature, whichever command installed it. diff --git a/skills/tabular/references/in-process.md b/skills/tabular/references/in-process.md index 2bef75965..1d4a4870e 100644 --- a/skills/tabular/references/in-process.md +++ b/skills/tabular/references/in-process.md @@ -4,28 +4,31 @@ Nothing deployed to point at, or rows that must not leave the machine: the same client runs the model here instead, with the same calls. This is how a notebook asks with no NIM at all. -It is an extra: +It is an extra, but no published release carries `in_process()` yet, so the +plain install gets a client without it. Until one does, install from a +checkout of `v2-candidate`, the branch the release is cut from. That build +compiles the client's native extension, so it needs rustup and the toolchain +`rust/rust-toolchain.toml` pins; pip runs the build from the client's own +directory, where rustup does not read that pin, which is what the variable +names. The client pins the API package to a version that is not published +either, so install that from the checkout too: ``` -pip install 'structured-data-models-client[in-process]' -``` - -No published release carries `in_process()` yet, so until one does, that -command installs a client without it. Install from a checkout instead. That -build compiles the client's native extension, so it needs rustup and the -toolchain `rust/rust-toolchain.toml` pins; pip runs the build from the -client's own directory, where rustup does not read that pin, which is what -the variable names. The client pins the API package to a version that is not -published either, so install that from the checkout too: - -``` -git clone https://github.com/NVIDIA/structured-data-models-client +git clone -b v2-candidate \ + https://github.com/NVIDIA/structured-data-models-client cd structured-data-models-client RUSTUP_TOOLCHAIN=1.97.0 pip install \ -e './packages/structured-data-models-api' \ -e './packages/structured-data-models-client[in-process]' ``` +Once a release carries it, that build goes away and the extra is the whole +install: + +``` +pip install 'structured-data-models-client[in-process]' +``` + A pip warning that the client `does not provide the extra 'in-process'`, or an `AttributeError` saying `SDMClient` has no attribute `in_process`, is an installed client older than the feature, whichever command installed it. From 1ff5d20409a4b79f47f6913213a738be4af6cffd Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Mon, 9 Nov 2026 16:30:29 -0800 Subject: [PATCH 10/13] Fail the release that leaves the checkout install behind The references build from a checkout because no published release carries in_process(). The release that first does makes that instruction wrong, and nothing would catch it: the references are prose, and the example harness runs them against this tree rather than against the index. So the client's own version decides which install the references may carry, and a version that goes final fails hygiene until both drop the checkout and pin the floor. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- RELEASING.md | 6 +++ scripts/check_repo_hygiene.py | 83 ++++++++++++++++++++++++++++++++++- 2 files changed, 87 insertions(+), 2 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index 12fe2e97a..9fe06903c 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -77,6 +77,12 @@ The version is written in several places, and all of them move together: `tests/test_release_contract.py` fails if `_version.py`, the Rust workspace, `java/pom.xml` or a first-party pin disagree. Search for the old version afterwards to catch anything else, such as the coordinates in `java/README.md`. +Going from a prerelease to a release also retires the checkout build the +skills' in-process references tell a reader to run, because the extra alone +carries `in_process()` from then on. `python scripts/check_repo_hygiene.py +in-process` fails until both `skills/*/references/in-process.md` drop that +block and pin the extra to the version that first carries it. + Update `CHANGELOG.md`: the entries for the release go under its own heading with the date you are tagging on, not the date you wrote them, so the tag carries a changelog that names the version it diff --git a/scripts/check_repo_hygiene.py b/scripts/check_repo_hygiene.py index 9962e1d6c..b486d4d9b 100644 --- a/scripts/check_repo_hygiene.py +++ b/scripts/check_repo_hygiene.py @@ -3,7 +3,7 @@ # All rights reserved. # SPDX-License-Identifier: Apache-2.0 -"""Three checks this repository has to pass before it can be published. +"""The checks this repository has to pass before it can be published. ``spdx`` asserts every first-party source file carries a licence header. A file added without one is otherwise invisible until a release audit finds it. @@ -13,6 +13,12 @@ chooses its own roots will miss a tree, so this enumerates from ``git ls-files``. +``in-process`` asserts the skills' in-process references install the way the +client's own version allows. They build from a checkout because no release +carries ``in_process()`` yet, and the release that first does makes that +instruction wrong. Nothing else would catch it: the references are prose, and +the example harness runs them against this tree rather than against the index. + ``internal`` asserts no internal-only reference reaches a *shipped* file. The distinction matters: an internal URL in a provenance record is correct and required, while the same URL in shipped source is a leak. So the scan covers @@ -361,11 +367,81 @@ def check_repository_url() -> int: return 0 + +IN_PROCESS_REFERENCES = ( + 'skills/tabular/references/in-process.md', + 'skills/relational/references/in-process.md', +) + +# While the client's version is a prerelease, no index carries `in_process()` +# and the references have to build from a checkout. Once it is a release they +# must not, and the extra needs a floor instead. The two states are exact +# opposites, so each one is asserted rather than only the one in force. +CHECKOUT_INSTALL = 'git clone -b v2-candidate' +PRERELEASE_VERSION = re.compile(r'(?:a|b|rc|\.dev)\d+$') +IN_PROCESS_FLOOR = re.compile(r'structured-data-models-client\[in-process\]>=\d') +CLIENT_VERSION_FILE = ( + 'packages/structured-data-models-client/src/sdm_client/_version.py' +) + + +def check_in_process_install() -> int: + """The in-process references must install the way this version allows.""" + version_file = REPO_ROOT / CLIENT_VERSION_FILE + found = re.search( + r"__version__ = '([^']+)'", version_file.read_text(encoding='utf-8') + ) + if found is None: + print(f'no __version__ in {CLIENT_VERSION_FILE}', file=sys.stderr) + return 1 + version = found.group(1) + prerelease = PRERELEASE_VERSION.search(version) is not None + + findings = [] + for relative in IN_PROCESS_REFERENCES: + body = (REPO_ROOT / relative).read_text(encoding='utf-8') + checkout = CHECKOUT_INSTALL in body + if prerelease and not checkout: + findings.append( + f'{relative}: installs from the index, but {version} is not ' + 'a release and carries no in_process()' + ) + if not prerelease and checkout: + findings.append( + f'{relative}: still builds from a checkout, but {version} ' + 'is a release' + ) + if not prerelease and not IN_PROCESS_FLOOR.search(body): + findings.append( + f'{relative}: the extra names no version floor, so an older ' + 'client satisfies it' + ) + + for finding in findings: + print(f'in-process install: {finding}', file=sys.stderr) + if findings: + print( + '\nA reader runs the first install that fits their client. When ' + 'a release carries in_process(), drop the checkout block from ' + 'both references and pin the extra to that version.', + file=sys.stderr, + ) + return 1 + print(f'the in-process references install the way {version} allows') + return 0 + def main() -> int: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument( 'check', - choices=('spdx', 'internal', 'retired', 'repo-url', 'all'), + choices=( + 'spdx', + 'internal', + 'retired', + 'repo-url', + 'in-process', + 'all', + ), ) args = parser.parse_args() if args.check == 'spdx': @@ -376,11 +452,14 @@ def main() -> int: return check_retired() if args.check == 'repo-url': return check_repository_url() + if args.check == 'in-process': + return check_in_process_install() return ( check_spdx() | check_internal() | check_retired() | check_repository_url() + | check_in_process_install() ) From 97e8c16ba70def7739337e6febf26c3d4a93b451 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Mon, 9 Nov 2026 16:45:20 -0800 Subject: [PATCH 11/13] Install the connectors the relational gather imports Gathering a relational request reaches sdm_client._rust.providers, which imports every provider module eagerly, and each one imports sdm_connectors at module scope. That package is in none of the extras the reference named, so a client installed exactly as the page said raised ModuleNotFoundError on materialize(), for frames that were already in memory and no warehouse in sight. The page said that could not happen. The install carries the connectors package now, the sentence that promised otherwise says what gathering actually reaches, and the harness fails with that name rather than an import traceback when it is missing. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- scripts/check_repo_hygiene.py | 6 ++++-- skills/relational/references/in-process.md | 10 +++++++--- tests/test_skills.py | 9 ++++++--- 3 files changed, 17 insertions(+), 8 deletions(-) diff --git a/scripts/check_repo_hygiene.py b/scripts/check_repo_hygiene.py index b486d4d9b..7276020e2 100644 --- a/scripts/check_repo_hygiene.py +++ b/scripts/check_repo_hygiene.py @@ -367,7 +367,6 @@ def check_repository_url() -> int: return 0 - IN_PROCESS_REFERENCES = ( 'skills/tabular/references/in-process.md', 'skills/relational/references/in-process.md', @@ -379,7 +378,9 @@ def check_repository_url() -> int: # opposites, so each one is asserted rather than only the one in force. CHECKOUT_INSTALL = 'git clone -b v2-candidate' PRERELEASE_VERSION = re.compile(r'(?:a|b|rc|\.dev)\d+$') -IN_PROCESS_FLOOR = re.compile(r'structured-data-models-client\[in-process\]>=\d') +IN_PROCESS_FLOOR = re.compile( + r'structured-data-models-client\[in-process\]>=\d' +) CLIENT_VERSION_FILE = ( 'packages/structured-data-models-client/src/sdm_client/_version.py' ) @@ -430,6 +431,7 @@ def check_in_process_install() -> int: print(f'the in-process references install the way {version} allows') return 0 + def main() -> int: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument( diff --git a/skills/relational/references/in-process.md b/skills/relational/references/in-process.md index ac59d2530..07b6994b8 100644 --- a/skills/relational/references/in-process.md +++ b/skills/relational/references/in-process.md @@ -11,7 +11,9 @@ compiles the client's native extension, so it needs rustup and the toolchain `rust/rust-toolchain.toml` pins; pip runs the build from the client's own directory, where rustup does not read that pin, which is what the variable names. The client pins the API package to a version that is not published -either, so install that from the checkout too: +either, so install that from the checkout too, and the connectors package +beside it: gathering reaches the client's data providers, and they are read +even when the tables are already frames in memory. ``` git clone -b v2-candidate \ @@ -19,6 +21,7 @@ git clone -b v2-candidate \ cd structured-data-models-client RUSTUP_TOOLCHAIN=1.97.0 pip install \ -e './packages/structured-data-models-api' \ + -e './packages/structured-data-models-connectors' \ -e './packages/structured-data-models-client[in-process]' ``` @@ -34,8 +37,9 @@ an `AttributeError` saying `SDMClient` has no attribute `in_process`, is an installed client older than the feature, whichever command installed it. The extra brings structured-data-models and PyTorch, and needs Python 3.11 -or later. Gathering the request needs nothing beyond it: the client carries -that itself. Without it, `SDMClient.in_process()` raises `MissingExtraError` +or later. Gathering the request happens in this client, with no model and no +engine behind it, but it imports the connectors package the install above +names. Without it, `SDMClient.in_process()` raises `MissingExtraError` naming that command; on Python 3.10 the error names the Python it needs instead. The first prediction fetches the published weights, `nvidia/Kumo-Relational` on Hugging Face, into the Hugging Face cache, and diff --git a/tests/test_skills.py b/tests/test_skills.py index 13a089a30..18ce90a9b 100644 --- a/tests/test_skills.py +++ b/tests/test_skills.py @@ -2253,11 +2253,14 @@ def test_the_in_process_examples_print_what_the_skill_shows(name): and run the model here, which is what the reference claims they do. ``SDM_IN_PROCESS`` is the reader asking for exactly this, so a missing - extra is a broken setup and fails here rather than skipping quietly. One - extra covers both references: gathering a relational request is the base - client's own work, so nothing else has to be installed to run them. + piece is a broken setup and fails here rather than skipping quietly. The + extra is not the whole of it for the relational reference: gathering a + request reaches the client's data providers, which import the connectors + package even when the tables are frames already in memory. """ installed('sdm', 'structured-data-models-client[in-process]') + if name.startswith('relational/'): + installed('sdm_connectors', 'structured-data-models-connectors') assert_every_example_prints_what_it_shows(SKILLS / name) From ec659a2aa146b5b37d8661b6c755c77b612e4325 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Mon, 9 Nov 2026 16:51:55 -0800 Subject: [PATCH 12/13] Hold the floor to the release that carries the feature Three things the first cut got wrong. The index install the relational page promises for after the release dropped the connectors package, so it would have reproduced the same materialize() failure the checkout install was just fixed for. The check read any prerelease as a client without in_process(), so 2.1.0rc1 would have demanded the checkout instructions back. And the floor it accepted was any floor at all, which >=1.0.0 satisfies while carrying none of the feature. The release that first carries it is now named once, and both the version in hand and the floor the page pins are compared against it. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- scripts/check_repo_hygiene.py | 57 +++++++++++++++------- skills/relational/references/in-process.md | 7 +-- 2 files changed, 43 insertions(+), 21 deletions(-) diff --git a/scripts/check_repo_hygiene.py b/scripts/check_repo_hygiene.py index 7276020e2..fda16706c 100644 --- a/scripts/check_repo_hygiene.py +++ b/scripts/check_repo_hygiene.py @@ -372,20 +372,29 @@ def check_repository_url() -> int: 'skills/relational/references/in-process.md', ) -# While the client's version is a prerelease, no index carries `in_process()` -# and the references have to build from a checkout. Once it is a release they -# must not, and the extra needs a floor instead. The two states are exact -# opposites, so each one is asserted rather than only the one in force. +# The release that first carries `in_process()`. Until the index has it the +# references have to build from a checkout; from that release on they must not, +# and the extra needs a floor no older than this. It is the feature's release +# rather than "any prerelease", so that 2.1.0rc1 does not read as a client +# without the feature and ask for the checkout back. +FIRST_IN_PROCESS_RELEASE = (2, 0, 0) CHECKOUT_INSTALL = 'git clone -b v2-candidate' -PRERELEASE_VERSION = re.compile(r'(?:a|b|rc|\.dev)\d+$') +PRERELEASE_SUFFIX = re.compile(r'(?:a|b|rc|\.post|\.dev)\d+$') IN_PROCESS_FLOOR = re.compile( - r'structured-data-models-client\[in-process\]>=\d' + r'structured-data-models-client\[in-process\]>=(\d+(?:\.\d+)*)' ) CLIENT_VERSION_FILE = ( 'packages/structured-data-models-client/src/sdm_client/_version.py' ) +def _release(version: str) -> tuple[tuple[int, ...], bool]: + """The version's release numbers, and whether a prerelease follows them.""" + prerelease = PRERELEASE_SUFFIX.search(version) + base = version[: prerelease.start()] if prerelease else version + return tuple(int(part) for part in base.split('.')), prerelease is not None + + def check_in_process_install() -> int: """The in-process references must install the way this version allows.""" version_file = REPO_ROOT / CLIENT_VERSION_FILE @@ -396,27 +405,39 @@ def check_in_process_install() -> int: print(f'no __version__ in {CLIENT_VERSION_FILE}', file=sys.stderr) return 1 version = found.group(1) - prerelease = PRERELEASE_VERSION.search(version) is not None + release, prerelease = _release(version) + unpublished = release < FIRST_IN_PROCESS_RELEASE or ( + release == FIRST_IN_PROCESS_RELEASE and prerelease + ) + first = '.'.join(str(part) for part in FIRST_IN_PROCESS_RELEASE) findings = [] for relative in IN_PROCESS_REFERENCES: body = (REPO_ROOT / relative).read_text(encoding='utf-8') checkout = CHECKOUT_INSTALL in body - if prerelease and not checkout: - findings.append( - f'{relative}: installs from the index, but {version} is not ' - 'a release and carries no in_process()' - ) - if not prerelease and checkout: + if unpublished and not checkout: findings.append( - f'{relative}: still builds from a checkout, but {version} ' - 'is a release' + f'{relative}: installs from the index, but {version} is ' + f'before {first}, the release that first carries in_process()' ) - if not prerelease and not IN_PROCESS_FLOOR.search(body): + if not unpublished and checkout: findings.append( - f'{relative}: the extra names no version floor, so an older ' - 'client satisfies it' + f'{relative}: still builds from a checkout, but {version} is ' + f'{first} or later' ) + if not unpublished: + floor = IN_PROCESS_FLOOR.search(body) + if floor is None: + findings.append( + f'{relative}: the extra names no version floor, so an ' + 'older client satisfies it' + ) + elif _release(floor.group(1))[0] < FIRST_IN_PROCESS_RELEASE: + findings.append( + f'{relative}: the extra floors at {floor.group(1)}, which ' + f'a client without in_process() satisfies; {first} is the ' + 'first that carries it' + ) for finding in findings: print(f'in-process install: {finding}', file=sys.stderr) diff --git a/skills/relational/references/in-process.md b/skills/relational/references/in-process.md index 07b6994b8..d4ddcccdc 100644 --- a/skills/relational/references/in-process.md +++ b/skills/relational/references/in-process.md @@ -25,11 +25,12 @@ RUSTUP_TOOLCHAIN=1.97.0 pip install \ -e './packages/structured-data-models-client[in-process]' ``` -Once a release carries it, that build goes away and the extra is the whole -install: +Once a release carries it, that build goes away, but the connectors package +does not: gathering imports it whatever the client was installed from. ``` -pip install 'structured-data-models-client[in-process]' +pip install 'structured-data-models-client[in-process]' \ + structured-data-models-connectors ``` A pip warning that the client `does not provide the extra 'in-process'`, or From 27cc6e19e2096851989cb2abf2dcf0d69801a143 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Tue, 10 Nov 2026 12:33:38 -0800 Subject: [PATCH 13/13] Read the version the way PEP 440 orders it The check decided whether this client carries in_process() by stripping suffixes with anchored regexes. That read .post1 as a step towards the release rather than past it, left .post1.dev1 for int() to choke on, could not see a version at all behind a local label, dropped the epoch, and compared the extra's floor on release numbers alone, so >=2.0.0rc1 passed for a floor of 2.0.0. It now parses the version with PEP 440's own grammar and compares the sort key that grammar defines, for the client's version and the extra's floor alike. Checked against packaging over every version that spelling can build: 59,136 of them, no disagreement on the gate, and none on ordering beyond the local label this deliberately ignores. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- scripts/check_repo_hygiene.py | 117 ++++++++++++++++++++++++++++------ 1 file changed, 96 insertions(+), 21 deletions(-) diff --git a/scripts/check_repo_hygiene.py b/scripts/check_repo_hygiene.py index fda16706c..89be52c73 100644 --- a/scripts/check_repo_hygiene.py +++ b/scripts/check_repo_hygiene.py @@ -377,22 +377,90 @@ def check_repository_url() -> int: # and the extra needs a floor no older than this. It is the feature's release # rather than "any prerelease", so that 2.1.0rc1 does not read as a client # without the feature and ask for the checkout back. -FIRST_IN_PROCESS_RELEASE = (2, 0, 0) +FIRST_IN_PROCESS = '2.0.0' CHECKOUT_INSTALL = 'git clone -b v2-candidate' -PRERELEASE_SUFFIX = re.compile(r'(?:a|b|rc|\.post|\.dev)\d+$') +# A version, as PEP 440's grammar spells one. That grammar orders the +# suffixes as well as naming them: a development release precedes whatever it +# hangs off, a pre-release precedes the release it names, and a post-release +# follows it. A local label orders after nothing that matters here, so it is +# read and dropped. +PEP_440 = re.compile( + r""" + v? + (?:(?P\d+)!)? + (?P\d+(?:\.\d+)*) + (?:[-_.]?(?Palpha|beta|preview|pre|rc|a|b|c) + [-_.]?(?P
\d+)?)?
+    (?:-(?P\d+)
+       |[-_.]?(?Ppost|rev|r)[-_.]?(?P\d+)?)?
+    (?:[-_.]?(?Pdev)[-_.]?(?P\d+)?)?
+    (?:\+[a-z0-9]+(?:[-_.][a-z0-9]+)*)?
+    """,
+    re.IGNORECASE | re.VERBOSE,
+)
+PRE_RELEASE_NAMES = {
+    'alpha': 'a',
+    'a': 'a',
+    'beta': 'b',
+    'b': 'b',
+    'c': 'rc',
+    'pre': 'rc',
+    'preview': 'rc',
+    'rc': 'rc',
+}
+BEFORE_ANY = (-1,)
+AFTER_ANY = (1,)
+
 IN_PROCESS_FLOOR = re.compile(
-    r'structured-data-models-client\[in-process\]>=(\d+(?:\.\d+)*)'
+    r'structured-data-models-client\[in-process\]>=([^\'"\s,\]]+)'
 )
 CLIENT_VERSION_FILE = (
     'packages/structured-data-models-client/src/sdm_client/_version.py'
 )
 
 
-def _release(version: str) -> tuple[tuple[int, ...], bool]:
-    """The version's release numbers, and whether a prerelease follows them."""
-    prerelease = PRERELEASE_SUFFIX.search(version)
-    base = version[: prerelease.start()] if prerelease else version
-    return tuple(int(part) for part in base.split('.')), prerelease is not None
+def _version(version: str) -> tuple[object, ...]:
+    """What the version sorts as, by PEP 440's rules.
+
+    Trailing zeros go, so 2.0 is the 2.0.0 it names. A release with nothing
+    after it sorts above every pre-release of itself and below every
+    post-release of itself, and a development release with neither of those in
+    front of it sorts below the lot.
+    """
+    found = PEP_440.fullmatch(version.strip())
+    if found is None:
+        raise ValueError(f'not a version this check can read: {version!r}')
+
+    release = [int(part) for part in found['release'].split('.')]
+    while len(release) > 1 and release[-1] == 0:
+        release.pop()
+
+    posted = (
+        found['post_name'] is not None or found['implicit_post'] is not None
+    )
+    if found['pre_name'] is not None:
+        pre: tuple[object, ...] = (
+            0,
+            PRE_RELEASE_NAMES[found['pre_name'].lower()],
+            int(found['pre'] or 0),
+        )
+    elif found['dev_name'] is not None and not posted:
+        pre = BEFORE_ANY
+    else:
+        pre = AFTER_ANY
+
+    post = (
+        (0, int(found['implicit_post'] or found['post'] or 0))
+        if posted
+        else BEFORE_ANY
+    )
+    dev = (
+        (0, int(found['dev'] or 0))
+        if found['dev_name'] is not None
+        else AFTER_ANY
+    )
+
+    return (int(found['epoch'] or 0), tuple(release), pre, post, dev)
 
 
 def check_in_process_install() -> int:
@@ -405,11 +473,8 @@ def check_in_process_install() -> int:
         print(f'no __version__ in {CLIENT_VERSION_FILE}', file=sys.stderr)
         return 1
     version = found.group(1)
-    release, prerelease = _release(version)
-    unpublished = release < FIRST_IN_PROCESS_RELEASE or (
-        release == FIRST_IN_PROCESS_RELEASE and prerelease
-    )
-    first = '.'.join(str(part) for part in FIRST_IN_PROCESS_RELEASE)
+    first = _version(FIRST_IN_PROCESS)
+    unpublished = _version(version) < first
 
     findings = []
     for relative in IN_PROCESS_REFERENCES:
@@ -418,12 +483,12 @@ def check_in_process_install() -> int:
         if unpublished and not checkout:
             findings.append(
                 f'{relative}: installs from the index, but {version} is '
-                f'before {first}, the release that first carries in_process()'
+                f'before {FIRST_IN_PROCESS}, the release that first carries in_process()'
             )
         if not unpublished and checkout:
             findings.append(
                 f'{relative}: still builds from a checkout, but {version} is '
-                f'{first} or later'
+                f'{FIRST_IN_PROCESS} or later'
             )
         if not unpublished:
             floor = IN_PROCESS_FLOOR.search(body)
@@ -432,12 +497,22 @@ def check_in_process_install() -> int:
                     f'{relative}: the extra names no version floor, so an '
                     'older client satisfies it'
                 )
-            elif _release(floor.group(1))[0] < FIRST_IN_PROCESS_RELEASE:
-                findings.append(
-                    f'{relative}: the extra floors at {floor.group(1)}, which '
-                    f'a client without in_process() satisfies; {first} is the '
-                    'first that carries it'
-                )
+            else:
+                try:
+                    floored = _version(floor.group(1))
+                except ValueError:
+                    findings.append(
+                        f'{relative}: the extra floors at {floor.group(1)}, '
+                        'which is not a version pip can read'
+                    )
+                else:
+                    if floored < first:
+                        findings.append(
+                            f'{relative}: the extra floors at '
+                            f'{floor.group(1)}, which a client without '
+                            f'in_process() satisfies; {FIRST_IN_PROCESS} is '
+                            'the first that carries it'
+                        )
 
     for finding in findings:
         print(f'in-process install: {finding}', file=sys.stderr)