memento-mcp-server 1.14.0 → 1.15.0-c

package/dist/services/triple-extraction/triple-extraction-service.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Triple 추출 서비스
+ * LLM을 사용하여 Episodic Memory의 observation에서 (subject, predicate, object) 형태의 지식 그래프 트리플을 추출합니다.
+ *
+ * AriGraph 파이프라인의 핵심 컴포넌트로, Episodic Memory에서 Semantic Memory로의 자동 학습을 지원합니다.
+ *
+ * 비용 최적화 전략:
+ * - Rate limit (토큰 버킷 알고리즘)
+ * - 캐싱 (TTL 기반)
+ * - 비용 모니터링
+ * - 에러 처리 및 폴백
+ */
+import type { TripleExtractionResult, TripleExtractionOptions } from '../../shared/types/triple-extraction.js';
+/**
+ * LLM 비용 모니터링
+ */
+interface LLMCostMetrics {
+    totalCalls: number;
+    totalTokens: number;
+    totalCost: number;
+    lastReset: number;
+}
+/**
+ * Triple 추출 서비스
+ */
+export declare class TripleExtractionService {
+    private openaiClient;
+    private geminiClient;
+    private readonly preferredProvider;
+    private readonly cache;
+    private readonly rateLimiter;
+    private readonly costMetrics;
+    private readonly canonicalizer;
+    private readonly entityLinker;
+    private readonly statistics;
+    private readonly DEFAULT_TEMPERATURE;
+    private readonly DEFAULT_MAX_TOKENS;
+    private readonly CACHE_SIZE;
+    private readonly CACHE_TTL_MS;
+    private readonly RATE_LIMITER_CAPACITY;
+    private readonly RATE_LIMITER_REFILL_RATE;
+    private readonly SUCCESS_SAMPLING_RATE;
+    constructor();
+    /**
+     * LLM 클라이언트 초기화
+     * 환경 변수 LLM_PROVIDER에 따라 프로바이더 선택
+     */
+    private initializeClients;
+    /**
+     * LLM 서비스 사용 가능 여부 확인
+     */
+    isAvailable(): boolean;
+    /**
+     * Observation 텍스트에서 Triple 추출
+     *
+     * @param observation Episodic Memory의 content (observation 텍스트)
+     * @param options 추출 옵션
+     * @param memoryId Episodic Memory ID (로깅용, 선택사항)
+     * @returns Triple 추출 결과
+     */
+    extractTriples(observation: string, options?: TripleExtractionOptions, memoryId?: string): Promise<TripleExtractionResult>;
+    /**
+     * LLM을 사용하여 Triple 추출
+     *
+     * @param observation Observation 텍스트
+     * @param provider LLM Provider
+     * @param options 추출 옵션
+     * @returns Triple 추출 결과와 rawLLMOutput
+     */
+    private extractWithLLM;
+    /**
+     * OpenAI를 사용하여 Triple 추출
+     */
+    private extractWithOpenAI;
+    /**
+     * Gemini를 사용하여 Triple 추출
+     */
+    private extractWithGemini;
+    /**
+     * Ollama를 사용하여 Triple 추출
+     */
+    private extractWithOllama;
+    /**
+     * Ollama 모델 존재 여부 확인
+     */
+    private checkOllamaModel;
+    /**
+     * LLM 응답을 파싱하여 Triple 배열 추출
+     *
+     * @param responseText LLM 원본 응답 텍스트
+     * @returns 파싱 결과 (success, triples, error)
+     */
+    private parseLLMResponse;
+    /**
+     * JSON 텍스트에서 JSON 객체 추출
+     */
+    private extractJSON;
+    /**
+     * Triple 유효성 검증
+     */
+    private isValidTriple;
+    /**
+     * 비용 메트릭 업데이트
+     */
+    private updateCostMetrics;
+    /**
+     * 실패 사유 분류
+     * 에러 타입과 컨텍스트를 기반으로 적절한 실패 사유를 반환합니다.
+     *
+     * @param error 에러 메시지 또는 파싱 결과의 error
+     * @param rawLLMOutput 원본 LLM 응답 (선택사항)
+     * @param errorType 파싱 결과의 에러 타입 (선택사항)
+     * @returns 분류된 실패 사유
+     */
+    private classifyFailureReason;
+    /**
+     * Triple 추출 결과 로깅
+     * rawLLMOutput 저장 정책에 따라 로그 파일에 저장합니다.
+     *
+     * 저장 정책:
+     * - 성공 케이스: 10% 샘플링
+     * - 실패 케이스: 100% 저장
+     * - PII 마스킹은 로거에서 처리
+     *
+     * @param result Triple 추출 결과
+     * @param memoryId Episodic Memory ID (선택사항)
+     * @param observation Observation 텍스트 (선택사항)
+     * @param rawLLMOutput 원본 LLM 응답 (로깅용)
+     */
+    private logExtractionResult;
+    /**
+     * 에러 타입 분류
+     * 에러의 특성에 따라 분류하여 적절한 처리 전략을 수립합니다.
+     *
+     * @param error 에러 객체
+     * @returns 에러 타입
+     */
+    private classifyErrorType;
+    /**
+     * Triple 추출 단계별 성공 여부 추적
+     * 각 triple에 대해 canonicalization과 entityLinking을 수행하여 steps를 생성합니다.
+     *
+     * @param triples 추출된 triple 배열
+     * @returns 추적된 steps 정보
+     */
+    private trackExtractionSteps;
+    /**
+     * 실패 결과 생성
+     *
+     * @param failureReason 실패 사유
+     * @param rawLLMOutput 원본 LLM 응답 또는 에러 메시지 (선택사항)
+     * @returns 실패 결과
+     */
+    private createFailureResult;
+    /**
+     * 비용 통계 조회
+     */
+    getCostMetrics(): LLMCostMetrics;
+    /**
+     * Triple 추출 통계 조회
+     *
+     * PRD 8.1: Triple 추출 통계
+     * - 성공률: 성공한 Triple 추출 수 / 전체 시도 수
+     * - 평균 추출 시간
+     * - LLM 호출 횟수 및 비용
+     * - 실패 사유별 통계
+     *
+     * @returns Triple 추출 통계
+     */
+    getStatistics(): import("./triple-extraction-statistics.js").TripleExtractionStatistics;
+    /**
+     * 실패 사유별 통계 조회
+     *
+     * PRD 8.1: 실패 사유별 통계
+     *
+     * @returns 실패 사유별 통계
+     */
+    getFailureReasonStatistics(): Record<string, number>;
+}
+export {};
+//# sourceMappingURL=triple-extraction-service.d.ts.map

