mcp-adr-analysis-server 2.1.11 → 2.1.19

package/dist/src/utils/research-orchestrator.d.ts

@@ -24,16 +24,94 @@ export interface ResearchAnswer {
         duration: number;
         sourcesQueried: string[];
         filesAnalyzed: number;
+        cached?: boolean;
     };
 }
+/**
+ * Research Orchestrator Class
+ *
+ * @description Coordinates multi-source research with cascading fallback strategy.
+ * Implements a hierarchical approach to answering research questions by querying
+ * sources in order of preference: project files → knowledge graph → environment → web search.
+ *
+ * Features:
+ * - Intelligent confidence scoring for each source
+ * - Configurable confidence thresholds
+ * - Result caching for performance optimization
+ * - Firecrawl integration for web search capabilities
+ * - Comprehensive error handling and fallback mechanisms
+ *
+ * @example
+ * ```typescript
+ * const orchestrator = new ResearchOrchestrator('/path/to/project', 'docs/adrs');
+ * orchestrator.setConfidenceThreshold(0.8);
+ *
+ * const result = await orchestrator.answerResearchQuestion(
+ *   'What authentication methods are used in this project?'
+ * );
+ *
+ * console.log(`Answer: ${result.answer}`);
+ * console.log(`Confidence: ${result.confidence}`);
+ * console.log(`Sources: ${result.sources.map(s => s.type).join(', ')}`);
+ * ```
+ *
+ * @since 2.0.0
+ * @category Research
+ * @category Orchestration
+ */
 export declare class ResearchOrchestrator {
     private logger;
     private projectPath;
     private adrDirectory;
     private confidenceThreshold;
+    private kgManager;
+    private cache;
+    private cacheTtl;
+    private firecrawl;
+    private config;
     constructor(projectPath?: string, adrDirectory?: string);
     /**
      * Answer a research question using cascading source hierarchy
+     *
+     * @description Executes comprehensive research using a cascading approach:
+     * 1. Project files search (fastest, most relevant)
+     * 2. Knowledge graph query (instant, context-aware)
+     * 3. Environment resources query (live data)
+     * 4. Web search fallback (external, when confidence is low)
+     *
+     * Results are cached for 5 minutes to improve performance for repeated queries.
+     *
+     * @param {string} question - The research question to investigate
+     *
+     * @returns {Promise<ResearchAnswer>} Comprehensive research results with:
+     * - `answer`: Synthesized answer from all sources
+     * - `confidence`: Overall confidence score (0-1)
+     * - `sources`: Array of source results with individual confidence scores
+     * - `needsWebSearch`: Whether web search is recommended
+     * - `metadata`: Execution metadata (duration, files analyzed, etc.)
+     *
+     * @throws {Error} When question is empty or research orchestration fails
+     *
+     * @example
+     * ```typescript
+     * const result = await orchestrator.answerResearchQuestion(
+     *   'How does authentication work in this project?'
+     * );
+     *
+     * if (result.confidence >= 0.8) {
+     *   console.log('High confidence answer:', result.answer);
+     * } else if (result.needsWebSearch) {
+     *   console.log('Consider web search for more information');
+     * }
+     *
+     * result.sources.forEach(source => {
+     *   console.log(`${source.type}: ${(source.confidence * 100).toFixed(1)}%`);
+     * });
+     * ```
+     *
+     * @since 2.0.0
+     * @category Research
+     * @category Public API
      */
     answerResearchQuestion(question: string): Promise<ResearchAnswer>;
     /**
@@ -61,10 +139,9 @@ export declare class ResearchOrchestrator {
      */
     private synthesizeAnswer;
     /**
-    /**
-     * Calculate relevance score for content
+     * Calculate relevance score for content (legacy method - kept for compatibility)
      */
-    private calculateRelevance;
+    private calculateRelevanceLegacy;
     /**
      * Extract keywords from question
      */
@@ -73,5 +150,60 @@ export declare class ResearchOrchestrator {
      * Set confidence threshold for web search fallback
      */
     setConfidenceThreshold(threshold: number): void;
+    /**
+     * SOURCE 4: Perform web search using Firecrawl (LLM-managed)
+     */
+    private performWebSearch;
+    /**
+     * Search using Firecrawl with LLM-driven query optimization
+     */
+    private searchWithFirecrawl;
+    /**
+     * Generate fallback search results when Firecrawl is not available
+     */
+    private generateFallbackSearchResults;
+    /**
+     * Generate search URLs using LLM
+     */
+    private generateSearchUrls;
+    /**
+     * Calculate relevance score using LLM
+     */
+    private calculateRelevance;
+    /**
+     * Generate search queries based on research question
+     */
+    private generateSearchQueries;
+    /**
+     * Generate cache key for research question
+     */
+    private generateCacheKey;
+    /**
+     * Get cached result if available and not expired
+     */
+    private getCachedResult;
+    /**
+     * Cache a research result
+     */
+    private setCachedResult;
+    /**
+     * Clear expired cache entries
+     */
+    cleanupCache(): void;
+    /**
+     * Clear all cache entries
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+        entries: Array<{
+            key: string;
+            age: number;
+            expires: number;
+        }>;
+    };
 }
 //# sourceMappingURL=research-orchestrator.d.ts.map

package/dist/src/utils/research-orchestrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"research-orchestrator.d.ts","sourceRoot":"","sources":["../../../src/utils/research-orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAWH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,eAAe,GAAG,iBAAiB,GAAG,aAAa,GAAG,YAAY,CAAC;IACzE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,GAAG,CAAC;IACV,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE;QACR,QAAQ,EAAE,MAAM,CAAC;QACjB,cAAc,EAAE,MAAM,EAAE,CAAC;QACzB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,mBAAmB,CAAe;gBAE9B,WAAW,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM;IAMvD;;OAEG;IACG,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IA+GvE;;OAEG;YACW,kBAAkB;IAqMhC;;OAEG;IACH,OAAO,CAAC,WAAW;IAmBnB;;OAEG;YACW,mBAAmB;IAuBjC;;OAEG;YACW,gBAAgB;IA6B9B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAa3B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAoCxB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IA0B1B;;OAEG;IACH,OAAO,CAAC,eAAe;IAuDvB;;OAEG;IACH,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;CAGhD"}
+{"version":3,"file":"research-orchestrator.d.ts","sourceRoot":"","sources":["../../../src/utils/research-orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAeH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,eAAe,GAAG,iBAAiB,GAAG,aAAa,GAAG,YAAY,CAAC;IACzE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,GAAG,CAAC;IACV,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE;QACR,QAAQ,EAAE,MAAM,CAAC;QACjB,cAAc,EAAE,MAAM,EAAE,CAAC;QACzB,aAAa,EAAE,MAAM,CAAC;QACtB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,CAAC;CACH;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,mBAAmB,CAAe;IAC1C,OAAO,CAAC,SAAS,CAAwB;IACzC,OAAO,CAAC,KAAK,CAAgD;IAC7D,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,MAAM,CAAM;gBAER,WAAW,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM;IAwBvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACG,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAuJvE;;OAEG;YACW,kBAAkB;IAqMhC;;OAEG;IACH,OAAO,CAAC,WAAW;IAmBnB;;OAEG;YACW,mBAAmB;IAiCjC;;OAEG;YACW,gBAAgB;IA6B9B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAa3B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAoCxB;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA0BhC;;OAEG;IACH,OAAO,CAAC,eAAe;IAuDvB;;OAEG;IACH,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI/C;;OAEG;YACW,gBAAgB;IAsC9B;;OAEG;YACW,mBAAmB;IA0DjC;;OAEG;IACH,OAAO,CAAC,6BAA6B;IAWrC;;OAEG;YACW,kBAAkB;IA0ChC;;OAEG;YACW,kBAAkB;IAwChC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA0C7B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAKxB;;OAEG;IACH,OAAO,CAAC,eAAe;IAevB;;OAEG;IACH,OAAO,CAAC,eAAe;IASvB;;OAEG;IACH,YAAY,IAAI,IAAI;IAcpB;;OAEG;IACH,UAAU,IAAI,IAAI;IAKlB;;OAEG;IACH,aAAa,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,KAAK,CAAC;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE;CAajG"}