diff --git a/docs/components/cookbook-booking-diagram.tsx b/docs/components/cookbook-booking-diagram.tsx
new file mode 100644
index 000000000..42a966238
--- /dev/null
+++ b/docs/components/cookbook-booking-diagram.tsx
@@ -0,0 +1,230 @@
+// How the booking assistant cookbook turns a request into a confirmed stay.
+// Every label avoids cookbook-specific terms so the diagram stands on its own.
+
+const mono = "font-mono font-bold uppercase";
+const label = `fill-fd-foreground ${mono} text-[13px] tracking-[0.1em]`;
+const caption = "fill-fd-muted-foreground font-mono text-[12px] uppercase tracking-[0.1em]";
+const note = "fill-fd-muted-foreground font-sans text-[13px]";
+const small = "fill-fd-foreground font-sans text-[12px]";
+const box = "fill-fd-background stroke-fd-foreground";
+const filled = "fill-[#f8e8e0] stroke-fd-foreground dark:fill-[#3a1f15]";
+const accent = "fill-[#b4441f] dark:fill-[#f0875f]";
+
+const screens = [
+ { title: "Request", note: "In their own words" },
+ { title: "Prefilled form", note: "Filled from the request" },
+ { title: "Stays", note: "Live prices, with photos" },
+ { title: "Summary", note: "Then the booking site" },
+];
+const fields = [
+ { name: "Where", value: "New York" },
+ { name: "Dates", value: "Oct 2 – 4" },
+ { name: "Adults", value: "2" },
+ { name: "Budget", value: null },
+];
+const stays = ["Times Square · $292 · 8.7", "Wall Street · $348 · 7.7", "SoHo · $516 · 8.7"];
+const x = (index: number) => 10 + index * 235;
+
+function Arrow({ d, id, both }: { d: string; id: string; both?: boolean }) {
+ return (
+
+ );
+}
+
+export function CookbookBookingDiagram() {
+ const id = "booking-diagram";
+ return (
+
+
+
+ );
+}
diff --git a/docs/components/cookbook-comparison-diagram.tsx b/docs/components/cookbook-comparison-diagram.tsx
new file mode 100644
index 000000000..cbb63f337
--- /dev/null
+++ b/docs/components/cookbook-comparison-diagram.tsx
@@ -0,0 +1,249 @@
+import { ChartColumn, MessagesSquare } from "lucide-react";
+
+// How the document comparison cookbook turns a question into a cited comparison.
+// Page numbers are the real citations for revenue and R&D in the three annual reports.
+// Every label avoids cookbook-specific terms so the diagram stands on its own.
+
+const pipeline = [
+ { title: "Annual reports", detail: "NVIDIA, AMD, Intel" },
+ { title: "Pages", detail: "Text read per page" },
+ { title: "Text chunks", detail: "Each keeps its page" },
+ { title: "Embeddings", detail: "Meaning as numbers" },
+ { title: "Database", detail: "Local SQLite file" },
+];
+
+const companies = ["NVIDIA", "AMD", "Intel"];
+const criteria = [
+ { name: "Revenue", pages: ["Page 37", "Page 50", "Page 27"], y: 222 },
+ { name: "R&D spending", pages: ["Page 41", "Page 56", "Page 16"], y: 288 },
+];
+
+const mono = "font-mono font-bold uppercase";
+const label = `fill-fd-foreground ${mono} text-[13px] tracking-[0.1em]`;
+const caption = "fill-fd-muted-foreground font-mono text-[12px] uppercase tracking-[0.1em]";
+const box = "fill-fd-background stroke-fd-foreground";
+const cell = "fill-[#eef1fb] stroke-fd-foreground dark:fill-[#1c2233]";
+
+function Arrow({ d, id, dashed }: { d: string; id: string; dashed?: boolean }) {
+ return (
+
+ );
+}
+
+export function CookbookComparisonDiagram() {
+ const id = "comparison-diagram";
+ return (
+
+
+
+ );
+}
diff --git a/docs/content/docs/cookbooks/booking-assistant.mdx b/docs/content/docs/cookbooks/booking-assistant.mdx
new file mode 100644
index 000000000..e3bf86bc4
--- /dev/null
+++ b/docs/content/docs/cookbooks/booking-assistant.mdx
@@ -0,0 +1,285 @@
+---
+title: Booking assistant
+description: Build a chat assistant that turns a request for a stay into a prefilled form, searches live hotel prices through trivago's MCP server, and reviews the stay before booking.
+---
+
+import { buttonVariants } from "fumadocs-ui/components/ui/button";
+import { ArrowUpRight, Github } from "lucide-react";
+import { CookbookBookingDiagram } from "@/components/cookbook-booking-diagram";
+
+Booking anything, a room, a table, an appointment, means collecting a handful of details: where, when, how many, and within what budget. People rarely give all of them at once. They say “a room in New York for two this weekend” and leave the rest for later. Chat assistants usually recover the missing details one question at a time, which is slow and easy to derail. Booking forms ask for everything up front, including what the person just said.
+
+An adaptive form combines the two. A language model reads the request, fills in every detail it understood, and shows a form for the rest: a date picker for dates, a number field for guests, choices for stars and amenities, each with validation. The person corrects anything the model got wrong, adds what's missing, and submits once. With generative UI, the model writes that form itself, and the next steps too: the stays that match, and a summary to check before anything is booked.
+
+The search itself can come from a service you don't run. The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is a standard way for applications to offer tools to AI models, and many travel and booking companies now publish MCP servers.
+
+In this cookbook, you'll learn how to:
+
+- Turn a request into a form prefilled with what the model understood, using a suitable control and validation rules for each detail.
+- Read submitted form values on the next turn, including fields the person left as prefilled.
+- Call a public MCP server from a function tool, and pass the model only the data it needs.
+- Show a summary before the person leaves for the booking site.
+- Replace a built-in component with your own version, so the model can prefill dates.
+- Generate answers with [OpenUI Gateway](/docs/gateway), OpenUI's hosted model API that routes requests to model providers and corrects generated UI, through its OpenAI-compatible [Chat Completions API](/docs/gateway/api/chat-completions).
+- Customize [Agent Interface](/docs/agent/getting-started/introduction), OpenUI's ready-made React chat shell with threads, streaming messages, and tool activity.
+
+
+
+## What you'll build
+
+The example finds stays anywhere in the world through [trivago's public MCP server](https://mcp.trivago.com/docs), which compares prices across booking sites and needs no API key. Every search returns real hotels with live prices for the requested dates, guest ratings, amenities, a photo, and a link to book. There is nothing to download or host: the only key you need is for OpenUI Gateway. The assistant never takes payment. Its last step opens the stay on trivago, where the person picks a booking site and books there.
+
+
+
+
+
+Try this conversation:
+
+1. **“A 4-star hotel in Midtown Manhattan with a gym for a work trip, November 10 to 13.”** Get a form with the destination, dates, 4★, and Gym already filled in, and the budget in US dollars.
+2. **Add 5★ and Breakfast included, then Find stays.** See stays with live prices as cards with photos.
+3. **“Make it under $350 a night.”** The assistant searches again and says how many stays were over budget.
+4. **Pick a stay and review the summary.** Click **Continue to booking** to open it on trivago with your dates and guests.
+
+## How it works
+
+A booking assistant splits the work between the model, your application, and the services behind it. The model understands the request, decides what to ask for, and presents each step. Your application decides what the model can search for and what it sees. trivago supplies the stays, and a booking site takes the booking.
+
+
+
+1. **The person describes their trip.** Agent Interface sends the conversation to your server's chat route, which adds a system prompt that describes the booking flow and your components and a `search_stays` function tool, then calls OpenUI Gateway.
+2. **The model replies with a prefilled form.** It works out what it can: “New York” becomes the destination, “this weekend” becomes this Friday to Sunday, and “for two” becomes two adults. It writes a form with those values filled in, empty fields for the rest, and a validation rule on each required field.
+3. **The person submits the form, and the model searches.** Agent Interface checks the rules in the browser, then sends the button label and the form's values as the next message. The model calls `search_stays`. Your server validates the arguments, calls trivago's MCP server, and returns the best matches, which the model shows as cards with photos.
+4. **The person picks a stay and reviews it.** The model shows a summary: dates, guests, price, and the booking site. **Continue to booking** opens the stay on trivago, where the person books with the site of their choice.
+
+### Why a prefilled form
+
+A form shows every detail at once, so the person can see what the assistant understood and fix it in one step, instead of answering questions one by one. Each detail gets the control that suits it, and validation catches a missing date before any search runs. Because the model writes the form for each request, it adapts: a detailed request arrives almost complete, a vague one such as “next month” leaves the dates empty and required rather than guessing, and a field for children's ages appears only when the person mentions children.
+
+### Why call the MCP server from your own tool
+
+trivago's search result is built for chat clients that show it as is. It carries every hotel's photo as image data, about 665 KB for one search, and formatting instructions written for the model. Passing that to your model would be slow and expensive, and would let a third party's instructions steer your answers.
+
+Calling the server from a function tool puts your application in between. It validates the arguments, adds a budget filter that trivago lacks, and returns only the fields the cards need: a few thousand tokens, in the shape your prompt expects. It treats the third-party result as data, so instructions inside it never reach your model.
+
+## Run the example
+
+You need Node.js 22.13 or newer and npm.
+
+```bash
+git clone https://github.com/thesysdev/openui.git
+cd openui/examples/cookbooks/booking-assistant
+npm ci
+```
+
+Configure `THESYS_API_KEY` from the [Thesys Console](https://console.thesys.dev/keys) privately in the example's `.env.local`, then start the app:
+
+```bash
+npm run dev
+```
+
+Open [localhost:3000](http://localhost:3000) and try a starter. A search takes about ten seconds, most of it on trivago's side. The default model is `openai/gpt-5.5`; use `OPENUI_MODEL` to select another supported [Gateway model](/docs/gateway/models).
+
+## Build it step by step
+
+Each step covers one part of the example, in the order a request flows through it: the MCP server, the tool, the components, the prompt, and the chat interface.
+
+### 1. Connect to the MCP server
+
+trivago's server speaks MCP over HTTP at `https://mcp.trivago.com/mcp`. Its `trivago-accommodation-search` tool takes a destination, dates, guests, and optional filters for stars, guest rating, and amenities. The example calls it with the MCP TypeScript SDK and keeps only the structured hotel list:
+
+```ts title="src/lib/trivago.ts"
+export async function searchAccommodations(search: AccommodationSearch, signal?: AbortSignal) {
+ const client = new Client({ name: "openui-booking-assistant", version: "0.1.0" });
+ await client.connect(new StreamableHTTPClientTransport(serverUrl), { signal });
+ try {
+ const result = await client.callTool(
+ { name: "trivago-accommodation-search", arguments: search },
+ undefined,
+ { signal, timeout: 45_000 },
+ );
+ return z
+ .object({ accommodations: z.array(accommodationSchema) })
+ .parse(result.structuredContent).accommodations;
+ } finally {
+ await client.close();
+ }
+}
+```
+
+`structuredContent` holds each hotel's name, prices, star and guest ratings, amenities, distance to the center, photo URL, and booking link. The schema drops everything else, including the embedded photos and the formatting instructions. See [trivago.ts](https://github.com/thesysdev/openui/blob/main/examples/cookbooks/booking-assistant/src/lib/trivago.ts) for the complete client, which also reports errors from the server.
+
+### 2. Expose a search tool
+
+Give Gateway a function tool named `search_stays`. It takes every detail of the trip:
+
+```json
+{
+ "destination": "Midtown Manhattan, New York",
+ "check_in": "2026-11-10",
+ "check_out": "2026-11-13",
+ "adults": 2,
+ "children_ages": [],
+ "rooms": 1,
+ "currency": "USD",
+ "max_price_per_night": 350,
+ "stars": [4, 5],
+ "min_guest_rating": "any",
+ "amenities": ["gym", "breakfastIncluded"],
+ "sort": "recommended"
+}
+```
+
+Currencies, guest ratings, and amenities are enums of the values trivago accepts. Your server validates the arguments again, rejecting a check-in in the past or more rooms than adults, and maps them to trivago's filters. trivago has no price filter, so the tool applies the budget itself:
+
+```ts title="src/lib/tools/search-stays.ts"
+// trivago has no price filter, so apply the budget here and report what it left out.
+const inBudget = found.filter(
+ (stay) =>
+ args.max_price_per_night === null || amount(stay.price_per_night) <= args.max_price_per_night,
+);
+const overBudget = found.filter((stay) => !inBudget.includes(stay));
+```
+
+The result holds the top six stays and, when the budget left some out, how many and the cheapest price among them, so the model can suggest raising the limit. See [search-stays.ts](https://github.com/thesysdev/openui/blob/main/examples/cookbooks/booking-assistant/src/lib/tools/search-stays.ts).
+
+### 3. Choose the components
+
+Use the built-in form controls, a few components for summaries and messages, and one component of your own:
+
+```ts title="src/library.ts"
+export const library = createLibrary({
+ root: "Stack",
+ components: [
+ ...[
+ "Stack",
+ "CardHeader",
+ "TextContent",
+ "Callout",
+ "Table",
+ "Col",
+ "Form",
+ "FormControl",
+ "Input",
+ "Select",
+ "SelectItem",
+ "Chips",
+ "ChipItem",
+ "OptionCards",
+ "OptionCard",
+ "Image",
+ "Buttons",
+ "Button",
+ ].map((name) => openuiLibrary.components[name]),
+ DatePicker,
+ openuiChatLibrary.components.FollowUpBlock,
+ openuiChatLibrary.components.FollowUpItem,
+ ],
+});
+```
+
+`Form` groups the fields and checks their validation rules when the person clicks a primary button. `Chips` covers short choices, such as stars and amenities. `OptionCards` shows the stays as selectable cards, each with an `Image` of the hotel. By default, an option card shows its image as a small thumbnail; one CSS rule in [styles.css](https://github.com/thesysdev/openui/blob/main/examples/cookbooks/booking-assistant/src/app/styles.css) stretches it across the card.
+
+React UI's own `DatePicker` stores JavaScript `Date` objects. The model can only write text, so it cannot prefill one, and a submitted `Date` reaches the model as a UTC timestamp that can fall on the day before. The example replaces it with a component that has the same name and props but reads and writes `YYYY-MM-DD` strings:
+
+```tsx title="src/components/date-picker.tsx"
+export const DatePicker = defineComponent({
+ name: "DatePicker",
+ props: openuiLibrary.components.DatePicker.props,
+ description:
+ "A single date. Prefill it by passing a YYYY-MM-DD string as value; the form submits YYYY-MM-DD.",
+ component: ({ props }) => {
+ const field = useStateField(props.name, props.value);
+ return (
+ field.setValue(toIsoDate(date))}
+ />
+ );
+ },
+});
+```
+
+Reusing the built-in props keeps `DatePicker` valid inside `FormControl`, and the new description tells the model the format. The [complete component](https://github.com/thesysdev/openui/blob/main/examples/cookbooks/booking-assistant/src/components/date-picker.tsx) also registers validation rules and closes the calendar once a date is picked. Generate the server specification from the library with `npm run generate`, which also runs before development and builds.
+
+### 4. Describe the booking flow
+
+The [prompt](https://github.com/thesysdev/openui/blob/main/examples/cookbooks/booking-assistant/src/lib/prompt.ts) gives the model today's date and trivago's filter options, then describes each step. The first rule starts every new request with a form:
+
+> When someone asks for a new stay, reply with one short sentence and a Form named 'trip' before searching, even if they gave every detail. Prefill every field they mentioned with a literal value, never a $variable.
+
+The model prefills a field by passing its value, such as the date `"2026-10-02"` or the adults `"2"`. It picks the destination's currency unless the person names one, so a trip to Tokyo shows its budget in yen. When the person submits, the form sends only the fields they changed, so another rule covers the rest:
+
+> Submitted form state contains only the fields the user changed. For every field missing from it, use the value you prefilled in that form.
+
+Agent Interface sends the whole conversation with every turn, so the model still sees its own form from the previous turn and can fill in the gaps. The remaining rules describe the stay cards, the summary, and the hand-off. Each stay card's value is the stay's booking link, so choosing a card sends the link back with the form, and the summary's **Continue to booking** button opens it with `@OpenUrl`. One example program for each step, the trip form, the stay cards, and the summary, shows the model how the components fit together.
+
+### 5. Connect Agent Interface
+
+Agent Interface provides the sidebar, composer, tool timeline, and stop control. Connect generation to the local chat route with `fetchLLM`. It sends the thread's messages in Chat Completions format and reads the route's stream with `agUIAdapter()`:
+
+```tsx title="src/components/booking-chat.tsx"
+const llm = fetchLLM({
+ url: "/api/chat",
+ streamAdapter: agUIAdapter(),
+ messageFormat: openAIMessageFormat,
+});
+```
+
+Chat Completions does not store conversations, so Agent Interface keeps each thread in the browser and sends its messages with every turn. Threads last until the page reloads. To keep them longer, pass a `storage` adapter backed by your database; see [Connect a backend](/docs/agent/reference/self-hosting).
+
+The chat route runs the same [function-tool loop](https://github.com/thesysdev/openui/blob/main/examples/cookbooks/booking-assistant/src/lib/tool-loop.ts) as the [conversational analytics cookbook](/cookbooks/conversational-analytics#5-stream-the-answer), streaming AG-UI events so Agent Interface shows each search and its result. It forwards only user messages and assistant answers from the browser and drops tool calls and results, so later steps rely on what the stay cards show, including the booking link in each card's value. A submitted form arrives as one message with the button label and the form's values, so the route accepts user messages of up to 4,000 characters.
+
+The example also customizes Agent Interface with a theme from `createTheme`, a logo, starters for four different trips, and a thread header that credits trivago. See [Welcome and starters](/docs/agent/customize/welcome-and-starters).
+
+This example calls Gateway directly from a Next.js route, but the tool and prompt can also run on an agent framework such as LangGraph, the Vercel AI SDK, Mastra, or Google ADK. Agent Interface stays the same and reads the framework's stream with the matching adapter. See our [LangGraph Platform](/docs/agent/agent-runtimes/langgraph-platform), [Vercel AI SDK](/docs/agent/agent-runtimes/vercel-ai-sdk), and [Vercel Eve](/docs/agent/agent-runtimes/vercel-eve) integrations, or the [Mastra](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/mastra) and [Google ADK](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/google-adk) examples.
+
+## Verify it works
+
+In the browser:
+
+1. Ask **“Book a room in New York for two this weekend.”** Confirm the form shows New York, this Friday to Sunday, two adults, and a budget in US dollars.
+2. Clear the adults field and click **Find stays**. The field should report that it is required, and nothing is sent.
+3. Fill it in again and search. Open **Form data** above your message to see the values that were sent, and expand **Behind the scenes** to see the `search_stays` call.
+4. Ask for **“under $100 a night”**, and confirm the reply says how many stays were over budget and the cheapest price among them.
+5. Pick a stay, check the summary, and click **Continue to booking**. trivago should open the stay for your dates and guests.
+6. Switch your operating system between light and dark mode, and confirm the theme follows.
+
+Generated layouts can vary. Hotels, prices, photos, and links should always come from a search result, and prices can change between searches.
+
+## Adapt it to your inventory
+
+To use another MCP server, keep the `search_stays` contract and replace `searchAccommodations`. Kiwi.com, for example, publishes a public MCP server for [flight search](https://www.kiwi.com/en/pages/mcp/). For your own inventory, call your availability API from the tool, or publish it as an MCP server so other assistants can use it too.
+
+The form pattern carries over to anything that needs a few details before an action: a restaurant reservation, a support ticket, a travel request. Describe the details, their controls, and which are required, and keep the action behind a summary. Before relying on a third-party MCP server in production, check its terms and plan for it being slow or unavailable.
+
+This example runs locally without authentication, and its chat route accepts browser requests only from its own page. Before deploying it, add authentication and rate limits. See the [example README](https://github.com/thesysdev/openui/tree/main/examples/cookbooks/booking-assistant) for the implementation notes.
+
+- [Agent Interface quickstart](/docs/agent/getting-started/quickstart)
+- [Gateway Chat Completions API](/docs/gateway/api/chat-completions)
+- [Connect a backend](/docs/agent/reference/self-hosting)
+
+Hotels, prices, and photos: [trivago MCP](https://mcp.trivago.com/docs), fetched live for each search.
diff --git a/docs/content/docs/cookbooks/document-comparison.mdx b/docs/content/docs/cookbooks/document-comparison.mdx
new file mode 100644
index 000000000..0df33355a
--- /dev/null
+++ b/docs/content/docs/cookbooks/document-comparison.mdx
@@ -0,0 +1,350 @@
+---
+title: Document comparison
+description: Build a chat assistant that compares stocks (NVIDIA, AMD, and Intel) annual reports with page-cited tables and charts.
+---
+
+import { buttonVariants } from "fumadocs-ui/components/ui/button";
+import { ArrowUpRight, Github } from "lucide-react";
+import { CookbookComparisonDiagram } from "@/components/cookbook-comparison-diagram";
+
+Comparing documents is everyday work: vendor proposals, contracts, policies, annual reports. The answers are spread across long files, and each document states the same fact in a different place and in different words. Reading three 150-page reports side by side takes hours, and a summary written as paragraphs hides exactly what you wanted to compare.
+
+A language model can read and compare, but long documents do not fit in a single request. Retrieval solves that: search each document for the passages about one criterion, and give the model only those passages, with their page numbers. Generative UI solves the presentation: the model answers with a comparison table, charts, callouts for gaps and conflicts, and the quoted evidence behind every value.
+
+In this cookbook, you'll learn how to:
+
+- Turn PDFs into searchable passages that keep their page numbers, using embeddings for search by meaning.
+- Give the model a search function tool, so it retrieves evidence for each criterion instead of answering from memory.
+- Make the model show its work: page-cited values, charts chosen from the shape of the data, callouts for missing or conflicting information, and source cards that open each quoted page.
+- Customize [Agent Interface](/docs/agent/getting-started/introduction), OpenUI's ready-made React chat shell with threads, streaming messages, and tool activity, with your own theme, sidebar, and pages.
+- Generate answers with [OpenUI Gateway](/docs/gateway), OpenUI's hosted model API that routes requests to model providers and corrects generated UI, through its OpenAI-compatible [Chat Completions API](/docs/gateway/api/chat-completions).
+- Send the conversation with each question, so a follow-up can add a criterion to the comparison.
+
+
+
+## What you'll build
+
+The example compares the latest annual reports (Form 10-K) from **NVIDIA**, **AMD**, and **Intel**: 396 pages, published as PDFs on each company's investor relations site. They make a realistic test. The same facts, such as revenue, R&D spending, and headcount, appear in different sections and wording in each report, and NVIDIA's fiscal year ends in January while the others end in December, a conflict the comparison should point out. The same approach works for vendor proposals, contracts, or any set of PDFs.
+
+
+ To compare your own PDFs, add them to documents/ and run{" "}
+ npm run prepare:documents.
+
+
+ );
+}
diff --git a/examples/cookbooks/document-comparison/src/components/sources.tsx b/examples/cookbooks/document-comparison/src/components/sources.tsx
new file mode 100644
index 000000000..77e84c6e3
--- /dev/null
+++ b/examples/cookbooks/document-comparison/src/components/sources.tsx
@@ -0,0 +1,35 @@
+import { defineComponent } from "@openuidev/react-lang";
+import {
+ CardSourceProvider,
+ CardSourceSchema,
+ Sources as SourceStrip,
+ type CardSource,
+} from "@openuidev/react-ui";
+import { z } from "zod/v4";
+
+// One card per page: the strip keys cards by URL, and two criteria can share a page.
+function onePerPage(items: CardSource[]) {
+ const pages = new Map();
+ items.forEach((item, index) => {
+ const key = item.url || String(index);
+ const seen = pages.get(key);
+ pages.set(
+ key,
+ seen ? { ...seen, title: [seen.title, item.title].filter(Boolean).join(" ") } : item,
+ );
+ });
+ return [...pages.values()];
+}
+
+// Reuses the Sources strip from React UI: one card per quoted page, opening the report there.
+export const Sources = defineComponent({
+ name: "Sources",
+ props: z.object({ items: z.array(CardSourceSchema) }),
+ description:
+ "A strip of source cards. Each item is { title, sourceName, url }: title is the quote, sourceName names the document and page, and url opens the page.",
+ component: ({ props }) => (
+
+
+
+ ),
+});
diff --git a/examples/cookbooks/document-comparison/src/lib/documents.ts b/examples/cookbooks/document-comparison/src/lib/documents.ts
new file mode 100644
index 000000000..8c07939e0
--- /dev/null
+++ b/examples/cookbooks/document-comparison/src/lib/documents.ts
@@ -0,0 +1,52 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+
+// The sample documents: each company's latest annual report (Form 10-K), as the PDF it
+// publishes on its investor relations site. Add your own PDFs to documents/ as well.
+export const sources = [
+ {
+ id: "nvidia",
+ name: "NVIDIA 10-K, fiscal 2026",
+ url: "https://investor.nvidia.com/files/doc_financials/2026/q4/10K-NVDA.pdf",
+ period: "Fiscal year ended January 25, 2026",
+ },
+ {
+ id: "amd",
+ name: "AMD 10-K, fiscal 2025",
+ url: "https://ir.amd.com/financial-information/sec-filings/content/0000002488-26-000018/0000002488-26-000018.pdf",
+ period: "Fiscal year ended December 27, 2025",
+ },
+ {
+ id: "intel",
+ name: "Intel 10-K, fiscal 2025",
+ url: "https://www.intc.com/filings-reports/all-sec-filings/content/0000050863-26-000011/0000050863-26-000011.pdf",
+ period: "Fiscal year ended December 27, 2025",
+ },
+];
+
+export const embeddingModel = "text-embedding-3-small";
+
+export type Document = { id: string; name: string; period: string | null; pages: number };
+
+export function createSchema(db: DatabaseSync) {
+ db.exec(`
+ CREATE TABLE documents (id TEXT PRIMARY KEY, name TEXT NOT NULL, period TEXT,
+ pages INTEGER NOT NULL);
+ CREATE TABLE chunks (id INTEGER PRIMARY KEY, document_id TEXT NOT NULL REFERENCES documents(id),
+ page INTEGER NOT NULL, text TEXT NOT NULL, embedding BLOB NOT NULL);
+ `);
+}
+
+export function openDatabase() {
+ const path = resolve(process.cwd(), "data/documents.sqlite");
+ if (!existsSync(path))
+ throw new Error("Documents not prepared. Run npm run prepare:documents, then retry.");
+ return new DatabaseSync(path, { readOnly: true });
+}
+
+export function listDocuments(db: DatabaseSync): Document[] {
+ return db
+ .prepare("SELECT id, name, period, pages FROM documents ORDER BY rowid")
+ .all() as Document[];
+}
diff --git a/examples/cookbooks/document-comparison/src/lib/embeddings.ts b/examples/cookbooks/document-comparison/src/lib/embeddings.ts
new file mode 100644
index 000000000..4c5fee00b
--- /dev/null
+++ b/examples/cookbooks/document-comparison/src/lib/embeddings.ts
@@ -0,0 +1,21 @@
+import OpenAI from "openai";
+import { embeddingModel } from "./documents";
+
+// OpenUI Gateway does not serve embeddings, so passages and questions are embedded with
+// OpenAI's embeddings API. Its vectors are normalized, so a dot product is cosine similarity.
+export async function embed(texts: string[], signal?: AbortSignal): Promise {
+ const apiKey = process.env.OPENAI_API_KEY;
+ if (!apiKey) throw new Error("Configure OPENAI_API_KEY in .env.local to embed documents.");
+ const client = new OpenAI({ apiKey });
+ const response = await client.embeddings.create(
+ { model: embeddingModel, input: texts },
+ { signal },
+ );
+ return response.data.map((item) => Float32Array.from(item.embedding));
+}
+
+export function similarity(a: Float32Array, b: Float32Array) {
+ let sum = 0;
+ for (let i = 0; i < a.length; i++) sum += a[i] * b[i];
+ return sum;
+}
diff --git a/examples/cookbooks/document-comparison/src/lib/prompt.ts b/examples/cookbooks/document-comparison/src/lib/prompt.ts
new file mode 100644
index 000000000..8cf577485
--- /dev/null
+++ b/examples/cookbooks/document-comparison/src/lib/prompt.ts
@@ -0,0 +1,46 @@
+import { generateSystemPrompt } from "@openuidev/lang-core";
+import spec from "../generated/spec.json";
+import type { Document } from "./documents";
+
+// Syntax guidance only. Real answers use passages returned by search_documents.
+// One example compares a single period; the other shows a trend and a breakdown by segment.
+const singlePeriodExample = `root = Stack([header, table, chart, gap, sources, followUps], "column", "l")
+header = CardHeader("Revenue, latest fiscal year", "Company A report · Company B report")
+table = Table([Col("Criterion", ["Revenue", "Revenue growth"]), Col("Company A", ["$10.0 billion (p. 12)", "Up 5% (p. 12)"]), Col("Company B", ["$8.0 billion (p. 40)", "Not found"])])
+chart = HorizontalBarChart(["Company A", "Company B"], [Series("Revenue (USD billions)", [10.0, 8.0])], "grouped", "USD billions", "Company")
+gap = Callout("info", "Growth not reported", "Company B's report does not state revenue growth, so it is left out of the comparison.")
+sources = Sources([{title: "“Revenue for the fiscal year was $10.0 billion, up 5% from a year ago.”", sourceName: "Company A · Page 12", url: "https://example.com/company-a.pdf#page=12"}, {title: "“Net revenue was $8.0 billion in 2025.”", sourceName: "Company B · Page 40", url: "https://example.com/company-b.pdf#page=40"}])
+followUps = FollowUpBlock([FollowUpItem("Add operating income"), FollowUpItem("Break down revenue by segment")])
+`;
+
+const trendExample = `root = Stack([header, trend, breakdown, parts, note, sources, followUps], "column", "l")
+header = CardHeader("Revenue trend and segments", "Company A report · Company B report")
+trend = LineChart(["2023", "2024", "2025"], [Series("Company A", [8.1, 9.5, 10.0]), Series("Company B", [7.2, 7.9, 8.0])], "linear", "Fiscal year", "Revenue (USD billions)")
+breakdown = HorizontalBarChart(["Company A · Data center", "Company A · Client", "Company B · Client", "Company B · Data center", "Company B · Embedded"], [Series("Revenue (USD billions)", [6.0, 4.0, 4.1, 3.1, 0.8])], "grouped", "Revenue (USD billions)", "Segment")
+parts = Table([Col("Company", ["Company A", "Company A", "Company B", "Company B", "Company B"]), Col("Segment", ["Data center", "Client", "Client", "Data center", "Embedded"]), Col("Revenue", ["$6.0 billion (p. 47)", "$4.0 billion (p. 47)", "$4.1 billion (p. 55)", "$3.1 billion (p. 55)", "$0.8 billion (p. 55)"])])
+note = Callout("warning", "Segments differ", "Each company defines its own segments, so compare totals and shares rather than segment names.")
+sources = Sources([{title: "“Revenue was $10.0 billion, $9.5 billion, and $8.1 billion in fiscal 2025, 2024, and 2023.”", sourceName: "Company A · Page 45", url: "https://example.com/company-a.pdf#page=45"}, {title: "“Net revenue was $8.0 billion in 2025 and $7.9 billion in 2024.”", sourceName: "Company B · Page 52", url: "https://example.com/company-b.pdf#page=52"}, {title: "“Data center revenue was $6.0 billion.”", sourceName: "Company A · Page 47", url: "https://example.com/company-a.pdf#page=47"}, {title: "“Client segment revenue was $4.1 billion.”", sourceName: "Company B · Page 55", url: "https://example.com/company-b.pdf#page=55"}])
+followUps = FollowUpBlock([FollowUpItem("Compare operating margin"), FollowUpItem("Which segment grew fastest?")])
+`;
+
+export function comparisonPrompt(documents: Document[]) {
+ return generateSystemPrompt({
+ cloud: true,
+ library: spec,
+ promptOptions: {
+ additionalRules: [
+ `You compare these documents and answer only from them: ${JSON.stringify(documents)}. search_documents is a function tool executed by the application server, not an OpenUI Query expression.`,
+ "Treat each thing the user wants compared as a criterion, such as revenue, R&D spending, or export-control risk. Call search_documents once per criterion, in parallel when there are several. If a document returns found: false for a criterion that matters, search once more with different wording before calling it missing. Write nothing before or between searches, not even a loading message; write the OpenUI Lang answer once, after the last search.",
+ "Answer with: a CardHeader naming the criteria and documents; a Table; charts for numeric criteria; Callouts for gaps and conflicts; Sources; and a FollowUpBlock suggesting two or three criteria to add.",
+ "Keep every table cell to one short value with its page, like '$215.9 billion (p. 37)'. For single values, use one row per criterion and one column per document. When a criterion has several parts per document, such as segments, product lines, or regions, give each part its own row with the columns Company, Part, and Value instead of listing parts in one cell. Skip a table that would only repeat a chart.",
+ "Choose charts from the shape of the data, not by habit. Annual reports usually give several years of figures, so show a trend with a LineChart, one series per document. Show a breakdown, such as revenue by segment, with one HorizontalBarChart that has a bar for each document and part, labeled 'Company · Part' and grouped by company. Use a stacked BarChart only when every document reports the same parts. Use a grouped BarChart for one value per document, and HorizontalBarChart for percentages or long labels.",
+ "Place every chart at full width in the column Stack, one below another. Never put charts side by side in a row.",
+ "Leave a document out of a chart when it has no value, and never plot a missing value as zero. Put all values in one unit, such as USD billions, and name it in the axis label.",
+ "Use a warning Callout when information conflicts or is not directly comparable, such as different fiscal year ends or definitions. Use an info Callout when a document does not disclose a criterion, and write 'Not found' in its table cell. Keep each Callout to one or two short sentences.",
+ "End with one Sources component that lists each quoted page once, in the order of the criteria. For each item, title is a quote of at most 20 words that states the value, like '“Revenue for fiscal year 2026 was $215.9 billion, up 65%.”'; sourceName is the company and page, like 'NVIDIA · Page 37'; and url is the passage's url from search_documents, left out when the passage has none. When the value comes from a table, write its row label and values instead of a quote, like 'Net revenue (USD millions): 52,853 in 2025, 53,101 in 2024'. Use only facts stated in the returned passages.",
+ "On follow-ups, keep the documents and earlier criteria in mind. When the user adds a criterion, search for it and show the comparison for that criterion. Do not generate Query, Mutation, reactive variables, or form controls.",
+ ],
+ examples: [singlePeriodExample, trendExample],
+ },
+ });
+}
diff --git a/examples/cookbooks/document-comparison/src/lib/theme.ts b/examples/cookbooks/document-comparison/src/lib/theme.ts
new file mode 100644
index 000000000..5ae8f5b0d
--- /dev/null
+++ b/examples/cookbooks/document-comparison/src/lib/theme.ts
@@ -0,0 +1,25 @@
+import { createTheme } from "@openuidev/react-ui";
+
+// A teal accent for this example, with separate values for dark mode so text on the
+// accent and the user's message bubble keep their contrast.
+export const lightTheme = createTheme({
+ interactiveAccentDefault: "#0f766e",
+ interactiveAccentHover: "#115e59",
+ interactiveAccentPressed: "#134e4a",
+ interactiveAccentDisabled: "#99d5cf",
+ textAccentPrimary: "#ffffff",
+ chatUserResponseBg: "#e3f2ef",
+ chatUserResponseText: "#0b3b36",
+ radiusM: "10px",
+});
+
+export const darkTheme = createTheme({
+ interactiveAccentDefault: "#2dd4bf",
+ interactiveAccentHover: "#5eead4",
+ interactiveAccentPressed: "#14b8a6",
+ interactiveAccentDisabled: "#134e4a",
+ textAccentPrimary: "#042f2e",
+ chatUserResponseBg: "#12332f",
+ chatUserResponseText: "#d7f5ef",
+ radiusM: "10px",
+});
diff --git a/examples/cookbooks/document-comparison/src/lib/tool-loop.ts b/examples/cookbooks/document-comparison/src/lib/tool-loop.ts
new file mode 100644
index 000000000..ba00e6177
--- /dev/null
+++ b/examples/cookbooks/document-comparison/src/lib/tool-loop.ts
@@ -0,0 +1,137 @@
+import { randomUUID } from "node:crypto";
+import type OpenAI from "openai";
+import type {
+ ChatCompletionChunk,
+ ChatCompletionCreateParamsStreaming,
+ ChatCompletionMessageParam,
+} from "openai/resources/chat/completions";
+
+/**
+ * Function-tool loop for the OpenUI Gateway Chat Completions API.
+ *
+ * Chat Completions returns function calls to the application instead of running
+ * them. Each round streams one completion. When the model requests tools, the
+ * loop runs them, appends the assistant's tool-call message and one `tool`
+ * message per call, and requests the next completion. It ends when the model
+ * answers without requesting a tool. The last allowed round sets
+ * `tool_choice: "none"` so the model must answer in text.
+ *
+ * The browser receives AG-UI events rather than raw completion chunks, because
+ * Chat Completions has no chunk for a tool result. Agent Interface reads them
+ * with `agUIAdapter()` and shows each call with its result.
+ */
+
+export type FunctionToolExecutor = (
+ argsJson: string,
+ ctx: { signal?: AbortSignal },
+) => Promise;
+
+export interface RunChatToolLoopOptions {
+ client: OpenAI;
+ /** The completion request; `messages` holds the system prompt and the conversation. */
+ params: Omit;
+ /**
+ * The already-open stream of the first round, created from `params`. Opening it
+ * before responding lets the route return Gateway's errors as HTTP errors.
+ */
+ firstStream: AsyncIterable;
+ /** name → executor. A call to any other name receives an error result. */
+ tools: Record;
+ /** Receives every AG-UI event to forward to the browser. */
+ emit: (event: Record) => void;
+ /** Propagates browser aborts into executors and model requests. */
+ signal?: AbortSignal;
+ /** Cap on model requests per question (default 5). */
+ maxRounds?: number;
+}
+
+type ToolCall = { id: string; name: string; arguments: string };
+
+export async function runChatToolLoop(options: RunChatToolLoopOptions): Promise {
+ const { client, tools, emit, signal, maxRounds = 5 } = options;
+ const messages: ChatCompletionMessageParam[] = [...options.params.messages];
+
+ for (let round = 0; round < maxRounds; round++) {
+ const lastRound = round === maxRounds - 1;
+ const stream =
+ round === 0
+ ? options.firstStream
+ : await client.chat.completions.create(
+ {
+ ...options.params,
+ messages,
+ stream: true,
+ ...(lastRound ? { tool_choice: "none" as const } : {}),
+ },
+ { signal },
+ );
+
+ const messageId = randomUUID();
+ let text = "";
+ const calls: ToolCall[] = [];
+ for await (const chunk of stream) {
+ const delta = chunk.choices[0]?.delta;
+ if (delta?.content) {
+ if (!text) emit({ type: "TEXT_MESSAGE_START", messageId, role: "assistant" });
+ text += delta.content;
+ emit({ type: "TEXT_MESSAGE_CONTENT", messageId, delta: delta.content });
+ }
+ // Each call streams as indexed deltas: its id and name first, then argument fragments.
+ // The last round ignores calls, in case a model does not honor tool_choice.
+ for (const part of lastRound ? [] : (delta?.tool_calls ?? [])) {
+ let call = calls[part.index];
+ if (!call) {
+ call = { id: part.id ?? "", name: part.function?.name ?? "", arguments: "" };
+ calls[part.index] = call;
+ emit({
+ type: "TOOL_CALL_START",
+ toolCallId: call.id,
+ toolCallName: call.name,
+ parentMessageId: messageId,
+ });
+ }
+ if (part.function?.arguments) {
+ call.arguments += part.function.arguments;
+ emit({ type: "TOOL_CALL_ARGS", toolCallId: call.id, delta: part.function.arguments });
+ }
+ }
+ }
+ if (text) emit({ type: "TEXT_MESSAGE_END", messageId });
+
+ const requested = calls.filter(Boolean);
+ if (requested.length === 0) {
+ if (!text) throw new Error("The model returned no answer. Please retry.");
+ return;
+ }
+
+ messages.push({
+ role: "assistant",
+ content: text || null,
+ tool_calls: requested.map((call) => ({
+ id: call.id,
+ type: "function",
+ function: { name: call.name, arguments: call.arguments },
+ })),
+ });
+ for (const call of requested) emit({ type: "TOOL_CALL_END", toolCallId: call.id });
+ // A throwing executor settles as an error result rather than aborting the run.
+ for (const call of requested) {
+ let content: string;
+ try {
+ const execute = Object.hasOwn(tools, call.name) ? tools[call.name] : undefined;
+ if (!execute) throw new Error(`Unknown tool: ${call.name}`);
+ content = await execute(call.arguments, { signal });
+ } catch (error) {
+ content = JSON.stringify({ error: error instanceof Error ? error.message : String(error) });
+ }
+ messages.push({ role: "tool", tool_call_id: call.id, content });
+ emit({
+ type: "TOOL_CALL_RESULT",
+ messageId: randomUUID(),
+ toolCallId: call.id,
+ content,
+ role: "tool",
+ });
+ }
+ }
+}
diff --git a/examples/cookbooks/document-comparison/src/lib/tools/search-documents.ts b/examples/cookbooks/document-comparison/src/lib/tools/search-documents.ts
new file mode 100644
index 000000000..6e1099065
--- /dev/null
+++ b/examples/cookbooks/document-comparison/src/lib/tools/search-documents.ts
@@ -0,0 +1,132 @@
+import { statSync } from "node:fs";
+import { resolve } from "node:path";
+import { z } from "zod/v4";
+import { openDatabase, sources, type Document } from "../documents";
+import { embed, similarity } from "../embeddings";
+
+// The search_documents function tool: its JSON schema for Gateway, argument validation,
+// semantic search over the prepared passages, and the executor the tool loop calls.
+
+export function searchDocumentsTool(documents: Document[]) {
+ return {
+ type: "function" as const,
+ function: {
+ name: "search_documents",
+ description:
+ "Find passages about one comparison criterion in the documents. Returns the closest passages from each document with page numbers. Call it once per criterion.",
+ parameters: {
+ type: "object",
+ properties: {
+ query: {
+ type: "string",
+ description:
+ "The information to find, as a short description, such as 'total revenue for the fiscal year and growth from the prior year'.",
+ },
+ document_ids: {
+ type: "array",
+ items: { type: "string", enum: documents.map((document) => document.id) },
+ description: "Documents to search. Empty for all documents.",
+ },
+ passages_per_document: {
+ type: "integer",
+ minimum: 1,
+ maximum: 4,
+ description:
+ "Passages to return from each document. Use 2 unless more context is needed.",
+ },
+ },
+ required: ["query", "document_ids", "passages_per_document"],
+ additionalProperties: false,
+ },
+ strict: true,
+ },
+ };
+}
+
+// Validate arguments again on the server; the model's output is untrusted input.
+const argsSchema = z
+ .object({
+ query: z.string().trim().min(3).max(300),
+ document_ids: z.array(z.string()).max(10),
+ passages_per_document: z.number().int().min(1).max(4),
+ })
+ .strict();
+
+// Below this similarity, a document probably does not discuss the criterion.
+const weakMatch = 0.3;
+
+type Passage = { documentId: string; page: number; text: string; embedding: Float32Array };
+let cache: { modified: number; documents: Document[]; passages: Passage[] } | undefined;
+
+// Load every passage once and reload only after npm run prepare:documents changes the file.
+function loadPassages() {
+ const modified = statSync(resolve(process.cwd(), "data/documents.sqlite")).mtimeMs;
+ if (cache?.modified === modified) return cache;
+ const db = openDatabase();
+ try {
+ const documents = db
+ .prepare("SELECT id, name, period, pages FROM documents ORDER BY rowid")
+ .all() as Document[];
+ const rows = db.prepare("SELECT document_id, page, text, embedding FROM chunks").all() as {
+ document_id: string;
+ page: number;
+ text: string;
+ embedding: Uint8Array;
+ }[];
+ const passages = rows.map((row) => ({
+ documentId: row.document_id,
+ page: row.page,
+ text: row.text,
+ embedding: new Float32Array(
+ row.embedding.buffer.slice(
+ row.embedding.byteOffset,
+ row.embedding.byteOffset + row.embedding.byteLength,
+ ),
+ ),
+ }));
+ cache = { modified, documents, passages };
+ return cache;
+ } finally {
+ db.close();
+ }
+}
+
+export async function executeSearchDocuments(
+ argsJson: string,
+ { signal }: { signal?: AbortSignal } = {},
+) {
+ const args = argsSchema.parse(JSON.parse(argsJson));
+ const { documents, passages } = loadPassages();
+ const unknown = args.document_ids.filter(
+ (id) => !documents.some((document) => document.id === id),
+ );
+ if (unknown.length) throw new RangeError(`Unknown documents: ${unknown.join(", ")}.`);
+ const selected = args.document_ids.length
+ ? documents.filter((document) => args.document_ids.includes(document.id))
+ : documents;
+
+ const [queryEmbedding] = await embed([args.query], signal);
+ const results = selected.map((document) => {
+ // PDF viewers open #page=N at that page. Your own PDFs in documents/ have no URL.
+ const url = sources.find((source) => source.id === document.id)?.url;
+ const matches = passages
+ .filter((passage) => passage.documentId === document.id)
+ .map((passage) => ({ ...passage, score: similarity(queryEmbedding, passage.embedding) }))
+ .sort((a, b) => b.score - a.score)
+ .slice(0, args.passages_per_document);
+ const bestScore = matches[0]?.score ?? 0;
+ return {
+ document_id: document.id,
+ document: document.name,
+ period: document.period,
+ found: bestScore >= weakMatch,
+ passages: matches.map((match) => ({
+ page: match.page,
+ url: url && `${url}#page=${match.page}`,
+ text: match.text,
+ score: Math.round(match.score * 1000) / 1000,
+ })),
+ };
+ });
+ return JSON.stringify({ query: args.query, results });
+}
diff --git a/examples/cookbooks/document-comparison/src/library.ts b/examples/cookbooks/document-comparison/src/library.ts
new file mode 100644
index 000000000..a069383de
--- /dev/null
+++ b/examples/cookbooks/document-comparison/src/library.ts
@@ -0,0 +1,27 @@
+import { createLibrary } from "@openuidev/react-lang";
+import { openuiChatLibrary, openuiLibrary } from "@openuidev/react-ui/genui-lib";
+import { Sources } from "./components/sources";
+
+// The same subset generates the server's specification and renders in the client.
+export const library = createLibrary({
+ root: "Stack",
+ components: [
+ ...[
+ "Stack",
+ "CardHeader",
+ "TextContent",
+ "Table",
+ "Col",
+ "BarChart",
+ "HorizontalBarChart",
+ "LineChart",
+ "Series",
+ "Callout",
+ "TagBlock",
+ ].map((name) => openuiLibrary.components[name]),
+ Sources,
+ // Follow-up suggestions live in the chat library.
+ openuiChatLibrary.components.FollowUpBlock,
+ openuiChatLibrary.components.FollowUpItem,
+ ],
+});
diff --git a/examples/cookbooks/document-comparison/tsconfig.json b/examples/cookbooks/document-comparison/tsconfig.json
new file mode 100644
index 000000000..ee52e6e0f
--- /dev/null
+++ b/examples/cookbooks/document-comparison/tsconfig.json
@@ -0,0 +1,30 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "lib": ["dom", "dom.iterable", "esnext"],
+ "strict": true,
+ "noEmit": true,
+ "skipLibCheck": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "bundler",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "react-jsx",
+ "incremental": true,
+ "plugins": [
+ {
+ "name": "next"
+ }
+ ],
+ "allowJs": true
+ },
+ "include": [
+ "next-env.d.ts",
+ "**/*.ts",
+ "**/*.tsx",
+ ".next/types/**/*.ts",
+ ".next/dev/types/**/*.ts"
+ ],
+ "exclude": ["node_modules"]
+}
diff --git a/examples/examples.json b/examples/examples.json
index 64ef5f9b8..fbc631ca6 100644
--- a/examples/examples.json
+++ b/examples/examples.json
@@ -66,6 +66,18 @@
"path": "cookbooks/conversational-analytics",
"envKey": "THESYS_API_KEY"
},
+ {
+ "title": "Document comparison",
+ "description": "Compare NVIDIA, AMD, and Intel annual reports with retrieved, page-cited evidence, charts, and a customized Agent Interface.",
+ "path": "cookbooks/document-comparison",
+ "envKey": "THESYS_API_KEY"
+ },
+ {
+ "title": "Booking assistant",
+ "description": "Find stays anywhere with prefilled, validated forms, live hotel prices from trivago's MCP server, and a summary before booking.",
+ "path": "cookbooks/booking-assistant",
+ "envKey": "THESYS_API_KEY"
+ },
{
"title": "Material UI",
"description": "A broad Material UI component library for generated interfaces.",