diff --git a/AGENTS.md b/AGENTS.md index 035ce7410..1cab4e2fc 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 8860a3b8a..c6b26780e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -129,6 +129,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 +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/RELEASING.md b/RELEASING.md index 6e9a14bb3..fd526b184 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/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", + ")" ] }, { 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/scripts/check_repo_hygiene.py b/scripts/check_repo_hygiene.py index 8935716de..bc250351a 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 @@ -362,11 +368,179 @@ def check_repository_url() -> int: return 0 +IN_PROCESS_REFERENCES = ( + 'skills/tabular/references/in-process.md', + 'skills/relational/references/in-process.md', +) + +# 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 = '2.0.0' +CHECKOUT_INSTALL = 'git clone -b v2-candidate' +# 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\]>=([^\'"\s,\]]+)'
+)
+CLIENT_VERSION_FILE = (
+    'packages/structured-data-models-client/src/sdm_client/_version.py'
+)
+
+
+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:
+    """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)
+    first = _version(FIRST_IN_PROCESS)
+    unpublished = _version(version) < first
+
+    findings = []
+    for relative in IN_PROCESS_REFERENCES:
+        body = (REPO_ROOT / relative).read_text(encoding='utf-8')
+        checkout = CHECKOUT_INSTALL in body
+        if unpublished and not checkout:
+            findings.append(
+                f'{relative}: installs from the index, but {version} is '
+                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_IN_PROCESS} 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'
+                )
+            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)
+    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':
@@ -377,11 +551,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()
     )
 
 
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 c857efa46..6ec73bfbd 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 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
 
 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..d4ddcccdc
--- /dev/null
+++ b/skills/relational/references/in-process.md
@@ -0,0 +1,202 @@
+# 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 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, 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 \
+    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-connectors' \
+    -e './packages/structured-data-models-client[in-process]'
+```
+
+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]' \
+    structured-data-models-connectors
+```
+
+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. 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
+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 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
+`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())
+
+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')
+print(list(named.columns))
+```
+
+**Verified** in this process, on a CPU:
+
+```
+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`. `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.
+
+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
+serves it, with the same `result.explanations` a deployment that serves it
+gives, keyed by the entity:
+
+```python
+explained = client.predict(
+    request, model=KumoRelational(), outputs=['prediction', 'explanation']
+)
+print(sorted(explained.explanations.gradients))
+client.close()
+```
+
+**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. 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
+  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.
+  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.
+
+## 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
+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.
+
+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/SKILL.md b/skills/tabular/SKILL.md
index 734a2ad1b..c69a197d0 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
@@ -121,6 +121,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
@@ -247,4 +255,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..1d4a4870e
--- /dev/null
+++ b/skills/tabular/references/in-process.md
@@ -0,0 +1,171 @@
+# 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, 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:
+
+```
+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.
+
+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
+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 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
+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')
+
+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:
+
+```
+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. `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
+
+- **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 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. 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. 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.
+
+## 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
+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.
+
+```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.
diff --git a/tests/test_skills.py b/tests/test_skills.py
index 19a45436b..e8c406c24 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,42 @@ 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,
+    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.
+
+    ``SDM_IN_PROCESS`` is the reader asking for exactly this, so a missing
+    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)
+
+
 # --- What the tables in the skills claim ----------------------------------