RAG

Installation

bun add @strav/rag
bun strav install rag

Setup

1. Register RagManager

Using a service provider (recommended)

import { RagProvider } from '@strav/rag'

app.use(new RagProvider())

Manual setup

import RagManager from '@strav/rag'

app.singleton(RagManager)
app.resolve(RagManager)

2. Configure

import { env } from '@strav/kernel'

export default {
  default: env('RAG_DRIVER', 'pgvector'),
  prefix: env('RAG_PREFIX', ''),

  embedding: {
    provider: env('RAG_EMBEDDING_PROVIDER', 'openai'),
    model: env('RAG_EMBEDDING_MODEL', 'text-embedding-3-small'),
    dimension: 1536,
  },

  chunking: {
    strategy: 'recursive',
    chunkSize: 512,
    overlap: 64,
  },

  stores: {
    pgvector: {
      driver: 'pgvector',
    },

    memory: {
      driver: 'memory',
    },

    null: {
      driver: 'null',
    },
  },
}

3. Set environment variables

RAG_DRIVER=pgvector
RAG_EMBEDDING_PROVIDER=openai
RAG_EMBEDDING_MODEL=text-embedding-3-small
OPENAI_API_KEY=sk-...

4. Enable pgvector (if using PostgreSQL driver)

The pgvector extension must be available in your PostgreSQL installation. The driver creates the extension and table automatically on first use.

-- If not already enabled at the database level:
CREATE EXTENSION IF NOT EXISTS vector;

Retrievable mixin

import { BaseModel } from '@strav/database'
import { retrievable } from '@strav/rag'

class Article extends retrievable(BaseModel) {
  declare id: number
  declare title: string
  declare body: string
  declare status: string

  static tableName = 'articles'

  static retrievableAs() {
    return 'articles'
  }

  toRetrievableContent() {
    return ${this.title}\n\n${this.body}
  }

  toRetrievableMetadata() {
    return { source: 'articles', authority: 0.8 }
  }

  shouldBeRetrievable() {
    return this.status === 'published'
  }
}

import { compose } from '@strav/kernel'
import { searchable } from '@strav/search'

class Article extends compose(BaseModel, searchable, retrievable) {
  // Full-text search AND vector retrieval on the same model
}

retrievableAs

static retrievableAs() {
  return 'knowledge_base'
}

toRetrievableContent

toRetrievableContent() {
  return ${this.title}\n\n${this.body}
}

toRetrievableMetadata

toRetrievableMetadata() {
  return {
    source: 'regulations',
    authority: 0.95,
    domain: 'legal',
    createdAt: this.createdAt.toISOString(),
  }
}

shouldBeRetrievable

shouldBeRetrievable() {
  return this.status === 'published'
}

Chunking

Content is split into chunks before embedding. Each chunk becomes a separate vector in the store. The RAG package ships two chunking strategies:

Recursive (default)

Fixed-size

Splits by raw character count with overlap. Simpler and more predictable, but doesn't respect content structure.

chunking: {
  strategy: 'recursive',  // 'recursive' or 'fixed'
  chunkSize: 512,          // max characters per chunk
  overlap: 64,             // characters of overlap between chunks
}

Custom chunker

import type { Chunker, Chunk } from '@strav/rag'

class SentenceChunker implements Chunker {
  chunk(content: string): Chunk[] {
    const sentences = content.match(/[^.!?]+[.!?]+/g) ?? [content]
    let offset = 0
    return sentences.map((s, i) => {
      const chunk = {
        content: s.trim(),
        index: i,
        startOffset: offset,
        endOffset: offset + s.length,
      }
      offset += s.length
      return chunk
    })
  }
}

Vectorizing

Instance methods

const article = await Article.find(1)

// Chunk, embed, and store in the vector store
await article.vectorize()

// Remove all chunks for this instance from the vector store
await article.vectorRemove()

Bulk import

Import all records from the database into the vector store:

const count = await Article.importAll()     // default batch size: 100
const count = await Article.importAll(500)  // custom batch size

Collection management

// Create the vector collection (with configured dimension)
await Article.createVectorCollection()

// Flush all vectors (remove documents, keep collection)
await Article.flushVectors()

Retrieving

From a model

const result = await Article.retrieve('What is dependency injection?')

The result object:

{
  matches: [
    {
      id: '42_0',
      content: 'Dependency injection is a design pattern...',
      score: 0.92,
      similarity: 0.92,
      metadata: { source: 'articles', authority: 0.8, chunkIndex: 0 },
    },
    // ...
  ],
  query: 'What is dependency injection?',
  processingTimeMs: 45,
}

Retrieve options

const result = await Article.retrieve('PSD3 compliance requirements', {
  topK: 10,
  threshold: 0.7,
  filter: { domain: 'legal' },
  rerank: {
    similarityWeight: 0.6,
    authorityWeight: 0.2,
    recencyWeight: 0.2,
  },
})

Reranking

