nexus-ai-pro 1.19.0 → 1.20.0

package/API_STABILITY.md

@@ -455,6 +455,17 @@ with nexus-ai-pro and declares the core versions it works with as a peer depende
 - The access rules are a guarantee: loopback binding by default, a token on every request, the token
   in a header for every change, and loopback hosts only unless others are allowed.
 
+## Retrieval stores stage (1.20.0)
+
+`PostgresVectorStore` (`nexus-ai-pro/postgres/vectors`) and `QdrantVectorStore` (`nexus-ai-pro/rag/qdrant`)
+are experimental in production readiness. The `VectorStore` contract they share with
+`MemoryVectorStore` follows the 1.x rules: a minor release may add optional methods and options, not
+remove or reshape these.
+
+- The pgvector table layout may gain columns in a minor release; `migrate()` adds what is missing.
+- A Qdrant point id is derived from the chunk id and is stable across releases, so a collection
+  written by one version is read by the next.
+
 ## Deprecation process
 
 Deprecated APIs are marked with `@deprecated` in declarations and described in the changelog. Removals

package/CHANGELOG.md

@@ -4,6 +4,41 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [1.20.0] - 2026-09-28
+
+Retrieval that scales past one process. Deprecated options now say so at run time, and every guide
+explains every export it lists.
+
+### Added
+
+- **Vector stores for retrieval.** `VectorStore` is a shared contract — `add()`, which replaces a chunk
+  whose id already exists, `search()`, `searchVector()` for a vector computed elsewhere, `delete()`,
+  and an exact-match metadata `filter` — with three implementations checked by one contract test:
+  - `PostgresVectorStore` on `nexus-ai-pro/postgres/vectors`, ranking with pgvector in the database,
+    with an HNSW index by default or an exact scan. `vectorStoreMigration()` gives its schema, and
+    `postgresMigration()` and `nexus db sql` include it when `vectors` is named.
+  - `QdrantVectorStore` on `nexus-ai-pro/rag/qdrant`, through Qdrant's REST API with `fetch` and Web
+    Crypto, so no Qdrant client is a dependency and it runs on edge runtimes. `migrate()` creates the
+    collection and indexes filter fields; failures raise `QdrantError`.
+  - `MemoryVectorStore`, which gains `searchVector()`, `delete()`, and the filter.
+- Retrieval is reachable from `nexus-ai-pro/rag` — `MemoryVectorStore`, `createHashEmbeddings()`,
+  `cosineSimilarity()`, `normalizeVector()`, `matchesMetadata()`, and the types — so an application
+  that ingests and searches no longer loads the root import.
+- **Deprecated options warn once per process** through Node's `DeprecationWarning` channel, with a
+  `NEXUS_DEP_*` code each, so `--no-deprecation` silences them and `--throw-deprecation` fails a CI
+  job on them: `GoogleProviderConfig.projectId`, `OllamaProviderConfig.timeout`,
+  `MetricsConfig.prometheus`, `HealthConfig.latencyHalfLife`, `DensificationConfig.preserveMarkdown`,
+  `InjectionDetectionConfig.sensitivity`, and `ToolPolicyConfig.requiresApproval`.
+
+### Changed
+
+- `MemoryVectorStore.add()` replaces a chunk whose id already exists instead of storing a second
+  copy, so re-ingesting a document no longer duplicates its passages in search results.
+- The guide check enforces that every export is explained in a guide's own text, not only named in
+  its generated reference; the five remaining guides — operations, embeddings, evaluation, images,
+  and realtime — now are. The README's limitations and production notes moved into the guides they
+  belong to.
+
 ## [1.19.0] - 2026-09-28
 
 A studio to look at it all. `nexus-ai-pro-studio` is a separate package — so the core install never
@@ -1008,7 +1043,8 @@ shared policy vocabulary is in place for a future release that revisits this.
 - URL fetching rejects unsafe private-network targets and limits response reads.
 - CLI and audit findings no longer disclose detected secret values.
 
