README.md

metadata

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

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

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

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:

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:

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

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

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.