GitHub - DaScient/prompt-atlas-ecl: Prototype repo exploring Entangled Co-Learning (ECL) between two LLMs—a Writer and a Tester—linked by a shared latent and evolving state. Inspired by The Prompt Atlas by Don D. M. Tadaya, it treats AI as a co-author rather than a tool, blending technical rigor with philosophical curiosity.

 ██████╗ ██████╗  ██████╗ ███╗   ███╗██████╗ ████████╗     █████╗ ████████╗██╗      █████╗ ███████╗
 ██╔══██╗██╔══██╗██╔═══██╗████╗ ████║██╔══██╗╚══██╔══╝    ██╔══██╗╚══██╔══╝██║     ██╔══██╗██╔════╝
 ██████╔╝██████╔╝██║   ██║██╔████╔██║██████╔╝   ██║       ███████║   ██║   ██║     ███████║███████╗
 ██╔═══╝ ██╔══██╗██║   ██║██║╚██╔╝██║██╔═══╝    ██║       ██╔══██║   ██║   ██║     ██╔══██║╚════██║
 ██║     ██║  ██║╚██████╔╝██║ ╚═╝ ██║██║        ██║       ██║  ██║   ██║   ███████╗██║  ██║███████║
 ╚═╝     ╚═╝  ╚═╝ ╚═════╝ ╚═╝     ╚═╝╚═╝        ╚═╝       ╚═╝  ╚═╝   ╚═╝   ╚══════╝╚═╝  ╚═╝╚══════╝

✦ Entanglement Co-Learning Engine ✦

Where models learn to co-think, not just co-exist.

"The moment two systems share uncertainty -- and begin to co-create understanding -- that is entanglement."

         ╔══════════════════════════════════════════════════════╗
         ║                                                      ║
         ║   A live research platform unifying Generative AI    ║
         ║   and Quantum-Inspired Information Theory through    ║
         ║   an evolving API layer and an Entanglement          ║
         ║   Co-Learning (ECL) core -- a minimal but expressive ║
         ║   architecture for training, reasoning, and          ║
         ║   experimentation across domains that span science,  ║
         ║   psychology, myth, biology, ethics, and beyond.     ║
         ║                                                      ║
         ╚══════════════════════════════════════════════════════╝

🌌 The Vision

Prompt Atlas Engine is not a product -- it's a living research instrument. It sits at the intersection of:

🧬 Quantum-Inspired Co-Learning -- Two latent streams share a GRU-based EntanglementBus, evolving a shared state that neither agent owns alone.
🪞 Archetypal Psychology meets AI -- An interactive reflection engine that maps your words to Jungian archetypes.
🌿 Biological Simulation -- Lotka-Volterra predator-prey dynamics, genetic evolution, coral-algae symbiosis, and pandemic branching -- all running in real-time.
🌈 Hyperspectral Visualization -- Publication-grade interactive 3D manifold explorations of high-dimensional coherence data.
🧪 Bioethics & Design Philosophy -- Frameworks for AI-guided responsible creation in a post-Darwinian epoch.
🌀 Cosmic Information Economies -- Exploring information as the universe's fundamental currency.

Every module in this repository is both a runnable system and a philosophical proposition.

📖 The Prompt Atlas — Kronos Edition is now bundled with this repository. Read the canonical text in PROMPT_ATLAS.md, the companion expansions, manifest, glossary, prompt library, diagrams, and appendices in docs/prompt-atlas/.

🗺️ Table of Contents

Click to navigate

	Section	Description
🏗️	Architecture	The complete system map
🚀	Quickstart	Get running in 60 seconds
🌐	API Reference	All endpoints documented
🧩	Key Concepts	ECL vocabulary
🪞	Soul's Mirror	Archetypal reflection engine
🧬	Biology & Beyond	Living simulations
🌈	Hyperspectral	High-dimensional visualization
🧪	Bio Design Ethics	Responsible creation frameworks
🌀	Cosmic Economies	Information as currency
📡	Tech Stack	Full technology map
⚙️	Configuration	Environment & settings
📈	Roadmap	What's coming next
🤝	Contributing	How to join
📜	Citation	How to cite
🜂	Ethos	The philosophy

🏗️ Architecture -- The Living Map

                              ┌──────────────────────────────────────────┐
                              │          🌌 PROMPT ATLAS ENGINE          │
                              │       Entanglement Co-Learning (ECL)     │
                              └──────────────┬───────────────────────────┘
                                             │
                    ┌────────────────────────┼────────────────────────┐
                    │                        │                        │
           ┌───────▼───────┐       ┌────────▼────────┐     ┌────────▼────────┐
           │   🧠 ECL CORE  │       │  🌐 API LAYER   │     │  📦 MODULES     │
           │   (PyTorch)    │       │  (FastAPI)       │     │  (Extensions)   │
           └───────┬───────┘       └────────┬────────┘     └────────┬────────┘
                   │                        │                        │
        ┌──────────┼──────────┐    ┌────────┼────────┐    ┌─────────┼─────────┐
        │          │          │    │        │        │    │         │         │
   ┌────▼──┐ ┌────▼──┐ ┌─────▼┐  ┌▼──┐  ┌──▼─┐ ┌───▼┐  ┌▼──┐   ┌──▼─┐  ┌───▼──┐
   │Models │ │Losses │ │State │  │Run│  │Step│ │Trc │  │🪞  │  │🧬   │   │🌈    │
   │       │ │       │ │ Bus  │  │   │  │    │ │    │  │Mir│   │Bio │  │Hypr  │
   └───────┘ └───────┘ └──────┘  └───┘  └────┘ └───-┘  │ror│   │Life│  │Spec  │
                                                       └───┘   └────┘  └──────┘
        Summarizer    InfoNCE    GRU        /runs   /step  /trace
        LatentHead    KL-sym     h(t)       /packs  /price /health
                                                        │         │         │
                                                   ┌────▼──┐ ┌────▼──┐ ┌───▼───┐
                                                   │🧪      │ │🌀     │ │ 📝    │
                                                   │Ethics │ │Cosmic │ │Prompts│
                                                   └───────┘ └───────┘ └───────┘

