improvement(docs): Ask AI chat grounded in the docs vector store (#5172)

* docs: Ask AI chat grounded in the docs vector store

Adds an Ask AI chat to the docs site. A floating launcher opens a chat panel
backed by the Vercel AI SDK (OpenAI provider, OPENAI_API_KEY from the
environment). A searchDocs tool runs locale-scoped vector/keyword search over
the existing docs embeddings so answers cite real pages.

The public endpoint is hardened: per-request size/token/step caps, message
sanitization (no client-injected tool results or system prompts), origin
checks, and a per-IP rate limit. Non-English retrieval uses keyword search;
English vector search applies a similarity threshold.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs: harden Ask AI retrieval + fix stale loading state

- searchDocs: wrap the keyword query in try/catch too, so each retrieval path
  (keyword, vector) is independent best-effort
- ask-ai: gate the loading ellipsis to the in-progress (last) message so older
  empty bubbles don't re-show it while a later request streams

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Will Chen
2026-06-25 16:32:29 -07:00
committed by GitHub
co-authored by Claude Opus 4.8
parent 5db5963fc1
commit 6355c8e699
5 changed files with 581 additions and 1 deletions
+2
View File
@@ -3,6 +3,7 @@ import { defineI18nUI } from 'fumadocs-ui/i18n'
import { DocsLayout } from 'fumadocs-ui/layouts/docs'
import { RootProvider } from 'fumadocs-ui/provider/next'
import { Geist_Mono, Inter } from 'next/font/google'
import { AskAI } from '@/components/ai/ask-ai'
import {
SidebarFolder,
SidebarItem,
@@ -120,6 +121,7 @@ export default async function Layout({ children, params }: LayoutProps) {
>
{children}
</DocsLayout>
<AskAI locale={lang} />
</RootProvider>
</body>
</html>
+344
View File
@@ -0,0 +1,344 @@
import { openai } from '@ai-sdk/openai'
import { convertToModelMessages, stepCountIs, streamText, tool, type UIMessage } from 'ai'
import { sql } from 'drizzle-orm'
import { z } from 'zod'
import { db, docsEmbeddings } from '@/lib/db'
import { generateSearchEmbedding } from '@/lib/embeddings'
export const runtime = 'nodejs'
export const maxDuration = 30
/** Model used for the Ask AI chat. Override with OPENAI_CHAT_MODEL in the environment. */
const CHAT_MODEL = process.env.OPENAI_CHAT_MODEL || 'gpt-5.4-mini'
/** Max documentation chunks returned per search to ground an answer. */
const SEARCH_LIMIT = 6
/** Candidates pulled before locale filtering, so a locale still yields SEARCH_LIMIT results. */
const SEARCH_CANDIDATES = SEARCH_LIMIT * 4
/** Minimum cosine similarity for an English vector match (mirrors the site search route). */
const SIMILARITY_THRESHOLD = 0.6
/** Locales the docs are published in (mirrors the site search route). */
const KNOWN_LOCALES = ['en', 'es', 'fr', 'de', 'ja', 'zh']
const DEFAULT_LOCALE = 'en'
/** Postgres full-text config per locale (mirrors the site search route). */
const TS_CONFIG: Record<string, string> = {
en: 'english',
es: 'spanish',
fr: 'french',
de: 'german',
ja: 'simple',
zh: 'simple',
}
/**
* Abuse guards. This endpoint proxies a paid LLM, so an unauthenticated public
* route is a target for scripted "free inference". These bounds cap the cost of
* any single request; an in-memory per-IP rate limit (below) caps volume on the
* hot path. A shared-store rate limit, a provider spend cap, and edge bot
* protection remain the durable controls (see the PR checklist).
*
* The size cap counts only user-authored text — NOT the conversation history,
* assistant turns, or retrieved doc chunks we add via the searchDocs tool, which
* legitimately grow large over a multi-turn chat.
*/
const MAX_MESSAGES = 200
const MAX_USER_INPUT_CHARS = 400_000
const MAX_OUTPUT_TOKENS = 4000
const MAX_STEPS = 6
/** Backstop on the sanitized model payload — bounds total LLM input (e.g. stuffed assistant text). */
const MAX_TOTAL_CHARS = 1_000_000
/**
* Per-IP rate limit. Fixed window, in-memory: this bounds volume from a single
* source on a warm instance without external infra. It is best-effort on
* serverless (state is per-instance, not shared across regions/cold starts);
* a shared store (e.g. Vercel KV) and an edge WAF remain the durable controls,
* but this closes the "no volume limit at all" gap on the hot path.
*/
const RATE_LIMIT_MAX = 20
const RATE_LIMIT_WINDOW_MS = 60_000
const rateLimitHits = new Map<string, { count: number; resetAt: number }>()
/** Resolve the client IP from forwarding headers, falling back to a shared bucket. */
function getClientIp(req: Request): string {
const forwarded = req.headers.get('x-forwarded-for')
if (forwarded) return forwarded.split(',')[0].trim()
return req.headers.get('x-real-ip') ?? 'unknown'
}
/** Fixed-window check. Returns retry-after seconds when the caller is over the limit, else null. */
function rateLimit(ip: string, now: number): number | null {
const entry = rateLimitHits.get(ip)
if (!entry || now >= entry.resetAt) {
rateLimitHits.set(ip, { count: 1, resetAt: now + RATE_LIMIT_WINDOW_MS })
return null
}
if (entry.count >= RATE_LIMIT_MAX) {
return Math.ceil((entry.resetAt - now) / 1000)
}
entry.count += 1
return null
}
/** Drop expired buckets so the Map doesn't grow unbounded on a long-lived instance. */
function sweepRateLimit(now: number): void {
if (rateLimitHits.size < 10_000) return
for (const [ip, entry] of rateLimitHits) {
if (now >= entry.resetAt) rateLimitHits.delete(ip)
}
}
/** A structurally valid UI message: has a role and a parts array. */
function isValidMessage(message: unknown): message is UIMessage {
return (
typeof message === 'object' &&
message !== null &&
typeof (message as { role?: unknown }).role === 'string' &&
Array.isArray((message as { parts?: unknown }).parts)
)
}
/** Total length of user-authored text across the conversation. */
function userInputChars(messages: UIMessage[]): number {
let total = 0
for (const message of messages) {
if (message.role !== 'user') continue
for (const part of message.parts) {
if (part.type === 'text' && typeof part.text === 'string') total += part.text.length
}
}
return total
}
/**
* Strip everything the model shouldn't trust from client-supplied history:
* drop `system` messages (client-injected instructions) and every non-text part
* (e.g. crafted tool results faking searchDocs output). Only user/assistant text
* survives, so grounding comes from the server-run searchDocs tool — not the
* client's payload.
*/
function sanitizeMessages(messages: UIMessage[]): UIMessage[] {
return messages
.filter((message) => message.role === 'user' || message.role === 'assistant')
.map((message) => ({
...message,
parts: message.parts.filter((part) => part.type === 'text' && typeof part.text === 'string'),
}))
.filter((message) => message.parts.length > 0)
}
/**
* Reject obvious cross-origin calls. Same-origin browser requests send an
* `Origin` header matching the host; we allow those, plus any host in
* DOCS_ALLOWED_ORIGINS (comma-separated). Requests with no Origin (e.g. curl)
* are allowed through to the cost caps rather than blocked, since Origin is
* trivially spoofable and is a filter, not a security boundary.
*/
function isAllowedOrigin(req: Request): boolean {
const origin = req.headers.get('origin')
if (!origin) return true
let originHost: string
try {
originHost = new URL(origin).host.toLowerCase()
} catch {
return false
}
const forwardedHost = req.headers.get('x-forwarded-host') ?? req.headers.get('host')
const requestHost = forwardedHost?.split(',')[0].trim().toLowerCase()
if (requestHost && originHost === requestHost) return true
const allowlist = (process.env.DOCS_ALLOWED_ORIGINS ?? '')
.split(',')
.map((value) => value.trim().toLowerCase())
.filter(Boolean)
return allowlist.includes(originHost)
}
const SYSTEM_PROMPT = `You are the documentation assistant for Sim — the open-source AI workspace where teams build, deploy, and manage AI agents.
Answer questions about Sim using the documentation. Always call the searchDocs tool before answering anything specific about Sim's features, configuration, or usage — do not answer from memory. Base your answer only on the returned documentation; if the docs do not cover the question, say so plainly rather than guessing.
Guidelines:
- Be direct and concrete. Lead with the answer, then the detail.
- Reference the relevant pages by their titles so the user knows where to read more.
- When you show configuration or code, keep it minimal and correct.
- The agent is called "Sim" and the chat surface is "Chat" — never say "Mothership" or "copilot".
- If a question is unrelated to Sim, briefly say it's outside the docs' scope.`
const SEARCH_COLUMNS = {
chunkId: docsEmbeddings.chunkId,
title: docsEmbeddings.headerText,
url: docsEmbeddings.sourceLink,
content: docsEmbeddings.chunkText,
sourceDocument: docsEmbeddings.sourceDocument,
}
/** Reciprocal-rank-fusion constant, matching the site search route. */
const RRF_K = 60
/**
* SQL predicate selecting only the locale's documents, so the row limit applies
* to matching rows: non-English docs are prefixed with their locale segment;
* English is everything not prefixed with another locale.
*/
function localeFilter(locale: string) {
const firstSegment = sql`split_part(${docsEmbeddings.sourceDocument}, '/', 1)`
if (locale === DEFAULT_LOCALE) {
const others = KNOWN_LOCALES.filter((l) => l !== DEFAULT_LOCALE)
return sql`${firstSegment} not in (${sql.join(
others.map((l) => sql`${l}`),
sql`, `
)})`
}
return sql`${firstSegment} = ${locale}`
}
type SearchRow = {
chunkId: string
title: string
url: string
content: string
sourceDocument: string
}
/**
* Retrieve candidate chunks for grounding, mirroring the site search route's
* hybrid strategy: Postgres full-text keyword search for every locale, plus
* vector similarity (thresholded) for English — fused by reciprocal rank so a
* page found by either signal can ground the answer.
*/
async function searchDocs(query: string, locale: string) {
const tsConfig = TS_CONFIG[locale] ?? 'simple'
// Each retrieval path is best-effort and independent: a failure in one still
// lets the other ground the answer (both empty just yields no grounding).
let keywordRows: SearchRow[] = []
try {
keywordRows = await db
.select(SEARCH_COLUMNS)
.from(docsEmbeddings)
.where(
sql`${docsEmbeddings.chunkTextTsv} @@ plainto_tsquery(${tsConfig}, ${query}) and ${localeFilter(locale)}`
)
.orderBy(
sql`ts_rank(${docsEmbeddings.chunkTextTsv}, plainto_tsquery(${tsConfig}, ${query})) DESC`
)
.limit(SEARCH_CANDIDATES)
} catch (error) {
console.error('Ask AI keyword search failed:', error)
}
let vectorRows: SearchRow[] = []
if (locale === DEFAULT_LOCALE) {
// Vector retrieval (embedding call + pgvector query) is best-effort: if it
// fails, fall back to the keyword rows already fetched rather than losing all
// grounding for the turn.
try {
const embedding = await generateSearchEmbedding(query)
const vectorLiteral = JSON.stringify(embedding)
vectorRows = await db
.select(SEARCH_COLUMNS)
.from(docsEmbeddings)
.where(
sql`1 - (${docsEmbeddings.embedding} <=> ${vectorLiteral}::vector) >= ${SIMILARITY_THRESHOLD} and ${localeFilter(locale)}`
)
.orderBy(sql`${docsEmbeddings.embedding} <=> ${vectorLiteral}::vector`)
.limit(SEARCH_CANDIDATES)
} catch (error) {
console.error('Ask AI vector search failed; using keyword results only:', error)
}
}
// Reciprocal rank fusion across the two rankings, deduped by chunk.
const scores = new Map<string, number>()
const rowById = new Map<string, SearchRow>()
for (const list of [vectorRows, keywordRows]) {
list.forEach((row, index) => {
scores.set(row.chunkId, (scores.get(row.chunkId) ?? 0) + 1 / (RRF_K + index + 1))
if (!rowById.has(row.chunkId)) rowById.set(row.chunkId, row)
})
}
return [...rowById.values()]
.sort((a, b) => (scores.get(b.chunkId) ?? 0) - (scores.get(a.chunkId) ?? 0))
.slice(0, SEARCH_LIMIT)
.map((row) => ({
title: row.title,
url: row.url,
content: row.content,
}))
}
export async function POST(req: Request) {
if (!isAllowedOrigin(req)) {
return new Response('Forbidden', { status: 403 })
}
const now = Date.now()
sweepRateLimit(now)
const retryAfter = rateLimit(getClientIp(req), now)
if (retryAfter !== null) {
return new Response('Too many requests', {
status: 429,
headers: { 'Retry-After': String(retryAfter) },
})
}
let body: { messages: UIMessage[]; locale?: string }
try {
body = await req.json()
} catch {
return new Response('Invalid JSON', { status: 400 })
}
const { messages } = body
const locale = KNOWN_LOCALES.includes(body.locale ?? '')
? (body.locale as string)
: DEFAULT_LOCALE
if (!Array.isArray(messages) || messages.length === 0 || messages.length > MAX_MESSAGES) {
return new Response('Invalid request', { status: 400 })
}
if (!messages.every(isValidMessage)) {
return new Response('Invalid request', { status: 400 })
}
if (userInputChars(messages) > MAX_USER_INPUT_CHARS) {
return new Response('Request too large', { status: 413 })
}
const modelMessages = sanitizeMessages(messages)
if (modelMessages.length === 0) {
return new Response('Invalid request', { status: 400 })
}
// Bound what actually reaches the model. Measured AFTER sanitization, so the
// prior searchDocs tool outputs that accumulate in client history (and are
// stripped here) don't count — only user/assistant text the model will see.
if (JSON.stringify(modelMessages).length > MAX_TOTAL_CHARS) {
return new Response('Request too large', { status: 413 })
}
const result = streamText({
model: openai(CHAT_MODEL),
system: SYSTEM_PROMPT,
messages: convertToModelMessages(modelMessages),
stopWhen: stepCountIs(MAX_STEPS),
maxOutputTokens: MAX_OUTPUT_TOKENS,
tools: {
searchDocs: tool({
description:
'Search the Sim documentation for relevant content. Use this before answering any question about Sim.',
inputSchema: z.object({
query: z.string().describe('A focused natural-language search query.'),
}),
execute: async ({ query }) => searchDocs(query, locale),
}),
},
})
return result.toUIMessageStreamResponse()
}
+218
View File
@@ -0,0 +1,218 @@
'use client'
import { type FormEvent, useEffect, useMemo, useRef, useState } from 'react'
import { useChat } from '@ai-sdk/react'
import { DefaultChatTransport } from 'ai'
import { ArrowUp, MessageCircle, Square, X } from 'lucide-react'
import { Streamdown } from 'streamdown'
import { cn } from '@/lib/utils'
import 'streamdown/styles.css'
interface DocSource {
title: string
url: string
}
/** Pull the deduped doc sources surfaced by the searchDocs tool out of a message's parts. */
function getSources(parts: ReadonlyArray<{ type: string; [key: string]: unknown }>): DocSource[] {
const seen = new Set<string>()
const sources: DocSource[] = []
for (const part of parts) {
if (part.type !== 'tool-searchDocs') continue
const output = (part as { output?: unknown }).output
if (!Array.isArray(output)) continue
for (const item of output as DocSource[]) {
if (!item?.url || seen.has(item.url)) continue
seen.add(item.url)
sources.push({ title: item.title, url: item.url })
}
}
return sources
}
/** Concatenate the streamed text parts of a message. */
function getText(parts: ReadonlyArray<{ type: string; [key: string]: unknown }>): string {
return parts
.filter((part) => part.type === 'text')
.map((part) => (part as unknown as { text: string }).text)
.join('')
}
interface AskAIProps {
/** Active docs locale, forwarded so retrieval is scoped to the reader's language. */
locale: string
}
export function AskAI({ locale }: AskAIProps) {
const [open, setOpen] = useState(false)
const [input, setInput] = useState('')
const scrollRef = useRef<HTMLDivElement>(null)
// Stable transport; the locale is sent per-message (below) so it stays current
// after a language switch instead of being frozen into the transport.
const transport = useMemo(() => new DefaultChatTransport({ api: '/api/chat' }), [])
const { messages, sendMessage, status, stop, error } = useChat({ transport })
const isBusy = status === 'submitted' || status === 'streaming'
// Jump to the bottom instantly when the panel opens (a mount transition).
useEffect(() => {
if (!open) return
scrollRef.current?.scrollTo({ top: scrollRef.current.scrollHeight })
}, [open])
// Smooth-scroll as new messages stream in (an explicit re-orientation cue).
useEffect(() => {
scrollRef.current?.scrollTo({ top: scrollRef.current.scrollHeight, behavior: 'smooth' })
}, [messages])
const handleSubmit = (event: FormEvent) => {
event.preventDefault()
const text = input.trim()
if (!text || isBusy) return
sendMessage({ text }, { body: { locale } })
setInput('')
}
return (
<>
{!open && (
<button
type='button'
aria-label='Ask AI'
onClick={() => setOpen(true)}
className='fixed right-4 bottom-4 z-50 flex h-11 items-center gap-2 rounded-full border border-[var(--border-1)] bg-[var(--surface-5)] px-4 font-season text-[var(--text-base)] text-sm shadow-lg transition-colors hover:bg-[var(--surface-active)] dark:bg-[var(--surface-4)]'
>
<MessageCircle className='size-[16px] text-[var(--text-icon)]' />
Ask AI
</button>
)}
{open && (
<div className='fixed right-4 bottom-4 z-50 flex h-[600px] max-h-[calc(100vh-2rem)] w-[400px] max-w-[calc(100vw-2rem)] flex-col overflow-hidden rounded-xl border border-[var(--border-1)] bg-[var(--surface-5)] shadow-xl dark:bg-[var(--surface-4)]'>
<div className='flex items-center justify-between border-[var(--border-1)] border-b px-4 py-3'>
<span className='flex items-center gap-2 font-season text-[var(--text-base)] text-sm'>
<MessageCircle className='size-[16px] text-[var(--text-icon)]' />
Ask AI
</span>
<button
type='button'
aria-label='Close'
onClick={() => {
stop()
setOpen(false)
}}
className='flex size-7 items-center justify-center rounded-md text-[var(--text-icon)] transition-colors hover:bg-[var(--surface-active)]'
>
<X className='size-[16px]' />
</button>
</div>
<div ref={scrollRef} className='flex-1 space-y-4 overflow-y-auto px-4 py-4'>
{messages.length === 0 && (
<p className='text-[var(--text-muted)] text-sm'>
Ask anything about building, deploying, and managing AI agents in Sim.
</p>
)}
{messages.map((message, index) => {
const text = getText(message.parts)
// Only the in-progress (last) message should show the loading state.
const isStreaming = isBusy && index === messages.length - 1
const sources = message.role === 'assistant' ? getSources(message.parts) : []
return (
<div
key={message.id}
className={cn(
'flex flex-col gap-1',
message.role === 'user' ? 'items-end' : 'items-start'
)}
>
{message.role === 'user' ? (
<div className='max-w-[90%] whitespace-pre-wrap rounded-lg bg-[var(--surface-active)] px-3 py-2 text-[var(--text-base)] text-sm'>
{text}
</div>
) : (
<div className='max-w-[90%] text-[var(--text-base)] text-sm'>
{text ? (
<Streamdown className='space-y-2 text-sm leading-relaxed [&_a]:text-[var(--text-link)] [&_a]:underline [&_li]:my-0.5 [&_ol]:list-decimal [&_ol]:pl-5 [&_ul]:list-disc [&_ul]:pl-5'>
{text}
</Streamdown>
) : isStreaming ? (
'…'
) : sources.length === 0 ? (
<span className='text-[var(--text-muted)]'>No answer returned.</span>
) : null}
</div>
)}
{sources.length > 0 && (
<div className='flex max-w-[90%] flex-wrap gap-1.5'>
{sources.map((source) => (
<a
key={source.url}
href={source.url}
target='_blank'
rel='noopener noreferrer'
className='rounded-md border border-[var(--border-1)] px-2 py-0.5 text-[var(--text-muted)] text-xs transition-colors hover:bg-[var(--surface-active)]'
>
{source.title || source.url}
</a>
))}
</div>
)}
</div>
)
})}
{error && (
<p className='text-[var(--text-muted)] text-sm'>
Something went wrong. Please try again.
</p>
)}
</div>
<form
onSubmit={handleSubmit}
className='flex items-end gap-2 border-[var(--border-1)] border-t px-3 py-3'
>
<textarea
value={input}
onChange={(event) => setInput(event.target.value)}
onKeyDown={(event) => {
if (event.key === 'Enter' && !event.shiftKey) {
event.preventDefault()
handleSubmit(event)
}
}}
rows={1}
placeholder='Ask a question…'
className='max-h-32 flex-1 resize-none bg-transparent font-season text-[var(--text-base)] text-sm outline-none placeholder:text-[var(--text-muted)]'
/>
{isBusy ? (
<button
type='button'
aria-label='Stop'
onClick={() => stop()}
className='flex size-8 shrink-0 items-center justify-center rounded-lg bg-[var(--surface-active)] text-[var(--text-icon)]'
>
<Square className='size-[14px]' />
</button>
) : (
<button
type='submit'
aria-label='Send'
disabled={!input.trim()}
className='flex size-8 shrink-0 items-center justify-center rounded-lg bg-[var(--text-base)] text-[var(--surface-5)] transition-opacity disabled:opacity-40 dark:bg-[var(--text-base)]'
>
<ArrowUp className='size-[16px]' />
</button>
)}
</form>
</div>
)}
</>
)
}
+6 -1
View File
@@ -15,8 +15,11 @@
"format:check": "biome format ."
},
"dependencies": {
"@ai-sdk/openai": "2.0.107",
"@ai-sdk/react": "2.0.205",
"@sim/db": "workspace:*",
"@vercel/og": "^0.6.5",
"ai": "5.0.203",
"class-variance-authority": "^0.7.1",
"clsx": "^2.1.1",
"drizzle-orm": "^0.45.2",
@@ -31,9 +34,11 @@
"react": "19.2.4",
"react-dom": "19.2.4",
"shiki": "4.0.0",
"streamdown": "2.5.0",
"tailwind-merge": "^3.0.2",
"reactflow": "^11.11.4",
"framer-motion": "^12.5.0"
"framer-motion": "^12.5.0",
"zod": "^4.3.6"
},
"devDependencies": {
"@sim/tsconfig": "workspace:*",