Retrieval & Context

import {
  buildRAGContext,
  createHeuristicRAGReranker,
  createRAGCollection,
  ingestRAGDocuments,
  openaiEmbeddings,
  searchDocuments
} from '@absolutejs/rag';
import { createSQLiteRAGStore } from '@absolutejs/rag-sqlite';

const collection = createRAGCollection({
  embedding: openaiEmbeddings({
    apiKey: process.env.OPENAI_API_KEY ?? '',
    defaultModel: 'text-embedding-3-small',
    dimensions: 1536
  }),
  rerank: createHeuristicRAGReranker(),
  store: createSQLiteRAGStore({ dimensions: 1536, path: './rag.sqlite' })
});

await ingestRAGDocuments(collection, {
  documents: [
    {
      id: 'release-notes',
      source: 'docs/releases.md',
      text: 'Hybrid retrieval fuses lexical and vector results...',
      title: 'Release Notes'
    }
  ]
});

// topK defaults to 6. Candidates over-fetch at topK * 4 whenever a
// reranker, query transform, or non-vector mode is active.
const hits = await searchDocuments(collection, {
  query: 'What changed in the latest release?',
  retrieval: 'hybrid',
  topK: 5
});

// Numbered "[1] Release Notes (docs/releases.md)" context blocks
// plus citation guidance, ready to drop into a prompt.
const context = buildRAGContext(hits);

import { fuseRAGQueryResults, searchDocuments } from '@absolutejs/rag';

// A mode string picks the defaults; an options object tunes fusion.
const results = await searchDocuments(collection, {
  query: 'quarterly revenue by region',
  retrieval: {
    diversityStrategy: 'mmr', // default 'none'
    fusion: 'rrf', // 'rrf' | 'max'
    fusionConstant: 60, // default 60
    lexicalWeight: 2, // default 2
    mmrLambda: 0.7, // default 0.7
    mode: 'hybrid', // 'vector' | 'lexical' | 'hybrid'
    sourceBalanceStrategy: 'round_robin', // default 'cap'
    vectorWeight: 1 // default 1
  },
  topK: 8
});

// The fusion primitive is exported for custom pipelines : reciprocal
// rank fusion (weight / (constant + rank)) or weighted max-score.
const fused = fuseRAGQueryResults({
  fusion: 'rrf',
  lexical: lexicalResults,
  lexicalWeight: 2,
  vector: vectorResults,
  vectorWeight: 1
});

import {
  createCohereRAGReranker,
  createHeuristicRAGQueryTransform,
  createHeuristicRAGRetrievalStrategy,
  createRAGCollection,
  createVoyageRAGReranker
} from '@absolutejs/rag';

const collection = createRAGCollection({
  embedding,
  // Heuristic variant expansion runs before retrieval; bring your own
  // model-backed transform via createRAGQueryTransform({ transform }).
  queryTransform: createHeuristicRAGQueryTransform(),
  // Hosted cross-encoders : Cohere rerank-v3.5, Voyage rerank-2, or
  // Jina jina-reranker-v2-base-multilingual by default.
  rerank: createCohereRAGReranker({
    apiKey: process.env.COHERE_API_KEY ?? ''
  }),
  // Routes scoped queries to vector, support-style queries to
  // lexical, and exact-phrase / source-native queries to hybrid.
  retrievalStrategy: createHeuristicRAGRetrievalStrategy(),
  store
});

// Per-search overrides win over the collection defaults.
await collection.search({
  query: 'refund policy for enterprise contracts',
  rerank: createVoyageRAGReranker({
    apiKey: process.env.VOYAGE_API_KEY ?? ''
  }),
  topK: 6
});

// The contract every backend implements (@absolutejs/rag/adapter-kit).
// embed, query, and upsert are required; every optional member
// unlocks a capability when present.
type RAGVectorStore = {
  embed: (input: RAGEmbeddingInput) => Promise<number[]>;
  query: (input: RAGQueryInput) => Promise<RAGQueryResult[]>;
  queryLexical?: (input: RAGLexicalQueryInput) => Promise<RAGQueryResult[]>;
  count?: (input?: RAGVectorCountInput) => Promise<number>;
  delete?: (input?: RAGVectorDeleteInput) => Promise<number>;
  analyze?: () => Promise<void> | void;
  rebuildNativeIndex?: () => Promise<void> | void;
  upsert: (input: RAGUpsertInput) => Promise<void>;
  clear?: () => Promise<void> | void;
  close?: () => Promise<void> | void;
  getStatus?: () => RAGVectorStoreStatus;
  getCapabilities?: () => RAGBackendCapabilities;
};

// A minimal custom store built on the adapter-kit vector helpers.
import {
  createRAGVector,
  normalizeVector,
  querySimilarity
} from '@absolutejs/rag/adapter-kit';

const memory = new Map<string, { embedding: number[]; text: string }>();

const demoStore: RAGVectorStore = {
  embed: async ({ text }) => normalizeVector(createRAGVector(text, 24)),
  query: async ({ queryVector, topK }) =>
    [...memory.entries()]
      .map(([chunkId, row]) => ({
        chunkId,
        chunkText: row.text,
        score: querySimilarity(queryVector, row.embedding)
      }))
      .sort((left, right) => right.score - left.score)
      .slice(0, topK),
  upsert: async ({ chunks }) => {
    for (const chunk of chunks) {
      memory.set(chunk.chunkId, {
        embedding: chunk.embedding ?? [],
        text: chunk.text
      });
    }
  }
};

// Postgres (pgvector) : table rag_chunks, hnsw index by default
import { createPostgresRAG } from '@absolutejs/rag-postgres';

const { collection, store } = createPostgresRAG({
  storeOptions: {
    connectionString: process.env.DATABASE_URL,
    dimensions: 1536,
    distanceMetric: 'cosine', // 'cosine' | 'l2' | 'inner_product'
    indexType: 'hnsw' // 'none' | 'hnsw' | 'ivfflat'
  }
});

// SQLite : JSON fallback everywhere, native vec0 when available
import { createSQLiteRAG } from '@absolutejs/rag-sqlite';

const sqlite = createSQLiteRAG({
  storeOptions: {
    dimensions: 1536,
    native: { mode: 'vec0' }, // loads the platform vec0 extension
    path: './rag.sqlite'
  }
});
sqlite.getNativeSupport(); // resolution, nativeActive, actionableMessage

// Pinecone : serverless index, provision + connect
import {
  createPineconeRAG,
  ensurePineconeIndex
} from '@absolutejs/rag-pinecone';

await ensurePineconeIndex({
  dimensions: 1536,
  indexName: 'docs',
  waitUntilReady: true
});

const pinecone = createPineconeRAG({
  indexName: 'docs', // apiKey falls back to PINECONE_API_KEY
  namespace: 'production',
  vector: { dimensions: 1536, distanceMetric: 'cosine', provider: 'pinecone' }
});