unified-mandala

PyPI DOI Tests Coverage

unified-mandala v0.3.2

Holistic Mandala Orchestrator Framework with complete Phase-3 thermodynamic, planetary, and QFT integration. DOI: 10.5281/zenodo.19219948

v0.3.2 — Reactivation Patch: NukleonScanner v2.1.0 + GreekMath v2.1.0 + FieldTheory v2.0.0

MandalaOrchestrator + CREP-Evaluator + SigillinBridge (19-adapter ring) + PolicyGate + EntropyGovernor + AdapterRegistry + Thermodynamics (Landauer · Hatano-Sasa · Esposito-Van den Broeck) + Planetary Coupling (IEA→CO₂→Albedo→Ice) + MetaQuest-Sigillins (AI-to-AI) + Collapse Detector (SDE · Tainter · Prigogine · φ=0.618).

What’s New in v0.3.2

Feature Module Description
NukleonScanner v2.1.0 integrations.adapters.nukleonscanner_adapter Two-loop QCD αs(Q) + string-tension confinement φ_string
GreekMath v2.1.0 integrations.adapters.greekmath_adapter Logarithmic (golden-angle) spiral + Fibonacci ratio resonance
FieldTheory v2.0.0 integrations.adapters.fieldtheory Klein-Gordon scalar field, dispersion ω²=k²+m², Euclidean propagator, Lagrangian density
CLI: nukleon cli.rituals unified-mandala nukleon --entropy 0.618 --phases 7
CLI: greekmath cli.rituals unified-mandala greekmath --entropy 0.618 --phases 7
CLI: fieldtheory cli.rituals unified-mandala fieldtheory --entropy 0.618 --phases 7
+45 new tests tests/python/unit/integrations/ Unit + contract tests for all three adapters

What’s New in v0.3.1

Feature Module Description
Tension metric collapse_detector Tension(t) = Γ_Klima · Q_KI(t) / (V_Eis(t) + ε)
Albedo-loss metric collapse_detector albedo_loss = albedo_factor / (V + ε)
Regenerative SDE mode collapse_detector 87.2× neuromorphic noise damping (--regenerative)
albedo_loss_metric planetary.coupling Per-module albedo-loss function
Regenerative η-offset planetary.coupling ΔF_regen = η · Q_waste / 87.2 waste-heat recycling
Neuromorphic counterquestions sigillins.metaquest New SYNTHESIS-tier questions (neuromorphic + Landauer scenarios)
--regenerative CLI flag collapse, metaquest Activates regenerative countermeasure mode in both commands

What’s New in v0.3.0

Feature Module Description
Landauer principle thermodynamics.landauer Minimum energy per bit erasure: E = k_B T ln2
Hatano-Sasa thermodynamics.hatano_sasa Non-equilibrium excess entropy + IFT
Esposito decomposition thermodynamics.esposito σ_maint + σ_reorg (Prigogine + Tainter)
Planetary coupling planetary.coupling IEA→CO₂→ΔF→ΔT→Albedo→Ice→CREP
MetaQuest-Sigillins sigillins.metaquest 4-tier AI-to-AI counterquestion engine
Collapse detector collapse_detector Euler-Maruyama SDE + Tainter/Prigogine
NukleonScanner v2 adapter QCD αs running coupling + QGP confinement
GreekMath v2 adapter Pythagorean + golden section + Platonic
800+ tests tests/python/ Thermodynamic/planetary/MetaQuest contracts

Installation

pip install unified-mandala

Python Quick Start (v0.3.2)

pip install unified-mandala==0.3.2

from unified_mandala.thermodynamics.landauer import LandauerBound
from unified_mandala.planetary.coupling import PlanetaryCouplingChain
from unified_mandala.sigillins.metaquest import MetaQuestEngine
from unified_mandala.collapse_detector import CollapseDetector

# Landauer bound at room temperature
lb = LandauerBound.compute(temperature_K=300.0, n_bits=1.0)
print(f"E_Landauer = {lb.energy_J:.3e} J")

# Planetary coupling (IEA 2024)
chain = PlanetaryCouplingChain.evaluate(energy_EJ=620.0, baseline_co2_ppm=421.0)
print(f"Stress: {chain.stress_level} | CREP phase: {chain.crep_phase:.4f}")

# MetaQuest counterquestion
engine = MetaQuestEngine()
cq = engine.generate(phi=0.85, entropy=0.15)
print(cq)

