README.md

---
license: mit
title: NLPforASD
sdk: gradio
emoji: 🏢
colorFrom: blue
colorTo: purple
short_description: Profile-adaptive RAG chatbot for Autism Spectrum Disorder in
---

#  NLP4ASD — Autism Spectrum Disorder Specialized Chatbot

A RAG-powered chatbot that answers questions about Autism Spectrum Disorder using scientific sources.
Answers adapt dynamically based on the user's profile.

---

##  What It Does

1. User selects a **profile** (Parent, Patient, Healthcare Professional, Teacher, Researcher)
2. User asks a question about ASD
3. The system **retrieves the most relevant scientific passages** from a local knowledge base
4. It builds a **profile-adapted prompt** and generates a grounded answer
5. Sources are displayed alongside the answer

No answer is generated without retrieved evidence — the chatbot is grounded, not free-form.

---

## 📁 Project Structure

```
NLP4ASD/
├── app.py                        # Gradio interface (entry point)
├── requirements.txt
├── README.md
│
├── data/
│   ├── raw/                      # Plain .txt scientific documents (your corpus)
│   ├── processed/                # Auto-generated: FAISS index + chunk JSON
│   └── sources_metadata.json     # Document registry
│
├── src/
│   ├── config.py                 # All tunable settings (models, paths, parameters)
│   ├── data_loader.py            # Load .txt files from data/raw/
│   ├── preprocessing.py          # Clean raw text
│   ├── chunking.py               # Split text into overlapping chunks
│   ├── embeddings.py             # Encode chunks with SentenceTransformers
│   ├── vector_store.py           # Build, save, and load FAISS index
│   ├── retriever.py              # Retrieve top-k relevant chunks
│   ├── prompt_builder.py         # Build adaptive prompts per profile
│   ├── generator.py              # Generate answer with HF model
│   ├── rag_pipeline.py           # Orchestrate full pipeline
│   └── utils.py                  # File helpers
│
└── notebooks/
    └── build_knowledge_base.ipynb  # Interactive knowledge base builder
```

---

## 🚀 Quick Start (Local)

### 1. Install dependencies
```bash
pip install -r requirements.txt
```

### 2. Add your documents
Place plain `.txt` files in `data/raw/`. The project includes 4 sample documents.

### 3. Build the knowledge base
```bash
python -c "from src.rag_pipeline import build_knowledge_base; build_knowledge_base()"
```
This embeds all documents and creates the FAISS index in `data/processed/`.

### 4. Run the app
```bash
python app.py
```
Open the local URL shown in your terminal.

---

## 🤗 Deploy to Hugging Face Spaces

1. Create a new Space (type: **Gradio**)
2. Push the full project:
```bash
git init
git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/NLP4ASD
git add .
git commit -m "Initial commit"
git push origin main
```
3. The Space will auto-install `requirements.txt` and launch `app.py`
4. On first start, the knowledge base is built automatically from `data/raw/`

> **Tip:** For faster startup, commit `data/processed/` (index + chunks) to avoid rebuilding on every cold start.

---

## ⚙️ Configuration

All key settings are in `src/config.py`:

| Setting | Default | Description |
|---------|---------|-------------|
| `EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | SentenceTransformer model |
| `GENERATOR_MODEL` | `google/flan-t5-base` | HF generation model |
| `CHUNK_SIZE` | `512` | Characters per chunk |
| `CHUNK_OVERLAP` | `64` | Overlap between chunks |
| `TOP_K` | `4` | Chunks retrieved per query |
| `MAX_NEW_TOKENS` | `512` | Max tokens generated |
| `TEMPERATURE` | `0.3` | Generation temperature |

---

## 🔄 Switching to a Better Model

To use a more powerful model, change `GENERATOR_MODEL` in `src/config.py`:

```python
# Biomedical-focused
GENERATOR_MODEL = "BioMistral/BioMistral-7B"

# Instruction-following
GENERATOR_MODEL = "mistralai/Mistral-7B-Instruct-v0.2"
GENERATOR_MODEL = "google/gemma-2b-it"

# Medical LLM
GENERATOR_MODEL = "meta-llama/Llama-3-8B-Instruct"
```

For 7B+ models on Spaces, use a **GPU Space** (T4 or A10) and enable 4-bit quantization:
```python
# In src/generator.py, replace the pipeline() call with:
from transformers import BitsAndBytesConfig
quantization_config = BitsAndBytesConfig(load_in_4bit=True)
model = AutoModelForCausalLM.from_pretrained(
    GENERATOR_MODEL,
    quantization_config=quantization_config,
    device_map="auto",
)
```

---

## 🔬 Future: LoRA / QLoRA Fine-Tuning

To fine-tune the generation model on ASD-specific data, insert the following step between `generator.py` (base model loading) and deployment:

### Where to add it
Create `src/fine_tuning.py` with:

```python
from peft import LoraConfig, get_peft_model, TaskType
from transformers import TrainingArguments, Trainer

# 1. Define LoRA configuration
lora_config = LoraConfig(
    r=16,                        # rank
    lora_alpha=32,
    target_modules=["q_proj", "v_proj"],  # for LLaMA/Mistral
    lora_dropout=0.05,
    bias="none",
    task_type=TaskType.CAUSAL_LM,
)

# 2. Wrap base model
model = get_peft_model(base_model, lora_config)

# 3. Prepare dataset: (prompt, expected_answer) pairs
# Use clinical Q&A from published ASD literature

# 4. Train
training_args = TrainingArguments(
    output_dir="./lora_checkpoints",
    per_device_train_batch_size=2,
    gradient_accumulation_steps=4,
    num_train_epochs=3,
    fp16=True,
    logging_steps=10,
    save_strategy="epoch",
)
trainer = Trainer(model=model, args=training_args, train_dataset=dataset)
trainer.train()

# 5. Save adapter (NOT full model weights — only ~10MB)
model.save_pretrained("./lora_adapter")

# 6. In generator.py, load with:
# from peft import PeftModel
# model = PeftModel.from_pretrained(base_model, "./lora_adapter")
```

QLoRA reduces VRAM requirements to ~6GB for a 7B model, enabling fine-tuning on a single consumer GPU.

---

## 🌍 Adding French Support

The prompt builder (`src/prompt_builder.py`) already supports French via `LANGUAGE_INSTRUCTIONS`.
To add translated profile instructions, extend `PROFILE_INSTRUCTIONS` with French keys or add a `_fr` suffix per profile.

---

## ⚠️ Disclaimer

NLP4ASD is a research prototype. It is not a medical device and does not provide professional medical advice.
All answers are grounded in retrieved scientific documents and should be verified by qualified professionals.

---

## 📄 License

MIT License — see `LICENSE` for details.