# ASTRA 3.0 — CL1 ↔ Unreal Engine, corrected build

Closed-loop bridge between Cortical Labs' **CL1** (or a compatible substrate) and
**Unreal Engine**, with an ASTRA MCP supervision path. This build applies every
correction from the review cycle and ships a **runnable Phase-1 core** plus the
**continuous 3D-navigation decoder**.

> **Honest status.** Only what can run, runs. Phase 1 (the UDP bridge, the
> substrate simulator, the wire protocol, the safety envelope) is implemented and
> tested here — `python3 bridge/bridge.py --selftest` passes, and the test suite is
> green (13/13). Phases 2–4 of the wider ASTRA program (unified IRB router, LLM
> orchestration, comparative benchmarking) are **not** reproduced in this package;
> see `PHASES.md` for their real status. This repository does **not** vendor the
> full ASTRA v2.9 TypeScript MCP server.

## What's inside

| Path | Status | What it is |
|---|---|---|
| `bridge/` | **runnable** | UDP↔MCP bridge, wire protocol, LIF substrate, safety envelope |
| `tests/` | **passing** | protocol / safety / simulator / selftest (stdlib `unittest`) |
| `ue-plugin/` | **source** | UE plugin: continuous `UCl1AxisDecoder` (3D nav) + interface headers |
| `docs/` | doc | fast-path, ethics, channel mapping, 3D-view optimization writeup |
| `configs/` | config | channel mapping 128→64, topologies |
| `scripts/` | scripts | `install.sh`, `run-tests.sh` |

## Quick start (no hardware)

```bash
# 1. (optional) deps — the Phase-1 core needs only the Python stdlib
pip install -r requirements.txt      # pyyaml (optional), pytest (optional)

# 2. validate the whole pipe in-process
python3 bridge/bridge.py --selftest

# 3. run the substrate over UDP and stream spikes to a UE receiver on :12345
python3 bridge/bridge.py --organoid --ue-host 127.0.0.1 --ue-port 12345 \
        --control-listen-port 12346 --random-seed 42 --duration 5

# 4. run the tests
python3 -m unittest discover -s tests -p 'test_all.py'   # or: pytest tests/ -q
```

## The 3D-navigation fix (headline correction)

The documented decoder pooled 64 channels into 4 horizontal bands (`band = channel/16`)
and took an argmax → one discrete state among Up/Down/Left/Right. That is the wrong
abstraction for a 3D view: it discards magnitude (no diagonals, no variable speed),
and the horizontal bands carry **no column (X) information** even though Left/Right is
an X distinction. `UCl1AxisDecoder` replaces it with a **rate-weighted centroid over the
true 8×8 grid**, on **baseline-subtracted** rates, giving a smooth analog stick + a
forward-velocity magnitude — the "axis mappings" read-out of *Assembloid Agency* §3.4.
Full rationale in `docs/OPTIMISATION-VUE-3D.md`.

## Verified references

- **CL API** — arXiv:2602.11632 (Hogan, Doherty, Khoo, Zhou, Salib, Stewart, Lawson,
  Loeffler, **Kagan**, 2026; CC BY-NC-SA 4.0). Hard limit used here: **200 Hz/channel**.
- **Assembloid Agency** — Leung & Loewith, NeurIPS 2025 Creative AI Track. The §3.4
  "spike-to-axis" read-out and §3.4 proximity→frequency encoding are implemented.

## License

**MIT** for this package — **with a third-party caveat**: the Cortical Labs CL SDK
(the `cl` module) is **CC BY-NC 4.0** (non-commercial), not on PyPI, and is **not**
bundled here. It is only needed to drive real hardware; the simulator and selftest need
none of it. See `LICENSE`.

---
Assistance Multi IA · Assistant-Multi-AI@proton.me