README.md

metadata

title: NeuroLens
emoji: 🧠
colorFrom: purple
colorTo: blue
sdk: streamlit
sdk_version: 1.38.0
python_version: '3.11'
app_file: app.py
pinned: false

NeuroLens

Cognitive Health Screening & Coaching Pipeline

NeuroLens is a three-stage system that takes a short conversational language assessment, extracts linguistic biomarkers documented in the cognitive-aging research literature, and generates a citation-grounded, retrieval-augmented prevention coaching summary.

Live demo: add your HuggingFace Spaces link here after deploying Author: Kshamaa

---

Overview

Stage 1	Conversational cognitive assessment — timed verbal fluency, narrative description, delayed recall
Stage 2	NLP-based linguistic biomarker extraction (spaCy / NLTK)
Stage 3	Retrieval-augmented generation over a curated literature corpus, with an automated faithfulness check

The project was built to demonstrate applied NLP and RAG system design in a health-adjacent domain, with explicit attention to scientific grounding, citation discipline, and output evaluation — engineering practices that matter disproportionately when a system touches health-related content.

---

Disclaimer

This is a research and engineering demonstration prototype, not a validated clinical or diagnostic tool. It is inspired by published, peer-reviewed cognitive-linguistic assessment paradigms (verbal fluency, narrative description, delayed recall), with the following caveats:

• It has not been clinically validated against any diagnostic gold standard.
• Its reference ranges are rough midpoints drawn from published study ranges, not a clinically derived normative dataset.
• Language samples are typed, not spoken, and collected in an unsupervised setting — both differ materially from standardized clinical administration.
• A production deployment in this space would require IRB-reviewed prospective studies, licensed clinical oversight, and regulatory review.

The system is designed to demonstrate AI engineering — NLP feature extraction, retrieval-augmented generation, and faithfulness evaluation — applied with genuine literacy in the underlying scientific domain.

---

Architecture

Stage 1: Conversational Assessment (Streamlit)
   → semantic fluency, phonemic fluency, narrative description, delayed recall
        ↓
Stage 2: Linguistic Biomarker Extraction (spaCy / NLTK)
   → lexical diversity (TTR/MATTR), fluency counts, syntactic complexity,
     disfluency rate, approximate idea density
        ↓
Stage 3: Grounded Prevention Coaching (RAG)
   → retrieval over a curated 18-paper corpus (e5-large-v2 + FAISS, with a
     TF-IDF fallback) → generated summary (openai/gpt-oss-120b via Groq)
     → RAGAS-style faithfulness check against retrieved sources

Repository Structure

.
├── app.py              # Streamlit application — all three stages
├── biomarkers.py        # Stage 2: NLP feature extraction
├── rag_engine.py         # Stage 3: retrieval, generation, faithfulness check
├── data/
│   └── corpus.json        # Curated literature corpus (18 entries)
├── requirements.txt
└── README.md

---

Stage 2 — Linguistic Biomarkers

Marker	What it measures	Research basis
Semantic (category) fluency	Unique animals named in 60 seconds	One of the most-replicated early markers of cognitive decline; shown to decline faster than letter fluency specifically in those at elevated Alzheimer's risk (longitudinal cohort, n=2,261; PMC7403823). Also shown to meaningfully discriminate normal aging / MCI / AD (PMC9153280).
Phonemic (letter) fluency	Unique F-words named in 60 seconds	Standard companion measure to semantic fluency; tends to remain stable until closer to dementia onset (PMC7403823).
Lexical diversity (TTR / MATTR)	Vocabulary variety, length-corrected	Reduced lexical diversity is associated with reduced vocabulary access in spontaneous speech (Covington & McFall, 2010).
Approximate idea density	Propositions per 10 words (POS-based approximation)	Modeled on the Nun Study: idea density in autobiographies written at ~age 22 predicted Alzheimer's neuropathology roughly 60 years later (Snowdon et al., 1996; retrospective analysis, PMC11852352). This implementation uses a simplified POS-tag-based approximation, not the original CPIDR scoring system.
Syntactic complexity	Subordination index, clause density	Simplified sentence structure has been associated with increased cognitive load during language production.
Delayed recall	Words correctly recalled after a distractor task	Standard episodic memory paradigm, simplified here.

