EEG · LLM Intent Classification · Ed25519 Provenance · Blockchain Ledger
A clinical-grade BCI pipeline designed for children with motor impairments. Raw EEG signals become cryptographically signed, tamper-evident session records committed to a SHA-256 hash-chained ledger, no full blockchain node required.
The Problem Space
Children with motor impairments need a non-invasive path to digital interaction. Raw EEG signals are noisy, high-dimensional, and clinically meaningless without interpretation, and every interpretation used in therapy must be auditable.
Raw 4-channel Emotiv EPOC data spanning delta through gamma bands requires FFT band-power extraction and SNR estimation before any meaningful classification can begin.
Mapping EEG features to user intent, relax, focus, fatigue, select, requires either rule-based heuristics or an LLM agent with a domain-specific system prompt and temperature-controlled inference.
Any therapeutic BCI system must produce tamper-evident records. Every session must be cryptographically signed with Ed25519 so clinicians can verify that no interpretation was altered.
SHA-256 hash-chained blocks provide a ledger that any
party can audit offline. The architecture is
chain-agnostic, swap
_save/_load
for Anchor calls to go on-chain with Solana.
System Architecture
Each session flows through four deterministic, independently testable stages. The signing and hashing layers are fully chain-agnostic.
Interactive Simulation
Watch simulated EEG sessions flow through the full pipeline in real time. Each session generates intent, signs provenance, and appends a block.
Module Reference
Each module is independently testable, strictly typed with mypy strict mode, and frozen-dataclass immutable. 41 tests across 3 test files.
Generates intent-biased 4-channel EEG frames at 256 Hz. FFT band-power extraction across δ θ α β γ bands. All randomness through seeded numpy Generator for full reproducibility.
Classifies EEG features into relax / focus / fatigue / select via any OpenAI-compatible endpoint. Rule-based fallback handles offline/CI runs. Never silently drops a session.
Ed25519 keypair generation and session signing. Canonical JSON serialisation (sort_keys=True) ensures deterministic signatures regardless of field insertion order.
Append-only SHA-256 hash-chained ledger with JSON persistence. verify_chain() walks every block recomputing hashes. Swap _save/_load with Anchor calls for Solana deployment.
Typed error hierarchy: BCIDAppError: SignatureError, ChainIntegrityError, ClassificationError. Always catch specific types rather than bare Exception.
Frozen, slots=True dataclass singleton loaded once at import. All fields overridable via environment variables. LLM_BASE_URL defaults to OpenAI but accepts any compatible endpoint.
Get Running
Python ≥ 3.11. No API key needed for rule-based mode. One command launches the full pipeline.
Clone the repo and install with dev tools using
pip install -e ".[dev]". Pre-commit
hooks included.
Copy .env.example to .env.
Set OPENAI_API_KEY for LLM mode, or
leave empty for rule-based fallback.
Execute bci-dapp for 5 sessions. Add
--n 20 --llm --export to customise
count, classifier, and ledger export.
# Clone and install git clone https://github.com/murtazaai/murtazai-bci-dapp.git cd murtazai-bci-dapp pip install -e ".[dev]" # Run the pipeline (rule-based, no API key needed) bci-dapp # Options bci-dapp --n 20 # custom session count bci-dapp --llm # LLM classifier (requires OPENAI_API_KEY) bci-dapp --export # write data/ledger_export.json bci-dapp --n 10 --llm --export # combine flags # Tests pytest # all 41 tests pytest --cov-report=html:htmlcov # coverage report
from bci_dapp import ( EEGSimulator, BCIAgent, ProvenanceManager, MockBlockchainLedger, ) sim = EEGSimulator(seed=42) # seed=None for random agent = BCIAgent(use_llm=False) # True requires OPENAI_API_KEY provenance = ProvenanceManager() ledger = MockBlockchainLedger(ledger_path="data/ledger.json") keypair = provenance.generate_keypair() # Run one session frame = sim.generate_frame() features = sim.to_feature_dict(frame) result = agent.classify(features) record = provenance.sign_session(result.to_payload(), keypair) block = ledger.append(record) print(f"intent={result.intent} confidence={result.confidence:.0%}") print(f"block=#{block.index} hash={block.block_hash[:16]}…") print(f"sig_valid={provenance.verify_record(record)}") # Verify full chain v = ledger.verify_chain() print(f"chain valid={v.valid} blocks={ledger.height}")
Environment Variables
| Variable | Default | Description |
|---|---|---|
LLM_BASE_URL |
https://api.openai.com/v1 | OpenAI-compatible endpoint, swap for rig-core or Ollama |
LLM_MODEL |
gpt-4o-mini | Model identifier passed to the completion endpoint |
OPENAI_API_KEY |
empty | When absent, rule-based classifier is used automatically |
EEG_SAMPLING_RATE |
256 | Simulated sample rate in Hz (matches Emotiv EPOC) |
EEG_WINDOW_SEC |
2.0 | Analysis window duration in seconds |
LEDGER_PATH |
data/ledger.json | JSON file path for ledger persistence |
LOG_LEVEL |
INFO | DEBUG, INFO, WARNING, ERROR, CRITICAL |
APP_DEBUG |
false | Enable debug mode (true / 1 / yes) |
Engineering Choices
Every architectural choice was deliberate. Here's the reasoning behind the most consequential ones.
Project Story
A system designed to bridge neuroscience, agentic AI, and Web3 provenance, all in a single runnable project.
Children with motor impairments need a non-invasive way to interact with digital environments. Raw EEG signals are noisy, high-dimensional, and clinically meaningless without interpretation, and any interpretation used in a therapeutic context must be auditable and tamper-evident to maintain trust with clinicians and families.
Design and build a complete BCI DApp pipeline that takes simulated Emotiv EPOC signals, classifies user intent with an LLM agent, and commits every interpretation to a cryptographically signed, hash-chained ledger, demonstrating rig-core agentic AI and Web3 blockchain architecture in a single screencast-ready project.
A fully runnable, screen-capturable demo showing EEG : LLM: signed provenance: verified chain in under 200 ms per session. Replacing _save/_load in MockBlockchainLedger with Anchor program calls produces a production Solana deployment, the signing, hashing, and classification layers are fully chain-agnostic and production-grade today.