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 }).