voctar 0.1.0

package/dist/src/types.d.ts

@@ -0,0 +1,111 @@
+export interface VectorDocument {
+    id: string;
+    text: string;
+    metadata?: Record<string, any>;
+}
+export interface VectorPoint {
+    id: string;
+    vector: number[];
+    payload?: Record<string, any>;
+}
+export interface EmbedOptions {
+    documentId?: string;
+    metadata?: Record<string, any>;
+    chunkSize?: number;
+    chunkStrategy?: 'fixed' | 'recursive' | 'semantic' | 'sentence' | 'paragraph';
+    chunkOverlap?: number;
+    autoChunk?: boolean;
+    user_id?: string;
+}
+export interface SearchOptions {
+    limit?: number;
+    scoreThreshold?: number;
+    /**
+     * Payload filter. Keys without a dot are applied under `metadata.*` (e.g. `user_id` → `metadata.user_id`).
+     * Keys that already contain a dot are used as-is (e.g. `metadata.thread_id`).
+     * Scalar values: equality match. Array values: match any element (OR) on that field.
+     */
+    filter?: Record<string, any>;
+    includeSystem?: boolean;
+}
+export interface SearchResult {
+    id: string;
+    text: string;
+    score: number;
+    createdAt: string;
+    system?: Record<string, any>;
+    metadata?: Record<string, any>;
+}
+export interface VectorConfig {
+    embedding?: RuntimeEmbeddingConfig;
+    store?: RuntimeStoreConfig;
+    /** @deprecated Prefer `embedding.type = 'custom'` */
+    embeddingProvider?: EmbeddingProvider;
+    /** @deprecated Prefer `store.type = 'custom'` */
+    vectorStoreProvider?: VectorStoreProvider;
+    defaultChunkSize?: number;
+    defaultChunkStrategy?: 'fixed' | 'recursive' | 'semantic' | 'sentence' | 'paragraph';
+    defaultChunkOverlap?: number;
+    autoChunk?: boolean;
+}
+export type RuntimeEmbeddingConfig = {
+    type: 'openai';
+    apiKey: string;
+    model?: string;
+    dimension?: number;
+    maxRetries?: number;
+} | {
+    type: 'custom';
+    provider: EmbeddingProvider;
+};
+export type RuntimeStoreConfig = {
+    type: 'sqlite';
+    path?: string;
+    inMemory?: boolean;
+} | {
+    type: 'qdrant';
+    url: string;
+    port?: number;
+    apiKey?: string;
+    timeout?: number;
+    checkCompatibility?: boolean;
+} | {
+    type: 'memory';
+} | {
+    type: 'custom';
+    provider: VectorStoreProvider;
+};
+export interface CollectionConfig {
+    dimension?: number;
+    distance?: 'cosine' | 'euclidean' | 'dot';
+}
+export interface EmbeddingProvider {
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+    getDimension(): number;
+    getModelName(): string;
+    getTokenLimit(): number;
+}
+export interface VectorStoreProvider {
+    ensureCollection(name: string, dimension: number, config?: CollectionConfig): Promise<void>;
+    upsert(collection: string, points: VectorPoint[]): Promise<void>;
+    search(collection: string, vector: number[], options: SearchOptions): Promise<SearchResult[]>;
+    delete(collection: string, ids: string[]): Promise<void>;
+    deleteCollection(collection: string): Promise<void>;
+    /** Scroll/query for point IDs matching a filter (for efficient chunk cleanup) */
+    getIdsByFilter(collection: string, filter: Record<string, any>, limit?: number): Promise<string[]>;
+}
+export declare class VectorEmbeddingError extends Error {
+    cause?: Error | undefined;
+    data?: Record<string, any> | undefined;
+    constructor(message: string, cause?: Error | undefined, data?: Record<string, any> | undefined);
+}
+export declare class VectorSearchError extends Error {
+    cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+export declare class VectorStoreError extends Error {
+    cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/src/types.js

@@ -0,0 +1,32 @@
+"use strict";
+// Vector embedding service types
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VectorStoreError = exports.VectorSearchError = exports.VectorEmbeddingError = void 0;
+// Custom error types
+class VectorEmbeddingError extends Error {
+    constructor(message, cause, data) {
+        super(JSON.stringify({ message, cause, data }, null, 2));
+        this.cause = cause;
+        this.data = data;
+        this.name = 'VectorEmbeddingError';
+        this.data = data;
+    }
+}
+exports.VectorEmbeddingError = VectorEmbeddingError;
+class VectorSearchError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'VectorSearchError';
+    }
+}
+exports.VectorSearchError = VectorSearchError;
+class VectorStoreError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'VectorStoreError';
+    }
+}
+exports.VectorStoreError = VectorStoreError;
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":";AAAA,iCAAiC;;;AAqHjC,qBAAqB;AACrB,MAAa,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAe,EAAS,KAAa,EAAS,IAA0B;QAClF,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QADvB,UAAK,GAAL,KAAK,CAAQ;QAAS,SAAI,GAAJ,IAAI,CAAsB;QAElF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAND,oDAMC;AAED,MAAa,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe,EAAS,KAAa;QAC/C,KAAK,CAAC,OAAO,CAAC,CAAC;QADmB,UAAK,GAAL,KAAK,CAAQ;QAE/C,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AALD,8CAKC;AAED,MAAa,gBAAiB,SAAQ,KAAK;IACzC,YAAY,OAAe,EAAS,KAAa;QAC/C,KAAK,CAAC,OAAO,CAAC,CAAC;QADmB,UAAK,GAAL,KAAK,CAAQ;QAE/C,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AALD,4CAKC"}

