Skip to main content

AI Box Library

Python library for the NXP Edge AI Industrial Platform.

Overview

ai-box-lib provides thin clients for component-to-component communication:

  • DataCollectorClient for publishing data collector payloads
  • PreProcessorClient for subscribing data collector payloads and publishing features
  • PostProcessorClient for subscribing ML model results and publishing processed results
  • ContextEngineClient for publishing context messages
  • ChannelClient for generic pub/sub communication between any components
  • AppClient for Edge Apps: subscribe and publish by the input and output names the app version declares

Installation

Install from PyPI:

pip install ai-box-lib

Quick Start

1) Publish data from a data collector

from ai_box_lib.data_collector_client import DataCollectorClient

client = DataCollectorClient[dict]()
client.connect()
client.publish_timestream({"random_number": "42"})

2) Subscribe and publish from a pre-processor

from ai_box_lib.pre_processor_client import PreProcessorClient

client = PreProcessorClient[dict, dict]()
client.connect()

def handle_raw(message: dict) -> None:
	processed = {"feature_a": [1.0, 2.0, 3.0]}
	client.publish_data(processed)

unsubscribe = client.subscribe_timestream(handle_raw)

3) Reduce model output in a post-processor

from ai_box_lib.post_processor_client import PostProcessorClient

client = PostProcessorClient[dict, dict]()
client.connect()

def handle_inference(message: dict) -> None:
	client.publish_object_detection([[10, 20, 30, 40, 0.9, 2]])  # x, y, w, h, score, classIndex

unsubscribe = client.subscribe_inference_result(handle_inference)

The task type of the pipeline's model is available as client.model_task_type. It is a label: what arrives in the handler is whatever the model emitted, which for object detection is typically a raw detection head that this component exists to reduce. Parse it yourself.

The model version's metadata is available as client.model_meta_data, typed as the variant matching model_task_type — ObjectDetectionModelMetaData, ClassificationModelMetaData, and so on — each declaring only the fields its task type uses. It is None when the version declares no metadata, or the box is too old to send it, so guard the object rather than each field. See the "Prepare a vision model" platform guide for the per-task-type fields.

4) Publish and subscribe to context data

from ai_box_lib.context_engine_client import ContextEngineClient

client = ContextEngineClient[dict]()
client.connect()
client.publish_data({"state": "ok"})

In a multi-asset setup, a single context engine is often responsible for all assets. Pass custom_asset_id to publish to a different asset's context engine topic:

client.publish_data({"state": "ok"}, custom_asset_id="asset-abc123")
from ai_box_lib.context_engine_client import ContextEngineClient
client = ContextEngineClient[dict]()
client.connect()
client.subscribe()

client.context  # Access the latest context value at any time

def handle_context(message: dict) -> None:
	print(f"Context update: {message}")

client.subscribe(handle_context) # Subscribe with a handler to receive real-time updates

Optionally you can pass custom_asset_id to subscribe to a Context Engine on a different asset, as long as it's connected to the same Box.

5) Communicate over a generic channel

A channel lets any two components exchange messages without being tied to a specific pipeline stage. You define the channel by providing a channel_id string. Both publisher and subscriber must use the same channel_id.

Messages are delivered on the topic {asset_id}/channel/{channel_id}.

Publisher:

from ai_box_lib.channel_client import ChannelClient

client: ChannelClient[None, dict] = ChannelClient("my-alerts")
client.connect()
client.publish({"severity": "high", "value": 42.0})

Subscriber:

from ai_box_lib.channel_client import ChannelClient

client: ChannelClient[dict, None] = ChannelClient("my-alerts")
client.connect()

def handle_alert(message: dict) -> None:
    print(f"Alert received: {message}")

unsubscribe = client.subscribe(handle_alert)
# call unsubscribe() when done

A single client instance can both publish and subscribe on the same channel.

6) Build an Edge App

AppClient subscribes to and publishes on the inputs and outputs an Edge App version declares, by name.

from ai_box_lib.app_client import AppClient

client = AppClient()
client.connect()

def handle_detections(message: dict) -> None:
    client.publish("alerts", {"receivedFrom": "detections"})

if client.has_input("detections"):
    client.subscribe("detections", handle_detections)

subscribe doesn't block: handlers run on background threads while main.py carries on.

Correlation IDs

Every message carries a correlation id so you can trace one piece of data through the pipeline (e.g. link an ML result back to its source frame). It is minted automatically at the origin and forwarded automatically when you publish from inside a subscription handler — no extra code needed.

Read the id of the message being handled with current_correlation_id():

def handle_raw(message: dict) -> None:
    frame_id = client.current_correlation_id()
    client.publish_data(process(message))  # inherits frame_id automatically

