memento-mcp-server 0.1.0

package/src/services/minilm-embedding-service.spec.ts

@@ -0,0 +1,104 @@
+/**
+ * MiniLM 임베딩 서비스 테스트
+ * TDD 방식으로 구현
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { MiniLMEmbeddingService } from './minilm-embedding-service.js';
+import type { EmbeddingResult, SimilarityResult, EmbeddingData } from '../types/embedding.types.js';
+
+// @xenova/transformers 모킹
+vi.mock('@xenova/transformers', () => ({
+  pipeline: vi.fn().mockResolvedValue(
+    vi.fn().mockResolvedValue({
+      data: [0.1, 0.2, 0.3, 0.4] // 384차원 벡터 예시
+    })
+  )
+}));
+
+describe('MiniLMEmbeddingService', () => {
+  let service: MiniLMEmbeddingService;
+  
+  beforeEach(() => {
+    service = new MiniLMEmbeddingService();
+  });
+
+  describe('생성자', () => {
+    it('서비스가 올바르게 초기화되어야 한다', () => {
+      expect(service).toBeDefined();
+      expect(service.isAvailable()).toBe(true); // MiniLM은 항상 사용 가능 (lazy loading)
+    });
+  });
+
+  describe('generateEmbedding', () => {
+    it('빈 텍스트에 대해 에러를 던져야 한다', async () => {
+      await expect(service.generateEmbedding('')).rejects.toThrow('텍스트가 비어있습니다');
+      await expect(service.generateEmbedding('   ')).rejects.toThrow('텍스트가 비어있습니다');
+    });
+
+    it('null이나 undefined에 대해 에러를 던져야 한다', async () => {
+      await expect(service.generateEmbedding(null as any)).rejects.toThrow();
+      await expect(service.generateEmbedding(undefined as any)).rejects.toThrow();
+    });
+
+    it('유효한 텍스트에 대해 임베딩을 생성해야 한다', async () => {
+      const result = await service.generateEmbedding('테스트 텍스트');
+      
+      expect(result).toBeDefined();
+      expect(result?.embedding).toEqual([0.1, 0.2, 0.3, 0.4]);
+      expect(result?.model).toBe('all-MiniLM-L6-v2');
+      expect(result?.usage.prompt_tokens).toBeGreaterThan(0);
+    });
+  });
+
+  describe('searchSimilar', () => {
+    it('빈 임베딩 배열에 대해 빈 배열을 반환해야 한다', async () => {
+      const result = await service.searchSimilar('쿼리', []);
+      expect(result).toEqual([]);
+    });
+
+    it('유사도 임계값을 적용해야 한다', async () => {
+      const embeddings: EmbeddingData[] = [
+        { id: '1', content: '유사한 내용', embedding: [0.1, 0.2, 0.3, 0.4] },
+        { id: '2', content: '다른 내용', embedding: [0.9, 0.8, 0.7, 0.6] }
+      ];
+
+      const result = await service.searchSimilar('쿼리', embeddings, 10, 0.8);
+      
+      // 유사도가 0.8 이상인 것만 반환되어야 함
+      expect(result.every(r => r.similarity >= 0.8)).toBe(true);
+    });
+
+    it('결과 개수를 제한해야 한다', async () => {
+      const embeddings: EmbeddingData[] = Array.from({ length: 20 }, (_, i) => ({
+        id: i.toString(),
+        content: `내용 ${i}`,
+        embedding: [0.1, 0.2, 0.3, 0.4]
+      }));
+
+      const result = await service.searchSimilar('쿼리', embeddings, 5);
+      expect(result).toHaveLength(5);
+    });
+  });
+
+  describe('isAvailable', () => {
+    it('MiniLM은 항상 사용 가능해야 한다 (lazy loading)', () => {
+      expect(service.isAvailable()).toBe(true);
+    });
+
+    it('모델 로딩 후에는 true를 반환해야 한다', async () => {
+      await service.generateEmbedding('테스트');
+      expect(service.isAvailable()).toBe(true);
+    });
+  });
+
+  describe('getModelInfo', () => {
+    it('올바른 모델 정보를 반환해야 한다', () => {
+      const info = service.getModelInfo();
+      
+      expect(info.model).toBe('all-MiniLM-L6-v2');
+      expect(info.dimensions).toBe(384);
+      expect(info.maxTokens).toBe(256);
+    });
+  });
+});

package/src/services/minilm-embedding-service.ts

@@ -0,0 +1,262 @@
+/**
+ * MiniLM 임베딩 서비스
+ * all-MiniLM-L6-v2 모델을 사용한 경량 임베딩 서비스
+ * 
+ * 클린코드 원칙:
+ * - 단일 책임 원칙: 임베딩 생성만 담당
+ * - 의존성 역전: 인터페이스에 의존
+ * - 개방-폐쇄: 확장에는 열려있고 수정에는 닫혀있음
+ */
+
+import { pipeline } from '@xenova/transformers';
+import type { 
+  EmbeddingServiceInterface, 
+  EmbeddingResult, 
+  SimilarityResult, 
+  EmbeddingData 
+} from '../types/embedding.types.js';
+
+export class MiniLMEmbeddingService implements EmbeddingServiceInterface {
+  // 상수 정의
+  private static readonly MODEL_NAME = 'all-MiniLM-L6-v2';
+  private static readonly DIMENSIONS = 384;
+  private static readonly MAX_TOKENS = 256;
+  private static readonly CACHE_TTL = 24 * 60 * 60 * 1000; // 24시간
+  
+  private readonly modelName = MiniLMEmbeddingService.MODEL_NAME;
+  private readonly dimensions = MiniLMEmbeddingService.DIMENSIONS;
+  private readonly maxTokens = MiniLMEmbeddingService.MAX_TOKENS;
+  private model: any = null;
+  private loadingPromise: Promise<any> | null = null;
+  private readonly cache = new Map<string, EmbeddingResult>();
+
+  constructor() {
+    console.log('✅ MiniLM 임베딩 서비스 초기화 완료');
+  }
+
+  /**
+   * 텍스트를 임베딩 벡터로 변환
+   * TDD: 빈 텍스트 검증, 모델 로딩, 캐싱 적용
+   */
+  async generateEmbedding(text: string): Promise<EmbeddingResult | null> {
+    this.validateInput(text);
+    
+    const cacheKey = this.generateCacheKey(text);
+    const cached = this.cache.get(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
+    try {
+      const model = await this.getModel();
+      const processedText = this.preprocessText(text);
+      
+      const result = await model(processedText, {
+        pooling: 'mean',
+        normalize: true
+      });
+
+      // result가 이미 배열이거나 data 속성을 가진 객체일 수 있음
+      const embedding = Array.isArray(result) ? result : Array.from(result.data || result);
+      const embeddingResult: EmbeddingResult = {
+        embedding,
+        model: this.modelName,
+        usage: {
+          prompt_tokens: this.estimateTokens(text),
+          total_tokens: this.estimateTokens(text)
+        }
+      };
+
+      this.cache.set(cacheKey, embeddingResult);
+      return embeddingResult;
+
+    } catch (error) {
+      console.error('❌ MiniLM 임베딩 생성 실패:', error);
+      throw new Error(`MiniLM 임베딩 생성 실패: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+  }
+
+  /**
+   * 쿼리와 유사한 임베딩 검색
+   * TDD: 빈 배열 처리, 임계값 적용, 개수 제한
+   */
+  async searchSimilar(
+    query: string,
+    embeddings: EmbeddingData[],
+    limit: number = 10,
+    threshold: number = 0.7
+  ): Promise<SimilarityResult[]> {
+    if (embeddings.length === 0) {
+      return [];
+    }
+
+    const queryEmbedding = await this.generateEmbedding(query);
+    if (!queryEmbedding) {
+      return [];
+    }
+
+    const similarities = embeddings.map(item => {
+      const similarity = this.calculateCosineSimilarity(
+        queryEmbedding.embedding, 
+        item.embedding
+      );
+      return {
+        id: item.id,
+        content: item.content,
+        similarity,
+        score: similarity
+      };
+    });
+
+    return similarities
+      .filter(item => item.similarity >= threshold)
+      .sort((a, b) => b.similarity - a.similarity)
+      .slice(0, limit);
+  }
+
+  /**
+   * 서비스 사용 가능 여부 확인
+   * TDD: 모델 로딩 상태 확인
+   */
+  isAvailable(): boolean {
+    // MiniLM은 항상 사용 가능 (모델이 로드되지 않아도 사용 가능)
+    // 실제 모델 로딩은 generateEmbedding 호출 시 lazy loading
+    return true;
+  }
+
+  /**
+   * 모델 정보 반환
+   * TDD: 올바른 정보 반환
+   */
+  getModelInfo(): { model: string; dimensions: number; maxTokens: number } {
+    return {
+      model: this.modelName,
+      dimensions: this.dimensions,
+      maxTokens: this.maxTokens
+    };
+  }
+
+  /**
+   * 입력 검증
+   * 클린코드: 단일 책임 원칙 - 검증만 담당
+   */
+  private validateInput(text: string): void {
+    if (!text || text.trim().length === 0) {
+      throw new Error('텍스트가 비어있습니다');
+    }
+  }
+
+  /**
+   * 모델 로딩 (지연 로딩)
+   * 클린코드: 단일 책임 원칙 - 모델 로딩만 담당
+   */
+  private async getModel(): Promise<any> {
+    if (this.model) {
+      return this.model;
+    }
+
+    if (this.loadingPromise) {
+      return await this.loadingPromise;
+    }
+
+    this.loadingPromise = this.loadModel();
+    this.model = await this.loadingPromise;
+    return this.model;
+  }
+
+  /**
+   * 실제 모델 로딩
+   */
+  private async loadModel(): Promise<any> {
+    try {
+      const model = await pipeline(
+        'feature-extraction',
+        'Xenova/all-MiniLM-L6-v2'
+      );
+      console.log('✅ MiniLM 모델 로딩 완료');
+      return model;
+    } catch (error) {
+      console.error('❌ MiniLM 모델 로딩 실패:', error);
+      throw new Error(`모델 로딩 실패: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+  }
+
+  /**
+   * 텍스트 전처리
+   * 클린코드: 단일 책임 원칙 - 전처리만 담당
+   */
+  private preprocessText(text: string): string {
+    return text
+      .trim()
+      .toLowerCase()
+      .replace(/\s+/g, ' ')
+      .substring(0, this.maxTokens * 4); // 토큰 수 제한
+  }
+
+  /**
+   * 캐시 키 생성
+   */
+  private generateCacheKey(text: string): string {
+    return `minilm:${this.hashText(text)}`;
+  }
+
+  /**
+   * 텍스트 해시 생성
+   */
+  private hashText(text: string): string {
+    let hash = 0;
+    for (let i = 0; i < text.length; i++) {
+      const char = text.charCodeAt(i);
+      hash = ((hash << 5) - hash) + char;
+      hash = hash & hash; // 32bit 정수로 변환
+    }
+    return hash.toString(36);
+  }
+
+  /**
+   * 토큰 수 추정
+   */
+  private estimateTokens(text: string): number {
+    // 간단한 토큰 추정 (실제로는 더 정교한 방법 필요)
+    return Math.ceil(text.length / 4);
+  }
+
+  /**
+   * 코사인 유사도 계산
+   * 클린코드: 단일 책임 원칙 - 수학 계산만 담당
+   */
+  private calculateCosineSimilarity(vecA: number[], vecB: number[]): number {
+    if (vecA.length !== vecB.length) {
+      throw new Error('벡터 차원이 일치하지 않습니다');
+    }
+
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+
+    for (let i = 0; i < vecA.length; i++) {
+      const a = vecA[i] ?? 0;
+      const b = vecB[i] ?? 0;
+      dotProduct += a * b;
+      normA += a * a;
+      normB += b * b;
+    }
+
+    const magnitude = Math.sqrt(normA) * Math.sqrt(normB);
+    return magnitude === 0 ? 0 : dotProduct / magnitude;
+  }
+
+  /**
+   * 캐시 정리
+   */
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * 메모리 사용량 확인
+   */
+  getCacheSize(): number {
+    return this.cache.size;
+  }
+}