Zelos Notebooks

A Zelos notebook is a plain markdown file with runnable Python cells. The local Zelos Agent executes each cell against real trace data through the Zelos Agent SDK — so a notebook is a repeatable analysis you can keep next to your code, diff in review, and re-run whenever the data changes.

Open it in the Zelos App for a visual editor and inline outputs, or use any text editor and run it from the command line. There's nothing proprietary about the file: prose is prose, and every top-level ```python fence is a cell.

What you get

• Plain markdown

  Prose and ```python cells in one file. Version it, review it, edit it anywhere. Outputs are never written back into the file.

• Run against live data

  Cells share one Python process and talk to the agent through connect() — query signals, compute on series, chart the result.

• Reproducible runs

  Zelos resolves each notebook's environment once and locks it. A publish carries that lock, so a fresh machine that pulls the notebook runs the same versions. Each cell's outputs record the run that produced them.

• Rendered output

  Add -o analysis.html (or .ipynb) to a run to also write a self-contained rendered notebook — prose, code, and every output — for archiving, sharing, or diffing runs.

Prerequisites

Choose either workflow:

• Zelos App — install the app for the notebook library, visual editor, and inline outputs. Open a workspace before opening a notebook; notebooks live in workspace tabs.
• Command line — run a Zelos Agent and install the Zelos CLI. The app also provides an agent on localhost:2300.

The agent provisions Python for you (>=3.10); you do not need to install it yourself.

No live data yet?

Run the demo generator in another terminal so the agent has signals to serve:

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

The paths below (bus0/BMS_message/status.*) come from this generator. Substitute your own if your catalog differs.

Work in the Zelos App

Select Notebooks in the left sidebar rail:

1. Choose New notebook to create a file in ~/Documents/Zelos Notebooks, Open notebook to open a .md or .markdown file elsewhere, or Examples to copy a runnable example into your library.
2. Select a notebook to open it in a workspace tab. Edit its name, description, and tags in the document header — editing the name renames the file. The sidebar switches from the library to the notebook's Parameters and Python settings; Back to Notebooks returns to the library.
3. Write prose in the document and Python in code cells. Changes autosave to the markdown file. See The notebook format for the small canonicalization changes the visual editor makes when it saves.
4. Run one cell with its play button or Cmd/Ctrl+Enter, or choose Run all in the status bar. The first run prepares the Python environment; later runs reuse it. Run out-of-date cells (Cmd/Ctrl+Shift+Enter) starts at the first changed cell and runs everything below it.

The status bar shows environment and kernel state, run progress, and whether outputs are up to date. A disconnected agent pauses runs but does not stop edits from saving.

The rail search filters notebook names, descriptions, relative paths, and folders. If a notebook's settings are open, typing a term shows the library and clearing it restores those settings. Press ↓ in the search field to enter the library; opening a result ends the search.

Renames and moves carry the notebook's separately stored outputs; deletion removes them.

Write a notebook

Get started with notebooks walks the whole round trip — create, query, chart, check, run, export. What that page leaves out is what a finished file looks like.

Any text is prose; every top-level ```python fence is a cell. Cells run top to bottom and share one Python process, so you connect once and reuse the handle everywhere below.

analysis.md

---
description: Rank the pack's cells and find the one that sags.
dependencies:
  - zelos-sdk[notebook]
params:
  window: "-2m"
---

Connect once, then later cells reuse `agent`.

```python
from zelos_sdk import connect

agent = connect()
agent
```

Pull the pack's cell voltages over the parameterized window. `params.window`
comes from the front matter and can be overridden at run time. A bare object
on a cell's last line renders itself, so this is the table.

```python
frame = agent.query("bus0/BMS_message/cells.*", start=params.window)
frame
```

Chart it. `plot()` emits Vega-Lite — the app renders it inline and an HTML
export renders it offline, with no plotting library in `dependencies`.

```python
frame.short_names().plot()
```

Summarize the spread across the pack.

```python
frame.short_names().describe()
```

zelos notebook run analysis.md runs it. The last line names the run's outcome and the exit code matches it — see Notebooks as tests.

The querying, series math, and charting all come from the Agent SDK — see Query Live Data for the full surface. List zelos-sdk in dependencies like any other package — the environment's lock pins the exact version it resolved to, and the [notebook] extra brings pandas and numpy with it.

Publish and share with Zelos Cloud

Each publish adds an immutable version: the saved source snapshot plus the latest settled outputs. Publishing does not run cells. A publish also ships the notebook's environment lock, so a machine that pulls the notebook and has never resolved its environment spec runs the same versions — see Environments. The first publish writes a remote block into the notebook's front matter, so this file — and every clone of it — publishes to the same cloud notebook from then on. Commit that block; see The remote block.

Publishing needs a signed-in account. Sign in with the Zelos App, or run zelos login on a headless machine — it authenticates in a browser and stores the credential in the system keyring.

A published notebook counts against your organization's cloud storage, and the plan sets how many cloud notebooks the organization can have.

