@ninebix/nmt-system 1.0.0

package/dist/core/local-embedding.js

@@ -0,0 +1,222 @@
+/**
+ * Local Embedding Service
+ * 로컬 초소형 모델을 사용한 임베딩 생성
+ *
+ * @module core/local-embedding
+ */
+import { pipeline, env } from '@xenova/transformers';
+// 모델 캐시 디렉토리 설정
+env.cacheDir = './data/models';
+env.allowLocalModels = true;
+/**
+ * Local Embedding Service
+ */
+export class LocalEmbeddingService {
+    extractor = null;
+    modelName;
+    isLoading = false;
+    loadPromise = null;
+    // 캐시
+    cache = new Map();
+    cacheMaxSize = 10000;
+    // 통계
+    stats = {
+        totalEmbeddings: 0,
+        cacheHits: 0,
+        totalTime: 0,
+        modelLoadTime: 0,
+    };
+    constructor(modelName = 'Xenova/all-MiniLM-L6-v2') {
+        this.modelName = modelName;
+    }
+    /**
+     * 모델 로드
+     */
+    async init() {
+        if (this.extractor)
+            return;
+        if (this.loadPromise)
+            return this.loadPromise;
+        this.isLoading = true;
+        const startTime = Date.now();
+        this.loadPromise = (async () => {
+            try {
+                console.log(`Loading embedding model: ${this.modelName}...`);
+                this.extractor = await pipeline('feature-extraction', this.modelName, {
+                    quantized: true, // 양자화된 모델 사용 (더 빠름)
+                });
+                this.stats.modelLoadTime = Date.now() - startTime;
+                console.log(`Model loaded in ${this.stats.modelLoadTime}ms`);
+            }
+            catch (error) {
+                console.error('Failed to load embedding model:', error);
+                throw error;
+            }
+            finally {
+                this.isLoading = false;
+            }
+        })();
+        return this.loadPromise;
+    }
+    /**
+     * 단일 텍스트 임베딩
+     */
+    async embed(text) {
+        await this.init();
+        // 캐시 확인
+        const cacheKey = text.toLowerCase().trim();
+        if (this.cache.has(cacheKey)) {
+            this.stats.cacheHits++;
+            return {
+                text,
+                embedding: this.cache.get(cacheKey),
+                model: this.modelName,
+                processingTime: 0,
+            };
+        }
+        const startTime = Date.now();
+        const output = await this.extractor(text, {
+            pooling: 'mean',
+            normalize: true,
+        });
+        const embedding = Array.from(output.data);
+        const processingTime = Date.now() - startTime;
+        // 캐시 저장
+        this.addToCache(cacheKey, embedding);
+        // 통계 업데이트
+        this.stats.totalEmbeddings++;
+        this.stats.totalTime += processingTime;
+        return {
+            text,
+            embedding,
+            model: this.modelName,
+            processingTime,
+        };
+    }
+    /**
+     * 배치 임베딩
+     */
+    async embedBatch(texts) {
+        const startTime = Date.now();
+        const results = [];
+        // 병렬 처리 (최대 10개씩)
+        const batchSize = 10;
+        for (let i = 0; i < texts.length; i += batchSize) {
+            const batch = texts.slice(i, i + batchSize);
+            const batchResults = await Promise.all(batch.map(t => this.embed(t)));
+            results.push(...batchResults);
+        }
+        const totalTime = Date.now() - startTime;
+        return {
+            results,
+            totalTime,
+            avgTime: totalTime / texts.length,
+        };
+    }
+    /**
+     * 두 텍스트 간 유사도 계산
+     */
+    async similarity(text1, text2, method = 'cosine') {
+        const [emb1, emb2] = await Promise.all([
+            this.embed(text1),
+            this.embed(text2),
+        ]);
+        let similarity;
+        switch (method) {
+            case 'cosine':
+                similarity = this.cosineSimilarity(emb1.embedding, emb2.embedding);
+                break;
+            case 'dot':
+                similarity = this.dotProduct(emb1.embedding, emb2.embedding);
+                break;
+            case 'euclidean':
+                similarity = 1 / (1 + this.euclideanDistance(emb1.embedding, emb2.embedding));
+                break;
+        }
+        return { text1, text2, similarity, method };
+    }
+    /**
+     * 쿼리와 가장 유사한 텍스트 찾기
+     */
+    async findMostSimilar(query, candidates, topK = 5) {
+        const queryEmb = await this.embed(query);
+        const candidateEmbs = await this.embedBatch(candidates);
+        const similarities = candidateEmbs.results.map((r, i) => ({
+            text: candidates[i],
+            similarity: this.cosineSimilarity(queryEmb.embedding, r.embedding),
+        }));
+        return similarities
+            .sort((a, b) => b.similarity - a.similarity)
+            .slice(0, topK);
+    }
+    /**
+     * 코사인 유사도
+     */
+    cosineSimilarity(a, b) {
+        let dotProduct = 0;
+        let normA = 0;
+        let normB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dotProduct += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+    }
+    /**
+     * 내적
+     */
+    dotProduct(a, b) {
+        return a.reduce((sum, val, i) => sum + val * b[i], 0);
+    }
+    /**
+     * 유클리드 거리
+     */
+    euclideanDistance(a, b) {
+        return Math.sqrt(a.reduce((sum, val, i) => sum + Math.pow(val - b[i], 2), 0));
+    }
+    /**
+     * 캐시에 추가
+     */
+    addToCache(key, embedding) {
+        if (this.cache.size >= this.cacheMaxSize) {
+            // LRU: 가장 오래된 항목 제거
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey)
+                this.cache.delete(firstKey);
+        }
+        this.cache.set(key, embedding);
+    }
+    /**
+     * 통계 반환
+     */
+    getStats() {
+        return {
+            ...this.stats,
+            cacheSize: this.cache.size,
+            cacheHitRate: this.stats.totalEmbeddings > 0
+                ? (this.stats.cacheHits / (this.stats.totalEmbeddings + this.stats.cacheHits)) * 100
+                : 0,
+            avgEmbeddingTime: this.stats.totalEmbeddings > 0
+                ? this.stats.totalTime / this.stats.totalEmbeddings
+                : 0,
+            model: this.modelName,
+            isLoaded: !!this.extractor,
+        };
+    }
+    /**
+     * 캐시 클리어
+     */
+    clearCache() {
+        this.cache.clear();
+    }
+    /**
+     * 임베딩 차원 반환
+     */
+    getDimension() {
+        return 384; // MiniLM-L6-v2 기준
+    }
+}
+// 싱글톤 인스턴스
+export const localEmbedding = new LocalEmbeddingService();
+//# sourceMappingURL=local-embedding.js.map

