Add seizure workshop

README.md

@@ -164,6 +164,7 @@ Explore the diverse range of projects available in this repository. Each link ta
 *   [`recap/`](./recap/) - **Workshop Recap:** A summary of key learnings and advancements made since the inception of the Gemini workshops, presented as a slide deck. ([📊 slides](https://google-gemini.github.io/workshops/recap))
 *   [`roast/`](./roast/) - **AI Roast Battle Arena: Uncensored Wit with LLMs:** Showcases a dynamic, multi-agent AI system designed to host uncensored roast battles between different LLMs, with an independent third LLM acting as an impartial judge.
 *   [`scripts/`](./scripts/) - **LLM-Powered Content Generation & Developer Experience:** A robust framework for generating various content types, including presentation slides and factual summaries, powered by LLMs, emphasizing efficient developer workflows.
+*   [`seizure/`](./seizure/) - **SeizureScoreAI: Seizure outcome scoring with Gemini:** A multi-agent clinical reasoning system for ILAE seizure outcome scoring after epilepsy surgery (Streamlit + Google ADK + Gemini).
 *   [`startupcon/`](./startupcon/) - **StartupCon Talk:** Workshop presentation on building with Gemini and AI agents. ([📊 slides](https://google-gemini.github.io/workshops/startupcon))
 *   [`smash/`](./smash/) - **Smash Bot: An LLM-Powered Fighting Game Agent:** A cutting-edge AI agent capable of playing a fighting game (like Super Smash Bros.) by observing the game state and controlling a virtual gamepad, powered by a multimodal LLM. ([📊 slides](https://google-gemini.github.io/workshops/smash))
 *   [`tv/`](./tv/) - **TV Companion: Your AI Film Critic and Controller:** An advanced LLM-powered assistant that "watches" movies and shows in real-time, offering insightful commentary, deep-diving into film trivia, and controlling your TV through natural voice commands.
@@ -201,6 +202,7 @@ Projects focusing on practical applications of LLMs, multi-agent systems, and re
 *   [`factuality/`](./factuality/) - Factuality: News Summarization & Redaction
 *   [`kundali/`](./kundali/) - Kundali Milan: AI Jyotish Guru
 *   [`roast/`](./roast/) - AI Roast Battle Arena: Uncensored Wit with LLMs
+*   [`seizure/`](./seizure/) - SeizureScoreAI: ILAE seizure outcome scoring with Gemini
 *   [`tv/`](./tv/) - TV Companion: Your AI Film Critic and Controller
 *   [`utils/`](./utils/) - LLM Demonstration Workshop Project
 

seizure/.dockerignore

@@ -0,0 +1,5 @@
+__pycache__
+*.pyc
+.env
+.git
+

seizure/.env.example

@@ -0,0 +1,2 @@
+# Google Gemini API Configuration
+GEMINI_API_KEY=your_gemini_api_key_here

seizure/.gitignore

@@ -0,0 +1,30 @@
+# Environment variables
+.env
+.env.*
+!.env.example
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Jupyter Notebook
+.ipynb_checkpoints
+*.ipynb_checkpoints
+
+# VS Code settings
+.vscode/
+
+# macOS system files
+.DS_Store
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+
+# Generated notes
+generated_notes/
+
+# Deprecated code
+deprecated_code/

seizure/CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing to SeizureScoreAI
+
+## Setup
+
+1. Clone the repo
+2. Install dependencies: `pip install -r requirements.txt`
+3. Add your `GEMINI_API_KEY` to a `.env` file
+4. Run: `streamlit run app/streamlit_app.py`
+
+## Contributors
+
+### AI ATL Hackathon Team
+
+- **[Vineet Reddy](https://github.com/vineet-reddy):** Conceived the idea to analyze epilepsy clinic notes and output ILAE scores. Developed the original Named Entity Recognition (NER) system with Viresh Pati. (NER system now deprecated)
+- **[Viresh Pati](https://github.com/vireshpati):** Co-designed the initial NER and designed the initial knowledge graph retrieval-augmented generation (KG RAG) system. (NER & KG RAG system now deprecated)
+- **[Mukesh Paranthaman](https://github.com/MukProgram):** Co-built the backend for the original NER and KG RAG system. (NER & KG RAG system now deprecated)
+- **[Sachi Goel](https://github.com/computer-s-2):** Designed the initial Streamlit frontend
+- **[Ananda Badari](https://github.com/abadari3):**  Developed logic for predicting ILAE and Engel scores using knowledge graphs. (KG logic now deprecated)
+
+### Post-Hackathon Development
+
+- **[Vineet Reddy](https://github.com/vineet-reddy):** Complete rewrite using Google Agent Development Kit (ADK) with multi-agent architecture
+
+---
+
+**Citation:** The ILAE Outcome Scale is sourced from [MGH Epilepsy Service](https://seizure.mgh.harvard.edu/engel-surgical-outcome-scale/).

seizure/Dockerfile

@@ -0,0 +1,18 @@
+# Use a lightweight base image
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Copy all code first (needed for setup.py)
+COPY . .
+
+# Install requirements and local package
+RUN pip install --no-cache-dir -r requirements.txt && pip install --no-cache-dir .
+
+# Set port for Cloud Run
+ENV PORT=8080
+EXPOSE 8080
+
+# Start Streamlit
+CMD ["bash", "-lc", "streamlit run app/streamlit_app.py --server.port $PORT --server.address 0.0.0.0"]
+

seizure/README.md

@@ -0,0 +1,178 @@
+# SeizureScoreAI: Multi-Agent Clinical Reasoning System
+
+A multi-agent system designed to emulate epileptologist decision-making for ILAE outcome scoring after epilepsy surgery. Built with **Google's Agent Development Kit (ADK)**, the system uses Gemini 3 Flash models in a sequential agent pipeline to process clinical notes and evaluate post-surgical outcomes. The goal is to teach an LLM to reason like an epileptologist.
+
+## Overview
+
+SeizureScoreAI employs a three-agent pipeline to process clinical notes and determine ILAE (International League Against Epilepsy) outcome scores:
+
+1. **Clinical Information Extractor**: Analyzes clinical notes to extract key metrics including:
+   - Presence of seizure freedom
+   - Presence of auras
+   - Baseline seizure frequency (pre-treatment)
+   - Post-treatment seizure frequency
+
+2. **ILAE Score Calculator**: Applies expertise to:
+   - Process extracted clinical information
+   - Calculate ILAE outcome scores based on standard criteria
+   - Provide detailed reasoning for score determination
+
+3. **Concise Reporter**: Generates clear, concise summaries of:
+   - Final ILAE score
+   - Key factors influencing the score
+   - Clinical reasoning behind the determination
+
+## Technical Architecture
+
+### Components
+
+- **Frontend**: Streamlit interface for clinical note input and result display
+- **Backend**: Multi-agent system built with **Google Agent Development Kit (ADK)**
+- **Agent Framework**: Sequential pipeline using ADK's `LlmAgent` class
+- **Model**: Gemini 3 Flash Preview (`gemini-3-flash-preview`)
+- **Session Management**: In-memory session service for agent state
+- **Structured Output**: JSON-formatted data for consistent processing between agents
+
+### Data Flow
+
+```
+Clinical Note → [Agent 1: Extract] → Structured Data → [Agent 2: Calculate] → ILAE Score + Reasoning → [Agent 3: Summarize] → Final Output
+```
+
+1. Clinical note input → Information Extraction (JSON)
+2. Structured entities → ILAE Score Calculation
+3. Detailed analysis → Concise Reporting
+4. Final output → User presentation with highlighted supporting text
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.8+
+- Google Gemini API key
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/vineet-reddy/SeizureScoreAI.git
+cd SeizureScoreAI
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Set up environment variables
+echo "GEMINI_API_KEY=your_api_key_here" > .env
+```
+
+### Usage
+
+Run the Streamlit application:
+
+```bash
+streamlit run app/streamlit_app.py
+```
+
+The application will:
+1. Accept clinical notes as input (via file upload)
+2. Process them through the three-agent pipeline
+3. Return ILAE scores with explanations
+4. Display the clinical note with highlighted supporting text
+
+## ILAE Outcome Scale
+
+The system evaluates surgical outcomes based on the following scale[^1]:
+
+| Class | Outcome |
+|-------|---------|
+| **1** | Completely seizure free; no auras |
+| **2** | Only auras; no other seizures |
+| **3** | 1-3 seizure days per year; ± auras |
+| **4** | 4 seizure days per year to 50% reduction of baseline seizure days; ± auras |
+| **5** | Less than 50% reduction of baseline seizure days; ± auras |
+| **6** | More than 100% increase of baseline seizure days; ± auras |
+
+[^1]: Source: [MGH Epilepsy Service - Epilepsy Surgery Outcome Scales](https://seizure.mgh.harvard.edu/engel-surgical-outcome-scale/)
+
+## Project Structure
+
+```
+SeizureScoreAI/
+├── src/
+│   └── seizure_score_ai/
+│       ├── __init__.py           # Package initialization
+│       └── agents.py             # Multi-agent pipeline using Google ADK
+├── app/
+│   ├── streamlit_app.py          # Streamlit frontend
+│   ├── config.toml               # Streamlit configuration
+│   └── example_notes/            # Example clinical notes for demo
+│       ├── ilaeclass1.txt
+│       ├── ilaeclass2.txt
+│       └── ilaeclass3.txt
+├── scripts/
+│   └── generate_clinic_notes.py  # Synthetic clinic note generator
+├── tests/
+│   ├── test_adk_agents.py        # ADK agent tests
+│   └── test_gemini.py            # API verification test
+├── data/
+│   └── test_notes/               # Sample clinical notes (synthetic)
+├── generated_notes/              # Generated synthetic notes
+├── docs/                         # Documentation
+├── .env                          # Environment variables (not in repo)
+├── requirements.txt              # Python dependencies
+├── setup.py                      # Package setup
+├── Dockerfile                    # Docker configuration
+└── README.md                     # This file
+```
+
+## Technology Stack
+
+| Component | Technology |
+|-----------|------------|
+| **AI Framework** | [Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/) `>=0.3.0` |
+| **LLM Model** | Gemini 3 Flash Preview |
+| **Frontend** | Streamlit `>=1.40.0` |
+| **Language** | Python 3.8+ |
+| **Environment** | python-dotenv for secure API key handling |
+
+### Key Dependencies
+
+```
+google-adk>=0.3.0
+streamlit>=1.40.0
+python-dotenv>=1.0.0
+```
+
+## Testing
+
+The system includes **synthetically generated test clinical notes** in the `data/test_notes/` directory, representing various post-surgical outcomes and clinical scenarios. These notes are designed to simulate real-world inputs but **do not contain any Protected Health Information (PHI)**.
+
+Example notes demonstrating different ILAE classes are available in `app/example_notes/` for demo purposes.
+
+## Security Considerations
+
+> **Important**: This system is **not HIPAA compliant**. Do not upload documents containing Protected Health Information (PHI).
+
+- API keys are managed through environment variables (`.env` file)
+- Never commit `.env` files to version control
+- Streamlit Cloud secrets provide secure deployment options
+
+## Limitations
+
+- Requires high-quality clinical notes for accurate scoring
+- LLM responses may vary slightly between runs
+- System should be used as a support tool, not a replacement for clinical judgment
+- Performance depends on the quality and completeness of input clinical notes
+- May return "indeterminate" if key clinical information is missing from the note
+
+## Contributing
+
+Interested in contributing? Check out [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to get started!
+
+## Project History
+
+This project originated as a proof-of-concept at the 2024 AI ATL Hackathon and has since undergone a complete architectural rewrite. The current implementation uses Google's Agent Development Kit with a multi-agent system, representing a fundamental redesign from the original NER/Knowledge Graph approach. See [CONTRIBUTING.md](CONTRIBUTING.md#project-history-and-contributors) for detailed project evolution and contributor information.
+
+## Citation
+
+The ILAE Outcome Scale used in this system is sourced from the Massachusetts General Hospital Epilepsy Service. For more information, visit their [Epilepsy Surgery Outcome Scales page](https://seizure.mgh.harvard.edu/engel-surgical-outcome-scale/).

seizure/app/config.toml

@@ -0,0 +1,22 @@
+[theme]
+primaryColor = "#FF4B4B"
+backgroundColor = "#FFFFFF"
+secondaryBackgroundColor = "#F0F2F6"
+textColor = "#262730"
+font = "sans serif"
+
+[server]
+maxUploadSize = 5
+enableXsrfProtection = true
+enableCORS = false
+port = 8501
+address = "0.0.0.0"
+
+[browser]
+gatherUsageStats = false
+serverAddress = "localhost"
+serverPort = 8501
+
+[logger]
+level = "info"
+messageFormat = "%(asctime)s %(message)s"

seizure/app/example_notes/ilaeclass1.txt

@@ -0,0 +1,65 @@
+**_This is a fictional clinical note for illustrative purposes only. It does not contain real patient information or PHI._**
+
+EPILEPSY CLINIC FOLLOW-UP NOTE
+
+Date: November 18, 2024
+Time: 10:30 AM
+
+PATIENT IDENTIFICATION
+Name: Sarah Johnson
+DOB: 03/15/1990
+MRN: 123456789
+
+CHIEF COMPLAINT
+Routine follow-up for epilepsy management
+
+HISTORY OF PRESENT ILLNESS
+34-year-old female with history of focal epilepsy s/p left temporal lobectomy in 2022 presents for routine follow-up. Patient reports complete seizure freedom since surgery. No auras. No episodes of loss of consciousness, automatisms, or focal aware sensory phenomena. Maintains regular sleep schedule. Medication compliance is excellent with no missed doses.
+
+CURRENT MEDICATIONS
+- Levetiracetam 1000mg BID
+- Lamotrigine 200mg BID
+
+REVIEW OF SYSTEMS
+- Constitutional: Denies fatigue, sleep problems
+- Neurological: No headaches, no dizziness, no focal deficits
+- Psychiatric: Good mood, no depression or anxiety
+- All other systems reviewed and negative
+
+PHYSICAL EXAMINATION
+Vital Signs: BP 118/76, HR 72, RR 16, T 98.6°F
+General: Well-appearing, alert and oriented x3
+Neurological:
+- Mental Status: Clear, fluent speech
+- Cranial Nerves: II-XII intact
+- Motor: 5/5 strength throughout
+- Sensory: Intact to light touch
+- Cerebellar: Normal finger-to-nose
+- Gait: Normal, steady
+
+LABORATORY/DIAGNOSTIC STUDIES
+- Recent AED levels within therapeutic range
+- Last EEG (3 months ago): No epileptiform abnormalities
+
+ASSESSMENT
+1. Focal Epilepsy (ICD-10: G40.209)
+   - Post-left temporal lobectomy
+   - ILAE Outcome Class 1 (completely seizure free, no auras)
+   - Excellent medication compliance
+   - Stable on current AED regimen
+
+PLAN
+1. Continue current AED regimen unchanged
+2. Continue driving (meets local regulations for seizure-free duration)
+3. Maintain regular sleep schedule and lifestyle modifications
+4. Return to clinic in 6 months
+5. Obtain repeat AED levels prior to next visit
+6. Call if any seizure activity or concerning symptoms develop
+
+Patient understands and agrees with plan.
+
+___________________________
+Dr. Michael Chen, MD
+Epileptologist
+Board Certified in Neurology
+Time spent: 30 minutes