marinaedutlan 0.7.0

Marina — Unified Metacognitive System. Python package providing the core MarinaAgent (DMA + Meta-DNA + MCP + pluggable Task substrate with retrieval bias, evaluate, and runOnTask) with CLI and API. Implements key elements from CARINA12 papers (unified substrate, Algorithm 1 approximation, metamemory, custom tasks, memory-influenced decisions).

Marina

A unified, extensible metacognitive system — downloadable via npm and pip, scriptable, and ready for research.

v0.7.0 (Beta) — Marina implements key elements of the CARINA 12 bio-inspired metacognitive cognitive architecture (BIMCA). It provides a single integrated core (MarinaAgent) combining:

• DMA (Dendritic Metacognitive Architecture): biophysical stability-plasticity primitives.
• Meta-DNA: regulatory "genome" with Model of the Self, pathways, epigenetic traces (χ), and Algorithm 1 approximation with overhead and modulation.
• MCP (Metacognitive Control Plane): decision-theoretic executive with rich actions.
• Pluggable Task Substrate: Working Memory (multi-buffer with load and focus modulation), Episodic Memory (with DMA engrams), Semantic Memory (activation + spreading simulation), Procedural Memory (utilities + conflict resolution). Retrieval bias is pre-computed and influences action selection from the first step.

Marina is designed for researchers to run, inspect, reproduce, and extend experiments with memory-modulated decisions, regulatory overhead, and custom environments. The TypeScript core is the reference implementation for paper fidelity; the Python package provides convenient parity for scripting and teaching.

One install. One core. Multiple interfaces (CLI, Python, JS, full web lab from source).

---

1. Qué es Marina / What is Marina

Marina is not a collection of independent tabs or demos.

It is one downloadable system whose heart is MarinaAgent:

• DMA (Dendritic Metacognitive Architecture): biophysically-grounded stability-plasticity via apical HCN channels. Real reversal recovery dynamics (<10 steps in paper-aligned regimes).
• Meta-DNA: GRN-inspired regulatory layer. Model of the Self (u,l,p,e,z), transcription factors, meta-genes, co-expressed pathways, and persistent epigenetic traces (χ) — the "cognitive development" mechanism.
• MCP (Metacognitive Control Plane): 1-step lookahead EU with 5+ meta-actions, risk/uncertainty/cost calibration.

Cross-layer effects are real (active pathways modulate DMA tauM and MCP risk; DMA deltas feed MoS uncertainty). The UI tabs are high-fidelity scientific visualizations that can be driven from the single unified core (see "Sync to Tabs").

Goal for 1.0: professional CLI + excellent onboarding + unmistakable "I am using one system" feeling.

---

Installation

npm (recommended for research fidelity and full features)

The npm package provides the canonical TypeScript implementation (reference for paper fidelity, full biophysical dynamics, and complete cross-layer modulation).

# Global install (recommended for CLI)
npm install -g marinaedutlan

# Or local / one-off
npx marinaedutlan

Requirements: Node.js >= 18.

After installation, marina (or npx marinaedutlan) launches a professional welcome banner, runs a quick 40-step integrated episode using the unified MarinaAgent, and displays a boxed summary with key metrics (uncertainty, performance, active pathways, DMA/MCP state, substrate metrics, last retrieval bias, etc.).

PyPI (Python package — convenient scripting and teaching)

The Python package (pip install marinaedutlan) provides a usable implementation of the same MarinaAgent core (DMA + Meta-DNA + MCP + pluggable Task substrate with retrieval bias, evaluate/runOnTask, persistence, self-audit, etc.). It is ideal for quick experiments, teaching, and environments where Node is not preferred.

Important: The distribution name on PyPI is marinaedutlan (to avoid collision with an unrelated "marina" project). After install you import as marina:

pip install marinaedutlan

# Run a 100-step episode (CLI)
marina
# or
marinaedutlan

# Or programmatic (both forms work)
python -c "
from marina.core import MarinaAgent
# or: from marina import MarinaAgent
agent = MarinaAgent()
agent.run_episode(100)
print(agent.get_summary())
"

Requirements: Python >= 3.9 + click.

