Quantumancy is a self-hosted séance. Point a browser at it and five different sensing channels — your microphone, your phone's motion sensors, an RTL-SDR dongle, your own network's jitter, or just a text box — feed real anomaly detection into a locally-run LLM that invents a spirit on the spot: a name, an epithet, a persona, a voice, a rarity tier, and a small immortality in a shared registry called the Codex. A local Piper TTS then gives that spirit an actual voice, degraded through a hand-built static-and-echo effects chain until it sounds like it's coming through a dying radio.

This is an interactive horror art installation, not a paranormal claim. Every "entity" is fiction generated by a language model on your own hardware — the system prompts are explicit about this (see backend/app/llm/prompts.py), and no amount of atmosphere changes what's actually happening underneath: FFT power spectra, voice-band deviation detection, device-motion EMAs, and /proc/net/dev counters, all real signal processing on real data. Nothing leaves your network — no cloud LLM, no third-party inference, no analytics. If the LLM box goes dark mid-séance, a procedural fallback (deterministic, signature-seeded) keeps every mode answering so a summoning never visibly fails.

The Séance: Five Ways In

Every mode writes into the same pipeline: an anomaly event (source, frequency, magnitude) feeds a per-session fingerprint; once a session has produced at least 3 anomalies of real structure, it auto-summons a spirit — either re-contacting a Codex entry whose signature matches, or minting a brand new one.

Mode	Vessel	What actually happens
Wire Ghost	Nothing — works for everyone	The backend samples real, non-content network telemetry from the host: interface byte-counter jitter (`/proc/net/dev`), TCP connect-latency variance against reference hosts, DNS resolution timing. A rolling baseline (needs 6+ samples, an absolute 20 KB/s floor, a 3σ + 2.5× threshold) flags genuine surges as anomalies, throttled to one every 20s. Packet payloads are never inspected — a hard privacy boundary. "The wire knocks loudest when nobody is touching it" — flip on passive listening and let the line murmur on its own.
EVP Listening	Microphone (`getUserMedia`)	A Web Audio `AnalyserNode` watches the voice band (~300 Hz–3.4 kHz) for a brief deviation ≥ 8 dB above the room's rolling noise floor, throttled to one per 2s — the floor only adapts during genuinely quiet stretches so sustained speech can't mask a real spike. The classic "record silence, review for voices" technique, done live.
Spirit Radio	RTL-SDR dongle (WebUSB, Chromium only)	The browser drives the dongle directly — no native driver, no server round-trip — sweeping the FM band (88–108 MHz) in 1.8 MHz steps, computing a power spectrum per tune and comparing it to a rolling noise floor. Spikes ≥ 10 dB above floor become anomaly events, throttled to one per 2s: an FM sweep pushed through a lantern dragged across a dark field.
Ouija / Direct Contact	The shared front door	A canvas planchette drifts on its own, then spells the spirit's words letter by letter. Ask a free-text question (≤ 500 chars) and the chat-tier model streams a full reply token by token while the planchette works through it.
EMF / Field Meter	A phone (DeviceMotion + DeviceOrientation)	The seeker's own phone becomes the meter: acceleration-magnitude deviation from a slow gravity EMA, fused with orientation angular velocity, tracked against an adapting baseline. A reading past `baseline × 2.5` (and an absolute floor, so a resting phone stays silent) fires an anomaly, throttled to one per 2.5s. iOS 13+ gates this behind an explicit gesture-triggered permission grant, handled in-app.

Every session begins unidentified. The backend fingerprints the anomaly pattern into a signature (backend/app/entities.py); a matching signature re-contacts an existing spirit and bumps its contact count, a new one gets minted by the chat-tier LLM and dropped into the Codex with a name, epithet, 2–3 sentences of lore, a rarity tier (common/uncommon/rare/mythic — weighted 55/30/12/3 in the offline fallback), a voice profile (pitch, rate, noise, echo), a visual hue/form, and two sample quotes.