-[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.19.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.20.0...HEAD
+[1.20.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.19.0...v1.20.0
 [1.19.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.18.0...v1.19.0
 [1.18.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.17.0...v1.18.0
 [1.17.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.16.0...v1.17.0

package/README.md

@@ -197,37 +197,22 @@ Shipped so far:
 - queryable traces, an evaluation platform, and a CI gate on top of it;
 - record and replay of provider traffic;
 - prompt versioning: typed templates, content versions, gated promotion, and serving through outages;
+- a self-hosted agent server, and a local studio as a separate package;
 - per-entry-point size budgets.
 
-Next is a self-hosted agent server. The image family leaves experimental once recorded live
-conformance passes on all three backends.
-
-## Known Limitations
-
-- Voice, telephony, images, local models, and custom providers are optional layers; enable only what
-  you use.
-- Audio and video preprocessing is limited, and provider modality support differs.
-- Bundled model metadata is a routing and estimation convenience, not a pricing contract.
-- Process-memory cache, queues, and asset storage are not enough for a distributed deployment; use
-  the Redis, BullMQ, filesystem, or S3 adapters instead.
-- Default hash embeddings suit tests and demos, not strong semantic search. Register a real
-  embedding provider for production retrieval.
-- NLI verification is an interface; bring a specialized verifier for high-confidence entailment.
-- Guardrails reduce risk but do not replace application authorization, provider-side moderation, or
-  human review of high-impact actions.
-- Realtime sessions are not yet routed through the metrics, audit, and rate-limit path that every
-  other family uses.
-- The image adapters are verified against documented wire shapes; recorded live conformance for all
-  three backends is still to come, which is why the family is experimental.
-
-## Production Notes
-
-- Use direct or rules-based routing when model choice is already known.
-- Keep semantic cache, semantic security, and custom hooks off latency-sensitive routes unless needed.
-- Disable response traces with `pipeline.includeTraceInResponse = false`.
-- Use shared adapters for distributed apps instead of process memory.
-- Treat bundled model pricing and context metadata as defaults, not financial truth.
-- Keep server-side authorization and provider moderation around high-risk workflows.
+Next: durable functional workflows and step-level recovery, then retrieval and integration breadth,
+a shared team studio, and self-managed deployment at scale, before 2.0.0 consolidates. The image
+family leaves experimental once recorded live conformance passes on all three backends.
+
+## Before Production
+
+Each guide ends with its limitations. The ones worth reading first: the
+[client guide](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/core.md#in-production) on latency, traces,
+and shared adapters; the [security guide](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/security.md#limitations)
+on what guardrails do not replace; and the
+[grounding guide](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/grounding.md#limitations) on embeddings
+and verification. Voice, telephony, images, realtime, local models, and custom providers are optional
+layers; enable only what you use.
 
 ## Donations
 

package/dist/cli/db.js

@@ -1,6 +1,14 @@
 import { postgresMigration } from '../postgres/index.js';
 import { CliUsageError, listFlag, numberFlag } from './args.js';
-const ADAPTERS = ['operations', 'store', 'traces', 'evaluation', 'circuits', 'prompts'];
+const ADAPTERS = [
+    'operations',
+    'store',
+    'traces',
+    'evaluation',
+    'circuits',
+    'prompts',
+    'vectors',
+];
 export async function runDbCommand(subcommand, { flags }) {
     if (subcommand !== 'sql')
         throw new CliUsageError(`Unknown db command "${subcommand ?? ''}". Use sql.`);
@@ -10,6 +18,9 @@ export async function runDbCommand(subcommand, { flags }) {
         throw new CliUsageError(`Unknown adapter ${unknown.join(', ')}. Choose from ${ADAPTERS.join(', ')}.`);
     }
     const vectorDimensions = numberFlag(flags, 'vector-dimensions');
+    if (adapters?.includes('vectors') && vectorDimensions === undefined) {
+        throw new CliUsageError('The vectors adapter needs --vector-dimensions.');
+    }
     process.stdout.write(postgresMigration({
         ...(adapters ? { adapters } : {}),
         ...(vectorDimensions === undefined ? {} : { vectorDimensions }),

package/dist/hallucination/retrieval.d.ts

@@ -17,24 +17,52 @@ export interface VectorSearchOptions {
     topK?: number;
     /** Lowest similarity returned. Defaults to 0. */
     minScore?: number;
+    /**
+     * Exact matches on top-level `metadata` fields, such as `{ tenant: 'acme' }`. Every field must
+     * match. Values are strings, numbers, or booleans, which every adapter can filter on natively.
+     */
+    filter?: Record<string, string | number | boolean>;
+}
+/**
+ * Where retrieval chunks live and how they are searched. `MemoryVectorStore`, `PostgresVectorStore`,
+ * and `QdrantVectorStore` implement it, and pass the same contract tests.
+ *
+ * Adding a chunk whose id already exists replaces it, so re-ingesting a document never duplicates
+ * its passages.
+ */
+export interface VectorStore {
+    /** Adds chunks, or replaces the ones whose id already exists, embedding those without a vector. */
+    add(documents: VectorDocument[]): Promise<void>;
+    /** The chunks most similar to a query text, best first. */
+    search(query: string, options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
+    /** The chunks most similar to a vector computed elsewhere, best first. */
+    searchVector(vector: number[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
+    /** Removes chunks by id. An id that is not stored is ignored. */
+    delete(ids: readonly string[]): Promise<void>;
 }
 /**
  * Chunks and their vectors in process memory, searched by cosine similarity. Defaults to hashed
  * term vectors, which need no provider.
  */
-export declare class MemoryVectorStore {
+export declare class MemoryVectorStore implements VectorStore {
     private documents;
     private embed;
     constructor(embed?: EmbeddingProvider);
-    /** Adds chunks, embedding those without a vector in one batch. */
+    /** Adds chunks, or replaces those whose id exists, embedding those without a vector in one batch. */
     add(documents: VectorDocument[]): Promise<void>;
     /** The chunks most similar to a query, best first. */
     search(query: string, options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
+    /** The chunks most similar to a vector, best first. */
+    searchVector(vector: number[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
+    /** Removes chunks by id. */
+    delete(ids: readonly string[]): Promise<void>;
     /** Removes every chunk. */
     clear(): void;
     /** Chunks held. */
     size(): number;
 }
+/** Whether a chunk's metadata satisfies an exact-match filter. Every adapter filters the same way. */
+export declare function matchesMetadata(metadata: Record<string, unknown> | undefined, filter: VectorSearchOptions['filter']): boolean;
 /**
  * Hashed term-count vectors, normalized to unit length. Deterministic and free, for tests and a
  * store without a provider.
@@ -42,4 +70,5 @@ export declare class MemoryVectorStore {
 export declare function createHashEmbeddings(texts: string[], dimensions?: number): number[][];
 /** Cosine similarity of two unit-length vectors, as their dot product. */
 export declare function cosineSimilarity(a: number[], b: number[]): number;
+/** Scales a vector to unit length, so a dot product is its cosine similarity. A zero vector stays zero. */
 export declare function normalizeVector(vector: number[]): number[];

package/dist/hallucination/retrieval.js

@@ -1,5 +1,5 @@
 export class MemoryVectorStore {
-    documents = [];
+    documents = new Map();
     embed;
     constructor(embed = createHashEmbeddings) {
         this.embed = embed;
@@ -10,29 +10,46 @@ export class MemoryVectorStore {
         let generatedIndex = 0;
         for (const doc of documents) {
             const embedding = doc.embedding || generated[generatedIndex++];
-            this.documents.push({ ...doc, embedding: normalizeVector(embedding) });
+            this.documents.set(doc.id, { ...doc, embedding: normalizeVector(embedding) });
         }
     }
     async search(query, options = {}) {
+        const [queryEmbedding] = await this.embed([query]);
+        return this.searchVector(queryEmbedding, options);
+    }
+    async searchVector(vector, options = {}) {
         const topK = options.topK || 5;
         const minScore = options.minScore ?? 0;
-        const [queryEmbedding] = await this.embed([query]);
-        const normalizedQuery = normalizeVector(queryEmbedding);
-        return this.documents
-            .map(({ embedding, ...doc }) => ({
-            ...doc,
-            score: cosineSimilarity(normalizedQuery, embedding),
-        }))
-            .filter((doc) => doc.score >= minScore)
-            .sort((a, b) => b.score - a.score)
-            .slice(0, topK);
+        const normalizedQuery = normalizeVector(vector);
+        const results = [];
+        for (const { embedding, ...doc } of this.documents.values()) {
+            if (!matchesMetadata(doc.metadata, options.filter))
+                continue;
+            const score = cosineSimilarity(normalizedQuery, embedding);
+            if (score >= minScore)
+                results.push({ ...doc, score });
+        }
+        return results.sort((a, b) => b.score - a.score).slice(0, topK);
+    }
+    async delete(ids) {
+        for (const id of ids)
+            this.documents.delete(id);
     }
     clear() {
-        this.documents = [];
+        this.documents.clear();
     }
     size() {
-        return this.documents.length;
+        return this.documents.size;
+    }
+}
+export function matchesMetadata(metadata, filter) {
+    if (!filter)
+        return true;
+    for (const [key, expected] of Object.entries(filter)) {
+        if (metadata?.[key] !== expected)
+            return false;
     }
+    return true;
 }
 export function createHashEmbeddings(texts, dimensions = 384) {
     return texts.map((text) => {

package/dist/index.d.ts

@@ -38,7 +38,7 @@ export { PipelineRunner, createPipelineContext, } from './pipeline/pipeline.js';
 export type { PipelineConfig, PipelineContext, PipelineHookName, PipelineHooksConfig, PipelineMiddleware, PipelineStep, PipelineStepName, PipelineTrace, PipelineTraceStep, } from './pipeline/types.js';
 export { withFactualDefaults, asJsonOnly, type FactualOptions, } from './hallucination/factual.js';
 export { withRagContext, extractCitations, validateCitations, type RagChunk, type RagOptions, } from './hallucination/rag.js';
-export { MemoryVectorStore, createHashEmbeddings, cosineSimilarity, type EmbeddingProvider, type VectorDocument, type VectorSearchOptions, type VectorSearchResult, } from './hallucination/retrieval.js';
+export { MemoryVectorStore, createHashEmbeddings, cosineSimilarity, matchesMetadata, normalizeVector, type EmbeddingProvider, type VectorDocument, type VectorSearchOptions, type VectorSearchResult, type VectorStore, } from './hallucination/retrieval.js';
 export { withKnowledgeGraphContext, selectGraphFacts, type KnowledgeGraph, type KnowledgeGraphEdge, type KnowledgeGraphNode, type KnowledgeGraphOptions, } from './hallucination/knowledge-graph.js';
 export { completeVerified, verifyAgainstContext, extractFacts, lexicalEntailment, type NliVerifier, type VerificationClient, type VerificationFact, type VerificationOptions, type VerificationReport, } from './hallucination/verification.js';
 export { completeWithSelfConsistency, selectMostConsistent, textSimilarity, type ConsistencyClient, type SelfConsistencyOptions, } from './hallucination/consistency.js';

package/dist/index.js

@@ -37,7 +37,7 @@ export { MemoryRateLimitStore, RedisRateLimitStore, } from './ops/rate-limit-ada
 export { PipelineRunner, createPipelineContext, } from './pipeline/pipeline.js';
 export { withFactualDefaults, asJsonOnly, } from './hallucination/factual.js';
 export { withRagContext, extractCitations, validateCitations, } from './hallucination/rag.js';
-export { MemoryVectorStore, createHashEmbeddings, cosineSimilarity, } from './hallucination/retrieval.js';
+export { MemoryVectorStore, createHashEmbeddings, cosineSimilarity, matchesMetadata, normalizeVector, } from './hallucination/retrieval.js';
 export { withKnowledgeGraphContext, selectGraphFacts, } from './hallucination/knowledge-graph.js';
 export { completeVerified, verifyAgainstContext, extractFacts, lexicalEntailment, } from './hallucination/verification.js';
 export { completeWithSelfConsistency, selectMostConsistent, textSimilarity, } from './hallucination/consistency.js';

package/dist/ops/health.js

@@ -1,8 +1,10 @@
+import { warnUnreadOption } from '../utils/deprecation.js';
 export class ProviderHealthMonitor {
     config;
     states = new Map();
     constructor(config = {}) {
         this.config = config;
+        warnUnreadOption(config.latencyHalfLife !== undefined, 'NEXUS_DEP_HEALTH_LATENCY_HALF_LIFE', 'HealthConfig.latencyHalfLife');
     }
     recordSuccess(providerName, latencyMs) {
         if (!this.config.enabled)

package/dist/ops/metrics.js

@@ -1,3 +1,4 @@
+import { warnUnreadOption } from '../utils/deprecation.js';
 export class InMemoryMetrics {
     counters = new Map();
     histograms = new Map();
@@ -86,6 +87,7 @@ export class MetricsCollector {
         this.config = config;
         this.sink = config.sink || this.memory;
         this.prefix = config.prefix || 'nexus_ai';
+        warnUnreadOption(config.prometheus !== undefined, 'NEXUS_DEP_METRICS_PROMETHEUS', 'MetricsConfig.prometheus');
     }
     async recordRequest(labels) {
         if (!this.config.enabled)

package/dist/optimizer/index.js

@@ -1,6 +1,7 @@
 import { Tokenizer } from '../utils/tokenizer.js';
 import { PromptDensifier } from './densifier.js';
 import { BudgetEnforcer } from './budget.js';
+import { warnUnreadOption } from '../utils/deprecation.js';
 export class TokenOptimizer {
     config;
     tokenizer = new Tokenizer();
@@ -8,6 +9,7 @@ export class TokenOptimizer {
     budget = new BudgetEnforcer(this.tokenizer);
     constructor(config = {}) {
         this.config = config;
+        warnUnreadOption(config.densification?.preserveMarkdown !== undefined, 'NEXUS_DEP_DENSIFICATION_PRESERVE_MARKDOWN', 'DensificationConfig.preserveMarkdown');
     }
     optimize(request) {
         if (this.config.enabled === false) {

package/dist/postgres/index.d.ts

@@ -5,13 +5,17 @@ export { operationStoreMigration, PostgresOperationStore, type PostgresOperation
 export { PostgresPromptStore, type PostgresPromptStoreOptions, promptStoreMigration } from './prompts.js';
 export { PostgresStore, type PostgresStoreOptions, storeMigration } from './store.js';
 export { PostgresTraceStore, type PostgresTraceStoreOptions, traceStoreMigration } from './traces.js';
+export { PostgresVectorStore, type PostgresVectorStoreOptions, vectorStoreMigration } from './vectors.js';
 /** The Postgres adapters a migration can include. */
-export type PostgresAdapter = 'operations' | 'store' | 'traces' | 'evaluation' | 'circuits' | 'prompts';
+export type PostgresAdapter = 'operations' | 'store' | 'traces' | 'evaluation' | 'circuits' | 'prompts' | 'vectors';
 /** Options for `postgresMigration()`. */
 export interface PostgresMigrationOptions {
-    /** Adapters to include. Defaults to all of them. */
+    /**
+     * Adapters to include. Defaults to every one but `vectors`, which needs pgvector and
+     * `vectorDimensions`, so it is included only when named.
+     */
     adapters?: readonly PostgresAdapter[];
-    /** Enables pgvector for the long-term store. */
+    /** Enables pgvector for the long-term store, and sets the width of the `vectors` table. */
     vectorDimensions?: number;
 }
 /**

package/dist/postgres/index.js

@@ -4,6 +4,7 @@ import { operationStoreMigration } from './operations.js';
 import { promptStoreMigration } from './prompts.js';
 import { storeMigration } from './store.js';
 import { traceStoreMigration } from './traces.js';
+import { vectorStoreMigration } from './vectors.js';
 export { circuitStoreMigration, PostgresCircuitStateStore, } from './circuits.js';
 export { fromPostgresJs } from './client.js';
 export { evaluationStoreMigration, PostgresDatasetStore, PostgresExperimentStore, } from './evaluate.js';
@@ -11,6 +12,7 @@ export { operationStoreMigration, PostgresOperationStore } from './operations.js
 export { PostgresPromptStore, promptStoreMigration } from './prompts.js';
 export { PostgresStore, storeMigration } from './store.js';
 export { PostgresTraceStore, traceStoreMigration } from './traces.js';
+export { PostgresVectorStore, vectorStoreMigration } from './vectors.js';
 export function postgresMigration(options = {}) {
     const adapters = new Set(options.adapters ?? ['operations', 'store', 'traces', 'evaluation', 'circuits', 'prompts']);
     const statements = [
@@ -22,6 +24,12 @@ export function postgresMigration(options = {}) {
         ...(adapters.has('evaluation') ? evaluationStoreMigration() : []),
         ...(adapters.has('circuits') ? circuitStoreMigration() : []),
         ...(adapters.has('prompts') ? promptStoreMigration() : []),
+        ...(adapters.has('vectors') ? vectorMigrationFor(options.vectorDimensions) : []),
     ];
     return `${statements.join(';\n\n')};\n`;
 }
+function vectorMigrationFor(dimensions) {
+    if (dimensions === undefined)
+        throw new RangeError('The vectors adapter needs vectorDimensions');
+    return vectorStoreMigration({ dimensions });
+}

package/dist/postgres/vectors.d.ts

@@ -0,0 +1,46 @@
+import { type EmbeddingProvider, type VectorDocument, type VectorSearchOptions, type VectorSearchResult, type VectorStore } from '../hallucination/retrieval.js';
+import { type PostgresLikeClient } from './client.js';
+/** Options for the pgvector store. */
+export interface PostgresVectorStoreOptions {
+    /** Width of every vector. Must match the embedding function's output. */
+    dimensions: number;
+    /** Embeds chunks that arrive without a vector, and search queries. Defaults to hashed term vectors. */
+    embed?: EmbeddingProvider;
+    /** Table name, optionally schema-qualified. Defaults to `nexus_vectors`. */
+    table?: string;
+    /**
+     * The approximate index created by `migrate()`. `hnsw` (the default) answers a search without
+     * scanning every row, at the cost of slower writes; `none` scans exactly, which suits a few
+     * thousand chunks.
+     */
+    index?: 'hnsw' | 'none';
+}
+/** The schema, as statements: the pgvector extension, the table, and its index. */
+export declare function vectorStoreMigration(options: Omit<PostgresVectorStoreOptions, 'embed'>): string[];
+/**
+ * Retrieval chunks in Postgres with pgvector, ranked by cosine similarity in the database.
+ *
+ * The same contract as `MemoryVectorStore`, checked by the same tests. Only the nearest chunks leave
+ * the database, so a search costs the same whether the table holds a thousand chunks or ten million.
+ * Adding a chunk whose id exists replaces it, and a metadata filter runs in SQL.
+ */
+export declare class PostgresVectorStore implements VectorStore {
+    private readonly client;
+    private readonly options;
+    private readonly table;
+    private readonly embed;
+    constructor(client: PostgresLikeClient, options: PostgresVectorStoreOptions);
+    /** Creates the extension, table, and index. Never runs implicitly. */
+    migrate(): Promise<void>;
+    /** Adds chunks, or replaces those whose id exists, embedding those without a vector in one batch. */
+    add(documents: VectorDocument[]): Promise<void>;
+    /** The chunks most similar to a query, best first. */
+    search(query: string, options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
+    /** The chunks most similar to a vector, best first. */
+    searchVector(vector: number[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
+    /** Removes chunks by id. */
+    delete(ids: readonly string[]): Promise<void>;
+    /** Chunks stored. */
+    size(): Promise<number>;
+    private assertWidth;
+}

package/dist/postgres/vectors.js

@@ -0,0 +1,100 @@
+import { createHashEmbeddings, } from '../hallucination/retrieval.js';
+import { fromJson, quoteDerived, quoteTable, runStatements } from './client.js';
+import { SqlParams, textArray } from './sql.js';
+const DEFAULT_TABLE = 'nexus_vectors';
+export function vectorStoreMigration(options) {
+    const dimensions = options.dimensions;
+    if (!(Number.isInteger(dimensions) && dimensions > 0))
+        throw new RangeError('dimensions must be a positive integer');
+    const name = options.table ?? DEFAULT_TABLE;
+    const table = quoteTable(name);
+    return [
+        'CREATE EXTENSION IF NOT EXISTS vector',
+        `CREATE TABLE IF NOT EXISTS ${table} (
+  id text PRIMARY KEY,
+  content text NOT NULL,
+  source text,
+  metadata jsonb,
+  embedding vector(${dimensions}) NOT NULL
+)`,
+        ...(options.index === 'none'
+            ? []
+            : [
+                `CREATE INDEX IF NOT EXISTS ${quoteDerived(name, 'embedding')} ON ${table} USING hnsw (embedding vector_cosine_ops)`,
+            ]),
+    ];
+}
+export class PostgresVectorStore {
+    client;
+    options;
+    table;
+    embed;
+    constructor(client, options) {
+        this.client = client;
+        this.options = options;
+        if (!(Number.isInteger(options.dimensions) && options.dimensions > 0)) {
+            throw new RangeError('dimensions must be a positive integer');
+        }
+        this.table = quoteTable(options.table ?? DEFAULT_TABLE);
+        this.embed = options.embed ?? ((texts) => createHashEmbeddings(texts, options.dimensions));
+    }
+    async migrate() {
+        await runStatements(this.client, vectorStoreMigration(this.options));
+    }
+    async add(documents) {
+        if (documents.length === 0)
+            return;
+        const missing = documents.filter((doc) => !doc.embedding).map((doc) => doc.content);
+        const generated = missing.length ? await this.embed(missing) : [];
+        let generatedIndex = 0;
+        const params = new SqlParams();
+        const rows = documents.map((doc) => {
+            const embedding = doc.embedding ?? generated[generatedIndex++];
+            this.assertWidth(embedding);
+            return `(${params.add(doc.id)}, ${params.add(doc.content)}, ${params.add(doc.source ?? null)}, ${params.add(doc.metadata === undefined ? null : JSON.stringify(doc.metadata))}::jsonb, ${params.add(JSON.stringify(embedding))}::vector)`;
+        });
+        await this.client.query(`INSERT INTO ${this.table} (id, content, source, metadata, embedding) VALUES ${rows.join(', ')}
+       ON CONFLICT (id) DO UPDATE SET content = EXCLUDED.content, source = EXCLUDED.source,
+         metadata = EXCLUDED.metadata, embedding = EXCLUDED.embedding`, params.values);
+    }
+    async search(query, options = {}) {
+        const [vector] = await this.embed([query]);
+        return this.searchVector(vector, options);
+    }
+    async searchVector(vector, options = {}) {
+        this.assertWidth(vector);
+        const params = new SqlParams();
+        const query = params.add(JSON.stringify(vector));
+        const conditions = [];
+        if (options.filter && Object.keys(options.filter).length > 0) {
+            conditions.push(`metadata @> ${params.add(JSON.stringify(options.filter))}::jsonb`);
+        }
+        const minScore = options.minScore ?? 0;
+        conditions.push(`1 - (embedding <=> ${query}::vector) >= ${params.add(minScore)}`);
+        const limit = params.add(options.topK || 5);
+        const { rows } = await this.client.query(`SELECT id, content, source, metadata::text AS metadata, 1 - (embedding <=> ${query}::vector) AS score
+       FROM ${this.table} WHERE ${conditions.join(' AND ')}
+       ORDER BY embedding <=> ${query}::vector LIMIT ${limit}`, params.values);
+        return rows.map((row) => ({
+            id: row.id,
+            content: row.content,
+            ...(row.source === null ? {} : { source: row.source }),
+            ...(row.metadata === null ? {} : { metadata: fromJson(row.metadata) }),
+            score: Number(row.score),
+        }));
+    }
+    async delete(ids) {
+        if (ids.length === 0)
+            return;
+        await this.client.query(`DELETE FROM ${this.table} WHERE id = ANY($1::text[])`, [textArray(ids)]);
+    }
+    async size() {
+        const { rows } = await this.client.query(`SELECT count(*)::int AS count FROM ${this.table}`);
+        return Number(rows[0]?.count ?? 0);
+    }
+    assertWidth(vector) {
+        if (!vector || vector.length !== this.options.dimensions) {
+            throw new RangeError(`A vector has ${vector?.length ?? 0} dimensions; this store was created with ${this.options.dimensions}`);
+        }
+    }
+}

package/dist/providers/google.js

@@ -1,4 +1,5 @@
 import { BaseProvider } from './base.js';
+import { warnUnreadOption } from '../utils/deprecation.js';
 import { buildMeta } from '../core/usage.js';
 import { generateRequestId } from '../utils/ids.js';
 import { createProviderHttpError, toNexusProviderError } from './errors.js';
@@ -28,6 +29,7 @@ export class GoogleProvider extends BaseProvider {
     constructor(config) {
         super();
         this.config = config;
+        warnUnreadOption(config.projectId !== undefined, 'NEXUS_DEP_GOOGLE_PROJECT_ID', 'GoogleProviderConfig.projectId');
     }
     async complete(request) {
         try {

package/dist/providers/ollama.js

@@ -1,4 +1,5 @@
 import { BaseProvider } from './base.js';
+import { warnUnreadOption } from '../utils/deprecation.js';
 import { buildMeta } from '../core/usage.js';
 export class OllamaProvider extends BaseProvider {
     info = { name: 'ollama', isLocal: true };
@@ -7,6 +8,7 @@ export class OllamaProvider extends BaseProvider {
     constructor(config) {
         super();
         this.config = config;
+        warnUnreadOption(config.timeout !== undefined, 'NEXUS_DEP_OLLAMA_TIMEOUT', 'OllamaProviderConfig.timeout');
     }
     async getClient() {
         if (!this.client) {

package/dist/rag/ingestion.d.ts

@@ -1,4 +1,6 @@
 import type { RagChunk } from '../hallucination/rag.js';
+export { MemoryVectorStore, createHashEmbeddings, cosineSimilarity, matchesMetadata, normalizeVector, type EmbeddingProvider, type VectorDocument, type VectorSearchOptions, type VectorSearchResult, type VectorStore, } from '../hallucination/retrieval.js';
+export type { RagChunk } from '../hallucination/rag.js';
 /** A document to split into chunks. */
 export interface DocumentSource {
     /** Its id, used in chunk ids. Defaults to `doc-1`, `doc-2`, and so on. */

package/dist/rag/ingestion.js

@@ -1,3 +1,4 @@
+export { MemoryVectorStore, createHashEmbeddings, cosineSimilarity, matchesMetadata, normalizeVector, } from '../hallucination/retrieval.js';
 export function ingestDocuments(documents, options = {}) {
     const chunks = [];
     const chunkSize = options.chunkSize || 1200;