hummbl-bibliography 1.0.0

package/toolkit/src/stats.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+import { Cite } from '@citation-js/core';
+import '@citation-js/plugin-bibtex';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const args = process.argv.slice(2);
+const bibDir = args[0] || '../bibliography';
+const jsonOutput = args.includes('--json');
+
+class BibStats {
+  constructor(bibDir) {
+    this.bibDir = path.resolve(bibDir);
+    this.stats = {
+      total: 0,
+      byTier: {},
+      byType: {},
+      transformations: { P: 0, IN: 0, CO: 0, DE: 0, RE: 0, SY: 0 },
+      quality: {
+        withDOI: 0,
+        withISBN: 0,
+        withAbstract: 0,
+        withKeywords: 0
+      }
+    };
+  }
+
+  parseBibTeXRaw(content) {
+    const rawEntries = {};
+    const entryRegex = /@\w+\{([^,]+),([^@]+?)(?=\n\})/gs;
+    let match;
+    
+    while ((match = entryRegex.exec(content)) !== null) {
+      const key = match[1].trim();
+      const entryText = match[2];
+      const fields = {};
+      
+      const lines = entryText.split('\n');
+      for (const line of lines) {
+        const fieldMatch = line.match(/^\s*(\w+)\s*=\s*\{(.+)\}\s*,?\s*$/);
+        if (fieldMatch) {
+          const [, fieldKey, value] = fieldMatch;
+          fields[fieldKey.toLowerCase()] = value.trim();
+        }
+      }
+      
+      rawEntries[key] = fields;
+    }
+    
+    return rawEntries;
+  }
+
+  extractTransformations(keywords) {
+    const transformations = new Set();
+    if (!keywords) return transformations;
+
+    const keywordStr = Array.isArray(keywords) ? keywords.join(', ') : keywords;
+    const matches = keywordStr.match(/HUMMBL:(P|IN|CO|DE|RE|SY)/g);
+
+    if (matches) {
+      matches.forEach(match => {
+        const trans = match.replace('HUMMBL:', '');
+        transformations.add(trans);
+      });
+    }
+
+    return transformations;
+  }
+
+  getTier(filename) {
+    const match = filename.match(/T(\d+)/);
+    if (match) return `T${match[1]}`;
+    return 'Unknown';
+  }
+
+  processEntry(entry, filename, rawEntry = {}) {
+    this.stats.total++;
+
+    // Count by tier
+    const tier = this.getTier(filename);
+    this.stats.byTier[tier] = (this.stats.byTier[tier] || 0) + 1;
+
+    // Count by type
+    const type = entry.type || 'unknown';
+    this.stats.byType[type] = (this.stats.byType[type] || 0) + 1;
+
+    // Count transformations from raw keywords
+    const keywords = rawEntry.keywords || '';
+    const transformations = this.extractTransformations(keywords);
+    transformations.forEach(trans => {
+      this.stats.transformations[trans]++;
+    });
+
+    // Quality metrics
+    if (entry.DOI) this.stats.quality.withDOI++;
+    if (entry.ISBN) this.stats.quality.withISBN++;
+    
+    const abstract = rawEntry.abstract || '';
+    if (abstract && abstract.length >= 50) this.stats.quality.withAbstract++;
+    if (transformations.size > 0) this.stats.quality.withKeywords++;
+  }
+
+  async loadFile(filepath) {
+    const filename = path.basename(filepath);
+
+    try {
+      const content = fs.readFileSync(filepath, 'utf8');
+      const citation = new Cite(content, { forceType: '@bibtex/text' });
+      const entries = citation.data;
+
+      // Parse raw BibTeX for additional fields
+      const rawEntries = this.parseBibTeXRaw(content);
+
+      entries.forEach(entry => {
+        const rawEntry = rawEntries[entry.id] || {};
+        this.processEntry(entry, filename, rawEntry);
+      });
+
+      return entries.length;
+    } catch (err) {
+      if (!jsonOutput) {
+        console.error(chalk.red(`Error loading ${filename}: ${err.message}`));
+      }
+      return 0;
+    }
+  }
+
+  printReport() {
+    console.log('\n' + '='.repeat(60));
+    console.log(chalk.cyan.bold('  HUMMBL BIBLIOGRAPHY STATISTICS'));
+    console.log('='.repeat(60));
+
+    // Total entries
+    console.log(chalk.cyan('\n📊 OVERVIEW'));
+    console.log(chalk.white(`Total Entries: ${chalk.bold(this.stats.total)}`));
+
+    // By tier
+    console.log(chalk.cyan('\n📚 BY TIER'));
+    Object.entries(this.stats.byTier).forEach(([tier, count]) => {
+      const percentage = ((count / this.stats.total) * 100).toFixed(1);
+      const bar = '█'.repeat(Math.floor(count / 2));
+      console.log(chalk.white(`  ${tier}: ${chalk.bold(count.toString().padStart(2))} (${percentage}%) ${chalk.blue(bar)}`));
+    });
+
+    // By type
+    console.log(chalk.cyan('\n📖 BY TYPE'));
+    Object.entries(this.stats.byType)
+      .sort((a, b) => b[1] - a[1])
+      .forEach(([type, count]) => {
+        const percentage = ((count / this.stats.total) * 100).toFixed(1);
+        console.log(chalk.white(`  ${type.padEnd(15)}: ${chalk.bold(count.toString().padStart(2))} (${percentage}%)`));
+      });
+
+    // Transformations
+    console.log(chalk.cyan('\n🔄 HUMMBL TRANSFORMATIONS'));
+    const transNames = {
+      P: 'Perspective',
+      IN: 'Inversion',
+      CO: 'Composition',
+      DE: 'Decomposition',
+      RE: 'Recursion',
+      SY: 'Synthesis'
+    };
+
+    Object.entries(this.stats.transformations)
+      .sort((a, b) => b[1] - a[1])
+      .forEach(([trans, count]) => {
+        const bar = '█'.repeat(Math.floor(count / 2));
+        console.log(chalk.white(`  ${trans.padEnd(2)} (${transNames[trans].padEnd(13)}): ${chalk.bold(count.toString().padStart(2))} ${chalk.green(bar)}`));
+      });
+
+    // Quality metrics
+    console.log(chalk.cyan('\n✨ QUALITY METRICS'));
+    const qualityMetrics = [
+      { label: 'Entries with DOI', count: this.stats.quality.withDOI },
+      { label: 'Entries with ISBN', count: this.stats.quality.withISBN },
+      { label: 'Entries with Abstract', count: this.stats.quality.withAbstract },
+      { label: 'Entries with HUMMBL Keywords', count: this.stats.quality.withKeywords }
+    ];
+
+    qualityMetrics.forEach(metric => {
+      const percentage = ((metric.count / this.stats.total) * 100).toFixed(1);
+      const color = percentage >= 80 ? 'green' : percentage >= 50 ? 'yellow' : 'red';
+      console.log(chalk.white(`  ${metric.label.padEnd(30)}: ${chalk.bold(metric.count.toString().padStart(2))} (${chalk[color](percentage + '%')})`));
+    });
+
+    // Gap analysis
+    console.log(chalk.cyan('\n📈 GAP ANALYSIS'));
+    const avgTransformations = Object.values(this.stats.transformations).reduce((a, b) => a + b, 0) / 6;
+    const gaps = Object.entries(this.stats.transformations)
+      .filter(([, count]) => count < avgTransformations)
+      .sort((a, b) => a[1] - b[1]);
+
+    if (gaps.length > 0) {
+      console.log(chalk.yellow(`  Average coverage: ${avgTransformations.toFixed(1)} entries per transformation`));
+      console.log(chalk.yellow(`  Need more entries for: ${gaps.map(([t]) => t).join(', ')}`));
+    } else {
+      console.log(chalk.green('  ✓ Balanced transformation coverage'));
+    }
+
+    console.log('\n' + '='.repeat(60) + '\n');
+  }
+
+  async run() {
+    // Find all .bib files
+    const bibFiles = fs.readdirSync(this.bibDir)
+      .filter(f => f.endsWith('.bib'))
+      .map(f => path.join(this.bibDir, f));
+
+    if (bibFiles.length === 0) {
+      if (!jsonOutput) {
+        console.log(chalk.red('\n❌ No .bib files found in ' + this.bibDir));
+      }
+      process.exit(1);
+    }
+
+    // Load all files
+    for (const filepath of bibFiles) {
+      await this.loadFile(filepath);
+    }
+
+    // Output results
+    if (jsonOutput) {
+      console.log(JSON.stringify(this.stats, null, 2));
+    } else {
+      this.printReport();
+    }
+  }
+}
+
+// Run stats
+const stats = new BibStats(bibDir);
+stats.run().catch(err => {
+  if (!jsonOutput) {
+    console.error(chalk.red('Fatal error:'), err);
+  }
+  process.exit(1);
+});

