ROS-Trace AI

Inspiration

Robotics failures rarely arrive as one clean exception. A navigation problem can produce interleaved transform warnings, sensor timeouts, planner errors, and repeated recovery messages across several nodes. The first useful clue may be hundreds of lines away from the final failure.

We wanted a tool that gives a robotics developer a credible starting point in seconds, without requiring a running robot, a complete ROS workstation, or permission to upload operational logs. That led to one central design decision: useful analysis had to be deterministic and offline first. AI should improve the explanation when a team opts in—not be a prerequisite for understanding the incident.

What it does

ROS-Trace AI turns ROS-style text logs into a compact diagnostic report:

• a severity and health summary;
• an ordered incident timeline;
• grouping of repeated failures;
• likely root-cause hypotheses;
• the exact log evidence behind each hypothesis; and
• actionable checks or commands for the developer to try next.

The web interface can load a bundled navigation-failure sample or accept pasted logs, so judges can see a meaningful result immediately. The deterministic path runs locally without ROS, an API key, or a network call. If an OpenAI key is explicitly configured, GPT-5.6 can enrich the structured findings with a clearer synthesis and prioritization.

ROS-Trace AI is intentionally a text-log analyzer rather than a binary ROS bag reader. Teams can export relevant console logs from ROS1 or ROS2 and analyze those locally.

How we built it

The backend is Python 3.11 with FastAPI and Pydantic. The frontend is vanilla HTML, CSS, and JavaScript served by the same application, so there is no separate frontend toolchain or build step.

The analysis pipeline has four boundaries:

1. A tolerant parser normalizes common ROS1/ROS2-style records while handling malformed lines gracefully.
2. Deterministic logic calculates severity metrics, groups repeated events, and applies known diagnostic rules.
3. FastAPI exposes the result to the static browser interface.
4. An optional OpenAI adapter sends structured findings—not an unbounded autonomous workflow—to GPT-5.6 for enrichment.

We used Codex as an engineering partner to shape and implement the project. The highest-impact Codex decisions were to keep offline analysis as the core product, isolate model access behind an injectable boundary, define expected failure behavior before implementation, and optimize the demo around a bundled sample and a no-build UI. Those choices made the tool easier to test, explain, and evaluate than a model-only log chatbot.

GPT-5.6 has a separate runtime role: when enabled, it synthesizes the deterministic timeline, helps prioritize hypotheses, and turns structured evidence into a more concise incident narrative. The deterministic result remains available when no key is configured.

Challenges we ran into

Converting noisy text into evidence

ROS output varies by version, logger, launch setup, and copy/paste source. A parser that rejects one malformed line can make the tool brittle, while a parser that accepts everything can create false structure. We designed tolerant parsing and preserved evidence so that the report remains useful without pretending every line is perfectly normalized.

Being useful without overclaiming

Logs support hypotheses, not certainty. We separated evidence, likely causes, and recommended checks instead of presenting generated prose as a proven diagnosis. That distinction matters even more when software recommendations can affect a physical robot.

Adding AI without making it a dependency

The obvious implementation was to send raw logs directly to a model. We chose the harder but more robust architecture: deterministic code first, optional GPT-5.6 second. This supports offline and privacy-sensitive environments, creates stable test boundaries, and gives users a result even when credentials or network access are unavailable.

Keeping the judging path short

A robotics tool can easily accumulate environment requirements. Serving a vanilla interface from FastAPI and analyzing plain text lets evaluators run the project without installing ROS or connecting hardware.

Accomplishments that we're proud of

• Built an offline-first developer tool instead of an AI-dependent demo.
• Made each diagnosis evidence-backed and paired it with a next action.
• Created a bundled sample workflow that reaches useful output quickly.
• Kept the application runnable without ROS, robot hardware, or an API key.
• Isolated optional GPT-5.6 enrichment from deterministic parsing and analysis.
• Used a single FastAPI process and no-build frontend to minimize setup friction.
• Designed tests around parser behavior, AI fallback, and API behavior.

What we learned

The most valuable AI architecture is sometimes a narrow layer on top of dependable software. Parsing, grouping, and known diagnostic patterns benefit from deterministic behavior; synthesis and prioritization are where a language model can add the most value.

We also learned that explainability is a product feature for developer tools. Showing the triggering lines beside a hypothesis makes the output easier to trust and easier to challenge. Finally, designing for a judge with no ROS environment improved the product for real users who need to inspect logs away from the robot.

What's next

• Add more deterministic signatures for transforms, DDS/QoS, lifecycle nodes, navigation, sensors, and resource exhaustion.
• Support rosbag/MCAP extraction through explicit local adapters.
• Add log redaction previews before optional model enrichment.
• Compare incidents across two runs to detect regressions.
• Export reports as Markdown/JSON and link incidents to issue trackers.
• Add configurable organization-specific diagnostic rules.
• Validate packaging and UX across Linux, macOS, and Windows.
• Evaluate model-assisted remediation against a curated ROS failure benchmark.

Built With

• api
• codex
• css3
• fastapi
• gpt-5.6
• html5
• javascript
• openai
• pydantic
• python
• ros2