Debugging an AI that performs dozens steps (reading files, calling APIs and writing code), is different than debugging regular functions. It is not possible to view a single stack-trace. Developers are instead left looking at hundreds of JSON lines, trying to decipher what the model actually thought and did at every step. OpenAI has taken a direct stab at this issue with the release EuphonyA new browser-based, open-source visualization tool that transforms structured chat logs and Codex sessions into interactive, readable conversation views.
Euphony OpenAI has two proprietary data formats that are used exclusively by OpenAI. Harmony Conversations Codex session JSONL files.
What is Harmony format?
Harmony is the foundation of Euphony. OpenAI’s open-weight model series, gpt-ossThis format was a special prompt that was used to train the trainees. harmony response format. Unlike standard chat formats, Harmony supports multi-channel outputs — meaning the model can produce reasoning output, tool calling preambles, and regular responses all within a single structured conversation. The model also includes role-based hierarchy of instructions (The system is a way to get in touch with others., If you are interested in learning more about the company, please contact them directly., User, The namespace for all named tools is ).
A single Harmony Conversation is stored in a .json The following are some examples of how to use .jsonl A file may contain much more structured metadata compared to a standard OpenAI API response. The richness of the metadata is great for agent workflows, training and evaluation but can also make raw inspection difficult. You are trying to read deeply nesting JSON objects that contain token IDs and decoded tokens as well as rendered display strings. Euphony has been built specifically to fix this problem.
Euphony – What Does It Do?
Euphony, at its heart, is an art form. Standalone web application and web component library It ingests Harmony JSON/JSONL and Codex session JSONL, then renders the data as a structured timeline of conversation in the web browser.
This tool is designed to support There are three methods of data loading The following features are available out-of-the box: copying JSON and JSONL from the clipboard or loading a locally stored file. .json The following are some examples of how to use .jsonl file from disk, or pointing it at any public HTTP(S) URL serving JSON or JSONL — including Hugging Face dataset URLs. Euphony auto-detects and renders according to the format in four different cases. If the JSONL file is a list, then it renders every conversation; if detected a Codex Session File, it will render a Codex Session timeline.
It goes beyond the basic rendering. Euphony surfaces Metadata at the message and conversation levels directly in the UI through a dedicated metadata inspection panel — useful when evaluating annotated datasets where each conversation carries extra fields like scores, sources, or labels. The software also includes support for JMESPath filtering. This allows you to filter large datasets through the JSON format. It is possible to use a Focus Mode Filters visible messages according to recipient, role or type of content. Grid View For skimming data quickly and easily, you can use an Editor mode JSONL can be directly modified in the browser. Within message content is support for Markdown rendering, including mathematical formulae.
There are two operating modes: frontend-only and backend-assisted
Euphony has a simple architectural split. Euphony is designed with a clean architectural split. Frontend only mode Configured through the VITE_EUPHONY_FRONTEND_ONLY=true The entire application runs on the web browser without any server dependencies. The entire app runs in the browser without any server dependency. backend-assisted mode, a local FastAPI Python server handles remote JSON/JSONL loading, backend translation, and Harmony rendering — which is particularly useful for loading large datasets.
Embed Euphony into Your Web App
Euphony’s ability to ship as a software package is one of its most useful features. reusable custom elements — standard Web Components that can be embedded in any frontend framework: React, Svelte, Vue, or plain HTML. The library is ready to use after building it with pnpm run build:library The main input point is (which) ./lib/euphony.js), you can drop a
This tech stack consists of a TypeScript-based codebase (78.7%), CSS, and a Python layer for the backend. It’s released under GPLv3. Apache 2.0 license.
The Key Takeaways
- OpenAI Euphony is open-sourced, a browser-based visualization tool that converts raw Harmony JSON/JSONL conversations and Codex session JSONL files into structured, browseable conversation timelines — no custom log parsers needed.
- Four auto-detection methods are supported by EuphonyThe program recognizes lists containing Harmony Conversations, Codex Session Files, or conversations nesting under fields at the top level. If it cannot identify any of these, then it renders arbitrary data in raw JSON objects.
- This tool comes with an extensive set of inspection features — including JMESPath filtering, focus mode (filter by role, recipient, or content type), conversation-level and message-level metadata inspection, grid view for dataset skimming, and an in-browser JSONL editor mode.
- There are two ways to run Euphony: a frontend-only mode recommended for static or external hosting, and an optional local backend-assisted mode powered by a FastAPI server that adds remote JSON/JSONL loading, backend translation, and Harmony rendering — with OpenAI explicitly warning against exposing the backend externally due to SSRF risk.
- Euphony has been designed for embeddabilityIt ships as Web Components that can be reused (
Check out the GitHub Repo and Demo. Also, feel free to follow us on Twitter Don’t forget about our 130k+ ML SubReddit Subscribe Now our Newsletter. Wait! Are you using Telegram? now you can join us on telegram as well.
Want to promote your GitHub repo, Hugging Face page, Product release or Webinar?? Connect with us
