feat(examples): add OpenUI PDF RAG integration

VI
2mo ago
+2818-160

PR Checklist

Please check if your PR fulfills the following requirements:

Bugs / Features

A changeset is not included because this adds a standalone example and does not change a published package.

What is the current behavior?

VoltAgent examples do not show how to turn retrieved agent context into streamed, interactive generative UI. There is no repository example covering an OpenUI parser and renderer, source-grounded charts, follow-up actions, and form values sent into a new VoltAgent turn.

What is the new behavior?

Adds examples/with-openui, a Next.js PDF RAG chat in which:

  • VoltAgent owns agent orchestration, BaseRetriever retrieval, conversation IDs, and Agent.streamText() streaming.
  • OpenUI owns the generated component prompt, AgentInterface, stream parsing, themed rendering, charts, forms, and follow-up actions.
  • The New York City Rent Guidelines Board 2025 Housing Supply Report is the only housing-data source.
  • The PDF is extracted and chunked once, embedded in memory, and searched without a vector database.
  • OpenUI follow-ups and @ToAssistant form submissions return through the same /api/chat route.
  • Current and legacy OpenUI action envelopes are normalized into focused retrieval queries.

The example README documents setup, supported versions, the request flow, datasource replacement, acceptance prompts, and production considerations.

Closes #1400

Validation

pnpm --filter voltagent-example-with-openui generate:prompt
pnpm --filter voltagent-example-with-openui typecheck
pnpm --filter voltagent-example-with-openui lint
pnpm --filter voltagent-example-with-openui test
pnpm --filter voltagent-example-with-openui build

All commands pass. The test suite contains 18 tests covering PDF extraction and ranking, current and legacy action-envelope retrieval, chat request preservation, and OpenUI parser acceptance for chart, dashboard, permit-impact, and form-oriented response shapes.

Browser acceptance on the local app:

CheckEvidence
Theme providerAgentInterface exposed 213 active --openui-* variables and rendered the configured dark green theme.
Parser and rendererAssistant output rendered as components rather than raw OpenUI Lang. No browser console errors were recorded.
ChartThe PDF-backed borough permit chart rendered at 678 by 326 pixels with all five borough labels and page 6 citation.
Follow-upClicking Explain the impact of these permits on housing supply created one user turn and one backend request in the same conversation. The reply distinguished permits from completions and displayed exact retrieved values.
Form submitEmpty required fields were blocked. Submitting Vacancy rates, City planners, and Compare borough differences produced one backend request and a page 5 table with exact borough rates and an explicit Not calculable value for Staten Island.

Notes for reviewers

  • The bundled PDF is an official public report and is about 2.1 MB.
  • The in-memory index is intentional for this single-document example. The README recommends persistent vector storage for larger or changing collections.
  • Authentication, rate limiting, durable conversation storage, and treating uploaded PDF text as untrusted input are documented as production follow-ups.
  • Local browser screenshots were used for acceptance verification but are not committed.

Summary by cubic

Adds examples/with-openui, a Next.js chat that connects VoltAgent’s single‑PDF RAG to OpenUI for streamed, interactive UI grounded in NYC’s 2025 Housing Supply Report. This demonstrates safe, source‑grounded charts/forms/follow‑ups with hardened sessions and strict request limits.

  • Server: /api/chat streams OpenAI‑compatible SSE using @voltagent/internal safeStringify, reads openui/generated/system-prompt.txt, sets an HttpOnly anonymous visitor cookie, and derives conversationId by hashing server userId with client threadId. Enforces a 1 MB JSON body limit (rejects oversized Content-Length, cancels over‑limit chunked bodies), validates a minimal messages schema, and returns 400 on invalid input.
  • Retrieval: NycHousingPdfRetriever lazily extracts/chunks the bundled PDF, embeds in memory with text-embedding-3-small, ranks by cosine similarity, drops matches below 0.30, expands hits to full PDF pages, and sets rag.references; on errors it injects a retrieval‑unavailable context so the agent refuses to answer from memory.
  • Request handling: normalizes current OpenUI sentinel and legacy <context> envelopes into focused retrieval queries, prioritizing submitted form fields; supports array‑formatted message content.
  • UI: @openuidev/react-ui AgentInterface with the OpenAI adapter streams from the same route; a dark theme is enabled; follow‑ups and @ToAssistant form submissions round‑trip to VoltAgent.
  • Tests: cover PDF extraction and ranking threshold; chat request validation including the 1 MB limit, malformed JSON, and stream cancellation; OpenUI parser acceptance (charts/dashboards/forms); and anonymous session cookies plus conversation ID derivation.
  • Repo: .gitignore excludes openui/generated/*; next.config.ts allows pdf-parse via serverExternalPackages; regenerate prompts with pnpm generate:prompt.
  • Standalone example only; no changes to published packages and no migration required.

Summary by CodeRabbit

  • New Features

    • Added a complete VoltAgent + OpenUI example for PDF-grounded NYC housing analysis.
    • Supports streaming charts, dashboards, forms, citations, follow-up actions, and submitted form interactions.
    • Added configurable models, starter prompts, chat endpoint setup, anonymous session continuity, and request-size validation.

  • Documentation

    • Added setup, architecture, configuration, data-source replacement, and validation guidance.

  • Tests

    • Added coverage for chat validation, sessions, PDF retrieval, and OpenUI response parsing.