Upstash RAG Chat Component

Install the RAG Chat Component using your preferred package manager:

# Using npm
npm install @upstash/rag-chat-component

# Using pnpm
pnpm add @upstash/rag-chat-component

# Using yarn
yarn add @upstash/rag-chat-component

To make your data searchable by the RAG component, you must insert it into your Upstash Vector index using one of these methods:

1. Upstash Vector SDKs: Use the JavaScript or Python SDKs to programmatically insert data.
2. Upstash Vector UI: Manually upsert data or upload PDFs via the Data Browser Tab in the Upstash Console.
3. docs2vector tool: Use the docs2vector tool to ingest markdown documentation files into your index.

You can integrate the component using two methods. Because it is a client-side component, it must be used within a file containing the use client directive.

Method 1: Dedicated Component File (Recommended)

Create a separate file for the chat component to isolate the client-side logic, then import it into your server components.

Method 2: Direct Integration

Import and use ChatComponent directly in a client-side page.

// components/chat.tsx
"use client";

import { ChatComponent } from "@upstash/rag-chat-component";

export const Chat = () => {
  return <ChatComponent />;
};

// page.tsx
import { Chat } from "./components/chat";

export default function Home() {
  return (
    <>
      <Chat />
      <p>Home</p>
    </>
  );
}

To ensure the component's styles are correctly applied, you must add the component's path to the content array in your tailwind.config.ts file.

import type { Config } from "tailwindcss";

export default {
  content: ["./node_modules/@upstash/rag-chat-component/**/*.{js,mjs}"],
} satisfies Config;

To start the playground project locally, use your preferred package manager to run the development script. The playground is a Next.js application.

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

To start the development server for the Next.js example project, use your preferred package manager to run the dev script. The application will be available at http://localhost:3000.

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

The component requires several environment variables to connect to Upstash Vector, Redis (optional), and LLM providers.

Required:

• UPSTASH_VECTOR_REST_URL: Your Upstash Vector database URL.
• UPSTASH_VECTOR_REST_TOKEN: Your Upstash Vector database token.
• OPENAI_API_KEY: OpenAI API key (used for embeddings/logic).
• TOGETHER_API_KEY: Together AI API key for the LLM.

Optional:

• UPSTASH_REDIS_REST_URL & UPSTASH_REDIS_REST_TOKEN: Required if you want to enable persistent chat history.
• TOGETHER_MODEL: The specific Together AI model to use. Defaults to meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo.

UPSTASH_VECTOR_REST_URL=
UPSTASH_VECTOR_REST_TOKEN=

# Optional for persistent chat history
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=

OPENAI_API_KEY=

TOGETHER_API_KEY=

# Optional
TOGETHER_MODEL="deepseek-ai/DeepSeek-V3"

The component uses a Prompt function to generate the text sent to the LLM. By default, it uses DEFAULT_PROMPT, which instructs the AI to be a concise assistant and only use the provided context and chat history.

If you are implementing a custom backend or extending the component, you can define your own prompt function following the PromptParameters shape. The function receives question, chatMessages (the conversation history), and context (the retrieved RAG data).

type PromptParameters = {
	chatMessages?: string;
	question: string;
	context: string;
};

type Prompt = ({ question, chatMessages, context }: PromptParameters) => string;

// Example of a custom prompt implementation
const myCustomPrompt: Prompt = ({ context, question, chatMessages }) => {
  return `System: You are a helpful assistant.\nContext: ${context}\nUser: ${question}`;
};

The ChatComponent manages chat sessions and history using the following logic:

• Session Management: It uses localStorage to persist a chat_session_id. If no ID exists, it generates a new one (e.g., session_...).
• History Retrieval: On mount, the component calls getHistory(sessionId) to fetch and display previous messages.
• Clearing History: The component includes a 'Clear' button in the header that calls deleteHistory(sessionId) to wipe the current conversation.
• Streaming: AI responses are streamed using readStreamableValue from the ai/rsc package, providing a real-time typing effect.

If you encounter timeout issues when deploying on Vercel, increase the function execution time limit in your vercel.json to allow more time for RAG operations to complete.

{
  "functions": {
    "app/**/*": {
      "maxDuration": 30
    }
  }
}

The RedisHistory constructor accepts a RedisHistoryConfig object to initialize the connection to Redis.

Properties:

• config?: A RedisConfigNodejs object used to instantiate a new Redis client if no client is provided.
• client?: An existing instance of the @upstash/redis Redis client.

Error Condition: If both config and client are omitted, the constructor throws: "Redis message stores require either a config object or a pre-configured client."

type RedisHistoryConfig = {
	config?: RedisConfigNodejs;
	client?: Redis;
};

The RedisHistory class implements the BaseMessageHistory interface to provide persistent chat history using Redis. It allows you to store, retrieve, and delete chat messages associated with specific session IDs.

To use it, you must provide either a pre-configured @upstash/redis client or a RedisConfigNodejs configuration object in the constructor. If neither is provided, the class will throw an error.

import { Redis } from "@upstash/redis";
import { RedisHistory } from "./path-to-redis-history";

// Option 1: Using a config object
const history = new RedisHistory({
  config: {
    url: "UPSTASH_REDIS_REST_URL",
    token: "UPSTASH_REDIS_REST_TOKEN",
  }
});

// Option 2: Using a pre-configured client
const client = new Redis({ url: "...", token: "..." });
const history = new RedisHistory({ client });