Skip to content
Retrieval SDK
Esc
↑↓navigate↵open⌘Jpreview
On this page

Providers

Connect embedding models, rerankers and databases. Built-in adapters cover the AI SDK, Cohere, pgvector, Qdrant and Elasticsearch.

Each adapter is its own import path, so you only bundle what you use. Database clients are optional peer dependencies. Adapters that wrap a client expose it as raw.

AI SDK

Any AI SDK embedding or reranking model works. Install ai and a provider.

import { fromAIEmbedding, fromAIReranking } from "retrieval-sdk/ai";
import { openai } from "@ai-sdk/openai";
import { cohere } from "@ai-sdk/cohere";

const embedder = fromAIEmbedding(
  openai.embeddingModel("text-embedding-3-small")
);
const reranker = fromAIReranking(cohere.reranking("rerank-v3.5"));

Some models embed questions and documents differently. Pass provider options per kind:

const embedder = fromAIEmbedding(cohere.embedding("embed-v4.0"), {
  query: { cohere: { inputType: "search_query" } },
  document: { cohere: { inputType: "search_document" } },
});

Cohere

Direct calls to the Cohere API, no extra dependency. Reads COHERE_API_KEY unless you pass apiKey.

import { cohereEmbedder, cohereReranker } from "retrieval-sdk/cohere";

const embedder = cohereEmbedder({ model: "embed-v4.0" }); // queries and documents get the right input_type
const reranker = cohereReranker({ model: "rerank-v3.5" });

pgvector

Works with any client that has a pg-style query method (pg.Pool, pg.Client, Neon…). Scores are cosine similarity.

create extension if not exists vector;
create table retrieval_vectors (id text primary key, embedding vector(1536) not null);
create index on retrieval_vectors using hnsw (embedding vector_cosine_ops);
import { pgvector } from "retrieval-sdk/pgvector";
import { Pool } from "pg";

const store = pgvector({
  client: new Pool({ connectionString: process.env.DATABASE_URL }),
  table: "retrieval_vectors",
  dimensions: 1536,
});

Qdrant

Use a collection with Cosine or Dot distance. Qdrant only accepts integer or UUID point ids, so each document id is hashed to a stable UUID and kept in the payload as id.

import { qdrant } from "retrieval-sdk/qdrant";
import { QdrantClient } from "@qdrant/js-client-rest";

const store = qdrant({
  client: new QdrantClient({ url: "http://localhost:6333" }),
  collection: "docs",
});

Elasticsearch

An Index, not a vector store: Elasticsearch ranks with its own BM25 match query. Use it anywhere you would use bm25().

import { elasticsearch } from "retrieval-sdk/elasticsearch";
import { Client } from "@elastic/elasticsearch";

const lexical = elasticsearch({
  client: new Client({ node: "http://localhost:9200" }),
  index: "docs",
});

Your own

Each contract is one or three methods:

import type { Embedder, Reranker, VectorStore } from "retrieval-sdk";

const embedder: Embedder = {
  maxBatchSize: 96, // optional, the SDK splits bigger inputs
  async embed(texts, { kind, abortSignal }) {
    return myModel.embed(texts, kind); // one vector per text, same order
  },
};

const reranker: Reranker = {
  async rerank(query, texts, { topK }) {
    return myReranker.rank(query, texts, topK); // [{ index, score }], best first
  },
};

A VectorStore has upsert(records), remove(ids) and query(vector, { topK }).

Was this page helpful?