Fidelity note: Both the npm and PyPI packages now deliver a high-fidelity implementation of the same unified MarinaAgent (DMA + Meta-DNA + MCP + rich cognitive substrate with pre-computed retrieval bias, Algorithm 1 regulation, pluggable Task, and persistence). The TypeScript version is the primary reference for the most precise biophysical constants and paper-aligned numbers. The Python version provides full practical parity for experiments, custom Tasks, profiles, and research use.

Full scientific web laboratory (from source)

For the complete interactive lab (high-fidelity layer visualizations, "Sync to Tabs", paper browser, Gemini Mirror Test, episode results with rich metrics):

git clone https://github.com/cristianmi24/Marina.git
cd Marina
npm install
npm run dev

The published packages intentionally ship only the lightweight core + CLI (no heavy UI assets) to keep distribution small and focused on the unified agent.

Optional: GEMINI_API_KEY for live Mirror Test queries in the full lab.

---

Quick Start

CLI (immediate value)

marina
# or
marina run --steps 120
marina run --steps 80 --json

You will see a professional banner, a real integrated episode using MarinaAgent, and a clean summary including:

• Core states (uncertainty, performance, satisfaction, active pathways)
• DMA (gHCN, tauM, beta)
• MCP (quality, risk)
• Substrate metrics (WM load, episodic engrams, semantic activation, procedural productions)
• lastRetrievalBias and lastProposedAction (how memory influenced the decision)
• Self-audit problems and epistemic utility

Programmatic Usage

Python

from marina.core import MarinaAgent
# or: from marina import MarinaAgent

agent = MarinaAgent()
agent.run_episode(150)
print(agent.get_summary())
# Includes: taskType, lastRetrievalBias, lastProposedAction, activePathways, alg1Overhead, etc.

JavaScript / TypeScript (canonical reference)

import { MarinaAgent } from "marinaedutlan/core";

const agent = new MarinaAgent("Planner");
agent.runEpisode(150);
console.log(agent.getSummary());

Headless/scripting use is recommended for research and reproducible experiments.

---

Features (aligned with CARINA 12 vision)

Marina provides a runnable, extensible seed of a bio-inspired metacognitive cognitive architecture:

• Unified Core (MarinaAgent): DMA + Meta-DNA (Model of the Self, pathways, epigenetic traces χ, Algorithm 1 approximation with overhead and direct modulation of WM/productions) + MCP.
• Pluggable Task Substrate:
  • Working Memory: multi-buffer (Goal/Retrieval/Perceptual/Motor/Imaginal) with load signals and pathway-driven focus modulation.
  • Episodic Memory: DMA engrams + retrieval/use/consolidate + metamemory.
  • Semantic Memory: activation + spreading simulation (outcome/delta similarity + recency).
  • Procedural Memory: utilities, conflict resolution, firing with effects, Meta-DNA modulation.
• Memory-influenced decisions: Retrieval bias is pre-computed at the beginning of each step from semantic and episodic memory and directly biases the action proposed to the Task (exposed as lastRetrievalBias and lastProposedAction).
• Experimentation tools: evaluate(task, steps, options) and runOnTask(task, steps) return rich results including self-audit, substrate snapshots, and history.
• Self-monitoring: Enriched IM-Onto-style self-audit (KTP/DRFP/ADTP) and epistemic utility signals.
• Persistence: Epigenetic state (χ traces) for cross-episode "cognitive development".

The TypeScript core is the reference implementation for paper fidelity. The Python package provides convenient parity on the extensible features (Task, bias, evaluate, runOnTask, last* fields).

Academic Context

This work follows the CARINA 12 — Bio-Inspired Metacognitive Cognitive Architecture plan and related papers on Dendritic Metacognition (DMA) and Meta-DNA regulatory genomes (see papers/ folder).

It demonstrates:

• A unified substrate + regulatory genome + executive plane.
• Pre-computed retrieval bias influencing action selection (memory-first decisions).
• Algorithm 1-style regulation with measurable overhead and modulation of working memory and procedural utilities.
• Easy custom-task experimentation so researchers can study how memory and regulation affect behavior in their own environments.

