README.md

---
title: Epilepsy Management AI Agent
emoji: 🧠
colorFrom: red
colorTo: purple
sdk: docker
app_port: 7860
tags:
- streamlit
- medical-ai
- epilepsy
- chromadb
- semantic-search
- healthcare
pinned: false
license: apache-2.0
short_description: AI-powered epilepsy device recommendations
---

# 🧠 Epilepsy Management AI Agent

AI-powered medical device recommendation system for epilepsy management using semantic search, safety filtering, and evidence-based ranking.

## 🎯 What This App Does

This Streamlit application helps clinicians and patients explore epilepsy management devices based on patient-specific descriptions. It uses:

- **Semantic Search**: ChromaDB + Sentence Transformers for intelligent device matching
- **Safety Rules**: Configurable filters for invasiveness and regulatory approvals (FDA/CE)
- **Interactive UI**: Multi-page interface with device catalog, admin tools, and recommendations

## ✨ Features

- 📝 **Patient Input → Smart Recommendations**: Describe patient condition and receive personalized device suggestions
- 🔍 **Semantic Search**: Uses `all-MiniLM-L6-v2` embeddings for intelligent text matching
- 🛡️ **Safety Filters**: Toggle invasive device filtering and requirement for specific approvals
- 📚 **Device Catalog**: Browse and search the complete knowledge base
- 🛠️ **Admin Tools**: Upload CSV data and rebuild vector index
- 📊 **Detailed Results**: View device specifications, approvals, indications, and source links

## 🚀 How to Use

1. **Enter Patient Description**: Describe the patient's epilepsy characteristics (seizure type, frequency, age, lifestyle needs)
2. **Configure Filters**: 
   - Toggle "Avoid invasive devices" on/off
   - Specify required approvals (e.g., "FDA, CE")
   - Adjust top K results (1-10)
3. **Generate Recommendations**: Click the button to get AI-filtered device suggestions
4. **Explore Results**: View device details, click source links, and browse the full catalog

## 📋 Example Query

> "16-year-old with focal aware seizures 2–3 times/week, mostly nocturnal; wants non-invasive detection and caregiver alerts."

## 🏗️ Architecture

```
Patient Input → Semantic Search (ChromaDB) 
             → Safety Rules Filtering 
             → Ranked Recommendations 
             → Interactive Display
```

### Technologies
- **Streamlit**: Web UI framework
- **ChromaDB**: Vector database for semantic search
- **Sentence Transformers**: Text embeddings (all-MiniLM-L6-v2)
- **Pandas**: Data manipulation
- **Python 3.11**: Runtime environment

## 📁 Project Structure

```
Epilepsy-Management-AI-Agent/
├── src/
│   └── app.py              # Main Streamlit application
├── pages/
│   ├── 1_📚_Device_Catalog.py    # Browse all devices
│   ├── 2_🛠️_Admin_ETL.py        # CSV upload & index rebuild
│   └── 3_ℹ️_About.py            # Project information
├── data/
│   └── devices.csv          # Device catalog database
├── utils/
│   ├── embeddings.py        # ChromaDB integration
│   └── rules.py            # Safety rule filtering
├── requirements.txt         # Python dependencies
├── Dockerfile              # Container configuration
└── README.md              # This file
```

## ⚙️ Deployment

This app is containerized using Docker and deployed on Hugging Face Spaces.

### Local Development
```bash
# Build and run
docker build -t epilepsy-ai .
docker run -p 7860:7860 epilepsy-ai

# Or with Streamlit directly
pip install -r requirements.txt
streamlit run src/app.py
```

## 📊 Data Model

The device catalog (`data/devices.csv`) includes:
- `device_id`: Unique identifier
- `name`: Device name
- `category`: Device type (wearable, implant, etc.)
- `indication`: Use case
- `invasiveness`: Invasive/Non-invasive
- `approvals`: Regulatory status (FDA, CE, etc.)
- `summary`: Description text
- `source_url`: Reference link
- `last_seen`: Timestamp

## ⚠️ Important Notice

This tool provides **informational recommendations only** and is **not a substitute for professional medical advice**. Always consult a licensed clinician for diagnosis and treatment decisions.

## 🔧 Configuration

- **ChromaDB**: Persists in `.chroma/` directory (rebuilds automatically on HF Spaces)
- **Model**: `sentence-transformers/all-MiniLM-L6-v2` (~80MB, downloads on first run)
- **Port**: 7860 (Hugging Face default)

## 📝 License

Apache 2.0

## 👥 Contributing

Feel free to submit issues or improvements to the device catalog or codebase.

---

Built with ❤️ for epilepsy management and healthcare innovation.