ModelOutput

class rapidtools.models.ModelOutput(text: str | None = None, masks: Any | None = None, bounding_boxes: list | None = None, raw_response: Any | None = None, error: str | None = None, retryable: bool = True)

Bases: object

A universal container for multimodal AI model outputs.

Variables:

• text (str | None) – Generated text (vision-language models).

• masks (Any | None) – Segmentation masks, e.g. a list of NumPy arrays for SAM 3.

• bounding_boxes (list | None) – Detected boxes as [x0, y0, x1, y1] lists.

• raw_response (Any | None) – The provider’s raw JSON or the raw tensors/metadata of a local model, kept for debugging.

• error (str | None) – Why the request produced no output (None on success). Transient failures (rate limits, timeouts) are still reported as a plain None return from run_inference; this field marks responses the provider actively rejected.

• retryable (bool) – Whether the same request could succeed later. Provider rejections (refusals, safety blocks, 4xx errors) set it to False so callers do not pause and retry them.

Example

>>> from rapidtools.models.base import ModelOutput
>>> out = ModelOutput(text='  ', bounding_boxes=[[0, 0, 4, 4]])
>>> out.has_text
False
>>> out.has_bounding_boxes
True
>>> ModelOutput.failure('refused').retryable
False

Methods

failure

Build an output that records why the request failed.

error: str | None = None

Why the request produced no usable output; None on success.

retryable: bool = True

Whether sending the same request again could succeed. False for provider rejections (refusals, safety blocks, 4xx errors).

classmethod failure(error: str, *, retryable: bool = False, raw_response: Any | None = None) → ModelOutput

Build an output that records why the request failed.

property failed: bool

True when the request failed (see error).

property has_text: bool

True when text contains non-whitespace characters.

property has_masks: bool

True when masks is set.

property has_bounding_boxes: bool

True when at least one bounding box is present.