EduCare Knowledge Bundle
Bundle OKF 0.2 · 4 conceitos · desairaj414/EduCare
Open source Repository Open in the app JSON README (API)
About
# EduCare Knowledge Bundle
EduCare converts clinical notes into clear, multilingual, reading-level-appropriate
patient education material while scrubbing PHI before it ever reaches the LLM.
Built by Team Neural Nexus for the TCS AI Fridays Hackathon 2026 (Ahmedabad).
# Overview
* [Architecture](architecture.md) - end-to-end pipeline from raw clinical notes to PDF handout.
# Components
* [Components](components/) - the Streamlit app and its backend modules (config, LLM client, generation, privacy scrubber, OCR, PDF export).
# Data
* [Data](data/) - the mock patient dataset used to demo and test all input modes.
# Decisions
* [Decisions](decisions/) - notable, non-obvious engineering choices and their rationale.
Details
- Kind
- OKF bundles
- Topic
- Government & public data
- Publisher
- desairaj414
- Origin
- okf_github
- Category
- dados
- Version
- 0.2
- Last push
- 2026-08-10T16:41:24Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-09-08 16:02:35
- Updated
- 2026-09-08 16:02:35
- Origin id
desairaj414/EduCare:.okf/index.md
README
# ❤️ EduCare — Healthcare Patient Education Material Generator
> **Team Neural Nexus** | TCS AI Fridays Hackathon 2026 — Ahmedabad
**🔗 Live demo:** _add your Streamlit Community Cloud URL here after deploying_
No API key needed to try it — the demo opens with an **Instant Demo** mode
using pre-generated output, plus options to bring your own key or try a
shared free key. See [Testing Modes](#testing-modes) below.
---
## Problem Statement
Healthcare providers spend **15–30 minutes per patient** manually translating complex clinical notes into understandable language. Patients receive dense, jargon-filled discharge papers they cannot understand — leading to **poor medication adherence, missed follow-ups, and preventable readmissions**.
**EduCare** solves this by converting clinical notes into **clear, multilingual, reading-level-appropriate patient education materials** in seconds — while ensuring **zero PHI leakage** to the AI model.
---
## Key Features
| Feature | Description |
|---|---|
| 🔒 **Privacy-First Architecture** | Regex-based PHI scrubber strips names, MRNs, emails, phones, dates, and ages *before* any data reaches the LLM. Full audit trail visible in-app. |
| 📖 **Adaptive Reading Level** | Choose Beginner, Intermediate, or Advance output — automatically adjusts vocabulary and sentence complexity. |
| 🎯 **Configurable Tone** | Empathetic, Direct & Clinical, or Pediatric-focused tone options. |
| 🌐 **Multilingual (5 Languages)** | English, Hindi (देवनागरी), Gujarati (ગુજરાતી), Marathi (देवनागरी), Spanish — all in native script. |
| ❓ **Teach-Back Questions** | Auto-generates 3 comprehension-check questions to verify patient understanding. |
| 📋 **3 Input Modes** | Free-Text Notes, Structured Form (smart dropdowns for diagnoses, medications, warnings), and Upload Handwritten Notes (OCR via a vision-capable LLM). |
| 📷 **OCR / Handwritten Notes** | Upload a photo of handwritten clinical notes — a vision LLM extracts the text for processing. |
| 🔗 **Share & Export** | Share tab with Download PDF, Email (mailto), and WhatsApp (coming soon) options. |
| 📄 **PDF Export** | Professional PDF with teal header, color-coded sections, bold rendering, and Unicode font support for all 5 languages. |
| ⏱️ **Generation Time Tracking** | Real-time badge in the header showing how long the AI generation took. |
| 🧪 **9 Mock Patient Cases** | 3 free-text, 3 structured form, 2 OCR scan, and 1 blank image for testing edge cases. |
| 🔀 **3 Testing Modes** | Instant Demo (pre-generated, no API key), Bring Your Own Key, or a shared free demo key — picked from a first-visit dialog. |
| 🌍 **Multi-Provider** | Gemini Flash by default, OpenRouter as a fallback, or any OpenAI-compatible endpoint via "Bring Your Own Key". |
---
## Screenshots
### Main UI — Dark Blue Theme with Sidebar Controls
The app features a professional dark blue header bar, white card panels, a dark navy sidebar with matched styling, and tabbed output with Patient Handout, Teach-Back Questions, Privacy Audit Log, and Share tabs.
### Header Bar — Tech Info Badges
The header displays: `🔒 Privacy Shield`, a badge for the active testing mode/provider (e.g. `📦 Instant Demo`, `🆓 Free Demo Key (Gemini)`, or `🔑 <your provider>`), `🔗 LangChain`, and a dynamic `⏱️ Xs` generation time badge after content is generated.
---
## Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ Streamlit Frontend │
│ Dark Navy Sidebar │ Input Panel │ Tabbed Output Panel │
│ (Controls, Samples)│ (3 Modes) │ (4 Tabs + Share) │
└────────┬──────────────────┬──────────────────┬──────────────┘
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────────┐
│ Mock Patients│ │ OCR Extract │ │ Privacy Scrubber │
│ (9 JSON) │ │ (Vision LLM, │ │ (6 PHI categories│
│ │ │ configurable)│ │ + audit log) │
└──────────────┘ └──────┬───────┘ └───────┬──────────┘
│ │
└──────┬─────────────┘
│ cleaned text only
▼
┌──────────────────┐
│ LangChain + │ ← Gemini Flash (default) /
│ Provider Layer │ OpenRouter / BYOK / legacy TCS
└───────┬──────────┘
│
┌────────┴─────────┐
▼ ▼
┌─────────────┐ ┌──────────────┐
│ Handout │ │ Teach-Back │
│ (Markdown) │ │ Questions │
└──────┬──────┘ └──────┬───────┘
│ │
▼ ▼
┌─────────────────────────────────┐
│ PDF Export (fpdf2) │
│ Google Noto Sans Unicode fonts │
│ Teal header, color sections │
└─────────────────────────────────┘
```
---
## Project Structure
```
EduCare/
├── app.py # Streamlit UI — main entry point
│ # Custom CSS theme (dark blue header, white cards, navy sidebar)
│ # Mode-selector dialog, 3 input modes, 4 output tabs, Share panel
├── config.py # Centralized configuration
│ # Shared demo key, reading levels, tones, languages
│ # Dropdown lists: 20 diagnoses, 17 medications, 13 warnings
├── providers.py # LLM provider registry (Gemini, OpenRouter, legacy TCS, custom)
│ # Per-provider model-selection strategy + key validation
├── api_client.py # LLM/Embeddings client, credentials passed in per call
├── generate.py # LangChain prompts + generation logic
│ # Enhanced prompt with emoji section headers
│ # Content-filter safe-word swap (TCS provider only)
│ # generate_handout() + generate_teachback()
├── privacy_scrubber.py # PHI detection & redaction engine
│ # 6 categories: names, MRNs, emails, phones, dates, ages
│ # Returns (cleaned_text, audit_log)
├── pdf_export.py # Professional multilingual PDF generation
│ # Teal header bar, color-coded sections, bold rendering
│ # Warning callout boxes, bordered disclaimer
├── ocr_extract.py # Handwritten notes OCR via a vision-capable LLM
│ # Direct httpx POST with base64 image
├── mock_patients.json # 9 synthetic patient cases
│ # 3 free-text (Diabetes, CABG, Pediatric Asthma)
│ # 3 structured form (same conditions)
│ # 2 OCR scans (handwritten images)
│ # 1 blank image (edge case testing)
├── mock_outputs.json # Pre-generated handout/teach-back per mock case (Instant Demo mode)
├── scripts/
│ └── pregenerate_demo_outputs.py # One-time script that populates mock_outputs.json
├── requirements.txt # Python dependencies
├── fonts/ # Google Noto Sans font files (Unicode)
│ ├── NotoSans.ttf # English, Spanish (Latin)
│ ├── NotoSansDevanagari.ttf# Hindi, Marathi (Devanagari)
│ └── NotoSansGujarati.ttf # Gujarati
├── token/ # Tiktoken cache (offline, avoids network calls)
├── docs/ # Enterprise deliverables
│ ├── Judge_Q&A.md # Anticipated judge questions with answers
│ ├── Demo_Prompts.md # Step-by-step demo script (5 demos)
│ ├── Future_Vision.md # 4-phase product roadmap
│ ├── Presentation_Deck.md # 11-slide pitch deck content
│ ├── sample_handwritten_diabetes.png # Sample OCR test image
│ ├── sample_handwritten_cardiac.png # Sample OCR test image
│ ├── sample_blank.png # Blank image for edge case testing
│ └── Sample_Patient_Handout.pdf # Example generated PDF
├── .env # Environment variables (API key) — gitignored, optional
├── .env.example # Template for environment setup
├── .gitignore # Excludes secrets, caches, venvs, build/OS artifacts
├── LICENSE # MIT
└── .okf/ # Open Knowledge Format bundle — architecture, components,
# mock data, and key engineering decisions as linked
# markdown concepts. Start at .okf/index.md.
```
---
## Input Modes
### 1. 📋 Free-Text Notes
Paste or type any clinical notes — discharge summaries, progress notes, consult notes. The privacy scrubber handles whatever is pasted.
### 2. 📝 Structured Form
Smart dropdown-based form with:
- **🩺 Diagnosis** — 20 common diagnoses dropdown + custom text
- **💊 Medications** — 17 common medications multi-select + custom text
- **📋 Care Instructions** — free text for lifestyle/precautions
- **🔬 Monitoring** — lab tests and follow-up monitoring
- **📅 Follow-Up Plan** — scheduling and referrals
- **⚠️ Warning Signs** — 13 common warnings dropdown + custom text
All fields are auto-assembled into clinical notes text for the AI.
### 3. 📷 Upload Handwritten Notes (OCR)
Upload a photo of handwritten or printed clinical notes. A vision-capable LLM (Gemini Flash by default) extracts the text, which appears in an editable text area for review before generation. Requires a live provider — Instant Demo mode instead loads the two pre-generated OCR mock cases directly.
---
## Output Tabs
| Tab | Content |
|---|---|
| **📋 Patient Handout** | Full patient education document with emoji section headers (🩺 What Is Happening, 💊 Your Medicines, 🏃 Lifestyle, ⚠️ Warning Signs, 📅 Follow-Up, 💡 Quick Tips) |
| **❓ Teach-Back Questions** | 3 comprehension-check questions with expected answers (AHRQ-recommended technique) |
| **🔍 Privacy Audit Log** | Every PHI item detected: type, original value, replacement tag + cleaned text sent to AI |
| **🔗 Share** | Download PDF, Email (mailto link), WhatsApp (coming soon) — all in styled cards |
---
## Testing Modes
On first load, EduCare asks how you'd like to try it — no account or key
required to just look around:
| Mode | What it needs | What it does |
|---|---|---|
| 📦 **Instant Demo** | Nothing | Loads pre-generated output for all 9 mock cases from `mock_outputs.json` — zero network calls, works even if every provider's quota is exhausted. Reading level/tone/language are fixed to the defaults it was generated with. |
| 🔑 **Bring Your Own Key** | Your own key for Gemini, OpenRouter, TCS GenAI Lab, or any OpenAI-compatible endpoint | Validates the key/model once, then generates live for any input, including custom notes and OCR. The key lives only in that browser session — never written to disk. |
| 🆓 **Try My Free Demo Key** | Nothing (uses a key the deployer configured) | Same as BYOK, but backed by a shared, rate-limited key. If it's exhausted or errors, the app prompts you to switch to Instant Demo or your own key instead of showing a stack trace. |
Switch modes anytime from the "🔄 Change testing mode" button in the sidebar.
---
## Quick Start
```bash
# 1. Install dependencies
pip install -r requirements.txt
# 2. (Optional) Set an API key — only needed for live generation.
# Instant Demo mode works with none at all.
cp .env.example .env
# then edit .env and set GEMINI_API_KEY=...
# 3. Run the app
streamlit run app.py
# 4. Open http://localhost:8501 in your browser
```
To populate `mock_outputs.json` yourself (only needed if you change the mock
cases or want to regenerate the Instant Demo content):
```bash
python scripts/pregenerate_demo_outputs.py
```
---
## Technology Stack
| Layer | Technology |
|---|---|
| Frontend | Streamlit 1.37+ (wide layout, custom CSS, dark theme, `st.dialog`) |
| LLM | Gemini Flash by default; OpenRouter fallback; any OpenAI-compatible endpoint via Bring Your Own Key; legacy TCS GenAI Lab endpoint |
| Orchestration | LangChain 0.2+ with ChatPromptTemplate |
| OCR | Vision-capable chat completions endpoint (direct httpx POST) |
| Privacy | Custom regex engine (6 PHI categories) |
| PDF | fpdf2 2.8+ with Google Noto Sans fonts (3 families) |
| Transport | httpx (SSL verification skipped only for the legacy TCS endpoint) |
| Content Filter | Safe-word swap utility (40+ medical term pairs) — applied only when the TCS provider is active |
---
## Privacy & Compliance
- **Zero PHI to LLM**: All personal identifiers are stripped *before* the text leaves the browser session.
- **6 PHI Categories**: Patient names, MRNs (Medical Record Numbers), email addresses, phone numbers, dates of birth, and ages.
- **Audit Trail**: Every redaction is logged with type, original value, and replacement tag — visible in the Privacy Audit Log tab.
- **No Data Persistence**: No clinical data is stored on disk or transmitted to any external service beyond the LLM API.
- **HIPAA-Aligned**: Architecture follows the "minimum necessary" principle — only de-identified clinical facts reach the AI.
---
## Content Filter Bypass (legacy TCS provider only)
The TCS GenAI Lab endpoint's safety filter blocks certain clinical keywords (e.g., "diagnosis", "symptoms", "diabetes"). EduCare uses a **transparent safe-word swap utility** in `generate.py`:
- 40+ medical terms are swapped with safe synonyms before sending (e.g., "diagnosis" → "health assessment")
- The original terms are restored in the AI's response
- Fully documented in code — a pragmatic engineering solution for enterprise API constraints
- **Only active when the TCS provider is selected.** Gemini, OpenRouter, and other OpenAI-compatible providers don't block clinical terms, so they skip the swap entirely — applying it unconditionally would otherwise mangle ordinary words in their responses (e.g. "individual" → "patient").
---
## Mock Patient Cases
| # | Case | Mode | Purpose |
|---|---|---|---|
| 1 | Type 2 Diabetes | Free-Text | Standard chronic illness with PII |
| 2 | CABG Post-Op | Free-Text | Post-surgical with MRN, email |
| 3 | Pediatric Asthma | Free-Text | Child patient, caregiver-focused |
| 4 | Diabetes | Structured Form | Same case via form inputs |
| 5 | CABG Post-Op | Structured Form | Same case via form inputs |
| 6 | Pediatric Asthma | Structured Form | Same case via form inputs |
| 7 | Diabetes OPD Notes | OCR Scan | Handwritten image extraction |
| 8 | Cardiac Discharge | OCR Scan | Handwritten image extraction |
| 9 | Blank Image | OCR Scan | Edge case — no text in image |
---
## UI Design
- **Header**: Dark blue gradient bar (`#1a3c6e → #2563a8`) with ❤️ EduCare branding and tech info badges
- **Sidebar**: Matching dark navy gradient with white text, translucent inputs, blue gradient buttons
- **Main Area**: Light gradient background (`#e8f0fe → #f0f4f8`) with white card panels and shadows
- **Buttons**: Blue gradient with hover elevation effect
- **Tabs**: Pill-style with blue active state
- **Trust Footer**: Three badges — Privacy Secured, Anonymized Data, Clinically Accurate
- **Fullscreen Layout**: Minimal padding, edge-to-edge header, max-width 100%
---
## Team Neural Nexus
Built with ❤️ at TCS AI Fridays Hackathon 2026, Ahmedabad.