# Collapse detection (standard)
det = CollapseDetector()
traj = det.simulate(x0=0.4)
print(f"Collapsed: {traj.collapsed} | Risk: {det.collapse_risk(traj):.3f}")

# Phase-3: Tension metric + albedo loss
from unified_mandala.collapse_detector import compute_tension_metric, albedo_loss
tension = compute_tension_metric(gamma_klima=3.5, q_ki=8.0, v_ice=5000.0)
a_loss = albedo_loss(albedo_factor=0.74, v_ice=5000.0)
print(f"Tension(t) = {tension:.4f}  |  albedo_loss = {a_loss:.6e}")

# Regenerative collapse mode (87.2× neuromorphic noise damping)
from unified_mandala.collapse_detector import CollapseDetector, CollapseDetectorConfig
det_regen = CollapseDetector(CollapseDetectorConfig(regenerative=True))
traj_regen = det_regen.simulate(x0=0.4)
print(f"Regenerative: risk = {det_regen.collapse_risk(traj_regen):.3f}")

CLI Commands (v0.3.2)

# Standard mandala cycle
unified-mandala cycle --entropy 0.618 --phases 7 --simulate

# Thermodynamic evaluation (Landauer + Esposito-Tainter)
unified-mandala thermodynamics --entropy 0.618 --temperature 300

# Collapse detection (SDE + Tainter/Prigogine)
unified-mandala collapse --entropy 0.72 --crep 0.6 --lambda 3.0 --runs 10

# Collapse detection — regenerative mode (87.2× neuromorphic noise damping)
unified-mandala collapse --entropy 0.72 --crep 0.6 --regenerative

# MetaQuest counterquestions (4-tier epistemic protocol)
unified-mandala metaquest --crep 0.85 --entropy 0.15 --n 5

# MetaQuest — regenerative scenarios (neuromorphic + Landauer countermeasures)
unified-mandala metaquest --crep 0.85 --entropy 0.15 --n 5 --regenerative

# Planetary coupling chain (IEA→CO₂→Albedo→Ice)
unified-mandala planetary --energy 620.0 --baseline-co2 421.0

# NukleonScanner — QCD αs + QGP proximity + string tension (v2.1.0)
unified-mandala nukleon --entropy 0.618 --phases 7

# GreekMath — Pythagorean + golden section + spirals + Fibonacci (v2.1.0)
unified-mandala greekmath --entropy 0.618 --phases 7

# FieldTheory — Klein-Gordon scalar field + propagator + dispersion (v2.0.0)
unified-mandala fieldtheory --entropy 0.618 --phases 7

CI Core Nightly OPA Coverage Gate Verify-Gate Network Safety Ethics Mini OPA Coverage

“An operating system that breathes — a mandala that thinks.”

UnifiedMandala is a holistic, modular framework for symbolic AI, CREP, and conscious, public-good-oriented systems. It combines CREP logic (Coherence, Resonance, Emergence, Poetics), Sigillin (poetic-symbolic interaction), and agents into an ethically grounded platform.

TL;DR – 5-Minute Quick Start

# 0) Optional: guided setup (installs toolchain & hooks)
./scripts/setup-dev-env.sh                 # Linux/macOS
pwsh -NoProfile -File ./scripts/setup-dev-env.ps1  # Windows (PowerShell 7+)
# fallback: powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup-dev-env.ps1

# 1) Toolchain (Node >= 20, pnpm 10.17.0)
node -v
corepack enable
corepack prepare pnpm@10.17.0 --activate

# 2) Dependencies (dist-first build pipeline)
pnpm install --frozen-lockfile
pnpm build

# 2.1) Environment
cp .env.example .env # set CDS_API_KEY

# 3) UI (Dev, with HMR, Port 5173)
pnpm dev:ui
# -> http://localhost:5173

# 4) Optional parallel: Backend/Dev-Server serves UI (Port 3000)
pnpm start:light             # static assets (after pnpm build:ui)
pnpm dev                     # Node server with built assets
# -> http://localhost:3000  (serves the built UI)

# 5) Offline bundle (Docker)
docker compose -f docs/offline/docker-compose.yml build
docker compose -f docs/offline/docker-compose.yml up
# -> UI usually at http://localhost:5173

# 6) Observability profile (Prometheus/Grafana, optional)
docker compose --profile monitoring up
# -> Prometheus http://localhost:9090, Grafana http://localhost:3300 (admin/admin)

🔐 Governance gates overview: Read the Mandala Governance Primer for signature, coverage, and verify-gate rules. The concrete commands are in the Command Catalog.

