Skip to content

Notebooks

A Zelos notebook is a markdown file with runnable Python cells, executed by the Zelos Agent against real trace data. This page is the fastest path from nothing installed to a notebook that queries, charts, and checks live data.

1. Install

Choose either workflow — both run the same notebooks.

  • Zelos App — install the app for the notebook library, visual editor, and inline outputs.
  • Command line — install the CLI and run a Zelos Agent. The app also provides an agent on localhost:2300, so the CLI works against it too.

The agent provisions Python for you (>=3.10) the first time a notebook runs; nothing to install yourself.

2. Get some data

Every example on this site runs against the demo generator, so you don't need real hardware to try a notebook. In a spare terminal:

zelos live demo --backfill 5m --duration 30m

That publishes a simulated battery pack and CAN bus for the next 30 minutes — enough to work through the rest of this page.

3. Create a notebook

Select Notebooks in the left sidebar, then New notebook.

zelos notebook new analysis.md

Either way you get a minimal starter that connects to the agent:

analysis.md
---
requires-python: '>=3.10'
dependencies:
- zelos-sdk[notebook]
---

```python
from zelos_sdk import connect

agent = connect()
agent
```

4. Query and chart

Add a cell that pulls a window of signals and charts them:

frame = agent.query("bus0/BMS_message/cells.*", start="-2m", downsample=400)
frame.plot()

agent.query() returns an Arrow-backed frame; .plot() renders inline in the app, in an exported HTML page, or in any Jupyter viewer.

5. Add a check

A check reports instead of raising, so every rule runs and you see the whole board. One raise_if_failed() at the end turns any failure into the run's outcome:

from zelos_sdk import connect, CheckResults

cells = agent.query("bus0/BMS_message/cells.*", start="-2m")
results = CheckResults(
    agent.check.that(series, ">", 3.0, name=path)
    for path, series in cells.short_names().items()
)
results.raise_if_failed()

Each column of the frame is a series that carries the window you queried, so the rule covers exactly the samples you looked at. The demo generator plants one weak cell on purpose, so this raises AssertionError:

AssertionError: 1 of 8 checks did not pass:
  2026-09-04 17:08:46.989  cell_3 · cells.cell_3 (2.988 V) > 3 V  always  FAILED

That's the point: a notebook full of checks is a test suite for your system, and its exit code says whether it passed. A single rule needs no scoreboard: assert agent.check.that(...).

6. Run and export

Choose Run all in the status bar, or run one cell with Cmd/Ctrl+Enter.

zelos notebook run analysis.md -o analysis.html

-o writes a self-contained, styled page — prose, code, and every output — alongside the terminal stream. The run's exit code makes the same run a CI gate — see Notebooks as tests for the outcomes it reports, and run for every flag.

Where to next

  • Example notebooks

    Seven complete, runnable examples — triage, forensics, units, CI gates, and more.

  • The notebook format

    Front matter, cells, {.norun}, parameters, and the lockfile.

  • Zelos Notebooks

    The full guide: publishing, tagging, and every CLI verb.