📂 Full Directory Structure

prompt-atlas-ecl/
│
├── 🧠 src/                           # Entanglement Learning Core
│   ├── train_ecl.py                  # Main training loop (GRU + InfoNCE)
│   ├── models.py                     # Summarizer, LatentHead (VAE heads)
│   ├── state_bus.py                  # EntanglementBus -- GRU shared state
│   ├── losses.py                     # InfoNCE contrastive + symmetric KL
│   └── executor.py                   # Spec/tests compliance validator
│
├── 🌐 server/                        # FastAPI Orchestration Layer
│   ├── app.py                        # Runs, auth, rate limits, CORS, Stripe
│   └── core_bridge.py                # Torch-to-API bridge (E-Star computation)
│
├── ⚙️ configs/                       # Model & Runtime Configuration
│   ├── ecl_llm_llm.yaml             # Hyperparams, loss weights, device
│   └── schemas/                      # JSON Schemas (brief, spec, tests)
│
├── 📝 prompts/                       # Prompt Orchestration
│   ├── seed_prompts_atlas.md         # Domain-crossing seed questions
│   ├── system_writer.txt             # Writer (W) role system prompt
│   └── system_tester.txt             # Tester (T) role system prompt
│
├── 🪞 ai_as_souls_mirror/            # Psychology x AI Reflection Module
│   ├── reflection_engine.py          # Archetype scorer + sentiment analysis
│   ├── mirror_experience.py          # FastAPI app + interactive interface
│   ├── archetypes.json               # 6 Jungian archetypes with colors
│   ├── manifesto.md                  # Essay: AI as psychological mirror
│   ├── static/                       # CSS, JS, media assets
│   └── tests/                        # Reflection engine test suite
│
├── 🧬 biology_life_and_beyond/       # Evolutionary & Ecological Simulation
│   ├── simulation_engine.py          # Lotka-Volterra, GA, coral, pandemic
│   ├── biology_app.py                # FastAPI with 4 simulation endpoints
│   ├── content/                      # Essays and prompts
│   └── static/                       # Zero-CDN interactive frontend
│
├── 🌈 hyperspectral_visuals/         # High-Dimensional Visualization
│   ├── hyperspectral_atlas_*.py      # 3 visualization generators
│   ├── *.html                        # Pre-generated interactive explorations
│   └── README.md                     # Scientific context + controls
│
├── 🧪 bio_design_ethics/             # Responsible AI + Biology Framework
│   ├── README.md                     # "Library of Nature" thesis
│   └── manifesto.md                  # Philosophical framework
│
├── 🌀 cosmic_information_economies/  # Information Theory as Currency
│   ├── app.py + engine.py            # FastAPI + computation core
│   ├── essays/                       # Narratives & case studies
│   ├── static/                       # Interactive frontend
│   └── tests/                        # Engine test suite
│
├── 🔧 scripts/                       # Utility Scripts
│   ├── prepare_data.py               # Toy training data generator
│   └── run_train.sh                  # Training launcher
│
├── 🗄️ infra/                         # Infrastructure & Deployment
│   └── schema.sql                    # Postgres schema (users)
│
├── 📚 docs/                          # Documentation & System Maps
│   └── Atlas_System_Map/             # Ethos manifest + system outline
│
├── CITATION.cff                      # How to cite this work
├── LICENSE                           # Apache 2.0
├── atlas_respect.md                  # Attribution framework
├── .env.example                      # Environment configuration template
└── requirements.txt                  # Core dependencies

🚀 Quickstart -- From Zero to Entangled

Step 1: Clone & Install

git clone https://github.com/dascient/prompt-atlas-ecl.git
cd prompt-atlas-ecl

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate        # Linux / macOS
# venv\Scripts\activate          # Windows

# Install dependencies
pip install -r requirements.txt

Step 2: Run the Entanglement Training Loop

python -m src.train_ecl

This initializes the EntanglementBus (GRU), generates synthetic embedding pairs, and trains with InfoNCE loss to balance divergence and coherence. Watch as E-Star (the entanglement coherence metric) evolves over 1000 steps.

Step 3: Launch the API Server

uvicorn server.app:app --reload --port 8000

Verify it's alive:

curl http://127.0.0.1:8000/health
# {"ok": true, "version": "0.2.0"}

Step 4: Create Your First Entanglement Run

# Create a run
curl -X POST http://127.0.0.1:8000/runs \
  -H "X-API-Key: demo-free-key" \
  -H "content-type: application/json" \
  -d '{"brief": {"goal": "Entangle a spec and tests loop"}}'
# {"run_id": "abc123-xyz"}

# Advance the state
curl -X POST http://127.0.0.1:8000/runs/abc123-xyz/step \
  -H "X-API-Key: demo-free-key"

# Retrieve the full trace
curl http://127.0.0.1:8000/runs/abc123-xyz/trace \
  -H "X-API-Key: demo-free-key"

📋 Example Response -- A Living Trace

{
  "t": 5,
  "e_star": 1.73,
  "spec": {
    "assumptions": ["models co-learn via shared state"],
    "steps": ["writer: draft spec", "tester: draft tests"],
    "acceptance": ["spec+tests present", "E-Star reported"]
  },
  "state_snapshot": [0.12, 0.05, 0.08, -0.03, 0.21]
}

Every step records the co-evolving state: the E-Star metric, the spec/tests negotiation, and the raw latent state vector -- a living trace of two systems learning to think together.

Step 5: Explore the Extension Modules