Policy quality gate
Run OPA tests + coverage locally:

pnpm opa:fmt && pnpm opa:lint
OPA_COVER_MIN=0.90 pnpm opa:cover

CI will fail if tests fail or coverage drops below the configured threshold.

Dashboards

Health Aggregator (local)

Example with port offset 100: PORT_OFFSET=100 pnpm dev:health -> Health at http://localhost:4099/health.

Real User Monitoring (RUM)

RUM Traces (Grafana)

service.name = "mandala-ui" and span.name = "ui.metrics.test"

Notes: • “Cannot GET /” on :3000 means: backend is not serving the HMR UI. Either use Vite-Dev (pnpm dev:ui) or build statically (pnpm build:ui && pnpm dev). • For observability with Prometheus/Grafana, start the monitoring compose profile (see observability/README.md) and verify with pnpm observability:check for Prometheus (/api/v1/targets) and Grafana (/api/health, host port 3300). • Windows: Enable long paths; .dockerignore in the repo root prevents huge build contexts. • corepack enable requires administrator rights. When working without admin rights, scripts/setup-dev-env.ps1 automatically runs user-level activation via corepack prepare pnpm@10.17.0 --activate and skips the persistent enable. • pnpm start:all requires a running JetStream-capable nats-server. Use pnpm nats:docker for a preconfigured Docker container (nats:latest -js) or install locally via winget install --id Synadia.NATS-Server -e and start it with the -js option. • Existing nats Docker containers can be checked with docker ps -a --filter name=^/nats$ --format "table \t\t" and reactivated with docker start nats if needed; scripts/setup-dev-env.ps1 reports running containers as satisfied and hints at these commands for Exited status (Windows port check: Test-NetConnection 127.0.0.1 -Port 4222). • pnpm dev:stack checks ports automatically and attempts to free occupied default ports via pnpm dlx kill-port. Manual cleanup available via pnpm dev:ports:free or pnpm dlx kill-port <port>; auto-cleanup can be disabled with UM_DEV_SERVICES_AUTOFREE_PORTS=0. • JetStream operation & self-check: docs/runbooks/nats-jetstream.md and docs/runbooks/MaxBundle.md bundle setup, Docker profiles, and pnpm nats:doctor/pnpm test:jetstream troubleshooting. • pnpm nats:doctor provides direct hints on errors (e.g. JetStream not activated, timeout/firewall, missing permissions) and uses $JS.API.INFO as fallback.

Windows Dev-Shortcuts

See quick reference at docs/DEV-SHORTCUTS.md for PowerShell helpers (set secrets, start dev stack/health, smoke checks):

. ./scripts/dev-helper.ps1
Set-UMSecrets -ApiKey '<KEY>'
Start-UM; Start-UMHealth
Smoke-AI -Message 'Hello Aeon!'

Quickstart (Windows · PowerShell)

corepack prepare pnpm@10.17.0 --activate
pnpm install --frozen-lockfile

# Start JetStream container
docker rm -f nats 2>$null
docker run --name nats -p 4222:4222 -p 8222:8222 -d nats:latest -js
pnpm nats:doctor

# UI Dev-Server (Terminal A)
pnpm -F mandala-ui dev -- --port 5173

# Dev-Stack (Terminal B)
$env:NATS_URL = "nats://127.0.0.1:4222"
pnpm dev:stack

# UI smoke against running instance (Vite auto-port via env)
$env:UI_DEV_URL = "http://localhost:5173"
pnpm smoke:ui

