Chat System

{
  "messages": [{
    "role": "user",
    "content": [
      { "type": "image", "image": "data:image/png;base64,..." },
      { "type": "text", "text": "Describe this image" }
    ]
  }]
}

{
  "messages": [{
    "role": "user",
    "content": "--- PDF Document: report.pdf ---\n[extracted text]\n--- End PDF ---\n\nSummarize this document"
  }],
  "pdfAttached": true
}

Client (useAIChat hook)
    |--- POST /api/ai/stream
    |    Body: { messages: [...], stream: true }
    |
    v
API Route (stream/route.ts)
    |--- 1. guardLLMChat()         → 404 if disabled
    |--- 2. getAuthUserId()        → 401 if unauthenticated
    |--- 3. ensureUserExists()     → Clerk ID → DB user ID
    |--- 4. checkRateLimit()       → 429/402 if exceeded
    |--- 5. checkUsageQuota()      → 402 if monthly quota exceeded
    |--- 6. deductCredits()        → 402 if insufficient
    |--- 7. Zod validation         → 400 if invalid
    |
    v
AI Service
    |--- resolveModelAlias()
    |--- createAIProvider()
    |--- streamResponse()
    |
    v
Provider API (OpenAI/Anthropic/Google/xAI)
    |
    v
SSE Stream (text/event-stream)
    |--- data: {"choices":[{"delta":{"content":"Hello"}}]}
    |--- data: {"choices":[{"delta":{"content":" world"}}]}
    |--- data: [DONE]
    |
    v
Client parses chunks → updates message state → renders in UI

{
  "messages": [
    { "role": "system", "content": "You are a helpful assistant" },
    { "role": "user", "content": "Explain React hooks" }
  ],
  "model": "claude",
  "temperature": 0.7,
  "maxTokens": 1000,
  "systemPrompt": "Optional system prompt",
  "context": "Optional context string"
}

const StreamRequestSchema = z.object({
  messages: z.array(
    z.object({
      role: z.enum(['system', 'user', 'assistant', 'function', 'tool']),
      content: z.union([z.string(), z.array(ContentPartSchema)]),
      name: z.string().optional(),
    })
  ),
  model: z.string().optional(),
  temperature: z.number().min(0).max(2).optional(),
  maxTokens: z.number().positive().optional(),
  systemPrompt: z.string().optional(),
  context: z.string().optional(),
})

{
  "messages": [{ "role": "user", "content": "What is Next.js?" }],
  "model": "gpt-5-mini",
  "temperature": 0.5
}

{
  "requests": [
    { "messages": [{ "role": "user", "content": "Question 1" }] },
    { "messages": [{ "role": "user", "content": "Question 2" }] }
  ],
  "parallel": true
}

export function useAIChat(options: UseAIChatOptions = {}) {
  const {
    api = '/api/ai/stream',
    initialMessages = [],
    onFinish,
    onError,
  } = options

'use client'

import { useAIChat } from '@/hooks/use-ai'

export function ChatPage() {
  const {
    messages,
    input,
    handleInputChange,
    handleSubmit,
    isLoading,
    error,
    stop,
    reload,
    clearMessages,
  } = useAIChat({
    api: '/api/ai/stream',
    onFinish: (message) => console.log('Done:', message.content),
    onError: (error) => console.error('Error:', error),
  })

  return (
    <form onSubmit={handleSubmit}>
      {messages.map((msg) => (
        <div key={msg.id}>{msg.content}</div>
      ))}
      <input value={input} onChange={handleInputChange} />
      <button type="submit" disabled={isLoading}>Send</button>
      {isLoading && <button onClick={stop}>Stop</button>}
    </form>
  )
}

/**
 * Single suggestion within a category
 */
export interface QuickPromptSuggestion {
  /** Unique identifier */
  id: string
  /** Short display label (max ~50 chars for UI) */
  label: string
  /** Full prompt text to be sent */
  prompt: string
}

/**
 * Category grouping related suggestions
 */
export interface QuickPromptCategory {
  /** Unique identifier */
  id: string
  /** Button label */
  label: string
  /** Lucide icon component */
  icon: LucideIcon
  /** List of suggestions in this category */
  suggestions: QuickPromptSuggestion[]
}

/**
 * Complete configuration for a chat type
 */
export interface QuickPromptConfig {
  chatType: 'llm' | 'rag'
  categories: QuickPromptCategory[]

Format 1: OpenAI-style delta
  data: {"choices":[{"delta":{"content":"token"}}]}

Format 2: OpenAI-style text
  data: {"choices":[{"text":"token"}]}

Format 3: Direct content
  data: {"content":"token"}

Format 4: Direct text
  data: {"text":"token"}

Format 5: Anthropic-style delta
  data: {"delta":{"text":"token"}}

Termination:
  data: [DONE]

Content-Type: text/event-stream
Cache-Control: no-cache, no-transform
Connection: keep-alive
X-Accel-Buffering: no

export function guardRAGChat(): NextResponse<FeatureDisabledError> | null {
  if (!isRAGChatEnabled()) {
    return createFeatureDisabledResponse('RAG Chat')
  }
  return null
}

/**
 * Guard for LLM Chat API routes
 *
 * Use at the start of:
 * - /api/ai/chat
 * - /api/ai/stream
 *
 * @returns NextResponse if feature disabled, null if enabled
 *
 * @example
 * export async function POST(request: Request) {
 *   const guard = guardLLMChat()
 *   if (guard) return guard
 *   // Feature is enabled, continue with handler
 * }
 */
export function guardLLMChat(): NextResponse<FeatureDisabledError> | null {
  if (!isLLMChatEnabled()) {
    return createFeatureDisabledResponse('LLM Chat')
  }
  return null
}