package/toolkit/src/test-validation.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+/**
+ * Test script for HUMMBL Base120 model validation and Memory Palace audit
+ * Run with: node src/test-validation.js
+ */
+
+import { validateModelCode } from './utils/validateModelCode.js';
+import { monitorModelReferences } from './utils/monitorModels.js';
+import { isMemoryPalaceModel, lookupMemoryPalace, auditRegistry } from './extensions/memoryPalace.js';
+import { auditBeyondBase120, scanForExtendedModels } from './extensions/beyondBase120Audit.js';
+
+console.log('🧪 Testing HUMMBL Base120 Model Validation\n');
+
+// Test valid models
+console.log('✅ Testing valid model codes:');
+const validTests = ['P1', 'IN15', 'CO7', 'DE3', 'RE20', 'SY5'];
+
+validTests.forEach(code => {
+  const result = validateModelCode(code);
+  if (result.isValid) {
+    console.log(`  ${code} → "${result.name}" (${result.transformation}) ✅`);
+  } else {
+    console.log(`  ${code} → ERROR: ${result.error} ❌`);
+  }
+});
+
+console.log('\n❌ Testing invalid model codes:');
+const invalidTests = ['P21', 'XX1', 'P0', 'IN', 'CO99'];
+
+invalidTests.forEach(code => {
+  const result = validateModelCode(code);
+  console.log(`  ${code} → ${result.error} ✅ (correctly rejected)`);
+});
+
+console.log('\n📚 Testing Memory Palace registry:');
+const memoryPalaceTests = [
+  { term: 'Antifragility', expected: true },
+  { term: 'Black Swan', expected: true },
+  { term: 'OODA Loop', expected: true },
+  { term: 'Skin in the Game', expected: true },
+  { term: 'Aurelius Lens', expected: true },
+  { term: 'Mimetic Desire', expected: true },
+  { term: 'Belonging Infrastructure', expected: true },
+  { term: 'RandomFakeModel', expected: false },
+  { term: 'SomethingNotRegistered', expected: false },
+];
+
+memoryPalaceTests.forEach(({ term, expected }) => {
+  const found = isMemoryPalaceModel(term);
+  const pass = found === expected;
+  const status = pass ? '✅' : '❌';
+  if (found) {
+    const entry = lookupMemoryPalace(term);
+    console.log(`  "${term}" → registered (${entry.room}, ${entry.source_type ?? 'unset'}) ${status}`);
+  } else {
+    console.log(`  "${term}" → not registered ${status}`);
+  }
+});
+
+console.log('\n🏛️ Memory Palace registry health:');
+const health = auditRegistry();
+console.log(`  Total entries: ${health.totalEntries}`);
+Object.entries(health.byRoom).forEach(([room, count]) => {
+  console.log(`  ${room}: ${count}`);
+});
+if (health.duplicateSlugs.length > 0) {
+  console.log(`  ❌ Duplicate slugs: ${health.duplicateSlugs.join(', ')}`);
+} else {
+  console.log(`  ✅ No duplicate slugs`);
+}
+if (health.duplicateNames.length > 0) {
+  console.log(`  ❌ Duplicate names: ${health.duplicateNames.join(', ')}`);
+} else {
+  console.log(`  ✅ No duplicate names`);
+}
+if (health.missingSourceTypes.length > 0) {
+  console.log(`  ⚠️ Missing source_type: ${health.missingSourceTypes.join(', ')}`);
+} else {
+  console.log(`  ✅ All entries have source_type`);
+}
+
+console.log('\n🔭 Testing Beyond-Base120 audit:');
+const governedText = `
+This framework applies Antifragility principles when designing for uncertainty.
+The Scapegoat Mechanism reveals how communities handle mimetic crises.
+The Aurelius Lens suggests governors should maintain continuous self-audit.
+We use the OODA Loop for rapid decision cycles in dynamic environments.
+`;
+
+const audit = auditBeyondBase120(governedText);
+console.log(`  Terms scanned: ${audit.stats.total_terms_scanned}`);
+console.log(`  Registered: ${audit.stats.registered}`);
+console.log(`  Unregistered: ${audit.stats.unregistered}`);
+if (audit.findings.length === 0) {
+  console.log(`  ✅ All extended model references are registered`);
+} else {
+  audit.findings.forEach(f => {
+    const icon = f.severity === 'ERROR' ? '❌' : '⚠️';
+    console.log(`  ${icon} [${f.code}] ${f.term}: ${f.message}`);
+  });
+}
+
+console.log('\n📊 Testing runtime monitoring:');
+const testOutput = `
+Let's apply P1 (First Principles Framing) to break this down.
+Using DE3 (Modularization) will help organize the code.
+Don't forget IN2 (Premortem Analysis) before deployment.
+Antifragility thinking applies here too.
+`;
+
+const monitoring = monitorModelReferences(testOutput);
+console.log(`Valid references: ${monitoring.valid.join(', ')}`);
+console.log(`Invalid references: ${monitoring.invalid.join(', ') || 'none'}`);
+console.log(`Hallucinations: ${monitoring.hallucinations.join(', ') || 'none (governed extension audit handles this now)'}`);
+
+console.log('\n🎉 Validation system ready for production use!');

