@maravilla-labs/types 0.2.1 → 0.2.2

package/index.ts

@@ -83,6 +83,87 @@ export interface KvStore {
 
 // Database Types
 
+/** MongoDB-style key direction: `1` ascending, `-1` descending. */
+export type IndexDirection = 1 | -1;
+
+/** Whether an index is a regular document index or a vector index. */
+export type IndexKind = 'document' | 'vector';
+
+export interface IndexSpec {
+  name?: string;
+  keys: Array<[string, IndexDirection]> | Record<string, IndexDirection>;
+  unique?: boolean;
+  sparse?: boolean;
+  partial?: Record<string, unknown>;
+  expireAfterSeconds?: number;
+}
+
+export interface IndexDescriptor {
+  collection: string;
+  name: string;
+  keys: Array<[string, IndexDirection]>;
+  unique: boolean;
+  sparse: boolean;
+  partial?: Record<string, unknown>;
+  expireAfterSeconds?: number;
+  kind: IndexKind;
+}
+
+/** Distance metric used to compare vectors. */
+export type VectorMetric = 'cosine' | 'l2' | 'hamming';
+
+/**
+ * On-disk storage precision for vectors.
+ * - `float32` (default): 4 bytes per dim
+ * - `int8`: 1 byte per dim, 4× smaller, typically <2% accuracy loss
+ * - `bit`: 1 bit per dim, 32× smaller; requires metric='hamming'
+ */
+export type VectorStorage = 'float32' | 'int8' | 'bit';
+
+/** Query shape: single vector or an array of vectors (ColBERT-style). */
+export type VectorQueryMode = 'single' | 'late-interaction';
+
+/** How multi-vector distances are aggregated per document. */
+export type VectorAggregation = 'max-sim' | 'sum';
+
+/** Spec used to declare a vector index on a collection field. */
+export interface VectorIndexSpec {
+  field: string;
+  dimensions: number;
+  metric?: VectorMetric;
+  storage?: VectorStorage;
+  matryoshka?: boolean;
+  multiVector?: boolean;
+}
+
+/** Metadata for a registered vector index. */
+export interface VectorIndexDescriptor {
+  collection: string;
+  field: string;
+  dimensions: number;
+  metric: VectorMetric;
+  storage: VectorStorage;
+  matryoshka: boolean;
+  multiVector: boolean;
+}
+
+/** Vector search clause riding inside DbFindOptions. */
+export interface VectorQuery {
+  field: string;
+  value: number[] | number[][];
+  k: number;
+  metric?: VectorMetric;
+  minScore?: number;
+  queryMode?: VectorQueryMode;
+  aggregation?: VectorAggregation;
+}
+
+/** Document returned by a vector search with similarity metadata attached. */
+export type VectorSearchHit = Record<string, any> & {
+  _score: number;
+  _distance: number;
+};
+
 /**
  * Database find options
  */
@@ -91,6 +172,8 @@ export interface DbFindOptions {
   skip?: number;
   sort?: Record<string, 1 | -1>;
   projection?: Record<string, 1 | 0>;
+  /** Hybrid metadata + vector search clause. */
+  vector?: VectorQuery;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/types",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "TypeScript definitions for Maravilla Runtime platform APIs",
   "main": "index.ts",
   "types": "index.ts",