Python Client

synthefy is the lightweight client and workflow package. Install synthefy-nori as well when you want to run the model locally. This page covers SynthefyNoriClient. Its one class, SynthefyNoriClient, runs the same predict call against the hosted service, an Amazon SageMaker endpoint, or a local copy of the model.

One call, every backend

mode="remote" uses the hosted API, mode="sagemaker" uses your AWS endpoint, and mode="local" runs in-process.

Takes DataFrames

Hand it a DataFrame and it aligns columns by name and encodes categoricals for you, rather than making you build a numeric matrix.

Joint targets

Pass a target matrix to predict related numeric outcomes together and draw samples from their joint distribution.

Retries built in

Timeouts, connection errors, 429s and 5xx are retried with exponential backoff.

Use this client when you want one API for hosted, SageMaker, and local execution. Local mode requires synthefy-nori; importing base synthefy stays lightweight and never imports Torch. For the lower-level local estimator, use NoriRegressor from the quickstart.

Quickstart

Install the appropriate distribution from the installation guide, then get a key from the API key guide.

import os
from synthefy import SynthefyNoriClient

client = SynthefyNoriClient(
    api_key=os.environ["SYNTHEFY_NORI_API_KEY"],
    mode="remote",
    model="synthefy/nori-30m",
)

X_train = [[0.0, 1.0], [1.0, 0.0], [0.5, 0.5], [0.2, 0.8]]
y_train = [0.1, 0.9, 0.5, 0.3]
X_test  = [[0.3, 0.7], [0.8, 0.2]]

print(client.predict(X_train, y_train, X_test))

[0.37, 0.72]

predict returns one float per row of X_test, in order. Pass as_pandas=True to get a pandas.Series instead.

Choosing a mode

mode decides where the model runs. It defaults to "remote".

`mode`	Runs	Needs
`"remote"`	the hosted endpoint	an API key; no GPU, no download
`"sagemaker"`	your SageMaker endpoint	the `aws` dependencies, an endpoint name, and AWS credentials
`"local"`	in-process, via `synthefy-nori`	the local runtime; no key or network

Choose the mode deliberately. The client never switches because it found local packages or ambient credentials. Change only mode and its backend-specific configuration when promoting the same workflow:

# No key or network. The model is still explicit.
client = SynthefyNoriClient(mode="local", model="nori-30m")

# Hosted production path.
client = SynthefyNoriClient(
    api_key=os.environ["SYNTHEFY_NORI_API_KEY"],
    mode="remote",
    model="synthefy/nori-30m",
)

For Marketplace subscription and endpoint creation, follow the Amazon SageMaker guide.

Predicting from DataFrames

Pass DataFrames and the client builds the numeric matrix for you. X_test is aligned to X_train by column name, so column order does not matter; a mismatch in the column sets raises.

preds = client.predict(df_train, y_train, df_test, as_pandas=True)

Non-numeric columns are encoded, fit on X_train and applied to X_test:

Default (categorical_encoding="ordinal") — each categorical column becomes one column of integer codes, from X_train’s categories in sorted order. A value seen only in X_test maps to -1; missing stays NaN and is imputed server-side.
categorical_encoding="onehot" — one indicator column per category, and missing values get their own indicator.
max_categorical_cardinality (default 100) caps how many distinct values a categorical column may have. Above it the column is dropped, with a warning telling you to encode it yourself.

Configuration

Constructor parameters

Parameter	Default	Description
`model`	required	Size selector (`"nori-6m"`, `"nori-30m"`) or a raw gateway slug. No default; omitting it raises `ValueError`.
`mode`	`"remote"`	`"remote"`, `"sagemaker"`, or `"local"`. `"auto"` is rejected.
`api_key`	`None`	Remote mode only. Falls back to the `SYNTHEFY_NORI_API_KEY` environment variable.
`timeout`	`300.0`	Per-request timeout in seconds.
`max_retries`	`2`	Retries on timeouts, connection errors, 429 and 5xx, with exponential backoff.
`auth_scheme`	`"Bearer"`	The gateway needs `"Bearer"`; dedicated deployments use `"Api-Key"`.
`base_url` / `endpoint`	the hosted gateway	Point at a dedicated deployment instead.
`endpoint_name`	`None`	Required with `mode="sagemaker"`; the SageMaker endpoint to invoke.
`region_name`	AWS configuration	AWS region containing the SageMaker endpoint.
`user_agent`	`None`	Custom `User-Agent` header.

predict parameters

Parameter	Default	Description
`as_pandas`	`False`	Return a `pandas.Series` instead of a list.
`categorical_encoding`	`"ordinal"`	`"ordinal"` or `"onehot"`.
`max_categorical_cardinality`	`100`	A non-numeric column with more distinct values than this is dropped, with a warning telling you to encode it yourself.
`discretize`	`None`	Remote mode returns point predictions only, so `"snap-mean"` is the only strategy it supports; the others need `mode="local"`. See Categorical & Ordinal Targets.
`text_columns`	`None`	Names the free-text columns. See Installation.
`timeout`	inherits the client	Override the timeout for one call.
`extra_headers`	`None`	Additional HTTP headers.

Get Started

Guides

Integration

One call, every backend

Takes DataFrames

Joint targets

Retries built in

Quickstart

Choosing a mode

Predicting from DataFrames

Configuration

Next steps

API key

Quickstart

One call, every backend

Takes DataFrames

Joint targets

Retries built in

​Quickstart

​Choosing a mode

​Predicting from DataFrames

​Configuration

​Next steps

API key

Quickstart

Quickstart

Choosing a mode

Predicting from DataFrames

Configuration

Next steps