Bag Doctor

Bundled demo: 663 messages become one deterministic incident and a completed, evidence-cited GPT-5.6 investigation.
GPT-5.6 Terra turns six bounded timing incidents into a hypothesis backed by validated evidence IDs.
All cited evidence IDs are visible, with explicit limits stating that timing alone cannot prove a physical root cause.
A 37.5 GiB bag is analyzed in place with real progress, ETA, cancellation, and GPT-5.6 gated until analysis completes.
Clean first-run dashboard with Demo, browser Upload, Local bag analysis, and deterministic gating before GPT-5.6.

Inspiration

Robotics field data is expensive to capture and painful to investigate. In my work, I deal with lidar systems, rovers, and sensor pipelines. When a run fails, the evidence is often buried inside a multi-gigabyte ROS 2 bag that someone must inspect manually.

I created Bag Doctor because much of that investigation is measurable, repeatable work that software should perform. I also believe that an AI investigating robot failures should be required to show the evidence behind its conclusions.

What it does

Bag Doctor is an evidence-driven failure investigator for ROS 2 recordings.

A deterministic analysis layer natively ingests MCAP and rosbag2 SQLite recordings without requiring a ROS installation or deserializing message payloads. It measures:

topic activity and inventory;
observed publication rates;
periodic, event-driven, unknown, and user-configured timing classifications;
inter-message gaps;
silence windows;
silence at the beginning and end of a recording.

The analysis uses a disk-backed SQLite workspace so large recordings can be processed with bounded Python memory.

Findings are ranked as incidents and assigned stable evidence IDs.

GPT-5.6 then investigates only a bounded, server-created evidence context. It returns ranked, confidence-scored hypotheses with evidence citations. Every cited evidence ID is validated server-side to confirm that it exists and belongs to the completed analysis job.

The primary investigator runs through the ChatGPT-authenticated Codex CLI using GPT-5.6 Terra, without requiring an OPENAI_API_KEY. An optional OpenAI Responses API provider uses the same bounded-evidence approach with controlled evidence tools.

Bag Doctor deliberately does not claim to prove physical root causes, repair bag files, create corrected recordings, or send raw telemetry to the model.

How I built it

I built the project with Codex and GPT-5.6 through a series of narrow, tested milestones.

The backend uses Python, FastAPI, rosbags, MCAP, Pydantic, and SQLite. Native ingestion strategies support standalone MCAP files, standalone rosbag2 SQLite files, complete bag directories, and packaged split SQLite bags.

FastAPI manages analysis jobs, cooperative cancellation, truthful progress, estimated completion time, Server-Sent Events, evidence retrieval, and investigation requests. Unknown totals never produce fabricated completion percentages.

The investigator protocol uses structured output, bounded evidence access, schema validation, evidence-ownership validation, and controlled failures.

The interface is a React and TypeScript diagnostic dashboard with:

responsive desktop and mobile layouts;
Light, Dark, and System themes;
collapsible navigation;
a dedicated GPT-5.6 Investigator panel;
evidence citation navigation;
printable investigation reports.

I used Codex to help implement and review individual milestones, add tests, inspect diffs, validate behavior, and maintain narrowly scoped commits.

GPT-5.6 Terra is also the product's runtime intelligence through Codex CLI, making GPT-5.6 central to both my development process and the user-facing investigation workflow.

Challenges I faced

Making ingestion honest

Standalone bag files initially failed against real recordings because they were treated like complete bag directories. I solved this by implementing native readers that derive the necessary information directly from each input format.

Keeping large analysis bounded and truthful

Large ROS 2 recordings cannot be loaded into memory all at once. I designed Bag Doctor to use a temporary SQLite workspace, bounded incident selection, bounded evidence storage, real processed-message counts, and cooperative cancellation.

I validated Bag Doctor on a real approximately 37.5 GiB field recording containing 744,684 messages. The Local workflow produced six leading-boundary timing findings and six bounded evidence records, which enabled a completed GPT-5.6 Terra investigation.

Detecting recording-boundary failures

Internal gaps between messages were not enough. A topic may begin publishing late or stop publishing before the recording ends.

Bag Doctor now evaluates leading and trailing silence after calculating ordinary topic timing statistics. Boundary gaps are kept separate from median-gap calculations so the detector does not distort the topic's normal timing behavior.

Constraining the AI

Instead of asking GPT-5.6 to inspect unrestricted raw telemetry, I designed the server to create a bounded deterministic evidence set. The model must cite evidence IDs, and the service verifies that those IDs belong to the current job before accepting the result.

Timing measurements alone do not establish a physical root cause.

Accomplishments that I am proud of

Native MCAP and rosbag2 SQLite analysis without requiring a ROS installation.
Bounded-memory processing for large recordings.
Stable, job-owned evidence IDs.
Server-side validation of evidence citations.
Cooperative cancellation and truthful progress over Server-Sent Events.
A primary GPT-5.6 Terra workflow through the authenticated Codex CLI without requiring an API key.
Successful analysis of a real approximately 37.5 GiB ROS 2 field recording.
A reproducible production frontend build.
58 Python tests and 28 frontend tests passing.
A complete judge path from the bundled Demo, to deterministic evidence, to an evidence-cited GPT-5.6 investigation.

What I learned

Reliable AI investigation begins before the model is called.

I learned that the quality of the final hypotheses depends on deterministic measurements, bounded context, stable identifiers, explicit uncertainty, and validation after generation.

The most important design decision was not asking GPT-5.6 to inspect an unrestricted recording. Instead, Bag Doctor gives the model a small, controlled evidence interface.

I also learned that product honesty matters. Progress should reflect real work, unsupported formats should not be advertised, and zero evidence should never be presented as proof that a recording is healthy.