Quick Start

This guide walks you through building your first AI assistant with Ragfish.

In just a few steps, you'll configure an AI model, connect a vector store, create a retriever, and start asking questions using your knowledge base.

By the end of this guide, you'll understand the basic building blocks of every Ragfish application.

Before You Begin

Make sure you have completed the following:

1. Installed @ragfish/core

2. Installed an AI provider (for example, @ragfish/openai)

3. Installed a vector store (for example, @ragfish/qdrant)

4. Installed Node.js 20 or later

If you haven't completed these steps, refer to the Installation guide first.

Step 1 - Configure Your AI Provider

Ragfish uses the global Settings object to configure the default Large Language Model (LLM) and embedding model used throughout your application.

Configure the language model.

import { Settings } from "@ragfish/core";
import { OpenAILLM } from "@ragfish/openai";

Settings.llm = new OpenAILLM({
    apiKey: process.env.OPENAI_API_KEY,
    model: "gpt-4o"
});

Step 2 - Configure the Embedding Model

Embeddings convert text into vectors that can be stored and searched efficiently.

import { OpenAIEmbedding } from "@ragfish/openai";

Settings.embedModel = new OpenAIEmbedding({
    apiKey: process.env.OPENAI_API_KEY,
    model: "text-embedding-3-small"
});

Step 3 - Connect a Vector Store

Create a connection to your vector database.

import { QdrantVectorStore } from "@ragfish/qdrant";

const vectorStore = new QdrantVectorStore({
    url: process.env.QDRANT_URL,
    apiKey: process.env.QDRANT_API_KEY
});

The vector store is responsible for storing and searching document embeddings.

Step 4 - Create a Retriever

The retriever searches the vector database and returns the most relevant information for each question.

import { QdrantRetriever } from "@ragfish/qdrant";

const retriever = new QdrantRetriever({
    vectorStore,
    collectionName: "knowledge"
});

Step 5 - Create a Chat Instance

Create a chat engine using the retriever.

import { Chat } from "@ragfish/core";

const chat = new Chat({
    retriever
});

The chat class orchestrates the retrieval pipeline and generates responses using the configured language model.

Step 6 - Ask Your First Question

You're now ready to interact with your AI assistant.

const response = await chat.message(
    "What is Ragfish?"
);

console.log(response);

When a question is submitted, Ragfish performs the following steps:

1. Converts the question into an embedding.

2. Searches the vector database for relevant content.

3. Retrieves the most relevant chunks.

4. Sends the retrieved context to the language model.

5. Generates a context-aware response.

How Ragfish Works

The following diagram illustrates the complete request pipeline.

User Question
      │
      ▼
 Embedding Model
      │
      ▼
 Vector Search
      │
      ▼
 Retrieved Context
      │
      ▼
 Large Language Model
      │
      ▼
 AI Response

This pipeline is managed automatically by the Chat class, allowing you to focus on your application rather than the underlying orchestration.

Complete Example

A minimal Ragfish application looks like this:

import { Chat, Settings } from "@ragfish/core";
import { OpenAILLM, OpenAIEmbedding } from "@ragfish/openai";
import { QdrantVectorStore, QdrantRetriever } from "@ragfish/qdrant";

Settings.llm = new OpenAILLM({
    apiKey: process.env.OPENAI_API_KEY
});

Settings.embedModel = new OpenAIEmbedding({
    apiKey: process.env.OPENAI_API_KEY
});

const vectorStore = new QdrantVectorStore({
    url: process.env.QDRANT_URL,
    apiKey: process.env.QDRANT_API_KEY
});

const retriever = new QdrantRetriever({
    vectorStore,
    collectionName: "knowledge"
});

const chat = new Chat({
    retriever
});

const response = await chat.message(
    "What is Ragfish?"
);

console.log(response);

What's Next?

Congratulations! You've built your first Ragfish-powered AI assistant.

In the next guide, you'll learn how to organize your application using the recommended Project Structure , making it easier to manage assistants, connectors, retrievers, and knowledge sources as your application grows.