AI

AI runs ONNX models on the appliance through a model-agnostic tensor interface, with client-side helpers that add per-model-family semantics (pre-processing, detection decoding).

Models are *.onnx files in the appliance model directory (OLO_AI_MODEL_DIR, default /app/models/ai in the appliance image). The shipped YOLOX weights (yolox_s.onnx, yolox_tiny.onnx, yolox_nano.onnx) live in apps/appliance/models/ai/ (Git LFS). Load one by name, then exchange named tensors; shape and dtype metadata comes from the model itself via info() (dynamic dimensions are reported as -1).

For object detection, the YoloDetector adapter wraps a YOLOX model with letterbox pre-processing, output decoding, and non-maximum suppression, returning standard Detection results whose boxes plug directly into the vision depth helpers.

AI wrapper over olo.ai.v1.Ai — generic ONNX model inference.

Service

class olo.ai.Ai[source]

Bases: object

Sync wrapper for the AI gRPC service.

__init__(session)[source]

Bind to a channel session.

Return type:

None

list_models(*, timeout=30.0)[source]

List loadable model names in the appliance model directory.

Return type:

list[str]

Parameters:

timeout (float)

load_model(name, *, timeout=30.0)[source]

Load a model by file name and return a session handle.

Return type:

Model

Parameters:
model_info(model_id, *, timeout=30.0)[source]

Fetch metadata for an already-loaded model session.

Return type:

ModelInfo

Parameters:
class olo.ai.Model[source]

Bases: object

Handle for a loaded ONNX model session on the appliance.

__init__(client, info)[source]

Bind to the Ai client and a loaded model’s metadata.

Parameters:
Return type:

None

property id: str

Server-assigned session id.

infer(inputs, *, output_names=None, timeout=60.0)[source]

Run inference with named input arrays; returns named output arrays.

Return type:

dict[str, ndarray]

Parameters:
property info: ModelInfo

Model input/output metadata.

unload(*, timeout=30.0)[source]

Release the model session on the appliance.

Return type:

None

Parameters:

timeout (float)

Types

class olo.ai.ModelInfo[source]

Bases: object

Metadata for a loaded ONNX model session.

__init__(model_id, name, inputs, outputs, metadata=<factory>)
Parameters:
Return type:

None

class olo.ai.TensorInfo[source]

Bases: object

Declared model input/output; dynamic dimensions are -1.

__init__(name, dtype, shape)
Parameters:
Return type:

None

class olo.ai.Detection[source]

Bases: object

Standard object-detection result returned by detector adapters.

Fields map 1:1 onto a future olo.ai.v1.Detection wire message. The box is an olo.vision.BoundingBox, so detections feed directly into depth helpers such as sample_depth_region and deproject_region.

__init__(label, class_id, score, box)
Parameters:
Return type:

None

Processing helpers

olo.ai.processing.letterbox(array, size, *, pad_value=114, center=False)[source]

Resize an HWC image to (height, width) preserving aspect ratio with padding.

Return type:

LetterboxResult

Parameters:
olo.ai.processing.image_to_tensor(array, *, layout='NCHW', channel_order='BGR', dtype=<class 'numpy.float32'>, scale=None, mean=None, std=None)[source]

Convert an HWC BGR image array into a batched model input tensor.

Applies optional value scaling (e.g. 1/255) and per-channel mean/std normalization, then transposes to the requested layout with batch dim 1.

Return type:

ndarray

Parameters:
olo.ai.processing.nms(boxes_xyxy, scores, iou_threshold)[source]

Greedy non-maximum suppression; returns kept indices by descending score.

Return type:

list[int]

Parameters:
olo.ai.processing.softmax(values, axis=-1)[source]

Numerically stable softmax.

Return type:

ndarray

Parameters:

YOLOX adapter

class olo.ai.yolo.YoloDetector[source]

Bases: object

Runs a YOLOX ONNX model through a loaded Model and decodes detections.

__init__(model, *, labels=('person', 'bicycle', 'car', 'motorcycle', 'airplane', 'bus', 'train', 'truck', 'boat', 'traffic light', 'fire hydrant', 'stop sign', 'parking meter', 'bench', 'bird', 'cat', 'dog', 'horse', 'sheep', 'cow', 'elephant', 'bear', 'zebra', 'giraffe', 'backpack', 'umbrella', 'handbag', 'tie', 'suitcase', 'frisbee', 'skis', 'snowboard', 'sports ball', 'kite', 'baseball bat', 'baseball glove', 'skateboard', 'surfboard', 'tennis racket', 'bottle', 'wine glass', 'cup', 'fork', 'knife', 'spoon', 'bowl', 'banana', 'apple', 'sandwich', 'orange', 'broccoli', 'carrot', 'hot dog', 'pizza', 'donut', 'cake', 'chair', 'couch', 'potted plant', 'bed', 'dining table', 'toilet', 'tv', 'laptop', 'mouse', 'remote', 'keyboard', 'cell phone', 'microwave', 'oven', 'toaster', 'sink', 'refrigerator', 'book', 'clock', 'vase', 'scissors', 'teddy bear', 'hair drier', 'toothbrush'), input_size=None, strides=(8, 16, 32))[source]

Bind to a loaded model; input size is read from the model when static.

Parameters:
Return type:

None

detect(image, *, conf=0.25, iou=0.45)[source]

Detect objects in a BGR image and return score-sorted detections.

Return type:

list[Detection]

Parameters:
property input_size: tuple[int, int]

Model input size as (height, width).

olo.ai.yolo.decode_yolox(raw, input_size, *, strides=(8, 16, 32))[source]

Decode raw YOLOX output rows into (N, 5+C) pixel-space predictions.

YOLOX exports emit grid-relative rows (cx, cy, log w, log h, objectness, class scores…). This applies the per-stride grid offsets and exp scaling, yielding center-based boxes in input-image pixels.

Return type:

ndarray

Parameters:

Import from olo/ai:

Service

  • Ai Async wrapper for the AI gRPC service.

  • Model Handle for a loaded ONNX model session.

Types

  • ModelInfo Metadata for a loaded model session.

  • TensorInfo Declared model input/output.

  • Tensor Dense tensor backed by a typed array.

  • Detection Standard object-detection result.

Processing helpers

YOLOX adapter