Get API key

Overview

View as Markdown

The platform's Python SDK: training jobs, fine-tuning, image generation, and batch work. On PyPI as privatemind; pre-installed in every workspace.

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

shell
pip install privatemind

It 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.train needs pip 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:

Python
import privatemind

The 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:

  1. token= passed to Client(...)
  2. the PRIVATEMIND_TOKEN environment variable
  3. the ~/.privatemind/auth file

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:

Python
import privatemind

privatemind.reconfigure(token="PMIND...:abcdef...")  # keeps the injected URLs

For 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:

Python
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.

Python
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 privatemind command 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.