package/dist/core/local-embedding.js.map

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

package/dist/core/merkle-engine.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Merkle Engine - Tree construction and verification
+ *
+ * Extended features:
+ * - Tree diff computation
+ * - Batch proofs for multiple leaves
+ * - Range proofs for consecutive leaves
+ * - Versioned trees
+ *
+ * @module core/merkle-engine
+ */
+import type { MerkleTree, MerkleProof, SHA3Hash, MerkleRoot } from '../types/index.js';
+/**
+ * Difference between two Merkle trees
+ */
+export interface TreeDiff {
+    /** Leaves added in newTree */
+    added: SHA3Hash[];
+    /** Leaves removed from oldTree */
+    removed: SHA3Hash[];
+    /** Leaves modified (same index, different hash) */
+    modified: {
+        index: number;
+        oldHash: SHA3Hash;
+        newHash: SHA3Hash;
+    }[];
+    /** Old root */
+    oldRoot: MerkleRoot;
+    /** New root */
+    newRoot: MerkleRoot;
+}
+/**
+ * Batch proof for multiple leaves
+ */
+export interface BatchMerkleProof {
+    /** Leaves being proven */
+    leaves: {
+        index: number;
+        hash: SHA3Hash;
+    }[];
+    /** Deduplicated sibling nodes: "level:index" -> hash */
+    siblings: Record<string, SHA3Hash>;
+    /** Root hash */
+    root: MerkleRoot;
+}
+/**
+ * Range proof for consecutive leaves
+ */
+export interface RangeProof {
+    /** Start index (inclusive) */
+    startIndex: number;
+    /** End index (exclusive) */
+    endIndex: number;
+    /** Leaves in range */
+    leaves: SHA3Hash[];
+    /** Left boundary proof */
+    leftProof: MerkleProof | null;
+    /** Right boundary proof */
+    rightProof: MerkleProof | null;
+    /** Root hash */
+    root: MerkleRoot;
+}
+/**
+ * Versioned Merkle tree with parent tracking
+ */
+export interface VersionedMerkleTree extends MerkleTree {
+    /** Version number */
+    version: number;
+    /** Parent root (null for initial version) */
+    parentRoot: MerkleRoot | null;
+    /** Version timestamp */
+    timestamp: string;
+    /** Changes from parent (if any) */
+    diff?: TreeDiff;
+}
+/**
+ * MerkleEngine class for tree operations
+ */
+export declare class MerkleEngine {
+    /**
+     * Build a Merkle tree from leaf hashes
+     * @param leaves - Array of leaf hashes
+     * @returns Complete Merkle tree structure
+     */
+    buildTree(leaves: SHA3Hash[]): MerkleTree;
+    /**
+     * Build Merkle tree from raw data buffers
+     * @param data - Array of data buffers
+     * @returns Merkle tree with hashed leaves
+     */
+    buildTreeFromData(data: Buffer[]): MerkleTree;
+    /**
+     * Generate inclusion proof for a leaf
+     * @param tree - Merkle tree
+     * @param leafIndex - Index of leaf to prove
+     * @returns Merkle proof
+     */
+    generateProof(tree: MerkleTree, leafIndex: number): MerkleProof;
+    /**
+     * Verify a Merkle proof
+     * @param proof - Proof to verify
+     * @returns true if proof is valid
+     */
+    verifyProof(proof: MerkleProof): boolean;
+    /**
+     * Verify proof with explicit root and leaf
+     * @param proof - Proof structure
+     * @param root - Expected root hash
+     * @param leaf - Expected leaf hash
+     * @returns true if valid
+     */
+    verifyProofWithValues(proof: MerkleProof, root: MerkleRoot, leaf: SHA3Hash): boolean;
+    /**
+     * Compute the root hash directly from leaves
+     * @param leaves - Leaf hashes
+     * @returns Root hash
+     */
+    computeRoot(leaves: SHA3Hash[]): MerkleRoot;
+    /**
+     * Update a leaf in the tree (returns new tree)
+     * @param tree - Original tree
+     * @param index - Leaf index to update
+     * @param newLeaf - New leaf hash
+     * @returns Updated tree
+     */
+    updateLeaf(tree: MerkleTree, index: number, newLeaf: SHA3Hash): MerkleTree;
+    /**
+     * Add a new leaf to the tree
+     * @param tree - Original tree
+     * @param newLeaf - New leaf hash
+     * @returns Updated tree
+     */
+    addLeaf(tree: MerkleTree, newLeaf: SHA3Hash): MerkleTree;
+    /**
+     * Get the height of the tree
+     * @param tree - Merkle tree
+     * @returns Tree height (number of levels)
+     */
+    getHeight(tree: MerkleTree): number;
+    /**
+     * Get all nodes at a specific level
+     * @param tree - Merkle tree
+     * @param level - Level index (0 = leaves)
+     * @returns Array of hashes at that level
+     */
+    getLevel(tree: MerkleTree, level: number): SHA3Hash[];
+    /**
+     * Serialize tree to JSON-friendly format
+     */
+    serialize(tree: MerkleTree): object;
+    /**
+     * Deserialize tree from JSON
+     */
+    deserialize(data: {
+        root: MerkleRoot;
+        levels: SHA3Hash[][];
+        leafCount: number;
+        originalLeaves: SHA3Hash[];
+    }): MerkleTree;
+    /**
+     * Compute the difference between two Merkle trees
+     *
+     * @param oldTree - Original tree
+     * @param newTree - Updated tree
+     * @returns TreeDiff with added, removed, and modified leaves
+     *
+     * @example
+     * ```typescript
+     * const tree1 = engine.buildTree(['a', 'b', 'c']);
+     * const tree2 = engine.buildTree(['a', 'b', 'd']);
+     * const diff = engine.computeDiff(tree1, tree2);
+     * // diff.modified = [{ index: 2, oldHash: 'c', newHash: 'd' }]
+     * ```
+     */
+    computeDiff(oldTree: MerkleTree, newTree: MerkleTree): TreeDiff;
+    /**
+     * Check if two trees have the same content
+     */
+    treesEqual(tree1: MerkleTree, tree2: MerkleTree): boolean;
+    /**
+     * Generate a batch proof for multiple leaves at once
+     *
+     * More efficient than generating individual proofs as siblings are deduplicated.
+     *
+     * @param tree - Merkle tree
+     * @param indices - Array of leaf indices to prove
+     * @returns BatchMerkleProof with deduplicated siblings
+     *
+     * @example
+     * ```typescript
+     * const batchProof = engine.generateBatchProof(tree, [0, 2, 5]);
+     * const valid = engine.verifyBatchProof(batchProof);
+     * ```
+     */
+    generateBatchProof(tree: MerkleTree, indices: number[]): BatchMerkleProof;
+    /**
+     * Verify a batch proof
+     *
+     * @param proof - BatchMerkleProof to verify
+     * @returns true if all leaves are proven to be in the tree
+     */
+    verifyBatchProof(proof: BatchMerkleProof): boolean;
+    /**
+     * Generate a range proof for consecutive leaves
+     *
+     * Useful for proving a subset of the tree without full proofs for each leaf.
+     *
+     * @param tree - Merkle tree
+     * @param startIndex - Start index (inclusive)
+     * @param endIndex - End index (exclusive)
+     * @returns RangeProof
+     */
+    generateRangeProof(tree: MerkleTree, startIndex: number, endIndex: number): RangeProof;
+    /**
+     * Verify a range proof
+     *
+     * @param proof - RangeProof to verify
+     * @returns true if the range is valid
+     */
+    verifyRangeProof(proof: RangeProof): boolean;
+    /**
+     * Create a versioned tree from an existing tree
+     *
+     * @param tree - Source tree
+     * @param parentRoot - Parent version root (null for initial)
+     * @returns VersionedMerkleTree
+     */
+    createVersion(tree: MerkleTree, parentRoot?: MerkleRoot | null): VersionedMerkleTree;
+    /**
+     * Create a new version from changes
+     *
+     * @param currentVersion - Current versioned tree
+     * @param newTree - New tree state
+     * @returns New VersionedMerkleTree with diff
+     */
+    createNewVersion(currentVersion: VersionedMerkleTree, newTree: MerkleTree): VersionedMerkleTree;
+    /**
+     * Serialize a versioned tree
+     */
+    serializeVersioned(tree: VersionedMerkleTree): object;
+    /**
+     * Deserialize a versioned tree
+     */
+    deserializeVersioned(data: {
+        root: MerkleRoot;
+        levels: SHA3Hash[][];
+        leafCount: number;
+        originalLeaves: SHA3Hash[];
+        version: number;
+        parentRoot: MerkleRoot | null;
+        timestamp: string;
+        diff?: TreeDiff;
+    }): VersionedMerkleTree;
+    /**
+     * Check if number is power of 2
+     */
+    private isPowerOfTwo;
+}
+/**
+ * Create a MerkleEngine instance
+ */
+export declare function createMerkleEngine(): MerkleEngine;
+//# sourceMappingURL=merkle-engine.d.ts.map

package/dist/core/merkle-engine.d.ts.map

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