add-ai-tour-assistant

Add an AI tour assistant with @tour-kit/ai

Use @tour-kit/ai when the user wants a conversational AI layer that knows about their tour structure, current step, and product docs — so it can answer "where do I find X?" or "what does this button do?" mid-onboarding without breaking flow.

Two architectures supported:

• CAG (Context-Augmented Generation) — stuffs tour structure into the system prompt. Simple, no vector store needed.
• RAG (Retrieval-Augmented Generation) — embeds docs in a vector store; used when context exceeds prompt budget.

Install

pnpm add @tour-kit/ai

@tour-kit/ai ships both client (browser-safe) and server (Node-only) entry points. Server route handlers pull from @tour-kit/ai/server.

Minimal working example

1. Server route (Next.js App Router)

// app/api/chat/route.ts
import { createChatRoute } from '@tour-kit/ai/server'

export const POST = createChatRoute({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: 'claude-sonnet-4-6',
  systemPrompt: 'You are an onboarding guide for Acme Dashboard.',
})

2. Client provider + chat widget

'use client'
import { AiChatProvider, useAiChat, useTourAssistant } from '@tour-kit/ai'

export function ChatLayout({ children }) {
  return (
    <AiChatProvider config={{ endpoint: '/api/chat', tourContext: true }}>
      {children}
      <ChatWidget />
    </AiChatProvider>
  )
}

function ChatWidget() {
  const { messages, sendMessage, status } = useAiChat()
  const { tourContext } = useTourAssistant()
  // your UI here — render messages, input box, send button
}

The tourContext: true flag passes the current tour id and active step to every request, so the AI knows where the user is and can answer step-specific questions.

RAG mode (large doc sets)

import { createInMemoryVectorStore, createChatRoute } from '@tour-kit/ai/server'

const vectorStore = createInMemoryVectorStore({
  embeddings: yourDocs,
})

export const POST = createChatRoute({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  vectorStore,
  topK: 5,
})

Plug in a VectorStoreAdapter for Pinecone/Weaviate/etc.

Common follow-ups

Combine with @tour-kit/react

Wrap <TourProvider> inside <AiChatProvider> so the assistant sees tour state automatically.

Rate limiting

Built-in SlidingWindowRateLimiter (client) and createServerRateLimiter (server) — set requestsPerMinute in config.

Streaming responses

const { messages, sendMessage } = useAiChat()
sendMessage('How do I export data?', { stream: true })

Gotchas

• Server isolation: files in @tour-kit/ai/server must NOT be imported from client code — they reference Node APIs that break in the browser. The package enforces this at the entry-point level, but custom imports can still leak.
• API key handling: never expose ANTHROPIC_API_KEY to the client. The route handler is the only place it should appear.
• Context window: in CAG mode, large tour structures can blow the budget. Switch to RAG once tour content > ~10k tokens.
• Next.js App Router: AiChatProvider is client-only.

Reference

• Docs: https://usertourkit.com/docs/ai
• Anthropic SDK setup: https://docs.claude.com/api
• npm: https://www.npmjs.com/package/@tour-kit/ai