# poornachandra-29/eeg-to-text architecture

> Architecture diagram of the GitHub repository poornachandra-29/eeg-to-text, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/poornachandra-29/eeg-to-text
- Repository: https://github.com/poornachandra-29/eeg-to-text

## Overview

This repository combines two products: EEG-to-text decoding and sentiment experiments, and NeuroRead, a research-grounded participant-analysis application. The documented experimental workflow prepares ZuCo and sentiment datasets, trains decoding/classification models, then evaluates decoding or the zero-shot sentiment pipeline. NeuroRead ingests scientific literature, analyzes participant measurements, grounds interpretations in retrieved evidence, and produces reports or serves a dashboard. Several NeuroRead orchestration links are visible in excerpts; unsampled model-training and evaluation internals are represented only at their documented boundaries.

Main entry points: [`neuroread_rag/main.py`](https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/main.py) (NeuroRead CLI), [`neuroread_rag/server.py`](https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/server.py) (Dashboard API), [`util/construct_dataset_mat_to_pickle_v1.py`](https://github.com/poornachandra-29/eeg-to-text/blob/main/util/construct_dataset_mat_to_pickle_v1.py) (Dataset preparation), [`neuroread_rag/retrieval/synthesizer.py`](https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/retrieval/synthesizer.py) (Evidence retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experiments["EEG Experiments"]
  node_prepare_data["Dataset preparation"]
  node_training_data["EEG dataset<br/>[data.py]"]
  node_decoder["EEG decoder<br/>[model_decoding.py]"]
  node_train_decode["Decoder training<br/>[train_decoding.py]"]
  node_eval_decode["Decoder evaluation<br/>[eval_decoding.py]"]
  node_sentiment_model["Sentiment classifier<br/>[model_sentiment.py]"]
  node_eval_sentiment["Sentiment evaluation<br/>[eval_sentiment.py]"]
end

subgraph group_literature["Research Literature"]
  node_discovery["Paper discovery<br/>[aggregator.py]"]
  node_ingestion["Literature ingestion<br/>[pipeline.py]"]
  node_vector_store[("Hybrid index<br/>[vector_store.py]")]
  node_synthesis["Evidence retrieval<br/>[synthesizer.py]"]
end

subgraph group_participant["Participant Analysis"]
  node_mat_processing["MAT processing<br/>[mat_processor.py]"]
  node_analysis["Participant analysis<br/>[analyzer.py]"]
end

subgraph group_interpretation["Grounded Results"]
  node_grounding["Scientific grounding"]
  node_recommendations["Recommendations<br/>[recommender.py]"]
end

subgraph group_delivery["Reports and Dashboard"]
  node_report["Report generation"]
  node_server["Dashboard API<br/>[server.py]"]
  node_frontend["Web dashboard<br/>[app.js]"]
  node_entrypoint["NeuroRead CLI<br/>[main.py]"]
end

node_researcher(("Researcher"))
node_zuco[("ZuCo data")]
node_sentiment_data[("Sentiment data")]
node_api_sources(("Academic sources"))
node_participant_input[("Participant data")]

node_researcher -->|"prepares datasets"| node_prepare_data
node_zuco -->|"supplies MAT files"| node_prepare_data
node_sentiment_data -->|"supplies labels"| node_prepare_data
node_prepare_data -->|"creates dataset"| node_training_data
node_training_data -->|"feeds training"| node_train_decode
node_train_decode -->|"trains"| node_decoder
node_researcher -->|"runs evaluation"| node_eval_decode
node_decoder -->|"evaluated by"| node_eval_decode
node_sentiment_data -->|"trains classifier"| node_sentiment_model
node_sentiment_model -->|"used in pipeline"| node_eval_sentiment
node_decoder -->|"decoded input"| node_eval_sentiment
node_researcher -->|"selects participant"| node_entrypoint
node_api_sources -->|"queried for papers"| node_discovery
node_discovery -->|"supplies papers"| node_ingestion
node_ingestion -->|"indexes literature"| node_vector_store
node_participant_input -->|"loads participant data"| node_mat_processing
node_mat_processing -.->|"produces measurements"| node_analysis
node_entrypoint -->|"runs analysis"| node_analysis
node_entrypoint -->|"runs ingestion"| node_ingestion
node_entrypoint -->|"opens index"| node_vector_store
node_entrypoint -->|"creates synthesizer"| node_synthesis
node_synthesis -->|"retrieves evidence"| node_vector_store
node_entrypoint -->|"grounds findings"| node_grounding
node_grounding -->|"uses synthesis"| node_synthesis
node_entrypoint -->|"generates report"| node_report
node_report -->|"renders recommendations"| node_recommendations
node_entrypoint -->|"launches server"| node_server
node_server -->|"serves dashboard"| node_frontend
node_server -->|"retrieves search results"| node_synthesis
node_server -->|"initializes grounding"| node_grounding
node_server -->|"initializes report"| node_report

click node_prepare_data "https://github.com/poornachandra-29/eeg-to-text/blob/main/util/construct_dataset_mat_to_pickle_v1.py"
click node_training_data "https://github.com/poornachandra-29/eeg-to-text/blob/main/data.py"
click node_decoder "https://github.com/poornachandra-29/eeg-to-text/blob/main/model_decoding.py"
click node_train_decode "https://github.com/poornachandra-29/eeg-to-text/blob/main/train_decoding.py"
click node_eval_decode "https://github.com/poornachandra-29/eeg-to-text/blob/main/eval_decoding.py"
click node_sentiment_model "https://github.com/poornachandra-29/eeg-to-text/blob/main/model_sentiment.py"
click node_eval_sentiment "https://github.com/poornachandra-29/eeg-to-text/blob/main/eval_sentiment.py"
click node_discovery "https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/discovery/aggregator.py"
click node_ingestion "https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/ingestion/pipeline.py"
click node_vector_store "https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/ingestion/vector_store.py"
click node_mat_processing "https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/participant_analysis/mat_processor.py"
click node_analysis "https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/participant_analysis/analyzer.py"
click node_synthesis "https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/retrieval/synthesizer.py"
click node_grounding "https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/interpretation/grounding_engine.py"
click node_recommendations "https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/recommendations/recommender.py"
click node_report "https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/reporting/report_generator.py"
click node_server "https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/server.py"
click node_frontend "https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/frontend/app.js"
click node_entrypoint "https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_prepare_data,node_training_data,node_decoder,node_train_decode,node_eval_decode,node_sentiment_model,node_eval_sentiment toneBlue
class node_discovery,node_ingestion,node_vector_store,node_synthesis,node_zuco,node_sentiment_data,node_participant_input toneAmber
class node_mat_processing,node_analysis toneMint
class node_grounding,node_recommendations toneRose
class node_report,node_server,node_frontend,node_entrypoint,node_researcher,node_api_sources toneIndigo
```

## Components

### EEG Experiments

- [Dataset preparation](https://github.com/poornachandra-29/eeg-to-text/blob/main/util/construct_dataset_mat_to_pickle_v1.py): `util/construct_dataset_mat_to_pickle_v1.py`
- [EEG dataset](https://github.com/poornachandra-29/eeg-to-text/blob/main/data.py): `data.py`
- [EEG decoder](https://github.com/poornachandra-29/eeg-to-text/blob/main/model_decoding.py): `model_decoding.py`
- [Decoder training](https://github.com/poornachandra-29/eeg-to-text/blob/main/train_decoding.py): `train_decoding.py`
- [Decoder evaluation](https://github.com/poornachandra-29/eeg-to-text/blob/main/eval_decoding.py): `eval_decoding.py`
- [Sentiment classifier](https://github.com/poornachandra-29/eeg-to-text/blob/main/model_sentiment.py): `model_sentiment.py`
- [Sentiment evaluation](https://github.com/poornachandra-29/eeg-to-text/blob/main/eval_sentiment.py): `eval_sentiment.py`

### Research Literature

- [Paper discovery](https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/discovery/aggregator.py): `neuroread_rag/discovery/aggregator.py`
- [Literature ingestion](https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/ingestion/pipeline.py): `neuroread_rag/ingestion/pipeline.py`
- [Hybrid index](https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/ingestion/vector_store.py): `neuroread_rag/ingestion/vector_store.py`
- [Evidence retrieval](https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/retrieval/synthesizer.py): `neuroread_rag/retrieval/synthesizer.py`

### Participant Analysis

- [MAT processing](https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/participant_analysis/mat_processor.py): `neuroread_rag/participant_analysis/mat_processor.py`
- [Participant analysis](https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/participant_analysis/analyzer.py): `neuroread_rag/participant_analysis/analyzer.py`

### Grounded Results

- [Scientific grounding](https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/interpretation/grounding_engine.py): `neuroread_rag/interpretation/grounding_engine.py`
- [Recommendations](https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/recommendations/recommender.py): `neuroread_rag/recommendations/recommender.py`

### Reports and Dashboard

- [Report generation](https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/reporting/report_generator.py): `neuroread_rag/reporting/report_generator.py`
- [Dashboard API](https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/server.py): `neuroread_rag/server.py`
- [Web dashboard](https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/frontend/app.js): `neuroread_rag/frontend/app.js`
- [NeuroRead CLI](https://github.com/poornachandra-29/eeg-to-text/blob/main/neuroread_rag/main.py): `neuroread_rag/main.py`

### Other components

- **Researcher**
- **ZuCo data**
- **Sentiment data**
- **Academic sources**
- **Participant data**

## Connections

- Researcher → Dataset preparation: prepares datasets (evidence: `README.md`)
- ZuCo data → Dataset preparation: supplies MAT files (evidence: `README.md`)
- Sentiment data → Dataset preparation: supplies labels (evidence: `README.md`)
- Dataset preparation → EEG dataset: creates dataset (evidence: `README.md`)
- EEG dataset → Decoder training: feeds training (evidence: `train_decoding.py`)
- Decoder training → EEG decoder: trains (evidence: `train_decoding.py`)
- Researcher → Decoder evaluation: runs evaluation (evidence: `README.md`)
- EEG decoder → Decoder evaluation: evaluated by (evidence: `README.md`)
- Sentiment data → Sentiment classifier: trains classifier (evidence: `README.md`)
- Sentiment classifier → Sentiment evaluation: used in pipeline (evidence: `README.md`)
- EEG decoder → Sentiment evaluation: decoded input (evidence: `README.md`)
- Researcher → NeuroRead CLI: selects participant (evidence: `neuroread_rag/main.py`)
- Academic sources → Paper discovery: queried for papers (evidence: `neuroread_rag/discovery/aggregator.py`)
- Paper discovery → Literature ingestion: supplies papers (evidence: `neuroread_rag/ingestion/pipeline.py`)
- Literature ingestion → Hybrid index: indexes literature (evidence: `neuroread_rag/ingestion/pipeline.py`)
- Participant data → MAT processing: loads participant data
- MAT processing → Participant analysis: produces measurements
- NeuroRead CLI → Participant analysis: runs analysis (evidence: `neuroread_rag/main.py`)
- NeuroRead CLI → Literature ingestion: runs ingestion (evidence: `neuroread_rag/main.py`)
- NeuroRead CLI → Hybrid index: opens index (evidence: `neuroread_rag/main.py`)
- NeuroRead CLI → Evidence retrieval: creates synthesizer (evidence: `neuroread_rag/main.py`)
- Evidence retrieval → Hybrid index: retrieves evidence (evidence: `neuroread_rag/retrieval/synthesizer.py`)
- NeuroRead CLI → Scientific grounding: grounds findings (evidence: `neuroread_rag/main.py`)
- Scientific grounding → Evidence retrieval: uses synthesis (evidence: `neuroread_rag/interpretation/grounding_engine.py`)
- NeuroRead CLI → Report generation: generates report (evidence: `neuroread_rag/main.py`)
- Report generation → Recommendations: renders recommendations (evidence: `neuroread_rag/reporting/report_generator.py`)
- NeuroRead CLI → Dashboard API: launches server (evidence: `neuroread_rag/main.py`)
- Dashboard API → Web dashboard: serves dashboard (evidence: `neuroread_rag/server.py`)
- Dashboard API → Evidence retrieval: retrieves search results (evidence: `neuroread_rag/server.py`)
- Dashboard API → Scientific grounding: initializes grounding (evidence: `neuroread_rag/server.py`)
- Dashboard API → Report generation: initializes report (evidence: `neuroread_rag/server.py`)