docs: add document comparison and booking assistant cookbooks by vishxrad · Pull Request #1250 · thesysdev/openui

vishxrad · 2026-09-28T06:38:06Z

What

Add two cookbooks, each with a runnable example, after conversational analytics:

Document comparison: compare the latest Form 10-K annual reports from NVIDIA, AMD, and Intel through conversation, and get page-cited tables, charts chosen from the shape of the data, callouts for gaps and conflicts, and source cards that open each quoted page of the PDF.
Booking assistant: describe a trip in your own words, get a form prefilled with what the model understood, fill in what's missing, pick from stays with live prices and photos, and review the stay before continuing to the booking site.

This combines the former stack of this PR and #1254.

Changes

Document comparison

Cookbook page: docs/content/docs/cookbooks/document-comparison.mdx, with a demo recording and its own diagram (CookbookComparisonDiagram) showing preparation once and the per-question search. It covers why retrieval and embeddings, setup, five build steps, a browser checklist, and adapting it to your own PDFs.
Example: examples/cookbooks/document-comparison.
- npm run prepare:documents downloads each 10-K PDF from the company's investor relations site, splits every page into overlapping passages that keep their page number, embeds them with OpenAI text-embedding-3-small, and stores them in SQLite. PDFs and the database are not committed.
- The search_documents function tool returns each document's closest passages with page numbers, a link to each page (#page=N), and a found flag.
- A Sources component reuses React UI's source strip: one card per quoted page with the company's icon, page, and quote.
- The prompt asks for one search per criterion with nothing written before the searches finish, page-cited table cells, charts chosen by data shape, warning and info callouts, and Sources.
- The route calls Gateway's Chat Completions API and runs a function-tool loop that streams AG-UI events, like the analytics cookbook.
- Agent Interface: a teal theme that follows the system mode, logoUrl and agentName with the default sidebar header, a Documents page, long starters with icons, and a thread header naming the documents.

Booking assistant

Cookbook page: docs/content/docs/cookbooks/booking-assistant.mdx, with a demo recording and CookbookBookingDiagram.
Example: examples/cookbooks/booking-assistant.
- Stays come from trivago's public MCP server, which needs no API key; there is no data to download.
- search_stays validates its arguments, calls trivago-accommodation-search with the MCP SDK, applies the budget (trivago has no price filter), and returns only the fields the cards need, never trivago's embedded images or formatting instructions.
- The model replies to a new request with a prefilled form with validation rules. Submitting it triggers the search, then stay cards with photos and a summary; Continue to booking opens the stay on trivago.
- A DatePicker that keeps React UI's name and props but reads and writes YYYY-MM-DD, so the model can prefill it.
- The route and tool loop match the other cookbooks (Chat Completions with AG-UI events).

Shared

Both examples are registered in the example catalogs and the docs navigation.
Both cookbooks import @openuidev/react-ui/styles/index.css once.

Test Plan

Examples: frozen pnpm install and verify (spec generation, typecheck, production build) pass on a clean copy without keys or data, as CI runs them.
Document comparison data: prepare:documents extracts 396 pages into 1,564 passages and embeds them.
Document comparison, live Gateway: revenue and growth (NVIDIA $215.9 billion, up 65%, p. 37), R&D over three years, revenue by segment, and revenue plus R&D render without errors. Source cards link to the cited pages, and two quotes from one page merge into one card.
Document comparison: Behind the scenes shows only the search calls; "Compare each CEO's total compensation" reports Not found with callouts; the collapsed sidebar shows only the logo; the Documents page and light and dark themes work.
Booking assistant, live Gateway: a prefilled form for "Book a room in Goa for two this weekend", the children's ages field, and a budget follow-up.
Docs: the document comparison page and diagram render and its demo video plays.
Docs: the booking assistant page, diagram, and demo video.

Checklist

I linked a related issue, if applicable (no related issue).
I updated docs/README when needed.
I considered backwards compatibility; existing docs routes are unchanged.

🤖 Generated with Claude Code