package/dist/services/triple-extraction/triple-extraction-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"triple-extraction-service.d.ts","sourceRoot":"","sources":["../../../src/services/triple-extraction/triple-extraction-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAYH,OAAO,KAAK,EAEV,sBAAsB,EACtB,uBAAuB,EAIxB,MAAM,yCAAyC,CAAC;AAyDjD;;GAEG;AACH,UAAU,cAAc;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,YAAY,CAAmC;IACvD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAwC;IAC1E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyB;IACrD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiB;IAC7C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAyB;IACvD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoC;IAG/D,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAO;IAC3C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAQ;IAC3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAO;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;IACnD,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAK;IAC3C,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAK;IAG9C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAO;;IAwB7C;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAoDzB;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;;;;;;OAOG;IACG,cAAc,CAClB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,uBAA4B,EACrC,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,sBAAsB,CAAC;IAsFlC;;;;;;;OAOG;YACW,cAAc;IAsG5B;;OAEG;YACW,iBAAiB;IAiD/B;;OAEG;YACW,iBAAiB;IAgD/B;;OAEG;YACW,iBAAiB;IAuG/B;;OAEG;YACW,gBAAgB;IAmB9B;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAuExB;;OAEG;IACH,OAAO,CAAC,WAAW;IAyBnB;;OAEG;IACH,OAAO,CAAC,aAAa;IAarB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAsBzB;;;;;;;;OAQG;IACH,OAAO,CAAC,qBAAqB;IAuD7B;;;;;;;;;;;;;OAaG;YACW,mBAAmB;IAyCjC;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAqDzB;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;IAkD5B;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAmB3B;;OAEG;IACH,cAAc,IAAI,cAAc;IAIhC;;;;;;;;;;OAUG;IACH,aAAa;IAIb;;;;;;OAMG;IACH,0BAA0B;CAG3B"}