Automatic forwarding only works when you publish from within the handler. If you publish later — from another thread, a timer, or an external trigger such as an API callback — capture the id and pass it back explicitly. Every publish* method accepts an optional correlation_id:

client.publish_data(process(message), correlation_id=frame_id)

API Summary

All clients must call connect() before any publish or subscribe operation.

  • DataCollectorClient.connect()
  • DataCollectorClient.publish_timestream(data, correlation_id?)
  • DataCollectorClient.publish_audio(data, correlation_id?)
  • DataCollectorClient.publish_image(data, correlation_id?)
  • PreProcessorClient.connect()
  • PreProcessorClient.subscribe_timestream(handler)
  • PreProcessorClient.subscribe_audio(handler)
  • PreProcessorClient.subscribe_image(handler)
  • PreProcessorClient.publish_data(data, correlation_id?)
  • PostProcessorClient.connect()
  • PostProcessorClient.subscribe_inference_result(handler)
  • PostProcessorClient.publish_anomaly_detection(score, correlation_id?)
  • PostProcessorClient.publish_classification(scores, correlation_id?)
  • PostProcessorClient.publish_regression(values, correlation_id?)
  • PostProcessorClient.publish_object_detection(detections, correlation_id?)
  • PostProcessorClient.publish_custom(data, correlation_id?) — for a CUSTOM task type, or any payload the publishers above do not fit
  • PostProcessorClient.model_task_type — task type declared on the pipeline's model (read-only)
  • PostProcessorClient.model_meta_data — metadata declared on the pipeline's model version (read-only)
  • ContextEngineClient.connect()
  • ContextEngineClient.publish_data(data, custom_asset_id?, correlation_id?)
  • ContextEngineClient.subscribe(handler?, custom_asset_id?)
  • ContextEngineClient.context — latest received context value (read-only)
  • ChannelClient(channel_id).connect()
  • ChannelClient(channel_id).publish(data, correlation_id?)
  • ChannelClient(channel_id).subscribe(handler)
  • AppClient().connect()
  • AppClient().publish(name, data, correlation_id?) — publish on a declared output
  • AppClient().subscribe(name, handler) — subscribe a connected input; messages arrive decoded
  • AppClient().has_input(name) — whether a declared input is connected
  • current_correlation_id() — id of the message currently being handled (any client; None outside a handler)

Validation and Limits

  • DataCollectorClient validates message keys against CHANNELS.
  • PreProcessorClient validates feature keys and feature shapes against FEATURES.
  • PostProcessorClient does not validate published payloads. The task type is a label, not a contract; the per-task-type publishers build a payload the platform can interpret, and publish_custom publishes whatever it is given.
  • AppClient raises ValueError for an undeclared input or output and for an unconnected input. It doesn't validate payload contents, but drops a message it can't decode, logging Dropping undecodable payload on input '<name>', without calling the handler.
  • Maximum publish payload size is 2 MB.

Changelog

2.0.0

Breaking: audio travels on the box's message bus as raw bytes instead of a list of numbers.

  • Needs box software 2.x (com.nxp.proxy-node 2.0.0 or later). Update the box from the portal before deploying a 2.x component to it; a box on 2.x takes only 2.x components. To stay on a 1.x box, pin ai-box-lib<2.
  • publish_audio takes audioChunk as bytes only.
  • The deprecated InferenceType alias is removed; use TaskResultType.

License

BSD-3-Clause. See LICENSE.

Metadata

Release files for ai-box-lib 2.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ai-box-lib 2.0.0
File Size Uploaded Provenance Actions
ai_box_lib-2.0.0.tar.gz 28.1 kB Without provenance Details for ai_box_lib-2.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ai-box-lib 2.0.0
File Interpreter ABI Platform Actions
ai_box_lib-2.0.0-py3-none-any.whl Python 3 none any Details for ai_box_lib-2.0.0-py3-none-any.whl

Total release size: 61.7 kB

Release files / ai_box_lib-2.0.0.tar.gz

Download URL ai_box_lib-2.0.0.tar.gz
Size 28.1 kB
Tags Source
SHA-256 checksum
How to use checksums
5f6490d3eab242cc66db796adcfd5e45260f922fbdb70480ff9a5bae41c06e8b
BLAKE2b-256 checksum
How to use checksums
52e3c8a6cd62b5358fc1c839661aeb9d4dfae95327c00be038786eca1c87afe8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / ai_box_lib-2.0.0-py3-none-any.whl

Download URL ai_box_lib-2.0.0-py3-none-any.whl
Size 33.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ebcb21fbc3926865dd58fa3e9a742f7ea7647fb1ed34c3a2f2b7643f45be2f8e
BLAKE2b-256 checksum
How to use checksums
79f8b842f5fa998b2c48b8a52f380b0687485b132bcf01792c128f8a1ffce2a1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for ai-box-lib 2.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page