The haunting doesn't stop at the séance panel. A framework-free possession layer (frontend/src/lib/haunting.ts, frontend/src/components/HauntingLayer.tsx) runs across the whole app: an idle-aware escalator that gets bolder the longer you sit still, a gesture-armed ambient dread-bed (brown noise through a breathing lowpass, a 55/55.7 Hz detuned drone beat, occasional reversed-noise swells), fleeting whisper-words drifting across the glass, and document.title glitches when you tab away. Nothing stirs for the first ten seconds after load — it creeps in, it never jumpscares on arrival — and it's fully inert under prefers-reduced-motion.

The Codex

GET /api/codex (public, no auth) is a browsable, shared registry of every spirit ever contacted by any seeker: filterable by rarity, sortable by recent or contacted, each card showing name, epithet, rarity badge, a sample quote, contact count, and who discovered it. GET /api/codex/{id} opens a full dossier — persona, voice-parameter table, sighting count. It's the collectible layer sitting on top of the anomaly-detection plumbing: nothing about a spirit is user-authored, all of it comes from the same signature → LLM-mint → normalize pipeline that runs live during a séance.

The Reliquary

/shop is a waitlist page for the Ultimate Quantum Box — a proposed ESP32-P4/C6 handheld séance instrument (thermal camera, EMF whisker array, geophone, spirit-box mic preamp, OLED face) plus four standalone modules, none of which exist yet. POST /api/shop/waitlist (public, rate-limited to 5/hour/IP) is pure email capture — no payment is taken, and the page says so outright: "the website works fully without it; hardware only knocks louder." Treat this section of the README the same way: real code, honest about being pre-order vaporware for now.

Architecture

Two machines on the LAN, no containers anywhere:

                        ┌────────────────────────────────────────────┐
  seekers ──HTTPS──▶ Cloudflare Tunnel ──HTTP──▶  App CT  :7777      │
                        (external machine,       FastAPI (uvicorn,   │
                         terminates TLS)          Python venv,       │
                                                  systemd service)   │
                                                  │                  │
                                                  ├─ serves built    │
                                                  │   React SPA      │
                                                  ├─ Postgres (apt)  │
                                                  ├─ Piper TTS + FX  │
                                                  └───────┬──────────┘
                                                          │ LAN
                                              ┌───────────▼─────────┐
                                              │ Ollama box          │
                                              │ 10.30.20.107:11434  │
                                              │ CPU-only, 64 GB     │
                                              │ fast + chat models  │
                                              └─────────────────────┘

