mcard-js 2.0.0 → 2.1.0

package/dist/rag/HandleVectorStore.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Handle-Aware Vector Store for Semantic Versioning
+ *
+ * Extends VectorStore to enable semantic similarity detection
+ * across MCard versions linked to handles.
+ *
+ * Key Features:
+ * - Link MCards to handles during indexing
+ * - Compare versions within a handle by semantic similarity
+ * - Filter searches by handle
+ * - Sort version history by distance to current or query
+ * - Automatic upgrade type classification based on semantic delta
+ *
+ * @module mcard-js/rag/HandleVectorStore
+ */
+import { MCard } from '../model/MCard';
+import { MCardVectorStore, VectorStoreConfig } from '../storage/VectorStore';
+export { VectorStoreConfig } from '../storage/VectorStore';
+/**
+ * A version in a handle's history with embedding info.
+ */
+export interface HandleVersion {
+    hash: string;
+    versionOrder: number;
+    isCurrent: boolean;
+    createdAt: string;
+    parentHash?: string;
+    embeddingId?: number;
+    semanticDelta?: number;
+    upgradeType?: string;
+}
+/**
+ * Result from version similarity comparison.
+ */
+export interface VersionSimilarityResult {
+    hash: string;
+    versionOrder: number;
+    similarityToCurrent: number;
+    distanceToCurrent: number;
+    similarityToQuery?: number;
+    parentHash?: string;
+    upgradeType?: string;
+}
+/**
+ * Classify upgrade type based on semantic similarity to parent.
+ *
+ * Thresholds:
+ * - >= 0.95: trivial (formatting, typo fixes)
+ * - 0.85 - 0.94: minor (small edits, clarifications)
+ * - 0.70 - 0.84: major (significant content changes)
+ * - < 0.70: breaking (major semantic drift)
+ *
+ * @param semanticDelta Cosine similarity to parent version
+ * @returns Upgrade type string
+ */
+export declare function classifyUpgradeType(semanticDelta: number): string;
+/**
+ * Calculate Euclidean distance between two vectors.
+ */
+export declare function euclideanDistance(a: number[], b: number[]): number;
+/**
+ * Extended vector store with handle-aware version similarity.
+ *
+ * This class implements the Handle-Hash Duality pattern with semantic
+ * awareness, enabling:
+ *
+ * - Version tracking via handles
+ * - Semantic similarity detection across versions
+ * - Intelligent upgrade classification
+ * - Cross-version semantic search
+ *
+ * Architecture:
+ * - Handles remain stable identifiers (Proxy Pattern)
+ * - Hashes reference immutable content (Content-Addressing)
+ * - Embeddings enable semantic understanding (Vector Search)
+ *
+ * @example
+ * ```typescript
+ * const store = new HandleVectorStore(':memory:');
+ *
+ * // Index with handle association
+ * await store.indexWithHandle(mcard, 'my_document');
+ *
+ * // Get versions sorted by similarity to current
+ * const versions = await store.getVersionsBySimilarity('my_document');
+ *
+ * // Find versions similar to a query
+ * const results = await store.searchHandleVersions('my_document', 'machine learning');
+ * ```
+ */
+export declare class HandleVectorStore extends MCardVectorStore {
+    constructor(dbPath?: string, config?: Partial<VectorStoreConfig>);
+    /**
+     * Create handle-vector bridge tables for semantic versioning.
+     */
+    private initHandleTables;
+    /**
+     * Index an MCard and associate it with a handle.
+     *
+     * This method:
+     * 1. Indexes the MCard content with embeddings (via base class)
+     * 2. Links the MCard hash to the handle with version tracking
+     * 3. Computes semantic delta from parent version (if exists)
+     * 4. Classifies the upgrade type based on similarity
+     *
+     * @param mcard MCard to index
+     * @param handle Handle name to associate with
+     * @param isCurrent Whether this is the current version
+     * @param chunk Whether to chunk long content
+     * @returns Number of vectors indexed (0 if content couldn't be indexed)
+     */
+    indexWithHandle(mcard: MCard, handle: string, isCurrent?: boolean, chunk?: boolean): Promise<number>;
+    /**
+     * Get all versions for a handle.
+     *
+     * @param handle Handle name to query
+     * @returns List of HandleVersion objects, ordered by version_order (0 = current)
+     */
+    getHandleVersions(handle: string): HandleVersion[];
+    /**
+     * Get all version hashes for a handle.
+     *
+     * @param handle Handle name to query
+     * @returns List of hashes, ordered by version_order
+     */
+    getHandleVersionHashes(handle: string): string[];
+    /**
+     * Get the current version for a handle.
+     *
+     * @param handle Handle name to query
+     * @returns HandleVersion for current version, or undefined if handle not found
+     */
+    getCurrentVersion(handle: string): HandleVersion | undefined;
+    /**
+     * Get versions for a handle, sorted by similarity to a reference.
+     *
+     * @param handle Handle name
+     * @param referenceHash Hash to compare against (default: current version)
+     * @param metric 'cosine' (higher = more similar) or 'euclidean' (lower = more similar)
+     * @returns List of VersionSimilarityResult, sorted by similarity
+     */
+    getVersionsBySimilarity(handle: string, referenceHash?: string, metric?: 'cosine' | 'euclidean'): VersionSimilarityResult[];
+    /**
+     * Search within a handle's versions by semantic query.
+     *
+     * Useful for finding which version of a document best matches
+     * a specific concept or topic.
+     *
+     * @param handle Handle name to filter by
+     * @param query Search query text
+     * @param k Number of results
+     * @returns List of VersionSimilarityResult with query similarity scores
+     */
+    searchHandleVersions(handle: string, query: string, k?: number): Promise<VersionSimilarityResult[]>;
+    /**
+     * Compute pairwise cosine similarities between all versions of a handle.
+     *
+     * Optionally caches results in the version_similarity_cache table.
+     *
+     * @param handle Handle name
+     * @param cache Whether to cache computed similarities
+     * @returns Map of (hash_a, hash_b) string key to cosine similarity
+     */
+    computeVersionDistances(handle: string, cache?: boolean): Map<string, number>;
+    /**
+     * Get embedding vector for a hash.
+     *
+     * @param hash MCard hash
+     * @param chunkIndex Chunk index (default 0 for first/whole chunk)
+     * @returns Embedding vector as array of floats, or undefined if not found
+     */
+    private getEmbedding;
+    /**
+     * List all handles with indexed versions.
+     *
+     * @returns List of unique handle names
+     */
+    listHandles(): string[];
+    /**
+     * Count versions for a handle.
+     *
+     * @param handle Handle name
+     * @returns Number of versions
+     */
+    countVersions(handle: string): number;
+    /**
+     * Delete all version records for a handle.
+     *
+     * Note: This only removes the handle-version associations,
+     * not the underlying MCard embeddings.
+     *
+     * @param handle Handle name
+     * @returns Number of version records deleted
+     */
+    deleteHandle(handle: string): number;
+    /**
+     * Get extended vector store information including handle stats.
+     */
+    getInfo(): Record<string, unknown>;
+}
+//# sourceMappingURL=HandleVectorStore.d.ts.map

