--- title: CliniqAI emoji: ๐Ÿชถ colorFrom: blue colorTo: indigo sdk: gradio sdk_version: "6.15.1" app_file: deploy/hf_space/gradio_app.py python_version: "3.12" pinned: false --- # CliniqAI โ€” Clinical Operations AI for Indian Hospitals ## Demo [![CliniqAI Demo](https://img.youtube.com/vi/DgvVKViuYm8/0.jpg)](https://www.youtube.com/watch?v=DgvVKViuYm8) > Giving doctors and nurses back the hours they lose to paperwork, so they can spend that time on patients. Built for the **[Hugging Face "Build Small" Hackathon](https://huggingface.co/build-small-hackathon)** โ€” a suite of small, open, โ‰ค32B models doing real hospital back-office work, with a human approving every decision that touches a patient. > **Status note:** This README describes **what actually runs today**, verified against the code and test suite. The original planning document (which scoped only 3 agents as "shipping") is preserved as **[`README_OLD.md`](README_OLD.md)** for pitch/historical context. Since then, **all seven agents have been implemented.** --- ## The Problem Indian doctors spend **2โ€“3 hours every day** on documentation. Nurses build duty rosters by hand over half a day. Receptionists book appointments by phone. Patients leave **4โ€“6 hours late** because pharmacy, billing, and family hand-offs all wait on each other. None of this needs medical judgment. It is mechanical, repetitive, and automatable โ€” and that is exactly the layer CliniqAI takes over, while clinicians stay in control of every clinical call. **The design rule:** *Agents prepare. Humans decide.* No agent sends or files anything patient-facing without explicit human approval. --- ## What the App Is A single **Gradio** web app with three role-based consoles, backed by a **FastAPI** service and a **LangGraph** multi-agent orchestrator. Seven agents share one typed state object and return validated **Pydantic** outputs, so everything is parseable, logged, and auditable. ``` Doctor console Patient console Nurse & Admin console โ”‚ โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ–ผ โ–ผ FastAPI โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–บ LangGraph Orchestrator โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” Documentation Appointment Roster Handover Discharge Clerical Wiki โ–ผ โ–ผ โ–ผ โ–ผ โ–ผ โ–ผ โ–ผ Retrieval (Chroma + BM25) ยท PostgreSQL ยท LLM router (Groq / OpenRouter / Ollama) ``` --- ## What Actually Works Today Legend: โœ… working & demoable ยท ๐ŸŸก works, needs an API key / external creds to go fully live ยท โš™๏ธ wired, depends on a build/seed step | Capability | Status | Notes | |---|---|---| | **Doctor console โ€” SOAP documentation** | โœ… | Paste a transcript (or record audio), get an editable SOAP draft with ICD-10 suggestions + citations, edit, then **Approve** to write it to the patient's wiki page. Falls back to a realistic **mock draft** if no LLM key is set, so it always demos. | | **Audio transcription (Whisper)** | ๐ŸŸก | Groq-hosted `whisper-large-v3-turbo`; needs `GROQ_API_KEY`. Transcript paste works with no key. | | **Patient console โ€” appointment chat** | โœ… | Chat widget routes to the Appointment Agent: parses intent, finds a free slot, books it, and replies with a confirmation + 1/2/0 confirm-reschedule-cancel flow. | | **Appointment booking + reminders** | โœ… | Slot-finding over a calendar; queues T-24h email + chat reminders via Celery. Uses a **local calendar fallback** so it runs offline. | | **Nurse โ€” shift handover brief** | โœ… | Generates a prioritised ward brief (urgent โ†’ watch โ†’ stable) with per-patient one-liners and pending actions. | | **Admin โ€” duty rostering** | โœ… | Greedy 14-day roster from a staff CSV (or demo data) in well under a second, with a fairness score; plus same-role, lowest-load **sick-call replacement**. | | **Nurse โ€” discharge coordination** | โœ… | Fans out **5 subtasks in parallel** (summary, pharmacy, family notify, follow-up booking, billing) and reports each one's status; failures are isolated. | | **Wiki health โ€” lint report** | โœ… | One click runs `lint_wiki()` over the public corpus: missing frontmatter, stale pages (>180d), broken `[[cross-refs]]`. Currently **0 issues** across the seeded corpus. | | **Orchestrator routing** | โœ… | LangGraph state graph routes each request to the right agent (6 agent nodes + orchestrator). | | **Knowledge retrieval (Chroma + BM25)** | โš™๏ธ | Hybrid search is wired behind one `search()` API; populate the index with `scripts/build_indices.py`. | | **LLM routing** | โœ… | LiteLLM picks Groq / OpenRouter / Ollama per task; degrades to mocks when no provider is configured. | | **Patient notifications (Telegram / WhatsApp)** | ๐ŸŸก | Telegram (free Bot API) and WhatsApp (Twilio) send paths exist; both no-op safely to a stub until credentials are set, so nothing crashes in a dry run. | | **Observability (Langfuse)** | ๐ŸŸก | LLM + retrieval calls are traced when Langfuse keys are present. | ### Agents โ€” all seven implemented | Agent | Does | |---|---| | **Documentation** | Transcript โ†’ retrieves patient history + guidelines + ICD-10 โ†’ drafts a SOAP note with citations โ†’ writes to the patient wiki on approval. | | **Appointment** | Parses booking/cancel/reschedule intent, checks availability, books, confirms, and schedules reminders. | | **Rostering** | Builds a fair 14-day roster from a CSV; resolves sick calls in real time. | | **Handover** | Produces a prioritised end-of-shift patient brief. | | **Discharge** | Coordinates the 5-stream discharge fan-out in parallel. | | **Clerical** | Drafts referral letters and post-visit summaries (human-approved). | | **Wiki Maintenance** | Updates patient pages and lints the knowledge corpus for staleness / broken links. | --- ## How It Works ### 1. The knowledge layer โ€” wiki + RAG, not just chunks CliniqAI follows the **LLM-Wiki** pattern: structured markdown pages (one per patient, drug, condition, protocol) that the system keeps current and cross-linked, instead of blindly chunking documents. When a guideline changes you update the page and mark the old content superseded โ€” so the next query reads a clean synthesis, not a blend of old and new. Large reference data (ICD-10 codes, formularies) lives in a **Chroma + BM25 hybrid index** for keyword-precise lookup. Structured operational data (appointments, rosters) lives in **PostgreSQL**. ### 2. The orchestration layer โ€” typed, auditable agents Every request enters the **LangGraph** graph, the orchestrator classifies it, and it flows to the owning agent. Each agent returns a validated Pydantic model (`SOAPNoteDraft`, `BookingResult`, `RosterResult`, `HandoverBrief`, `DischargeCoordination`, `CommunicationDraft`, โ€ฆ). State updates follow strict rules โ€” lists append, scalars overwrite, no node mutates shared state directly. ### 3. The model layer โ€” small, open, swappable Tasks are routed by **LiteLLM**: heavy reasoning (SOAP notes, handover, discharge summaries) โ†’ a 32B-class model on **Groq**; high-frequency simple replies โ†’ a fast 8B model; offline โ†’ **Ollama** locally. Every model in the routing table is free and **โ‰ค32B parameters** โ€” the spirit of the Build Small hackathon. If no provider is configured, the app serves realistic mocks so the UI still demos end-to-end. ### 4. The safety layer Every clinical output is traceable to a source page or guideline, nothing patient-facing is sent without human approval, and all agent actions are traceable via Langfuse. --- ## Why It's Beneficial Carried forward from the original product thesis โ€” these are the targets the workflows are built to hit: | Workflow | Today (manual) | With CliniqAI | |---|---|---| | SOAP note sign-off | 8โ€“10 min/consult | **< 90 sec** review-and-approve | | Duty roster generation | 3โ€“5 hours | **< 5 min** (sub-second in practice) | | Sick-call replacement | 30โ€“60 min | **< 15 min** | | Discharge โ†’ patient leaves | 4โ€“6 hours | **< 1.5 hours** (parallel fan-out) | | No-show rate | 15โ€“20% | **< 8%** (reminders + waitlist) | The compounding win: a doctor reclaiming ~2 hours/day is the equivalent of adding clinical capacity **without hiring** โ€” the most expensive constraint in Indian healthcare โ€” while the patient experience (faster discharge, fewer missed appointments, clearer summaries) improves at the same time. --- ## Demo / Run It Locally **Prereqs:** Docker (for Postgres/Redis), and [`uv`](https://docs.astral.sh/uv/). The app runs with **no API keys** thanks to mock fallbacks; add keys to `.env.local` to go fully live. ```bash # 1. Install deps into the uv-managed venv (Python 3.12) uv sync # 2. Bring up Postgres + Redis docker compose -f infra/docker-compose.dev.yml up -d # 3. Create the schema and seed demo data uv run alembic -c infra/alembic.ini upgrade head PYTHONHASHSEED=0 uv run python scripts/seed_demo.py # 4. Launch the Gradio app โ†’ http://127.0.0.1:7860 uv run python deploy/hf_space/app.py ``` Then click through the three consoles: - **Doctor** โ†’ paste a consult transcript โ†’ **Draft SOAP note** โ†’ edit โ†’ **Approve**. - **Patient** โ†’ type *"Book an appointment for tomorrow"* โ†’ confirm with **1**. - **Nurse & Admin** โ†’ **Handover** (Generate brief) ยท **Roster** (Generate roster, then Find replacement) ยท **Discharge queue** (Initiate discharge) ยท **Wiki health** (**Run lint**). Optional live integrations (add to `.env.local`, then restart): `GROQ_API_KEY` (LLM + Whisper) ยท `OPENROUTER_API_KEY` (fallback) ยท `TELEGRAM_BOT_TOKEN` + `TELEGRAM_CHAT_ID` (free patient notifications) ยท `LANGFUSE_*` (tracing). To deploy: the same `deploy/hf_space/app.py` runs on **Hugging Face Spaces** โ€” push, set secrets in the Spaces panel, done. --- ## Testing ```bash PYTHONHASHSEED=0 uv run pytest -q ``` **64 tests pass** today โ€” documentation, rostering, handover, clerical, orchestrator routing, integrations, and contracts suites are all green. The appointment and discharge happy-path tests currently error/fail due to a **mock-patching harness issue** (they patch names that are imported lazily inside functions, so `mock.patch` can't find them) โ€” the underlying agent code is verified working via direct smoke tests; only the test wiring needs the patch target corrected. --- ## Tech Stack (as actually wired) **Backend:** Python 3.12 ยท FastAPI ยท LangGraph (orchestration) ยท LiteLLM (model routing) ยท Pydantic v2 (typed outputs) ยท SQLAlchemy + Alembic + PostgreSQL ยท Celery + Redis (reminders). **AI & retrieval:** Groq Whisper (`whisper-large-v3-turbo`) ยท ChromaDB + rank-bm25 (hybrid search) ยท Langfuse (tracing). **Frontend:** Gradio (three consoles, one-command HF Spaces deploy). **Integrations:** Google Calendar (with offline local-calendar fallback) ยท Gmail ยท Telegram Bot API ยท WhatsApp (Twilio). --- ## Repository Map | Path | What's there | |---|---| | `app/agents/` | The seven agents (`documentation`, `appointment`, `roster`, `handover`, `discharge`, `clerical`, `wiki`) | | `app/orchestrator.py` | LangGraph state graph + routing | | `app/ui/` | Gradio consoles: `doctor_tab`, `patient_tab`, `nurse_admin_tab` | | `app/retrieval/` | Chroma + BM25 indices behind `index_api.search()` | | `app/integrations/` | Calendar, Gmail, Telegram, WhatsApp, Whisper | | `app/llm/router.py` | LiteLLM task routing + mock fallback | | `wiki/` | The markdown knowledge corpus (10 condition pages seeded) | | `deploy/hf_space/app.py` | Gradio entrypoint (local + HF Spaces) | | `scripts/` | `seed_demo.py`, `build_indices.py`, `fetch_data.sh` | | `plans/`, `README_OLD.md` | Original planning docs and pitch context | --- ## Team Built by: - [@drumilhved](https://huggingface.co/drumilhved) - [@someonesphantom](https://huggingface.co/someonesphantom) - [@Jayasuryan0419](https://huggingface.co/Jayasuryan0419) --- ## Clinical Safety - Every clinical recommendation is traceable to a specific wiki page or guideline source. - No agent sends a patient-facing communication without human approval. - Patient data is handled in line with India's **Digital Personal Data Protection Act (DPDPA)**; synthetic data only in this repo. - Full audit trail of agent actions via Langfuse.