getting-started.md

Getting Started

Installation

bun add @gsrag/core @gsrag/providers @gsrag/storage @gsrag/readers @gsrag/shared @gsrag/contracts

Requirements: Bun >= 1.0, Node.js >= 18

Quick Start

import { GsRag } from "@gsrag/core";
import {
  OpenAICompletionAdapter,
  OpenAIEmbeddingAdapter,
} from "@gsrag/providers";
import { createLocalStorageRegistry } from "@gsrag/storage";

// 1. Create storage (local JSON files)
const storages = createLocalStorageRegistry({
  workingDirectory: "./rag-data",
});

// 2. Create providers
const providers = {
  completion: new OpenAICompletionAdapter({
    model: "gpt-4o-mini",
    apiKey: process.env.OPENAI_API_KEY!,
  }),
  embedding: new OpenAIEmbeddingAdapter({
    embeddingModel: "text-embedding-3-small",
    embeddingDimension: 1536,
    apiKey: process.env.OPENAI_API_KEY!,
  }),
};

// 3. Initialize the client
const gsrag = new GsRag({ providers, storages });
await gsrag.initialize();

// 4. Insert documents
await gsrag.insertDocuments({
  documents: [
    { content: "Ada Lovelace wrote the first algorithm.", filePath: "ada.txt" },
    { content: "Alan Turing proposed the Turing machine.", filePath: "turing.txt" },
  ],
});

// 5. Query
const result = await gsrag.query("Who contributed to computing?", {
  mode: "hybrid",
});
console.log(result.content);

// 6. Clean up
await gsrag.finalize();

Minimal Example (Ollama, local only)

import { GsRag, QueryParam } from "@gsrag/core";
import { OllamaCompletionAdapter, OllamaEmbeddingAdapter } from "@gsrag/providers";
import { createLocalStorageRegistry } from "@gsrag/storage";

const gsrag = new GsRag({
  providers: {
    completion: new OllamaCompletionAdapter({ model: "llama3.1" }),
    embedding: new OllamaEmbeddingAdapter({
      model: "llama3.1",
      embeddingModel: "nomic-embed-text",
      embeddingDimension: 768,
    }),
  },
  storages: createLocalStorageRegistry({ workingDirectory: "./rag-data" }),
});

await gsrag.initialize();
await gsrag.insertDocuments({
  documents: [{ content: "GsRag is a TypeScript RAG library.", filePath: "intro.txt" }],
});
const answer = await gsrag.query("What is GsRag?");
console.log(answer.content);
await gsrag.finalize();

Next Steps

• Configuration — All config options and env vars
• Providers — LLM provider setup details
• Storage — Backend setup (local, Postgres, Qdrant, Redis)
• Query — Query modes, parameters, streaming
• Document Pipeline — Ingestion, chunking, deletion
• Graph Admin — Knowledge graph CRUD
• Multi-Workspace — Workspace isolation
• Architecture — Package structure, data flow
• Advanced — Custom providers, pipeline internals