marinaedutlan 0.6.1

package/bin/marina.js

@@ -0,0 +1,414 @@
+#!/usr/bin/env node
+/**
+ * marina
+ * Unified Metacognitive System — lightweight professional CLI + unified core (DMA + Meta-DNA + MCP).
+ *
+ * This published package contains only the core + CLI (no heavy UI/frontend).
+ * Full rich web lab with visualizations is available by running from source.
+ *
+ * Version is read from package.json at runtime.
+ */
+
+import { spawn } from 'child_process';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { dirname, join } from 'path';
+import { readFileSync } from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// When installed globally or locally, __dirname points inside the package.
+// We ship only the lightweight core + CLI (see "files" in package.json).
+const packageRoot = join(__dirname, '..');
+const distCore = join(packageRoot, 'dist', 'core', 'MarinaAgent.js');
+
+// Read our own version for --version / banners (professional touch)
+let PKG_VERSION = '0.6.1';
+try {
+  const pkg = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
+  PKG_VERSION = pkg.version || PKG_VERSION;
+} catch {}
+
+const args = process.argv.slice(2);
+const subcommand = args[0];
+
+async function showWelcomeAndQuickDemo() {
+  console.log('\n╔════════════════════════════════════════════════════════════════════════════╗');
+  console.log(`║  MARINA — Unified Metacognitive System (v${PKG_VERSION})                          ║`);
+  console.log('║  One single integrated core: DMA (bio) + Meta-DNA (regulatory) + MCP (exec)  ║');
+  console.log('╚════════════════════════════════════════════════════════════════════════════╝\n');
+
+  console.log('Lightweight professional package: CLI + unified MarinaAgent core.');
+  console.log('The rich web lab with full visualizations is available by running from source.\n');
+
+  // Give immediate value: run a short professional demo episode
+  console.log('Running quick 40-step integrated demo...\n');
+
+  try {
+    const coreUrl = pathToFileURL(distCore).href;
+    const { MarinaAgent } = await import(coreUrl);
+    const agent = new MarinaAgent();
+    agent.runEpisode(40);
+    const summary = agent.getSummary();
+
+    printUnifiedSummary(summary, 40);
+  } catch (e) {
+    console.log('Could not load core for demo. Basic banner only.');
+  }
+
+  console.log('\nNext steps:');
+  console.log('  marina run --steps 120                      # longer headless episode on the unified core');
+  console.log('  marina run --steps 80 --json                # machine readable (includes substrate stats)');
+  console.log('  marina run --steps 60 --save-profile        # persist epigenetic traces + substrate experiences');
+  console.log('  marina run --load-profile my-profile.json   # resume previous "cognitive development"');
+  console.log('  marina doctor                               # health + core verification');
+  console.log('  marina examples                             # paper-aligned usage');
+  console.log('  marina --help\n');
+
+  console.log('For the full interactive scientific lab (all layer visualizations,');
+  console.log('Sync to Tabs, Gemini Mirror Test, etc.): clone the repo and run `npm run dev`.\n');
+}
+
+async function startFullWebLab() {
+  // Informational only — the full rich web lab (React visualizations, Gemini Mirror Test, etc.)
+  // is intentionally not included in the published lightweight package.
+  console.log('\nThe full rich web UI is not bundled in this package (keeps it small).');
+  console.log('To run the complete scientific interface with all visualizations:');
+  console.log('  git clone https://github.com/cristianmi24/Marina.git && cd Marina && npm install && npm run dev\n');
+}
+
+function printUnifiedSummary(summary, steps) {
+  const u = (summary.uncertainty?.toFixed?.(3) ?? summary.uncertainty ?? '—').toString().padEnd(6);
+  const p = (summary.performance?.toFixed?.(3) ?? summary.performance ?? '—').toString().padEnd(6);
+  const z = (summary.satisfaction?.toFixed?.(3) ?? summary.satisfaction ?? '—').toString().padEnd(6);
+  const paths = (summary.activePathways || []).join(', ') || '—';
+  const g = (summary.dmaGHCN?.toFixed?.(3) ?? summary.dmaGHCN ?? '—');
+  const tm = (summary.dmaTauM?.toFixed?.(1) ?? summary.dmaTauM ?? '—');
+  const q = (summary.mcpQuality?.toFixed?.(2) ?? summary.mcpQuality ?? '—');
+  const r = (summary.mcpRisk?.toFixed?.(2) ?? summary.mcpRisk ?? '—');
+
+  console.log('┌────────────────────────────────────────────────────────────┐');
+  console.log('│  Unified Episode Summary — single MarinaAgent (v' + PKG_VERSION + ')          │');
+  console.log('├────────────────────────────────────────────────────────────┤');
+  console.log(`│  Steps: ${String(steps).padEnd(52)} │`);
+  console.log(`│  Uncertainty: ${u}   Performance: ${p}   Satisfaction: ${z} │`);
+  console.log(`│  Active pathways: ${paths.padEnd(42)} │`);
+  console.log(`│  DMA: gHCN=${g}  tauM=${tm}                              │`);
+  console.log(`│  MCP: q=${q}  r=${r}                                      │`);
+  if (summary.episodicEngrams != null) {
+    console.log(`│  Episodic engrams (DMA): ${(summary.episodicEngrams + '').padEnd(35)} │`);
+  }
+  if (summary.workingMemoryLoad != null) {
+    console.log(`│  WM load (items): ${(summary.workingMemoryLoad.toFixed(2) + ' (' + (summary.workingMemoryItems || 0) + ')').padEnd(30)} │`);
+  }
+  if (summary.metamemoryAvgConfidence != null) {
+    console.log(`│  Metamemory avg confidence: ${(summary.metamemoryAvgConfidence.toFixed(2) + '').padEnd(32)} │`);
+  }
+  if (summary.lastMCPAction) {
+    console.log(`│  Last MCP dispatched: ${(summary.lastMCPAction + '').padEnd(38)} │`);
+  }
+  if (summary.lastDispatch && summary.lastDispatch.substrateAfter) {
+    const sa = summary.lastDispatch.substrateAfter;
+    console.log(`│  After dispatch - Plasticity: ${sa.plasticityBias}  MemoryPressure: ${sa.memoryPressure} │`);
+  }
+  if (summary.selfAuditProblems != null) {
+    console.log(`│  IM-Onto Self-Audit problems: ${(summary.selfAuditProblems + '').padEnd(30)} │`);
+  }
+  if (summary.epistemicUtility) {
+    console.log(`│  CMT Epistemic Utility: ${(summary.epistemicUtility + '').padEnd(34)} │`);
+  }
+  // Metamemory from substrate (CARINA12 / IM-Onto alignment)
+  if (summary.selfAudit && summary.selfAudit.modelOfSelf && summary.selfAudit.modelOfSelf.metamemory) {
+    const mm = summary.selfAudit.modelOfSelf.metamemory;
+    console.log(`│  Metamemory (avgConf/pressure): ${mm.avgConfidence} / ${mm.plasticityInfluence} │`);
+  }
+  if (summary.substrateSnapshot) {
+    const ss = summary.substrateSnapshot;
+    console.log(`│  Substrate: WM ${ss.wmLoad?.toFixed(2)} | Engrams ${ss.episodicSize} | Plast ${ss.plasticity?.toFixed(2)} │`);
+  }
+  console.log('└────────────────────────────────────────────────────────────┘');
+}
+
+async function runHeadless(steps = 100, json = false, saveProfile = false, loadProfile = null) {
+  if (!json) {
+    console.log(`\n🧪 MARINA — Running ${steps}-step integrated episode (headless)`);
+    console.log('   Single core: DMA (Dendritic Metacognition) + Meta-DNA + MCP + substrate seed\n');
+  }
+
+  try {
+    const coreUrl = pathToFileURL(distCore).href;
+    const { MarinaAgent } = await import(coreUrl);
+    const agent = new MarinaAgent();
+
+    // First-class (minimal) epigenetic + substrate persistence
+    if (loadProfile) {
+      try {
+        const fs = await import('fs');
+        const profile = JSON.parse(fs.readFileSync(loadProfile, 'utf8'));
+        agent.deserialize(profile);
+        if (!json) console.log(`   Loaded profile: ${loadProfile} (epigenetic + substrate traces restored)`);
+      } catch (e) {
+        if (!json) console.log(`   Warning: could not load profile ${loadProfile} (${e.message})`);
+      }
+    }
+
+    const results = agent.runEpisode(steps);
+    const summary = agent.getSummary();
+
+    if (saveProfile) {
+      try {
+        const fs = await import('fs');
+        const path = await import('path');
+        const outDir = process.cwd();
+        const file = path.join(outDir, `marina-profile-${Date.now()}.json`);
+        fs.writeFileSync(file, JSON.stringify(agent.serialize(), null, 2));
+        if (!json) console.log(`   Profile saved: ${file} (contains epigenetic traces + substrate experiences)`);
+      } catch (e) {
+        if (!json) console.log('   Warning: failed to save profile:', e.message);
+      }
+    }
+
+    if (json) {
+      const payload = {
+        version: PKG_VERSION,
+        steps,
+        summary,
+        substrate: {
+          workingMemoryLoad: summary.workingMemoryLoad,
+          workingMemoryItems: summary.workingMemoryItems,
+          episodicEngrams: summary.episodicEngrams,
+          metamemory: agent.getSubstrateStats ? agent.getSubstrateStats().metamemory : null,
+          legacy: agent.getSubstrateStats ? agent.getSubstrateStats() : null
+        },
+        lastDispatch: summary.lastDispatch || null,
+        selfAudit: summary.selfAudit || (agent.getSelfAudit ? agent.getSelfAudit() : null),
+        epistemicMirror: summary.epistemicMirror || (agent.getEpistemicMirrorSignals ? agent.getEpistemicMirrorSignals() : null),
+        lastFew: results.slice(-3)
+      };
+      if (saveProfile) payload.profileSaved = true;
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    printUnifiedSummary(summary, steps);
+    console.log('\nThis run exercised the *one* integrated system described in the papers.');
+    console.log('   Substrate experiences recorded:', summary.substrateExperiences ?? 0);
+    console.log('   Task type:', summary.taskType || 'internal-bandit');
+    console.log('For rich visualizations, cross-layer sync and paper explorer:  marina\n');
+    console.log('Tip: Use the JS/Python API for custom tasks with retrieval bias (pre-computed and exposed):');
+    console.log('  // JS');
+    console.log('  const t = MarinaAgent.createSimpleTask(ctx => 0.4 + (ctx.retrievalBias || 0) * 0.8);');
+    console.log('  const a = new MarinaAgent(); a.setTask(t);');
+    console.log('  const ev = a.evaluate(null, 20); console.log(ev.avgOutcome, ev.finalSummary.lastRetrievalBias);');
+    console.log('  // Python');
+    console.log('  from marina.core import MarinaAgent');
+    console.log('  def my_task(ctx): return 0.4 + (ctx.get("retrievalBias", 0) * 0.8)');
+    console.log('  a = MarinaAgent(task=my_task); ev = a.evaluate(steps=20); print(ev["avgOutcome"], ev["lastRetrievalBias"]) \n');
+  } catch (e) {
+    if (json) {
+      console.log(JSON.stringify({ error: 'core_load_failed', message: String(e) }));
+      return;
+    }
+    console.error('✗ Failed to load the compiled unified core.');
+    console.error('  Root cause:', e?.message || e);
+    console.error('\n  Ensure the package was built (prepublish does this).');
+    console.error('  Local dev:   npm run build && npm run build:core');
+    console.error('  Then test:   node bin/marina.js run --steps 30\n');
+    console.error('  Fallback:    Run `marina` (no args) and use the "Run 100-step Integrated Episode" button in the UI.');
+    process.exit(1);
+  }
+}
+
+async function runDoctor() {
+  console.log(`\n🩺 MARINA v${PKG_VERSION} Doctor — system health for the unified package\n`);
+
+  const checks = [];
+
+  // Node version
+  const nodeV = process.version;
+  const major = parseInt(nodeV.slice(1).split('.')[0], 10);
+  checks.push({ name: 'Node >=18', ok: major >= 18, detail: nodeV });
+
+  // Package version (self)
+  checks.push({ name: 'Package version', ok: true, detail: PKG_VERSION });
+
+  checks.push({ name: 'No heavy runtime deps (lightweight core+CLI package)', ok: true, detail: 'published package has empty dependencies' });
+
+  // dist/core exists
+  let coreFileOk = false;
+  try {
+    // simple existence via import attempt later
+    coreFileOk = true; // will be validated in load test
+  } catch {}
+  checks.push({ name: 'dist/core/MarinaAgent.js present', ok: coreFileOk, detail: 'checked at runtime' });
+
+  // Core load test
+  let coreOk = false;
+  let coreDetail = '';
+  try {
+    const coreUrl = pathToFileURL(distCore).href;
+    const { MarinaAgent } = await import(coreUrl);
+    const a = new MarinaAgent();
+    a.step();
+    const s = a.getSummary();
+    coreOk = !!(s && typeof s.uncertainty === 'number');
+    coreDetail = coreOk ? 'loaded + stepped OK (dist/core/MarinaAgent.js)' : 'loaded but summary odd';
+  } catch (e) {
+    coreDetail = 'FAILED: ' + (e?.message || e);
+  }
+  checks.push({ name: 'Unified core (MarinaAgent)', ok: coreOk, detail: coreDetail + ' + functional substrate seed' });
+
+  // Package files presence (heuristic)
+  const hasServer = true; // we got this far
+  checks.push({ name: 'Published assets (dist + bin)', ok: hasServer, detail: 'visible in runtime context' });
+
+  console.log('Checks:');
+  for (const c of checks) {
+    const mark = c.ok ? '✓' : (c.name.includes('optional') ? '△' : '✗');
+    console.log(`  ${mark} ${c.name.padEnd(34)} ${c.detail}`);
+  }
+
+  const allCritical = checks.filter(c => !c.name.includes('optional')).every(c => c.ok);
+  console.log('\n' + (allCritical ? '✅ Core system healthy. Ready for `marina` and `marina run`.' : '⚠️  Some checks failed. See guidance above.'));
+  console.log('   Full rich lab (visualizations): run the project from source (`npm run dev`).\n');
+}
+
+function showVersion() {
+  console.log(`marina ${PKG_VERSION}`);
+  process.exit(0);
+}
+
+function showExamples() {
+  console.log(`
+MARINA v${PKG_VERSION} — Paper-aligned usage examples (single unified system)
+
+1. Headless research run (reproducible episode)
+   marina run --steps 120
+   # or JSON for scripts / notebooks:
+   marina run --steps 50 --json
+   # persist "cognitive development" (epigenetic traces + substrate experiences):
+   marina run --steps 80 --save-profile
+   marina run --load-profile marina-profile-*.json --steps 40
+
+   Expected qualitative (from DMA + Meta-DNA + MCP papers):
+   - DMA: gHCN rises and tauM contracts on stable regimes (<10 step recovery on reversal)
+   - Meta-DNA: 1–3 pathways co-express (p_TimeMgmt, p_EpistemicVal, p_CogPlanning)
+   - MCP: q improves while r (risk) is actively suppressed under high u
+   - Substrate: experiences with DMA snapshots are recorded (seed for future full episodic memory)
+
+2. Programmatic (Python — same core logic)
+   pip install marina
+   python -c "
+   from marina import MarinaAgent
+   a = MarinaAgent()
+   a.run_episode(80)
+   print(a.get_summary())
+   "
+
+3. Full interactive scientific lab (all visualizations)
+   Clone the repo and run from source:
+   git clone https://github.com/cristianmi24/Marina.git
+   cd Marina && npm install && npm run dev
+   (The rich React lab is not included in the published npm package to keep it small.)
+
+4. Quick doctor (verify your installed package)
+   marina doctor
+
+All paths exercise the *same* MarinaAgent (one system). The tabs in the UI are
+high-fidelity paper views that can be driven from the unified core (Sync button).
+`);
+}
+
+function showHelp() {
+  console.log('marina v' + PKG_VERSION + ' - Unified Metacognitive System (core + CLI). See --help or "marina run". Full web lab from source.');
+  process.exit(0);
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+  process.exit(0);
+}
+
+// Robust arg parsing (no external deps, pure Node)
+function parseArgs(argv) {
+  const out = {
+    steps: 100,
+    json: false,
+    saveProfile: false,
+    loadProfile: null,
+    help: false,
+    version: false
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+
+    if (a === '--steps' || a === '-s') {
+      out.steps = parseInt(next, 10) || 100;
+      i++;
+    } else if (a === '--json' || a === '-j') {
+      out.json = true;
+    } else if (a === '--save-profile') {
+      out.saveProfile = true;
+    } else if (a === '--load-profile') {
+      out.loadProfile = next || null;
+      i++;
+    } else if (a === '--help' || a === '-h') {
+      out.help = true;
+    } else if (a === '--version' || a === '-v') {
+      out.version = true;
+    } else if (/^\d+$/.test(a)) {
+      out.steps = parseInt(a, 10);
+    }
+  }
+  return out;
+}
+
+const rest = args.slice(1); // after subcommand
+
+if (!subcommand) {
+  await showWelcomeAndQuickDemo();
+} else if (subcommand === 'ui' || subcommand === 'start' || subcommand === 'web') {
+  await startFullWebLab();
+} else if (subcommand === 'run' || subcommand === 'episode') {
+  const opts = parseArgs(rest);
+  if (opts.help) {
+    showHelp();
+    process.exit(0);
+  }
+  if (opts.version) {
+    showVersion();
+  }
+  await runHeadless(opts.steps, opts.json, opts.saveProfile, opts.loadProfile);
+} else if (subcommand === 'doctor' || subcommand === 'health') {
+  await runDoctor();
+} else if (subcommand === 'examples' || subcommand === 'ex') {
+  showExamples();
+} else if (subcommand === 'version' || subcommand === '--version' || subcommand === '-v') {
+  showVersion();
+} else if (subcommand === '--help' || subcommand === '-h' || subcommand === 'help') {
+  showHelp();
+} else {
+  console.error(`Unknown command: ${subcommand}`);
+  showHelp();
+  process.exit(1);
+}

package/dist/core/MarinaAgent.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Public type declarations for the bundled Marina core.
+ * This file is copied to dist/core/MarinaAgent.d.ts during build for packaging.
+ *
+ * The runtime implementation is the bundled ESM in MarinaAgent.js.
+ * These types describe the public contract used by CLI, tests, and consumers
+ * of `import { MarinaAgent } from "marina/core"`.
+ */
+
+export interface Task {
+  getOutcome(context: {
+    step: number;
+    lastAction?: any;
+    dmaState?: any;
+    proposedAction?: any;
+    retrievalBias?: number;
+  }): { reward: number; info?: any };
+  reset?(): void;
+}
+
+export interface MarinaAgentOptions {
+  dmaManualRegime?: number;
+  dnaRegime?: 'Static' | 'Dynamic' | 'Adversarial';
+  forceMcpStep?: boolean;
+}
+
+export declare class MarinaAgent {
+  stepCount: number;
+  history: any[];
+
+  // Core layers (exposed for inspection / advanced use)
+  dma: any;
+  metaDna: any;
+  mcp: any;
+
+  // Cognitive substrate (Working Memory + Episodic/Semantic/Procedural memories)
+  workingMemory: any;
+  episodicMemory: any;
+  semanticMemory: any;
+  proceduralMemory: any;
+  substrate: any; // legacy trace buffer
+
+  // Metrics exposed by the unified run
+  productionsFired: number;
+  lastAlg1Overhead: number;
+  lastRetrievalBias: number;
+  lastProposedAction: number | null;
+
+  constructor(initialMcpBackend?: 'Planner' | 'RAG', task?: Task | null);
+
+  /** Advance the entire integrated system (DMA + Meta-DNA + MCP + substrate) by one step. */
+  step(options?: MarinaAgentOptions): {
+    dma?: any;
+    metaDna?: any;
+    mcp?: any;
+  };
+
+  /** Run N steps using the unified core. */
+  runEpisode(steps?: number): any[];
+
+  /** Return a compact summary suitable for dashboards, CLI and persistence.
+   * The exact shape is rich and may evolve; treat as opaque object with documented fields
+   * (uncertainty, performance, activePathways, dmaGHCN, lastRetrievalBias, etc.).
+   */
+  getSummary(): any;
+
+  /** Return the full combined state of the single system (authoritative for UI sync, etc.). */
+  getCombinedState(): any;
+
+  /** Rich self-audit (IM-Onto KTP/DRFP/ADTP style) enriched with substrate + regulator signals. */
+  getSelfAudit?(): any;
+
+  /** CMT / epistemic mirror signals derived from the unified state. */
+  getEpistemicMirrorSignals?(): any;
+
+  /** Substrate statistics (experiences, plasticity, memory pressure, etc.). */
+  getSubstrateStats(): any;
+
+  /** Evaluate a (custom) task for a number of steps and return rich results including self-audit. */
+  evaluate(task?: Task | null, steps?: number, options?: { includeHistory?: boolean }): any;
+
+  /** Run an episode on a specific task without permanently replacing the agent's task. */
+  runOnTask(task: Task, steps?: number, options?: any): { results: any[]; summary: any; taskType: string };
+
+  /** Replace the current pluggable task/environment. */
+  setTask(task: Task): void;
+
+  /** Ask the procedural memory what it would propose right now (useful with custom tasks). */
+  proposeAction(context?: any): any;
+
+  /** Reset the entire agent (layers + substrate + counters). */
+  reset(): void;
+
+  /** Serialize key persistent state (epigenetic traces + substrate experiences) for cross-run "cognitive development". */
+  serialize(): any;
+
+  /** Restore from a previously serialized snapshot. */
+  deserialize(data: any): void;
+
+  /** Static helper to create a simple Task from a reward function (great for quick experiments). */
+  static createSimpleTask(rewardFn: (ctx: any) => number | { reward: number; info?: any }): Task;
+}
+
+export interface DMAState { /* internal - exposed via getCombinedState / getSummary */ }
+export interface MetaDNAStep { /* internal */ }
+export interface MCPStepLog { /* internal */ }
+
+export { Task as MarinaTask };