{
  "markdown": "# ❤️ EduCare — Healthcare Patient Education Material Generator\n\n> **Team Neural Nexus** | TCS AI Fridays Hackathon 2026 — Ahmedabad\n\n**🔗 Live demo:** _add your Streamlit Community Cloud URL here after deploying_\n\nNo API key needed to try it — the demo opens with an **Instant Demo** mode\nusing pre-generated output, plus options to bring your own key or try a\nshared free key. See [Testing Modes](#testing-modes) below.\n\n---\n\n## Problem Statement\n\nHealthcare 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**.\n\n**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.\n\n---\n\n## Key Features\n\n| Feature | Description |\n|---|---|\n| 🔒 **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. |\n| 📖 **Adaptive Reading Level** | Choose Beginner, Intermediate, or Advance output — automatically adjusts vocabulary and sentence complexity. |\n| 🎯 **Configurable Tone** | Empathetic, Direct & Clinical, or Pediatric-focused tone options. |\n| 🌐 **Multilingual (5 Languages)** | English, Hindi (देवनागरी), Gujarati (ગુજરાતી), Marathi (देवनागरी), Spanish — all in native script. |\n| ❓ **Teach-Back Questions** | Auto-generates 3 comprehension-check questions to verify patient understanding. |\n| 📋 **3 Input Modes** | Free-Text Notes, Structured Form (smart dropdowns for diagnoses, medications, warnings), and Upload Handwritten Notes (OCR via a vision-capable LLM). |\n| 📷 **OCR / Handwritten Notes** | Upload a photo of handwritten clinical notes — a vision LLM extracts the text for processing. |\n| 🔗 **Share & Export** | Share tab with Download PDF, Email (mailto), and WhatsApp (coming soon) options. |\n| 📄 **PDF Export** | Professional PDF with teal header, color-coded sections, bold rendering, and Unicode font support for all 5 languages. |\n| ⏱️ **Generation Time Tracking** | Real-time badge in the header showing how long the AI generation took. |\n| 🧪 **9 Mock Patient Cases** | 3 free-text, 3 structured form, 2 OCR scan, and 1 blank image for testing edge cases. |\n| 🔀 **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. |\n| 🌍 **Multi-Provider** | Gemini Flash by default, OpenRouter as a fallback, or any OpenAI-compatible endpoint via \"Bring Your Own Key\". |\n\n---\n\n## Screenshots\n\n### Main UI — Dark Blue Theme with Sidebar Controls\nThe 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.\n\n### Header Bar — Tech Info Badges\nThe 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.\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    Streamlit Frontend                        │\n│  Dark Navy Sidebar  │  Input Panel  │  Tabbed Output Panel  │\n│  (Controls, Samples)│  (3 Modes)    │  (4 Tabs + Share)     │\n└────────┬──────────────────┬──────────────────┬──────────────┘\n         │                  │                  │\n         ▼                  ▼                  ▼\n  ┌──────────────┐  ┌──────────────┐   ┌──────────────────┐\n  │ Mock Patients│  │ OCR Extract  │   │ Privacy Scrubber │\n  │ (9 JSON)     │  │ (Vision LLM, │   │ (6 PHI categories│\n  │              │  │  configurable)│  │  + audit log)    │\n  └──────────────┘  └──────┬───────┘   └───────┬──────────┘\n                           │                    │\n                           └──────┬─────────────┘\n                                  │ cleaned text only\n                                  ▼\n                        ┌──────────────────┐\n                        │  LangChain +     │  ← Gemini Flash (default) /\n                        │  Provider Layer  │    OpenRouter / BYOK / legacy TCS\n                        └───────┬──────────┘\n                                │\n                       ┌────────┴─────────┐\n                       ▼                  ▼\n               ┌─────────────┐   ┌──────────────┐\n               │   Handout   │   │  Teach-Back  │\n               │  (Markdown) │   │  Questions   │\n               └──────┬──────┘   └──────┬───────┘\n                      │                  │\n                      ▼                  ▼\n               ┌─────────────────────────────────┐\n               │   PDF Export (fpdf2)             │\n               │   Google Noto Sans Unicode fonts │\n               │   Teal header, color sections    │\n               └─────────────────────────────────┘\n```\n\n---\n\n## Project Structure\n\n```\nEduCare/\n├── app.py                    # Streamlit UI — main entry point\n│                             #   Custom CSS theme (dark blue header, white cards, navy sidebar)\n│                             #   Mode-selector dialog, 3 input modes, 4 output tabs, Share panel\n├── config.py                 # Centralized configuration\n│                             #   Shared demo key, reading levels, tones, languages\n│                             #   Dropdown lists: 20 diagnoses, 17 medications, 13 warnings\n├── providers.py               # LLM provider registry (Gemini, OpenRouter, legacy TCS, custom)\n│                             #   Per-provider model-selection strategy + key validation\n├── api_client.py             # LLM/Embeddings client, credentials passed in per call\n├── generate.py               # LangChain prompts + generation logic\n│                             #   Enhanced prompt with emoji section headers\n│                             #   Content-filter safe-word swap (TCS provider only)\n│                             #   generate_handout() + generate_teachback()\n├── privacy_scrubber.py       # PHI detection & redaction engine\n│                             #   6 categories: names, MRNs, emails, phones, dates, ages\n│                             #   Returns (cleaned_text, audit_log)\n├── pdf_export.py             # Professional multilingual PDF generation\n│                             #   Teal header bar, color-coded sections, bold rendering\n│                             #   Warning callout boxes, bordered disclaimer\n├── ocr_extract.py            # Handwritten notes OCR via a vision-capable LLM\n│                             #   Direct httpx POST with base64 image\n├── mock_patients.json        # 9 synthetic patient cases\n│                             #   3 free-text (Diabetes, CABG, Pediatric Asthma)\n│                             #   3 structured form (same conditions)\n│                             #   2 OCR scans (handwritten images)\n│                             #   1 blank image (edge case testing)\n├── mock_outputs.json         # Pre-generated handout/teach-back per mock case (Instant Demo mode)\n├── scripts/\n│   └── pregenerate_demo_outputs.py  # One-time script that populates mock_outputs.json\n├── requirements.txt          # Python dependencies\n├── fonts/                    # Google Noto Sans font files (Unicode)\n│   ├── NotoSans.ttf          #   English, Spanish (Latin)\n│   ├── NotoSansDevanagari.ttf#   Hindi, Marathi (Devanagari)\n│   └── NotoSansGujarati.ttf  #   Gujarati\n├── token/                    # Tiktoken cache (offline, avoids network calls)\n├── docs/                     # Enterprise deliverables\n│   ├── Judge_Q&A.md          #   Anticipated judge questions with answers\n│   ├── Demo_Prompts.md       #   Step-by-step demo script (5 demos)\n│   ├── Future_Vision.md      #   4-phase product roadmap\n│   ├── Presentation_Deck.md  #   11-slide pitch deck content\n│   ├── sample_handwritten_diabetes.png   # Sample OCR test image\n│   ├── sample_handwritten_cardiac.png    # Sample OCR test image\n│   ├── sample_blank.png      #   Blank image for edge case testing\n│   └── Sample_Patient_Handout.pdf        # Example generated PDF\n├── .env                      # Environment variables (API key) — gitignored, optional\n├── .env.example              # Template for environment setup\n├── .gitignore                # Excludes secrets, caches, venvs, build/OS artifacts\n├── LICENSE                   # MIT\n└── .okf/                     # Open Knowledge Format bundle — architecture, components,\n                              #   mock data, and key engineering decisions as linked\n                              #   markdown concepts. Start at .okf/index.md.\n```\n\n---\n\n## Input Modes\n\n### 1. 📋 Free-Text Notes\nPaste or type any clinical notes — discharge summaries, progress notes, consult notes. The privacy scrubber handles whatever is pasted.\n\n### 2. 📝 Structured Form\nSmart dropdown-based form with:\n- **🩺 Diagnosis** — 20 common diagnoses dropdown + custom text\n- **💊 Medications** — 17 common medications multi-select + custom text\n- **📋 Care Instructions** — free text for lifestyle/precautions\n- **🔬 Monitoring** — lab tests and follow-up monitoring\n- **📅 Follow-Up Plan** — scheduling and referrals\n- **⚠️ Warning Signs** — 13 common warnings dropdown + custom text\n\nAll fields are auto-assembled into clinical notes text for the AI.\n\n### 3. 📷 Upload Handwritten Notes (OCR)\nUpload 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.\n\n---\n\n## Output Tabs\n\n| Tab | Content |\n|---|---|\n| **📋 Patient Handout** | Full patient education document with emoji section headers (🩺 What Is Happening, 💊 Your Medicines, 🏃 Lifestyle, ⚠️ Warning Signs, 📅 Follow-Up, 💡 Quick Tips) |\n| **❓ Teach-Back Questions** | 3 comprehension-check questions with expected answers (AHRQ-recommended technique) |\n| **🔍 Privacy Audit Log** | Every PHI item detected: type, original value, replacement tag + cleaned text sent to AI |\n| **🔗 Share** | Download PDF, Email (mailto link), WhatsApp (coming soon) — all in styled cards |\n\n---\n\n## Testing Modes\n\nOn first load, EduCare asks how you'd like to try it — no account or key\nrequired to just look around:\n\n| Mode | What it needs | What it does |\n|---|---|---|\n| 📦 **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. |\n| 🔑 **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. |\n| 🆓 **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. |\n\nSwitch modes anytime from the \"🔄 Change testing mode\" button in the sidebar.\n\n---\n\n## Quick Start\n\n```bash\n# 1. Install dependencies\npip install -r requirements.txt\n\n# 2. (Optional) Set an API key — only needed for live generation.\n#    Instant Demo mode works with none at all.\ncp .env.example .env\n# then edit .env and set GEMINI_API_KEY=...\n\n# 3. Run the app\nstreamlit run app.py\n\n# 4. Open http://localhost:8501 in your browser\n```\n\nTo populate `mock_outputs.json` yourself (only needed if you change the mock\ncases or want to regenerate the Instant Demo content):\n\n```bash\npython scripts/pregenerate_demo_outputs.py\n```\n\n---\n\n## Technology Stack\n\n| Layer | Technology |\n|---|---|\n| Frontend | Streamlit 1.37+ (wide layout, custom CSS, dark theme, `st.dialog`) |\n| LLM | Gemini Flash by default; OpenRouter fallback; any OpenAI-compatible endpoint via Bring Your Own Key; legacy TCS GenAI Lab endpoint |\n| Orchestration | LangChain 0.2+ with ChatPromptTemplate |\n| OCR | Vision-capable chat completions endpoint (direct httpx POST) |\n| Privacy | Custom regex engine (6 PHI categories) |\n| PDF | fpdf2 2.8+ with Google Noto Sans fonts (3 families) |\n| Transport | httpx (SSL verification skipped only for the legacy TCS endpoint) |\n| Content Filter | Safe-word swap utility (40+ medical term pairs) — applied only when the TCS provider is active |\n\n---\n\n## Privacy & Compliance\n\n- **Zero PHI to LLM**: All personal identifiers are stripped *before* the text leaves the browser session.\n- **6 PHI Categories**: Patient names, MRNs (Medical Record Numbers), email addresses, phone numbers, dates of birth, and ages.\n- **Audit Trail**: Every redaction is logged with type, original value, and replacement tag — visible in the Privacy Audit Log tab.\n- **No Data Persistence**: No clinical data is stored on disk or transmitted to any external service beyond the LLM API.\n- **HIPAA-Aligned**: Architecture follows the \"minimum necessary\" principle — only de-identified clinical facts reach the AI.\n\n---\n\n## Content Filter Bypass (legacy TCS provider only)\n\nThe 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`:\n- 40+ medical terms are swapped with safe synonyms before sending (e.g., \"diagnosis\" → \"health assessment\")\n- The original terms are restored in the AI's response\n- Fully documented in code — a pragmatic engineering solution for enterprise API constraints\n- **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\").\n\n---\n\n## Mock Patient Cases\n\n| # | Case | Mode | Purpose |\n|---|---|---|---|\n| 1 | Type 2 Diabetes | Free-Text | Standard chronic illness with PII |\n| 2 | CABG Post-Op | Free-Text | Post-surgical with MRN, email |\n| 3 | Pediatric Asthma | Free-Text | Child patient, caregiver-focused |\n| 4 | Diabetes | Structured Form | Same case via form inputs |\n| 5 | CABG Post-Op | Structured Form | Same case via form inputs |\n| 6 | Pediatric Asthma | Structured Form | Same case via form inputs |\n| 7 | Diabetes OPD Notes | OCR Scan | Handwritten image extraction |\n| 8 | Cardiac Discharge | OCR Scan | Handwritten image extraction |\n| 9 | Blank Image | OCR Scan | Edge case — no text in image |\n\n---\n\n## UI Design\n\n- **Header**: Dark blue gradient bar (`#1a3c6e → #2563a8`) with ❤️ EduCare branding and tech info badges\n- **Sidebar**: Matching dark navy gradient with white text, translucent inputs, blue gradient buttons\n- **Main Area**: Light gradient background (`#e8f0fe → #f0f4f8`) with white card panels and shadows\n- **Buttons**: Blue gradient with hover elevation effect\n- **Tabs**: Pill-style with blue active state\n- **Trust Footer**: Three badges — Privacy Secured, Anonymized Data, Clinically Accurate\n- **Fullscreen Layout**: Minimal padding, edge-to-edge header, max-width 100%\n\n---\n\n## Team Neural Nexus\n\nBuilt with ❤️ at TCS AI Fridays Hackathon 2026, Ahmedabad.\n",
  "bytes": 15695,
  "sha": "295b398b5b68f9e51b5121e1db5f1e075e14154e2de1cba9b9c1ef082b072554",
  "repo_slug": "desairaj414/educare",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_desairaj414_educare_okf_index_md_de9a28b9/readme"
}