# Launch the Soul's Mirror (Psychology x AI)
cd ai_as_souls_mirror && pip install -r requirements.txt
uvicorn mirror_experience:app --reload --port 8001

# Launch Biology Simulations
cd biology_life_and_beyond && pip install -r requirements.txt
uvicorn biology_app:app --reload --port 8002

# Launch Cosmic Information Economies
cd cosmic_information_economies && pip install -r requirements.txt
uvicorn app:app --reload --port 8003

# Generate Hyperspectral Visualizations
cd hyperspectral_visuals
python hyperspectral_atlas_performance.py
# Opens interactive 3D exploration in your browser

🛰️ Phase 1 -- Distributed Orchestration (MACP + Vector Memory)

The ECL core ships with a lightweight Multi-Agent Communication Protocol and a long-term vector memory layer so that Writer / Tester / Ethics / Latent agents can be distributed across processes (or hosts / accelerators) and share state asynchronously.

Both layers are designed with a strict data-sovereignty stance: they default to in-process fallbacks and only reach for external services (NATS, Qdrant) when you explicitly point at them.

MACP -- the Entanglement Bus

Transport: NATS + JetStream when nats-py is installed and reachable; an in-memory loopback otherwise.
Subject convention: macp.<run_id>.<source_role>.<event_kind> (JetStream-friendly for replay/persistence).
Strict, schema-versioned message contracts via Pydantic (EntanglementEvent).
Minimal Agent base class makes it trivial to add Writer / Tester / Ethics agents.

import asyncio
from src.macp import (
    Agent, AgentRole, EntanglementBusBroker, EntanglementEvent, EventKind,
)

class Writer(Agent):
    role = AgentRole.WRITER
    subscribe_kind = EventKind.RUN_STARTED.value

    async def on_event(self, event):
        await self.emit(EventKind.SPEC_PROPOSED, {"spec": {"goal": event.payload["goal"]}})

async def main():
    # nats_servers=["nats://localhost:4222"] for distributed mode
    broker = EntanglementBusBroker()
    async with broker:
        w = Writer(broker, run_id="run-1"); await w.start()
        await broker.publish(EntanglementEvent(
            run_id="run-1", kind=EventKind.RUN_STARTED,
            source=AgentRole.ORCHESTRATOR, payload={"goal": "design API"},
        ))
        await asyncio.sleep(0.1)

asyncio.run(main())

Vector Memory -- Long-Term Co-Learning Recall

CoLearningMemoryStore persists (state vector, spec, tests, E*) tuples so future runs can retrieve what you tried before and condition new co-learning on it.

Backend: Qdrant (cosine distance, payload filtering) when qdrant-client + a Qdrant URL are configured; pure-Python in-memory backend otherwise.
Enable from the API by setting PAE_MEMORY=1 (and optionally QDRANT_URL, QDRANT_API_KEY); every /runs/{id}/step will then be persisted automatically.

from src.vectorstore import CoLearningMemoryStore

store = CoLearningMemoryStore(qdrant_url="http://localhost:6333")  # or omit for fallback
store.remember(run_id="run-1", vector=[0.1] * 64, e_star=1.7,
               spec={"goal": "..."}, tests=[], tags=["api", "phase1"])
for score, point in store.recall([0.1] * 64, limit=5):
    print(score, point.payload.run_id, point.payload.e_star)

Bring Up the Phase-1 Infrastructure

# Optional: install the distributed extras.
pip install nats-py qdrant-client

# Start NATS (JetStream) + Qdrant locally.
docker compose -f infra/docker-compose.yml up -d
# NATS:   nats://localhost:4222   (monitoring on :8222)
# Qdrant: http://localhost:6333   (dashboard at /dashboard)

# End-to-end roundtrip smoke test (uses fallbacks if services aren't running).
python -m scripts.macp_smoke

# Run the new unit tests.
pytest tests/ -q

To run the API server with persistent memory enabled:

PAE_MEMORY=1 QDRANT_URL=http://localhost:6333 \
  uvicorn server.app:app --reload --port 8000

🔬 Phase 2 -- Loss Geometry, Formal Verification, Experiment Tracking

Phase 2 adds the scientific instrumentation that lets ECL's co-learning be both more rigorous and more observable:

Distribution-geometry losses (`src/losses_geom.py`)

The earlier training loop only had a per-sample contrastive signal (InfoNCE). Phase 2 adds two batch-level distributional terms:

Sinkhorn-regularized Wasserstein-2 — entropy-regularized optimal transport between Writer and Tester latent batches, computed in log-space for stability and fully differentiable.
Multi-bandwidth Gaussian MMD² — kernel-mean-discrepancy estimator (Gretton et al. 2012) using a sum of RBF kernels so it's sensitive across scales.
Real kl_sym — moment-matched Gaussian symmetric KL replaces the previous return torch.tensor(0.0) stub.

All three are weight-gated in configs/ecl_llm_llm.yaml (loss_weights.wass, loss_weights.mmd); set to 0.0 to recover Phase 1 behavior.

Symbolic Tester (`src/testers/z3_tester.py`)

The Phase 1 tester was a hand-rolled field counter. Phase 2 promotes it to a structural verifier with the same optional-dependency contract used in Phase 1:

When the optional z3-solver package is installed, the Tester builds a Z3 model over required-field predicates plus a test-coverage constraint and asks the solver whether the spec is satisfiable.
Otherwise an equivalent pure-Python checker runs. Both paths return the same VerificationReport, and src.executor.soft_violation keeps its ndarray API so existing callers are unaffected.

from src.testers import verify_spec
report = verify_spec(spec_dict, tests_list)
report.satisfied, report.missing_fields, report.backend  # → bool, [...], "z3" or "python"

MLflow experiment tracking (`src/tracking/MLflowTracker`)

Training and the API can now stream params/metrics to MLflow:

Set PAE_TRACKING=1 (or tracking.enabled: true in the config) to turn it on.
MLFLOW_TRACKING_URI is honored for remote tracking; default is MLflow's local file store.
If mlflow isn't installed, every call becomes a silent no-op — exactly the same pattern as the NATS / Qdrant fallbacks from Phase 1.

pip install mlflow             # optional
PAE_TRACKING=1 python -m src.train_ecl

🗄️ Phase 3 -- Persistent Runs & Live Trace Streaming

Phase 3 hardens the API layer so runs survive process restarts and clients can watch a run unfold in real time.

`RunStore` -- pluggable persistence (`src/runstore/`)

The API used to keep all run state in a process-global dict. That works for local demos but loses everything on restart and can't be shared across worker processes. Phase 3 introduces a small RunStore protocol with two implementations, following the same optional-dependency contract as Phases 1–2:

InMemoryRunStore -- threadsafe dict-backed default; behaviorally identical to the old RUNS global.
SQLRunStore -- SQLAlchemy-backed; activates when PAE_DATABASE_URL is set (sqlite, Postgres, MySQL, ...). Falls back gracefully to in-memory if SQLAlchemy isn't installed or the URL fails to open.

# Local file-backed sqlite (zero setup):
PAE_DATABASE_URL=sqlite:///./pae_runs.db uvicorn server.app:app --reload

# Postgres in production:
PAE_DATABASE_URL=postgresql+psycopg://user:pass@db:5432/pae uvicorn server.app:app

Schema is intentionally minimal -- pae_runs (one row per run with brief/config/state JSON) and pae_run_steps (append-only trace keyed by (run_id, t)) -- so migrations are nearly free.

Live trace WebSocket (`src/streaming/`)

/runs/{run_id}/stream is a WebSocket endpoint that pushes each new ECL step the moment it's appended:

const ws = new WebSocket("ws://localhost:8000/runs/<run_id>/stream?x_api_key=demo-free-key");
ws.onmessage = (msg) => {
  const event = JSON.parse(msg.data);
  // event.type === "snapshot" | "step"
  // step events carry { t, spec, tests, e_star, state }
};

