API reference

Bringup

Prerequisites: Python 3.12, a virtualenv, and .env with MONGODB_URI (Atlas IP allowlist must include your machine) and the VIAM_* robot credentials. bash setup.sh creates the venv, installs requirements.txt, and copies .env.example to .env.

Mock bringup (no hardware): FEELS_MOCK=1 python realtime_plot.py --port 8080, then open http://localhost:8080. The dashboard serves the full UI on bundled recordings; a purple MOCK badge marks the mode.

Live bringup: python realtime_plot.py --port 8080. Verify with curl localhost:8080/api/status — atlas_configured reports Atlas reachability and cycle reports the macro state. Teach one item in Mode 2, then run Mode 1 on a mystery cup.

Python modules

Generated with pdoc from the docstrings. Each page has inline source and a GitHub link.

atlas.py — vector memory: teach, identify, predict_lda
feature_extractor.py — 10-D signatures from torque telemetry
embedder.py — hand / pca / chronos embedding backends
teach_csv.py — batch teaching CLI

Module relationships. realtime_plot orchestrates: it calls feature_extractor for signatures, atlas for memory, and teach_csv handles batch ingestion.

HTTP API — realtime_plot.py

Request flow. The dashboard posts to realtime_plot, which queries Atlas and streams telemetry back over SSE.

Method	Path	Handler	What it does
`GET`	`/`	`handle_index`
`GET`	`/docs`	`handle_docs`	Serve the built-in docs pages (the presentation). /docs and /docs/{page}.
`GET`	`/docs/{page}`	`handle_docs`	Serve the built-in docs pages (the presentation). /docs and /docs/{page}.
`GET`	`/stream`	`handle_stream`
`POST`	`/tare`	`handle_tare`
`POST`	`/record/start`	`handle_record_start`
`POST`	`/record/stop`	`handle_record_stop`
`GET`	`/record/download`	`handle_record_download`
`POST`	`/api/cycle/predict`	`handle_cycle_predict`	Mode 1: run the swirl macro on a mystery cup → features → Atlas $vectorSearch.
`POST`	`/api/cycle/teach`	`handle_cycle_teach`	Mode 2: run the swirl macro on a labeled item → save signature to Atlas.
`POST`	`/api/cycle/abort`	`handle_cycle_abort`	Stop the running macro subprocess (physical e-stop remains at the venue).
`POST`	`/api/cycle/correct`	`handle_cycle_correct`	Teach the true label for the most recent prediction's recording.
`GET`	`/api/status`	`handle_api_status`
`POST`	`/api/vectorspace`	`handle_vspace`	2-D PCA of the Atlas signature library, optionally with the query

teach_csv.py — CLI

python teach_csv.py [paths] [flags]

Flag	What it does
`paths`	CSV files
`--session`	session tag (default: thu
`--label`	force one label for all files"
`--dry-run`	show what would be taught"
`--force`	re-teach files already in Atlas"
`--include-mystery`
`--require-swirl`
`--list`	show signature counts per label"