@nahisaho/musubix-deep-research 3.4.0

package/README.md

@@ -0,0 +1,89 @@
+# @nahisaho/musubix-deep-research
+
+Deep Research Integration for MUSUBIX - Iterative search-read-reason cycle for AI agents during requirements and design phases.
+
+## Features
+
+- 🔄 **Iterative Research Cycle**: Search → Read → Reason → Reflect loop
+- 🔍 **Multi-Provider Search**: Jina AI (primary), Brave (fallback 1), DuckDuckGo (fallback 2)
+- 🧠 **LM API Integration**: VS Code LM API (GitHub Copilot) for reasoning
+- 📚 **Knowledge Accumulation**: Persistent knowledge base across iterations
+- 💰 **Token Budget Management**: Automatic tracking and limits
+- 📊 **Research Reports**: Markdown/JSON formatted reports with citations
+
+## Installation
+
+```bash
+npm install @nahisaho/musubix-deep-research
+```
+
+## Usage
+
+### CLI
+
+```bash
+# Start deep research
+npx musubix deep-research "How to implement authentication in TypeScript?"
+
+# With options
+npx musubix deep-research "TypeScript decorators" \
+  --max-iterations 5 \
+  --token-budget 10000 \
+  --output report.md
+```
+
+### Programmatic API
+
+```typescript
+import { ResearchEngine, ResearchConfig } from '@nahisaho/musubix-deep-research';
+
+const config: ResearchConfig = {
+  query: 'How to implement authentication in TypeScript?',
+  maxIterations: 10,
+  tokenBudget: 15000,
+  providers: {
+    jinaApiKey: process.env.JINA_API_KEY,
+    braveApiKey: process.env.BRAVE_API_KEY,
+  },
+};
+
+const engine = new ResearchEngine(config);
+const report = await engine.research();
+
+console.log(report.summary);
+console.log(`Found ${report.findings.length} findings`);
+```
+
+## Architecture
+
+Based on **Template Method Pattern** (ADR-v3.4.0-001):
+
+```
+ResearchEngine (Template Method)
+  ├─ initialize()
+  ├─ while (!shouldStop())
+  │   ├─ generateQuestions()  → LMReasoning
+  │   ├─ search()             → SearchProviderFactory
+  │   ├─ read()               → JinaProvider.read()
+  │   ├─ reason()             → LMReasoning
+  │   └─ logIteration()       → TrajectoryLogger
+  └─ generateReport()         → ReportGenerator
+```
+
+## Requirements
+
+- Node.js >= 20.0.0
+- npm >= 10.0.0
+- VS Code with GitHub Copilot (for LM API)
+- Jina AI API Key (recommended)
+
+## License
+
+MIT
+
+## Documentation
+
+- [Requirements](../../storage/specs/REQ-MUSUBIX-v3.4.0.md)
+- [Design](../../storage/design/DES-DR-v3.4.0.md)
+- [ADRs](../../docs/adr/)
+- [Tasks](../../storage/tasks/TSK-DR-v3.4.0.md)

package/dist/engine/research-engine.d.ts

