euphony README

项目的 README,来自 github.com/openai/euphony。合并为一个 markdown 文件:README.md。

Euphony: Harmony Chat and Codex Session Viewer

Build license

Visualize harmony chat conversations and Codex sessions in your browser 🎵

🎵 Euphony Demo 💬 Harmony Chat Example 🤖 Codex Session Example

Harmony conversations and Codex session logs are useful across training, evaluation, and agent workflows, but they are often difficult to inspect. Euphony addresses that gap by providing portable, customizable, and modular Web Components for visualizing structured chat data and Codex sessions in the browser.

Features

Feature What it does
Harmony conversation viewer Renders Harmony conversations with support for different message types and metadata.
Codex session viewer Detects Codex session JSONL files, converts them into a conversation, and renders them in the same viewer.
Flexible loading Loads data from the clipboard, local .json or .jsonl files, or public HTTP(S) JSON/JSONL URLs.
Markdown and HTML rendering Renders markdown in message content, including formulas and optional HTML blocks.
Translation Translates non-English text into English in normal mode or frontend-only mode with a user-provided OpenAI API key.
Metadata inspection Exposes conversation-level and message-level metadata directly in the UI.
Filtering and focus mode Filters datasets with JMESPath and narrows visible messages by role, recipient, or content type.
Grid and editor modes Supports dataset skimming in grid view and direct JSONL editing in editor mode.
Harmony token rendering Shows Harmony renderer output, token IDs, decoded tokens, and rendered display strings.
Embeddable web components Ships reusable custom elements for integrating the viewer into other web apps in any framework (e.g., React, Svelte, Vue).

Get Started

There are two ways you can use Euphony.

  1. Use the standalone app to view Harmony JSON/JSONL data and Codex session JSONL files.
  2. Use the Euphony JavaScript library to render Harmony data in your own web app.

Use Euphony to View My Data

  1. Load data from one of the supported sources:
    1. Paste JSON or JSONL from the clipboard
    2. Choose a local .json or .jsonl file
    3. Provide a public HTTP(S) URL that serves JSON or JSONL (e.g., Hugging Face)
  2. Euphony automatically detects and renders the input:
    1. If the JSONL is a list of conversations → Euphony renders all conversations
    2. If the JSONL is a Codex session file → Euphony renders a structured Codex session timeline
    3. If the conversation is stored at some top-level field → Euphony renders all conversations and treat other top-level fields as each conversation’s metadata
    4. Else → Euphony renders the data as raw JSON objects

Integrate Euphony into My Web App

Web Component API

To use Euphony web components, first build the Euphony library:

pnpm install
pnpm run build:library

The main library entrypoint is built at: ./lib/euphony.js.

Then, you can import the JS file. To show a viewer of Harmony data, you can add the web component to your HTML file (or React, Svelte, Vue components):

<euphony-conversation conversation-string="HARMONY_CONVERSATION_JSON_STRING">
</euphony-conversation>

Alternatively, you can pass parsed JSON object directly into the euphony-conversation HTMLElement from Javascript.

const harmonyConversation: Conversation;
const myEuphonyConvoElement = document.querySelector('euphony-conversation');
myEuphonyConvoElement.conversationJSON = harmonyConversation;

Euphony web components are customizable. For example, to style these components, you can override CSS variables in your stylesheets.

--euphony-padding-v: 10px;
--euphony-padding-h: 15px;
--euphony-font-color: hsl(0, 0%, 12.94%);
--euphony-font-color-secondary: hsl(0, 0%, 61.96%);
--euphony-user-color: hsl(122, 43.43%, 38.82%);
--euphony-assistant-color: hsl(282, 67.88%, 37.84%);
--euphony-conv-background-color: hsl(0, 0%, 96.08%);

Frontend-only and Backend-assisted Modes

Euphony can run in two modes:

Mode What it is for
Frontend-only mode Recommended for static or external hosting. URL loading happens in the browser, and translation uses a user-provided OpenAI API key when needed.
Backend-assisted mode Optional for local development. The FastAPI server supports remote JSON/JSONL loading, backend translation, and Harmony rendering. Useful to load large datasets.

The backend server is optional. It should only be used locally. Frontend-only mode is controlled with the Vite env variable VITE_EUPHONY_FRONTEND_ONLY.

The current backend includes a remote URL fetch path for loading JSON and JSONL data. If you host that backend on an external server, it can introduce SSRF risk because the server may be tricked into fetching attacker-controlled URLs. Therefore, only use the backend-assisted mode for local development.

Development

To develop Euphony locally, install Node.js and a package manager such as pnpm.

Start the backend server:

pnpm install
uvicorn fastapi-main:app --app-dir server --host 127.0.0.1 --port 8020 --reload

Start the frontend development server:

pnpm run dev

To force frontend-only mode with Vite:

VITE_EUPHONY_FRONTEND_ONLY=true pnpm run dev

Visit http://localhost:3000/, you should see Euphony running in your browser!

To build the static frontend:

pnpm run build
python -m http.server -d ./dist

To build a frontend-only static bundle:

VITE_EUPHONY_FRONTEND_ONLY=true pnpm run build
python -m http.server -d ./dist

License

Euphony is released under the Apache 2.0 license. See LICENSE.

The file src/css/prism-coldark-auto.css is derived from an upstream Prism theme (GitHub) and remains subject to the MIT license terms of that upstream work.

euphony (openai/euphony)

正在搜索数据库…

这是什么?Euphony 是一个用于查看 Harmony 聊天数据和 Codex 会话日志的浏览器查看器。你可以将它作为独立应用使用,也可以以 Web 组件的形式嵌入到自己的 Web 应用中。
它是独立应用,还是可以嵌入的库?两者都是。你可以打开独立应用来查看 Harmony JSON/JSONL 和 Codex 会话文件,也可以使用 Euphony JavaScript 库在自己的 Web 应用中渲染 Harmony 数据。
我该怎么让它运行起来?安装 Node.js 和 pnpm,克隆仓库,然后启动前端开发服务器。如果要进行静态部署,则改为构建前端产物包。
我需要运行后端服务器吗?不需要。FastAPI 后端是可选的,仅用于本地开发,主要用于加载大型数据集。对于静态或外部托管,建议使用纯前端模式。
我可以把后端部署到公共服务器上吗?不安全。其远程 URL 抓取功能可能被滥用来发起 SSRF 攻击,因此后端辅助模式只应在你的本地机器上使用。
我可以在 React、Svelte 或 Vue 应用中使用它吗?可以。它以自定义元素的形式发布,可在任何框架中使用,你也可以通过覆盖 CSS 变量来重新设置样式。
加载 URL 或翻译文本时,我的数据会去哪里?在纯前端模式下,URL 加载在你的浏览器中完成。翻译会使用你提供的 OpenAI API 密钥,且仅在需要时才会进行。
为什么要开发 Euphony?Harmony 聊天数据和 Codex 会话日志对训练、评估和智能体工作流很有用,但不易检查。Euphony 提供了可移植的 Web 组件和查看器,填补了这一空白。
加载的数据可以做什么?可以使用 JMESPath 进行筛选,按角色、接收者或内容类型聚焦消息,在网格视图中快速浏览数据集,在编辑模式下直接编辑 JSONL,并检查 Harmony 词元 ID 和渲染输出。
它能翻译非英语消息吗?可以。它可以在普通模式或纯前端模式下,使用你提供的 OpenAI API 密钥,将非英语文本翻译成英文。
作者
openai
大小
2.6 MB
星标
426
更新
提交Apr 22
时长
7个月
提交 · 90 天