docs: Ask AI chat grounded in the docs vector store

apps/docs/app/[lang]/layout.tsx

@@ -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 />
         </RootProvider>
       </body>
     </html>

apps/docs/app/api/chat/route.ts

@@ -0,0 +1,142 @@
+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
+
+/**
+ * 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; durable per-IP rate limiting, a provider spend cap, and
+ * edge bot protection are provisioned separately (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
+
+/** 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') total += part.text.length
+    }
+  }
+  return total
+}
+
+/**
+ * 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
+  } catch {
+    return false
+  }
+
+  const requestHost = req.headers.get('x-forwarded-host') ?? req.headers.get('host')
+  if (originHost === requestHost) return true
+
+  const allowlist = (process.env.DOCS_ALLOWED_ORIGINS ?? '')
+    .split(',')
+    .map((value) => value.trim())
+    .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.`
+
+/**
+ * Vector search over the docs embeddings, returning the most relevant chunks
+ * with their source links so the model can ground and cite its answer.
+ */
+async function searchDocs(query: string) {
+  const embedding = await generateSearchEmbedding(query)
+  const vectorLiteral = JSON.stringify(embedding)
+
+  const rows = await db
+    .select({
+      title: docsEmbeddings.headerText,
+      url: docsEmbeddings.sourceLink,
+      content: docsEmbeddings.chunkText,
+      similarity: sql<number>`1 - (${docsEmbeddings.embedding} <=> ${vectorLiteral}::vector)`,
+    })
+    .from(docsEmbeddings)
+    .orderBy(sql`${docsEmbeddings.embedding} <=> ${vectorLiteral}::vector`)
+    .limit(SEARCH_LIMIT)
+
+  return rows.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 { messages }: { messages: UIMessage[] } = await req.json()
+
+  if (!Array.isArray(messages) || messages.length === 0 || messages.length > MAX_MESSAGES) {
+    return new Response('Invalid request', { status: 400 })
+  }
+  if (userInputChars(messages) > MAX_USER_INPUT_CHARS) {
+    return new Response('Request too large', { status: 413 })
+  }
+
+  const result = streamText({
+    model: openai(CHAT_MODEL),
+    system: SYSTEM_PROMPT,
+    messages: convertToModelMessages(messages),
+    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),
+      }),
+    },
+  })
+
+  return result.toUIMessageStreamResponse()
+}

apps/docs/components/ai/ask-ai.tsx

@@ -0,0 +1,195 @@
+'use client'
+
+import { type FormEvent, useEffect, 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('')
+}
+
+export function AskAI() {
+  const [open, setOpen] = useState(false)
+  const [input, setInput] = useState('')
+  const scrollRef = useRef<HTMLDivElement>(null)
+
+  const { messages, sendMessage, status, stop, error } = useChat({
+    transport: new DefaultChatTransport({ api: '/api/chat' }),
+  })
+
+  const isBusy = status === 'submitted' || status === 'streaming'
+
+  useEffect(() => {
+    scrollRef.current?.scrollTo({ top: scrollRef.current.scrollHeight, behavior: 'smooth' })
+  }, [messages, open])
+
+  const handleSubmit = (event: FormEvent) => {
+    event.preventDefault()
+    const text = input.trim()
+    if (!text || isBusy) return
+    sendMessage({ text })
+    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={() => 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) => {
+              const text = getText(message.parts)
+              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>
+                      ) : isBusy ? (
+                        '…'
+                      ) : 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}
+                          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>
+      )}
+    </>
+  )
+}

apps/docs/package.json

@@ -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:*",