Update README.md

Author: BryceWDesign

README.md

@@ -1,107 +1,146 @@
 # SynapDrive-AI
 
-**SynapDrive-AI** is a **simulation-first** prototype of an **intent → safety → actuation** control pipeline inspired by BCI/autonomy workflows.
+**SynapDrive-AI** is a **simulation-first** reference implementation of an **intent → context → safety gate → actuation** pipeline inspired by autonomy + BCI workflows.
 
-This repo **does not** claim medical/clinical functionality. It is intentionally built to be runnable on any machine without hardware:
-- **Text pathway** = “decoded intent” (what a BCI decoder *could* output)
-- **Signal pathway** = simulated EEG-like waveforms + label-driven reasoning
+This repo makes **no medical/clinical claims**. It’s designed to be runnable without hardware, while still supporting **optional** real-world input pathways (BrainFlow / LSL).
 
 ---
 
-## What you can do with it (today)
+## What it does
 
-- Run a full end-to-end loop: **intent → context → safety gate → actuation → evaluation**
-- Verify safety gating blocks low-confidence actions
-- View stable telemetry logs (intended for dashboards/tests)
-- Extend it with real adapters later (robotics, vehicles, BCI devices)
+- End-to-end loop: **intent → optimizer (memory + vision context) → safety gate → actuation → evaluation**
+- **Safe-by-default:** unknown / low-confidence intents are blocked
+- **Telemetry contract:** stable log schema for dashboards/tests
+- **Reproducibility:** record/replay (JSONL)
+- **Quality gates:** tests + CI + lint + type-check + coverage
+- **Dashboard:** local Flask UI for quick inspection
 
 ---
 
 ## Architecture (canonical pipeline)
 
 ```mermaid
 flowchart LR
-  A[Input: decoded text OR simulated signal] --> B[Intent decode / reasoning]
-  B --> C[Optimizer: memory + vision context]
-  C --> D[SafetyGuard]
-  D -->|safe| E[DecisionRouter]
-  D -->|blocked| X[Blocked result]
-  E --> F[ActuationEngine (simulated)]
-  F --> G[EpisodicMemory]
-  F --> H[MetaEvaluator]
-  G --> C
-
+    A[Input: decoded text / simulated signal / BrainFlow / LSL] --> B[Intent packet]
+    B --> C[Context optimizer: memory + vision]
+    C --> D{SafetyGate}
+    D -- safe --> E[DecisionRouter]
+    D -- blocked --> X[Blocked response]
+    E --> F[ActuationEngine (simulated)]
+    F --> G[EpisodicMemory]
+    F --> H[MetaEvaluator]
+    G --> C
 
 Single source of truth wiring: synapdrive_ai/pipeline.py
 
 Quickstart
-1) Install
+Install
 python -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
+Run (decoded intent text)
+python -m synapdrive_ai --text "move left" --image road --no-delay
+python -m synapdrive_ai --text "stop" --image hazard --no-delay
+Run (simulated signal label)
+python -m synapdrive_ai --signal walk --count 3 --interval 1 --no-delay
+python -m synapdrive_ai --signal stop --no-delay
+Tests
+pip install -r requirements-dev.txt
+pytest -q
+Record & replay (reproducible runs)
 
-2) Run one cycle (decoded intent text)
-python -m synapdrive_ai --text "move left" --image road
-python -m synapdrive_ai --text "stop" --image hazard
+Record a run to JSONL:
 
-3) Run one cycle (simulated signal label)
-python -m synapdrive_ai --signal walk --count 3 --interval 1
-python -m synapdrive_ai --signal stop
+python -m synapdrive_ai --text "move left" --image road --record runs.jsonl --no-delay
+python -m synapdrive_ai --signal walk --count 3 --record runs.jsonl --no-delay
 
-4) Run tests
-pytest -q
+Replay later (deterministic, no-delay):
+
+python -m synapdrive_ai --replay runs.jsonl
+Dashboard (Flask)
+
+Run:
+
+python -m synapdrive_ai.interface.web_dashboard
+
+Open:
+
+http://127.0.0.1:5055
+
+Optional integrations (not installed by default)
+BrainFlow (optional)
+
+Install:
+
+pip install -r requirements-brainflow.txt
+
+Run (defaults to BrainFlow Synthetic board, id=0):
+
+python -m synapdrive_ai --brainflow --bf-board-id 0 --bf-seconds 2 --no-delay
+LSL / pylsl (optional)
+
+Install:
+
+pip install -r requirements-lsl.txt
+
+Run (recommend specifying stream type or name):
+
+python -m synapdrive_ai --lsl --lsl-type EEG --lsl-seconds 2 --no-delay
+# or
+python -m synapdrive_ai --lsl --lsl-name "MyEEGStream" --lsl-seconds 2 --no-delay
+Repo map
+
+synapdrive_ai/pipeline.py — canonical wiring (supports deterministic --no-delay)
+
+synapdrive_ai/bci/intent_generator.py — conservative text → intent packet
+
+synapdrive_ai/bci/signal_simulator.py — synthetic EEG-like signals
 
-Repo map (what matters)
+synapdrive_ai/agi/core_reasoning.py — RMS-based confidence from signal energy
 
-synapdrive_ai/pipeline.py
-Canonical end-to-end pipeline.
+synapdrive_ai/agi/cognitive_optimizer.py — memory + vision context injection
 
-synapdrive_ai/bci/signal_simulator.py
-Generates EEG-like synthetic waveforms.
+synapdrive_ai/safety/safety_guard.py — safety gating
 
-synapdrive_ai/agi/core_reasoning.py
-Label + waveform → structured intent packet (uses RMS energy for confidence).
+synapdrive_ai/action/decision_router.py — normalized result packets
 
-synapdrive_ai/agi/cognitive_optimizer.py
-Injects memory + vision context into intent.
+synapdrive_ai/control/actuation_engine.py — simulated actuation + telemetry schema
 
-synapdrive_ai/safety/safety_guard.py
-Blocks low-confidence or suspicious actions.
+synapdrive_ai/replay/recording.py — JSONL record/replay utilities
 
-synapdrive_ai/action/decision_router.py
-Normalizes results and routes to actuation.
+synapdrive_ai/interface/web_dashboard.py — Flask dashboard
 
-synapdrive_ai/control/actuation_engine.py
-Simulated actuator + telemetry log schema.
+synapdrive_ai/tests/ — contract tests (pipeline shape, telemetry keys, dashboard API)
 
-synapdrive_ai/tests/
-Contract tests enforcing stable output + telemetry.
+examples/ — reviewer quickcheck + golden runs generator
 
-Safety stance
+docs/ — architecture + safety model writeups
 
-This project enforces a conservative safety default:
+Reviewer validation pack
 
-Unknown / low-confidence intents are blocked
+examples/REVIEWER_QUICKCHECK.md (2–5 minute checklist)
 
-Telemetry schema is treated as a contract (dashboard/tests depend on it)
+examples/generate_golden_runs.py → examples/golden_runs.jsonl
 
-Roadmap (credible next steps)
+Generate & replay:
 
-Add optional integration adapters (not enabled by default):
+python examples/generate_golden_runs.py --out examples/golden_runs.jsonl
+python -m synapdrive_ai --replay examples/golden_runs.jsonl
+Safety stance (explicit)
 
-BrainFlow input stream (device or replay)
+Unknown or low-confidence intents are blocked
 
-MNE-based feature extraction for offline datasets
+Stable response shapes (no crashing on drift)
 
-LSL (Lab Streaming Layer) bridge for research setups
+Telemetry schema is a contract (UI/tests depend on it)
 
-Add real actuator adapters:
+Non-goals:
 
-ROS2 topic publisher
+clinical diagnosis
 
-MAVLink command emitter
+medical-device claims
 
-Game/Sim environment interface
+real-world safety certification for actuation
 
 License