How mwasifanwar/biosignal-ai works
Project Type and Purpose
• Project type: a full-stack, Python-based machine-learning inference and API service for interpreting EEG/fMRI signals.
• Purpose: ingest biosignals, preprocess them, run decoding models (traditional and deep learning), expose results via a REST API, and drive external devices or diagnostics.
File Structure
• Top-level scripts:
• main.py – likely a CLI or orchestrator for batch processing.
• run_api.py – entrypoint for the web/API service.
• setup.py, requirements.txt – packaging and dependencies.
• Directories:
• api/ – REST API layer: routing (routes.py) and middleware.
• config/ – application and model configuration (settings.py, model_config.py).
• core/ – core processing pipeline:
– bci_controller.py (interfaces to devices),
– eeg_processor.py (signal preprocessing),
– fmri_analyzer.py,
– neural_decoder.py (orchestration of model inference).
• models/ – ML components:
– traditional_models.py (classical ML),
– deep_models.py (deep-learning architectures).
• utils/ – supporting utilities:
– data_loader.py, signal_utils.py, visualization.py.
• tests/ – unit & integration tests.
Extract Insights from README
• Key functions: control devices, predict disorders, enable BCI.
• Core technologies implied: Python, NumPy/SciPy, ML frameworks (e.g., PyTorch/TensorFlow, scikit-learn), FastAPI (inferred from api/).
Main Components and Their Relationships
a. Data Inputs
– EEG sensors
– fMRI scanners
b. Data Ingestion & Preprocessing
– utils/data_loader.py loads raw signals.
– core/eeg_processor.py and core/fmri_analyzer.py clean and transform data.
c. Neural Decoding & Prediction
– core/neural_decoder.py selects model (based on config/model_config.py).
– models/traditional_models.py for classical algorithms.
– models/deep_models.py for neural nets.
d. BCI Control Layer
– core/bci_controller.py translates model outputs into device commands.
e. API Layer
– run_api.py launches the REST service.
– api/routes.py defines endpoints for:
• submitting new signal data
• retrieving predictions or control commands
– api/middleware.py handles auth, logging, error handling.
f. Configuration & Settings
– config/settings.py manages environment variables and global settings.
g. Utilities & Visualization
– utils/visualization.py for plotting results (used in dashboards or logs).
Architectural Patterns & Principles
• Layered architecture:
• Ingestion → Processing → Inference → Serving.
• Clear separation of concerns:
• “api” vs. “core” vs. “models” vs. “utils”.
• Config-driven behavior (model selection, hyperparameters).
• Test-driven reliability (py.test suite in tests/).