Overview

The @talosjs/rag package is a Retrieval-Augmented Generation toolkit. It turns your documents into searchable knowledge: extract PDFs to Markdown with automatic OCR fallback, embed the content via OpenRouter, store it in a LanceDB vector database, and retrieve the most relevant passages with hybrid search. You define a typed vector database class, open a table, add records, and search. Every record carries an id, the searchable text, and a metadata object of your own typed fields.

What the package gives you

Retrieval is hybrid: full-text and vector search run together and are merged with RRF reranking, so you get both keyword precision and semantic recall. The metadata shape you declare drives the types for records, filters, and selected fields, so a wrong field name or value type fails to compile. The RAG class handles the ingest side, extracting a PDF to Markdown and OCR’ing any page that needs it. Storage is local: LanceDB keeps vectors on disk, with no separate database server to run. Filters combine field conditions with AND, OR, and NOT to narrow results, and databases register with a decorator so you can resolve them from the DI container.

The building blocks

Block	What it is	Page
Vector Database	A typed class describing where data lives, which embedding model to use, and the schema.	Vector Database
Vector Table	The handle you add records to, look them up, and index.	Vector Table
PDF Extraction	Extracts PDFs to Markdown with automatic OCR fallback for scanned pages.	PDF Extraction
Embeddings	The OpenRouter models that turn `text` into vectors.	Embeddings
Search	Hybrid full-text + vector search with RRF reranking.	Search
Filtering	Composable conditions to scope queries.	Filtering

Installation

bun add @talosjs/rag

Embeddings are generated through OpenRouter, so set your API key in the environment:

OPENROUTER_API_KEY=sk-or-...

The record shape

Every row in a table has the same three top-level fields:

{
  id: string;        // your identifier
  text: string;      // the content that gets embedded and full-text indexed
  metadata: { ... }; // your custom, typed fields used for filtering and selection
}

You describe metadata with a DataType and the database carries it through everywhere — added records, search results, filters, and selected columns are all typed against it.

End-to-end example

import { AbstractVectorDatabase } from "@talosjs/rag";
import type { EmbeddingModelType, FieldValueType } from "@talosjs/rag";
import { Utf8 } from "apache-arrow";

type ArticleData = {
  metadata: {
    title: string;
    category: string;
  };
};

class ArticleVectorDatabase extends AbstractVectorDatabase<ArticleData> {
  public constructor(embeddingModel: EmbeddingModelType = { model: "qwen3-embedding-8b" }) {
    super(embeddingModel);
  }

  public getDatabaseUri = (): string => "./data/articles.lance";

  public getSchema = (): { [K in keyof ArticleData]: FieldValueType } => ({
    metadata: new Utf8(),
  });
}

// Connect and open a table (created with indexes on first open).
const db = new ArticleVectorDatabase();
await db.connect();
const table = await db.open("articles");

// Add records.
await table.add([
  {
    id: "1",
    text: "An introduction to retrieval-augmented generation systems.",
    metadata: { title: "RAG Intro", category: "AI" },
  },
  {
    id: "2",
    text: "How vector databases store and search embeddings.",
    metadata: { title: "Vector DBs", category: "Database" },
  },
]);

// Search: hybrid full-text + vector, with an optional filter.
const results = await table.search("retrieval augmented generation", {
  limit: 5,
  select: ["title", "category"],
  filter: { field: "category", op: "=", value: "AI" },
});

How retrieval works

When you call search(), the table:

Runs a vector search over the embedded text and a full-text search over the same column.
Merges both result sets with an RRF reranker (Reciprocal Rank Fusion).
Applies your filter and select, then returns the top limit records, typed against your metadata.

This hybrid approach catches results that pure keyword search misses (semantic matches) and results that pure vector search ranks poorly (exact terms, names, codes).

Tables are created with three indexes on first open(): a btree index on id, a full-text (FTS) index on text, and an IVF-PQ vector index on vector, so search stays fast from the start. See Vector Database for details.

Getting Started

AI

Framework

Command Line

What the package gives you

The building blocks

Installation

The record shape

End-to-end example

How retrieval works

​What the package gives you

​The building blocks

​Installation

​The record shape

​End-to-end example

​How retrieval works

What the package gives you

The building blocks

Installation

The record shape

End-to-end example

How retrieval works