# Overview 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](https://docs.privatemind.com/training-sdk.html), [fine-tuning](https://docs.privatemind.com/sdk-finetune.html), [workspace jobs](https://docs.privatemind.com/sdk-jobs.html), [model servers](https://docs.privatemind.com/sdk-model-servers.html), your org's [model weights](https://docs.privatemind.com/sdk-weights.html), [image generation](https://docs.privatemind.com/sdk-images.html), and [batch work](https://docs.privatemind.com/sdk-batch.html). For chat completions, embeddings, and everything else OpenAI-shaped, keep using the [OpenAI SDK](https://docs.privatemind.com/openai-sdk.html) with your PrivateMind base URL. ## Install ```sh pip install privatemind ``` It needs Python 3.11 or newer. With uv, run `uv add privatemind`. The [package](https://pypi.org/project/privatemind/) 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`](https://docs.privatemind.com/training-sdk.html#promote-a-notebook-function) needs `pip install 'privatemind[promote]'`. - [Market data](https://docs.privatemind.com/sdk-market-data.html) 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](https://docs.privatemind.com/workspaces.html). 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](https://docs.privatemind.com/sdk-images.html), [batch](https://docs.privatemind.com/sdk-batch.html) | | App backend | `app_url=` or `PRIVATEMIND_APP_URL` | `https://privatemind.com` | [training jobs](https://docs.privatemind.com/training-sdk.html), [workspace jobs](https://docs.privatemind.com/sdk-jobs.html), [model servers](https://docs.privatemind.com/sdk-model-servers.html), [model weights](https://docs.privatemind.com/sdk-weights.html) | 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](https://docs.privatemind.com/api-keys.html): 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](https://docs.privatemind.com/sdk-market-data.html) | | `ModelServerFailedError` | a model server crashed or could not start while `server.wait()` was watching it. See [Model servers](https://docs.privatemind.com/sdk-model-servers.html) | | `SecretNotFoundError` | a secret the code asked for is not attached to this workspace or job. See [Secrets](https://docs.privatemind.com/secrets.html) | | `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](https://docs.privatemind.com/training-sdk.html#the-run-handle) | | `UnknownStatusError` | a batch reported a status this SDK release can classify as neither running nor finished; carries `batch_id` and `status`. See [batch](https://docs.privatemind.com/sdk-batch.html) | | `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](https://docs.privatemind.com/training-sdk.html): submit and manage training jobs, promote a notebook function into a training job. - [Workspace jobs](https://docs.privatemind.com/sdk-jobs.html): one command in a workspace image on a home volume, by hand, from the SDK, or on a schedule. - [Fine-tuning](https://docs.privatemind.com/sdk-finetune.html): 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](https://docs.privatemind.com/sdk-evaluate.html): score a fine-tuned model on your own eval set, push it to your registry and serve it. - [Model weights](https://docs.privatemind.com/sdk-weights.html): 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](https://docs.privatemind.com/sdk-images.html): text to image in one typed call. - [Batch](https://docs.privatemind.com/sdk-batch.html): bulk chat-completion work at 50% of the normal token rate. - [Market data](https://docs.privatemind.com/sdk-market-data.html): read the feeds added to a workspace with DuckDB; the SDK handles the keys. - [Workspaces](https://docs.privatemind.com/workspaces.html): the environment the SDK lives in, pre-wired.