> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bioptimus.com/llms.txt
> Use this file to discover all available pages before exploring further.
# bioptimus.observability.healthcheck
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`](/sdk-reference/observability/healthcheck#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`](/sdk-reference/observability/healthcheck#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**:
```python theme={null}
from bioptimus.observability.healthcheck import verify_endpoint
report = verify_endpoint("h1", backend="remote", base_url="http://localhost:8080")
print(report.ok, [check.name for check in report.checks if not check.passed])
```
## Check
```python theme={null}
@dataclass(frozen=True)
class 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
```python theme={null}
@dataclass(frozen=True)
class 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
```python theme={null}
@property
def failures() -> list[Check]
```
Returns the checks that ran and failed, in execution order.
***
#### to\_dict
```python theme={null}
def to_dict() -> dict[str, Any]
```
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
```python theme={null}
def summary() -> str
```
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
```python theme={null}
def synthetic_tile(size: tuple[int, int] = _DEFAULT_TILE_SIZE,
*,
seed: int = _DEFAULT_SEED) -> Image.Image
```
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
```python theme={null}
def synthetic_expression(num_genes: int) -> list[float]
```
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
```python theme={null}
@log_failures
def verify_endpoint(model: str = "h1",
backend: str = "remote",
*,
modes: Sequence[str] | str = "auto",
tile_size: tuple[int, int] | None = None,
seed: int = _DEFAULT_SEED,
raise_on_failure: bool = False,
**backend_kwargs: Any) -> HealthReport
```
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`](/sdk-reference/observability/healthcheck#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`](/sdk-reference/observability/healthcheck#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`.