package/dist/src/vector.d.ts

@@ -0,0 +1,74 @@
+import type { VectorDocument, VectorConfig, SearchOptions, SearchResult, EmbeddingProvider, VectorStoreProvider, CollectionConfig, EmbedOptions } from './types';
+export declare class Vector {
+    private embeddingProvider;
+    private vectorStoreProvider;
+    private defaultChunkSize;
+    private defaultChunkStrategy;
+    private defaultChunkOverlap;
+    private autoChunk;
+    constructor(config?: VectorConfig);
+    /**
+     * Embed text into a collection - automatically chunks if needed
+     * If documentId already exists, it will be overwritten (all old chunks deleted first)
+     * @returns Document ID and chunk IDs
+     */
+    embed(collection: string, text: string, options?: EmbedOptions): Promise<{
+        documentId: string;
+        chunkIds: string[];
+    }>;
+    /**
+     * Embed multiple documents in batch
+     */
+    embedBatch(collection: string, documents: VectorDocument[], user_id?: string): Promise<string[]>;
+    /**
+     * Search for similar documents
+     */
+    search(collection: string, query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Update or insert a document (handles all chunks automatically)
+     */
+    upsert(collection: string, documentId: string, text: string, options?: EmbedOptions): Promise<void>;
+    /**
+     * Delete a document and all its chunks
+     * Uses metadata filtering to find and delete all chunks efficiently
+     */
+    delete(collection: string, documentId: string | string[]): Promise<void>;
+    /**
+     * Delete an entire collection
+     */
+    deleteCollection(collection: string): Promise<void>;
+    /**
+     * Ensure a collection exists with optional custom configuration
+     */
+    ensureCollection(collection: string, config?: CollectionConfig): Promise<void>;
+    /**
+     * Get the current embedding provider
+     */
+    getEmbeddingProvider(): EmbeddingProvider;
+    /**
+     * Get the current vector store provider
+     */
+    getVectorStoreProvider(): VectorStoreProvider;
+    /**
+     * Generate chunk ID from document ID and chunk index
+     */
+    static getChunkId(documentId: string, chunkIndex: number): string;
+    /**
+     * Parse chunk ID to extract document ID and chunk index
+     */
+    static parseChunkId(chunkId: string): {
+        documentId: string;
+        chunkIndex: number;
+    } | null;
+    /**
+     * Check if an ID is a chunk ID (contains #)
+     */
+    static isChunkId(id: string): boolean;
+    private resolveEmbeddingProvider;
+    private resolveVectorStoreProvider;
+    private createEmbeddingProviderFromRuntime;
+    private createVectorStoreProviderFromRuntime;
+    private validateCollectionName;
+    private validateText;
+}
+//# sourceMappingURL=vector.d.ts.map

package/dist/src/vector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector.d.ts","sourceRoot":"","sources":["../../src/vector.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EAGZ,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,YAAY,EACb,MAAM,SAAS,CAAC;AAQjB,qBAAa,MAAM;IACjB,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,mBAAmB,CAAsB;IAGjD,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,oBAAoB,CAAgE;IAC5F,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,SAAS,CAAU;gBAEf,MAAM,CAAC,EAAE,YAAY;IAYjC;;;;OAIG;IACG,KAAK,CACT,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAiItD;;OAEG;IACG,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAkItG;;OAEG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA+CjG;;OAEG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBzG;;;OAGG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAsC9E;;OAEG;IACG,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAazD;;OAEG;IACG,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAcpF;;OAEG;IACH,oBAAoB,IAAI,iBAAiB;IAIzC;;OAEG;IACH,sBAAsB,IAAI,mBAAmB;IAI7C;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;IAIjE;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAiBvF;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAMrC,OAAO,CAAC,wBAAwB;IAehC,OAAO,CAAC,0BAA0B;IAgBlC,OAAO,CAAC,kCAAkC;IAa1C,OAAO,CAAC,oCAAoC;IA2B5C,OAAO,CAAC,sBAAsB;IAa9B,OAAO,CAAC,YAAY;CASrB"}