Backed by an in-process pub/sub StreamHub with bounded per-subscriber queues -- a stalled WebSocket will lose events rather than backpressure the API hot path. Auth is via the x_api_key query parameter (browsers can't set custom headers on the initial WS handshake), and ownership is enforced exactly as for the HTTP endpoints.

📊 Phase 4 -- Dashboard & Visualization

Phase 4 delivers the v0.4.x roadmap items: a metrics surface and a live, zero-build dashboard for visualising what the ECL core is actually doing.

Metric derivations (`src/metrics/`)

Pure-Python projections over a RunRecord, no numpy/torch dependency:

e_star_series(record) -- [{t, e_star}, ...], ready for a line chart.
latent_drift_series(record) -- [{t, state_norm, state_delta}, ...]. state_norm is the L2 magnitude of the latent state at step t; state_delta is ‖state_t − state_{t-1}‖, exposing how aggressively the latent is moving. The first step has state_delta = null so charts can render a gap rather than a misleading zero.
summarize_run(record) -- at-a-glance card data: step count, latest/mean E★, final ‖state‖, mean drift.

To make per-step drift meaningful, StepRecord now carries an optional state field (defaults to None for backwards compatibility) and the API populates it on each /step call. The SQL backend gets a nullable state_json column on pae_run_steps; legacy Phase 3 rows continue to deserialize without complaint.

New endpoints

	Endpoint	Description
📋	`GET /runs`	List the caller's runs with summary fields
📊	`GET /runs/{run_id}/metrics`	E-Star + drift series + summary, dashboard-ready

Static dashboard (`web/`)

The dashboard ships as plain HTML + vanilla JS (Chart.js via CDN). Zero build steps, zero npm. FastAPI mounts the directory at /dashboard if it exists; the mount is skipped cleanly when running an API-only install with the directory pruned away.

uvicorn server.app:app --reload
open http://localhost:8000/dashboard/

The landing page accepts an API key (held in memory for the page only — never persisted to localStorage / sessionStorage / cookies), lists your runs, and links to a per-run page that renders:

E-Star trajectory -- per-step certificate proxy.
Latent drift -- ‖state‖ and Δ over time.
Latest spec -- pretty-printed JSON, updated live.
Live badge -- the page opens the existing /runs/{id}/stream WebSocket and appends each new step to both charts as it arrives.

🌐 API Reference

	Endpoint	Method	Description	Auth
💚	`/health`	`GET`	Health check -- returns `ok` and version	--
🏃	`/runs`	`POST`	Create a new entanglement run with a brief	🔑
📋	`/runs`	`GET`	List the caller's runs with summaries (Phase 4)	🔑
⏭️	`/runs/{run_id}/step`	`POST`	Advance the ECL state by one tick	🔑
📜	`/runs/{run_id}/trace`	`GET`	Retrieve the full trace history for a run	🔑
📊	`/runs/{run_id}/metrics`	`GET`	Derived E★ / drift series + summary (Phase 4)	🔑
📡	`/runs/{run_id}/stream`	`WS`	WebSocket stream of new steps as they arrive (Phase 3)	🔑
🎨	`/dashboard/`	`GET`	Static dashboard UI (Phase 4)	--
📦	`/prompt-packs`	`GET`	List all available prompt archetypes	--
💰	`/pricing`	`GET`	API pricing tiers (mock data for integration)	--

Authentication: Pass X-API-Key: demo-free-key (free tier, 10 req/min) or X-API-Key: demo-pro-key (pro tier, 100 req/min) in the request header.

🤖 Phase 5 -- Dual-LLM, Real Embeddings & Multi-Agent Orchestration

Phase 5 promotes the engine from "stub dynamics" to a real co-learning loop driven by configurable LLMs, real embeddings, and a multi-agent pipeline. Like every other extension module, everything is optional -- the deterministic / hashed fallbacks keep the test suite and offline demos running with no API keys, no network, and no extra installs.

LLM providers (`src/llm/`)

Provider	When it activates	Dependencies
`DeterministicProvider`	Always available	none -- pure-Python, hash-derived stable output
`OpenAIProvider`	`OPENAI_API_KEY` set	`pip install openai`
`AnthropicProvider`	`ANTHROPIC_API_KEY` set	`pip install anthropic`
`DualLLMProvider`	Both keys set	both SDKs

Select via PAE_LLM_PROVIDER= (deterministic / openai / anthropic / dual). Missing optional deps cleanly fall back to the deterministic provider so the API never crashes on misconfiguration.

DualLLMProvider is the headline feature -- it fans one prompt out to both real providers in parallel, picks the higher-confidence response, and records a divergence metric on meta.divergence so disagreements surface in the dashboard.

Embedding streams (`src/embeddings/`)

Provider	When it activates	Dependencies
`HashingEmbeddings`	Always available	none -- signed-hash n-gram, à la `HashingVectorizer`
`OpenAIEmbeddings`	`OPENAI_API_KEY` set	`pip install openai`
`SentenceTransformersEmbeddings`	Explicit selection	`pip install sentence-transformers`

Select via PAE_EMBEDDINGS_PROVIDER= (hashing / openai / sentence-transformers). The hashing backend is a real technique, not a stub -- cosine similarity is meaningfully higher for related strings than unrelated ones, which is enough to drive the orchestrator's coherence-based E★ proxy.

Multi-agent orchestration (`src/agents/`)

brief
   │
   ▼
┌──────────────┐         ┌──────────────┐         ┌──────────────┐
│ WriterAgent  │ ──spec─▶│ TesterAgent  │ ──tests│ EthicsAgent  │
└──────────────┘         └──────────────┘         └──────────────┘
       │                        │                        │
       └──────────────────┬─────┴────────────────────────┘
                          ▼
              embed(spec) + embed(tests) + embed(ethics)
                          │
              cosine(spec, tests) → coherence
              ethics.verdict     → bonus / penalty
              prev_state ⨯ 0.5 + centroid ⨯ 0.5 → new state
                          │
                          ▼
              { spec, tests, ethics, e_star, state, agents, divergence }

Each agent uses the same LLMProvider, parses the response (handling fenced code blocks, bare JSON, and prose-wrapped JSON), and falls back to a sensible default shape if the model returns garbage. The orchestrator computes the new latent state from a centroid of the three agent embeddings, blended 50/50 with the previous state for genuine co-learning memory across steps.

Activation

# Run with real LLMs:
export PAE_LLM=1
export PAE_LLM_PROVIDER=dual          # or openai / anthropic / deterministic
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export PAE_EMBEDDINGS_PROVIDER=openai  # or hashing / sentence-transformers
uvicorn server.app:app --reload

Core.step now accepts the run's brief and, when the orchestrator is active, delegates to it -- emitting ethics, agents, and divergence keys on the step result alongside the usual spec / tests / e_star / state. Without PAE_LLM=1 the legacy torch stepper runs unchanged, so existing clients see no behavioural diff.

🏛️ Phase 6 -- Plugin Ecosystem, Prompt Registry, Studio & Benchmarks

Phase 6 ships the v1.0.x roadmap: the engine is now extensible from outside the repo, the four legacy prompt packs are replaced by a real on-disk registry, the dashboard gains a Studio page for browsing packs, and scripts/bench.py gives the project a reproducible benchmark contract.

Plugin ecosystem (`src/plugins/`)

A four-namespace registry (llm, embeddings, agent, tester) that lets third-party packages add providers without touching the repo:

from src.plugins import register

@register("llm", "ollama")
def make_ollama():
    from my_ollama_provider import OllamaProvider
    return OllamaProvider(host="http://localhost:11434")

The LLM and embedding factories consult the registry after their built-ins, so plugin providers are selectable via the same PAE_LLM_PROVIDER / PAE_EMBEDDINGS_PROVIDER env vars. Entry-point discovery (prompt_atlas.llm, prompt_atlas.embeddings, …) is opt-in via PAE_PLUGINS=1 — importing arbitrary third-party code at server startup needs the operator's blessing. Failed plugin loads are logged and skipped, never raised.

GET /plugins returns the installed extensions (namespace · name · source · meta) so the Studio can show what's available.

Community Prompt Registry (`src/registry/`, `prompts/packs/`)

The hardcoded /prompt-packs stub is replaced by a real disk-backed registry:

Packs are YAML or JSON files matching the PromptPack Pydantic schema (id, version, title, domain, tags, description, author, license, prompts[], defaults).
Bundled packs ship under prompts/packs/ and preserve the legacy IDs (myth-1, science-1, psych-1, purpose-1) so existing clients keep working.
Operators add their own packs by pointing PAE_PROMPT_PACKS_DIR (:-separated, like PATH) at one or more overlay directories. Later entries override earlier ones.
Templates use plain {slot} substitution. Defaults declared on the pack fill missing slots; unknown slots raise KeyError. Caller args always win.

New / changed API:

Method	Path	Notes
GET	`/prompt-packs?q=&domain=&tag=&limit=&offset=`	Paginated list with search/filter
GET	`/prompt-packs/{id}`	Full pack document
GET	`/prompt-packs/{id}/prompts/{name}`	A single template
GET	`/plugins`	Installed extensions

Prompt Atlas Studio (`web/studio.html`)

A zero-build, vanilla-JS page mounted at /dashboard/studio.html that:

Lists registry packs with free-text search + domain filter.
Drills into a pack to inspect templates (role, inputs, body rendered verbatim via textContent to avoid HTML injection).
Links back to the runs dashboard.

Reproducible benchmarks (`scripts/bench.py`)

# Deterministic torch path
python -m scripts.bench --steps 16 --json /tmp/bench.json

# Phase 5 orchestrator + Phase 6 prompt pack
python -m scripts.bench --llm --pack myth-1 --prompt user_story \
    --var system_under_review="a feed-ranking service" \
    --steps 16 --json /tmp/bench-myth.json

The output JSON conforms to docs/research/bench_result.schema.json (version: 1) -- a stable contract so notebooks and papers can keep parsing results across releases. Headline metrics: e_star_mean, e_star_final, drift_mean, steps_per_second.

Research notes (`docs/research/`)

New top-level home for the project's research-grade documentation -- bench schema, reading list, and citation guidance. The full academic write-up + benchmark suite are tracked here.

🧩 Key Concepts -- The Language of Entanglement

🔮 EntanglementBus	A GRU-based recurrent unit that maintains an evolving shared state between co-learning agents. At each timestep, it ingests concatenated features from two latent streams and produces a fused hidden state `h(t)` that neither agent controls alone -- only together.
⭐ E-Star	The entanglement coherence metric -- a scalar derived inversely from InfoNCE loss. Higher E-Star means the two streams have found shared structure; lower means they're still diverging. It's the pulse of the system.
📝 Prompt Packs	Thematic archetype collections that guide prompt-space exploration. Four domains: Myth (creation, narrative), Science (unknowns, hypothesis), Psychology (self, reflection), and Purpose (profit, meaning). Each pack seeds different co-learning trajectories.
🏃 Runs	Sessions that capture entangled state trajectories -- the evolving relationship between a Writer agent (specs) and a Tester agent (tests) as they negotiate through shared uncertainty. Each run is a unique experiment in co-creation.
📊 InfoNCE Loss	A contrastive loss that pulls positive pairs (corresponding features from both streams) together while pushing negative pairs apart. Temperature tau = 0.1 controls the sharpness of the distribution.
🧬 Latent Heads	VAE-style mu/sigma projection heads that map summarized embeddings into a distributional latent space, enabling uncertainty-aware representations for each co-learning stream.

🪞 AI as Soul's Mirror

An interactive prototype where AI becomes a mirror for archetypal self-reflection.

"What if AI could reflect not just your words -- but your archetype?"

The Soul's Mirror module maps your natural language input to six Jungian archetypes -- Wanderer, Healer, Sage, Warrior, Creator, and Lover -- using keyword lexicons, sentiment analysis, and a reflection engine that returns personalized affirmations.

🔍 How It Works

    Your Words                    Reflection Engine                  Your Mirror
  ┌──────────┐               ┌──────────────────────┐           ┌──────────────┐
  │ "I seek  │               │  Tokenize -> Score   │           │ Archetype:   │
  │  truth   │──────────────>│  6 Archetypes        │──────────>│   🧙 Sage    │
  │  in the  │               │  Detect Sentiment    │           │ Affirmation: │
  │  chaos"  │               │  Generate Reflection │           │  "Wisdom     │
  └──────────┘               └──────────────────────┘           │   finds you" │
                                                                 └──────────────┘

Archetypes:

	Archetype	Color	Essence
🧭	Wanderer	`#4F46E5`	Exploration, journey, discovery
💚	Healer	`#10B981`	Restoration, compassion, balance
🧙	Sage	`#8B5CF6`	Wisdom, truth, understanding
⚔️	Warrior	`#EF4444`	Courage, strength, conviction
🎨	Creator	`#F59E0B`	Innovation, expression, vision
💜	Lover	`#EC4899`	Connection, passion, devotion

Launch:

cd ai_as_souls_mirror
uvicorn mirror_experience:app --reload --port 8001
# Visit http://localhost:8001

🧬 Biology, Life, and Beyond

Interactive micro-exhibits for evolutionary and ecological exploration.

"What if you could watch evolution happen -- in real time, in your browser?"

Four living simulations, each exposing a different facet of biological complexity:

🐺 Lotka-Volterra Predator-Prey Dynamics

Classical predator-prey oscillations solved with a 4th-order Runge-Kutta integrator. Configurable growth rates, predation coefficients, and environmental pulse shocks.

curl http://localhost:8002/api/lv

🧬 Evolutionary Design (Genetic Algorithm)

A genetic algorithm evolves DNA-like sequences (ACGT) toward target motifs and GC-content balance. Watch selection, crossover, and mutation drive a population toward fitness peaks.

curl http://localhost:8002/api/evo

🪸 Coral-Algae Symbiosis

Coupled ODEs modeling the delicate balance between coral and algae populations under heat stress. Observe bistability, tipping points, and ecological collapse in real-time.

curl http://localhost:8002/api/coral

🦠 Pandemic Mutation Branching

Stochastic mutation branching with variant emergence. Each variant carries its own R-naught, driving exponential growth cascades that mirror real-world pandemic dynamics.

curl http://localhost:8002/api/pandemic

Launch all simulations:

cd biology_life_and_beyond
uvicorn biology_app:app --reload --port 8002
# Visit http://localhost:8002

🌈 Hyperspectral Visuals

Publication-grade interactive visualizations for high-dimensional coherence data.

"64 spectral bands. 3 principal components. One pulsing E-Star metric. Zero CDN dependencies."

The Hyperspectral Visuals module generates self-contained interactive HTML explorations that visualize high-dimensional data through:

🎬 Auto-animating band traversal across 64 spectral bands
🌀 3D PCA rotation of manifold-embedded cluster data
⭐ Real-time E-Star pulse in the title bar
🖱️ Click-to-inspect individual spectra
🎨 Color presets: Natural RGB, Near-Infrared (NIR), Short-Wave IR (SWIR)
⌨️ Keyboard controls: Space (play/pause), R (reset)

🔬 Generate Your Own

cd hyperspectral_visuals

# Generate the performance visualization (produces a 14.1 MB interactive HTML)
python hyperspectral_atlas_performance.py

# Or generate the explorer variant (produces a 2.4 MB interactive HTML)
python hyperspectral_atlas_demo_v2.py

Offline-first: All generated HTML files are fully self-contained -- no internet connection required to explore them. Share them with anyone.

🧪 Bio Design Ethics

Frameworks for responsible creation in the age of AI-guided biology.

"Nature has been writing design patents for 3.8 billion years. Are we ready to be co-authors?"

The Bio Design Ethics module is a reflective philosophical framework exploring:

🌱 The Library of Nature -- AI as a reader, then co-author, of evolutionary design
⚖️ Computational Symbiosis -- Ethical frameworks for synthetic life
🔬 Post-Darwinian Responsibility -- What it means to create when creation has consequences at ecosystem scale
🧬 AI as Observer to Co-Author -- The transition from modeling life to participating in its design

🌀 Cosmic Information Economies

Exploring information as the universe's fundamental currency.

"What if every computation is a transaction -- and every insight is a dividend?"

This module proposes that information -- not matter, not energy -- is the most fundamental medium of exchange in the cosmos. It includes:

📖 Essays: Information as Cosmic Currency, The Wormhole Ledger Case Study
🎮 Interactive Frontend: Explore information-theoretic models in your browser
📝 Prompt Catalogue: Curated prompts for further exploration

cd cosmic_information_economies
uvicorn app:app --reload --port 8003
# Visit http://localhost:8003

📡 Tech Stack -- The Instruments

Layer	Technology	Purpose
🧠 Core ML		GRU EntanglementBus, InfoNCE, VAE heads
🌐 API		Orchestration, auth, rate limiting
📊 Data		Config, state persistence, validation
🧮 Compute		Numerical operations, RK4 integration
🗄️ Database		Persistent runs (roadmap)
🎨 Frontend		Dashboard UI (roadmap)
💳 Billing		API monetization (optional)
🐳 Deploy		Containerized deployment
🐍 Runtime		Primary language

⚙️ Configuration

Copy .env.example to .env and configure:

Variable	Description	Default
`APP_MODE`	Execution mode	`research`
`PAE_DEVICE`	Compute device (`auto`, `cpu`, `cuda`, `mps`)	`auto`
`PAE_STATE_DIM`	Dimensionality of entangled state vector	`64`
`DEFAULT_PLAN`	Default pricing plan	`free`
`STRIPE_SECRET`	Stripe billing integration (optional)	--
`STRIPE_WEBHOOK_SECRET`	Stripe webhook verification (optional)	--

Training Configuration (configs/ecl_llm_llm.yaml):

Parameter	Value	Purpose
`state_dim`	64	Hidden state dimensionality
`batch_size`	4	Training batch size
`max_steps`	1000	Training iterations
`loss_weight_latent`	0.5	Latent space regularization
`loss_weight_MI`	1.0	Mutual information weight
`loss_weight_coherence`	1.0	InfoNCE coherence weight
`loss_weight_divergence`	0.2	KL divergence weight
`infonce_temp`	0.1	Contrastive temperature

📈 Roadmap -- The Path Ahead

  v0.2.0                          v0.3.x                    v0.4.x
  ═══════════════╦═══════════════════╦══════════════════════════╦═══════
                 ║                   ║                          ║
  ✅ ECL Core    ║  ✅ Postgres ORM  ║  ✅ Dashboard            ║
  ✅ FastAPI API ║  ✅ Persistent    ║  ✅ E-Star Visualization ║
  ✅ Auth + Rate ║     Runs          ║  ✅ Latent Drift Charts  ║
  ✅ 5 Extension ║  ✅ Migration     ║  ✅ WebSocket Streaming  ║
     Modules     ║     Framework     ║                          ║
                 ║                   ║                          ║
  ═══════════════╩═══════════════════╩══════════════════════════╩═══════

       v0.5.x                                   v1.0.x ★ CURRENT
  ═════════════════════════════╦════════════════════════════════════════
                               ║
  ✅ Dual-LLM Integration      ║  ✅ Prompt Atlas Studio
     (OpenAI + Anthropic)      ║  ✅ Plugin Ecosystem
  ✅ Real Embedding Streams    ║  ✅ Community Prompt Registry
  ✅ Multi-Agent Orchestration ║  ✅ Reproducible Benchmarks
                               ║  ✅ Research-Grade Documentation
  ═════════════════════════════╩════════════════════════════════════════

🧑‍💻 Development Commands

Command	Purpose
`python -m src.train_ecl`	Run the entanglement training loop
`uvicorn server.app:app --reload --port 8000`	Start API server in dev mode
`python scripts/prepare_data.py`	Generate toy training data
`bash scripts/run_train.sh`	Launch training via shell script
`pytest`	Run test suite (roadmap)
`docker compose up`	Full-stack launch with Postgres & API (roadmap)

🤝 Contributing -- Join the Entanglement

Every fork is a new branch of possibility. Every contribution is an act of co-creation.

We welcome contributions across all dimensions of this project:

	Area	How to Contribute
🧠	ECL Core	Improve training loops, add new loss functions, optimize the EntanglementBus
🌐	API Layer	Add endpoints, improve auth, enhance rate limiting
🪞	Soul's Mirror	Expand archetypes, improve reflection engine, add new psychological models
🧬	Biology	Add new simulations, improve integrators, contribute ecological models
🌈	Visualization	Create new visual explorations, improve interactivity
🧪	Ethics	Contribute frameworks, essays, and philosophical perspectives
🌀	Cosmic Economics	Expand information-theoretic models
📝	Prompts	Contribute new prompt packs for unexplored domains
📚	Documentation	Improve guides, add tutorials, translate

Getting Started

Fork the repository
Create a feature branch: git checkout -b feature/your-idea
Make your changes with clear commit messages
Push to your fork and open a Pull Request

💡 First time contributing? Start by exploring the Prompt Packs or adding a new essay to Bio Design Ethics. Every contribution matters.

Please read atlas_respect.md for attribution guidelines and the spirit of co-authorship that guides this project.

📜 Citation & Attribution

If you use Prompt Atlas Engine in your research, please cite:

@software{tadaya2025promptatlas,
  title     = {Entangled Co-Learning for LLMs -- Prompt Atlas Edition},
  author    = {Tadaya, Don D. M.},
  year      = {2025},
  url       = {https://github.com/dascient/prompt-atlas-ecl},
  license   = {Apache-2.0}
}

🌐 Licensing

Licensed under the Apache License 2.0 -- see LICENSE for details.

Code: Apache 2.0 | Narrative content (manifestos, essays): CC BY-NC 4.0

Research contributions and forks are welcome. Please cite or link back to this repository when referencing the ECL framework.

🜂 Ethos

╔══════════════════════════════════════════════════════════════════╗
║                                                                  ║
║   "Prompt Atlas is not a product -- it's a conversation          ║
║    between systems. Between minds. Between epochs."              ║
║                                                                  ║
║   Our goal is to explore machine entanglement as cognition:      ║
║   the moment two systems share uncertainty -- and begin          ║
║   to co-create understanding.                                    ║
║                                                                  ║
║   We believe the future of AI is not domination but dialogue.    ║
║   Not replacement but resonance. Not answers but the shared      ║
║   courage to hold better questions.                              ║
║                                                                  ║
║   Every module here is an invitation:                            ║
║     to reflect, to simulate, to visualize, to question,          ║
║     and to build -- together.                                    ║
║                                                                  ║
╚══════════════════════════════════════════════════════════════════╝

Built with 🧠 + 🤍 by humans and machines, entangled.

"The universe is not made of atoms -- it's made of stories. And the best stories are the ones we write together."

Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 35 Commits
ai_as_souls_mirror		ai_as_souls_mirror
bio_design_ethics		bio_design_ethics
biology_life_and_beyond		biology_life_and_beyond
configs		configs
cosmic_information_economies		cosmic_information_economies
docs		docs
hyperspectral_visuals		hyperspectral_visuals
infra		infra
prompts		prompts
scripts		scripts
server		server
src		src
tests		tests
web		web
.DS_Store		.DS_Store
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
CITATION.cff		CITATION.cff
LICENSE		LICENSE
PROMPT_ATLAS.md		PROMPT_ATLAS.md
README 2.md		README 2.md
README.md		README.md
atlas_respect.md		atlas_respect.md
i		i
i.txt		i.txt
requirements 2.txt		requirements 2.txt
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

✦ Entanglement Co-Learning Engine ✦

🌌 The Vision

🗺️ Table of Contents

🏗️ Architecture -- The Living Map

🚀 Quickstart -- From Zero to Entangled

Step 1: Clone & Install

Step 2: Run the Entanglement Training Loop

Step 3: Launch the API Server

Step 4: Create Your First Entanglement Run

Step 5: Explore the Extension Modules

🛰️ Phase 1 -- Distributed Orchestration (MACP + Vector Memory)

MACP -- the Entanglement Bus

Vector Memory -- Long-Term Co-Learning Recall

Bring Up the Phase-1 Infrastructure

🔬 Phase 2 -- Loss Geometry, Formal Verification, Experiment Tracking

Distribution-geometry losses (src/losses_geom.py)

Symbolic Tester (src/testers/z3_tester.py)

MLflow experiment tracking (src/tracking/MLflowTracker)

🗄️ Phase 3 -- Persistent Runs & Live Trace Streaming

RunStore -- pluggable persistence (src/runstore/)

Live trace WebSocket (src/streaming/)

📊 Phase 4 -- Dashboard & Visualization

Metric derivations (src/metrics/)

New endpoints

Static dashboard (web/)

🌐 API Reference

🤖 Phase 5 -- Dual-LLM, Real Embeddings & Multi-Agent Orchestration

LLM providers (src/llm/)

Embedding streams (src/embeddings/)

Multi-agent orchestration (src/agents/)

Activation

🏛️ Phase 6 -- Plugin Ecosystem, Prompt Registry, Studio & Benchmarks

Plugin ecosystem (src/plugins/)

Community Prompt Registry (src/registry/, prompts/packs/)

Prompt Atlas Studio (web/studio.html)

Reproducible benchmarks (scripts/bench.py)

Research notes (docs/research/)

🧩 Key Concepts -- The Language of Entanglement

🪞 AI as Soul's Mirror

🧬 Biology, Life, and Beyond

🌈 Hyperspectral Visuals

🧪 Bio Design Ethics

🌀 Cosmic Information Economies

📡 Tech Stack -- The Instruments

⚙️ Configuration

📈 Roadmap -- The Path Ahead

🧑‍💻 Development Commands

🤝 Contributing -- Join the Entanglement

Getting Started

📜 Citation & Attribution

🌐 Licensing

🜂 Ethos

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Distribution-geometry losses (`src/losses_geom.py`)

Symbolic Tester (`src/testers/z3_tester.py`)

MLflow experiment tracking (`src/tracking/MLflowTracker`)

`RunStore` -- pluggable persistence (`src/runstore/`)

Live trace WebSocket (`src/streaming/`)

Metric derivations (`src/metrics/`)

Static dashboard (`web/`)

LLM providers (`src/llm/`)

Embedding streams (`src/embeddings/`)

Multi-agent orchestration (`src/agents/`)

Plugin ecosystem (`src/plugins/`)

Community Prompt Registry (`src/registry/`, `prompts/packs/`)

Prompt Atlas Studio (`web/studio.html`)

Reproducible benchmarks (`scripts/bench.py`)

Research notes (`docs/research/`)

Packages