# flylab connection notes

Current local edition: read [RUN.md](./RUN.md). The default endpoint is unset.
This edition uses an open lab and the unchanged experimental neural backend.
The instructions below are adapted from the supplied connection handoff; external
hosting and paid services are not configured by this package.

# Orbofi task: connect flylab's experimental MaleCNS server

Release: flylab branding update, based on Flight update (lab / 03), 8 September 2026. Read NEURAL-SERVER-SETUP.md for the hosting checklist. The current app is http://localhost:8080 . Download the complete source from the Project panel. Work inside that extracted project, preserving all files and licenses.

## Deliverable
Deploy the included Python WebSocket service, connect the viewer to it, and verify that selecting each of 12 flies shows that fly's measured model spike telemetry. Do not simulate telemetry in the browser or describe the model as Google's brain emulation.

## 1. Prepare the data

Use Python 3.11+ with adequate RAM and disk for the upstream download and sparse graph import. The importer holds full annotation/connectivity tables in memory; measure peak RAM before choosing a production machine. It is not suitable for a static host or a 128 MB Worker.

```bash
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
python -m backend.import_malecns --raw-dir data/raw --out data/graph
python -m backend.build_brain_atlas --raw-dir data/raw --graph data/graph --out dist/assets/brain-atlas.json
```

Expected retained graph: 164,506 typed neurons, 25,135,616 edges. Expected atlas: 1,430 sampled cell bodies, 22 annotation superclass groups. The atlas and graph/telemetry.json must come from the same build. The viewer checks the exact atlas hash before showing activity. Keep upstream source URLs, checksums and attributions.

## 2. Launch the service

Provision a persistent Python process. Set FLYWORLD_TOKEN to a newly generated secret (at least 16 characters) using the host's secret manager; do not commit it, put it in a URL, or include it in this public app. Set FLYWORLD_ORIGINS to the exact viewer origin (comma-separated if several). Then:

```bash
python -m backend.server --graph data/graph --host 127.0.0.1 --port 8765 --state-dir state --device cpu
```

Run behind a TLS reverse proxy with WebSocket upgrade support. The public endpoint must start with wss:// for the HTTPS viewer. Configure supervisor restarts and a durable state volume; use --resume only when a valid saved checkpoint exists. Every authenticated viewer controls the same authoritative world; this is not per-user tenancy.

The CPU path is functional but slower than real time on the tested machine. CUDA is optional for numerical execution, not a guarantee of real-time speed. To evaluate a GPU, use the supported CUDA/PyTorch setup in the project documentation, select --device cuda and run CPU/CUDA parity and full 12-agent throughput measurements on the supplied GPU. No GPU performance claim is currently verified.

## 3. Configure the viewer

After obtaining the real deployed endpoint:

```bash
python configure_neural.py wss://YOUR_DEPLOYED_HOST/ws
```

Replace the placeholder with the actual endpoint. This writes dist/neural-config.json without a token. Deploy the updated dist/ folder including the matching anatomical atlas. The Connect live brain form beneath the paired body/anatomy views then preloads the URL. The user enters the session token there; the token is sent only in the first authenticated WebSocket message and is not persisted by the app.

For a local CPU trial, serve dist/ over HTTP and enter ws://127.0.0.1:8765 in the form. Set the server's origin allowlist to the local viewer origin too. Opening the HTML directly as a file is unsupported.

## 4. Acceptance

```bash
python -m unittest discover -s tests -v
node tests/local-world.mjs
node tests/feeding.mjs
node --no-warnings --experimental-loader ./tests/three-loader.mjs tests/raster.mjs
node tests/brain-inspector.mjs
node tests/connection-config.mjs
python tests/verify_live_graph.py --graph data/graph
```

The last test launches a temporary local server and checks authentication, 12 telemetry streams, pause, food commands and checkpoint restore; it does not certify the public proxy. Also test the actual deployed endpoint in the app:

- Connection form reaches Connected and labels the real dataset.
- All 12 residents can be selected; activity comes from the selected fly's payload.
- Pause freezes the displayed measurement window. Resume advances it.
- Server disconnection freezes the world and displays a reconnect state.
- Wrong token fails. Wrong atlas hides activity; never silently recolor it.
- Place banana, fish and meat. Their different odor strengths are design assumptions.
- Record wall-clock throughput and peak CPU/GPU memory for the complete population.

## Scientific boundaries

The MaleCNS wiring is observed anatomy. LIF dynamics, transmitter signs, generic sensory stimulation and body control are original experimental assumptions. The anatomical display is sampled soma coordinates, not a cortex, neuropil regions, full arbors or an activity recording from a living fly. No validated aging, food preference physiology, aerodynamic flight or Google-equivalent functional reproduction is claimed.

## Files to edit

- dist/neural-config.json: public endpoint, schema 1, population 12. Never a secret.
- backend/server.py: service/authentication/streaming.
- backend/engine.py: dynamics and measured spike telemetry.
- backend/build_brain_atlas.py: exact atlas/telemetry pairing.
- dist/brain.js: selected-fly activity display and integrity checks.
- docs/FLYWORLD-HANDOFF.md: update with deployed endpoint, host procedure and measured results.

Return the tested app URL, revised source bundle, updated docs, hosting instructions and benchmark report. Preserve the local fallback and the distinction between anatomy, experimental activity and procedural behavior.