PsyFi

Deterministic consciousness-field simulation workspace and phenomenology visualization instrument.
Web-first · ABX-Core v1.3 · research/visualization only — not medical advice.

Install · Usage · Live Experience · Production readiness · API · Documentation · Contributing

---

Why

PsyFi keeps simulation truth in Python and puts an expressive, safety-clamped visual instrument in the browser:

• Deterministic ABX-Core runtime with provenance
• Substance presets + phenomenology catalog → distilled visual overlays
• Immutable ParameterField → Canvas / optional WebGL engines → mandatory safety pass
• Cancelable /api/v1 jobs, IndexedDB history, installable PWA shell

The field is expressive. The instrument is precise.

Production readiness

Full board: docs/PRODUCTION_READINESS.md.

Track	Status	Notes
/api/v1 contracts	hard_frozen	psyfi-api-v1-hard-2026-07-25
CI (pytest + hallmark + GPU build)	green path	.github/workflows/ci.yml
Docker deploy	ready	Compose + urllib healthcheck + GPU dist/ bake
Live Experience + safety	ready	Neutral View · ParameterField authority
GPU platform G0–G3	ready	/gpu/ present · compute · TAA · premium post
GPU G4 cutover ship gates	ready	assets · parity · goldens · G4_CUTOVER.md
Desktop Ultra (30/40/50 + peers)	ready	NVIDIA · AMD RX · Intel Arc · Apple Pro/Max
PWA (/ shell + /gpu/ route)	ready	separate /gpu/ · SW v41 · PWA_GPU_ROUTE.md
Device matrix + Phase 4	filled	2026-07-25 human + simulated Ultra QA
Simulated Ultra QA	passed	SIMULATED_ULTRA_QA.md
Soft-present pixel goldens	ready	PIXEL_GOLDENS.md
Native iOS	deferred	docs/IOS_MIGRATION.md

Ship checklist: pytest → npm test && npm run gpu:test && npm run gpu:build → docker compose up -d --build → /health /ready / /gpu/.

Optional next: hardware Ultra fps confirmation; full R3F stills on a GPU CI runner.
Instrument track: I1–I5 landed (instrument map, hold-and-compare, spatiotemporal anchors, planner, Journey objects) — see docs/CONTINUATION_PLAN.md and docs/INSTRUMENT_GROUNDING_PLAN.md.

Install

git clone https://github.com/scrimshawlife-ctrl/Psy-Fi.git
cd Psy-Fi
pip install -e ".[dev]"

# Optional: markdown lint/fix tooling for README
npm install

Optional MIDI extras are already included in the default install (mido, python-rtmidi).

Usage

# Rebuild phenomenology catalog + substance visual overlays
python3 scripts/build_experience_catalog.py

# Hard-freeze sync (after OpenAPI / golden updates)
python3 scripts/export_openapi.py
python3 scripts/regenerate_overlay_goldens.py
python3 scripts/sync_frozen_contracts.py

# Tests
python3 -m pytest tests/ -q
npm test   # hallmark README lint
npm run gpu:test

# Optional GPU platform (R3F + WebGPU)
npm run gpu:build
# → served at /gpu/ when the API runs

# Dev server
python3 scripts/run_dev_server.py
# → http://localhost:8000

# Production-style Docker
docker compose up -d --build
# → http://localhost:8000

Live Experience

1. Open Live Experience
2. Choose substance + recipe + mode (Open / Attractor / Void / Power)
3. Set intensity / seed; scrub the phase timeline
4. Hit Neutral View (N) anytime
5. Optional: camera / motion / MIDI modulators (ParameterField only), export, bridge from the last workspace simulation

curl -s 'http://localhost:8000/api/v1/substances' | python3 -m json.tool | head
curl -s -X POST http://localhost:8000/api/v1/visualize/parameter-timeline \
  -H 'Content-Type: application/json' \
  -d '{"substance":"dmt","mode":"power","intensity":0.8,"seed":1337,"steps":8}'