Compare the latest Form 10-K filings from NVIDIA, AMD, and Intel through conversation. npm run prepare:documents downloads each PDF from the company's investor relations site, splits every page into passages, and embeds them with OpenAI into SQLite. The search_documents function tool returns each document's closest passages with page numbers and a found flag, so gaps become callouts instead of invented values. Answers compare criteria in a table with page citations, choose charts from the shape of the data (trends, breakdowns, single values), flag fiscal-year and definition conflicts, and end with one collapsible Sources section. The chat route and tool loop match the first cookbook and the Gateway template. Agent Interface is customized for this example: a teal theme that follows the system light or dark mode, a custom sidebar with a Documents page, long starters with icons, and a thread header naming the documents. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The page follows the conversational analytics cookbook: a general introduction to comparing documents with retrieval and generative UI, why passages and embeddings, setup, five build steps (documents, search tool, components, Agent Interface customization, streaming), a browser checklist that includes a known gap, and notes on adapting it. Generalize the architecture diagram into CookbookArchitecture so each cookbook supplies its own server and data labels; the analytics page passes its existing text and renders unchanged. Add the example README and catalog entries, and let prepare:documents read keys from .env as well as .env.local, since openui create writes .env. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

vercel · 2026-09-28T06:38:12Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
openui-docs	Ready	Preview	Sep 28, 2026 3:39pm UTC

Resolve the cookbook tables in examples/README.md and examples/cookbooks/README.md by keeping both cookbooks with main's new top-level /cookbooks URLs, and move this branch's remaining links to /cookbooks as well. Match the example's OpenUI packages to main's update: react-ui and react-headless 0.16.3, cli 0.4.1. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@openuidev/react-ui/components.css and styles/index.css are the same stylesheet; the package build copies one to the other. Keep the components.css import, as the Gateway template does. The built CSS is unchanged. Also style the document comparison example's mobile header name, which Agent Interface leaves unstyled like the sidebar name. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Replace the shared architecture diagram with one that explains this cookbook on its own: preparing the reports once (pages, text chunks, embeddings, a local database), then answering a question by picking what to compare and finding the best-matching page in each report. Labels use plain words and real page citations. Explain in How it works that separate searches keep one criterion's passages from crowding out another's, and describe the search as embedding the query with OpenAI and ranking passages loaded from SQLite. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

It is the same stylesheet as components.css; the built CSS is unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Keep every table cell to one short value, and give each part of a multi-part criterion, such as a company's segments, its own row. Show breakdowns as one full-width horizontal bar chart with a bar per company and segment, never put charts side by side, and keep callouts short. Remove PieChart from the component library, and update the example answer and the cookbook page to match. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Replace the Sources accordion with a Sources component built on React UI's source strip: one card per quoted page with the company, page, and quote, opening the PDF at that page. search_documents returns each passage's page URL, and quotes from the same page merge into one card. Also tell the model not to write before or between searches, so no OpenUI Lang status message appears in Behind the scenes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Pass agentName and logoUrl to Agent Interface and render the default SidebarHeader, as the Sidebar docs describe. Custom logo and name nodes lacked the classes that hide the name and swap the logo for the open button in the collapsed sidebar. The logo is now an SVG that follows the system color scheme, also used on the welcome screen. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Show the recording under What you'll build, converted from GIF to MP4 like the conversational analytics demo, and drop the note about Gateway embeddings. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Follow the conversational analytics cookbook's move off the Responses API. Chat Completions stores no conversations, so Agent Interface keeps threads in memory and fetchLLM sends each thread's messages with every question. - Chat route: calls gateway.chat.completions.create with the system prompt and the conversation, forwarding only user questions and assistant answers. It opens the first stream before responding so Gateway errors return as HTTP errors, and accepts browser requests only from its own page. - Tool loop: the Chat Completions loop from the conversational analytics cookbook, streaming AG-UI events so each search shows with its result. - Browser: fetchLLM with openAIMessageFormat and agUIAdapter(), no storage prop. - search_documents uses the Chat Completions tool shape. - Removed the frontend-token route and gateway-session.ts. - The cookbook page, README, and .env.example describe Chat Completions. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

