Settings

Settings provides the central configuration mechanism for the Ragfish Framework.

It allows you to configure the default components used by Ragfish, including the language model and embedding model.

By configuring these components through Settings, you can define your application's AI configuration in one place and allow Ragfish components to use the configured models.

Basic Configuration

A typical Ragfish application configures the language model and embedding model during application startup.

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

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

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

Language Model

Settings.llm defines the Large Language Model used by Ragfish for response generation.

For example, using OpenAI:

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

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

Once configured, framework components can use the configured LLM without requiring the model configuration to be passed into every operation.

Embedding Model

Settings.embedModel defines the embedding model used to convert text into vector representations.

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

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

The embedding model is used as part of the retrieval pipeline to represent knowledge and queries as vectors.

Settings in the Retrieval Pipeline

The language model and embedding model have different responsibilities within a Ragfish application.

  Settings
                    │
          ┌─────────┴─────────┐
          │                   │
          ▼                   ▼
      Settings.llm     Settings.embedModel
          │                   │
          ▼                   ▼
   Generate Response      Generate Vectors
                              │
                              ▼
                         Vector Store
                              │
                              ▼
                          Retrieval

The embedding model supports the retrieval process, while the language model generates the final response.

Using Settings with Chat

After configuring the required models, you can create a Chat instance.

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

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

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

const chat = new Chat({
  retriever
});

The Chat instance can then use the configured framework components as part of the request pipeline.

Centralized Configuration

Using a central Settings object provides several benefits.

Consistent Configuration

Framework components can use the same configured AI models.

Less Repetition

The same LLM or embedding configuration does not need to be repeatedly passed throughout the application.

Provider Independence

The core framework remains independent of a specific AI provider.

For example:

Settings.llm = new OpenAILLM(...);

The OpenAILLM implementation is provided by @ragfish/openai, while the Settings configuration mechanism belongs to @ragfish/core.

This separation keeps the framework modular and allows additional providers to integrate with the same core architecture.

Environment Variables

API credentials should be stored outside your source code.

For example:

OPENAI_API_KEY=your-api-key

Then use the environment variable when configuring the provider:

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

Avoid committing API keys directly to your source code or version control.

Application Startup

For larger applications, configure Settings during application initialization.

A recommended structure is:

src/
├── config/
│   └── ragfish.ts
├── assistants/
├── retrievers/
├── connectors/
└── index.ts

Create a configuration module:

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

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

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

Initialize the configuration when your application starts:

import { configureRagfish } from "./config/ragfish";

configureRagfish();

Keeping framework configuration separate from application logic makes larger projects easier to maintain.

Provider Architecture

Settings belongs to the core framework, while the actual AI provider implementations are provided through separate packages.

@ragfish/core
      │
      └── Settings
            │
            ├── llm
            │
            └── embedModel
                    │
                    ▼
              Provider Package
                    │
                    ▼
             AI Provider

This architecture allows Ragfish to support additional AI providers without changing the core configuration API.

Best Practices

When working with Settings:

1. Configure the framework during application startup.

2. Keep API credentials in environment variables.

3. Keep provider-specific configuration inside provider modules.

4. Avoid duplicating global configuration throughout your application.

5. Keep framework configuration separate from business logic.

Next Steps

Now that you understand how Ragfish configures its core AI components, continue to Assistant.