@memberjunction/ai-vectordb 5.20.0 → 5.22.0

package/README.md

@@ -1,6 +1,6 @@
 # @memberjunction/ai-vectordb
 
-A provider-agnostic abstraction layer for vector databases in MemberJunction. This package defines the abstract base class, type system, and query interfaces that concrete vector database implementations (such as Pinecone) must fulfill.
+A provider-agnostic abstraction layer for vector databases in MemberJunction. This package defines the `VectorDBBase` abstract class and all associated types that concrete vector database implementations must fulfill. It contains no provider-specific logic -- only the contracts, data structures, and query interfaces shared across all implementations.
 
 ## Architecture
 
@@ -9,7 +9,7 @@ graph TD
     subgraph Abstraction["@memberjunction/ai-vectordb"]
         VDBB["VectorDBBase (abstract)"]
         VR["VectorRecord"]
-        QO["QueryOptions"]
+        QO["QueryOptions / HybridQueryOptions"]
         QR["QueryResponse / ScoredRecord"]
         IDX["IndexDescription / IndexList"]
         BR["BaseResponse"]
@@ -37,29 +37,47 @@ graph TD
     style Consumers fill:#7c5295,stroke:#563a6b,color:#fff
 ```
 
+All vector database providers extend `VectorDBBase` and implement its abstract methods. Consumer code programs against the base class, making it straightforward to swap providers without changing application logic.
+
 ## Installation
 
 ```bash
 npm install @memberjunction/ai-vectordb
 ```
 
-## Overview
-
-This package provides:
+## Quick Start
 
-- **VectorDBBase** -- an abstract class that defines a complete API for vector database operations (index management + record CRUD + similarity queries)
-- **Record types** -- `VectorRecord`, `RecordValues`, `RecordSparseValues`, `RecordMetadata` for representing vectors and their metadata
-- **Query types** -- `QueryOptions`, `QueryResponse`, `ScoredRecord` for similarity search
-- **Index types** -- `IndexDescription`, `IndexList`, `IndexModelMetricEnum` for index configuration
-- **Response types** -- `BaseResponse` for standardized success/failure responses
+```typescript
+import { VectorDBBase, VectorRecord } from '@memberjunction/ai-vectordb';
 
-Concrete implementations like `@memberjunction/ai-vectors-pinecone` extend `VectorDBBase` to connect to specific vector database services.
+// Use any concrete provider that extends VectorDBBase
+const db: VectorDBBase = new PineconeDatabase(apiKey);
 
-## Core Components
+// Insert a vector record
+const record: VectorRecord = {
+    id: 'doc-001',
+    values: [0.1, 0.2, 0.3 /* ... */],
+    metadata: { entity: 'Products', recordId: '12345' }
+};
+await db.createRecord(record);
+
+// Query for similar vectors
+const result = await db.queryIndex({
+    vector: [0.1, 0.2, 0.3 /* ... */],
+    topK: 10,
+    includeMetadata: true
+});
+
+if (result.success) {
+    for (const match of result.data.matches) {
+        console.log(`Match: ${match.id} (score: ${match.score})`);
+    }
+}
+```
 
-### VectorDBBase (Abstract Class)
+## VectorDBBase Abstract Class
 
-All vector database providers must extend this class. The constructor requires an API key, which is validated and stored for subclass access via a protected getter.
+All vector database providers must extend this class. The constructor requires an API key, which is validated (must be non-empty) and stored for subclass access via a protected getter.
 
 ```mermaid
 classDiagram
@@ -67,12 +85,14 @@ classDiagram
         <<abstract>>
         #apiKey : string
         +constructor(apiKey: string)
+        +SupportsHybridSearch : boolean
         +listIndexes()* IndexList
         +getIndex(params)* BaseResponse
         +createIndex(params)* BaseResponse
         +deleteIndex(params)* BaseResponse
         +editIndex(params)* BaseResponse
         +queryIndex(params)* BaseResponse
+        +HybridQuery(params) BaseResponse
         +createRecord(record)* BaseResponse
         +createRecords(records)* BaseResponse
         +getRecord(params)* BaseResponse
@@ -88,213 +108,415 @@ classDiagram
         +queryIndex(params) BaseResponse
     }
 
+    class CustomProvider {
+        +SupportsHybridSearch : boolean
+        +HybridQuery(params) BaseResponse
+    }
+
     VectorDBBase <|-- PineconeDatabase
+    VectorDBBase <|-- CustomProvider
 
     style VectorDBBase fill:#2d6a9f,stroke:#1a4971,color:#fff
     style PineconeDatabase fill:#2d8659,stroke:#1a5c3a,color:#fff
+    style CustomProvider fill:#2d8659,stroke:#1a5c3a,color:#fff
 ```
 
-The abstract methods support both synchronous and asynchronous return types via union types (`BaseResponse | Promise<BaseResponse>`), allowing implementations to choose the appropriate pattern.
+All abstract methods use union return types (`BaseResponse | Promise<BaseResponse>`) so subclasses can implement them as either synchronous or asynchronous.
 
-### Type System
+## Abstract Methods Reference
 
-#### Vector Records
-
-```typescript
-// Core vector record with generic metadata support
-type VectorRecord<T extends RecordMetadata = RecordMetadata> = {
-    id: string;                          // Unique record identifier
-    values: RecordValues;                // Dense vector (array of numbers)
-    sparseValues?: RecordSparseValues;   // Optional sparse representation for hybrid search
-    metadata?: T;                        // Arbitrary filterable metadata
-};
+### Index Operations
 
-type RecordValues = Array<number>;
+| Method | Parameters | Returns | Description |
+|---|---|---|---|
+| `listIndexes()` | none | `IndexList` | List all indexes in the project. |
+| `getIndex(params)` | `BaseRequestParams` | `BaseResponse` | Retrieve configuration details for a single index by ID. |
+| `createIndex(params)` | `CreateIndexParams` | `BaseResponse` | Create a new vector index with specified dimension, metric, and optional provider-specific params. |
+| `deleteIndex(params)` | `BaseRequestParams` | `BaseResponse` | Permanently delete an index and all its records. |
+| `editIndex(params)` | `EditIndexParams` | `BaseResponse` | Modify an existing index's configuration. |
+| `queryIndex(params)` | `QueryOptions` | `BaseResponse` | Execute a similarity search against an index by vector values or by record ID. |
 
-type RecordSparseValues = {
-    indices: Array<number>;   // Non-zero positions
-    values: Array<number>;    // Corresponding values
-};
+### Record Operations
 
-type RecordMetadataValue = string | boolean | number | Array<string>;
-type RecordMetadata = Record<string, RecordMetadataValue>;
-```
+| Method | Parameters | Returns | Description |
+|---|---|---|---|
+| `createRecord(record)` | `VectorRecord` | `BaseResponse` | Insert a single vector record into an index. |
+| `createRecords(records)` | `VectorRecord[]` | `BaseResponse` | Insert multiple vector records in batch. |
+| `getRecord(params)` | `BaseRequestParams` | `BaseResponse` | Fetch a single record by ID. |
+| `getRecords(params)` | `BaseRequestParams` | `BaseResponse` | Fetch multiple records (IDs passed via `data`). |
+| `updateRecord(record)` | `UpdateOptions` | `BaseResponse` | Update a single record's vector values and/or metadata. |
+| `updateRecords(records)` | `UpdateOptions` | `BaseResponse` | Update multiple records in batch. |
+| `deleteRecord(record)` | `VectorRecord` | `BaseResponse` | Delete a single record from an index. |
+| `deleteRecords(records)` | `VectorRecord[]` | `BaseResponse` | Delete multiple records in batch. |
 
-#### Index Configuration
+### Virtual Methods (Non-Abstract)
 
-```typescript
-type IndexDescription = {
-    name: string;                       // Index name (max 45 chars)
-    dimension: number;                  // Vector dimensionality
-    metric: IndexModelMetricEnum;       // 'cosine' | 'euclidean' | 'dotproduct'
-    host: string;                       // Hosting URL
-};
-```
+| Method | Parameters | Returns | Description |
+|---|---|---|---|
+| `SupportsHybridSearch` (getter) | none | `boolean` | Returns `false` by default. Override to return `true` in providers that implement `HybridQuery()`. |
+| `HybridQuery(params)` | `HybridQueryOptions` | `BaseResponse` | Perform a hybrid search combining vector similarity with keyword matching. Default implementation falls back to `queryIndex()`. |
 
-#### Query Types
+## Hybrid Search
 
-```mermaid
-graph LR
-    QPB["QueryParamsBase<br/>topK, includeValues,<br/>includeMetadata, filter"]
-    QBV["QueryByVectorValues<br/>+ vector"]
-    QBID["QueryByRecordId<br/>+ id"]
-    QO["QueryOptions"]
+Hybrid search combines dense vector similarity (semantic search) with sparse keyword matching (BM25) to produce more relevant results than either technique alone. This is particularly useful when queries contain specific terms (product names, codes, identifiers) that benefit from exact text matching alongside semantic understanding.
 
