Your First AI Assistant

In this tutorial, you'll build your first AI Assistant using the Ragfish Framework.

You'll learn how to:

1. Configure an AI provider

2. Configure an embedding model

3. Connect a vector store

4. Create a retriever

5. Build a chat interface

6. Ask questions using your knowledge base

By the end of this guide, you'll have a working AI assistant that understands your documents and generates context-aware responses.

How Ragfish Works

Before writing any code, it's important to understand the request flow.

When a user asks a question, Ragfish performs the following steps automatically.

User Question
      │
      ▼
Generate Embedding
      │
      ▼
Search Vector Store
      │
      ▼
Retrieve Relevant Chunks
      │
      ▼
Generate Prompt
      │
      ▼
Large Language Model
      │
      ▼
AI Response

The Chat class orchestrates this entire workflow.

Step 1 - Import Required Packages

Import the core framework, AI provider, and vector store.

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

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

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

Step 2 - Configure the Language Model

Configure the default Large Language Model.

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

Every chat request will use this language model unless another model is explicitly specified.

Step 3 - Configure the Embedding Model

Configure the embedding model used for semantic search.

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

The embedding model converts text into vectors that can be searched efficiently.

Step 4 - Connect to a Vector Store

Create a connection to your vector database.

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

The vector store contains embeddings generated from your knowledge base.

Step 5 - Create a Retriever

The retriever searches your vector database for relevant information.

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

The retriever determines which document chunks are sent to the language model.

Step 6 — Create a Chat Instance

Create the chat engine.

const chat = new Chat({
    retriever
});

The Chat class coordinates retrieval, prompt construction, and response generation.

Step 7 - Ask Your First Question

You can now ask questions using natural language.

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

console.log(response);

The response returned by chat.message() is generated using both your knowledge base and the configured language model.

Complete Example

The following example combines all previous steps into a single application.

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

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

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

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 Happens Behind the Scenes?

When chat.message() is called, Ragfish executes the following pipeline:

1. Converts the user's question into an embedding.

2. Searches the vector store for similar content.

3. Retrieves the most relevant document chunks.

4. Builds a prompt using the retrieved context.

5. Sends the prompt to the configured language model.

6. Returns the generated response.

This orchestration is handled automatically by the framework.

Next Steps

Congratulations! 🎉

You've successfully built your first AI assistant with Ragfish.

In the next section, you'll explore the Core Framework , where you'll learn how the framework works internally.

1. Framework Architecture

2. Global Settings

3. Chat Engine

4. Assistant API

5. Ingestion Pipeline

6. Chunking Strategies

7. Retrieval System

8. Type Definitions

9. Error Handling

Understanding these core components will help you build more advanced, scalable, and production-ready AI applications using Ragfish.