@mxf-dev/core 1.0.0

package/src/services/McpToolDocumentationService.ts

@@ -0,0 +1,238 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+
+/**
+ * MCP Tool Documentation Service
+ * 
+ * Provides comprehensive documentation, examples, and validation helpers
+ * for MCP tools to improve agent tool calling accuracy.
+ */
+
+import { Logger } from '../utils/Logger.js';
+import { McpToolDefinition } from '../protocols/mcp/McpServerTypes.js';
+import { generateToolDocumentation } from '../protocols/mcp/McpToolSchema.js';
+import { generateToolCallExamples } from '../protocols/mcp/McpToolCallParser.js';
+
+const logger = new Logger('info', 'McpToolDocumentationService', 'server');
+
+export class McpToolDocumentationService {
+    private static instance: McpToolDocumentationService;
+    private toolCache: Map<string, McpToolDefinition> = new Map();
+    
+    private constructor() {}
+    
+    /**
+     * Get singleton instance
+     */
+    public static getInstance(): McpToolDocumentationService {
+        if (!McpToolDocumentationService.instance) {
+            McpToolDocumentationService.instance = new McpToolDocumentationService();
+        }
+        return McpToolDocumentationService.instance;
+    }
+    
+    /**
+     * Register a tool for documentation
+     */
+    public registerTool(tool: McpToolDefinition): void {
+        this.toolCache.set(tool.name, tool);
+    }
+    
+    /**
+     * Get comprehensive help for a specific tool
+     */
+    public getToolHelp(toolName: string): string {
+        const tool = this.toolCache.get(toolName);
+        if (!tool) {
+            return `Tool "${toolName}" not found. Use listTools() to see available tools.`;
+        }
+        
+        const lines: string[] = [];
+        
+        // Basic documentation
+        lines.push(generateToolDocumentation(tool));
+        lines.push('');
+        
+        // Call format examples
+        lines.push('### How to Call This Tool:');
+        lines.push('');
+        const examples = generateToolCallExamples(tool.name, tool.inputSchema);
+        examples.forEach((example, index) => {
+            lines.push(`#### Format ${index + 1}:`);
+            lines.push('```');
+            lines.push(example);
+            lines.push('```');
+            lines.push('');
+        });
+        
+        // Common mistakes
+        lines.push('### Common Mistakes to Avoid:');
+        lines.push('');
+        lines.push(this.getCommonMistakes(tool));
+        
+        return lines.join('\n');
+    }
+    
+    /**
+     * Get quick reference for all tools
+     */
+    public getQuickReference(): string {
+        const lines: string[] = [
+            '# MCP Tools Quick Reference',
+            '',
+            'Format your tool calls using one of these patterns:',
+            '- XML: `<tool>tool_name</tool><parameters>{...}</parameters>`',
+            '- Function: `tool_name({...})`',
+            '- Structured: `TOOL: tool_name PARAMETERS: {...}`',
+            '',
+            '## Available Tools:',
+            ''
+        ];
+        
+        // Group tools by category
+        const categories = new Map<string, McpToolDefinition[]>();
+        
+        for (const tool of this.toolCache.values()) {
+            const category = tool.metadata?.category || 'general';
+            if (!categories.has(category)) {
+                categories.set(category, []);
+            }
+            categories.get(category)!.push(tool);
+        }
+        
+        // Display by category
+        for (const [category, tools] of categories) {
+            lines.push(`### ${category.charAt(0).toUpperCase() + category.slice(1)}`);
+            lines.push('');
+            
+            for (const tool of tools) {
+                const required = tool.inputSchema.required || [];
+                lines.push(`- **${tool.name}**: ${tool.description}`);
+                lines.push(`  - Required: ${required.length > 0 ? required.join(', ') : 'none'}`);
+            }
+            lines.push('');
+        }
+        
+        return lines.join('\n');
+    }
+    
+    /**
+     * Get validation tips for better tool calling
+     */
+    public getValidationTips(): string[] {
+        return [
+            'Always provide all required parameters',
+            'Check parameter types match the schema (string, number, boolean, etc.)',
+            'Use proper JSON formatting for parameters',
+            'Don\'t include extra properties not defined in the schema',
+            'For file paths, use absolute paths starting with /',
+            'For enum parameters, use exact values from the allowed list',
+            'Check minimum/maximum constraints for numbers',
+            'Verify string patterns match required formats'
+        ];
+    }
+    
+    /**
+     * Generate common mistakes for a specific tool
+     */
+    private getCommonMistakes(tool: McpToolDefinition): string {
+        const mistakes: string[] = [];
+        const schema = tool.inputSchema;
+        
+        if (schema.required && schema.required.length > 0) {
+            mistakes.push(`- Forgetting required parameters: ${schema.required.join(', ')}`);
+        }
+        
+        if (schema.properties) {
+            for (const [key, prop] of Object.entries(schema.properties as Record<string, any>)) {
+                if (prop.type === 'string' && prop.minLength) {
+                    mistakes.push(`- Providing empty string for "${key}" (minimum length: ${prop.minLength})`);
+                }
+                if (prop.enum) {
+                    mistakes.push(`- Using invalid value for "${key}" (must be one of: ${prop.enum.join(', ')})`);
+                }
+                if (prop.pattern) {
+                    mistakes.push(`- "${key}" must match pattern: ${prop.pattern}`);
+                }
+            }
+        }
+        
+        if (schema.additionalProperties === false) {
+            mistakes.push('- Including properties not defined in the schema');
+        }
+        
+        mistakes.push('- Using wrong parameter types (e.g., string instead of number)');
+        mistakes.push('- Malformed JSON in parameters');
+        
+        return mistakes.join('\n');
+    }
+    
+    /**
+     * Get suggested fix for a validation error
+     */
+    public getSuggestedFix(
+        toolName: string,
+        error: string,
+        providedInput: any
+    ): string {
+        const tool = this.toolCache.get(toolName);
+        if (!tool) {
+            return 'Tool not found';
+        }
+        
+        const suggestions: string[] = [];
+        
+        // Analyze error and provide specific suggestions
+        if (error.includes('Missing required parameter')) {
+            const match = error.match(/Missing required parameter: (\w+)/);
+            if (match) {
+                const param = match[1];
+                const prop = tool.inputSchema.properties?.[param];
+                if (prop) {
+                    suggestions.push(`Add "${param}" parameter of type ${prop.type}`);
+                    if (prop.description) {
+                        suggestions.push(`Description: ${prop.description}`);
+                    }
+                    if (prop.example) {
+                        suggestions.push(`Example: "${param}": ${JSON.stringify(prop.example)}`);
+                    }
+                }
+            }
+        }
+        
+        if (error.includes('must be one of')) {
+            const match = error.match(/(\w+) must be one of: (.+)/);
+            if (match) {
+                suggestions.push(`Change "${match[1]}" to one of the allowed values: ${match[2]}`);
+            }
+        }
+        
+        if (error.includes('type')) {
+            suggestions.push('Check that all parameter types match the schema:');
+            if (tool.inputSchema.properties) {
+                for (const [key, prop] of Object.entries(tool.inputSchema.properties as Record<string, any>)) {
+                    suggestions.push(`- ${key}: ${prop.type}`);
+                }
+            }
+        }
+        
+        return suggestions.join('\n');
+    }
+}

