@tour-kit/ai API

import { AiChatProvider } from '@tour-kit/ai'

<AiChatProvider config={{ endpoint: '/api/chat' }}>
  {children}
</AiChatProvider>

import { AiChatContext } from '@tour-kit/ai'
type Value = React.ContextType<typeof AiChatContext> // AiChatContextValue | null

import { aiChatPanelVariants } from '@tour-kit/ai'

<div className={aiChatPanelVariants({ size: 'lg' })}>...</div>

import { createRateLimiter, SlidingWindowRateLimiter } from '@tour-kit/ai'

const limiter = createRateLimiter({ maxMessages: 10, windowMs: 60_000 })
if (!limiter.recordMessage()) showToast('Slow down')
const status = limiter.getStatus() // RateLimitStatus

import { createAnalyticsBridge } from '@tour-kit/ai'
import { useAnalytics } from '@tour-kit/analytics'

const { track } = useAnalytics()
const onEvent = createAnalyticsBridge({ track, prefix: 'ai_chat' })

<AiChatProvider config={{ endpoint: '/api/chat', onEvent }}>{children}</AiChatProvider>

import { assembleTourContext } from '@tour-kit/ai'

const ctx = assembleTourContext(tourState) // TourAssistantContext

interface AiChatConfig {
  endpoint: string
  chatId?: string
  tourContext?: boolean
  suggestions?: SuggestionsConfig
  persistence?: PersistenceConfig
  rateLimit?: ClientRateLimitConfig
  onEvent?(event: AiChatEvent): void
  strings?: Partial<AiChatStrings>
  errorMessage?: string
}

interface SuggestionsConfig {
  static?: string[]
  dynamic?: boolean
  cacheTtl?: number // default 60_000
}

type PersistenceConfig = 'local' | { adapter: PersistenceAdapter }

interface PersistenceAdapter {
  save(chatId: string, messages: UIMessage[]): Promise<void>
  load(chatId: string): Promise<UIMessage[] | null>
  clear(chatId: string): Promise<void>
}

interface ClientRateLimitConfig {
  maxMessages?: number // default 10
  windowMs?: number    // default 60_000
}

interface RateLimitStatus {
  canSend: boolean
  remaining: number
  resetInMs: number
}

interface AnalyticsBridgeConfig {
  track: (eventName: string, properties?: Record<string, unknown>) => void
  prefix?: string // default 'ai_chat'
}

interface AiChatStrings {
  placeholder: string
  send: string
  errorMessage: string
  emptyState: string
  stopGenerating: string
  retry: string
  title: string
  closeLabel: string
  ratePositiveLabel: string
  rateNegativeLabel: string
}

interface AiChatState {
  messages: UIMessage[]
  status: ChatStatus
  error: Error | null
  isOpen: boolean
}

type ChatStatus = 'ready' | 'submitted' | 'streaming' | 'error'

type AiChatEventType =
  | 'chat_opened'
  | 'chat_closed'
  | 'message_sent'
  | 'response_received'
  | 'suggestion_clicked'
  | 'message_rated'
  | 'error'

interface AiChatEvent {
  type: AiChatEventType
  data: Record<string, unknown>
  timestamp: Date
}

interface TourAssistantContext {
  activeTour: { id: string; name: string; currentStep: number; totalSteps: number } | null
  activeStep: { id: string; title: string; content: string } | null
  completedTours: string[]
  checklistProgress: { completed: number; total: number } | null
}

interface UseTourAssistantReturn extends UseAiChatReturn {
  isLoading: boolean
  suggestions: string[]
  askAboutStep(): void
  askForHelp(topic?: string): void
  tourContext: TourAssistantContext
}

import { createChatRouteHandler } from '@tour-kit/ai/server'

export const POST = createChatRouteHandler({
  model: 'openai/gpt-4o-mini',
  context: { strategy: 'context-stuffing', documents },
  instructions: { tone: 'friendly' },
  rateLimit: { identifier: (req) => req.headers.get('x-user-id') ?? 'anon' },
})

import {
  createRetriever,
  createRAGMiddleware,
  createInMemoryVectorStore,
  createAiSdkEmbedding,
  chunkDocument,
  chunkDocuments,
} from '@tour-kit/ai/server'

import { generateSuggestions, parseSuggestions } from '@tour-kit/ai/server'

import { createServerRateLimiter, createInMemoryRateLimitStore } from '@tour-kit/ai/server'

interface ChatRouteHandlerOptions {
  model: LanguageModel
  context: ContextConfig
  instructions?: InstructionsConfig
  rateLimit?: ServerRateLimitConfig
  beforeSend?(message): Promise<UIMessage | null> | UIMessage | null
  beforeResponse?(response): Promise<string> | string
  maxDuration?: number // default 30
  onEvent?(event: AiChatEvent): void | Promise<void>
}

type ContextConfig = ContextStuffingConfig | RAGConfig

interface ContextStuffingConfig {
  strategy: 'context-stuffing'
  documents: Document[]
}

interface RAGConfig {
  strategy: 'rag'
  documents: Document[]
  embedding: EmbeddingAdapter
  vectorStore?: VectorStoreAdapter
  topK?: number
  minScore?: number
  chunkSize?: number
  chunkOverlap?: number
  rerank?: { model: string; topN?: number }
}

interface InstructionsConfig {
  productName?: string
  productDescription?: string
  tone?: 'professional' | 'friendly' | 'concise'
  boundaries?: string[]
  custom?: string
  override?: boolean
}

interface ServerRateLimitConfig {
  maxMessages?: number
  windowMs?: number
  identifier: (req: Request) => string | Promise<string>
  store?: RateLimitStore
}

interface ServerRateLimitResult {
  allowed: boolean
  count: number
  limit: number
  remaining: number
  resetAt: number
}

interface RateLimitStore {
  increment(identifier: string, windowMs: number): Promise<{ count: number; resetAt: number }>
  check(identifier: string): Promise<{ count: number; resetAt: number }>
}

interface Document {
  id: string
  content: string
  metadata?: DocumentMetadata
}

interface DocumentMetadata {
  source?: string
  title?: string
  tags?: string[]
  [key: string]: unknown
}

interface RetrievedDocument extends Document {
  score: number
}

interface VectorStoreAdapter {
  name: string
  upsert(documents: Document[], embeddings: number[][]): Promise<void>
  search(embedding: number[], topK: number, minScore?: number): Promise<RetrievedDocument[]>
  delete(ids: string[]): Promise<void>
  clear(): Promise<void>
}

interface EmbeddingAdapter {
  name: string
  embed(text: string): Promise<number[]>
  embedMany(texts: string[]): Promise<number[][]>
  dimensions: number
}