finalScore = similarity × similarityWeight
           + authority  × authorityWeight
           + recency    × recencyWeight

• similarity — cosine similarity from the vector store (0–1)
• authority — metadata.authority value (0–1). Set via toRetrievableMetadata()
• recency — time decay: 1 / (1 + ageDays/30). Uses metadata.createdAt

Results are re-sorted by composite score. This is designed for the Knowledge Currency Validator, which needs to rank grounding sources by both relevance and freshness.

Auto-vectorizing

Register event listeners so models are automatically vectorized on create/update and removed on delete:

Article.bootRetrieval('article')

Vectorization failures are silently caught — they should not break the event pipeline.

rag helper

import { rag } from '@strav/rag'

Ingesting content

Chunk, embed, and store content in one call:

const ids = await rag.ingest('knowledge_base', longDocument, {
  metadata: { source: 'wiki', authority: 0.9, createdAt: new Date().toISOString() },
  sourceId: 'doc-42',
})
// Returns array of generated chunk IDs

Per-call chunking overrides:

const ids = await rag.ingest('regulations', document, {
  chunkSize: 256,
  overlap: 32,
  strategy: 'fixed',
  metadata: { domain: 'regulatory', authority: 0.95 },
})

Retrieving content

const result = await rag.retrieve('What changed in PSD3?', {
  collection: 'regulations',
  topK: 5,
  threshold: 0.7,
  filter: { domain: 'regulatory' },
  rerank: {
    similarityWeight: 0.5,
    authorityWeight: 0.3,
    recencyWeight: 0.2,
  },
})

Removing content

// Remove specific chunks by ID
await rag.delete('knowledge_base', ['id-1', 'id-2'])

// Remove all chunks from a source (e.g., all chunks from document 42)
await rag.deleteBySource('knowledge_base', 'doc-42')

// Clear an entire collection
await rag.flush('knowledge_base')

Using the store directly

const store = rag.store()          // default store
const store = rag.store('memory')  // named store

// Low-level operations
await store.createCollection('my_index', 1536)
await store.upsert('my_index', documents)
const result = await store.query('my_index', queryVector, { topK: 5 })
await store.deleteCollection('my_index')

Collection prefix

RAG_PREFIX=dev_

Multiple stores

You can configure and use multiple stores simultaneously:

// Use a named store
const memStore = RagManager.store('memory')

// Or via the helper
rag.store('pgvector')

Custom driver

import { rag } from '@strav/rag'
import type { VectorStore } from '@strav/rag'

rag.extend('pinecone', (config) => {
  return new PineconeDriver(config)
})

interface VectorStore {
  readonly name: string
  createCollection(collection: string, dimension: number): Promise
  deleteCollection(collection: string): Promise
  upsert(collection: string, documents: VectorDocument[]): Promise
  delete(collection: string, ids: (string | number)[]): Promise
  deleteBySource(collection: string, sourceId: string | number): Promise
  flush(collection: string): Promise
  query(collection: string, vector: number[], options?: QueryOptions): Promise
}

Then set it as the driver in your config:

// config/rag.ts
export default {
  default: 'pinecone',
  stores: {
    pinecone: {
      driver: 'pinecone',
      apiKey: env('PINECONE_API_KEY', ''),
      environment: env('PINECONE_ENV', 'us-east-1-aws'),
    },
  },
}

CLI commands

The rag package provides two CLI commands (auto-discovered by the framework):

rag:ingest

Vectorize all records for a model into the vector store:

bun strav rag:ingest app/models/article.ts
bun strav rag:ingest app/models/article.ts --chunk 50

• --chunk — Records per batch (default: 100).

rag:flush

Remove all vectors from a model's collection:

bun strav rag:flush app/models/article.ts

Testing

.env.test
RAG_DRIVER=null

RAG_DRIVER=memory

Swap stores at runtime:

import RagManager, { MemoryDriver } from '@strav/rag'

RagManager.useStore(new MemoryDriver())

Drivers

pgvector

CREATE TABLE _strav_vectors (
  id BIGSERIAL PRIMARY KEY,
  collection VARCHAR(255) NOT NULL,
  source_id VARCHAR(255),
  content TEXT NOT NULL,
  metadata JSONB DEFAULT '{}',
  embedding vector(1536),
  created_at TIMESTAMPTZ DEFAULT NOW()  -- PostgreSQL syntax
);

Memory

const driver = new MemoryDriver()
await driver.upsert('test', documents)
const stored = driver.getCollection('test')
expect(stored.length).toBe(3)

Null

No-op driver. All writes are discarded, queries return empty results. Useful for disabling RAG in specific environments without code changes.

Architecture

RagProvider          →  registers RagManager singleton
RagManager           →  config loading, driver resolution, collection naming
VectorStore          →  interface implemented by drivers
rag helper           →  convenience API (ingest, retrieve, delete, flush)
retrievable() mixin  →  ORM integration (vectorize, vectorRemove, importAll)

1:N chunk handling

This makes re-vectorization on update idempotent and clean.