From cca3dc551fd10331039b30e52b5cb1f9028651a8 Mon Sep 17 00:00:00 2001
From: Benjamin Hackl <mail@behackl.dev>
Date: Thu, 15 Jan 2026 23:29:55 +0100
Subject: [PATCH] Add demo-05: codebase navigation task using Vitabel

---
 demo-05/README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 demo-05/README.md

diff --git a/demo-05/README.md b/demo-05/README.md
new file mode 100644
index 0000000..8a0398f
--- /dev/null
+++ b/demo-05/README.md
@@ -0,0 +1,84 @@
+# Demo 05: Codebase Navigation - Understanding Vitabel's Interactive Plotting
+
+## Purpose
+
+This demo shows how to use an AI agent to navigate and understand a complex codebase. Instead of reading hundreds of files manually, you'll use the agent to quickly locate relevant code, understand the architecture, and dissect how a specific feature works.
+
+## Target Codebase: Vitabel
+
+**Vitabel** is a Python toolbox for plotting, processing, and interactively labeling vital medical data (e.g., from defibrillators, anesthesia records, or critical care monitors). It's developed by the Uni Graz Math department.
+
+**Repository:** https://github.com/UniGrazMath/vitabel
+
+**Key Stats:**
+- ~46 MB codebase
+- Python-based
+- Designed for Jupyter notebooks
+- Main feature: Interactive data visualization and annotation
+
+## Task: Understand the Interactive Plotting System
+
+Your goal is to understand **how the interactive plotting system in Vitabel works**. Specifically:
+
+1. **Find the entry point**: Locate the `plot_interactive()` method mentioned in the README
+2. **Trace the flow**: Follow the code path from the method call to the actual rendering
+3. **Identify key components**: What libraries are used? What classes are involved?
+4. **Understand the architecture**: How are plots structured? How does interactivity work?
+5. **Document the findings**: Create a brief summary of how the system works
+
+## Starting Point
+
+From the Vitabel README, we know the main entry point is:
+
+```python
+case.plot_interactive(
+    channels=[['cpr_acceleration'], ['capnography'], ['ecg_pads'], []],
+    labels = [['ROSC'], ['etco2_from_capnography', 'ROSC'], ['ROSC'], ['ROSC', 'rosc_probability']],
+    channel_overviews=[['cpr_acceleration']],
+    time_unit='s',
+    subplots_kwargs={'figsize': (22, 9)}
+)
+```
+
+**Your task:** Find and understand how this `plot_interactive()` method is implemented.
+
+## Process
+
+Use the agent iteratively to:
+
+1. **Explore the codebase structure**: What directories exist? What are the main modules?
+2. **Locate the plotting code**: Search for `plot_interactive` and related plotting functions
+3. **Understand the dependencies**: What libraries (matplotlib, plotly, etc.) are used?
+4. **Follow the call chain**: From the public API to the internal implementation
+5. **Identify key classes/functions**: What are the main building blocks?
+6. **Ask targeted questions**: Use the agent to explain complex parts or unfamiliar patterns
+
+## Tips for Agent-Assisted Navigation
+
+- **Start broad**: Ask the agent to describe the overall structure first
+- **Be specific**: Once you know where to look, ask about specific functions/classes
+- **Ask for context**: Request explanations of unfamiliar patterns or libraries
+- **Iterate**: Use answers to refine your questions and dig deeper
+- **Focus**: Don't try to understand everything - focus on the plotting system
+
+## Expected Outcome
+
+By the end of this demo, you should have:
+- A mental map of Vitabel's plotting architecture
+- Understanding of how `plot_interactive()` works under the hood
+- Experience using an AI agent to navigate and understand a complex codebase
+
+## Files to Explore (Suggestions)
+
+Start with these areas:
+- `src/vitabel/` - Main source code directory
+- Look for `vitals.py` or similar module containing the `Vitals` class
+- Search for `plot_interactive` implementation
+- Check for visualization-related modules or subdirectories
+
+## Bonus Challenges
+
+If you finish early, try:
+1. Understand how the label system works (how events are annotated on plots)
+2. Explore how different data sources are loaded (defibrillator vs VitalDB)
+3. Understand the circulation prediction algorithm