Features

Area	Status
ABX-Core deterministic runtime	yes
Modular field engines	yes
22+ substance presets	yes
Phenomenology catalog + overlays	yes
Live Experience (Canvas + optional WebGL)	yes
Cancelable /api/v1/jobs	yes
PWA shell + IndexedDB history	yes
MIDI / audio / haptics modulators	yes (opt-in, gated)
WebGPU /gpu/ platform (G0–G2)	yes
/api/v1 hard freeze	yes
Native iOS	deferred (separate track)

Architecture

seed + substance/experience + optional modulators
        ↓
immutable PsyFiParameterField
        ↓
Canvas / WebGL engines
        ↓
mandatory SafetyPass
        ↓
quiet chrome + provenance

Simulation metrics remain Python-authoritative. UI never becomes the source of truth.

API

Canonical browser API is /api/v1 (hard-frozen). Legacy /api/* and /simulate/ remain mirrored.

• OpenAPI living snapshot: docs/contracts/openapi.json
• Hard-freeze pack: docs/contracts/frozen/
• Interactive docs: /docs when the server is running

Documentation

Doc	Purpose
AGENTS.md	Agent contract (intent → spec/plan → code)
intent/	Stage-0 intent blanks — no product invent
PROJECT_INDEX.md	Codebase map & ownership index
.agents/skills/codebase-memory/	Codebase Memory graph skill
docs/PRODUCTION_READINESS.md	Production readiness board
docs/CONTINUATION_PLAN.md	Web-track next steps
docs/INSTRUMENT_GROUNDING_PLAN.md	Instrument + spatiotemporal grounding plan (I1–I5)
docs/rendering/ROADMAP.md	GPU G0–G5 roadmap
docs/rendering/G4_CUTOVER.md	G4 cutover checklist
docs/rendering/PIXEL_GOLDENS.md	Soft-present pixel goldens
docs/DESKTOP_GPU.md	Multi-vendor WebGPU Ultra
docs/PWA_GPU_ROUTE.md	/gpu/ separate-route decision
docs/SIMULATED_ULTRA_QA.md	Simulated P0 Ultra desktop QA
docs/NVIDIA_GPU.md	NVIDIA drivers + Compose
PLANS.md	Product phases + gates
docs/VISUAL_EXPERIENCES.md	Live Experience guide
docs/rendering/README.md	WebGPU platform docs
DEPLOYMENT.md	Docker deploy guide
docs/PHENOMENOLOGY_PIPELINE.md	Scraped → overlays
docs/BROWSER_CAPABILITY_MATRIX.md	Device QA (filled)
docs/contracts/frozen/API_V1_FREEZE.md	Contract hard freeze
docs/PHASE4_USABILITY.md	Usability checklist
MOBILE_PWA_GUIDE.md	PWA guidance
docs/IOS_MIGRATION.md	Deferred native notes

Non-claims

Modeled phenomenology for research and visualization only.
Not medical, diagnostic, or therapeutic advice.
Motifs/parameters are INFERRED; source existence is OBSERVED.

Contributing

• Keep simulation outputs deterministic for fixed seeds/params
• Prefer /api/v1 for new routes; update OpenAPI + run scripts/sync_frozen_contracts.py
• Do not bypass the visual safety pass
• Do not add medical/healing claims to UI copy
• Native iOS stays out of the web track
• Device matrix / Phase 4 are living QA — not freeze blockers
• Keep root markdown hallmark-clean: npx hallmark fix README.md

python3 -m pytest tests/ -q
npx hallmark lint README.md
python3 scripts/export_openapi.py
python3 scripts/build_experience_catalog.py
python3 scripts/sync_frozen_contracts.py

License

MIT © Applied Alchemy Labs.

License

Copyright © 2026 Zero State LLC. All Rights Reserved. Licensed under the Zero State Proprietary License v1.0. See LICENSE.

Third-party components remain subject to their respective licenses.