@girardmedia/bootspring 2.0.37 → 2.0.38

package/intelligence/model-context-optimizer.js

@@ -0,0 +1,704 @@
+/**
+ * Bootspring Model Context Optimizer
+ *
+ * Optimizes AI context for different LLM models (Claude, GPT, Gemini, etc.)
+ * Handles token limits, formatting preferences, and context prioritization.
+ *
+ * @package bootspring
+ * @module intelligence/model-context-optimizer
+ */
+
+const path = require('path');
+
+/**
+ * Model configurations with token limits and formatting preferences
+ */
+const MODEL_CONFIGS = {
+  claude: {
+    name: 'Claude',
+    provider: 'Anthropic',
+    variants: {
+      'claude-opus-4': { contextWindow: 200000, outputLimit: 32000 },
+      'claude-sonnet-4': { contextWindow: 200000, outputLimit: 64000 },
+      'claude-3.5-sonnet': { contextWindow: 200000, outputLimit: 8192 },
+      'claude-3-opus': { contextWindow: 200000, outputLimit: 4096 },
+      'claude-3-sonnet': { contextWindow: 200000, outputLimit: 4096 },
+      'claude-3-haiku': { contextWindow: 200000, outputLimit: 4096 }
+    },
+    defaultVariant: 'claude-sonnet-4',
+    contextFile: 'CLAUDE.md',
+    formatting: {
+      preferMarkdown: true,
+      xmlTags: true,
+      headingStyle: 'atx',
+      codeBlocks: 'fenced',
+      listStyle: 'dash',
+      tableSupport: true
+    },
+    features: {
+      toolUse: true,
+      vision: true,
+      systemPrompt: true,
+      streaming: true,
+      artifacts: true
+    }
+  },
+  openai: {
+    name: 'GPT',
+    provider: 'OpenAI',
+    variants: {
+      'gpt-4o': { contextWindow: 128000, outputLimit: 16384 },
+      'gpt-4-turbo': { contextWindow: 128000, outputLimit: 4096 },
+      'gpt-4': { contextWindow: 8192, outputLimit: 4096 },
+      'gpt-3.5-turbo': { contextWindow: 16385, outputLimit: 4096 },
+      'o1': { contextWindow: 200000, outputLimit: 100000 },
+      'o1-mini': { contextWindow: 128000, outputLimit: 65536 }
+    },
+    defaultVariant: 'gpt-4o',
+    contextFile: 'OPENAI.md',
+    formatting: {
+      preferMarkdown: true,
+      xmlTags: false,
+      headingStyle: 'atx',
+      codeBlocks: 'fenced',
+      listStyle: 'dash',
+      tableSupport: true
+    },
+    features: {
+      toolUse: true,
+      vision: true,
+      systemPrompt: true,
+      streaming: true,
+      jsonMode: true
+    }
+  },
+  gemini: {
+    name: 'Gemini',
+    provider: 'Google',
+    variants: {
+      'gemini-2.0-flash': { contextWindow: 1000000, outputLimit: 8192 },
+      'gemini-1.5-pro': { contextWindow: 2000000, outputLimit: 8192 },
+      'gemini-1.5-flash': { contextWindow: 1000000, outputLimit: 8192 },
+      'gemini-1.0-pro': { contextWindow: 32760, outputLimit: 8192 }
+    },
+    defaultVariant: 'gemini-1.5-pro',
+    contextFile: 'GEMINI.md',
+    formatting: {
+      preferMarkdown: true,
+      xmlTags: false,
+      headingStyle: 'atx',
+      codeBlocks: 'fenced',
+      listStyle: 'dash',
+      tableSupport: true
+    },
+    features: {
+      toolUse: true,
+      vision: true,
+      systemPrompt: true,
+      streaming: true,
+      multimodal: true
+    }
+  },
+  mistral: {
+    name: 'Mistral',
+    provider: 'Mistral AI',
+    variants: {
+      'mistral-large': { contextWindow: 128000, outputLimit: 8192 },
+      'mistral-medium': { contextWindow: 32000, outputLimit: 8192 },
+      'mistral-small': { contextWindow: 32000, outputLimit: 8192 },
+      'codestral': { contextWindow: 32000, outputLimit: 8192 }
+    },
+    defaultVariant: 'mistral-large',
+    contextFile: 'MISTRAL.md',
+    formatting: {
+      preferMarkdown: true,
+      xmlTags: false,
+      headingStyle: 'atx',
+      codeBlocks: 'fenced',
+      listStyle: 'dash',
+      tableSupport: true
+    },
+    features: {
+      toolUse: true,
+      vision: false,
+      systemPrompt: true,
+      streaming: true,
+      codeSpecialized: true
+    }
+  },
+  llama: {
+    name: 'Llama',
+    provider: 'Meta',
+    variants: {
+      'llama-3.3-70b': { contextWindow: 128000, outputLimit: 8192 },
+      'llama-3.2-90b': { contextWindow: 128000, outputLimit: 8192 },
+      'llama-3.1-405b': { contextWindow: 128000, outputLimit: 8192 },
+      'llama-3.1-70b': { contextWindow: 128000, outputLimit: 8192 }
+    },
+    defaultVariant: 'llama-3.3-70b',
+    contextFile: 'LLAMA.md',
+    formatting: {
+      preferMarkdown: true,
+      xmlTags: false,
+      headingStyle: 'atx',
+      codeBlocks: 'fenced',
+      listStyle: 'dash',
+      tableSupport: true
+    },
+    features: {
+      toolUse: true,
+      vision: true,
+      systemPrompt: true,
+      streaming: true,
+      openWeight: true
+    }
+  }
+};
+
+/**
+ * Context section priorities (higher = more important)
+ */
+const SECTION_PRIORITIES = {
+  critical: 100,      // Must always include (project name, tech stack)
+  high: 80,           // Important for most tasks (commands, guidelines)
+  medium: 60,         // Useful context (plugins, structure)
+  low: 40,            // Nice to have (learnings, state)
+  optional: 20        // Can be dropped first (verbose explanations)
+};
+
+/**
+ * Default section classifications
+ */
+const SECTION_CLASSIFICATIONS = {
+  'Project Overview': SECTION_PRIORITIES.critical,
+  'Tech Stack': SECTION_PRIORITIES.critical,
+  'Development Guidelines': SECTION_PRIORITIES.high,
+  'Bootspring Commands': SECTION_PRIORITIES.high,
+  'Custom Instructions': SECTION_PRIORITIES.high,
+  'Enabled Plugins': SECTION_PRIORITIES.medium,
+  'Project Structure': SECTION_PRIORITIES.medium,
+  'Current State': SECTION_PRIORITIES.medium,
+  'Git Repository': SECTION_PRIORITIES.low,
+  'Recent Learnings': SECTION_PRIORITIES.low,
+  'Generated': SECTION_PRIORITIES.optional
+};
+
+/**
+ * Token estimation ratios (characters per token, approximate)
+ */
+const TOKEN_RATIOS = {
+  english: 4.0,       // Average English text
+  code: 3.5,          // Source code
+  markdown: 3.8,      // Markdown formatted text
+  json: 4.5           // JSON data
+};
+
+/**
+ * Model Context Optimizer
+ * Optimizes AI context for different LLM models
+ */
+class ModelContextOptimizer {
+  /**
+   * Create a new ModelContextOptimizer
+   * @param {object} options - Configuration options
+   * @param {string} options.projectRoot - Project root directory
+   * @param {string} options.model - Model family (claude, openai, gemini, etc.)
+   * @param {string} options.variant - Specific model variant
+   * @param {number} options.reserveTokens - Tokens to reserve for output
+   */
+  constructor(options = {}) {
+    this.projectRoot = options.projectRoot || process.cwd();
+    this.modelFamily = options.model || 'claude';
+    this.variant = options.variant || null;
+    this.reserveTokens = options.reserveTokens || 8000;
+    this.customSectionPriorities = options.sectionPriorities || {};
+
+    // Validate model family
+    if (!MODEL_CONFIGS[this.modelFamily]) {
+      throw new Error(`Unknown model family: ${this.modelFamily}`);
+    }
+
+    this.config = MODEL_CONFIGS[this.modelFamily];
+
+    // Set variant (use default if not specified)
+    if (!this.variant) {
+      this.variant = this.config.defaultVariant;
+    }
+
+    // Validate variant
+    if (!this.config.variants[this.variant]) {
+      throw new Error(`Unknown variant ${this.variant} for model ${this.modelFamily}`);
+    }
+
+    this.variantConfig = this.config.variants[this.variant];
+  }
+
+  /**
+   * Get available context budget in tokens
+   * @returns {number} Available tokens for context
+   */
+  getContextBudget() {
+    return this.variantConfig.contextWindow - this.reserveTokens;
+  }
+
+  /**
+   * Estimate token count for text
+   * @param {string} text - Text to estimate
+   * @param {string} contentType - Type of content (english, code, markdown, json)
+   * @returns {number} Estimated token count
+   */
+  estimateTokens(text, contentType = 'markdown') {
+    if (!text) return 0;
+    const ratio = TOKEN_RATIOS[contentType] || TOKEN_RATIOS.english;
+    return Math.ceil(text.length / ratio);
+  }
+
+  /**
+   * Parse context document into sections
+   * @param {string} content - Markdown content to parse
+   * @returns {Array<object>} Parsed sections with metadata
+   */
+  parseSections(content) {
+    const sections = [];
+    const lines = content.split('\n');
+
+    let currentSection = null;
+    let currentContent = [];
+
+    for (const line of lines) {
+      // Check for heading
+      const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+
+      if (headingMatch) {
+        // Save previous section
+        if (currentSection) {
+          currentSection.content = currentContent.join('\n').trim();
+          currentSection.tokens = this.estimateTokens(currentSection.content);
+          sections.push(currentSection);
+        }
+
+        // Start new section
+        const level = headingMatch[1].length;
+        const title = headingMatch[2].trim();
+
+        currentSection = {
+          level,
+          title,
+          priority: this.getSectionPriority(title),
+          content: '',
+          tokens: 0,
+          line: lines.indexOf(line)
+        };
+        currentContent = [line];
+      } else if (currentSection) {
+        currentContent.push(line);
+      } else {
+        // Content before first heading (preamble)
+        if (line.trim()) {
+          currentSection = {
+            level: 0,
+            title: '_preamble',
+            priority: SECTION_PRIORITIES.critical,
+            content: '',
+            tokens: 0,
+            line: 0
+          };
+          currentContent = [line];
+        }
+      }
+    }
+
+    // Save last section
+    if (currentSection) {
+      currentSection.content = currentContent.join('\n').trim();
+      currentSection.tokens = this.estimateTokens(currentSection.content);
+      sections.push(currentSection);
+    }
+
+    return sections;
+  }
+
+  /**
+   * Get priority for a section based on title
+   * @param {string} title - Section title
+   * @returns {number} Priority value
+   */
+  getSectionPriority(title) {
+    // Check custom priorities first
+    if (this.customSectionPriorities[title]) {
+      return this.customSectionPriorities[title];
+    }
+
+    // Check default classifications
+    for (const [pattern, priority] of Object.entries(SECTION_CLASSIFICATIONS)) {
+      if (title.toLowerCase().includes(pattern.toLowerCase())) {
+        return priority;
+      }
+    }
+
+    return SECTION_PRIORITIES.medium;
+  }
+
+  /**
+   * Optimize context to fit within token budget
+   * @param {string} content - Original context content
+   * @param {object} options - Optimization options
+   * @returns {object} Optimized context with metadata
+   */
+  optimize(content, options = {}) {
+    const budget = options.budget || this.getContextBudget();
+    const preserveCritical = options.preserveCritical !== false;
+
+    const sections = this.parseSections(content);
+    const totalTokens = sections.reduce((sum, s) => sum + s.tokens, 0);
+
+    // If we're under budget, no optimization needed
+    if (totalTokens <= budget) {
+      return {
+        content,
+        originalTokens: totalTokens,
+        optimizedTokens: totalTokens,
+        sectionsIncluded: sections.length,
+        sectionsDropped: 0,
+        droppedSections: [],
+        withinBudget: true
+      };
+    }
+
+    // Sort sections by priority (descending)
+    const sortedSections = [...sections].sort((a, b) => b.priority - a.priority);
+
+    // Select sections that fit within budget
+    const includedSections = [];
+    const droppedSections = [];
+    let usedTokens = 0;
+
+    for (const section of sortedSections) {
+      // Critical sections are always included if preserveCritical is true
+      const isCritical = section.priority === SECTION_PRIORITIES.critical;
+
+      if (isCritical && preserveCritical) {
+        includedSections.push(section);
+        usedTokens += section.tokens;
+      } else if (usedTokens + section.tokens <= budget) {
+        includedSections.push(section);
+        usedTokens += section.tokens;
+      } else {
+        droppedSections.push(section);
+      }
+    }
+
+    // Re-sort by original line order to maintain document flow
+    includedSections.sort((a, b) => a.line - b.line);
+
+    // Reconstruct content
+    const optimizedContent = includedSections
+      .map(s => s.content)
+      .join('\n\n');
+
+    return {
+      content: optimizedContent,
+      originalTokens: totalTokens,
+      optimizedTokens: usedTokens,
+      sectionsIncluded: includedSections.length,
+      sectionsDropped: droppedSections.length,
+      droppedSections: droppedSections.map(s => ({
+        title: s.title,
+        tokens: s.tokens,
+        priority: s.priority
+      })),
+      withinBudget: usedTokens <= budget
+    };
+  }
+
+  /**
+   * Format context for specific model
+   * @param {string} content - Context content
+   * @returns {string} Formatted content
+   */
+  formatForModel(content) {
+    const formatting = this.config.formatting;
+    let formatted = content;
+
+    // Apply XML tags for Claude
+    if (formatting.xmlTags && this.modelFamily === 'claude') {
+      formatted = this.wrapWithXmlTags(formatted);
+    }
+
+    // Normalize list style
+    if (formatting.listStyle === 'dash') {
+      formatted = formatted.replace(/^\*\s+/gm, '- ');
+    } else if (formatting.listStyle === 'asterisk') {
+      formatted = formatted.replace(/^-\s+/gm, '* ');
+    }
+
+    return formatted;
+  }
+
+  /**
+   * Wrap content sections with XML tags (Claude preference)
+   * @param {string} content - Content to wrap
+   * @returns {string} Wrapped content
+   */
+  wrapWithXmlTags(content) {
+    const sections = this.parseSections(content);
+    const wrapped = [];
+
+    for (const section of sections) {
+      if (section.title === '_preamble') {
+        wrapped.push(section.content);
+      } else {
+        const tagName = section.title
+          .toLowerCase()
+          .replace(/[^a-z0-9]+/g, '-')
+          .replace(/^-|-$/g, '');
+
+        wrapped.push(`<${tagName}>\n${section.content}\n</${tagName}>`);
+      }
+    }
+
+    return wrapped.join('\n\n');
+  }
+
+  /**
+   * Generate optimized context file for the model
+   * @param {string} sourceContent - Source context content
+   * @param {object} options - Generation options
+   * @returns {object} Generated context with file info
+   */
+  generateContextFile(sourceContent, options = {}) {
+    // Optimize content
+    const optimized = this.optimize(sourceContent, options);
+
+    // Format for model
+    const formatted = this.formatForModel(optimized.content);
+
+    // Add model-specific header
+    const header = this.generateHeader();
+    const finalContent = `${header}\n\n${formatted}`;
+
+    return {
+      filename: this.config.contextFile,
+      filepath: path.join(this.projectRoot, this.config.contextFile),
+      content: finalContent,
+      model: this.modelFamily,
+      variant: this.variant,
+      optimization: {
+        originalTokens: optimized.originalTokens,
+        optimizedTokens: this.estimateTokens(finalContent),
+        sectionsIncluded: optimized.sectionsIncluded,
+        sectionsDropped: optimized.sectionsDropped,
+        droppedSections: optimized.droppedSections
+      },
+      formatting: this.config.formatting,
+      features: this.config.features
+    };
+  }
+
+  /**
+   * Generate model-specific header
+   * @returns {string} Header content
+   */
+  generateHeader() {
+    const lines = [
+      `# AI Context - ${this.config.name}`,
+      '',
+      `**Optimized for**: ${this.config.name} (${this.variant})`,
+      `**Provider**: ${this.config.provider}`,
+      `**Context Window**: ${this.variantConfig.contextWindow.toLocaleString()} tokens`,
+      `**Generated**: ${new Date().toISOString()}`
+    ];
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Get model capabilities and recommendations
+   * @returns {object} Model capabilities and recommendations
+   */
+  getModelCapabilities() {
+    return {
+      model: this.modelFamily,
+      variant: this.variant,
+      provider: this.config.provider,
+      contextWindow: this.variantConfig.contextWindow,
+      outputLimit: this.variantConfig.outputLimit,
+      availableBudget: this.getContextBudget(),
+      features: this.config.features,
+      formatting: this.config.formatting,
+      recommendations: this.generateRecommendations()
+    };
+  }
+
+  /**
+   * Generate model-specific recommendations
+   * @returns {Array<string>} Recommendations
+   */
+  generateRecommendations() {
+    const recommendations = [];
+    const features = this.config.features;
+
+    // Tool use recommendations
+    if (features.toolUse) {
+      recommendations.push('Model supports function/tool calling - consider using structured commands');
+    }
+
+    // Vision recommendations
+    if (features.vision) {
+      recommendations.push('Model supports image analysis - can include diagrams or screenshots');
+    }
+
+    // Context window recommendations
+    if (this.variantConfig.contextWindow >= 100000) {
+      recommendations.push('Large context window available - include comprehensive documentation');
+    } else if (this.variantConfig.contextWindow < 32000) {
+      recommendations.push('Limited context window - prioritize essential information only');
+    }
+
+    // Model-specific recommendations
+    if (this.modelFamily === 'claude') {
+      recommendations.push('Claude excels with XML tags for structured sections');
+      recommendations.push('Use <example> tags for code patterns');
+    } else if (this.modelFamily === 'openai') {
+      recommendations.push('Consider using JSON mode for structured outputs');
+    } else if (this.modelFamily === 'gemini') {
+      recommendations.push('Very large context - can include full codebase context');
+    } else if (this.modelFamily === 'mistral') {
+      if (this.variant === 'codestral') {
+        recommendations.push('Codestral specialized for code - include more code examples');
+      }
+    }
+
+    return recommendations;
+  }
+
+  /**
+   * Compare context requirements across models
+   * @param {string} content - Context content to compare
+   * @returns {Array<object>} Comparison results for all models
+   */
+  compareAcrossModels(content) {
+    const results = [];
+    const originalTokens = this.estimateTokens(content);
+
+    for (const [family, config] of Object.entries(MODEL_CONFIGS)) {
+      const optimizer = new ModelContextOptimizer({
+        projectRoot: this.projectRoot,
+        model: family
+      });
+
+      const budget = optimizer.getContextBudget();
+      const fitsWithinBudget = originalTokens <= budget;
+
+      results.push({
+        model: family,
+        variant: config.defaultVariant,
+        provider: config.provider,
+        contextWindow: optimizer.variantConfig.contextWindow,
+        availableBudget: budget,
+        contentTokens: originalTokens,
+        fitsWithinBudget,
+        utilizationPercent: Math.round((originalTokens / budget) * 100),
+        contextFile: config.contextFile
+      });
+    }
+
+    // Sort by context window size (descending)
+    return results.sort((a, b) => b.contextWindow - a.contextWindow);
+  }
+
+  /**
+   * Generate multi-model context files
+   * @param {string} sourceContent - Source context content
+   * @param {Array<string>} models - Models to generate for
+   * @returns {Array<object>} Generated context files
+   */
+  generateMultiModelContexts(sourceContent, models = null) {
+    const targetModels = models || Object.keys(MODEL_CONFIGS);
+    const results = [];
+
+    for (const model of targetModels) {
+      try {
+        const optimizer = new ModelContextOptimizer({
+          projectRoot: this.projectRoot,
+          model
+        });
+
+        const context = optimizer.generateContextFile(sourceContent);
+        results.push({
+          ...context,
+          status: 'success'
+        });
+      } catch (error) {
+        results.push({
+          model,
+          status: 'error',
+          error: error.message
+        });
+      }
+    }
+
+    return results;
+  }
+}
+
+/**
+ * Get list of supported models
+ * @returns {Array<object>} List of supported models
+ */
+function listSupportedModels() {
+  const models = [];
+
+  for (const [family, config] of Object.entries(MODEL_CONFIGS)) {
+    models.push({
+      family,
+      name: config.name,
+      provider: config.provider,
+      variants: Object.keys(config.variants),
+      defaultVariant: config.defaultVariant,
+      contextFile: config.contextFile,
+      features: config.features
+    });
+  }
+
+  return models;
+}
+
+/**
+ * Get model configuration
+ * @param {string} family - Model family
+ * @param {string} variant - Model variant (optional)
+ * @returns {object} Model configuration
+ */
+function getModelConfig(family, variant = null) {
+  const config = MODEL_CONFIGS[family];
+  if (!config) {
+    return null;
+  }
+
+  const variantConfig = variant
+    ? config.variants[variant]
+    : config.variants[config.defaultVariant];
+
+  return {
+    family,
+    name: config.name,
+    provider: config.provider,
+    variant: variant || config.defaultVariant,
+    contextWindow: variantConfig.contextWindow,
+    outputLimit: variantConfig.outputLimit,
+    contextFile: config.contextFile,
+    formatting: config.formatting,
+    features: config.features
+  };
+}
+
+module.exports = {
+  ModelContextOptimizer,
+  listSupportedModels,
+  getModelConfig,
+  MODEL_CONFIGS,
+  SECTION_PRIORITIES,
+  SECTION_CLASSIFICATIONS,
+  TOKEN_RATIOS
+};

package/mcp/contracts/mcp-contract.v1.json

@@ -1,7 +1,7 @@
 {
   "contractVersion": "v1",
   "packageName": "@girardmedia/bootspring",
-  "packageVersion": "2.0.37",
+  "packageVersion": "2.0.38",
   "tools": [
     {
       "name": "bootspring_assist",