Current status (transparent): Core architectural elements and practical extensibility are implemented and well integrated. Full classical CA substrate details (rich spreading activation, complete procedural compilation), exact paper Algorithm 1, and comprehensive P1–P4 ablation harnesses remain areas of ongoing/future work.

Advanced Usage — Custom Tasks & Experiments

The pluggable Task system is one of Marina’s most powerful practical features.

JavaScript / TypeScript (recommended form)

import { MarinaAgent } from "marinaedutlan/core";

// Preferred: use the factory (guarantees correct Task shape)
const myTask = MarinaAgent.createSimpleTask((ctx) => {
  // ctx includes: step, retrievalBias, proposedAction, dmaState, ...
  const base = (ctx.step % 4 === 0 ? 0.75 : 0.35);
  return { reward: base + (ctx.retrievalBias || 0) * 0.9 };
});

const agent = new MarinaAgent("Planner", myTask);
const result = agent.evaluate(null, 50, { includeHistory: true });

console.log("avgOutcome:", result.avgOutcome);
console.log("lastRetrievalBias:", result.finalSummary.lastRetrievalBias);
console.log("lastProposedAction:", result.finalSummary.lastProposedAction);

// You can also swap tasks at runtime:
agent.setTask(MarinaAgent.createSimpleTask(ctx => 0.5));
const proposal = agent.proposeAction();

Python (equivalent)

from marina.core import MarinaAgent

def my_task(ctx):
    base = 0.75 if ctx.get("step", 0) % 4 == 0 else 0.35
    return {"reward": base + (ctx.get("retrievalBias") or 0) * 0.9}

agent = MarinaAgent(task=MarinaAgent.create_simple_task(my_task))
result = agent.evaluate(steps=50)

print(result["avgOutcome"], result["lastRetrievalBias"])

# Runtime swap + proposeAction
agent.set_task(MarinaAgent.create_simple_task(lambda ctx: 0.5))
proposal = agent.propose_action()

You can also use agent.runOnTask(...) / agent.run_on_task(...) (temporary task for one evaluation) and agent.proposeAction() / agent.propose_action().

Inspecting state

s = agent.get_summary()
print(s["lastRetrievalBias"], s["lastProposedAction"], s["workingMemoryLoad"])

This design makes it straightforward to study how memory pressure, semantic activation, and regulatory overhead shape behavior in your own tasks.

Limitations (transparent)

• Both packages now deliver a high-fidelity implementation of the integrated MarinaAgent (full substrate with WM/Episodic/Semantic/Procedural, pre-computed retrieval bias, Algorithm 1 regulation with overhead and modulations, rich MCP dispatch). The TypeScript reference remains the gold standard for the most precise paper constants and edge-case biophysical behavior.
• Some advanced classical CA details (full production compilation, extremely rich spreading activation in all scenarios) are implemented at a high practical level but remain areas of ongoing refinement per the CARINA12 plan.
• The full interactive scientific laboratory (Sync to Tabs, advanced visualizations, paper explorer) is available when running from source. The published packages focus on the professional unified core + CLI for easy distribution and experimentation.
• For the absolute latest research-grade numbers from the papers, the TS core (npm) is recommended; Python provides excellent practical parity for most research, teaching, and custom-task work.

Building from Source (Full Web Laboratory)

git clone https://github.com/cristianmi24/Marina.git
cd Marina
npm install
npm run dev          # launches the full web lab
# or
npm run build:core   # only the distributable core

References

• CARINA12_IMPLEMENTATION_PLAN.md and related documents in /papers/
• Dendritic Metacognition (DMA) paper
• Meta-DNA regulatory genome work (BICA)
• IJCAI MCP / CARINA 11 papers

License

MIT (see LICENSE). Research use, contributions, and citations of the CARINA line are welcome.

For the complete interactive lab:

git clone https://github.com/cristianmi24/Marina.git
cd Marina && npm install && npm run dev

Inside the lab you get the beautiful landing, paper explorer, and the powerful "Unified Core" panel with "Run 100-step Integrated Episode" + "Sync to Tabs" that proves everything is one system.