-    QPB --> QBV
-    QPB --> QBID
-    QBV --> QO
-    QBID --> QO
+### How It Works
 
-    style QPB fill:#2d6a9f,stroke:#1a4971,color:#fff
-    style QBV fill:#2d8659,stroke:#1a5c3a,color:#fff
-    style QBID fill:#2d8659,stroke:#1a5c3a,color:#fff
-    style QO fill:#b8762f,stroke:#8a5722,color:#fff
-```
+1. **Check support**: Read the `SupportsHybridSearch` getter before calling `HybridQuery()`.
+2. **Call HybridQuery**: Pass both a vector embedding and an optional keyword query string.
+3. **Fallback behavior**: If the provider does not override `HybridQuery()`, the base class automatically falls back to a pure vector `queryIndex()` call, ignoring keyword-specific parameters (`KeywordQuery`, `Alpha`, `FusionMethod`). This means consumer code does not need to branch on provider capability -- it is always safe to call `HybridQuery()`.
 
-```typescript
-// Base query parameters shared by all query types
-type QueryParamsBase = {
-    topK: number;               // Number of results to return
-    includeValues?: boolean;    // Include vector values in results
-    includeMetadata?: boolean;  // Include metadata in results
-    filter?: object;            // Metadata filter
-};
+### HybridQueryOptions
 
-// Query by providing a vector directly
-type QueryByVectorValues = QueryParamsBase & { vector: RecordValues };
+`HybridQueryOptions` extends `QueryParamsBase` with the following additional fields:
 
-// Query using an existing record's vector
-type QueryByRecordId = QueryParamsBase & { id: string };
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `vector` | `RecordValues` | Yes | Embedding vector for the semantic similarity component. |
+| `KeywordQuery` | `string` | No | Keyword query string for BM25/text search. |
+| `Alpha` | `number` | No | Balance between vector and keyword results. `0.0` = pure keyword, `1.0` = pure vector. Default: `0.7`. |
+| `FusionMethod` | `'rrf' \| 'weighted'` | No | Strategy for fusing vector and keyword result lists. Default: `'rrf'` (Reciprocal Rank Fusion). |
 
-// Union type for all query configurations
-type QueryOptions = QueryByRecordId | QueryByVectorValues;
-```
+Plus the inherited `QueryParamsBase` fields: `topK`, `includeValues`, `includeMetadata`, `filter`.
 
-#### Query Response
+### Implementing Hybrid Search in a Provider
 
 ```typescript