package/toolkit/src/utils/modelRegistry.ts

@@ -0,0 +1,193 @@
+/**
+ * HUMMBL Base120 Model Registry Service
+ * Centralized validation and lookup service for mental models
+ */
+
+import { validateModelCode, BASE120_MODELS, TransformationType, ModelCode } from './validateModelCode.js';
+
+export interface ModelDefinition {
+  code: ModelCode;
+  name: string;
+  transformation: TransformationType;
+  description: string;
+  example?: string;
+}
+
+// Singleton Model Registry
+export class ModelRegistry {
+  private static instance: ModelRegistry;
+  private models: Map<ModelCode, ModelDefinition>;
+
+  private constructor() {
+    this.models = this.loadBase120();
+  }
+
+  static getInstance(): ModelRegistry {
+    if (!ModelRegistry.instance) {
+      ModelRegistry.instance = new ModelRegistry();
+    }
+    return ModelRegistry.instance;
+  }
+
+  /**
+   * Load all Base120 models into registry
+   */
+  private loadBase120(): Map<ModelCode, ModelDefinition> {
+    const registry = new Map<ModelCode, ModelDefinition>();
+
+    Object.entries(BASE120_MODELS).forEach(([transformation, models]) => {
+      models.forEach((name, index) => {
+        const code = `${transformation}${index + 1}` as ModelCode;
+        registry.set(code, {
+          code,
+          name,
+          transformation: transformation as TransformationType,
+          description: this.getDefaultDescription(code),
+          example: this.getDefaultExample(code)
+        });
+      });
+    });
+
+    return registry;
+  }
+
+  /**
+   * Validate a model code
+   */
+  validate(code: string): ReturnType<typeof validateModelCode> {
+    return validateModelCode(code);
+  }
+
+  /**
+   * Get model definition by code
+   */
+  getModel(code: ModelCode): ModelDefinition | null {
+    return this.models.get(code) || null;
+  }
+
+  /**
+   * Search models by name or description
+   */
+  search(query: string): ModelCode[] {
+    const results: ModelCode[] = [];
+    const lowerQuery = query.toLowerCase();
+
+    this.models.forEach((def, code) => {
+      if (def.name.toLowerCase().includes(lowerQuery) ||
+          def.description.toLowerCase().includes(lowerQuery)) {
+        results.push(code);
+      }
+    });
+
+    return results;
+  }
+
+  /**
+   * Get all models for a transformation
+   */
+  getTransformationModels(transformation: TransformationType): ModelDefinition[] {
+    const models: ModelDefinition[] = [];
+    this.models.forEach(def => {
+      if (def.transformation === transformation) {
+        models.push(def);
+      }
+    });
+    return models;
+  }
+
+  /**
+   * Get all models
+   */
+  getAllModels(): ModelDefinition[] {
+    return Array.from(this.models.values());
+  }
+
+  /**
+   * Comprehensive audit of text
+   */
+  auditText(text: string): {
+    references: Array<{code: string, definition?: ModelDefinition, isValid: boolean}>;
+    hallucinations: string[];
+    validationErrors: string[];
+  } {
+    const references = this.extractReferences(text);
+    const hallucinations = this.detectHallucinations(text);
+    const validationErrors = this.findValidationErrors(text);
+
+    return { references, hallucinations, validationErrors };
+  }
+
+  /**
+   * Extract model references from text
+   */
+  private extractReferences(text: string): Array<{code: string, definition?: ModelDefinition, isValid: boolean}> {
+    const modelPattern = /(P|IN|CO|DE|RE|SY)(\d+)/g;
+    const matches = [...text.matchAll(modelPattern)];
+
+    return matches.map(([fullMatch, transformation, num]) => {
+      const code = `${transformation}${num}`;
+      const result = validateModelCode(code);
+
+      return {
+        code,
+        definition: result.isValid ? this.models.get(code as ModelCode) : undefined,
+        isValid: result.isValid
+      };
+    });
+  }
+
+  /**
+   * Hallucination detection removed — use beyondBase120Audit.ts (Memory Palace)
+   * for extended model drift detection. No-op retained for interface compat.
+   */
+  private detectHallucinations(_text: string): string[] {
+    return [];
+  }
+
+  /**
+   * Find validation errors
+   */
+  private findValidationErrors(text: string): string[] {
+    const errors: string[] = [];
+    const references = this.extractReferences(text);
+
+    references.forEach(ref => {
+      if (!ref.isValid) {
+        errors.push(`Invalid model code: ${ref.code}`);
+      }
+    });
+
+    return errors;
+  }
+
+  /**
+   * Get default description for a model (placeholder)
+   */
+  private getDefaultDescription(code: ModelCode): string {
+    // In a full implementation, this would have detailed descriptions
+    // For now, return a basic description
+    const result = validateModelCode(code);
+    return result.name ? `HUMMBL Base120 model: ${result.name}` : 'Unknown model';
+  }
+
+  /**
+   * Get default example for a model (placeholder)
+   */
+  private getDefaultExample(code: ModelCode): string {
+    // In a full implementation, this would have usage examples
+    return `Example usage of ${code}`;
+  }
+
+  /**
+   * Health check
+   */
+  healthCheck(): { status: 'healthy' | 'unhealthy', modelCount: number } {
+    const modelCount = this.models.size;
+    const expectedCount = 120; // 6 transformations × 20 models each
+
+    return {
+      status: modelCount === expectedCount ? 'healthy' : 'unhealthy',
+      modelCount
+    };
+  }
+}