All paths (CLI, Python, JS import ... from "marinaedutlan/core", and the web lab) execute the same MarinaAgent.

---

5. CLI

marina                 # rich integrated UI (the full scientific experience)
marina ui
marina run 120         # headless 120-step episode on the unified core
marina run --steps 50 --json
marina doctor          # health checks (Node, core load, GEMINI key)
marina examples        # paper-aligned scenarios + expected behaviors
marina --help

The CLI (marina, marina run, doctor, examples) is the primary professional entry point for the published package. It is lightweight, fast, and scriptable.

marina run and the Python equivalent exercise the exact same MarinaAgent core that powers the JS API and the (source-only) web lab.

Quick reference

Command	Effect
marina	Full scientific UI + unified core panel
marina run 120	Headless 120-step episode (pretty output)
marina run --steps 50 --json	Machine-readable (pipelines / notebooks)
marina doctor	Health + version + core load checks
marina examples	Paper scenarios + expected behaviors
marina --version / -v	Print version
python -m marinaedutlan.cli --doctor	Same for the pip package

Troubleshooting (common)

• No marina command after npm install -g → restart terminal / check global bin path.
• Core load fails in run → run npm run build && npm run build:core (dev) or reinstall the published package.
• Mirror Test real queries fail → export GEMINI_API_KEY=...
• Want the absolute latest research visuals? Always prefer the npm package + UI.

---

6. API Python

from marina.core import MarinaAgent
# or: from marina import MarinaAgent

agent = MarinaAgent()
for _ in range(200):
    agent.step()                    # or agent.run_episode(200)

summary = agent.get_summary()
state   = agent.get_combined_state()
agent.reset()

See marina/core.py — the public surface (get_summary, evaluate, serialize, create_simple_task, lastRetrievalBias, lastProposedAction, activePathways, etc.) is the supported contract.

---

7. API JavaScript / TypeScript

import { MarinaAgent } from "marinaedutlan/core";

const agent = new MarinaAgent("Planner");
agent.step({ dmaManualRegime: 1 });
const summary = agent.getSummary();
const full    = agent.getCombinedState();
const snap    = agent.serialize();   // epigenetic traces etc.
agent.deserialize(snap);

The published dist/core/MarinaAgent.js is bundled and has no external runtime deps beyond what the simulators need.

---

8. Casos de uso / Use Cases

• Research: Reproduce qualitative claims from the DMA, Meta-DNA (BICA), MCP (IJCAI/CARINA-11), IM-Onto and CMT papers inside one executable system.
• Agent engineering: Add a real metacognitive regulator to LLM wrappers, robotics controllers, or non-stationary bandits.
• Education: Students explore stability-plasticity, gene-regulatory metacognition, and meta-reasoning in one afternoon.
• Ablation & reproducibility: marina run --json + seeds in scripts for Monte-Carlo campaigns.
• Future (1.0+): Epigenetic profiles persisted across sessions, full experiment harness, Mirror Test campaigns against the integrated agent.

---

9. Arquitectura / Architecture

User / Script / Notebook
          │
          ▼
┌─────────────────────────────────────────────────────────────┐
│  Interfaces (all point to the same core)                     │
│  • CLI (bin/marina.js + Python click)                        │
│  • Python: from marina.core import MarinaAgent (or from marina) │
│  • JS:     import { MarinaAgent } from "marinaedutlan/core"         │
│  • Web UI (React + the same TS MarinaAgent + visual layers)  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────┐
│  MarinaAgent  (THE single system heart)                           │
│  • step() / runEpisode() / getSummary() / serialize()             │
│  • Composes three high-fidelity layers from the papers:           │
│     1. DMA (dma_simulator.ts) — HCN, gHCN, tauM, beta, Vb        │
│     2. MetaDNA (meta_dna_simulator.ts) — MoS 5D, TFs, genes,     │
│        pathways, epigenetic χ traces (persistent "development")  │
│     3. MCP (mcp_simulator.ts) — EU, 5 meta-actions, Planner/RAG  │
│  • Early cross-layer modulation already active (p_EpistemicVal   │
│    reduces risk; p_TimeMgmt narrows tauM; DMA delta → MoS u)     │
└──────────────────────────────────────────────────────────────────┘
          ▲ rich signals (load, Δq, confidence, gene E(t), gHCN)
          │
   (future substrate: WM / Episodic with DMA engrams / Procedural)

