Skip to main content
Post-deployment endpoint verification with a synthetic tile. Answers the first question a customer has after deploying a model and installing the SDK: is the endpoint up, reachable, and returning the output I expect? The check builds a synthetic tile of the exact geometry the model declares, sends it through whichever backend the customer deployed (remote, aws, local, or huggingface), and validates the response against the model’s output contract. Unlike the probes in bioptimus.observability.probes, this module performs real work: it constructs a client, opens a connection or loads a checkpoint, and issues a billable inference request. It is therefore never run implicitly as part of a diagnostic snapshot — the caller asks for it explicitly, through verify_endpoint, the bioptimus verify CLI subcommand, or the verify argument of build_support_bundle. Like the probes, the entry point is fail-safe by default: every failure is captured as a Check carrying its ErrorCode and remediation, so a broken deployment still yields a complete, shareable report instead of a traceback. Pass raise_on_failure=True to turn the first failure into a raised BioptimusRuntimeError instead. Example:

​
Check

Outcome of a single verification step. Attributes:
  • name - Stable slug identifying the step, for example "embedding_request".
  • passed - Whether the step succeeded. A skipped step is reported as passed so that a model which does not offer a mode cannot fail the run.
  • duration_ms - Wall-clock duration of the step in milliseconds.
  • skipped - Whether the step did not run (for example a mode the model does not expose). detail carries the reason.
  • detail - Human-readable outcome or failure detail.
  • error_code - The ErrorCode value for a failed step, otherwise None.
  • remediation - Actionable hint for a failed step, otherwise None.
  • context - Structured fields describing the step, for example the observed and expected output lengths.

​
HealthReport

Result of verifying one model on one backend. Attributes:
  • schema_version - Version of this report’s shape.
  • captured_at - UTC ISO-8601 timestamp of the run.
  • model - Model name that was verified, for example "h1".
  • backend - Backend that was verified, for example "aws".
  • target - Human-readable description of what was reached (a base URL, a SageMaker endpoint name, a checkpoint path, or a Hub repo), or None when the client could not be built.
  • modes - Inference modes that were attempted.
  • ok - Whether every non-skipped check passed.
  • checks - The checks in execution order.

​
failures

Returns the checks that ran and failed, in execution order.

​
to_dict

Returns the JSON-friendly representation of the report. Returns: A mapping suitable for json.dumps, for inclusion in a support bundle, or for printing from the CLI.

​
summary

Returns a one-line, human-readable verdict. Returns: A string such as "h1 on remote: ok (3 checks)" or "h1 on remote: FAILED — embedding_request [BIO-NET-001]".

​
synthetic_tile

Builds a deterministic synthetic RGB tile. The tile combines a smooth two-axis gradient with low-amplitude seeded noise, so it is neither a constant image (which can mask a broken normalisation path) nor pure noise (which compresses poorly and is harder to eyeball in a server log). The same seed and size always produce byte-identical pixels, so repeated runs are directly comparable.
​
Tile (width, height) in pixels.
​
Seed for the noise component.
Returns: An RGB PIL.Image.Image of the requested size.

​
synthetic_expression

Builds a synthetic bulk-RNA expression vector.
​
Number of genes the model expects, in the model’s gene order.
Returns: A list of num_genes identical, non-zero expression values.

​
verify_endpoint

Verifies that a deployed model endpoint is up and correctly configured. Builds a client for backend, fetches model metadata, sends one synthetic tile per requested inference mode, and validates each response against the model’s declared output contract (length, finiteness, and echoed tile metadata). Every step is recorded as a Check; nothing raises unless raise_on_failure is set.
​
Model name, for example "h1" or "m-optimus". Must match a registered SDK model config.
​
Backend to verify: "remote", "aws", "local", or "huggingface".
​
Inference modes to exercise. "auto" (the default) resolves the modes the model actually exposes — embedding only for the plain backbones, prediction only for tissue-seg, both for m-optimus — and narrows to embedding for the huggingface backend, which has no prediction head. Pass "embedding", "prediction", or a sequence of both to force a specific set.
​
Tile (width, height) to send. Defaults to the size in the model’s tile spec, which is what a correctly configured endpoint expects; override only to probe how an endpoint handles another size.
​
Seed for the synthetic tile, so runs are reproducible.
​
When True, raises instead of returning a report whose ok is False.
​
Forwarded verbatim to Backbone — for example base_url for remote, endpoint_name and region_name for aws, model_dir or checkpoint for local, and device or precision for huggingface.
Returns: A HealthReport describing every check that ran. Raises:
  • BioptimusValueError - When modes names a mode that cannot be verified, or when tile_size is not a pair of positive integers. Both are raised up front, before any client is built.
  • BioptimusRuntimeError - When raise_on_failure is True and any check failed. The error carries the first failure’s code and the full report in its context.