From the Zelos App

Choose Share in the notebook header, then select who can open the cloud notebook: Only me, Organization, or Public link. See Publishing Notebooks for what each one lets in.

The owner or an organization admin can change organization-wide access; only the owner can switch a published notebook to Only me.

The app blocks publishing while a run is active, while its outputs could not be saved, or while the organization's cloud storage is full or its cloud uploads are turned off. If edited cells have stale outputs, it warns you but lets you publish so the snapshot remains an honest record of the current state.

After publishing succeeds, the Cloud view refreshes the notebook's row and publish history immediately. You do not need to reload it.

Public links are capabilities with two important constraints:

• A link stays pinned to the version it was created for. Publishing an update does not move existing links; create a new link to share the new version.
• Copy a newly created URL when it appears. For security, Zelos does not show that secret URL again. You can still rename or revoke the link later. Changing access from Public link to a restricted option revokes every active public link.

The Share dialog shows the three most recent versions. View opens a version in a read-only tab, with no file written and no kernel started. See all opens the complete history in Zelos Cloud.

Read a cloud notebook

Opening a notebook from the Cloud view, from a link, or from the console's Open in Zelos App renders the published version in a read-only tab. The tab switches between versions in place and offers the next step:

• Save to library saves the notebook into your notebooks folder, outputs and environment lock included, and opens it for editing. The file stays bound to the cloud notebook, so publishing from it adds a version there.
• Open local copy appears instead when your library already holds a file bound to that cloud notebook. Save a copy is the only way to get a second file.
• Update to latest appears when your local copy matches an older published version; it replaces the file with the newest version. A copy with local edits shows Local edits instead and is left alone.

Publishing from a copy of someone else's notebook that you cannot change offers Publish as a copy, which publishes to a new cloud notebook of your own and rebinds the file to it.

From the CLI

publish publishes the notebook's currently saved state and prints its cloud page:

zelos notebook publish analysis.md

To run and publish in one step, add --publish to a run. Errored runs publish too, because a failed test is exactly the run someone needs to see:

zelos notebook run analysis.md --publish

Flag	What it does
--org <slug>	Which organization to publish into. Needed only when you belong to several. Accepted by both publish and run --publish.
--visibility <org\|personal>	Who can see the cloud notebook. First publish only; defaults to org.
--new	Ignore the existing binding and fork onto a fresh cloud notebook.
--tag <name>	Add an organization tag. Repeatable. Never removes one. Accepted by both publish and run --publish.

The CLI publishes with Only me or Organization access. Create and manage public links from the app or the cloud notebook page. A publish that the cloud refuses, for a full storage pool or a notebook limit, fails with that reason and leaves the file untouched.

Tagging a notebook

Tags are organization vocabulary, shared with cloud traces and layouts, so a label means the same thing across everything your team publishes. They live in Zelos Cloud rather than in the file, which is what lets a rename reach every notebook, trace, and layout carrying the tag at once.

Tag a notebook in the app, from the header beside its authors. Search the organization's tags, tick them on and off, or type a name that isn't there yet to add it — anyone in the organization may. Each chip's colored dot opens the same color picker a signal chip uses.

Two rules decide what the header offers you, and it says which when it refuses:

• Changing a notebook's tags is for its owner, or an organization owner or admin.
• Renaming or recoloring a tag itself is for whoever created it, or an organization owner or admin. That one is per tag, so you can recolor the tags you made and not the ones you didn't.

A notebook you haven't published yet has no cloud copy to hold tags, so what you pick is applied by its first publish.

The console shows the same tags on the notebooks list, with Edit tags… on each row and a filter across the top. zelos tags list prints the vocabulary.

Publishing from the CLI can tag too:

zelos notebook publish analysis.md --tag battery --tag ci

--tag only ever adds, and every name must already exist — an unknown one fails before anything is published rather than quietly minting a tag nobody meant to create. Publishing the same tags again changes nothing, so a nightly run --publish --tag ci cannot wipe labels somebody curated.

That asymmetry is deliberate. A notebook's tags belong to the notebook, not to one version of it: publish version 9 and versions 1 through 8 carry the same tags, because there is one set for the whole notebook. A script that could rewrite it would be relabeling the whole history without seeing what it was overwriting. Removing a tag is something you do where you can see the whole set — the app's header or the console's list.

Tags say what a notebook is about. What a particular run did — its outcome, its parameters, when it ran and who published it — is already recorded on the version itself.

Where to next

• Example notebooks

  Seven complete, runnable examples — from first query to a CI release gate — against demo data.

• Notebooks as tests

  Checks score every rule, one assertion gates the run, and the exit code is the contract.

• The notebook format

  Front matter, cells, {.norun}, parameters, and environments.

• CLI reference

  new, list, run, publish, rename, copy, delete, mkdir, import, and env warm — every flag.

• Query Live Data

  The SDK surface your cells use: frames, series, latest values, charts.

• Open Trace Files

  Point the same query API at a saved .trz file.