The old "five independent simulators" are now views. The unified episode runner and Sync to Tabs button make the "one system" concrete.

See:

• src/core/MarinaAgent.ts (reference)
• marina/core.py (Python port)
• Individual *_simulator.ts for exact paper equations.

---

Current status & limitations (0.5 beta)

What you get today (professional quality for research & education):

• One downloadable, scriptable, importable unified core (MarinaAgent) with explicit cross-layer modulation (Meta-DNA pathways → DMA/MCP, MCP decisions → regulator) and a minimal substrate seed (episodic traces carrying DMA snapshots).
• Excellent CLI (marina run, doctor, examples, --json, --save-profile/--load-profile, version) on both npm and pip.
• Rich web lab with integrated episode runner + automatic sync into layer inspectors. The tabs remain high-fidelity independent inspectors for the individual paper models (valuable for scientific debugging).
• High paper fidelity on the three layers + honest substrate start. Both packages now provide high-fidelity implementations of the unified core (Python has full practical parity for substrate, bias, regulation and Task extensibility).

Known limitations (being addressed on the path to 1.0):

• Cognitive substrate is a strong, usable implementation (full WM buffers, Episodic with DMA engrams, Semantic with spreading, Procedural with modulation). Some deeper classical CA details remain per the CARINA-12 plan.
• Cross-layer is now structured (explicit applyMetaDNAModulations + MCP feedback) but still lighter than the full regulatory loops described in the BICA/Meta-DNA and CARINA papers.
• Epigenetic + substrate persistence via serialize/deserialize and new --save-profile / --load-profile in CLI; full "cognitive development dashboard" UX pending.
• No built-in campaign/ablation harness yet (scriptable via --json + the core).
• Python provides a high-fidelity port with the same public API and integrated behavior as the TS reference (see marina/core.py). Use the TS core when you need the most precise paper constants.
• Ontology explorer and Mirror Test (CMT) remain valuable but architecturally separate tools (not yet driven by the unified core).
• Some advanced Mirror Test scenarios require a GEMINI_API_KEY.

We are transparent: 0.5 is the point where a researcher or student can install once and feel they are using a real unified system, not a demo collection.

Paper fidelity notes All numeric constants, update rules, and qualitative behaviors (reversal recovery <10 steps for DMA, pathway co-expression logic for Meta-DNA, EU + 5 meta-actions for MCP) are taken directly from the source papers. The MarinaAgent.step() / runEpisode() loop is the single place where cross-layer modulation happens.

---

10. Contribución / Contributing

We welcome contributions that increase fidelity, cohesion or professional DX:

1. Fork + branch from main.
2. Keep paper constants and algorithm structure intact (DMA HCN kinetics, Meta-DNA Algorithm-1 style, MCP 1-step EU).
3. Add or improve cross-layer effects only when they have a traceable justification in one of the source papers.
4. For UI: new visualizations must be able to consume MarinaAgent.getCombinedState().
5. CLI / packaging changes must keep npm install -g marinaedutlan && marinaedutlan and pip install marinaedutlan working cleanly.
6. Run npm run lint (and Python equivalent) before PR.
7. Update this README and the architecture section when the unified contract changes.

Current status (0.7.0): Proper dual npm + PyPI support with real Python implementation, packaging fixes, and improved parity between platforms. Full cognitive substrate and larger experiment harness remain planned for the path to 1.0.

Repository: https://github.com/cristianmi24/Marina

---

License

MIT

---

Ready to publish as 0.7.0 beta.
The user who does npm install -g marinaedutlan && marina or pip install marinaedutlan now receives a working system on both platforms (with real Python package, not just metadata).

See MARINA_UNIFIED_IMPLEMENTATION_PLAN.md for the longer-term roadmap (Phases 2–5: substrate, persistence, reproducibility harness, 1.0 release criteria).