Validation extension (planned, not yet executed)

Biomarker extraction could be validated against the DementiaBank Pitt Corpus — transcribed Cookie Theft picture descriptions from healthy controls and dementia patients (Becker et al., 1994). This corpus is access-gated (approved-research-use only via TalkBank/DementiaBank), so it remains a documented next step rather than something bundled into the repo.

---

Stage 3 — Literature Corpus & Retrieval

The corpus (data/corpus.json) contains 18 entries across six domains, each summarized in original prose with source attribution and a link to the original publication:

• APOE4 genetics × lifestyle interaction — meta-analysis of FINGER, MAPT, and J-MINT (n>3,400) finding lifestyle intervention benefits APOE4 carriers as much as or more than non-carriers (PMC12726239).
• Exercise & cognitive reserve — mechanistic and outcome evidence linking physical activity to neuroplasticity, glymphatic clearance, and preserved executive function.
• Diet & nutrition — the MIND diet RCT (NEJM, 2023) alongside a field-wide caution piece (Nature, 2025) on the limits of diet-only effects relative to combined multidomain interventions.
• Cognitive training — the FINGER trial and its global WW-FINGERS adaptations (~70 countries), showing ~25% greater cognitive improvement in the multidomain intervention group versus control.
• Social engagement — social activity as a structural component of FINGER-style trials, including digitally-delivered versions.
• Cognitive reserve / early-life enrichment — the Nun Study's idea density findings and related exercise results.

Retrieval is marker-driven: a Stage 2 score below the reference range triggers retrieval from the literature domain most relevant to that specific marker (e.g., low semantic fluency → cognitive training and social engagement literature), rather than relying on raw text similarity alone.

Faithfulness evaluation

Every generated coaching summary is checked with a second model call (openai/gpt-oss-120b via Groq) that decomposes the text into individual factual claims and verdicts each as SUPPORTED / PARTIAL / UNSUPPORTED against the retrieved source excerpts — a RAGAS-style faithfulness check, surfaced in the app's "Faithfulness check" panel. This is treated as the most important evaluation step in the pipeline: given the health-adjacent subject matter, demonstrating that the system catches its own unsupported claims matters more here than in a typical RAG demo.

---

Setup

Local installation

pip install -r requirements.txt
python -m spacy download en_core_web_sm   # if not already pulled via requirements.txt
export GROQ_API_KEY=your_key_here
streamlit run app.py

A Groq API key is required for Stage 3 generation: create one at console.groq.com under API Keys.

Deployment (HuggingFace Spaces)

1. Create a new Space (SDK: Streamlit).
2. Push app.py, biomarkers.py, rag_engine.py, data/corpus.json, and requirements.txt.
3. Add GROQ_API_KEY as a Space secret under Settings → Variables and secrets.
4. On first run, the app downloads the spaCy model and the e5-large-v2 sentence-embedding model. If sentence-transformers or its weights are unavailable for any reason, the retriever automatically falls back to a TF-IDF retriever (rag_engine.py: LiteratureRetriever), so the pipeline degrades gracefully rather than failing.

---

Known Limitations

• Reference ranges are literature-informed approximations, not a validated clinical normative sample — flagged explicitly in the app.
• Typed responses differ from spoken responses; several markers (disfluency, timing) are conventionally derived from speech, not text.
• Fluency tasks use an enforced 60-second countdown (30 seconds for the recall distractor), implemented via periodic Streamlit reruns rather than a client-side timer — accurate to roughly one second, sufficient for this use case.
• Idea density is a simplified POS-based approximation of the Snowdon/Kemper method, not the original CPIDR scoring tool.
• The animal/F-word validity lists used for fluency scoring are compact, curated lists rather than an exhaustive lexical resource; uncommon but valid answers may be flagged as "possible intrusions" rather than counted.
• No clinical validation has been performed; DementiaBank validation is a documented next step pending approved data access.

Future Work

• Speech-to-text capture for analysis of true spoken language
• Client-side (JS-based) frame-accurate timing
• DementiaBank Pitt Corpus validation, reporting a basic separation result (e.g. effect size) between healthy-control and dementia transcripts
• Expansion of the literature corpus and per-domain retrieval re-ranking
• Opt-in longitudinal tracking of results across multiple sessions