@strav/rag 1.0.0-alpha.28 → 1.0.0-alpha.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/rag",
-  "version": "1.0.0-alpha.28",
+  "version": "1.0.0-alpha.30",
   "description": "Strav RAG module — vector store abstraction, pgvector + in-memory drivers, chunking strategies. Composes with @strav/brain for embeddings and @strav/database for persistence.",
   "type": "module",
   "main": "./src/index.ts",
@@ -19,10 +19,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@strav/brain": "1.0.0-alpha.28",
-    "@strav/cli": "1.0.0-alpha.28",
-    "@strav/database": "1.0.0-alpha.28",
-    "@strav/kernel": "1.0.0-alpha.28"
+    "@strav/brain": "1.0.0-alpha.30",
+    "@strav/cli": "1.0.0-alpha.30",
+    "@strav/database": "1.0.0-alpha.30",
+    "@strav/kernel": "1.0.0-alpha.30"
   },
   "peerDependencies": {
     "@types/bun": ">=1.3.14"

package/src/console/index.ts

@@ -1,3 +1,4 @@
 export { RagConsoleProvider } from './rag_console_provider.ts'
 export { RagFlush } from './rag_flush.ts'
 export { RagList } from './rag_list.ts'
+export { RagReindex } from './rag_reindex.ts'

package/src/console/rag_console_provider.ts

@@ -10,8 +10,9 @@
 import { ConsoleProvider } from '@strav/cli'
 import { RagFlush } from './rag_flush.ts'
 import { RagList } from './rag_list.ts'
+import { RagReindex } from './rag_reindex.ts'
 
 export class RagConsoleProvider extends ConsoleProvider {
   override readonly name = 'console.rag'
-  override readonly commands = [RagFlush, RagList] as const
+  override readonly commands = [RagFlush, RagList, RagReindex] as const
 }

package/src/console/rag_flush.ts

@@ -19,14 +19,14 @@ import { RagManager } from '../rag_manager.ts'
 
 export class RagFlush extends Command {
   static signature = 'rag:flush {collection} {--store=} {--force}'
-  static description = 'Delete every vector in a collection (on the active or --store= named store).'
+  static description =
+    'Delete every vector in a collection (on the active or --store= named store).'
   static providers = ['config', 'logger', 'brain', 'rag']
 
   override async execute({ args, flags }: ExecuteArgs): Promise<number> {
     const collection = args.collection as string
-    const storeName = typeof flags.store === 'string' && flags.store.length > 0
-      ? flags.store
-      : undefined
+    const storeName =
+      typeof flags.store === 'string' && flags.store.length > 0 ? flags.store : undefined
 
     const manager = this.app.resolve(RagManager)
     const fullCollection = manager.collectionName(collection)
@@ -43,9 +43,7 @@ export class RagFlush extends Command {
     }
 
     await manager.store(storeName).flush(fullCollection)
-    this.success(
-      `Flushed collection "${fullCollection}" on store "${storeLabel}".`,
-    )
+    this.success(`Flushed collection "${fullCollection}" on store "${storeLabel}".`)
     return ExitCode.Success
   }
 }

package/src/console/rag_reindex.ts

@@ -0,0 +1,100 @@
+/**
+ * `bun strav rag:reindex {name?} [--all] [--batch=100]` —
+ * walk a registered repository and re-vectorize every row.
+ *
+ * Apps register repos at boot:
+ *
+ *   const registry = app.resolve(RetrievableRegistry)
+ *   registry.register('articles', ArticleRepository)
+ *
+ * Then:
+ *
+ *   bun strav rag:reindex articles          # one repo
+ *   bun strav rag:reindex --all             # every registered repo
+ *
+ * The repo class must implement `reindexAll(batchSize?)` — the
+ * `retrievable()` mixin already does. Batch size defaults to 100;
+ * apps hitting embedding rate limits drop it lower.
+ *
+ * Long-running on large corpora — apps that need cron-driven or
+ * queued re-index typically ship a custom command pointing at the
+ * same `reindexAll` method.
+ */
+
+import { Command, type ExecuteArgs, ExitCode } from '@strav/cli'
+import { RagError } from '../rag_error.ts'
+import { RetrievableRegistry } from '../retrievable_registry.ts'
+
+export class RagReindex extends Command {
+  static signature = 'rag:reindex {name?} {--all} {--batch=100}'
+  static description =
+    'Re-vectorize one registered retrievable repository (or every one with --all).'
+  static providers = ['config', 'logger', 'brain', 'rag', 'database']
+
+  override async execute({ args, flags }: ExecuteArgs): Promise<number> {
+    const registry = this.app.resolve(RetrievableRegistry)
+    const batchSize = parseBatch(flags.batch)
+
+    if (flags.all === true) {
+      const names = registry.names()
+      if (names.length === 0) {
+        this.warn(
+          'No retrievables registered. Call `registry.register(name, Repo)` from a service provider first.',
+        )
+        return ExitCode.Success
+      }
+      let total = 0
+      for (const name of names) {
+        const processed = await this.reindexOne(registry, name, batchSize)
+        total += processed
+      }
+      this.success(
+        `Re-indexed ${total} rows across ${names.length} repositor${names.length === 1 ? 'y' : 'ies'}.`,
+      )
+      return ExitCode.Success
+    }
+
+    const name = args.name
+    if (typeof name !== 'string' || name.length === 0) {
+      this.error(
+        'rag:reindex requires a repository name, or --all to re-index every registered repository.',
+      )
+      this.info(`Registered: ${registry.names().join(', ') || '(none)'}`)
+      return ExitCode.UsageError
+    }
+
+    try {
+      const processed = await this.reindexOne(registry, name, batchSize)
+      this.success(`Re-indexed ${processed} rows in "${name}".`)
+      return ExitCode.Success
+    } catch (err) {
+      if (err instanceof RagError) {
+        this.error(err.message)
+        this.info(`Registered: ${registry.names().join(', ') || '(none)'}`)
+        return ExitCode.GenericFailure
+      }
+      throw err
+    }
+  }
+
+  private async reindexOne(
+    registry: RetrievableRegistry,
+    name: string,
+    batchSize: number,
+  ): Promise<number> {
+    this.info(`Re-indexing "${name}"…`)
+    const repo = this.app.resolve(registry.resolve(name))
+    const processed = await repo.reindexAll(batchSize)
+    this.info(`  ${processed} rows.`)
+    return processed
+  }
+}
+
+function parseBatch(raw: unknown): number {
+  if (typeof raw === 'number' && raw > 0) return Math.floor(raw)
+  if (typeof raw === 'string') {
+    const n = Number.parseInt(raw, 10)
+    if (Number.isFinite(n) && n > 0) return n
+  }
+  return 100
+}

package/src/drivers/memory/memory_driver.ts

@@ -21,12 +21,7 @@
  */
 
 import { CollectionNotFoundError } from '../../rag_error.ts'
-import type {
-  QueryOptions,
-  QueryResult,
-  VectorDocument,
-  VectorMatch,
-} from '../../types.ts'
+import type { QueryOptions, QueryResult, VectorDocument, VectorMatch } from '../../types.ts'
 import type { VectorStore } from '../../vector_store.ts'
 
 interface StoredDoc {
@@ -55,10 +50,7 @@ export class MemoryDriver implements VectorStore {
     this.dimensions.delete(collection)
   }
 
-  async upsert(
-    collection: string,
-    documents: readonly VectorDocument[],
-  ): Promise<void> {
+  async upsert(collection: string, documents: readonly VectorDocument[]): Promise<void> {
     const bucket = this.requireBucket(collection)
     for (const doc of documents) {
       const id = doc.id ?? crypto.randomUUID()

package/src/drivers/pgvector/pgvector_driver.ts

@@ -34,7 +34,6 @@ import {
   type PostgresDatabase,
 } from '@strav/database'
 import { VectorQueryError } from '../../rag_error.ts'
-import { ragVectorSchema } from '../../vectors/rag_vector_schema.ts'
 import type {
   QueryOptions,
   QueryResult,
@@ -43,6 +42,7 @@ import type {
   VectorMatch,
 } from '../../types.ts'
 import type { VectorStore } from '../../vector_store.ts'
+import { ragVectorSchema } from '../../vectors/rag_vector_schema.ts'
 
 export interface PgvectorDriverOptions {
   /** PostgresDatabase instance — typically resolved from the container. */
@@ -99,18 +99,12 @@ export class PgvectorDriver implements VectorStore {
   }
 
   async deleteCollection(collection: string): Promise<void> {
-    await this.exec().execute(
-      `DELETE FROM "${this.table}" WHERE "collection" = $1`,
-      [collection],
-    )
+    await this.exec().execute(`DELETE FROM "${this.table}" WHERE "collection" = $1`, [collection])
   }
 
   // ─── Mutations ────────────────────────────────────────────────────────
 
-  async upsert(
-    collection: string,
-    documents: readonly VectorDocument[],
-  ): Promise<void> {
+  async upsert(collection: string, documents: readonly VectorDocument[]): Promise<void> {
     if (documents.length === 0) return
     // pgvector accepts the vector as a stringified array literal —
     // `[0.12,0.34,...]` — cast with `::vector` at the boundary.
@@ -167,10 +161,7 @@ export class PgvectorDriver implements VectorStore {
   }
 
   async flush(collection: string): Promise<void> {
-    await this.exec().execute(
-      `DELETE FROM "${this.table}" WHERE "collection" = $1`,
-      [collection],
-    )
+    await this.exec().execute(`DELETE FROM "${this.table}" WHERE "collection" = $1`, [collection])
   }
 
   // ─── Query ────────────────────────────────────────────────────────────
@@ -194,7 +185,9 @@ export class PgvectorDriver implements VectorStore {
     if (options.filter) {
       for (const [key, value] of Object.entries(options.filter)) {
         params.push(JSON.stringify(value))
-        where.push(`"metadata" @> jsonb_build_object('${escapeJsonbKey(key)}', $${params.length}::jsonb)`)
+        where.push(
+          `"metadata" @> jsonb_build_object('${escapeJsonbKey(key)}', $${params.length}::jsonb)`,
+        )
       }
     }
 
@@ -221,10 +214,10 @@ export class PgvectorDriver implements VectorStore {
     try {
       rows = await this.exec().query(sql, params)
     } catch (cause) {
-      throw new VectorQueryError(
-        `pgvector query failed for collection "${collection}".`,
-        { context: { collection, table: this.table }, cause },
-      )
+      throw new VectorQueryError(`pgvector query failed for collection "${collection}".`, {
+        context: { collection, table: this.table },
+        cause,
+      })
     }
 
     const matches: VectorMatch[] = rows.map((r) => ({

package/src/index.ts

@@ -1,25 +1,30 @@
 // Public API of `@strav/rag`.
 //
-// V1: vector store abstraction + memory & pgvector drivers +
-// fixed-size & recursive chunkers + RagManager + RagProvider.
+// Shipped:
+//   - Vector store abstraction + Memory & Pgvector drivers.
+//   - Fixed-size + recursive chunkers.
+//   - `RagManager` + `RagProvider` service wiring.
+//   - `retrievable()` repository mixin + `RetrievableRegistry`.
+//   - CLI: `rag:list`, `rag:flush`, `rag:reindex {name|--all}`.
+//   - Re-ranking — `Reranker` interface + `KeywordReranker` +
+//     `MMRReranker` + `RetrieveOptions.rerank` / `rerankPool`.
 // Composes with `@strav/brain` for embeddings and `@strav/database`
 // for pgvector persistence + multitenancy.
-//
-// Deferred to follow-up slices: `retrievable()` repository mixin,
-// CLI commands (`rag:reindex`, `rag:flush`), re-ranking strategies.
 
 export { createChunker } from './chunking/chunker.ts'
 export { FixedSizeChunker } from './chunking/fixed_size_chunker.ts'
 export { RecursiveChunker } from './chunking/recursive_chunker.ts'
+export {
+  RagConsoleProvider,
+  RagFlush,
+  RagList,
+  RagReindex,
+} from './console/index.ts'
 export { MemoryDriver } from './drivers/memory/memory_driver.ts'
 export {
   PgvectorDriver,
   type PgvectorDriverOptions,
 } from './drivers/pgvector/pgvector_driver.ts'
-export {
-  applyRagVectorMigration,
-  type ApplyRagVectorMigrationOptions,
-} from './vectors/apply_rag_vector_migration.ts'
 export {
   CollectionNotFoundError,
   EmbeddingError,
@@ -32,14 +37,19 @@ export {
   type RagManagerOptions,
   type StoreFactory,
 } from './rag_manager.ts'
-export {
-  RagConsoleProvider,
-  RagFlush,
-  RagList,
-} from './console/index.ts'
 export { RagProvider } from './rag_provider.ts'
-export { ragVectorSchema } from './vectors/rag_vector_schema.ts'
+export {
+  KeywordReranker,
+  type KeywordRerankerOptions,
+  MMRReranker,
+  type MMRRerankerOptions,
+  type Reranker,
+} from './rerankers/index.ts'
 export { retrievable } from './retrievable.ts'
+export {
+  RetrievableRegistry,
+  type RetrievableTarget,
+} from './retrievable_registry.ts'
 export type {
   Chunk,
   Chunker,
@@ -48,11 +58,16 @@ export type {
   QueryOptions,
   QueryResult,
   RagConfig,
+  RetrievedDocument,
   RetrieveOptions,
   RetrieveResult,
-  RetrievedDocument,
   StoreConfig,
   VectorDocument,
   VectorMatch,
 } from './types.ts'
 export type { VectorStore } from './vector_store.ts'
+export {
+  type ApplyRagVectorMigrationOptions,
+  applyRagVectorMigration,
+} from './vectors/apply_rag_vector_migration.ts'
+export { ragVectorSchema } from './vectors/rag_vector_schema.ts'

package/src/rag_error.ts

@@ -35,7 +35,10 @@ export class RagError extends StravError {
     super(
       message,
       { code: options.code ?? 'rag.error', status: options.status ?? 500 },
-      { ...(options.context ? { context: options.context } : {}), ...(options.cause !== undefined ? { cause: options.cause } : {}) },
+      {
+        ...(options.context ? { context: options.context } : {}),
+        ...(options.cause !== undefined ? { cause: options.cause } : {}),
+      },
     )
   }
 }
@@ -54,7 +57,10 @@ export class CollectionNotFoundError extends RagError {
 }
 
 export class VectorQueryError extends RagError {
-  constructor(message: string, options: { context?: Record<string, unknown>; cause?: unknown } = {}) {
+  constructor(
+    message: string,
+    options: { context?: Record<string, unknown>; cause?: unknown } = {},
+  ) {
     super(message, {
       code: 'rag.vector_query',
       status: 500,
@@ -65,7 +71,10 @@ export class VectorQueryError extends RagError {
 }
 
 export class EmbeddingError extends RagError {
-  constructor(message: string, options: { context?: Record<string, unknown>; cause?: unknown } = {}) {
+  constructor(
+    message: string,
+    options: { context?: Record<string, unknown>; cause?: unknown } = {},
+  ) {
     super(message, {
       code: 'rag.embedding',
       status: 500,

package/src/rag_manager.ts

@@ -23,10 +23,10 @@
  * `tenants.withTenant(...)` get per-tenant isolation for free.
  */
 
-// biome-ignore lint/style/useImportType: PostgresDatabase value import for the container path that wires PgvectorDriver.
-import { PostgresDatabase } from '@strav/database'
 // biome-ignore lint/style/useImportType: BrainManager value import for @inject() param-type metadata.
 import { BrainManager } from '@strav/brain'
+// biome-ignore lint/style/useImportType: PostgresDatabase value import for the container path that wires PgvectorDriver.
+import { PostgresDatabase } from '@strav/database'
 // biome-ignore lint/style/useImportType: Application value import for the container handle.
 import { Application, inject, ulid } from '@strav/kernel'
 import { createChunker } from './chunking/chunker.ts'
@@ -34,13 +34,13 @@ import { MemoryDriver } from './drivers/memory/memory_driver.ts'
 import { PgvectorDriver } from './drivers/pgvector/pgvector_driver.ts'
 import { EmbeddingError, RagError } from './rag_error.ts'
 import type {
-  ChunkingConfig,
   Chunk,
   Chunker,
+  ChunkingConfig,
   RagConfig,
+  RetrievedDocument,
   RetrieveOptions,
   RetrieveResult,
-  RetrievedDocument,
   StoreConfig,
   VectorDocument,
 } from './types.ts'
@@ -168,7 +168,7 @@ export class RagManager {
       strategy: options.chunking?.strategy ?? this.config.chunking.strategy,
       chunkSize: options.chunking?.chunkSize ?? this.config.chunking.chunkSize,
       overlap: options.chunking?.overlap ?? this.config.chunking.overlap,
-      ...(options.chunking?.separators ?? this.config.chunking.separators
+      ...((options.chunking?.separators ?? this.config.chunking.separators)
         ? { separators: options.chunking?.separators ?? this.config.chunking.separators }
         : {}),
     }
@@ -198,10 +198,10 @@ export class RagManager {
       })
       embeddings = result.embeddings as number[][]
     } catch (cause) {
-      throw new EmbeddingError(
-        `RagManager.ingest: embedding ${texts.length} chunks failed.`,
-        { context: { collection: fullCollection }, cause },
-      )
+      throw new EmbeddingError(`RagManager.ingest: embedding ${texts.length} chunks failed.`, {
+        context: { collection: fullCollection },
+        cause,
+      })
     }
 
     const documents: VectorDocument[] = chunks.map((chunk, i) => ({
@@ -223,13 +223,8 @@ export class RagManager {
 
   // ─── Retrieve ─────────────────────────────────────────────────────────
 
-  async retrieve(
-    query: string,
-    options: RetrieveOptions = {},
-  ): Promise<RetrieveResult> {
-    const fullCollection = this.collectionName(
-      options.collection ?? this.config.default,
-    )
+  async retrieve(query: string, options: RetrieveOptions = {}): Promise<RetrieveResult> {
+    const fullCollection = this.collectionName(options.collection ?? this.config.default)
     const start = performance.now()
 
     let embedding: number[]
@@ -240,24 +235,23 @@ export class RagManager {
       })
       embedding = result.embeddings[0] as number[]
     } catch (cause) {
-      throw new EmbeddingError(
-        `RagManager.retrieve: embedding query failed.`,
-        { context: { collection: fullCollection }, cause },
-      )
+      throw new EmbeddingError(`RagManager.retrieve: embedding query failed.`, {
+        context: { collection: fullCollection },
+        cause,
+      })
     }
 
+    const finalTopK = options.topK
+    const fetchK = options.rerank !== undefined ? (options.rerankPool ?? finalTopK) : finalTopK
+
     const queryOpts: { topK?: number; threshold?: number; filter?: Record<string, unknown> } = {}
-    if (options.topK !== undefined) queryOpts.topK = options.topK
+    if (fetchK !== undefined) queryOpts.topK = fetchK
     if (options.threshold !== undefined) queryOpts.threshold = options.threshold
     if (options.filter !== undefined) queryOpts.filter = options.filter
 
-    const result = await this.store(options.store).query(
-      fullCollection,
-      embedding,
-      queryOpts,
-    )
+    const result = await this.store(options.store).query(fullCollection, embedding, queryOpts)
 
-    const matches: RetrievedDocument[] = result.matches.map((m) => ({
+    let matches: RetrievedDocument[] = result.matches.map((m) => ({
       id: m.id,
       content: m.content,
       score: m.score,
@@ -266,6 +260,13 @@ export class RagManager {
       ...(m.sourceId !== undefined ? { sourceId: m.sourceId } : {}),
     }))
 
+    if (options.rerank !== undefined && matches.length > 0) {
+      matches = [...(await options.rerank.rerank(query, matches))]
+      if (finalTopK !== undefined && matches.length > finalTopK) {
+        matches = matches.slice(0, finalTopK)
+      }
+    }
+
     return {
       query,
       matches,

package/src/rag_provider.ts

@@ -16,17 +16,13 @@
  * via a real `config/rag.ts`.
  */
 
-// biome-ignore lint/style/useImportType: PostgresDatabase value import — required when any pgvector store is configured. Loaded conditionally below.
-import { PostgresDatabase } from '@strav/database'
 // biome-ignore lint/style/useImportType: BrainManager value import for c.resolve.
 import { BrainManager } from '@strav/brain'
-import {
-  type Application,
-  ConfigError,
-  ConfigRepository,
-  ServiceProvider,
-} from '@strav/kernel'
+// biome-ignore lint/style/useImportType: PostgresDatabase value import — required when any pgvector store is configured. Loaded conditionally below.
+import { PostgresDatabase } from '@strav/database'
+import { type Application, ConfigError, ConfigRepository, ServiceProvider } from '@strav/kernel'
 import { RagManager, type RagManagerOptions } from './rag_manager.ts'
+import { RetrievableRegistry } from './retrievable_registry.ts'
 import type { RagConfig } from './types.ts'
 
 export class RagProvider extends ServiceProvider {
@@ -34,6 +30,7 @@ export class RagProvider extends ServiceProvider {
   override readonly dependencies = ['config', 'brain']
 
   override register(app: Application): void {
+    app.singleton(RetrievableRegistry, () => new RetrievableRegistry())
     app.singleton(RagManager, (c) => {
       const raw = c.resolve(ConfigRepository).get('rag') as Partial<RagConfig> | undefined
       const config = applyDefaults(raw)

package/src/rerankers/index.ts

@@ -0,0 +1,3 @@
+export { KeywordReranker, type KeywordRerankerOptions } from './keyword_reranker.ts'
+export { MMRReranker, type MMRRerankerOptions } from './mmr_reranker.ts'
+export type { Reranker } from './reranker.ts'

package/src/rerankers/keyword_reranker.ts

@@ -0,0 +1,69 @@
+/**
+ * `KeywordReranker` — boost matches whose content literally contains
+ * tokens from the query.
+ *
+ * Useful when the embedder is too smooth for short, jargon-heavy
+ * queries (product SKUs, error codes, acronyms). Combines the raw
+ * vector similarity with a token-overlap score:
+ *
+ *     score = (1 - weight) * similarity + weight * overlap
+ *
+ * where `overlap = matched tokens / total query tokens`. Pure
+ * lexical with no inverted index — fine at top-K sizes of a few
+ * dozen. Apps that need real BM25 wire a custom `Reranker`.
+ */
+
+import type { RetrievedDocument } from '../types.ts'
+import type { Reranker } from './reranker.ts'
+
+export interface KeywordRerankerOptions {
+  /**
+   * Blend factor between vector similarity (0) and keyword overlap
+   * (1). Default `0.3` — similarity stays the dominant signal,
+   * keyword overlap nudges exact-match docs higher.
+   */
+  weight?: number
+  /** Case-sensitive matching. Default `false`. */
+  caseSensitive?: boolean
+  /**
+   * Custom tokenizer. Default splits on Unicode whitespace and
+   * drops empty fragments. Apps with stricter requirements (stem,
+   * stop-word filter, etc.) pass their own.
+   */
+  tokenize?(input: string): readonly string[]
+}
+
+export class KeywordReranker implements Reranker {
+  private readonly weight: number
+  private readonly caseSensitive: boolean
+  private readonly tokenize: (input: string) => readonly string[]
+
+  constructor(options: KeywordRerankerOptions = {}) {
+    this.weight = options.weight ?? 0.3
+    this.caseSensitive = options.caseSensitive ?? false
+    this.tokenize = options.tokenize ?? defaultTokenize
+  }
+
+  rerank(query: string, matches: readonly RetrievedDocument[]): RetrievedDocument[] {
+    const queryStr = this.caseSensitive ? query : query.toLowerCase()
+    const tokens = [...new Set(this.tokenize(queryStr))].filter(Boolean)
+    if (tokens.length === 0) return [...matches]
+
+    const scored = matches.map((m) => {
+      const haystack = this.caseSensitive ? m.content : m.content.toLowerCase()
+      let hits = 0
+      for (const token of tokens) {
+        if (haystack.includes(token)) hits++
+      }
+      const overlap = hits / tokens.length
+      const blended = m.similarity * (1 - this.weight) + overlap * this.weight
+      return { ...m, score: blended }
+    })
+
+    return scored.sort((a, b) => b.score - a.score)
+  }
+}
+
+function defaultTokenize(input: string): readonly string[] {
+  return input.split(/\s+/)
+}

package/src/rerankers/mmr_reranker.ts

@@ -0,0 +1,107 @@
+/**
+ * `MMRReranker` — Maximal Marginal Relevance.
+ *
+ * Reorders matches to balance relevance to the query against
+ * diversity among the chosen documents. Useful when the raw top-K
+ * contains near-duplicate chunks from the same source.
+ *
+ *     MMR(d) = λ * sim(d, query) - (1 - λ) * max_{s ∈ selected} sim(d, s)
+ *
+ * `λ = 1.0` collapses to pure similarity (no diversity bias);
+ * `λ = 0.0` greedily maximizes diversity ignoring the query.
+ * `0.5` (default) is a balanced middle.
+ *
+ * Requires document embeddings the vector store didn't return. The
+ * caller provides an `embed(text)` callback — typically
+ * `(t) => brain.embed([t]).then(r => r.embeddings[0])`. The reranker
+ * embeds the query + every document once (`matches.length + 1`
+ * calls); apps that rerank pools >50 should cache or pre-compute
+ * upstream.
+ */
+
+import type { RetrievedDocument } from '../types.ts'
+import type { Reranker } from './reranker.ts'
+
+export interface MMRRerankerOptions {
+  /**
+   * Compute an embedding for a single piece of text. Apps wire
+   * this from `BrainManager.embed`:
+   *
+   *   embed: async (t) => {
+   *     const r = await brain.embed([t], { model: 'text-embedding-3-small' })
+   *     return r.embeddings[0]!
+   *   }
+   */
+  embed(text: string): Promise<number[]>
+  /**
+   * Relevance/diversity blend in `[0, 1]`. Default `0.5`. `1.0` =
+   * pure similarity; `0.0` = pure diversity.
+   */
+  lambda?: number
+}
+
+export class MMRReranker implements Reranker {
+  private readonly embed: (text: string) => Promise<number[]>
+  private readonly lambda: number
+
+  constructor(options: MMRRerankerOptions) {
+    this.embed = options.embed
+    this.lambda = options.lambda ?? 0.5
+  }
+
+  async rerank(query: string, matches: readonly RetrievedDocument[]): Promise<RetrievedDocument[]> {
+    if (matches.length <= 1) return [...matches]
+
+    const queryEmbedding = await this.embed(query)
+    const docEmbeddings = await Promise.all(matches.map((m) => this.embed(m.content)))
+
+    const remaining = matches.map((_, i) => i)
+    const ordered: { index: number; mmr: number }[] = []
+
+    while (remaining.length > 0) {
+      let bestSlot = 0
+      let bestMmr = Number.NEGATIVE_INFINITY
+      for (let r = 0; r < remaining.length; r++) {
+        const i = remaining[r] as number
+        const relevance = cosineSimilarity(queryEmbedding, docEmbeddings[i] as number[])
+        let maxOverlap = 0
+        for (const { index: s } of ordered) {
+          const overlap = cosineSimilarity(
+            docEmbeddings[i] as number[],
+            docEmbeddings[s] as number[],
+          )
+          if (overlap > maxOverlap) maxOverlap = overlap
+        }
+        const mmr = this.lambda * relevance - (1 - this.lambda) * maxOverlap
+        if (mmr > bestMmr) {
+          bestMmr = mmr
+          bestSlot = r
+        }
+      }
+      const chosen = remaining[bestSlot] as number
+      ordered.push({ index: chosen, mmr: bestMmr })
+      remaining.splice(bestSlot, 1)
+    }
+
+    return ordered.map(({ index, mmr }) => ({
+      ...(matches[index] as RetrievedDocument),
+      score: mmr,
+    }))
+  }
+}
+
+function cosineSimilarity(a: readonly number[], b: readonly number[]): number {
+  const n = Math.min(a.length, b.length)
+  let dot = 0
+  let normA = 0
+  let normB = 0
+  for (let i = 0; i < n; i++) {
+    const ai = a[i] as number
+    const bi = b[i] as number
+    dot += ai * bi
+    normA += ai * ai
+    normB += bi * bi
+  }
+  if (normA === 0 || normB === 0) return 0
+  return dot / (Math.sqrt(normA) * Math.sqrt(normB))
+}

package/src/rerankers/reranker.ts

@@ -0,0 +1,35 @@
+/**
+ * Re-ranking — reorder a `topK` set of retrieved documents using
+ * a signal richer than raw vector similarity.
+ *
+ * The vector store hands back matches sorted by cosine similarity.
+ * That's a strong baseline but loses information: keyword overlap,
+ * diversity, recency, source authority, second-stage cross-encoder
+ * scores, etc. A `Reranker` consumes the initial top-K and returns
+ * the same documents in a (possibly different) order with new
+ * `score` values. The raw vector `similarity` field is preserved
+ * verbatim so apps that want to display both can.
+ *
+ * Common usage:
+ *
+ * ```ts
+ * const { matches } = await rag.retrieve(query, {
+ *   topK: 5,
+ *   rerankPool: 25,                  // fetch a wider pool…
+ *   rerank: new MMRReranker({ ... }),// reorder for diversity…
+ * })                                  // …then slice to topK.
+ * ```
+ *
+ * The contract is intentionally narrow: the reranker decides the
+ * order. The framework handles the over-fetch-then-truncate pattern
+ * via `rerankPool` so apps don't have to manage it.
+ */
+
+import type { RetrievedDocument } from '../types.ts'
+
+export interface Reranker {
+  rerank(
+    query: string,
+    matches: readonly RetrievedDocument[],
+  ): Promise<RetrievedDocument[]> | RetrievedDocument[]
+}

package/src/retrievable.ts

@@ -65,11 +65,7 @@
 
 import type { Repository } from '@strav/database'
 import type { RagManager } from './rag_manager.ts'
-import type {
-  RetrieveOptions,
-  RetrieveResult,
-  VectorMatch,
-} from './types.ts'
+import type { RetrieveOptions, RetrieveResult, VectorMatch } from './types.ts'
 
 /** Minimal constructor type we can mix into. Wider than `typeof Repository` so subclasses with extra ctor args still type-check. */
 // biome-ignore lint/suspicious/noExplicitAny: mixin constructor signatures intentionally accept any[]; the user-side subclass narrows.
@@ -157,9 +153,7 @@ export function retrievable<TModel extends object, TBase extends RepositoryConst
       // replace cleanly. (RagManager.ingest writes fresh ids per
       // call; without this step every re-vectorize would
       // duplicate.)
-      await this.rag
-        .store()
-        .deleteBySource(this.rag.collectionName(collection), id)
+      await this.rag.store().deleteBySource(this.rag.collectionName(collection), id)
 
       if (!this.shouldRetrieve(model)) return []
 
@@ -182,9 +176,7 @@ export function retrievable<TModel extends object, TBase extends RepositoryConst
     async vectorRemove(model: TModel): Promise<void> {
       const collection = this.collectionName()
       const id = modelId(model)
-      await this.rag
-        .store()
-        .deleteBySource(this.rag.collectionName(collection), id)
+      await this.rag.store().deleteBySource(this.rag.collectionName(collection), id)
     }
 
     /**
@@ -238,9 +230,7 @@ export function retrievable<TModel extends object, TBase extends RepositoryConst
       const ids = [...new Set(matches.map((m) => m.sourceId).filter((s): s is string => !!s))]
       if (ids.length === 0) return []
       const found = await this.findMany(ids as unknown as readonly string[])
-      const byId = new Map<string, TModel>(
-        found.map((m) => [modelId(m), m]),
-      )
+      const byId = new Map<string, TModel>(found.map((m) => [modelId(m), m]))
       const out: TModel[] = []
       for (const match of matches) {
         if (!match.sourceId) continue

package/src/retrievable_registry.ts

@@ -0,0 +1,60 @@
+/**
+ * `RetrievableRegistry` — bag of named pointers to retrievable
+ * repositories so the `rag:reindex` console command can resolve
+ * them at runtime.
+ *
+ * The framework can't statically discover which repositories use
+ * the `retrievable()` mixin — apps register them at boot:
+ *
+ *   const registry = app.resolve(RetrievableRegistry)
+ *   registry.register('articles', ArticleRepository)
+ *
+ * Then:
+ *
+ *   bun strav rag:reindex articles
+ *   bun strav rag:reindex --all
+ *
+ * resolves the repository through the container and calls
+ * `reindexAll(batchSize)`. The repo class must implement
+ * `reindexAll(batchSize?: number): Promise<number>` — the
+ * `retrievable()` mixin provides exactly that shape.
+ */
+
+import { inject } from '@strav/kernel'
+import { RagError } from './rag_error.ts'
+
+export interface RetrievableTarget {
+  reindexAll(batchSize?: number): Promise<number>
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: container-resolved constructor; the user-side class narrows.
+type RetrievableConstructor = new (...args: any[]) => RetrievableTarget
+
+@inject()
+export class RetrievableRegistry {
+  private readonly targets = new Map<string, RetrievableConstructor>()
+
+  /**
+   * Register a repository class under `name`. The class will be
+   * resolved from the container on `rag:reindex <name>`.
+   */
+  register(name: string, ctor: RetrievableConstructor): void {
+    this.targets.set(name, ctor)
+  }
+
+  /** List every registered name — used by `rag:reindex --all`. */
+  names(): readonly string[] {
+    return [...this.targets.keys()]
+  }
+
+  /** Resolve the constructor for one name. Throws when unregistered. */
+  resolve(name: string): RetrievableConstructor {
+    const ctor = this.targets.get(name)
+    if (ctor === undefined) {
+      throw new RagError(`RetrievableRegistry: no retrievable registered under "${name}".`, {
+        context: { requested: name, available: this.names() },
+      })
+    }
+    return ctor
+  }
+}

package/src/types.ts

@@ -79,6 +79,25 @@ export interface RetrieveOptions {
   embedModel?: string
   /** Override the brain provider used for embedding. */
   embedProvider?: string
+  /**
+   * Optional re-ranker. When set, the framework fetches `rerankPool`
+   * (or `topK` if unset) matches from the store, runs the reranker,
+   * then slices the result to `topK`. The reranker decides the
+   * final order + `score`; `similarity` carries the raw vector
+   * cosine.
+   *
+   * Built-in strategies live under `@strav/rag` —
+   * `KeywordReranker` (lexical overlap blend) and `MMRReranker`
+   * (Maximal Marginal Relevance for diversity).
+   */
+  rerank?: import('./rerankers/reranker.ts').Reranker
+  /**
+   * Size of the candidate pool fetched from the store before
+   * re-ranking. Ignored when `rerank` is unset. Defaults to
+   * `topK` — set higher (`topK * 3` to `topK * 5` is typical) to
+   * give the reranker room to reorder.
+   */
+  rerankPool?: number
 }
 
 export interface RetrieveResult {

package/src/vector_store.ts

@@ -47,9 +47,5 @@ export interface VectorStore {
   deleteBySource(collection: string, sourceId: string): Promise<void>
   flush(collection: string): Promise<void>
 
-  query(
-    collection: string,
-    vector: readonly number[],
-    options?: QueryOptions,
-  ): Promise<QueryResult>
+  query(collection: string, vector: readonly number[], options?: QueryOptions): Promise<QueryResult>
 }

package/src/vectors/apply_rag_vector_migration.ts

@@ -30,11 +30,7 @@
  * the helper itself.
  */
 
-import {
-  emitCreateTable,
-  type DatabaseExecutor,
-  type SchemaRegistry,
-} from '@strav/database'
+import { type DatabaseExecutor, emitCreateTable, type SchemaRegistry } from '@strav/database'
 import { ragVectorSchema } from './rag_vector_schema.ts'
 
 export interface ApplyRagVectorMigrationOptions {