RAGChat exposes several useful methods:

MethodDescription
ragChat.chatautomatically retrieves relevant knowledge to include in LLM response
ragChat.contextaccess or modify your Vector DB
ragChat.historyaccess or modify your chat history

chat

The chat method enables conversations with a language model (LLM) using your vector database as a knowledge base and chat history.

Key Features:

  • Get LLM answers based on your knowledge base
  • Custom message history length
  • Supports streaming for a better UX
  • Customizable hooks for fine-grained control over the chat process
  • Optional pure LLM chat mode without RAG

Important Considerations:

  • Adjust similarityThreshold to fine-tune accuracy of results
  • Balance information: Too much context can lead to inaccuracies
  • Use historyLength and topK options to manage the amount of data fed to the LLM

Request

input
string
required

Question to ask your RAG chat

options
ChatOptions

Response

response
ChatReturnType

Usage Tips:

  • Adjust historyLength based on the complexity of your conversations
  • Use topK to control the number of relevant context items retrieved
  • Enable streaming for a better UX
  • Use the onContextFetched and onChatHistoryFetched hooks to inspect and modify data before it’s sent to the LLM
  • Set disableRAG to true when building custom pipelines or for simple LLM interactions

Example:

const chatResponse = await ragChat.chat({
  input: "What are the key features of our latest product?",
  options: {
    historyLength: 5,
    topK: 3,
    streaming: true,
    onContextFetched: (context) => {
      console.log("Retrieved context:", context)
      return context
    },
    metadata: { source: "product_inquiry" },
  },
})

if (chatResponse.isStream) {
  for await (const chunk of chatResponse.output) {
    console.log(chunk)
  }
} else {
  console.log(chatResponse.output)
}

context

Context describes the items retrieved from your vector database considered relevant for the current query. Add, delete or update data from your knowledge base:

MethodDescription
addadd various data types into a vector database.
addManyadd multiple pieces of data at once.
deleteremove data from your knowledge base
deleteEntireContextclears your entire knowledge base

add

The add method adds various types of context to your application. It supports multiple data formats, automatically handles text splitting, and simplifies adding and managing context.

Supported Data Types:

  • Plain text
  • Embeddings
  • PDF files
  • CSV files
  • Text files
  • HTML content (from files or URLs)

Key Features:

  • Automatic text splitting for PDF, CSV, and HTML input
  • Flexible configuration options for each data type
  • Support for both file and URL sources for HTML content

Request

payload
AddContextPayload

Response

response
SaveOperationResult

Usage Tips:

  • For large documents, consider using the PDF or text file options to use automatic text splitting.
  • When adding CSV data, use the csvConfig to specify which column to use and adjust the delimiter if necessary.
  • For web content, you can either specify an HTML file or a URL using the appropriate configuration.
  • Use the options parameter to fine-tune how the context is added and processed.

Example:

const result = await context.add({
  type: "pdf",
  fileSource: "./document.pdf",
  pdfConfig: { splitPages: true },
  options: { metadata: { source: "company_report" } },
})

if (result.success) {
  console.log(`Added ${result.ids.length} context items`)
} else {
  console.error(`Failed to add context: ${result.error}`)
}

addMany

The addMany method is an efficient way to add multiple contexts to your application in a single operation. It extends the capabilities of the add method to handle batch processing, making it ideal for large-scale data ingestion.

delete

The delete method allows you to remove one or more context items from your vector database. It provides an easy way to manage your knowledge base by deleting specific items or groups of items.

Key Features:

  • Supports deletion of a single item or multiple items in a single operation
  • Optional namespace specification for targeted deletion

Request

payload
DeleteContextPayload

Response

The method doesn’t return a value, but it’s asynchronous, so you should wait for it to finish.

Usage Tips:

  • Use a single ID string to delete a single item, or an array of ID strings for batch deletions
  • Specify a namespace when working with multiple indices to ensure you’re deleting from the correct one
  • Always wait for the delete operation to complete before proceeding with other operations.

Example:

// Deleting a single item
await context.delete({
  id: "item_123",
  namespace: "product_catalog",
})