@@ -0,0 +1,97 @@
+import { KnowledgeBase } from '../knowledge/knowledge-base.js';
+import { TokenTracker } from '../utils/token-tracker.js';
+import { TrajectoryLogger } from '../utils/trajectory-logger.js';
+import { ReportGenerator } from '../reporters/report-generator.js';
+import type { ResearchConfig, ResearchReport, ReflectiveQuestion, SearchResult, WebContent, KnowledgeItem } from '../types/index.js';
+/**
+ * Research Engine - Main orchestrator using Template Method Pattern
+ *
+ * REQ: REQ-DR-CORE-001 - Iterative search-read-reason cycle
+ * ADR: ADR-v3.4.0-001 - Template Method Pattern architecture
+ *
+ * Flow:
+ * 1. initialize()
+ * 2. while (!shouldStop())
+ *    a. generateQuestions()
+ *    b. search()
+ *    c. read()
+ *    d. reason()
+ *    e. evaluate()
+ * 3. generateReport()
+ */
+export declare class ResearchEngine {
+    protected knowledge: KnowledgeBase;
+    protected tokenTracker: TokenTracker;
+    protected logger: TrajectoryLogger;
+    protected reportGenerator: ReportGenerator;
+    protected config: ResearchConfig;
+    protected iteration: number;
+    protected startTime: number;
+    protected definitiveAnswer: string | null;
+    constructor(config: ResearchConfig);
+    /**
+     * Main research method - Template Method
+     *
+     * REQ: REQ-DR-CORE-001 - Iterative cycle
+     */
+    research(): Promise<ResearchReport>;
+    /**
+     * Initialize research session
+     */
+    protected initialize(): void;
+    /**
+     * Check if research should stop
+     *
+     * Stopping conditions:
+     * 1. Max iterations reached
+     * 2. Token budget exceeded
+     * 3. Definitive answer found
+     */
+    protected shouldStop(): boolean;
+    /**
+     * Hook: Generate reflective questions
+     * Override in subclass or use LMReasoning
+     */
+    protected generateQuestions(): Promise<ReflectiveQuestion[]>;
+    /**
+     * Hook: Search for information
+     * Override in subclass or use SearchProviderFactory
+     */
+    protected search(_questions: ReflectiveQuestion[]): Promise<SearchResult[]>;
+    /**
+     * Hook: Read web contents
+     * Override in subclass or use JinaProvider
+     */
+    protected read(_results: SearchResult[]): Promise<WebContent[]>;
+    /**
+     * Hook: Reason and extract knowledge
+     * Override in subclass or use LMReasoning
+     */
+    protected reason(contents: WebContent[]): Promise<KnowledgeItem[]>;
+    /**
+     * Check if answer is definitive
+     * Override in subclass or use LMReasoning
+     */
+    protected isAnswerDefinitive(): Promise<boolean>;
+    /**
+     * Generate final research report
+     */
+    protected generateFinalReport(): Promise<ResearchReport>;
+    /**
+     * Validate configuration
+     */
+    private validateConfig;
+    /**
+     * Get current knowledge base (for testing)
+     */
+    getKnowledge(): KnowledgeBase;
+    /**
+     * Get token tracker (for testing)
+     */
+    getTokenTracker(): TokenTracker;
+    /**
+     * Get trajectory logger (for testing)
+     */
+    getLogger(): TrajectoryLogger;
+}
+//# sourceMappingURL=research-engine.d.ts.map

package/dist/engine/research-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-engine.d.ts","sourceRoot":"","sources":["../../src/engine/research-engine.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,UAAU,EACV,aAAa,EACd,MAAM,mBAAmB,CAAC;AAG3B;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,cAAc;IACzB,SAAS,CAAC,SAAS,EAAE,aAAa,CAAC;IACnC,SAAS,CAAC,YAAY,EAAE,YAAY,CAAC;IACrC,SAAS,CAAC,MAAM,EAAE,gBAAgB,CAAC;IACnC,SAAS,CAAC,eAAe,EAAE,eAAe,CAAC;IAE3C,SAAS,CAAC,MAAM,EAAE,cAAc,CAAC;IACjC,SAAS,CAAC,SAAS,EAAE,MAAM,CAAK;IAChC,SAAS,CAAC,SAAS,EAAE,MAAM,CAAK;IAChC,SAAS,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAQ;gBAErC,MAAM,EAAE,cAAc;IAelC;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,cAAc,CAAC;IA4DzC;;OAEG;IACH,SAAS,CAAC,UAAU,IAAI,IAAI;IAU5B;;;;;;;OAOG;IACH,SAAS,CAAC,UAAU,IAAI,OAAO;IAqB/B;;;OAGG;cACa,iBAAiB,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAWlE;;;OAGG;cACa,MAAM,CAAC,UAAU,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAOjF;;;OAGG;cACa,IAAI,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAOrE;;;OAGG;cACa,MAAM,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAoBxE;;;OAGG;cACa,kBAAkB,IAAI,OAAO,CAAC,OAAO,CAAC;IActD;;OAEG;cACa,mBAAmB,IAAI,OAAO,CAAC,cAAc,CAAC;IAuB9D;;OAEG;IACH,OAAO,CAAC,cAAc;IActB;;OAEG;IACH,YAAY,IAAI,aAAa;IAI7B;;OAEG;IACH,eAAe,IAAI,YAAY;IAI/B;;OAEG;IACH,SAAS,IAAI,gBAAgB;CAG9B"}

package/dist/engine/research-engine.js