package/src/services/MemoryCompressor.ts

@@ -0,0 +1,385 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+
+/**
+ * MemoryCompressor Service
+ *
+ * Handles memory consolidation and compression when promoting memories
+ * between strata. Integrates with ContextCompressionEngine for semantic
+ * compression and summarization.
+ *
+ * Feature flag: MEMORY_STRATA_ENABLED
+ */
+
+import { Logger } from '../utils/Logger.js';
+import {
+  MemoryEntry,
+  MemoryStratum,
+  MemoryConsolidation,
+  ConsolidationType
+} from '../types/MemoryStrataTypes.js';
+import { ContextCompressionEngine } from '../mxp/ContextCompressionEngine.js';
+
+/**
+ * Compression level for different stratum transitions
+ */
+export enum CompressionLevel {
+  None = 'none',           // No compression (Working → Working)
+  Light = 'light',         // 30% compression (Working → ShortTerm)
+  Moderate = 'moderate',   // 60% compression (ShortTerm → Episodic/LongTerm)
+  Heavy = 'heavy'          // 85% compression (Episodic → Semantic)
+}
+
+/**
+ * Compression result
+ */
+export interface CompressionResult {
+  originalContent: string;
+  compressedContent: string;
+  originalLength: number;
+  compressedLength: number;
+  compressionRatio: number;
+  method: 'semantic' | 'extractive' | 'abstractive';
+}
+
+/**
+ * Consolidation options
+ */
+export interface ConsolidationOptions {
+  maxMemories?: number;
+  similarityThreshold?: number;
+  compressionLevel?: CompressionLevel;
+  preserveMetadata?: boolean;
+}
+
+/**
+ * MemoryCompressor handles memory compression and consolidation
+ */
+export class MemoryCompressor {
+  private static instance: MemoryCompressor;
+  private logger: Logger;
+  private contextCompressor: ContextCompressionEngine | null = null;
+  private enabled: boolean = false;
+
+  // Compression ratios per level
+  private readonly compressionRatios: Record<CompressionLevel, number> = {
+    [CompressionLevel.None]: 1.0,
+    [CompressionLevel.Light]: 0.7,
+    [CompressionLevel.Moderate]: 0.4,
+    [CompressionLevel.Heavy]: 0.15
+  };
+
+  private constructor() {
+    this.logger = new Logger('info', 'MemoryCompressor');
+  }
+
+  public static getInstance(): MemoryCompressor {
+    if (!MemoryCompressor.instance) {
+      MemoryCompressor.instance = new MemoryCompressor();
+    }
+    return MemoryCompressor.instance;
+  }
+
+  /**
+   * Initialize the MemoryCompressor
+   */
+  public initialize(config: { enabled: boolean }): void {
+    this.enabled = config.enabled;
+
+    if (this.enabled) {
+      this.contextCompressor = ContextCompressionEngine.getInstance();
+      this.logger.info('[MemoryCompressor] Initialized with semantic compression support');
+    }
+  }
+
+  /**
+   * Check if compression is enabled
+   */
+  public isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  /**
+   * Compress a memory entry for promotion to a slower stratum
+   */
+  public async compressMemory(
+    memory: MemoryEntry,
+    targetStratum: MemoryStratum
+  ): Promise<MemoryEntry> {
+    if (!this.enabled) return memory;
+
+    const compressionLevel = this.getCompressionLevel(memory.stratum, targetStratum);
+
+    if (compressionLevel === CompressionLevel.None) {
+      return memory;
+    }
+
+    const result = await this.compressContent(memory.content, compressionLevel);
+
+    const compressedMemory: MemoryEntry = {
+      ...memory,
+      content: result.compressedContent,
+      metadata: {
+        ...memory.metadata,
+        originalLength: result.originalLength,
+        compressionRatio: result.compressionRatio,
+        compressionMethod: result.method,
+        compressedAt: new Date().toISOString()
+      }
+    };
+
+    this.logger.debug(
+      `[MemoryCompressor] Compressed memory ${memory.id} for ${targetStratum} stratum ` +
+      `(${result.originalLength} → ${result.compressedLength} chars, ${(result.compressionRatio * 100).toFixed(1)}%)`
+    );
+
+    return compressedMemory;
+  }
+
+  /**
+   * Consolidate multiple memories into a single memory
+   */
+  public async consolidateMemories(
+    memories: MemoryEntry[],
+    type: ConsolidationType,
+    options: ConsolidationOptions = {}
+  ): Promise<MemoryConsolidation> {
+    if (!this.enabled || memories.length === 0) {
+      throw new Error('Cannot consolidate: compression disabled or no memories provided');
+    }
+
+    let consolidatedContent: string;
+    let reason: string;
+
+    switch (type) {
+      case 'merge':
+        consolidatedContent = await this.mergeMemories(memories);
+        reason = `Merged ${memories.length} similar memories`;
+        break;
+
+      case 'summarize':
+        consolidatedContent = await this.summarizeMemories(memories);
+        reason = `Summarized ${memories.length} memories`;
+        break;
+
+      case 'abstract':
+        consolidatedContent = await this.abstractPattern(memories);
+        reason = `Abstracted common pattern from ${memories.length} memories`;
+        break;
+
+      default:
+        throw new Error(`Unsupported consolidation type: ${type}`);
+    }
+
+    // Create new consolidated memory
+    const baseMemory = memories[0];
+    const newMemory: MemoryEntry = {
+      ...baseMemory,
+      id: `consolidated-${Date.now()}`,
+      content: consolidatedContent,
+      importance: Math.max(...memories.map(m => m.importance)),
+      tags: Array.from(new Set(memories.flatMap(m => m.tags))),
+      relatedMemories: memories.map(m => m.id),
+      accessCount: memories.reduce((sum, m) => sum + m.accessCount, 0),
+      createdAt: new Date(),
+      lastAccessed: new Date(),
+      metadata: {
+        consolidationType: type,
+        sourceMemoryCount: memories.length,
+        consolidatedAt: new Date().toISOString()
+      }
+    };
+
+    this.logger.info(
+      `[MemoryCompressor] Consolidated ${memories.length} memories via ${type}: ${newMemory.id}`
+    );
+
+    return {
+      consolidatedMemories: memories.map(m => m.id),
+      newMemory,
+      type,
+      reason
+    };
+  }
+
+  /**
+   * Determine if memories are similar enough to consolidate
+   */
+  public async areSimilar(
+    memory1: MemoryEntry,
+    memory2: MemoryEntry,
+    threshold: number = 0.7
+  ): Promise<boolean> {
+    const similarity = this.calculateSimilarity(memory1, memory2);
+    return similarity >= threshold;
+  }
+
+  // Private helper methods
+
+  private getCompressionLevel(
+    fromStratum: MemoryStratum,
+    toStratum: MemoryStratum
+  ): CompressionLevel {
+    // Define compression levels for stratum transitions
+    const transitions: Record<string, CompressionLevel> = {
+      [`${MemoryStratum.Working}-${MemoryStratum.ShortTerm}`]: CompressionLevel.Light,
+      [`${MemoryStratum.ShortTerm}-${MemoryStratum.Episodic}`]: CompressionLevel.Moderate,
+      [`${MemoryStratum.ShortTerm}-${MemoryStratum.LongTerm}`]: CompressionLevel.Moderate,
+      [`${MemoryStratum.Episodic}-${MemoryStratum.Semantic}`]: CompressionLevel.Heavy,
+      [`${MemoryStratum.LongTerm}-${MemoryStratum.Semantic}`]: CompressionLevel.Heavy
+    };
+
+    const key = `${fromStratum}-${toStratum}`;
+    return transitions[key] || CompressionLevel.None;
+  }
+
+  private async compressContent(
+    content: string,
+    level: CompressionLevel
+  ): Promise<CompressionResult> {
+    const originalLength = content.length;
+    const targetRatio = this.compressionRatios[level];
+
+    let compressedContent: string;
+    let method: 'semantic' | 'extractive' | 'abstractive';
+
+    if (this.contextCompressor && level !== CompressionLevel.Light) {
+      // Use semantic compression for moderate/heavy compression
+      compressedContent = await this.semanticCompress(content, targetRatio);
+      method = 'semantic';
+    } else {
+      // Use extractive compression for light compression
+      compressedContent = this.extractiveCompress(content, targetRatio);
+      method = 'extractive';
+    }
+
+    const compressedLength = compressedContent.length;
+    const actualRatio = compressedLength / originalLength;
+
+    return {
+      originalContent: content,
+      compressedContent,
+      originalLength,
+      compressedLength,
+      compressionRatio: actualRatio,
+      method
+    };
+  }
+
+  private async semanticCompress(content: string, targetRatio: number): Promise<string> {
+    // Use ContextCompressionEngine for semantic compression
+    const targetLength = Math.ceil(content.length * targetRatio);
+
+    // Simple summarization approach
+    const words = content.split(/\s+/);
+    const targetWords = Math.ceil(words.length * targetRatio);
+
+    if (words.length <= targetWords) {
+      return content;
+    }
+
+    // Extract key sentences (simple extractive approach)
+    const sentences = content.split(/[.!?]+/).filter(s => s.trim());
+    const targetSentences = Math.max(1, Math.ceil(sentences.length * targetRatio));
+
+    return sentences.slice(0, targetSentences).join('. ') + '.';
+  }
+
+  private extractiveCompress(content: string, targetRatio: number): string {
+    // Simple extractive compression: keep first N% of content
+    const targetLength = Math.ceil(content.length * targetRatio);
+
+    if (content.length <= targetLength) {
+      return content;
+    }
+
+    // Split on sentences and keep complete sentences up to target
+    const sentences = content.split(/[.!?]+/).filter(s => s.trim());
+    let compressed = '';
+
+    for (const sentence of sentences) {
+      const candidate = compressed + sentence + '. ';
+      if (candidate.length > targetLength) break;
+      compressed = candidate;
+    }
+
+    return compressed.trim() || content.substring(0, targetLength) + '...';
+  }
+
+  private async mergeMemories(memories: MemoryEntry[]): Promise<string> {
+    // Combine content with deduplication
+    const contents = memories.map(m => m.content);
+    const uniqueContents = Array.from(new Set(contents));
+    return uniqueContents.join('\n\n');
+  }
+
+  private async summarizeMemories(memories: MemoryEntry[]): Promise<string> {
+    // Create a summary of key points
+    const contents = memories.map(m => m.content).join('\n\n');
+
+    // Apply moderate compression
+    const result = await this.compressContent(contents, CompressionLevel.Moderate);
+    return result.compressedContent;
+  }
+
+  private async abstractPattern(memories: MemoryEntry[]): Promise<string> {
+    // Extract common patterns
+    const allWords = memories.flatMap(m =>
+      m.content.toLowerCase().split(/\s+/)
+    );
+
+    // Count word frequencies
+    const wordCounts = new Map<string, number>();
+    for (const word of allWords) {
+      wordCounts.set(word, (wordCounts.get(word) || 0) + 1);
+    }
+
+    // Filter common words (stop words)
+    const stopWords = new Set(['the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for']);
+    const keywords = Array.from(wordCounts.entries())
+      .filter(([word, count]) => !stopWords.has(word) && count > 1)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 10)
+      .map(([word]) => word);
+
+    return `Common pattern detected across ${memories.length} memories. Key concepts: ${keywords.join(', ')}`;
+  }
+
+  private calculateSimilarity(memory1: MemoryEntry, memory2: MemoryEntry): number {
+    // Calculate Jaccard similarity based on content words
+    const words1 = new Set(memory1.content.toLowerCase().split(/\s+/));
+    const words2 = new Set(memory2.content.toLowerCase().split(/\s+/));
+
+    const intersection = new Set([...words1].filter(w => words2.has(w)));
+    const union = new Set([...words1, ...words2]);
+
+    const contentSimilarity = union.size > 0 ? intersection.size / union.size : 0;
+
+    // Factor in tag similarity
+    const tags1 = new Set(memory1.tags);
+    const tags2 = new Set(memory2.tags);
+    const tagIntersection = new Set([...tags1].filter(t => tags2.has(t)));
+    const tagUnion = new Set([...tags1, ...tags2]);
+    const tagSimilarity = tagUnion.size > 0 ? tagIntersection.size / tagUnion.size : 0;
+
+    // Weighted combination
+    return contentSimilarity * 0.8 + tagSimilarity * 0.2;
+  }
+}