package/dist/rag/HandleVectorStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HandleVectorStore.d.ts","sourceRoot":"","sources":["../../src/rag/HandleVectorStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAmG,MAAM,wBAAwB,CAAC;AAI9K,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAM3D;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAUjE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAUlE;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,iBAAkB,SAAQ,gBAAgB;gBAEvC,MAAM,GAAE,MAAmB,EAAE,MAAM,GAAE,OAAO,CAAC,iBAAiB,CAAM;IAKhF;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAuBxB;;;;;;;;;;;;;;OAcG;IACG,eAAe,CACjB,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,OAAc,EACzB,KAAK,GAAE,OAAc,GACtB,OAAO,CAAC,MAAM,CAAC;IAgHlB;;;;;OAKG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE;IA8BlD;;;;;OAKG;IACH,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAKhD;;;;;OAKG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAsC5D;;;;;;;OAOG;IACH,uBAAuB,CACnB,MAAM,EAAE,MAAM,EACd,aAAa,CAAC,EAAE,MAAM,EACtB,MAAM,GAAE,QAAQ,GAAG,WAAsB,GAC1C,uBAAuB,EAAE;IA6D5B;;;;;;;;;;OAUG;IACG,oBAAoB,CACtB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,CAAC,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,uBAAuB,EAAE,CAAC;IA2CrC;;;;;;;;OAQG;IACH,uBAAuB,CACnB,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,OAAc,GACtB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAsDtB;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IA4BpB;;;;OAIG;IACH,WAAW,IAAI,MAAM,EAAE;IAOvB;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAOrC;;;;;;;;OAQG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAepC;;OAEG;IACM,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAqB9C"}