-type QueryResponse<T extends RecordMetadata = RecordMetadata> = {
-    matches: Array<ScoredRecord<T>>;  // Sorted by similarity
-    namespace: string;                 // Execution namespace
-    usage?: OperationUsage;            // Read unit consumption
-};
+import { VectorDBBase, HybridQueryOptions, BaseResponse } from '@memberjunction/ai-vectordb';
+
+export class WeaviateDB extends VectorDBBase {
+    public override get SupportsHybridSearch(): boolean {
+        return true;
+    }
+
+    public override async HybridQuery(params: HybridQueryOptions): Promise<BaseResponse> {
+        const results = await this.client.hybridSearch({
+            vector: params.vector,
+            query: params.KeywordQuery,
+            alpha: params.Alpha ?? 0.7,
+            fusionType: params.FusionMethod ?? 'rrf',
+            limit: params.topK,
+            includeMetadata: params.includeMetadata
+        });
+        return { success: true, message: 'Hybrid query complete', data: results };
+    }
 
-interface ScoredRecord<T> extends VectorRecord<T> {
-    score?: number;  // Similarity score (interpretation depends on metric)
+    // ... remaining abstract method implementations
 }
 ```
 
-#### Standardized Response
-
-All operations return a `BaseResponse`:
+### Consumer Usage
 
 ```typescript
-type BaseResponse = {
-    success: boolean;
-    message: string;
-    data: unknown;
-};
+const db: VectorDBBase = getVectorProvider();
+
+// Safe to call regardless of provider -- falls back to pure vector search
+const results = await db.HybridQuery({
+    vector: embedding,
+    KeywordQuery: 'quarterly revenue report',
+    Alpha: 0.6,
+    topK: 20,
+    includeMetadata: true
+});
+
+// Or check support for conditional UI behavior
+if (db.SupportsHybridSearch) {
+    showKeywordSearchInput();
+}
 ```
 
-## Usage
+## Implementing a Custom Provider
 
-### Implementing a Provider
+Follow these steps to add support for a new vector database (e.g., Weaviate, Qdrant, Milvus).
+
+### Step 1: Create the Provider Class
 
 ```typescript
 import {
     VectorDBBase,
-    VectorRecord,
+    BaseRequestParams,
     BaseResponse,
     CreateIndexParams,
+    EditIndexParams,
+    IndexList,
     QueryOptions,
-    IndexList
+    UpdateOptions,
+    VectorRecord
 } from '@memberjunction/ai-vectordb';
 
-export class MyVectorDB extends VectorDBBase {
-    constructor(apiKey: string) {
-        super(apiKey); // Validates and stores the API key
+export class QdrantDB extends VectorDBBase {
+    private client: QdrantClient;
+
+    constructor(apiKey: string, host: string) {
+        super(apiKey); // Validates the API key
+        this.client = new QdrantClient({ apiKey: this.apiKey, host });
     }
 
     async listIndexes(): Promise<IndexList> {
-        // Call your vector DB API using this.apiKey
-        return { indexes: [] };
+        const collections = await this.client.getCollections();
+        return {
+            indexes: collections.map(c => ({
+                name: c.name,
+                dimension: c.vectors.size,
+                metric: c.vectors.distance,
+                host: this.host
+            }))
+        };
+    }
+
+    async getIndex(params: BaseRequestParams): Promise<BaseResponse> {
+        const info = await this.client.getCollection(params.id);
+        return { success: true, message: 'Index retrieved', data: info };
     }
 
     async createIndex(params: CreateIndexParams): Promise<BaseResponse> {
-        return { success: true, message: 'Created', data: { id: params.id } };
+        await this.client.createCollection(params.id, {
+            vectors: { size: params.dimension, distance: params.metric }
+        });
+        return { success: true, message: 'Index created', data: null };
+    }
+
+    async deleteIndex(params: BaseRequestParams): Promise<BaseResponse> {
+        await this.client.deleteCollection(params.id);
+        return { success: true, message: 'Index deleted', data: null };
+    }
+
+    async editIndex(params: EditIndexParams): Promise<BaseResponse> {
+        await this.client.updateCollection(params.id, params.data);
+        return { success: true, message: 'Index updated', data: null };
     }
 
     async queryIndex(params: QueryOptions): Promise<BaseResponse> {
-        // Perform similarity search
-        return { success: true, message: 'OK', data: { matches: [] } };
+        const results = await this.client.search(params);
+        return { success: true, message: 'Query complete', data: results };
+    }
+
+    async createRecord(record: VectorRecord): Promise<BaseResponse> {
+        await this.client.upsert([record]);
+        return { success: true, message: 'Record created', data: null };
+    }
+
+    async createRecords(records: VectorRecord[]): Promise<BaseResponse> {
+        await this.client.upsert(records);
+        return { success: true, message: `${records.length} records created`, data: null };
+    }
+
+    async getRecord(params: BaseRequestParams): Promise<BaseResponse> {
+        const record = await this.client.retrieve(params.id);
+        return { success: true, message: 'Record retrieved', data: record };
+    }
+
+    async getRecords(params: BaseRequestParams): Promise<BaseResponse> {
+        const records = await this.client.retrieveMany(params.data);
+        return { success: true, message: 'Records retrieved', data: records };
+    }
+
+    async updateRecord(record: UpdateOptions): Promise<BaseResponse> {
+        await this.client.update(record);
+        return { success: true, message: 'Record updated', data: null };
+    }
+
+    async updateRecords(records: UpdateOptions): Promise<BaseResponse> {
+        await this.client.updateMany(records);
+        return { success: true, message: 'Records updated', data: null };
     }
 
-    // ... implement remaining abstract methods
+    async deleteRecord(record: VectorRecord): Promise<BaseResponse> {
+        await this.client.delete(record.id);
+        return { success: true, message: 'Record deleted', data: null };
+    }
+
+    async deleteRecords(records: VectorRecord[]): Promise<BaseResponse> {
+        await this.client.deleteMany(records.map(r => r.id));
+        return { success: true, message: 'Records deleted', data: null };
+    }
 }
 ```
 
-### Consuming a Provider
+### Step 2: Register with MemberJunction Class Factory (Optional)
+
+If you want MemberJunction's class factory to discover your provider automatically:
 
 ```typescript
-import { VectorDBBase, VectorRecord } from '@memberjunction/ai-vectordb';
+import { RegisterClass } from '@memberjunction/global';
+
+@RegisterClass(VectorDBBase, 'QdrantDB')
+export class QdrantDB extends VectorDBBase {
+    // ... implementation
+}
+```
 
-async function searchSimilar(vectorDB: VectorDBBase, embedding: number[]): Promise<void> {
-    // Insert a record
-    const record: VectorRecord = {
-        id: 'doc-001',
-        values: embedding,
-        metadata: { entity: 'Products', recordId: '12345' }
-    };
-    await vectorDB.createRecord(record);
-
-    // Query for similar vectors
-    const result = await vectorDB.queryIndex({
-        vector: embedding,
-        topK: 10,
-        includeMetadata: true
-    });
-
-    if (result.success) {
-        for (const match of result.data.matches) {
-            console.log(`Match: ${match.id} (score: ${match.score})`);
-        }
+### Step 3: Add Hybrid Search Support (Optional)
+
+If your vector database supports hybrid search natively, override the getter and method:
+
+```typescript
+export class QdrantDB extends VectorDBBase {
+    public override get SupportsHybridSearch(): boolean {
+        return true;
+    }
+
+    public override async HybridQuery(params: HybridQueryOptions): Promise<BaseResponse> {
+        // Use your provider's native hybrid search API
+        const results = await this.client.hybridSearch({
+            vector: params.vector,
+            keyword: params.KeywordQuery,
+            alpha: params.Alpha ?? 0.7,
+            limit: params.topK
+        });
+        return { success: true, message: 'Hybrid query complete', data: results };
     }
 }
 ```
 
+## QueryOptions Reference
+
+`QueryOptions` is a union type supporting two query strategies:
+
+```mermaid
+graph LR
+    QPB["QueryParamsBase<br/>topK, includeValues,<br/>includeMetadata, filter"]
+    QBV["QueryByVectorValues<br/>+ vector"]
+    QBID["QueryByRecordId<br/>+ id"]
+    QO["QueryOptions"]
+
+    QPB --> QBV
+    QPB --> QBID
+    QBV --> QO
+    QBID --> QO
+
+    style QPB fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style QBV fill:#2d8659,stroke:#1a5c3a,color:#fff
+    style QBID fill:#2d8659,stroke:#1a5c3a,color:#fff
+    style QO fill:#b8762f,stroke:#8a5722,color:#fff
+```
+
+### QueryParamsBase
+
+Shared query parameters inherited by both query strategies.
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `topK` | `number` | Yes | Number of results to return. |
+| `includeValues` | `boolean` | No | Whether to include embedding vectors in results. Default: `false`. |
+| `includeMetadata` | `boolean` | No | Whether to include metadata in results. Default: `false`. |
+| `filter` | `object` | No | Metadata filter to narrow the search scope. |
+
+### QueryByVectorValues
+
+Query by providing a vector directly. Extends `QueryParamsBase`.
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `vector` | `RecordValues` | Yes | Vector values output from an embedding model. |
+
+### QueryByRecordId
+
+Query using an existing record's stored vector. Extends `QueryParamsBase`.
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | Yes | ID of an existing record whose vector to use for the query. |
+
+### Usage Examples
+
+```typescript
+// Query by vector values
+const resultByVector = await db.queryIndex({
+    vector: [0.1, 0.2, 0.3],
+    topK: 5,
+    includeMetadata: true,
+    filter: { category: 'finance' }
+});
+
+// Query by record ID (find similar to an existing record)
+const resultById = await db.queryIndex({
+    id: 'doc-001',
+    topK: 10,
+    includeMetadata: true
+});
+```
+
+## Type Reference
+
+### Core Types
+
+| Type | Description |
+|---|---|
+| `VectorRecord<T>` | A vector record with `id`, `values` (dense embedding), optional `sparseValues`, and optional `metadata`. Generic over metadata type. |
+| `RecordValues` | `Array<number>` -- a dense embedding vector. |
+| `RecordSparseValues` | Sparse vector representation with parallel `indices` and `values` arrays for non-zero positions. |
+| `RecordMetadata` | `Record<string, RecordMetadataValue>` -- arbitrary key-value metadata attached to records. |
+| `RecordMetadataValue` | `string \| boolean \| number \| Array<string>` -- valid metadata value types. |
+| `BaseResponse` | Standard response envelope: `success` (boolean), `message` (string), `data` (result payload). |
+
+### Index Types
+
+| Type | Description |
+|---|---|
+| `IndexDescription` | Describes an index: `name` (max 45 chars), `dimension`, `metric`, and `host` URL. |
+| `IndexList` | Container with an optional `indexes` array of `IndexDescription`. |
+| `IndexModelMetricEnum` | `'cosine' \| 'euclidean' \| 'dotproduct'` distance metrics for similarity comparison. |
+
+### Request/Options Types
+
+| Type | Description |
+|---|---|
+| `BaseRequestParams` | Base request with `id` (string) and optional `data`. |
+| `CreateIndexParams` | Extends `BaseRequestParams` with `dimension` (number), `metric` (IndexModelMetricEnum), and optional `additionalParams`. |
+| `EditIndexParams` | Extends `BaseRequestParams` for index configuration changes. |
+| `UpdateOptions<T>` | Record update with `id`, optional `values`, optional `sparseValues`, and optional `metadata`. Values are optional to support metadata-only updates. |
+
+### Query Types
+
+| Type | Description |
+|---|---|
+| `QueryParamsBase` | Shared query parameters: `topK`, `includeValues`, `includeMetadata`, `filter`. |
+| `QueryByRecordId` | Extends `QueryParamsBase` with `id` -- query using an existing record's vector. |
+| `QueryByVectorValues` | Extends `QueryParamsBase` with `vector` -- query using a raw embedding array. |
+| `QueryOptions` | Union of `QueryByRecordId \| QueryByVectorValues`. |
+| `HybridQueryOptions` | Extends `QueryParamsBase` with `vector`, `KeywordQuery`, `Alpha`, and `FusionMethod` for combined vector + keyword search. |
+| `QueryResponse<T>` | Query result containing `matches` (sorted `ScoredRecord` array), `namespace`, and optional `usage`. |
+| `ScoredRecord<T>` | Extends `VectorRecord` with a `score` field. Score interpretation depends on the index metric. |
+| `OperationUsage` | Usage metrics with optional `readUnits` count. |
+
 ## Distance Metrics
 
 The `IndexModelMetricEnum` supports three metrics for similarity comparison:
 
-| Metric | Description | Use Case |
-|---|---|---|
-| `cosine` | Measures angle between vectors (direction similarity) | Text embeddings, semantic search |
-| `euclidean` | Straight-line distance between points | Numeric features, specifications |
-| `dotproduct` | Measures both direction and magnitude alignment | Recommendation systems, weighted scoring |
+| Metric | Value | Description | Score Interpretation |
+|---|---|---|---|
+| Cosine | `'cosine'` | Measures angle between vectors (direction similarity) | Higher = more similar |
+| Euclidean | `'euclidean'` | Straight-line distance between vector endpoints | Lower = more similar |
+| Dot Product | `'dotproduct'` | Measures both direction and magnitude alignment | Higher = more similar |
 
 ## Available Implementations
 
-| Package | Vector Database |
-|---|---|
-| `@memberjunction/ai-vectors-pinecone` | Pinecone |
+| Package | Provider | Hybrid Search |
+|---|---|---|
+| `@memberjunction/ai-vectors-pinecone` | Pinecone | No |
 
-Create additional implementations by extending `VectorDBBase` and registering with MemberJunction's class factory.
+Create additional implementations by extending `VectorDBBase` and optionally registering with MemberJunction's class factory.
 
 ## Dependencies
 
 | Package | Purpose |
 |---|---|
 | `@memberjunction/core` | Core MemberJunction functionality |
-| `@memberjunction/global` | Global utilities |
+| `@memberjunction/global` | Global utilities and class registration |
 
 ## Development
 
 ```bash
 # Build
+cd packages/AI/Vectors/Database
 npm run build
 
-# Development mode
-npm run start
+# Run tests
+npm run test
+
+# Watch mode
+npm run test:watch
 ```
 
 ## License

package/dist/generic/MetadataFilter.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Metadata filter support for the shared Knowledge Hub vector index.
+ *
+ * Provides a `VectorMetadataFilter` utility that converts high-level
+ * filter options into provider-native filter objects suitable for
+ * passing to `VectorDBBase.QueryIndex()`.
+ *
+ * @module @memberjunction/ai-vectordb
+ */
+/**
+ * Classification of how the vectorized content originated.
+ * Mirrors the type in @memberjunction/ai-vectors for package independence.
+ */
+export type VectorSourceType = 'entity' | 'content-item' | 'file' | 'web-page';
+/**
+ * Filter options for querying the shared vector index.
+ * All fields are optional -- omitted fields mean "no filter on this dimension".
+ * Mirrors the interface in @memberjunction/ai-vectors for package independence.
+ */
+export interface SharedIndexFilterOptions {
+    /** Restrict to specific entity names */
+    EntityNames?: string[];
+    /** Restrict to specific source types */
+    SourceTypes?: VectorSourceType[];
+    /** Restrict to specific MIME content types */
+    ContentTypes?: string[];
+    /** Require all specified tags to be present */
+    Tags?: string[];
+    /** Restrict to specific Entity Document IDs */
+    EntityDocumentIDs?: string[];
+}
+/**
+ * Describes the structure of a single metadata filter condition.
+ * Each vector DB provider translates these into its native filter syntax.
+ */
+export interface MetadataFilterCondition {
+    /** The metadata field name to filter on */
+    Field: string;
+    /** The comparison operator */
+    Operator: 'eq' | 'in' | 'contains';
+    /** The value(s) to compare against */
+    Value: string | string[] | number;
+}
+/**
+ * Utility class for converting `SharedIndexFilterOptions` into a flat array
+ * of `MetadataFilterCondition` objects that vector DB providers can interpret.
+ */
+export declare class VectorMetadataFilter {
+    /**
+     * Convert shared index filter options into an array of filter conditions.
+     * Providers should map these conditions to their native filter syntax
+     * (e.g., Pinecone metadata filters, Weaviate where clauses, etc.).
+     *
+     * @param options - The high-level filter options from the search request
+     * @returns An array of conditions; empty if no filters are specified
+     */
+    static BuildConditions(options: SharedIndexFilterOptions): MetadataFilterCondition[];
+    /**
+     * Convert filter conditions into a simple key-value filter object
+     * compatible with the existing `QueryParamsBase.filter` field.
+     *
+     * This produces a "Pinecone-style" filter using `$in` and `$eq` operators.
+     * Providers with different filter syntax should override or adapt.
+     *
+     * @param conditions - The array of filter conditions to convert
+     * @returns A plain object suitable for `QueryParamsBase.filter`
+     */
+    static ToNativeFilter(conditions: MetadataFilterCondition[]): Record<string, unknown>;
+    /**
+     * Convenience method that converts SharedIndexFilterOptions directly
+     * to a native filter object in one step.
+     *
+     * @param options - The high-level filter options
+     * @returns A native filter object, or undefined if no filters specified
+     */
+    static FromOptions(options: SharedIndexFilterOptions): Record<string, unknown> | undefined;
+}
+//# sourceMappingURL=MetadataFilter.d.ts.map

package/dist/generic/MetadataFilter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MetadataFilter.d.ts","sourceRoot":"","sources":["../../src/generic/MetadataFilter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,cAAc,GAAG,MAAM,GAAG,UAAU,CAAC;AAE/E;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACrC,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,wCAAwC;IACxC,WAAW,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACjC,8CAA8C;IAC9C,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,+CAA+C;IAC/C,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACpC,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,QAAQ,EAAE,IAAI,GAAG,IAAI,GAAG,UAAU,CAAC;IACnC,sCAAsC;IACtC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,CAAC;CACrC;AAED;;;GAGG;AACH,qBAAa,oBAAoB;IAC7B;;;;;;;OAOG;WACW,eAAe,CAAC,OAAO,EAAE,wBAAwB,GAAG,uBAAuB,EAAE;IAgD3F;;;;;;;;;OASG;WACW,cAAc,CAAC,UAAU,EAAE,uBAAuB,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAqB5F;;;;;;OAMG;WACW,WAAW,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;CAOpG"}

package/dist/generic/MetadataFilter.js

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview Metadata filter support for the shared Knowledge Hub vector index.
+ *
+ * Provides a `VectorMetadataFilter` utility that converts high-level
+ * filter options into provider-native filter objects suitable for
+ * passing to `VectorDBBase.QueryIndex()`.
+ *
+ * @module @memberjunction/ai-vectordb
+ */
+/**
+ * Utility class for converting `SharedIndexFilterOptions` into a flat array
+ * of `MetadataFilterCondition` objects that vector DB providers can interpret.
+ */
+export class VectorMetadataFilter {
+    /**
+     * Convert shared index filter options into an array of filter conditions.
+     * Providers should map these conditions to their native filter syntax
+     * (e.g., Pinecone metadata filters, Weaviate where clauses, etc.).
+     *
+     * @param options - The high-level filter options from the search request
+     * @returns An array of conditions; empty if no filters are specified
+     */
+    static BuildConditions(options) {
+        const conditions = [];
+        if (options.EntityNames && options.EntityNames.length > 0) {
+            conditions.push({
+                Field: 'EntityName',
+                Operator: 'in',
+                Value: options.EntityNames,
+            });
+        }
+        if (options.SourceTypes && options.SourceTypes.length > 0) {
+            conditions.push({
+                Field: 'SourceType',
+                Operator: 'in',
+                Value: options.SourceTypes,
+            });
+        }
+        if (options.ContentTypes && options.ContentTypes.length > 0) {
+            conditions.push({
+                Field: 'ContentType',
+                Operator: 'in',
+                Value: options.ContentTypes,
+            });
+        }
+        if (options.Tags && options.Tags.length > 0) {
+            for (const tag of options.Tags) {
+                conditions.push({
+                    Field: 'Tags',
+                    Operator: 'contains',
+                    Value: tag,
+                });
+            }
+        }
+        if (options.EntityDocumentIDs && options.EntityDocumentIDs.length > 0) {
+            conditions.push({
+                Field: 'EntityDocumentID',
+                Operator: 'in',
+                Value: options.EntityDocumentIDs,
+            });
+        }
+        return conditions;
+    }
+    /**
+     * Convert filter conditions into a simple key-value filter object
+     * compatible with the existing `QueryParamsBase.filter` field.
+     *
+     * This produces a "Pinecone-style" filter using `$in` and `$eq` operators.
+     * Providers with different filter syntax should override or adapt.
+     *
+     * @param conditions - The array of filter conditions to convert
+     * @returns A plain object suitable for `QueryParamsBase.filter`
+     */
+    static ToNativeFilter(conditions) {
+        const filter = {};
+        for (const condition of conditions) {
+            switch (condition.Operator) {
+                case 'eq':
+                    filter[condition.Field] = { $eq: condition.Value };
+                    break;
+                case 'in':
+                    filter[condition.Field] = { $in: condition.Value };
+                    break;
+                case 'contains':
+                    // For array fields, "contains" checks if the value is in the array
+                    filter[condition.Field] = { $eq: condition.Value };
+                    break;
+            }
+        }
+        return filter;
+    }
+    /**
+     * Convenience method that converts SharedIndexFilterOptions directly
+     * to a native filter object in one step.
+     *
+     * @param options - The high-level filter options
+     * @returns A native filter object, or undefined if no filters specified
+     */
+    static FromOptions(options) {
+        const conditions = VectorMetadataFilter.BuildConditions(options);
+        if (conditions.length === 0) {
+            return undefined;
+        }
+        return VectorMetadataFilter.ToNativeFilter(conditions);
+    }
+}
+//# sourceMappingURL=MetadataFilter.js.map

package/dist/generic/MetadataFilter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MetadataFilter.js","sourceRoot":"","sources":["../../src/generic/MetadataFilter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAuCH;;;GAGG;AACH,MAAM,OAAO,oBAAoB;IAC7B;;;;;;;OAOG;IACI,MAAM,CAAC,eAAe,CAAC,OAAiC;QAC3D,MAAM,UAAU,GAA8B,EAAE,CAAC;QAEjD,IAAI,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxD,UAAU,CAAC,IAAI,CAAC;gBACZ,KAAK,EAAE,YAAY;gBACnB,QAAQ,EAAE,IAAI;gBACd,KAAK,EAAE,OAAO,CAAC,WAAW;aAC7B,CAAC,CAAC;QACP,CAAC;QAED,IAAI,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxD,UAAU,CAAC,IAAI,CAAC;gBACZ,KAAK,EAAE,YAAY;gBACnB,QAAQ,EAAE,IAAI;gBACd,KAAK,EAAE,OAAO,CAAC,WAAW;aAC7B,CAAC,CAAC;QACP,CAAC;QAED,IAAI,OAAO,CAAC,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1D,UAAU,CAAC,IAAI,CAAC;gBACZ,KAAK,EAAE,aAAa;gBACpB,QAAQ,EAAE,IAAI;gBACd,KAAK,EAAE,OAAO,CAAC,YAAY;aAC9B,CAAC,CAAC;QACP,CAAC;QAED,IAAI,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1C,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;gBAC7B,UAAU,CAAC,IAAI,CAAC;oBACZ,KAAK,EAAE,MAAM;oBACb,QAAQ,EAAE,UAAU;oBACpB,KAAK,EAAE,GAAG;iBACb,CAAC,CAAC;YACP,CAAC;QACL,CAAC;QAED,IAAI,OAAO,CAAC,iBAAiB,IAAI,OAAO,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpE,UAAU,CAAC,IAAI,CAAC;gBACZ,KAAK,EAAE,kBAAkB;gBACzB,QAAQ,EAAE,IAAI;gBACd,KAAK,EAAE,OAAO,CAAC,iBAAiB;aACnC,CAAC,CAAC;QACP,CAAC;QAED,OAAO,UAAU,CAAC;IACtB,CAAC;IAED;;;;;;;;;OASG;IACI,MAAM,CAAC,cAAc,CAAC,UAAqC;QAC9D,MAAM,MAAM,GAA4B,EAAE,CAAC;QAE3C,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACjC,QAAQ,SAAS,CAAC,QAAQ,EAAE,CAAC;gBACzB,KAAK,IAAI;oBACL,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,CAAC,KAAK,EAAE,CAAC;oBACnD,MAAM;gBACV,KAAK,IAAI;oBACL,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,CAAC,KAAK,EAAE,CAAC;oBACnD,MAAM;gBACV,KAAK,UAAU;oBACX,mEAAmE;oBACnE,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,CAAC,KAAK,EAAE,CAAC;oBACnD,MAAM;YACd,CAAC;QACL,CAAC;QAED,OAAO,MAAM,CAAC;IAClB,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,WAAW,CAAC,OAAiC;QACvD,MAAM,UAAU,GAAG,oBAAoB,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QACjE,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,OAAO,oBAAoB,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;IAC3D,CAAC;CACJ"}

package/dist/generic/VectorDBBase.d.ts

@@ -1,25 +1,66 @@
 import { BaseRequestParams, BaseResponse, CreateIndexParams, EditIndexParams, IndexList, UpdateOptions, VectorRecord } from "./record.js";
-import { QueryOptions } from './query.types.js';
+import { HybridQueryOptions, QueryOptions } from './query.types.js';
+import { SharedIndexFilterOptions } from './MetadataFilter.js';
 export declare abstract class VectorDBBase {
     private _apiKey;
     /**
      * Only sub-classes can access the API key
      */
-    protected get apiKey(): string;
+    protected get ApiKey(): string;
     constructor(apiKey: string);
-    abstract listIndexes(): IndexList | Promise<IndexList>;
-    abstract getIndex(params: BaseRequestParams): BaseResponse | Promise<BaseResponse>;
-    abstract createIndex(params: CreateIndexParams): BaseResponse | Promise<BaseResponse>;
-    abstract deleteIndex(params: BaseRequestParams): BaseResponse | Promise<BaseResponse>;
-    abstract editIndex(params: EditIndexParams): BaseResponse | Promise<BaseResponse>;
-    abstract queryIndex(params: QueryOptions): BaseResponse | Promise<BaseResponse>;
-    abstract createRecord(record: VectorRecord): BaseResponse | Promise<BaseResponse>;
-    abstract createRecords(record: VectorRecord[]): BaseResponse | Promise<BaseResponse>;
-    abstract getRecord(param: BaseRequestParams): BaseResponse | Promise<BaseResponse>;
-    abstract getRecords(params: BaseRequestParams): BaseResponse | Promise<BaseResponse>;
-    abstract updateRecord(record: UpdateOptions): BaseResponse | Promise<BaseResponse>;
-    abstract updateRecords(records: UpdateOptions): BaseResponse | Promise<BaseResponse>;
-    abstract deleteRecord(record: VectorRecord): BaseResponse | Promise<BaseResponse>;
-    abstract deleteRecords(records: VectorRecord[]): BaseResponse | Promise<BaseResponse>;
+    abstract ListIndexes(): IndexList | Promise<IndexList>;
+    abstract GetIndex(params: BaseRequestParams): BaseResponse | Promise<BaseResponse>;
+    abstract CreateIndex(params: CreateIndexParams): BaseResponse | Promise<BaseResponse>;
+    abstract DeleteIndex(params: BaseRequestParams): BaseResponse | Promise<BaseResponse>;
+    abstract EditIndex(params: EditIndexParams): BaseResponse | Promise<BaseResponse>;
+    abstract QueryIndex(params: QueryOptions): BaseResponse | Promise<BaseResponse>;
+    abstract CreateRecord(record: VectorRecord, indexName?: string): BaseResponse | Promise<BaseResponse>;
+    abstract CreateRecords(records: VectorRecord[], indexName?: string): BaseResponse | Promise<BaseResponse>;
+    abstract GetRecord(param: BaseRequestParams): BaseResponse | Promise<BaseResponse>;
+    abstract GetRecords(params: BaseRequestParams): BaseResponse | Promise<BaseResponse>;
+    abstract UpdateRecord(record: UpdateOptions): BaseResponse | Promise<BaseResponse>;
+    abstract UpdateRecords(records: UpdateOptions): BaseResponse | Promise<BaseResponse>;
+    abstract DeleteRecord(record: VectorRecord, indexName?: string): BaseResponse | Promise<BaseResponse>;
+    abstract DeleteRecords(records: VectorRecord[], indexName?: string): BaseResponse | Promise<BaseResponse>;
+    /**
+     * Delete ALL records from an index. Use with caution.
+     * @param indexName The name of the index to clear
+     * @param namespace Optional namespace within the index
+     */
+    abstract DeleteAllRecords(indexName: string, namespace?: string): BaseResponse | Promise<BaseResponse>;
+    /**
+     * Whether this provider supports hybrid (vector + keyword) search.
+     * Override and return true in providers that implement HybridQuery().
+     */
+    get SupportsHybridSearch(): boolean;
+    /**
+     * Perform a hybrid search combining vector similarity with keyword (BM25) matching.
+     * Only available on providers where SupportsHybridSearch is true.
+     * Default implementation falls back to a standard vector QueryIndex call.
+     */
+    HybridQuery(params: HybridQueryOptions): BaseResponse | Promise<BaseResponse>;
+    /**
+     * Query the vector index with metadata filtering using SharedIndexFilterOptions.
+     *
+     * Default implementation converts the filter options to a native filter object
+     * and delegates to QueryIndex. Providers can override BuildMetadataFilter()
+     * for custom filter syntax.
+     *
+     * @param params - Standard query options with an additional metadataFilter field
+     * @returns The query response from the vector database
+     */
+    MetadataFilteredQuery(params: QueryOptions & {
+        metadataFilter: SharedIndexFilterOptions;
+    }): BaseResponse | Promise<BaseResponse>;
+    /**
+     * Convert SharedIndexFilterOptions to a provider-native filter object.
+     *
+     * Override this method in provider subclasses to produce provider-specific
+     * filter syntax (e.g., Pinecone, Weaviate, Qdrant, etc.).
+     *
+     * @param options - The high-level filter options
+     * @returns A native filter object, or undefined if no filters
+     */
+    BuildMetadataFilter(options: SharedIndexFilterOptions): object | undefined;
 }
 //# sourceMappingURL=VectorDBBase.d.ts.map

package/dist/generic/VectorDBBase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VectorDBBase.d.ts","sourceRoot":"","sources":["../../src/generic/VectorDBBase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,iBAAiB,EACnD,eAAe,EAAE,SAAS,EAAE,aAAa,EACzC,YAAY,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,8BAAsB,YAAY;IAC9B,OAAO,CAAC,OAAO,CAAS;IACxB;;OAEG;IACH,SAAS,KAAK,MAAM,IAAI,MAAM,CAE7B;gBAEY,MAAM,EAAE,MAAM;IAQ3B,QAAQ,CAAC,WAAW,IAAI,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACtD,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAClF,QAAQ,CAAC,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IACrF,QAAQ,CAAC,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IACrF,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IAClF,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAE/E,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IACjF,QAAQ,CAAC,aAAa,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IACrF,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IACnF,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,iBAAiB,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IACrF,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IACnF,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IACrF,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IAClF,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;CACzF"}
+{"version":3,"file":"VectorDBBase.d.ts","sourceRoot":"","sources":["../../src/generic/VectorDBBase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,iBAAiB,EACnD,eAAe,EAAE,SAAS,EAAE,aAAa,EACzC,YAAY,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,wBAAwB,EAAwB,MAAM,kBAAkB,CAAC;AAElF,8BAAsB,YAAY;IAC9B,OAAO,CAAC,OAAO,CAAS;IACxB;;OAEG;IACH,SAAS,KAAK,MAAM,IAAI,MAAM,CAE7B;gBAEY,MAAM,EAAE,MAAM;IAQ3B,QAAQ,CAAC,WAAW,IAAI,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACtD,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAClF,QAAQ,CAAC,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IACrF,QAAQ,CAAC,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IACrF,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IAClF,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAE/E,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IACrG,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IAC1G,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IACnF,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,iBAAiB,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IACrF,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IACnF,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IACrF,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IACtG,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IAE1G;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAEtG;;;OAGG;IACH,IAAW,oBAAoB,IAAI,OAAO,CAEzC;IAED;;;;OAIG;IACI,WAAW,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAKpF;;;;;;;;;OASG;IACI,qBAAqB,CACxB,MAAM,EAAE,YAAY,GAAG;QAAE,cAAc,EAAE,wBAAwB,CAAA;KAAE,GACpE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAWvC;;;;;;;;OAQG;IACI,mBAAmB,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,GAAG,SAAS;CAGpF"}

package/dist/generic/VectorDBBase.js

@@ -1,8 +1,9 @@
+import { VectorMetadataFilter } from './MetadataFilter.js';
 export class VectorDBBase {
     /**
      * Only sub-classes can access the API key
      */
-    get apiKey() {
+    get ApiKey() {
         return this._apiKey;
     }
     constructor(apiKey) {
@@ -10,5 +11,53 @@ export class VectorDBBase {
             throw new Error('API key cannot be empty');
         this._apiKey = apiKey;
     }
+    /**
+     * Whether this provider supports hybrid (vector + keyword) search.
+     * Override and return true in providers that implement HybridQuery().
+     */
+    get SupportsHybridSearch() {
+        return false;
+    }
+    /**
+     * Perform a hybrid search combining vector similarity with keyword (BM25) matching.
+     * Only available on providers where SupportsHybridSearch is true.
+     * Default implementation falls back to a standard vector QueryIndex call.
+     */
+    HybridQuery(params) {
+        // Default: fall back to pure vector search, ignoring keyword params
+        return this.QueryIndex({ vector: params.vector, topK: params.topK, includeMetadata: params.includeMetadata, includeValues: params.includeValues, filter: params.filter });
+    }
+    /**
+     * Query the vector index with metadata filtering using SharedIndexFilterOptions.
+     *
+     * Default implementation converts the filter options to a native filter object
+     * and delegates to QueryIndex. Providers can override BuildMetadataFilter()
+     * for custom filter syntax.
+     *
+     * @param params - Standard query options with an additional metadataFilter field
+     * @returns The query response from the vector database
+     */
+    MetadataFilteredQuery(params) {
+        const nativeFilter = this.BuildMetadataFilter(params.metadataFilter);
+        const queryParams = {
+            ...params,
+            filter: nativeFilter ?? params.filter,
+        };
+        // Remove the metadataFilter before passing to QueryIndex
+        delete queryParams['metadataFilter'];
+        return this.QueryIndex(queryParams);
+    }
+    /**
+     * Convert SharedIndexFilterOptions to a provider-native filter object.
+     *
+     * Override this method in provider subclasses to produce provider-specific
+     * filter syntax (e.g., Pinecone, Weaviate, Qdrant, etc.).
+     *
+     * @param options - The high-level filter options
+     * @returns A native filter object, or undefined if no filters
+     */
+    BuildMetadataFilter(options) {
+        return VectorMetadataFilter.FromOptions(options);
+    }
 }
 //# sourceMappingURL=VectorDBBase.js.map

package/dist/generic/VectorDBBase.js.map

@@ -1 +1 @@
-{"version":3,"file":"VectorDBBase.js","sourceRoot":"","sources":["../../src/generic/VectorDBBase.ts"],"names":[],"mappings":"AAKA,MAAM,OAAgB,YAAY;IAE9B;;OAEG;IACH,IAAc,MAAM;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;IAED,YAAa,MAAc;QACvB,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;QAE/C,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IAC1B,CAAC;CAkBJ"}
+{"version":3,"file":"VectorDBBase.js","sourceRoot":"","sources":["../../src/generic/VectorDBBase.ts"],"names":[],"mappings":"AAIA,OAAO,EAA4B,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAElF,MAAM,OAAgB,YAAY;IAE9B;;OAEG;IACH,IAAc,MAAM;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;IAED,YAAa,MAAc;QACvB,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;QAE/C,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IAC1B,CAAC;IA0BD;;;OAGG;IACH,IAAW,oBAAoB;QAC3B,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACI,WAAW,CAAC,MAA0B;QACzC,oEAAoE;QACpE,OAAO,IAAI,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,eAAe,EAAE,MAAM,CAAC,eAAe,EAAE,aAAa,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9K,CAAC;IAED;;;;;;;;;OASG;IACI,qBAAqB,CACxB,MAAmE;QAEnE,MAAM,YAAY,GAAG,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;QACrE,MAAM,WAAW,GAAiB;YAC9B,GAAG,MAAM;YACT,MAAM,EAAE,YAAY,IAAI,MAAM,CAAC,MAAM;SACxC,CAAC;QACF,yDAAyD;QACzD,OAAQ,WAAuC,CAAC,gBAAgB,CAAC,CAAC;QAClE,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;IACxC,CAAC;IAED;;;;;;;;OAQG;IACI,mBAAmB,CAAC,OAAiC;QACxD,OAAO,oBAAoB,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACrD,CAAC;CACJ"}

package/dist/generic/configuration.types.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Configuration interfaces for VectorDatabase and VectorIndex provider settings.
+ *
+ * These are stored as JSON in the Configuration / ProviderConfig columns and
+ * parsed at runtime. All fields are optional — NULL or missing means "use
+ * provider/environment defaults."
+ */
+/**
+ * Provider-level configuration for a VectorDatabase record.
+ * Stored in VectorDatabase.Configuration as JSON.
+ *
+ * Controls connection behavior, resilience, and throughput limits that
+ * apply to every index managed by this database provider instance.
+ */
+export interface VectorDatabaseConfiguration {
+    /** Connection settings — host overrides, timeouts, proxy */
+    connection?: VectorDatabaseConnectionConfig;
+    /** Retry / resilience behavior for transient failures */
+    resilience?: VectorDatabaseResilienceConfig;
+    /** Throughput caps that the provider should respect */
+    throughput?: VectorDatabaseThroughputConfig;
+}
+export interface VectorDatabaseConnectionConfig {
+    /**
+     * Custom API host/endpoint URL. Overrides the default derived from
+     * environment variables (e.g. PINECONE_HOST).
+     * Useful for private endpoints, proxies, or region overrides.
+     */
+    hostUrl?: string;
+    /**
+     * Request timeout in milliseconds for individual API calls.
+     * Default varies by provider (typically 30 000 ms).
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Connection timeout in milliseconds — how long to wait for a
+     * TCP connection to be established.
+     */
+    connectTimeoutMs?: number;
+    /**
+     * HTTP/SOCKS proxy URL (e.g. "http://proxy.corp:8080").
+     * Only applies to providers that support proxy configuration.
+     */
+    proxyUrl?: string;
+}
+export interface VectorDatabaseResilienceConfig {
+    /**
+     * Maximum number of retries on transient failures (429, 5xx).
+     * Set to 0 to disable retries. Default: 3.
+     */
+    maxRetries?: number;
+    /**
+     * Base delay in ms for exponential backoff between retries.
+     * Actual delay = baseDelayMs * 2^(attempt). Default: 500.
+     */
+    retryBaseDelayMs?: number;
+    /**
+     * Maximum delay in ms between retries (caps the exponential
+     * backoff). Default: 30 000.
+     */
+    retryMaxDelayMs?: number;
+}
+export interface VectorDatabaseThroughputConfig {
+    /**
+     * Maximum number of vectors in a single upsert batch.
+     * Pinecone recommends ≤100; other providers may differ.
+     */
+    maxUpsertBatchSize?: number;
+    /**
+     * Maximum number of concurrent API requests to the provider.
+     * Helps avoid rate-limit errors on shared-tier plans.
+     */
+    maxConcurrentRequests?: number;
+    /**
+     * Hard ceiling on requests per second. The client will
+     * throttle to stay under this limit. 0 = unlimited.
+     */
+    maxRequestsPerSecond?: number;
+}
+/**
+ * Index-level provider configuration stored in VectorIndex.ProviderConfig
+ * as JSON. Currently populated by the server entity hook when an index
+ * is auto-provisioned, and may also be edited manually.
+ *
+ * Contains both read-back fields (ExternalID, Dimensions, Metric set by
+ * the hook) and tunable settings.
+ */
+export interface VectorIndexProviderConfig {
+    /**
+     * The provider-assigned identifier for this index (e.g. Pinecone
+     * index host URL or Weaviate class name). Written by the server
+     * hook after provisioning.
+     */
+    ExternalID?: string;
+    /**
+     * Dimensionality of vectors stored in this index.
+     * Written by the server hook from the embedding model.
+     */
+    Dimensions?: number;
+    /**
+     * Distance metric used for similarity search.
+     * Written by the server hook from VectorIndex.DistanceMetric.
+     */
+    Metric?: string;
+    /** Provisioning and capacity settings (provider-specific) */
+    provisioning?: VectorIndexProvisioningConfig;
+    /** Default query parameters applied when not overridden per-call */
+    queryDefaults?: VectorIndexQueryDefaults;
+    /** Namespace mapping strategy for multi-tenant or multi-entity indexes */
+    namespaceStrategy?: VectorIndexNamespaceStrategy;
+    /** Per-record metadata constraints */
+    metadataLimits?: VectorIndexMetadataLimits;
+}
+export interface VectorIndexProvisioningConfig {
+    /**
+     * Deployment type. Pinecone supports "serverless" and "pod".
+     * Other providers may use different terminology.
+     */
+    deploymentType?: 'serverless' | 'pod' | string;
+    /** Cloud provider for serverless indexes (e.g. "aws", "gcp", "azure") */
+    cloud?: string;
+    /** Cloud region (e.g. "us-east-1", "us-west-2") */
+    region?: string;
+    /**
+     * Pod type (e.g. "p1.x1", "s1.x2"). Only relevant for pod-based
+     * deployments.
+     */
+    podType?: string;
+    /** Number of replicas for high-availability. Pod-based only. */
+    replicas?: number;
+    /** Number of shards for horizontal scaling. Pod-based only. */
+    shards?: number;
+}
+export interface VectorIndexQueryDefaults {
+    /**
+     * Default number of results to return. Overridden by explicit
+     * topK in individual queries.
+     */
+    topK?: number;
+    /** Whether to include metadata in query results by default */
+    includeMetadata?: boolean;
+    /** Whether to include vector values in query results by default */
+    includeValues?: boolean;
+}
+export interface VectorIndexNamespaceStrategy {
+    /**
+     * How namespaces are assigned:
+     * - "none": single flat namespace (default)
+     * - "per-entity": one namespace per entity name
+     * - "per-tenant": one namespace per organization/tenant ID
+     * - "custom": driven by a custom function or template
+     */
+    mode?: 'none' | 'per-entity' | 'per-tenant' | 'custom';
+    /**
+     * Template string for custom namespace names.
+     * Supports {{EntityName}}, {{TenantID}}, {{EntityDocumentID}}.
+     * Only used when mode = "custom".
+     */
+    template?: string;
+}
+export interface VectorIndexMetadataLimits {
+    /**
+     * Maximum total metadata size in bytes per record.
+     * Pinecone free tier: 40 KB. Paid: 40 KB default.
+     * Records exceeding this will have large fields truncated.
+     */
+    maxMetadataBytesPerRecord?: number;
+    /**
+     * Maximum number of metadata fields per record.
+     * Some providers cap this (e.g. Pinecone: no hard cap but
+     * performance degrades past ~40 fields).
+     */
+    maxMetadataFields?: number;
+}
+//# sourceMappingURL=configuration.types.d.ts.map

package/dist/generic/configuration.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configuration.types.d.ts","sourceRoot":"","sources":["../../src/generic/configuration.types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH;;;;;;GAMG;AACH,MAAM,WAAW,2BAA2B;IACxC,4DAA4D;IAC5D,UAAU,CAAC,EAAE,8BAA8B,CAAC;IAE5C,yDAAyD;IACzD,UAAU,CAAC,EAAE,8BAA8B,CAAC;IAE5C,uDAAuD;IACvD,UAAU,CAAC,EAAE,8BAA8B,CAAC;CAC/C;AAED,MAAM,WAAW,8BAA8B;IAC3C;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,8BAA8B;IAC3C;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,8BAA8B;IAC3C;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAE/B;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACjC;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACtC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,6BAA6B,CAAC;IAE7C,oEAAoE;IACpE,aAAa,CAAC,EAAE,wBAAwB,CAAC;IAEzC,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,4BAA4B,CAAC;IAEjD,sCAAsC;IACtC,cAAc,CAAC,EAAE,yBAAyB,CAAC;CAC9C;AAED,MAAM,WAAW,6BAA6B;IAC1C;;;OAGG;IACH,cAAc,CAAC,EAAE,YAAY,GAAG,KAAK,GAAG,MAAM,CAAC;IAE/C,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,wBAAwB;IACrC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,8DAA8D;IAC9D,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,mEAAmE;IACnE,aAAa,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,4BAA4B;IACzC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,YAAY,GAAG,QAAQ,CAAC;IAEvD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,yBAAyB;IACtC;;;;OAIG;IACH,yBAAyB,CAAC,EAAE,MAAM,CAAC;IAEnC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC9B"}

package/dist/generic/configuration.types.js

@@ -0,0 +1,9 @@
+/**
+ * Configuration interfaces for VectorDatabase and VectorIndex provider settings.
+ *
+ * These are stored as JSON in the Configuration / ProviderConfig columns and
+ * parsed at runtime. All fields are optional — NULL or missing means "use
+ * provider/environment defaults."
+ */
+export {};
+//# sourceMappingURL=configuration.types.js.map

package/dist/generic/configuration.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configuration.types.js","sourceRoot":"","sources":["../../src/generic/configuration.types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/generic/query.types.d.ts

@@ -40,6 +40,20 @@ export type QueryByVectorValues = QueryParamsBase & {
  * The options that may be passed to {@link VectorDBBase.queryIndex }
  */
 export type QueryOptions = QueryByRecordId | QueryByVectorValues;
+/**
+ * Options for hybrid search combining vector similarity with keyword (BM25) search.
+ * Providers that support hybrid search implement VectorDBBase.HybridQuery().
+ */
+export interface HybridQueryOptions extends QueryParamsBase {
+    /** Vector values for the semantic similarity component */
+    vector: RecordValues;
+    /** Keyword query string for the BM25/text search component */
+    KeywordQuery?: string;
+    /** Balance between vector and keyword: 0.0 = pure keyword, 1.0 = pure vector (default: 0.7) */
+    Alpha?: number;
+    /** Method for fusing vector and keyword result lists (default: 'rrf') */
+    FusionMethod?: 'rrf' | 'weighted';
+}
 export interface ScoredRecord<T extends RecordMetadata = RecordMetadata> extends VectorRecord<T> {
     /**
      * The similarity score of the record. The interpretation of this score will be different

package/dist/generic/query.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.types.d.ts","sourceRoot":"","sources":["../../src/generic/query.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGtE,MAAM,MAAM,eAAe,GAAG;IAC1B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG;IAC5C;;;OAGG;IACH,EAAE,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,eAAe,GAAG;IAChD;;OAEG;IACH,MAAM,EAAE,YAAY,CAAC;CACxB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,eAAe,GAAG,mBAAmB,CAAC;AAEjE,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,CAAE,SAAQ,YAAY,CAAC,CAAC,CAAC;IAC5F;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,IAAI;IACnE,6CAA6C;IAC7C,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAChC,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,KAAK,CAAC,EAAE,cAAc,CAAC;CAC1B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IACzB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC"}
+{"version":3,"file":"query.types.d.ts","sourceRoot":"","sources":["../../src/generic/query.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGtE,MAAM,MAAM,eAAe,GAAG;IAC1B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG;IAC5C;;;OAGG;IACH,EAAE,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,eAAe,GAAG;IAChD;;OAEG;IACH,MAAM,EAAE,YAAY,CAAC;CACxB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,eAAe,GAAG,mBAAmB,CAAC;AAEjE;;;GAGG;AACH,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACvD,0DAA0D;IAC1D,MAAM,EAAE,YAAY,CAAC;IACrB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,YAAY,CAAC,EAAE,KAAK,GAAG,UAAU,CAAC;CACrC;AAED,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,CAAE,SAAQ,YAAY,CAAC,CAAC,CAAC;IAC5F;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,IAAI;IACnE,6CAA6C;IAC7C,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAChC,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,KAAK,CAAC,EAAE,cAAc,CAAC;CAC1B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IACzB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC"}

package/dist/generic/record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/generic/record.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC3B;;;;MAIE;IACF,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;MAIE;IACF,MAAM,EAAE,oBAAoB,CAAA;IAC5B;;;;MAIE;IACF,IAAI,EAAE,MAAM,CAAC;CAChB,CAAA;AAED;;GAEG;AACH,MAAM,CAAC,OAAO,CAAC,MAAM,oBAAoB,EAAE;IACvC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,YAAY,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,MAAM,OAAO,oBAAoB,CAAC,CAAC;AAElG;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;CACrC;AAED,uDAAuD;AACvD,MAAM,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;AAEzC;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC7B,uEAAuE;IACvE,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACvB,0EAA0E;IAC1E,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACzB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;AAE5E,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;AAEjE,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,IAAI;IAClE;;;OAGG;IACH,EAAE,EAAE,MAAM,CAAC;IACX;;OAEG;IACH,MAAM,EAAE,YAAY,CAAC;IACrB;;;OAGG;IACH,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC;;OAEG;IACH,QAAQ,CAAC,EAAE,CAAC,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,GAAG,CAAA;CACb,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAE,iBAAiB,GAAG;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,oBAAoB,CAAC;IAC7B,gBAAgB,CAAC,EAAE,GAAG,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,iBAAiB,GAAG,EACjD,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,IAAI;IACnE,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,iEAAiE;IACjE,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;OACG;IACH,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC;;OAEG;IACH,QAAQ,CAAC,EAAE,CAAC,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,GAAG,CAAA;CACZ,CAAA"}
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/generic/record.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC3B;;;;MAIE;IACF,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;MAIE;IACF,MAAM,EAAE,oBAAoB,CAAA;IAC5B;;;;MAIE;IACF,IAAI,EAAE,MAAM,CAAC;CAChB,CAAA;AAED;;GAEG;AACH,MAAM,CAAC,OAAO,CAAC,MAAM,oBAAoB,EAAE;IACvC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,YAAY,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,MAAM,OAAO,oBAAoB,CAAC,CAAC;AAElG;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;CACrC;AAED,uDAAuD;AACvD,MAAM,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;AAEzC;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC7B,uEAAuE;IACvE,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACvB,0EAA0E;IAC1E,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACzB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;AAE5E,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;AAEjE,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,IAAI;IAClE;;;OAGG;IACH,EAAE,EAAE,MAAM,CAAC;IACX;;OAEG;IACH,MAAM,EAAE,YAAY,CAAC;IACrB;;;OAGG;IACH,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC;;OAEG;IACH,QAAQ,CAAC,EAAE,CAAC,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IAEX,IAAI,CAAC,EAAE,GAAG,CAAA;CACb,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,GAAG;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,oBAAoB,CAAC;IAE7B,gBAAgB,CAAC,EAAE,GAAG,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,iBAAiB,GAAG,EACjD,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,IAAI;IACnE,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,iEAAiE;IACjE,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;OACG;IACH,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC;;OAEG;IACH,QAAQ,CAAC,EAAE,CAAC,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAIhB,IAAI,EAAE,GAAG,CAAA;CACZ,CAAA"}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from './generic/record.js';
 export * from './generic/VectorDBBase.js';
 export * from './generic/query.types.js';
+export * from './generic/MetadataFilter.js';
+export * from './generic/configuration.types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC"}

package/dist/index.js

@@ -1,4 +1,6 @@
 export * from './generic/record.js';
 export * from './generic/VectorDBBase.js';
 export * from './generic/query.types.js';
+export * from './generic/MetadataFilter.js';
+export * from './generic/configuration.types.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/ai-vectordb",
   "type": "module",
-  "version": "5.20.0",
+  "version": "5.22.0",
   "description": "MemberJunction: AI Vector Database Module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,8 +17,8 @@
   "author": "MemberJunction.com",
   "license": "ISC",
   "dependencies": {
-    "@memberjunction/core": "5.20.0",
-    "@memberjunction/global": "5.20.0",
+    "@memberjunction/core": "5.22.0",
+    "@memberjunction/global": "5.22.0",
     "dotenv": "^17.2.4"
   },
   "devDependencies": {