README.md

---
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

```bash
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](https://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