Payload types¶

Every port declares a dtype. Fluksio checks values against it and offers compatible messages when you bind dashboard widgets.

Messages carry JSON. Binary data lives in the artifact store; messages carry references to it.

Scalars¶

NaN and infinity are rejected, including in structured payloads. For an unavailable numeric result, omit that output or return None to publish nothing. A numeric port does not accept None as its value.

Structured payloads¶

record¶

An object with string keys and scalar or null values. Nested objects and lists are not allowed.

{"title": "Boiler", "body": "Pressure low", "severity": "warning"}

Notification and Player widgets read records. Dashboard alert channels also publish them.

list¶

An array with a declared item type:

list and series cannot be declared as item types. Use item: "json" if items need arbitrary nested structures.

series¶

Labelled lines of numeric [timestamp, value] pairs:

{
  "lines": [
    {"label": "living", "points": [[1717000000, 21.4], [1717000060, 21.5]]}
  ],
  "range_s": 86400,
  "interval_s": 60
}

Additional top-level keys are preserved. A Query chart expects the range_s and interval_s from its request in the response; this prevents an answer for another window from replacing its chart.

The run-series comparison endpoint also returns this shape.

artifact¶

A reference to bytes in the content-addressed artifact store:

{"digest": "sha256:…", "size": 4194304, "media_type": "application/octet-stream", "name": "weights.pt"}

digest and size identify the content. media_type and name describe it. The reference works wherever the store is reachable.

Create one with fluksio.save_artifact and read its bytes with fluksio.load_artifact. See Artifacts.

image, audio, video¶

Artifact references restricted to the matching media_type family:

{
  "digest": "sha256:…",
  "size": 61344,
  "media_type": "image/jpeg",
  "name": "frame.jpg",
  "meta": {"width": 1280, "height": 720, "seq": 41}
}

An audio port accepts audio/*; image and video work the same way. An artifact port accepts all three. Optional meta fields are for the consumer; Fluksio does not interpret them.

A media stream is a streaming port publishing one reference per frame or chunk. Saving with volatile=True keeps bytes in memory and lets local websocket clients receive them with the value. Stored media and portal views fetch the bytes separately.

Use occasional snapshots through a portal. For continuous video, point a Media widget's Live stream at a browser-compatible source URL reachable by the screen.

json¶

Any JSON-serializable value. Use it for payloads without a fixed shape. Prefer a specific type when one fits; it gives widgets and other authors a clearer contract.

Referencing a run's output¶

A run parameter can name an existing value instead of repeating it:

• @run:<id>.<output> resolves an earlier run's output.
• sha256:… resolves an artifact digest.

These strings resolve before the run starts, regardless of the input's type. Both prefixes are reserved even for str inputs; they cannot be passed as literal text in run parameters.

Widget bindings¶

Player transport commands publish to a separate str message. Binding checks apply in the editor and on the server.

Icon and colour names¶

Forecast reads a list of records with label, icon and value, plus optional color:

[{"label": "Today", "icon": "cloud-rain", "color": "primary", "value": "14°"}]

The Icon widget uses the same vocabulary:

An empty icon draws nothing. Unknown icons use a placeholder; unknown colours use default. Each warns once in the browser console.

Type failures¶

A mismatched value raises an error on the node that produced it, naming the port and received value. It is not published downstream.

See also¶

• Flows, nodes and messages
• Node types
• Dashboards and devices