privatemind is the platform's Python SDK. It covers the surfaces that go beyond the OpenAI-compatible API: training jobs, fine-tuning, workspace jobs, model servers, your org's model weights, image generation, and batch work. For chat completions, embeddings, and everything else OpenAI-shaped, keep using the OpenAI SDK with your PrivateMind base URL.
Install
pip install privatemindIt needs Python 3.11 or newer. With uv, run uv add privatemind. The package and the import share the name, and pip install privatemind-python resolves to the same package.
Three features need an extra:
- Reading a run's metrics, params or artifacts back from MLflow needs
pip install 'privatemind[mlflow]'. - Promoting a notebook function with
@pm.trainneedspip install 'privatemind[promote]'. - Market data needs
privatemind[market-data], which current workspace images already carry.
Call the first two without their extra and they raise ConfigError naming it. Everything else works on the base install.
Pre-configured in every workspace
The SDK comes pre-installed and pre-configured in every PrivateMind workspace. Open a notebook and import it, with nothing to set up:
import privatemindThe workspace injects everything the SDK needs as environment variables:
| Variable | What it provides |
|---|---|
PRIVATEMIND_TOKEN |
a scoped bearer token issued to the workspace |
PRIVATEMIND_URL |
the platform API base URL (image generation, batch) |
PRIVATEMIND_APP_URL |
the app backend base URL (training jobs) |
PRIVATEMIND_TARGET_CLUSTER |
the GPU cluster the workspace runs on |
PRIVATEMIND_HOME_VOLUME / PRIVATEMIND_HOME_PATH |
the home Volume used to stage promoted code |
Every example in this section runs as-is inside a workspace, with no token, URL or cluster name to supply. Outside a workspace, such as on a laptop or in CI, you supply a token yourself, as below.
Two base URLs
The SDK talks to two services:
| Service | Configure with | Default | Serves |
|---|---|---|---|
| Platform API | base_url= or PRIVATEMIND_URL |
https://api.privatemind.com |
image generation, batch |
| App backend | app_url= or PRIVATEMIND_APP_URL |
https://privatemind.com |
training jobs, workspace jobs, model servers, model weights |
Both default to the production platform, so outside a workspace you set a token and nothing else. The keyword argument wins over the environment variable, which wins over the default. Inside a workspace both variables are injected.
Authentication
The client resolves the bearer token in order:
token=passed toClient(...)- the
PRIVATEMIND_TOKENenvironment variable - the
~/.privatemind/authfile
Outside a workspace, the token is a PrivateMind API key: the full PMIND...:abcdef... string. If you keep it in ~/.privatemind/auth, the SDK checks the file before reading it: it must be mode 0600, owned by the user running Python, and not a symlink. Anything else raises AuthError and says what to fix.
Base URLs must be https://. For local development there is an escape hatch, allow_insecure_http=True or PRIVATEMIND_ALLOW_INSECURE_HTTP=1. Leave it off everywhere else.
Module functions and the explicit Client
Every API call exists twice: as a module-level function (from privatemind import generate_image) and as a method on Client. The module functions share one process-wide client, created from the environment on first use. When credentials or URLs change mid-session, as they do in a long-lived notebook, reconfigure(...) builds a replacement and closes the old one:
import privatemind
privatemind.reconfigure(token="PMIND...:abcdef...") # keeps the injected URLsFor explicit control, construct a Client yourself and use it as a context manager (or call close() when done). Configuration is resolved eagerly, so a missing token fails at construction, not on the first request:
from privatemind import Client
with Client(
base_url="https://api.privatemind.com", # optional: this is the default
app_url="https://privatemind.com", # optional: this is the default
token="PMIND...:abcdef...",
) as pm:
for j in pm.list_jobs():
print(j.kind, j.name, j.phase)Client also takes timeout= (per-request seconds, default 30) and verify= (TLS verification, on by default); reconfigure(...) accepts the same keyword arguments. Every module function accepts client= to route a single call through an explicit client. Clients refuse to pickle, because the token would travel with them: construct one per process.
Timeouts and retries
Each request gets the client's timeout (default 30 seconds). Raise it for slow calls, such as image generation at high step counts or large batch result downloads.
Retries follow one rule: reads retry, writes never do.
| Calls | Behavior |
|---|---|
| Reads: job status, batch status, listings, file downloads | Up to 3 attempts on network failures, timeouts, and 5xx responses. A 503 waits for the server's Retry-After (capped at 60 seconds); everything else backs off exponentially with jitter. |
| Writes: submit a job, upload a file, create or cancel a batch, generate an image | Sent exactly once, so nothing non-idempotent is ever duplicated. A transient failure raises ServerError, and you decide whether to resend. |
4xx responses are never retried. A 429 raises RateLimitError immediately, carrying the server's Retry-After; the SDK does not sleep on your behalf.
Errors
Everything the SDK raises derives from PrivatemindError. HTTP-mapped errors carry the response status_code and the server's error message; errors raised before a request leaves have status_code = None.
| Exception | Raised when |
|---|---|
ConfigError |
configuration cannot be resolved: an http:// URL without the escape hatch, or an invalid URL scheme |
AuthError |
no token, an unsafe ~/.privatemind/auth file, or HTTP 401 |
ForbiddenError |
HTTP 403: authenticated but not permitted. Subclasses AuthError, so except AuthError catches it too |
ValidationError |
a bad argument caught client-side, or HTTP 400 |
NotFoundError |
HTTP 404 |
ConflictError |
HTTP 409, e.g. a job name that already exists |
RateLimitError |
HTTP 429; retry_after holds the parsed Retry-After header in seconds, or None |
ServerError |
HTTP 5xx after retries are exhausted, and network or timeout failures |
MarketDataError |
market data can't be read: nothing mounted, no such feed, or a read refused for memory. See Market data |
ModelServerFailedError |
a model server crashed or could not start while server.wait() was watching it. See Model servers |
SecretNotFoundError |
a secret the code asked for is not attached to this workspace or job. See Secrets |
UnknownPhaseError |
a training run or a workspace job reported a phase this SDK release can classify as neither running nor finished; carries run_name and phase. See training jobs |
UnknownStatusError |
a batch reported a status this SDK release can classify as neither running nor finished; carries batch_id and status. See batch |
UnknownStateError |
the base of the two above, so one except covers a run and a batch |
PrivatemindError |
the base class; raised directly only for statuses with no mapping above |
Validation is fail-fast: a malformed image size, an invalid job name, or an out-of-range worker count raises ValidationError before any request is made.
from privatemind import NotFoundError, PrivatemindError, RateLimitError, get_job
try:
run = get_job("tj-abc12")
except NotFoundError:
print("no such job")
except RateLimitError as e:
print(f"rate limited; retry in {e.retry_after or 30:.0f}s")
except PrivatemindError as e:
print(e.status_code, e.message)Where next
- Training jobs: submit and manage training jobs, promote a notebook function into a training job.
- Workspace jobs: one command in a workspace image on a home volume, by hand, from the SDK, or on a schedule.
- Fine-tuning: SFT, DPO, KTO and GRPO in one call, as a LoRA or QLoRA adapter or with every weight trained, validated before it costs a GPU.
- Evaluate and publish: score a fine-tuned model on your own eval set, push it to your registry and serve it.
- Model weights: push a folder of weights to your org's registry as a version, pull it back, share or delete it. The
privatemindcommand does all of it except sharing. - Image generation: text to image in one typed call.
- Batch: bulk chat-completion work at 50% of the normal token rate.
- Market data: read the feeds added to a workspace with DuckDB; the SDK handles the keys.
- Workspaces: the environment the SDK lives in, pre-wired.