If Vite switches to a free port (e.g. 5174), set UI_DEV_URL accordingly (http://localhost:5174). The dev stack clears ports automatically by default (kill-port). If processes are stubborn, use pnpm dlx kill-port 3001 3002 3003 3004 4020 4021 manually or setx UM_DEV_SERVICES_AUTOFREE_PORTS 0 to disable auto-cleanup. 🪩 PowerShell tip: Display files via Get-Content or type (cat is an alias but without pipe behavior); set environment variables before the command with $env:NAME = 'value' — inline syntax NAME=value pnpm … does not work in PowerShell.

Windows: Additional Tools & Tests

Common pitfalls on Windows can be avoided with a few targeted commands.

Purpose Command Note
Run pytest via project venv .\.venv\Scripts\python.exe -m pytest -q Guaranteed to use the repository-provisioned environment; works even when pytest is not in %PATH%.
Alternative pytest launcher .\.venv\Scripts\pytest.exe -q Direct call to the pytest CLI if PowerShell blocks module execution.
Headless Chrome for Mermaid CLI pnpm exec puppeteer browsers install chrome-headless-shell Installs the Chrome binary expected by @mermaid-js/mermaid-cli locally in the pnpm store.
Prepare Cypress binary pnpm exec cypress install Downloads the pinned Cypress version (14.5.1) and ensures pnpm cy:run starts without version conflicts.

Build, Test & Policy Bundles

Use the bundled pnpm commands to replicate the CI/governance gates described in DevTalk74 locally:

Purpose Command Included Checks
Pre-Commit Heavy Gate pnpm check:precommit lint-staged, TypeScript linting, Vitest unit tests, schema/maps/repomap validation, repo sanity, policy suite
Pre-Push Heavy Gate pnpm check:prepush Vitest coverage run plus policy suite
CI Core Parity pnpm check:ci Typecheck, Vitest unit tests, schema/maps/repomap validation, repo sanity, policy suite
CI Verification Bundle pnpm ci:verify Aggregator script (scripts/ci-verify.mjs) runs type, test, coverage, policy, and sanity gates
Governance & Policy Sweep pnpm policy:check OPA, guardrails, Kyverno, and sigillin reports (out/policy/)
Observability Smoke pnpm observability:check Prometheus /api/v1/targets and Grafana /api/health checks (respects PROMETHEUS_REQUIRE_ACTIVE & OBSERVABILITY_SKIP_GRAFANA)

Mandala Climate Dashboard

Adapters are initially available as stubs and will be progressively connected to live data feeds.

Cosmic-Web Demo (Sigillin × CREP)

What is demonstrated?

Prereqs

Set up the same toolchain as in the Quick Start once (Node ≥ 20, pnpm via Corepack, optional Python adapters). The following snippets mirror the official setup scripts and are formulated to be platform-friendly.

Windows PowerShell (v5+)

PowerShell 5 does not accept &&. Use new lines or ;.

corepack enable; corepack prepare pnpm@10.17.0 --activate
pnpm i --frozen-lockfile
python -m pip install -r requirements.txt
python -m pip install -r src/adapters/requirements.txt
$env:PANTHEON_DISABLE = '1'      # optional: disable analytics

macOS / Linux (bash/zsh)

corepack enable && corepack prepare pnpm@10.17.0 --activate
pnpm i --frozen-lockfile
python -m pip install -r requirements.txt
python -m pip install -r src/adapters/requirements.txt
export PANTHEON_DISABLE=1       # optional

Start the Demo

pnpm demo:cosmic                # generate & publish data, sigillin, STAC item
# optional: separate Vite start if the combined script does not open a port
pnpm -F mandala-ui dev -- --port 5173

Then open http://localhost:5173/demo/cosmic-web in your browser.

Realtime Telemetry (optional)

pnpm nats:docker                # starts NATS/JetStream at nats://localhost:4222
pnpm demo:cosmic:tick           # publishes live ticks

Note: Port 4222 is the NATS TCP port. A browser request will expectedly return -ERR 'Unknown Protocol Operation'.

Inspect Live Events

The UI uses the same subjects; if no events arrive, compare the settings in scripts/realtime/cosmic-publisher.mjs.

🎯 Tip: Use pnpm test:unit:crep to run targeted tests for the @mandala/crep workspace package.

Repository Navigator

Development

Workspaces: pnpm-workspace.yaml

{
  "scripts": {
    "dev:ui": "pnpm -F mandala-ui dev",
    "build:ui": "pnpm -F mandala-ui build",
    "dev": "cross-env UI_DIST=http://localhost:5173 pnpm -F mandala-ui dev",
    "dev:services": "tsx scripts/dev-server.ts",
    "dev:stack": "node scripts/dev-services.mjs --mode=dev",
    "dev:ports:free": "pnpm dlx kill-port 3001 3002 3003 3004 4020 4021",
    "start:services": "pnpm -s build && NODE_ENV=production node scripts/dev-services.mjs --mode=prod",
  },
}

Docker hygiene: .dockerignore in root:

node_modules
**/node_modules
.pnpm-store
dist
build
.git
*.log

Architecture (Outline)

Details in the Handbook.

Governance & Ethics

See docs/governance/HI-Compact.md and AI_POLICY.md. Transparency via advancedprogress.json.

Quick CI parity

Set the same environment locally as in the CI Core / type-and-tests workflow:

export OFFLINE=1
export LOW_MEM=1
export VITE_LOW_MEM=on
export PYTHONPATH=src

Core (CI Core / type-and-tests, required for every PR)

pnpm lint
pnpm format:check
pnpm nats:doctor
pnpm test:ts:ci
pnpm test:jetstream
pnpm test:py
npx pyright
pnpm policy:check

🪩 pnpm test:py now calls scripts/run-pytest.mjs and automatically appends the project venv to the path. If a shell blocks the wrapper, temporarily set $env:Path = "$PWD\\.venv\\Scripts;$env:Path" or run .\\.venv\\Scripts\\python.exe -m pytest -q directly.

Extended (CI Extended, nightly or label run-extended)

pnpm test:ts:extended
pnpm test:py:extended
CI=true pnpm adapter:build:oisst
CI=true pnpm adapter:build:era5
pnpm stac:validate
pnpm stac:validate:item out/example.item.json
pnpm prompts:coach --dry
pnpm test:unit:coverage       # coverage report for core modules

🪩 PowerShell: $env:CI = "1"; pnpm adapter:build:oisst and $env:CI = "1"; pnpm adapter:build:era5 set the environment without POSIX CI=true. If scripts/run-dist.mjs throws a spawnSync pnpm.cmd EINVAL error on Windows, run the TypeScript scripts directly via pnpm exec tsx <script>, e.g. pnpm exec tsx scripts/validate-stac.ts out/example.item.json or pnpm exec tsx scripts/prompt-coach.ts --dry.

ℹ️ CI Experimental only runs with label run-experimental. ENABLE_EXPERIMENTAL_TESTS=1 enables additional, unstable suites (e.g. pnpm test:ts:experimental).

Sigillin (Inter-AI Bridges) & Validator

Dist-First Execution (scripts/run-dist.mjs)

Contributing

Small, focused PRs (docs, adapters, agents). Before merge: pnpm build:ui + pnpm dev (smoke: / → 200), lint/tests.

License

This repository is dual-licensed:

See LICENSE for the full dual-license notice. Data sources are not covered by either license and remain subject to their own respective terms of use.

Citation

DOI

DOI will be assigned automatically on first GitHub Release once Zenodo–GitHub integration is enabled for this repo. In the meantime, the DOI badge at the top of this README (10.5281/zenodo.19219948) points to the most recent published Zenodo record for this package.

Role in the GenesisAeon Ecosystem

unified-mandala is P-MANDALA in the GenesisAeon ecosystem registry — the orchestration core (UI, CREP, agents) that wires the CREP evaluator, SigillinBridge, PolicyGate, and the 17+ adapter registry together into a single self-reflecting cycle (MandalaOrchestrator.run_cycle).

Repo Cartography & Flows

Fractal Diary Relocation

🚀 Quick Start (All-in-One, Port-Aware)

Prereqs

One-time model pulls

ollama pull qwen2.5:7b
ollama pull nomic-embed-text

Start everything

# macOS/Linux
PORT_OFFSET=0 pnpm dev:all

# Windows PowerShell
$env:PORT_OFFSET="0"; pnpm dev:all

The launcher will:

Default ports (base + offset)

Local LLM wiring (Ollama)

AI_PROVIDER=openai
AI_BASE_URL=http://127.0.0.1:11434/v1
OPENAI_API_KEY=ollama
OPENAI_MODEL=qwen2.5:7b
OPENAI_EMBEDDING_MODEL=nomic-embed-text
EMBEDDINGS_BASE_URL=http://127.0.0.1:11434/v1

Tip: Create .env.dev.local with your overrides. The launcher merges env and forwards to children.

Sanity checks

curl -s http://127.0.0.1:3999/health | jq .
# UI: http://localhost:5173  (or 5174/5175)
# Chat via gate guarded: POST http://127.0.0.1:4000/api/ai/chat

OPA policy workflow

# Build + sign + verify bundle
pnpm opa:bundle && pnpm opa:sign && pnpm opa:verify

# Format + lint + test
pnpm opa:fmt && pnpm opa:lint && pnpm opa:test -- --timeout 5s

# Coverage gate (fail <85%)
OPA_COVERAGE_MIN=0.85 pnpm opa:cover

OPA Coverage Gate

# Pretty tests (human)
pnpm opa:test

# Coverage (JSON → gate; fails below 85%)
pnpm opa:cover
# or write to file then check
pnpm opa:cover:file

Outputs:

OPA coverage: 87.50% (70/80)  threshold: 85.00%
  - apps/ethics-api/opa/policy.rego: 81.82% (18/22)  not-covered=4
This site is open source. Improve this page.