> This page is for Structured Data Models Client.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/sdgm/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/sdgm/_mcp/server.

# Predict with Custom Context

> Status of supplying labeled context examples directly to a Kumo Relational prediction task

> **Warning**
>
> **Not available for Kumo Relational.** Supplying your own labeled context and prediction rows as DataFrames, bypassing PQL, is not supported for the relational model in this client.

## What exists today

sdm-client builds one `Request` type for every model, and the direct builder — `Request(context=..., predict=..., target=..., task=...)` — accepts `related_tables=` in its signature. A relational request is gathered, not assembled from frames, though: the neighborhood around each entity is sampled and folded onto the instance table, which is what `materialize()` does. So a directly-built request is refused when you name `model=KumoRelational()`, even with `related_tables=`:

```python
from sdm_client import Request, SDMClient, KumoRelational

request = Request(
    context=labelled,
    predict=to_score,
    target="churn",
    task="classification",
    related_tables={"orders": orders_df},
)

with SDMClient(url="http://localhost:8000") as client:
    client.predict(request, model=KumoRelational())
# UnsupportedRequestError: a relational request has to be gathered first...
```

The direct builder works for **Kumo Tabular**, where it is the primary path — see [Kumo Tabular: Make Predictions](/sdgm/kumo-tabular/user-guide/make-predictions/make-predictions).

## What to use instead

Build the request from PQL, as described in [Make Predictions](/sdgm/kumo-relational/user-guide/make-predictions/make-predictions) and [Write Predictive Queries](/sdgm/kumo-relational/user-guide/make-predictions/writing-predictive-queries):

```python
from sdm_client import PredictiveQuery

query = PredictiveQuery(query_text, schema)
request = query.materialize(indices=entity_ids)
```

`materialize()` derives context examples from the schema's own historical data; there is currently no supported way to substitute context you constructed yourself for the relational model.

If your workflow specifically needs hand-selected relational context — for example, to test how a particular set of examples affects prediction quality — that capability is not available in this client version. Check the [changelog](https://github.com/NVIDIA/structured-data-models-client/blob/main/CHANGELOG.md) for updates.