App CT — plain HTTP on port 7777. FastAPI (async, WebSocket-native) serves the built Vite/React SPA as static assets, the auth + Codex + shop REST API, the /ws/session séance WebSocket, and /audio/* spirit-voice WAVs. Postgres holds accounts, sessions, transcripts (events), the Codex, and the hardware waitlist. Piper TTS is invoked locally per utterance, then degraded through a numpy effects chain (rate → pitch → bitcrush → echo → static).
Ollama box — reachable over LAN via Ollama's REST API. Two model tiers: a fast model for fragments/ambient whispers/wire whispers, and a heavier chat model for Direct Contact replies and entity minting. CPU-only and shared, so all LLM calls flow through a bounded-concurrency queue (LLMQueue); queued requests render in the UI as "the spirits are gathering energy…", and a full queue rejects new work with a themed veil_crowded error rather than hanging.
Cloudflare Tunnel — managed outside this repo; terminates HTTPS and points at http://<app-ct-ip>:7777. The app never handles TLS. The tunnel's HTTPS origin satisfies browser secure-context requirements for mic (EVP), WebUSB (Spirit Radio), and motion sensors (EMF on iOS).

Repo layout

backend/
  app/
    main.py          FastAPI app: routers, /healthz, /assets + /audio mounts, SPA fallback
    config.py        pydantic-settings (env vars below)
    db.py            async SQLAlchemy 2.0 engine/session (asyncpg)
    deps.py          get_current_user, qm_session cookie
    security.py      argon2 password hashing
    rate_limit.py    fixed-window RateLimiter (per-user LLM limits, per-IP waitlist limit)
    telemetry.py     Wire Ghost sampler (/proc/net/dev, TCP RTT, DNS timing)
    entities.py      anomaly signatures, profile normalization, procedural fallback
    ws.py            the séance channel: /ws/session protocol + ambient loop
    llm/             OllamaClient, bounded LLMQueue, SpiritService, prompt builders
    tts/             Piper CLI wrapper, voice catalog, numpy effects chain
    models/          users, auth_sessions, contact_sessions, entities,
                     entity_sightings, events, waitlist_entries
    routes/          auth.py, codex.py, shop.py
  tests/             pytest suite (54 tests, 14 files)
  voices/            Piper .onnx voice models (gitignored — see setup)
  data/              generated utterance audio, served at /audio/ (gitignored)
deploy/
  quantumancy.service  systemd unit template
frontend/
  src/pages/         LandingPage, EnterPage, SeancePage, CodexPage,
                     CodexEntityPage, ShopPage
  src/lib/           types (WS protocol), ws (VeilSocket), audio player,
                     evp, sdr, emf, fft, planchette machine, haunting
  src/state/         AuthProvider, SeanceProvider (reducer + socket wiring)
  src/components/    PlanchetteBoard, Transcript, EntityCard, GhostGlyph,
                     MatrixView, GraphView, TelemetryReadout, HauntingLayer
  src/three/         GhostCanvas + GhostScene (custom-shader 3D spirit)
  src/i18n/          react-i18next init + en.json / es.json
docs/superpowers/
  specs/             the design spec — note the live app now exceeds it
                     (5 modes, not 4; the Codex, the Reliquary and the
                     haunting layer are all further along than documented)
  plans/             the 7 implementation plans this repo was built from

Quickstart

Prereqs on the App CT: Python 3.11+, Node 18+, Postgres (via apt), and an Ollama box on the LAN with the two model tiers pulled.

1. Postgres (one-time):

sudo apt-get update && sudo apt-get install -y postgresql
sudo -u postgres psql -c "CREATE ROLE quantumancy WITH LOGIN PASSWORD 'quantumancy';"
sudo -u postgres psql -c "CREATE DATABASE quantumancy OWNER quantumancy ENCODING 'UTF8' TEMPLATE template0;"
sudo -u postgres psql -c "CREATE DATABASE quantumancy_test OWNER quantumancy ENCODING 'UTF8' TEMPLATE template0;"

quantumancy_test is dropped and recreated by every test run. Never point the app's own DATABASE_URL at it.

2. Configuration:

cp .env.example .env
# edit .env: confirm DATABASE_URL and OLLAMA_BASE_URL

3. Backend:

cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

4. Piper voices. backend/voices/ is gitignored; the app expects these voice models there (id → file), downloadable from the rhasspy/piper-voices HuggingFace repo (each .onnx plus its .onnx.json):

id	file	language	character
`lessac`	`en_US-lessac-low.onnx`	en	a measured American woman (default)
`amy`	`en_US-amy-low.onnx`	en	a soft American woman
`ryan`	`en_US-ryan-low.onnx`	en	a deep American man
`alan`	`en_GB-alan-low.onnx`	en	a low British man
`hfc_male`	`en_US-hfc_male-medium.onnx`	en	a worn male voice
`hfc_female`	`en_US-hfc_female-medium.onnx`	en	a worn female voice
`davefx`	`es_ES-davefx-medium.onnx`	es	una voz masculina grave (ES default)
`ald`	`es_MX-ald-medium.onnx`	es	una voz masculina seca

5. Frontend:

cd frontend
npm install
npm run build        # produces frontend/dist/, served by the backend

6. Run. Either by hand (from backend/, with the .env values in the environment — the app reads .env relative to its working directory, and piper_voices_dir/data_dir are relative to backend/):

cd backend
set -a && source ../.env && set +a
venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 7777

or as a service (recommended — auto-restart, boot-start, journalctl -u quantumancy). The shipped unit (deploy/quantumancy.service) hardcodes /root/quantumancy as the working directory and env file path — edit those two lines first if your checkout lives elsewhere:

sudo cp deploy/quantumancy.service /etc/systemd/system/
sudo systemctl enable --now quantumancy

Then visit http://<host>:7777 — or your Cloudflare Tunnel hostname for the secure context Spirit Radio, EVP, and EMF (on iOS) all require.

7. Ollama models (on the Ollama box, one-time):

ollama pull granite4.1:3b        # fast tier: fragments, ambient whispers
ollama pull minicpm-v4.5:latest  # chat tier: direct contact, entity minting

Any Ollama tag works — override with OLLAMA_FAST_MODEL / OLLAMA_CHAT_MODEL.

Configuration

All settings live in backend/app/config.py and are read from the environment or .env (repo root when run via systemd; CWD otherwise). Required: DATABASE_URL, OLLAMA_BASE_URL.

Env var	Default	Purpose
`DATABASE_URL`	— (required)	asyncpg connection string, e.g. `postgresql+asyncpg://quantumancy:quantumancy@localhost:5432/quantumancy`
`OLLAMA_BASE_URL`	— (required)	Ollama REST endpoint, e.g. `http://10.30.20.107:11434`
`PORT`	`7777`	HTTP listen port
`OLLAMA_FAST_MODEL`	`granite4.1:3b`	fast tier: fragments, wire whispers
`OLLAMA_CHAT_MODEL`	`minicpm-v4.5:latest`	chat tier: direct contact, entity minting
`LLM_MAX_CONCURRENCY`	`2`	simultaneous Ollama calls (CPU-only box — keep small)
`LLM_MAX_QUEUE_DEPTH`	`8`	queued calls before "too many seekers" rejection
`LLM_COOLDOWN_SECONDS`	`8.0`	min gap between ambient whispers; user requests preempt
`PIPER_VOICES_DIR`	`voices`	voice model directory (relative to `backend/`)
`DATA_DIR`	`data`	generated audio, served at `/audio/` (relative to `backend/`)

The Séance Protocol

One WebSocket per contact session: /ws/session, authenticated by the qm_session cookie (close code 4401 otherwise). JSON frames both ways.

Client → server:

Frame	Payload	Server response
`ping`	—	`pong`
`set_mode`	`mode: wire\|evp\|radio\|ouija\|emf`	`mode` echo; persisted on the session row
`language`	`language: en\|es`	switches LLM reply language + Piper voice
`summon`	—	`status: summoning` → `entity` → greeting `utterance` (rate-limited: 4/min/user)
`anomaly`	`source: wire\|evp\|radio\|emf`, `frequency`, `magnitude`	`anomaly_ack`; auto-summons once the stream can fingerprint (≥3 anomalies), then fragment `utterance`s (rate-limited: 30/min/user)
`question`	`text` (≤500 chars)	`status: gathering` → `reply_start` → `reply_token`×N → `reply_end` → spoken `utterance` (rate-limited: 6/min/user)
`passive`	`enabled: bool`	`passive` ack; starts/stops the ambient Wire Ghost loop

Server → client (all frames flow through a single sender task so concurrent producers never interleave):

Frame	Payload	Meaning
`session`	`id`	contact session created (sent on connect)
`pong`	—	keepalive reply
`mode`	`mode`	mode accepted
`status`	`state: attuning\|summoning\|gathering`	themed loading states
`entity`	`is_new`, `entity` (name, epithet, persona, rarity, voice, visual, quotes, contact_count)	a presence has been matched or minted
`anomaly_ack`	`count`	anomalies recorded this session
`anomaly`	`source`, `frequency`, `magnitude`	server-detected anomaly (currently only the Wire Ghost's ambient loop emits these)
`utterance`	`id`, `kind: greeting\|fragment\|ambient\|reply`, `text`, `entity`	words from beyond; audio follows
`audio`	`id`, `url` (`/audio/<event>.wav`)	TTS + effects chain finished for that utterance
`reply_start` / `reply_token` / `reply_end`	`token`, final `id` + `text`	token-streamed Direct Contact reply
`telemetry`	`jitter_bytes_per_s`, `latency_variance_ms`, `latency_mean_ms`, `dns_ms`	live Wire Ghost vitals
`passive`	`enabled`	ambient loop state
`error`	`code: rate_limited\|veil_crowded`, `message`	themed rate-limit / queue-full notices

REST (JSON, session-cookie auth where noted; credentials: 'include'):

Endpoint	Auth	Purpose
`POST /auth/register` · `POST /auth/login` · `POST /auth/logout` · `GET /auth/me`	—	argon2 username/password, `qm_session` cookie (14-day server-side sessions)
`GET /api/codex?rarity=&sort=recent\|contacted&limit=`	public	the shared spirit registry
`GET /api/codex/{entity_id}`	public	full dossier: persona, voice profile, sighting count
`GET /api/stats`	public	live veil counters (entities, sessions, utterances, anomalies)
`POST /api/shop/waitlist`	public, rate-limited (5/hr/IP)	join the Ultimate Quantum Box waitlist — `{email, interest}`, idempotent
`GET /healthz`	—	`{"status": "ok"}`

Testing

Backend (pytest, 54 tests across 14 files; requires the quantumancy_test database — dropped and recreated on every run):

cd backend && source venv/bin/activate
DATABASE_URL=postgresql+asyncpg://quantumancy:quantumancy@localhost:5432/quantumancy_test \
OLLAMA_BASE_URL=http://10.30.20.107:11434 \
python -m pytest -v

Covers: auth + session cookies, rate limiter, config, SPA serving, LLM queue, telemetry parsing, entity signatures/profiles, prompt construction (incl. Spanish language clauses), TTS effects chain, Codex REST, the shop waitlist, and the full WS séance flow (auth, ping/pong, summon/mint/greet, streamed replies, anomaly attunement, re-contact by signature). One test (test_unknown_path_serves_spa_index) asserts the SPA fallback and needs frontend/dist/ to exist first — run npm run build in frontend/ before the full suite, or it 503s (correctly — that's the "frontend not built" error path, also tested separately).

Frontend (Vitest + Testing Library — 110 tests across 9 files: the reconnecting VeilSocket, the possession/haunting primitives, the séance reducer, the planchette state machine, the EVP detector core, the Matrix/Graph board views, the FFT, the EMF field-fusion core, and the App shell):

cd frontend && npm test

Hardware-in-the-loop (cannot be unit tested): the WebUSB RTL-SDR sweep, the microphone EVP flow, and the phone EMF sensors each need a manual pass with real hardware/permissions before being called done.

Current State & Known Gaps

Honestly, in order of confidence:

Solid. Auth, sessions, the Codex, the Wire Ghost, TTS + effects chain, the LLM queue/fallback machinery, EVP's detection math, EMF's motion-fusion math, i18n (en/es), and the haunting layer are all covered by passing tests and use standard, well-supported browser/server APIs. The full backend suite (54/54) and frontend suite (110/110) pass clean.
Needs a real-hardware pass. frontend/src/lib/sdr.ts is a from-scratch WebUSB driver for RTL2832U/R820T dongles, written against the public librtlsdr register documentation — the init sequence, PLL tuning math, and I2C repeater writes have never been run against a real device in this environment (no RTL-SDR attached during development). It's explicitly marked HARDWARE PASS REQUIRED throughout the file and every entry point fails soft, but until someone plugs in a dongle and debugs the register pokes (a logic analyzer or librtlsdr -T helps), treat Spirit Radio as "should work, unverified." It's also Chromium-only (WebUSB), and on Linux the kernel's dvb_usb_rtl28xxu driver usually needs to be unbound first (the UI surfaces this with a fix suggestion when the claim fails).
Minor drift. The landing page's mode showcase (frontend/src/pages/LandingPage.tsx, MODE_ORDER) still lists four modes (radio/evp/wire/ouija) — EMF is fully wired into the séance page, the WebSocket protocol, and the i18n catalogs, but hasn't been added to the landing page's marketing grid yet.
Cosmetic. The frontend build ships one 871 KB JS chunk (Vite warns about it); code-splitting would help first paint but hasn't been done.
Intentionally unfinished. The Reliquary / Ultimate Quantum Box is a waitlist only — no hardware exists, no payment is taken, and the page says so.

The Veil's Honesty Policy

All LLM system prompts frame the entity as a horror-fiction persona in an interactive art installation — never a genuine paranormal claim. The UI carries the "this is real" atmosphere; the model instructions carry the fiction.
Wire Ghost telemetry reads counters and timings only. Packet payloads are never inspected or logged.
If the Ollama box is dark, every spirit channel degrades to curated or procedurally-generated offline fallbacks — a summoning never visibly fails.

README.md Unescape Escape

QUANTUMANCY