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. A standalone agent keeps no samples by default, so start it with --store-type memory or --store-type disk before you query live data.

The agent provisions the Python a notebook declares (>=3.10 in the starter) when you first open or run it. You install nothing 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

Both write the same minimal starter that connects to the agent. When you are signed in, the app also credits you under authors:

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() returns a Vega-Lite chart that renders inline in the app, in an exported HTML page, and in JupyterLab.

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  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 styled page with prose, code and every output, alongside the terminal stream. Vega-Lite charts render offline; Plotly charts load the Plotly library from the web. 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: the app, publishing, tagging, and every zelos notebook command, including pull.