package/toolkit/src/utils/monitorModels.ts

@@ -0,0 +1,150 @@
+/**
+ * Runtime monitoring for HUMMBL Base120 model references
+ * Prevents hallucination by monitoring agent outputs in real-time
+ */
+
+import { validateModelCode, ModelCode } from './validateModelCode.js';
+
+export interface AuditReport {
+  references: ModelReference[];
+  hallucinations: string[];
+  validationErrors: string[];
+}
+
+export interface ModelReference {
+  code: string;
+  name?: string;
+  isValid: boolean;
+  position: number;
+}
+
+/**
+ * Monitors agent output for mental model references and hallucinations
+ */
+export function monitorModelReferences(output: string): {
+  valid: ModelCode[];
+  invalid: string[];
+  hallucinations: string[];
+} {
+  const modelPattern = /(P|IN|CO|DE|RE|SY)(\d+)/g;
+  const matches = [...output.matchAll(modelPattern)];
+
+  const valid: ModelCode[] = [];
+  const invalid: string[] = [];
+
+  matches.forEach(([fullMatch, transformation, num]) => {
+    const code = `${transformation}${num}`;
+    const result = validateModelCode(code);
+
+    if (result.isValid) {
+      valid.push(code as ModelCode);
+    } else {
+      invalid.push(code);
+    }
+  });
+
+  // Check for hallucinated terms
+  const hallucinations = detectHallucinations(output);
+
+  return { valid, invalid, hallucinations };
+}
+
+/**
+ * Comprehensive audit of text for model compliance
+ */
+export function auditText(text: string): AuditReport {
+  const references = extractReferences(text);
+  const hallucinations = detectHallucinations(text);
+  const validationErrors = findValidationErrors(text);
+
+  return {
+    references,
+    hallucinations,
+    validationErrors
+  };
+}
+
+/**
+ * Extract all model references from text
+ */
+function extractReferences(text: string): ModelReference[] {
+  const modelPattern = /(P|IN|CO|DE|RE|SY)(\d+)/g;
+  const matches = [...text.matchAll(modelPattern)];
+
+  return matches.map((match, index) => {
+    const code = `${match[1]}${match[2]}`;
+    const result = validateModelCode(code);
+
+    return {
+      code,
+      name: result.name,
+      isValid: result.isValid,
+      position: match.index || 0
+    };
+  });
+}
+
+/**
+ * Detect hallucinated mental model references.
+ * Governed ARCANA models and BaseN extensions are excluded from hallucination
+ * detection — they are first-class governed models, not noise.
+ */
+/**
+ * Hallucination detection removed — use beyondBase120Audit.ts (Memory Palace)
+ * for extended model drift detection. No-op retained for interface compat.
+ */
+function detectHallucinations(_text: string): string[] {
+  return [];
+}
+
+/**
+ * Find validation errors in model references
+ */
+function findValidationErrors(text: string): string[] {
+  const errors: string[] = [];
+  const references = extractReferences(text);
+
+  references.forEach(ref => {
+    if (!ref.isValid) {
+      errors.push(`Invalid model code: ${ref.code}`);
+    }
+  });
+
+  return errors;
+}
+
+/**
+ * Check if output passes model validation
+ */
+export function passesValidation(output: string): boolean {
+  const { invalid, hallucinations } = monitorModelReferences(output);
+  return invalid.length === 0 && hallucinations.length === 0;
+}
+
+/**
+ * Generate validation report for logging
+ */
+export function generateValidationReport(output: string): string {
+  const audit = auditText(output);
+  const { valid, invalid, hallucinations } = monitorModelReferences(output);
+
+  let report = 'MENTAL MODEL VALIDATION REPORT\n';
+  report += '='.repeat(40) + '\n\n';
+
+  report += `Valid references (${valid.length}): ${valid.join(', ') || 'None'}\n`;
+  report += `Invalid references (${invalid.length}): ${invalid.join(', ') || 'None'}\n`;
+  report += `Hallucinations detected (${hallucinations.length}): ${hallucinations.join(', ') || 'None'}\n\n`;
+
+  if (audit.validationErrors.length > 0) {
+    report += 'Validation Errors:\n';
+    audit.validationErrors.forEach(error => {
+      report += `- ${error}\n`;
+    });
+    report += '\n';
+  }
+
+  const overallStatus = passesValidation(output) ? '✅ PASS' : '❌ FAIL';
+  report += `Overall Status: ${overallStatus}\n`;
+
+  return report;
+}