The Open Standard for Generative UI
Document comparison
A runnable companion to the document comparison cookbook. Ask what to compare, watch the assistant search each document, and get a page-cited table, charts, and source cards that open each quoted page as the answer streams.
The example compares the latest annual reports (Form 10-K) from NVIDIA, AMD, and Intel. It runs on Next.js, Agent Interface, OpenUI Gateway's Chat Completions API, OpenAI embeddings, and Node's built-in SQLite module.
Run
Requirements: Node.js 22.13+ and npm. This is a standalone example outside the package workspace.
npm ci
Configure two keys privately in .env.local:
THESYS_API_KEYfrom the Thesys Console, for generation.npm run generate:apiKeymints one into.env.local.OPENAI_API_KEYfrom the OpenAI Platform, for embeddings.
Optional OPENUI_MODEL selects a supported provider/model identifier; the default is openai/gpt-5.5.
npm run prepare:documents
npm run dev
The first prepare:documents run downloads about 83 MB of PDFs into data/pdfs/, which later runs reuse, and embeds 1,564 passages for about a cent. Open http://localhost:3000. To use another port, run npm run dev -- --port 3001.
Try:
- “Compare revenue and growth.”
- “How has R&D spending changed over three years?”
- “Break down revenue by segment.”
- “Compare each CEO's total compensation.” The reports refer to the proxy statement, so the answer should report the gap.
How it works
- Agent Interface sends the thread's messages to
/api/chat, which calls OpenUI Gateway's Chat Completions API. - The model calls
search_documentsonce per criterion, with a short description of the information to find. - The server embeds the description, ranks each document's passages by similarity, and returns the closest ones with page numbers, links to those pages, and a
foundflag. runTools()returns the passages to the model, and the route streams the tool calls and generated OpenUI Lang to the browser.- Agent Interface displays tool activity and progressively renders the comparison: a page-cited table, charts, callouts for gaps and conflicts, and a card for each quoted page.
Files
| File | Purpose |
|---|---|
scripts/prepare-documents.ts |
Download the PDFs, extract pages, split passages, embed, and store |
src/lib/documents.ts |
Sample document sources, database schema, and document list |
src/lib/embeddings.ts |
OpenAI embeddings and similarity |
src/lib/tools/search-documents.ts |
Function schema, argument validation, and passage search |
src/library.ts |
The chat library, shared by the prompt and renderer |
src/lib/prompt.ts |
Comparison rules and example answers for Gateway |
src/lib/gateway-history.ts |
Loads a thread's stored turns from Gateway as chat messages |
src/app/api/chat/route.ts |
runTools() generation, streaming, and turn storage |
src/app/api/documents/route.ts |
Document list for the Documents page |
src/app/api/frontend-token/route.ts |
Frontend token for Gateway thread storage |
src/lib/theme.ts |
Light and dark theme overrides |
src/components/comparison-chat.tsx |
Agent Interface, chat transport, thread storage, sidebar, and Documents route |
src/components/document-library.tsx |
The Documents page |
npm run generate creates the ignored component specification before dev/build/verify. The server passes that specification to generateSystemPrompt({ cloud: true, library: spec, promptOptions }), and Agent Interface renders responses with the same component library.
Documents
prepare:documents downloads each report in sources (src/lib/documents.ts) from the company's investor relations site and checks that the download is complete. It extracts text page by page with unpdf, splits each page into 1,200-character passages that overlap by 200 characters, embeds them with text-embedding-3-small, and writes data/documents.sqlite. Re-running it rebuilds the database.
To compare your own PDFs, add them to documents/ and run npm run prepare:documents again. The importer reads a PDF's text layer, so run OCR on scanned documents first. For large collections, store the embeddings in a vector database and keep the tool's contract.
The downloaded reports and the database are ignored by Git and are not redistributed with this repository.
Conversations
The OpenAI SDK sends requests to https://api.thesys.dev/v1/embed/chat/completions using THESYS_API_KEY. Chat Completions does not store conversations, so the chat route stores each turn in the thread's Gateway conversation and loads the earlier turns from there for every question. Follow-up suggestions are sent the same way, so they build on the earlier answers.
Agent Interface stores the thread list with Gateway's Conversations API through useOpenuiCloudStorage(). The browser calls Gateway directly with a short-lived frontend token from /api/frontend-token, which mints it with THESYS_API_KEY for one local user (DEMO_USER_ID, default demo-user) and app (APP_ID, default document-comparison-cookbook), so the key stays on the server and the browser reaches only those threads. Chat Completions doesn't write turns to a conversation, so the chat route appends each turn, including the tool calls and their results, with storeChatCompletionHistory() from @openuidev/server. A stopped or failed answer still keeps the user's message. Threads stay listed after a reload, and a thread you open again loads its messages. To keep threads in your own database instead, use restStorage.
The chat route uses only the new question from the browser. loadChatCompletionHistory() in src/lib/gateway-history.ts loads the earlier turns from the thread's Gateway conversation, including their searches and passages, so the model sees where each earlier quote came from, and every passage it sees came from this server. The response ends once the turn is stored, so a follow-up finds it. The route runs the tool with the OpenAI SDK's runTools() and returns the runner's toReadableStream(), one JSON chunk per line, which openAIReadableStreamAdapter() reads. Chat Completions has no chunk for a tool result, so in a live answer Behind the scenes shows each call's arguments but not its result.
The app binds to loopback, and every browser shares one local user's threads. For deployment, add authentication, mint each frontend token for the signed-in user, check that each threadId belongs to that user before storing a turn in it, and add request-size and rate limits to both routes.
Verify
npm run verify
verify generates the component specification and runs a production build with type checking. It needs neither credentials nor a download.
In the browser, open a card in an answer's Sources to check a value on its page, expand Behind the scenes to inspect search_documents, open Documents in the sidebar, and switch the operating system between light and dark mode.