A chat assistant that turns a request for a stay into a prefilled, validated form, searches real availability, and books after a summary. It uses Lisbon listings and nightly calendars from Inside Airbnb, which npm run prepare:listings downloads into a local SQLite database. - search_stays checks every night of the stay against the calendar and, when few stays match, counts how many each relaxed preference would add. - book_stay validates its arguments, checks the nights again, and saves a simulated booking in one transaction. - A DatePicker with React UI's props that reads and writes YYYY-MM-DD, so the model can prefill dates and submitted dates keep their calendar day. - The prompt starts each request with a form and uses prefilled values for fields the submitted form state leaves out. - A terracotta theme, logo, and a My bookings page in the sidebar. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

… the example The page follows the other cookbooks: why a prefilled form and why confirm before booking, setup, five build steps (listings, tools, components, the booking flow prompt, Agent Interface), a browser checklist, and adapting it to other inventory. Its diagram shows the four chat screens and the server steps behind them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Replace the Inside Airbnb download with trivago's public MCP server, so the booking assistant finds stays anywhere with live prices and needs only the Thesys key. Move generation to Chat Completions, following the conversational analytics cookbook. - search_stays calls trivago-accommodation-search with the MCP SDK and returns only the fields the cards need, dropping the embedded photo data and trivago's formatting instructions. It applies the budget, which trivago cannot filter by, and reports what it left out. - Stay cards show each hotel's photo across the card. Each card's value is its booking link, so the summary's Continue to booking button opens it without storing tool results between turns. - The form covers destination, dates, adults, children's ages, rooms, budget in the destination's currency, stars, guest rating, and amenities. - Chat route and tool loop match the conversational analytics cookbook: Chat Completions, AG-UI events, fetchLLM, and an origin check. - Removed the listings download, SQLite database, simulated booking, My bookings page, frontend-token route, and gateway-session.ts. - The cookbook page, diagram, README, and catalog entries describe the new flow, including why the tool calls the MCP server itself. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

A Form renders only once its required buttons are defined, and the prompt's examples defined them after every field, so the trip form appeared only when the answer finished. Define each form's Buttons right after the Form in the examples, and tell the model to do the same, so the form appears early and fills in as its fields stream. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…he page - Show the recording under What you'll build, converted from GIF to MP4 like the other cookbook demos. - Name trivago's MCP server in the page description. - Use New York instead of Goa across the page and diagram, following the recording; the example keeps its Goa starter. - Explain why the tool calls the MCP server itself without referring to the Responses API, since the example uses Chat Completions. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Refine language for clarity in document comparison process.

The document comparison cookbook has its own diagram, so the generic CookbookArchitecture component served only the analytics page. Restore cookbook-analytics-architecture.tsx and the analytics page's diagram, which also resolves the conflict with the diagram edit on main. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Bring in the restored analytics architecture diagram and the latest document comparison changes, so this branch no longer renames the diagram that main edits. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore: import React UI CSS once, through components.css `@openuidev/react-ui/styles/index.css` (and `./index.css`) ship the same stylesheet as `./components.css`; cp-css.js writes one to the other. Many examples and the self-hosted template imported both. - Drop the redundant `styles/index.css` import from the agent-framework, harness, miscellaneous, and FastAPI examples and the self-hosted template and overlays, and the extra page-level import in the Vercel Eve example. - Switch examples that imported only `styles/index.css` to `components.css`, matching the Gateway template. - Recommend `components.css` in the react-ui README and API reference, and note that the other two paths contain the same stylesheet. Cookbook examples are covered by #1250. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: explain why the default and layered stylesheets don't mix Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore: prefer styles/index.css over components.css styles/index.css pairs with layered/styles/index.css and the per-component styles/<Component>.css files, and the react-ui README and API reference already called it the default. Switch the examples, both templates, the docs overview snippet, and the browser bundle's CSS concat to it, and list components.css and index.css as aliases. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Bring in the single React UI CSS import (#1252) and the Chat Completions move for the analytics cookbook (#1256). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Bring in main's latest changes through the document comparison branch. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