// Deleting multiple items
await context.delete({
  id: ["item_456", "item_789", "item_101"],
  namespace: "customer_data",
})

deleteEntireContext

The deleteEntireContext method removes all knowledge base items, either for a single namespace or for all namespaces.

Key Features:

  • Clears your entire knowledge base
  • Optional: Specify a namespace for targeted deletion

Request

options
ResetOptions

Response

The method doesn’t return a value, but it’s asynchronous, so you should wait for it to complete.

Usage Tips:

  • Use this method with caution, as it will permanently delete all context items.
  • Specify a namespace if you only want to reset a specific part of your database.

Example:

// Resetting the entire vector database
await context.deleteEntireContext()
console.log("Entire context deleted successfully")

// Resetting a specific namespace
await context.deleteEntireContext({
  namespace: "temporary_data",
})

This operation is irreversible. Make sure you really want to delete all context items before you before calling this method. It’s recommended that you only use this method when you’re absolutely sure you want to delete all data.

history

The history feature allows you to manage your chat history. It provides methods to add, retrieve, and delete messages, giving you full control over the conversation data stored in your application.

In typical use, you won’t need to manipulate your chat history manually. However, having the ability to directly access and modify messages can be useful in certain scenarios.

Key Features:

  • Add individual messages to the chat history
  • Retrieve messages from the chat history
  • Delete specific messages or entire conversations
  • Support for multiple chat sessions
  • Optional time-to-live (TTL) for automatic session expiry

addMessage

The addMessage method allows you to add a new message to the chat history for a specific session.

Request

payload
HistoryAddMessage

Response

The method doesn’t return a value, but it’s asynchronous, so you should wait for it to complete.

Usage Tips:

  • Ensure the role is set to either “assistant” or “user”
  • Use the usage_metadata to track token usage if needed for your use case
  • Use unique session IDs to manage multiple concurrent conversations
  • Set a TTL for sessions that should automatically expire

Example:

await history.addMessage({
  message: {
    role: "user",
    content: "What's the weather like today?",
    metadata: {
      userLocation: "New York",
      timestamp: Date.now(),
    },
    usage_metadata: {
      input_tokens: 6,
      output_tokens: 0,
      total_tokens: 6,
    },
  },
  sessionId: "user_456_weather_chat",
  sessionTTL: 1800, // Session will expire after 30 minutes
})

deleteMessages

The deleteMessages method allows you to remove all messages associated with a specific chat session.

Request

payload
DeleteMessagesPayload

Response

The method doesn’t return a value, but it’s asynchronous, so you should wait for it to complete.

Usage Tips:

  • Use this method to clear the history of a specific chat session.
  • Be careful when using this method, as it will permanently delete all messages in the session.

Example:

const sessionIdToDelete = "user_789_support_chat"

await history.deleteMessages({ sessionId: sessionIdToDelete })

console.log(`All messages in session ${sessionIdToDelete} have been deleted`)

This operation is irreversible. Once messages are deleted, they cannot be recovered. Use this method carefully and implement safeguards in your application to prevent accidental data loss.

getMessages

The getMessages method retrieves several messages from a chat session’s history. It provides flexibility in selecting the range of messages to fetch and returns them in reverse chronological order (newest first).

Request

options
GetMessagesOptions

Response

messages
UpstashMessage[]

An array of UpstashMessage objects, where each object contains:

Usage Tips:

  • Use the sessionId parameter to retrieve messages from specific conversations
  • Adjust the amount parameter to control how many messages you want to fetch
  • Use the startIndex parameter to paginate through the chat history or fetch older messages
  • The returned messages are in reverse chronological order (newest first)
  • Each message includes an id field, which is generated based on its position in the chat history

Example:

const messages = await history.getMessages({
  sessionId: "user_123_support_chat",
  amount: 10,
  startIndex: 0,
})

console.log(`Retrieved ${messages.length} messages:`)
messages.forEach((msg) => {
  console.log(`${msg.role}: ${msg.content} (ID: ${msg.id})`)
})