# Always-On Agent Observability Dashboard

## PURPOSE
A Streamlit + Plotly dashboard that visualises a Pi Durable storage backend: per-task
checkpoint timelines, a status breakdown, tool-call success vs interruption, and a
storage-backend comparison (SQLite vs JSONL vs in-memory). It turns the invisible
"checkpoints and persistent state happening behind the scenes" into a live picture an
operator can read in seconds.

## WHY THIS MATTERS
The video admits the durability is hard to *see*: "it's not super straightforward to show
you what's actually going on behind the scenes... it is creating the checkpoints, it is
creating the persistent storage with SQLite." A dashboard closes that gap. It also
encodes the speaker's operational guidance directly — SQLite is the recommended
production backend, JSONL is supported with a different multi-file layout, and memory is
erased on exit so it is experiment-only.

## HOW TO BUILD
1. `load_backend()` returns a tidy DataFrame of `task_id, conversation_id, status,
   checkpoint, seq, done, backend`.
2. Sidebar: backend selector, crash-rate slider, and a task filter.
3. A Plotly timeline (Gantt-style scatter) of checkpoints per task with a marker for the
   interruption point.
4. A `plotly.express` bar of tasks by status and a pie of checkpoint completion.
5. A small `st.metric` row: resume rate, duplicates, mean checkpoints per task.

```python
fig = px.timeline(df, x_start="start", x_end="end", y="task_id", color="status")
st.plotly_chart(fig, use_container_width=True)
```

## WHEN TO USE IN PRODUCTION
Stand up a read-only copy next to any always-on agent fleet so on-call can confirm
recovery after a restart, spot tasks stuck mid-tool-call, and compare backends before a
migration. It is also a useful demo surface when explaining durability to stakeholders.
Do NOT use it as the control plane — it must not submit tasks or mutate storage; keep it
read-only so it can never be the thing that corrupts state. It is not a real-time
profiler either; poll on an interval.

## HOW IT HELPS STUDENTS
Students practise Streamlit layout, Plotly Express charts, and DataFrame reshaping from
messy storage rows into a timeline. More importantly they learn to make reliability
*legible* — the skill of turning plumbing into a decision surface, which is what turns a
prototype agent into something a team can run on call.

## STARTER CODE
See `starter/main.py` for a runnable Streamlit app with seeded demo data, three Plotly
figures, metric cards, and TODO markers for wiring the real SQLite/JSONL readers.
