assistant-ui + Kontext SDK Starter

Production-ready AI chatbot with personalized responses powered by assistant-ui and Kontext SDK.

Features

• Beautiful UI built with assistant-ui composable primitives and shadcn/ui
• User-ID-first auth flow with short-lived Kontext tokens minted by your backend
• Personalized AI responses powered by Kontext profile + vault data (Gmail optional but supported)
• Production-ready with streaming, auto-scroll, and error handling
• Privacy-first design with user-controlled data and one-click disconnect
• Responsive design for desktop and mobile

Quick Start

Prerequisites

• Node.js 18+
• OpenAI API key
• Kontext API key (get yours at dashboard.kontext.dev)
• Local checkout of persona-builder/packages/kontext-sdk to link the latest SDK

Installation

# Clone the repository
git clone https://github.com/co-browser/assistant-ui-kontext-starter
cd assistant-ui-kontext-starter

# Install dependencies
npm install

# This repo links the SDK from ../persona-builder/packages/kontext-sdk
# adjust the path in package.json if your local checkout differs

# Copy environment variables
cp .env.example .env.local

Configuration

1. Add your API keys to .env.local:

# Kontext SDK
KONTEXT_API_KEY=ktextXXXXXXXXXXXXXXXX
KONTEXT_API_URL=https://api.kontext.dev
NEXT_PUBLIC_KONTEXT_API_URL=https://api.kontext.dev

# OpenAI
OPENAI_API_KEY=sk-XXXXXXXXXXXXXXXXXX

2. Configure allowed origins in your Kontext Dashboard:
   • Development: http://localhost:3000
   • Production: https://your-domain.com

Development

npm run dev

Open http://localhost:3000 to view the application.

How It Works

1. User identity: The app mints a UUID per visitor and stores it in a first-party cookie so both client and API routes can address the same Kontext user.
2. Token minting: /api/kontext/user-token exchanges your developer API key + user ID for a short-lived JWT; <KontextApp> refreshes it automatically in the browser.
3. Vault & profile: Gmail connection (optional) unlocks vault uploads plus profile enrichment; both surfaces consume the same tokenized Kontext client.
4. Personalized chat: The chat API requests a profile prompt via kontext.profile.getProfile, optionally scoped by the user’s latest message.
5. Privacy control: Users can refresh or disconnect Gmail at any time, clearing access while preserving their generated user ID.

Focused Retrieval (userQuery)

• What it does: Sends your latest message as userQuery so the backend retrieves turn-specific context (e.g., a clean, deduped list of projects/legal/docs) without changing your saved persona.
• When to enable: Targeted asks like “List all my projects/legal/docs/visa” or “Give exhaustive details on …”.
• When to disable: Open-ended chat, brainstorming, or when you want broader background context.
• Signals: Response headers show X-Kontext-UserQuery: 1|0 and X-Kontext-TurnContext: 1|0 for quick validation.

Project Structure

├── app/
│   ├── api/chat/route.ts       # AI endpoint with Kontext profile integration
│   ├── api/kontext/user-token/ # User-token minting endpoint (BFF)
│   ├── api/kontext/vault/      # Vault upload/search/status API routes
│   ├── assistant.tsx           # Main chat UI component
│   └── layout.tsx              # App layout (mints user IDs)
├── components/
│   ├── kontext-provider.tsx    # KontextApp wrapper with user-token endpoint
│   ├── kontext-header-status.tsx # Gmail/vault management affordances
│   └── assistant-ui/           # Chat UI components
├── hooks/
│   └── useKontextUserId.tsx    # Sync Kontext user ID cookies on the client
└── lib/
    ├── server-kontext.ts        # Helper to instantiate server-side Kontext client
    └── user-id.ts               # Ensures per-user UUID cookies

Customization

AI Provider

The starter is configured for OpenAI. To use another provider:

1. Install the provider package:

npm install @ai-sdk/anthropic

2. Update app/api/chat/route.ts:

import { anthropic } from "@ai-sdk/anthropic";

const result = streamText({
  model: anthropic("claude-3-sonnet"),
  messages: modelMessages,
});

Privacy Settings

Configure privacy levels in app/api/chat/route.ts:

const profile = await kontext.profile.getProfile({
  userId,
  task: "chat",
  privacyLevel: "strict", // Options: 'strict' | 'moderate' | 'none'
});

Styling

• Tailwind CSS v4 with PostCSS. Core imports live in app/globals.css (@import "tailwindcss";).
• Component styling follows shadcn/ui patterns in components/ui/*.
• Customize theme tokens and CSS variables in app/globals.css.
• PostCSS is configured in postcss.config.mjs.

Deployment

Vercel

Environment Variables

Configure these in your deployment platform:

Variable	Description
KONTEXT_API_KEY	Server-side Kontext API key
KONTEXT_API_URL	Kontext API base URL (use http://localhost:8000 for the local SDK)
NEXT_PUBLIC_KONTEXT_API_URL	Client-side Kontext API base URL
OPENAI_API_KEY	OpenAI API key

Other Platforms

This is a standard Next.js application and can be deployed to any platform that supports Node.js:

• Railway
• Render
• AWS Amplify
• Netlify
• Self-hosted

Documentation

• assistant-ui Documentation
• Kontext SDK Documentation
• Next.js Documentation
• Vercel AI SDK

Support

• assistant-ui Discord
• Kontext Support
• GitHub Issues

License

MIT

Contributing

Contributions are welcome. Please submit pull requests with:

• Clear description of changes
• Updated documentation
• Test coverage for new features