vishxrad and others added 2 commits September 28, 2026 12:00

vercel Bot deployed to Preview September 28, 2026 06:41 View deployment

vercel Bot deployed to Preview September 28, 2026 08:29 View deployment

vercel Bot deployed to Preview September 28, 2026 08:46 View deployment

vishxrad mentioned this pull request Sep 28, 2026

chore: import React UI CSS once, through styles/index.css #1252

Merged

9 tasks

vishxrad marked this pull request as ready for review September 28, 2026 09:06

vishxrad and others added 2 commits September 28, 2026 14:43

Import React UI styles from styles/index.css in both cookbooks

681d59a

It is the same stylesheet as components.css; the built CSS is unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

vercel Bot deployed to Preview September 28, 2026 09:16 View deployment

vercel Bot deployed to Preview September 28, 2026 09:32 View deployment

vercel Bot deployed to Preview September 28, 2026 09:52 View deployment

vercel Bot deployed to Preview September 28, 2026 10:02 View deployment

docs(cookbooks): add the document comparison demo video

1856e88

Show the recording under What you'll build, converted from GIF to MP4 like the conversational analytics demo, and drop the note about Gateway embeddings. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

vercel Bot deployed to Preview September 28, 2026 10:22 View deployment

vishxrad mentioned this pull request Sep 28, 2026

docs: add a booking assistant cookbook #1253

Merged

11 tasks

vishxrad force-pushed the visharad/cookbook-document-comparison branch from d3c543b to 1856e88 Compare September 28, 2026 11:20

vishxrad mentioned this pull request Sep 28, 2026

docs: add a booking assistant cookbook #1254

Merged

11 tasks

vishxrad added this pull request to stack #1255 September 28, 2026 11:22

vishxrad and others added 4 commits September 28, 2026 18:34

vercel Bot deployed to Preview September 28, 2026 13:08 View deployment

vishxrad and others added 3 commits September 28, 2026 18:45

Update description for document comparison

f9212ce

vercel Bot deployed to Preview September 28, 2026 14:46 View deployment

Clarify OpenUI Lang generation in comparison steps

f16cdbf

Refine language for clarity in document comparison process.

vercel Bot deployed to Preview September 28, 2026 14:52 View deployment

vishxrad and others added 2 commits September 28, 2026 20:55

Merge the document comparison branch into the booking assistant branch

90ceb48

Bring in the restored analytics architecture diagram and the latest document comparison changes, so this branch no longer renames the diagram that main edits. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

vercel Bot deployed to Preview September 28, 2026 15:28 View deployment

vishxrad and others added 2 commits September 28, 2026 21:03

Merge main into the document comparison cookbook

3da0d18

Bring in the single React UI CSS import (#1252) and the Chat Completions move for the analytics cookbook (#1256). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Merge the document comparison branch into the booking assistant branch

bf93801

Bring in main's latest changes through the document comparison branch. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

vishxrad changed the title ~~docs: add a document comparison cookbook~~ docs: add document comparison and booking assistant cookbooks Sep 28, 2026

vercel Bot deployed to Preview September 28, 2026 15:37 View deployment

abhithesys approved these changes Sep 28, 2026

View reviewed changes

vishxrad merged commit 31d3ec7 into main Sep 28, 2026
7 of 8 checks passed

vishxrad deleted the visharad/cookbook-document-comparison branch September 28, 2026 16:13

Navigation Menu

docs: add document comparison and booking assistant cookbooks - #1250

docs: add document comparison and booking assistant cookbooks#1250
vishxrad merged 22 commits into
mainfrom
visharad/cookbook-document-comparison

vishxrad commented Sep 28, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Sep 28, 2026 •

edited

Loading

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

vishxrad commented Sep 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Changes

Document comparison

Booking assistant

Shared

Test Plan

Checklist

Uh oh!

vercel Bot commented Sep 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vishxrad commented Sep 28, 2026 •

edited

Loading

vercel Bot commented Sep 28, 2026 •

edited

Loading