@@ -0,0 +1,260 @@
+// Research Engine - Template Method Pattern
+// TSK-DR-001
+// REQ: REQ-DR-CORE-001
+// ADR: ADR-v3.4.0-001
+import { KnowledgeBase } from '../knowledge/knowledge-base.js';
+import { TokenTracker } from '../utils/token-tracker.js';
+import { TrajectoryLogger } from '../utils/trajectory-logger.js';
+import { ReportGenerator } from '../reporters/report-generator.js';
+import { InvalidConfigurationError } from '../types/errors.js';
+/**
+ * Research Engine - Main orchestrator using Template Method Pattern
+ *
+ * REQ: REQ-DR-CORE-001 - Iterative search-read-reason cycle
+ * ADR: ADR-v3.4.0-001 - Template Method Pattern architecture
+ *
+ * Flow:
+ * 1. initialize()
+ * 2. while (!shouldStop())
+ *    a. generateQuestions()
+ *    b. search()
+ *    c. read()
+ *    d. reason()
+ *    e. evaluate()
+ * 3. generateReport()
+ */
+export class ResearchEngine {
+    knowledge;
+    tokenTracker;
+    logger;
+    reportGenerator;
+    config;
+    iteration = 0;
+    startTime = 0;
+    definitiveAnswer = null;
+    constructor(config) {
+        this.validateConfig(config);
+        this.config = {
+            maxIterations: 10,
+            tokenBudget: 15000,
+            outputFormat: 'markdown',
+            ...config,
+        };
+        this.knowledge = new KnowledgeBase();
+        this.tokenTracker = new TokenTracker(this.config.tokenBudget);
+        this.logger = new TrajectoryLogger();
+        this.reportGenerator = new ReportGenerator();
+    }
+    /**
+     * Main research method - Template Method
+     *
+     * REQ: REQ-DR-CORE-001 - Iterative cycle
+     */
+    async research() {
+        this.initialize();
+        while (!this.shouldStop()) {
+            console.log(`\n🔍 === Iteration ${this.iteration + 1}/${this.config.maxIterations} ===`);
+            try {
+                // Generate reflective questions
+                const questions = await this.generateQuestions();
+                // Search for information
+                const searchResults = await this.search(questions);
+                this.logger.logIteration({
+                    iteration: this.iteration,
+                    action: {
+                        type: 'search',
+                        query: questions[0]?.question || this.config.query,
+                        resultsCount: searchResults.length,
+                    },
+                    tokensUsed: 0,
+                    knowledgeGained: 0,
+                    timestamp: Date.now(),
+                });
+                // Read web contents
+                const contents = await this.read(searchResults);
+                // Reason and extract knowledge
+                const knowledgeItems = await this.reason(contents);
+                this.knowledge.addAll(knowledgeItems);
+                this.logger.logIteration({
+                    iteration: this.iteration,
+                    action: {
+                        type: 'reason',
+                        tokensUsed: 0, // Updated by LMReasoning
+                        knowledgeGained: knowledgeItems.length,
+                    },
+                    tokensUsed: 0,
+                    knowledgeGained: knowledgeItems.length,
+                    timestamp: Date.now(),
+                });
+                // Evaluate if answer is definitive
+                if (await this.isAnswerDefinitive()) {
+                    console.log('✅ Definitive answer found');
+                    break;
+                }
+                this.iteration++;
+            }
+            catch (error) {
+                console.error(`❌ Error in iteration ${this.iteration}:`, error);
+                // Continue to next iteration on non-fatal errors
+                this.iteration++;
+            }
+        }
+        return this.generateFinalReport();
+    }
+    /**
+     * Initialize research session
+     */
+    initialize() {
+        this.iteration = 0;
+        this.startTime = Date.now();
+        this.definitiveAnswer = null;
+        console.log(`🚀 Starting research: "${this.config.query}"`);
+        console.log(`   Max iterations: ${this.config.maxIterations}`);
+        console.log(`   Token budget: ${this.config.tokenBudget}`);
+    }
+    /**
+     * Check if research should stop
+     *
+     * Stopping conditions:
+     * 1. Max iterations reached
+     * 2. Token budget exceeded
+     * 3. Definitive answer found
+     */
+    shouldStop() {
+        // Max iterations
+        if (this.iteration >= this.config.maxIterations) {
+            console.log('⏹️  Max iterations reached');
+            return true;
+        }
+        // Token budget exceeded
+        if (this.tokenTracker.isExceeded()) {
+            console.log('⏹️  Token budget exceeded');
+            return true;
+        }
+        // Definitive answer found
+        if (this.definitiveAnswer !== null) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Hook: Generate reflective questions
+     * Override in subclass or use LMReasoning
+     */
+    async generateQuestions() {
+        // Default implementation: return initial query as question
+        return [
+            {
+                question: this.config.query,
+                reason: 'Initial research question',
+                priority: 5,
+            },
+        ];
+    }
+    /**
+     * Hook: Search for information
+     * Override in subclass or use SearchProviderFactory
+     */
+    async search(_questions) {
+        // Default implementation: return empty results
+        // Will be implemented in TSK-DR-006 (SearchProviderFactory)
+        console.log('⚠️  search() not implemented yet, returning empty results');
+        return [];
+    }
+    /**
+     * Hook: Read web contents
+     * Override in subclass or use JinaProvider
+     */
+    async read(_results) {
+        // Default implementation: return empty contents
+        // Will be implemented in TSK-DR-007 (JinaProvider)
+        console.log('⚠️  read() not implemented yet, returning empty contents');
+        return [];
+    }
+    /**
+     * Hook: Reason and extract knowledge
+     * Override in subclass or use LMReasoning
+     */
+    async reason(contents) {
+        // Default implementation: extract basic knowledge
+        const knowledgeItems = [];
+        for (const content of contents) {
+            for (const fact of content.extractedFacts) {
+                knowledgeItems.push({
+                    type: 'fact',
+                    content: fact,
+                    sources: [content.url],
+                    relevance: 0.7,
+                    iteration: this.iteration,
+                    timestamp: Date.now(),
+                });
+            }
+        }
+        return knowledgeItems;
+    }
+    /**
+     * Check if answer is definitive
+     * Override in subclass or use LMReasoning
+     */
+    async isAnswerDefinitive() {
+        // Default implementation: check knowledge count
+        // Will be enhanced with LM reasoning in TSK-DR-010
+        const knowledgeCount = this.knowledge.size();
+        // Consider answer definitive if we have 10+ knowledge items
+        if (knowledgeCount >= 10) {
+            this.definitiveAnswer = this.knowledge.getSummary(5);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Generate final research report
+     */
+    async generateFinalReport() {
+        const durationMs = Date.now() - this.startTime;
+        const totalTokens = this.tokenTracker.getUsed();
+        console.log(`\n📊 Research completed in ${(durationMs / 1000).toFixed(2)}s`);
+        console.log(`   Iterations: ${this.iteration}`);
+        console.log(`   Tokens used: ${totalTokens}/${this.config.tokenBudget}`);
+        console.log(`   Knowledge items: ${this.knowledge.size()}`);
+        const report = await this.reportGenerator.generate(this.config.query, this.knowledge, this.logger.getLogs(), {
+            totalTokens,
+            durationMs,
+            iterations: this.iteration,
+        });
+        return report;
+    }
+    /**
+     * Validate configuration
+     */
+    validateConfig(config) {
+        if (!config.query || config.query.trim().length === 0) {
+            throw new InvalidConfigurationError('Query is required');
+        }
+        if (config.maxIterations !== undefined && config.maxIterations <= 0) {
+            throw new InvalidConfigurationError('maxIterations must be positive');
+        }
+        if (config.tokenBudget !== undefined && config.tokenBudget <= 0) {
+            throw new InvalidConfigurationError('tokenBudget must be positive');
+        }
+    }
+    /**
+     * Get current knowledge base (for testing)
+     */
+    getKnowledge() {
+        return this.knowledge;
+    }
+    /**
+     * Get token tracker (for testing)
+     */
+    getTokenTracker() {
+        return this.tokenTracker;
+    }
+    /**
+     * Get trajectory logger (for testing)
+     */
+    getLogger() {
+        return this.logger;
+    }
+}
+//# sourceMappingURL=research-engine.js.map

package/dist/engine/research-engine.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+export { ResearchEngine } from './engine/research-engine.js';
+export { KnowledgeBase } from './knowledge/knowledge-base.js';
+export { SearchProviderFactory, createSearchProviderFactory } from './providers/provider-factory.js';
+export type { ProviderConfig } from './providers/provider-factory.js';
+export { JinaProvider, createJinaProvider } from './providers/jina-provider.js';
+export { BraveProvider, createBraveProvider } from './providers/brave-provider.js';
+export { DuckDuckGoProvider, createDuckDuckGoProvider } from './providers/duckduckgo-provider.js';
+export { LMReasoning, createLMReasoning } from './reasoning/lm-reasoning.js';
+export type { LMProvider, LMGenerationOptions } from './reasoning/lm-reasoning.js';
+export { VSCodeLMProvider, createVSCodeLMProvider } from './providers/vscode-lm-provider.js';
+export { ExpertIntegration, createExpertIntegration } from './providers/expert-integration.js';
+export { SecretManager } from './security/secret-manager.js';
+export { ContentSanitizer } from './security/content-sanitizer.js';
+export { SecureLogger } from './security/secure-logger.js';
+export * from './performance/index.js';
+export { TokenTracker } from './utils/token-tracker.js';
+export { TrajectoryLogger } from './utils/trajectory-logger.js';
+export { ReportGenerator } from './reporters/report-generator.js';
+export * from './mcp/index.js';
+export type * from './types/index.js';
+export * from './types/errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAG9D,OAAO,EAAE,qBAAqB,EAAE,2BAA2B,EAAE,MAAM,iCAAiC,CAAC;AACrG,YAAY,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACnF,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,oCAAoC,CAAC;AAGlG,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAC7E,YAAY,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACnF,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AAG/F,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAG3D,cAAc,wBAAwB,CAAC;AAGvC,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAGlE,cAAc,gBAAgB,CAAC;AAa/B,mBAAmB,kBAAkB,CAAC;AAGtC,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,30 @@
+// Deep Research Integration - Public API
+// Version: 3.4.0
+// REQ: REQ-DR-CORE-001 through REQ-DR-NFR-006
+// Core Engine
+export { ResearchEngine } from './engine/research-engine.js';
+export { KnowledgeBase } from './knowledge/knowledge-base.js';
+// Providers
+export { SearchProviderFactory, createSearchProviderFactory } from './providers/provider-factory.js';
+export { JinaProvider, createJinaProvider } from './providers/jina-provider.js';
+export { BraveProvider, createBraveProvider } from './providers/brave-provider.js';
+export { DuckDuckGoProvider, createDuckDuckGoProvider } from './providers/duckduckgo-provider.js';
+// Reasoning (TSK-DR-010~012)
+export { LMReasoning, createLMReasoning } from './reasoning/lm-reasoning.js';
+export { VSCodeLMProvider, createVSCodeLMProvider } from './providers/vscode-lm-provider.js';
+export { ExpertIntegration, createExpertIntegration } from './providers/expert-integration.js';
+// Security (TSK-DR-013~015)
+export { SecretManager } from './security/secret-manager.js';
+export { ContentSanitizer } from './security/content-sanitizer.js';
+export { SecureLogger } from './security/secure-logger.js';
+// Performance (TSK-DR-016~018)
+export * from './performance/index.js';
+// Utils
+export { TokenTracker } from './utils/token-tracker.js';
+export { TrajectoryLogger } from './utils/trajectory-logger.js';
+export { ReportGenerator } from './reporters/report-generator.js';
+// MCP Tools (TSK-DR-020)
+export * from './mcp/index.js';
+// Errors
+export * from './types/errors.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,iBAAiB;AACjB,8CAA8C;AAE9C,cAAc;AACd,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAE9D,YAAY;AACZ,OAAO,EAAE,qBAAqB,EAAE,2BAA2B,EAAE,MAAM,iCAAiC,CAAC;AAErG,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACnF,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,oCAAoC,CAAC;AAElG,6BAA6B;AAC7B,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAE7E,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AAE/F,4BAA4B;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D,+BAA+B;AAC/B,cAAc,wBAAwB,CAAC;AAEvC,QAAQ;AACR,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAElE,yBAAyB;AACzB,cAAc,gBAAgB,CAAC;AAe/B,SAAS;AACT,cAAc,mBAAmB,CAAC"}

package/dist/integration/knowledge-store.d.ts

@@ -0,0 +1,117 @@
+import type { Entity, Relation, QueryFilter, SearchOptions, TraverseOptions } from '@musubix/knowledge';
+/**
+ * Configuration for Knowledge Store integration
+ */
+export interface KnowledgeStoreConfig {
+    /** Base path for knowledge storage (default: .knowledge) */
+    basePath?: string;
+    /** Auto-save on updates */
+    autoSave?: boolean;
+    /** Load on initialization */
+    autoLoad?: boolean;
+}
+/**
+ * Knowledge item from research
+ */
+export interface KnowledgeItem {
+    content: string;
+    type: 'fact' | 'concept' | 'relation' | 'source';
+    confidence?: number;
+    iteration: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Storage result
+ */
+export interface StorageResult {
+    entityId: string;
+    stored: boolean;
+    message?: string;
+}
+/**
+ * Query result with context
+ */
+export interface KnowledgeQueryResult {
+    entities: Entity[];
+    relationCount: number;
+    depth: number;
+}
+/**
+ * Knowledge Store Integration
+ *
+ * Integrates Deep Research with @musubix/knowledge package
+ * for persistent knowledge graph storage.
+ *
+ * Features:
+ * - Store research results as entities
+ * - Query knowledge graph
+ * - Track relations between findings
+ * - Git-friendly JSON storage
+ * - Export/import knowledge base
+ */
+export declare class KnowledgeStoreIntegration {
+    private store;
+    private config;
+    private entityCounter;
+    constructor(config?: KnowledgeStoreConfig);
+    /**
+     * Initialize the knowledge store
+     */
+    initialize(): Promise<void>;
+    /**
+     * Check if knowledge store is available
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Store a knowledge item from research
+     */
+    storeKnowledgeItem(item: KnowledgeItem, query: string): Promise<StorageResult>;
+    /**
+     * Query knowledge base
+     */
+    query(filter: QueryFilter): Promise<Entity[]>;
+    /**
+     * Search knowledge base by text
+     */
+    search(text: string, options?: SearchOptions): Promise<Entity[]>;
+    /**
+     * Get related entities (graph traversal)
+     */
+    getRelated(entityId: string, options?: TraverseOptions): Promise<KnowledgeQueryResult>;
+    /**
+     * Add relation between entities
+     */
+    addRelation(relation: Omit<Relation, 'id'>): Promise<void>;
+    /**
+     * Export knowledge base
+     */
+    export(): Promise<string>;
+    /**
+     * Get statistics
+     */
+    getStats(): {
+        entityCount: number;
+        relationCount: number;
+    };
+    /**
+     * Save knowledge store to disk
+     */
+    save(): Promise<void>;
+    /**
+     * Generate entity ID
+     */
+    private generateEntityId;
+    /**
+     * Extract title from content (first 50 chars)
+     */
+    private extractTitle;
+    /**
+     * Load @musubix/knowledge package dynamically
+     */
+    private loadKnowledge;
+}
+/**
+ * Factory function to create Knowledge Store integration
+ */
+export declare function createKnowledgeStoreIntegration(config?: KnowledgeStoreConfig): KnowledgeStoreIntegration;
+//# sourceMappingURL=knowledge-store.d.ts.map

package/dist/integration/knowledge-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-store.d.ts","sourceRoot":"","sources":["../../src/integration/knowledge-store.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,MAAM,EACN,QAAQ,EAER,WAAW,EACX,aAAa,EACb,eAAe,EAChB,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAWD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,yBAAyB;IACpC,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,aAAa,CAAK;gBAEd,MAAM,CAAC,EAAE,oBAAoB;IAIzC;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAejC;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAWrC;;OAEG;IACG,kBAAkB,CACtB,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,aAAa,CAAC;IA0CzB;;OAEG;IACG,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAQnD;;OAEG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAQtE;;OAEG;IACG,UAAU,CACd,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,oBAAoB,CAAC;IAehC;;OAEG;IACG,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBhE;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAmB/B;;OAEG;IACH,QAAQ,IAAI;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE;IAQ1D;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAa3B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;OAEG;IACH,OAAO,CAAC,YAAY;IAKpB;;OAEG;YACW,aAAa;CAS5B;AAED;;GAEG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,CAAC,EAAE,oBAAoB,GAC5B,yBAAyB,CAE3B"}