initial commit

README.md

@@ -1,259 +1,12 @@
 ---
 title: Ebola Case Detection
-colorFrom: red
-colorTo: yellow
+emoji: 🏃
+colorFrom: green
+colorTo: green
 sdk: gradio
 sdk_version: 6.16.0
 app_file: app.py
 pinned: false
-python_version: "3.11"
 ---
 
-# Ebola Virus Disease Clinical Screening AI Agent
-
-Production-ready adaptive EVD screening agent for healthcare workers, built with Python, Pydantic, an LLM-driven reasoning layer, LangGraph, and Gradio.
-
-This agent performs dynamic clinical interviewing and classifies:
-
-- No Case
-- Suspected Case
-- Probable Case
-
-It does not classify Confirmed Case (laboratory confirmation is intentionally out of scope).
-
-## 1) Solution Architecture
-
-### Layer 1: Conversation Manager
-- Maintains session memory and full conversation history.
-- Tracks already asked questions and pending question.
-- Applies one-turn clinician input and returns one-turn agent output.
-
-### Layer 2: LLM Clinical Reasoning Agent
-- Uses an LLM to summarize known evidence, identify missing evidence, extract structured facts, and choose the next best single question.
-- Adapts questioning dynamically to symptoms, travel, exposure, and epidemiological context.
-- Stops questioning when the model determines sufficient evidence has been gathered.
-
-### Layer 3: Epidemiological Context Engine
-- Loads configurable outbreak context from JSON.
-- Computes proximity/context risk modifier from district, neighboring outbreaks, and alerts.
-- Prioritizes exposure questions earlier in high-risk context.
-
-### Layer 4: Explainability Module
-- Generates structured, auditable rationale:
-	- Classification
-	- Evidence collected
-	- Criteria/definition match explanation
-	- Recommended action
-
-## 2) Folder Structure
-
-```text
-.
-├── app.py
-├── requirements.txt
-├── data/
-│   └── epi_context.sample.json
-├── evd_agent/
-│   ├── __init__.py
-│   ├── config.py
-│   ├── context_engine.py
-│   ├── conversation.py
-│   ├── explainability.py
-│   ├── graph.py
-│   ├── llm_client.py
-│   ├── models.py
-│   └── reasoning.py
-└── tests/
-		└──
-```
-
-## 3) Data Models
-
-Implemented with Pydantic in `evd_agent/models.py`:
-
-- `PatientFacts`: structured interview variables (symptoms, exposure, death, lab availability, location).
-- `EpidemiologicalContext`: outbreak metadata and alerts.
-- `DecisionOutput`: classification, rule, evidence, action, confidence, stop flag.
-- `LLMInterviewPlan`: structured LLM output for evidence summary, fact updates, and next question.
-- `InterviewState`: full session state, asked questions, pending question, history.
-- `TurnResult`: structured output for each turn.
-
-## 4) State Schema
-
-`InterviewState` fields:
-
-- `session_id`: unique UUID per session
-- `status`: in_progress | complete
-- `facts`: patient feature store
-- `context`: loaded epidemiological context
-- `history`: full clinician/assistant turns
-- `asked_questions`: dedup set
-- `followup_question_count`: tracks the max 3 follow-up questions rule
-- `pending_question_text`: next LLM-generated question
-- `decision`: current decision snapshot
-- `llm_summary`: latest reasoning summary from the model
-- `rationale_log`: extensible audit trail
-
-## 5) Agent Workflow Diagram
-
-```mermaid
-flowchart TD
-		A[Clinician Input] --> B[Conversation Manager]
-		B --> D[LLM Reasoning Agent]
-		D --> E[Structured Fact Updates]
-		E --> H{Case Definition Met? by LLM + MOH guidance}
-		H -- Yes --> I[Suspected or Probable]
-		H -- No --> J[LLM-Generated Next Question]
-		I --> K[Explainability Module]
-		J --> K
-		K --> L[Gradio UI Panels + Chat]
-```
-
-LangGraph orchestration is implemented in `evd_agent/graph.py` with nodes:
-- `ingest_input`
-	- `llm_reason`
-- `compose_response`
-
-## 6) Clinical Reasoning Logic
-
-Clinical decisions are made directly by the LLM using Kenya MOH case definitions plus county context as supplemental situational awareness.
-County context influences question priority and concern level but does not independently classify a case.
-
-## 7) Clinical Reasoning Workflow
-
-Suspected case triggers if any:
-- Unexplained bleeding.
-- Sudden unexplained death.
-- Fever >= 38C with at least 3 compatible symptoms.
-- Fever >= 38C with qualifying exposure in previous 21 days.
-
-Probable case triggers when all:
-- Deceased,
-- Meets suspected criteria,
-- Epidemiological linkage to known case,
-- Laboratory confirmation unavailable.
-
-Adaptive questioning behavior:
-- One question at a time.
-- Stops immediately once suspect/probable criteria are met.
-- Uses LLM reasoning to prioritize highest-value unresolved evidence.
-- Asks a maximum of 3 follow-up questions when no case definition is met.
-- Avoids duplicate questions through state tracking.
-
-## 8) Gradio Implementation
-
-Gradio app in `app.py` includes:
-- Chat interface
-- Conversation history
-- Session memory (`gr.State` with `InterviewState`)
-- Classification panel
-- Epidemiological context panel
-- Alert banner
-- Reset button
-
-## 9) Deployment Instructions
-
-### Deploy to Hugging Face Spaces (Gradio)
-
-This repository is now Space-ready.
-
-1. Create a new Space on Hugging Face:
-	- Owner: your account or org
-	- Space SDK: Gradio
-	- Visibility: public or private
-2. Push this repository to the Space remote:
-
-```bash
-# Replace with your values
-git remote add hf https://huggingface.co/spaces/<username-or-org>/<space-name>
-git push hf main
-```
-
-3. In the Space settings, add required Secrets:
-	- `EVD_LLM_API_KEY` (or `OPENAI_API_KEY`)
-4. Optional Space variables/secrets:
-	- `EVD_LLM_MODEL` (example: `gpt-4.1-mini`)
-	- `EVD_LLM_BASE_URL` (if using a compatible non-default endpoint)
-	- `EVD_CONTEXT_PATH` (custom context path in the Space filesystem)
-
-When the build completes, the app launches automatically on the Space URL.
-
-### Local run
-
-```bash
-python -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-python app.py
-```
-
-Open `http://localhost:7860`.
-
-### Configurable context
-
-Set custom context file:
-
-```bash
-export EVD_CONTEXT_PATH=/absolute/path/to/epi_context.json
-python app.py
-```
-
-### LLM configuration
-
-Set an OpenAI-compatible model before starting the app. The UI will not launch without credentials, and the initial interview turn is generated by the LLM:
-
-```bash
-export EVD_LLM_API_KEY=your_key_here
-export EVD_LLM_MODEL=gpt-4.1-mini
-python app.py
-```
-
-You can also use a local `.env` file (auto-loaded by the app):
-
-```bash
-cp .env.example .env
-# edit .env with your real key
-python app.py
-```
-
-Optional custom endpoint:
-
-```bash
-export EVD_LLM_BASE_URL=https://your-openai-compatible-endpoint
-python app.py
-```
-
-### Container (example)
-
-```dockerfile
-FROM python:3.12-slim
-WORKDIR /app
-COPY . .
-RUN pip install --no-cache-dir -r requirements.txt
-EXPOSE 7860
-CMD ["python", "app.py"]
-```
-
-## 10) Production Hardening Recommendations
-
-1. Add authentication and role-based access control for surveillance users.
-2. Encrypt data in transit and at rest (TLS + disk/database encryption).
-3. Replace in-memory session state with durable backend store (PostgreSQL/Redis).
-4. Add structured audit logging (classification path, timestamp, user identity, facility).
-5. Add observability (metrics, traces, interview completion rates, escalation latency).
-6. Add input validation guardrails and red-team testing for ambiguous narratives.
-7. Add clinical governance versioning for case definitions by country/date.
-8. Integrate notification adapters (SMS, DHIS2, surveillance endpoint APIs).
-9. Add high-availability deployment and disaster recovery plan.
-10. Add unit/integration/regression tests to CI/CD gates.
-
-## 11) Complete Python Code
-
-All complete runnable code is included in this repository under:
-- `app.py`
-- `evd_agent/*.py`
-
-## Notes on Clinical Scope
-
-- This system is a surveillance decision-support assistant and should be used under official public health protocols.
-- Confirmed case classification is intentionally excluded, pending laboratory diagnostics.
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference