Create app.py

app.py

@@ -0,0 +1,490 @@
+"""
+app.py — AI Visit Plan Generator (Hugging Face Spaces Version)
+
+This is a single-file application that:
+1. Accepts free-text care referral instructions
+2. Sends them to an AI model on Hugging Face
+3. Extracts a structured Visit Plan (JSON)
+4. Displays the result in a web interface
+
+Deployed as a Hugging Face Space with Gradio.
+"""
+
+import os
+import json
+import re
+import gradio as gr
+import requests
+from pydantic import BaseModel, Field
+from typing import Optional
+from enum import Enum
+
+
+# ══════════════════════════════════════════════════════════════════
+# SECTION 1: CONFIGURATION
+# ══════════════════════════════════════════════════════════════════
+
+# Read the API token from the Space's secrets (set in Settings)
+HUGGINGFACE_API_TOKEN = os.environ.get("HUGGINGFACE_API_TOKEN", "")
+
+if not HUGGINGFACE_API_TOKEN:
+    print("WARNING: HUGGINGFACE_API_TOKEN not found in environment.")
+    print("Go to your Space's Settings > Repository secrets to add it.")
+
+# The default AI model
+DEFAULT_MODEL = "mistralai/Mistral-7B-Instruct-v0.3"
+
+
+# ══════════════════════════════════════════════════════════════════
+# SECTION 2: DATA MODELS (What a Visit Plan looks like)
+# ══════════════════════════════════════════════════════════════════
+
+class DayOfWeek(str, Enum):
+    MONDAY = "Monday"
+    TUESDAY = "Tuesday"
+    WEDNESDAY = "Wednesday"
+    THURSDAY = "Thursday"
+    FRIDAY = "Friday"
+    SATURDAY = "Saturday"
+    SUNDAY = "Sunday"
+
+
+class Confidence(str, Enum):
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+class VisitOccurrence(BaseModel):
+    """A single scheduled visit within the plan."""
+    day_of_week: DayOfWeek = Field(..., description="Day the visit occurs")
+    start_time: str = Field(..., description="Preferred start time, e.g. '08:00'")
+    end_time: str = Field(..., description="Preferred end time, e.g. '09:00'")
+    duration_minutes: int = Field(..., description="Duration in minutes")
+    care_tasks: list[str] = Field(
+        default_factory=list,
+        description="Specific tasks, e.g. ['medication administration', 'personal care']"
+    )
+    notes: Optional[str] = Field(None, description="Additional notes for this visit")
+    confidence: Confidence = Field(
+        Confidence.MEDIUM,
+        description="Confidence level for this occurrence extraction"
+    )
+
+
+class VisitPlan(BaseModel):
+    """Top-level visit plan generated from referral text."""
+    visit_frequency: str = Field(..., description="e.g. 'Twice daily, 7 days a week'")
+    preferred_times: list[str] = Field(
+        default_factory=list, description="e.g. ['08:00-09:00', '20:00-21:00']"
+    )
+    qualifications_required: list[str] = Field(
+        default_factory=list, description="e.g. ['medication-trained']"
+    )
+    gender_preference: Optional[str] = Field(
+        None, description="e.g. 'Female carer preferred'"
+    )
+    environmental_requirements: list[str] = Field(
+        default_factory=list, description="e.g. ['key-safe code: 1234']"
+    )
+    occurrences: list[VisitOccurrence] = Field(
+        default_factory=list, description="Individual visit occurrences"
+    )
+    summary: str = Field(..., description="Brief plain-English summary")
+    extraction_notes: list[str] = Field(
+        default_factory=list, description="Flags for ambiguous or missing info"
+    )
+
+
+# ══════════════════════════════════════════════════════════════════
+# SECTION 3: THE PROMPT (Instructions for the AI)
+# ══════════════════════════════════════════════════════════════════
+
+VISIT_PLAN_SCHEMA = json.dumps(VisitPlan.model_json_schema(), indent=2)
+
+SYSTEM_PROMPT = f"""You are a care coordination assistant for a domiciliary care platform.
+Your task is to read free-text referral documents (from GPs, hospitals, or social workers)
+and extract a structured visit plan.
+
+## Output Format
+Return ONLY valid JSON matching this schema - no markdown, no explanation, no preamble:
+
+{VISIT_PLAN_SCHEMA}
+
+## Rules
+1. Extract all visit-related information from the referral text.
+2. Map clinical shorthand to full terms:
+   - "BD" = "twice daily", "OD" = "once daily", "TDS" = "three times daily"
+   - "PRN" = "as needed", "QDS" = "four times daily"
+3. If information is ambiguous or missing, set the field to a sensible default
+   and add a note to "extraction_notes" explaining what was assumed.
+4. Set confidence to "high" when the referral explicitly states the value,
+   "medium" when inferred from context, "low" when guessed or defaulted.
+5. Never invent care tasks that are not mentioned or implied in the referral.
+6. If gender preference is not mentioned, set it to null.
+7. Include ALL days of the week if the referral says "daily" or "7 days a week".
+8. Times should be in 24-hour format (e.g. "08:00" not "8am").
+"""
+
+# Few-shot example (teaches the AI by showing an example input and expected output)
+FEW_SHOT_INPUT = """
+Mrs Joan Smith, 82. Lives alone, ground floor flat. Key-safe code 4521.
+Requires personal care morning and evening, 7 days. Medication administration BD
+(insulin). Female carer preferred due to personal care. Moving and handling required
+- uses a zimmer frame. Daughter (Sarah, 07700 900123) is primary contact.
+"""
+
+FEW_SHOT_OUTPUT = json.dumps({
+    "visit_frequency": "Twice daily, 7 days a week",
+    "preferred_times": ["08:00-09:00", "20:00-21:00"],
+    "qualifications_required": [
+        "medication-trained (insulin administration)",
+        "moving-and-handling"
+    ],
+    "gender_preference": "Female carer preferred",
+    "environmental_requirements": [
+        "Key-safe code: 4521",
+        "Ground floor flat",
+        "Uses zimmer frame"
+    ],
+    "occurrences": [
+        {
+            "day_of_week": "Monday",
+            "start_time": "08:00",
+            "end_time": "09:00",
+            "duration_minutes": 60,
+            "care_tasks": ["personal care", "medication administration (insulin)"],
+            "notes": "Morning visit",
+            "confidence": "high"
+        },
+        {
+            "day_of_week": "Monday",
+            "start_time": "20:00",
+            "end_time": "21:00",
+            "duration_minutes": 60,
+            "care_tasks": ["personal care", "medication administration (insulin)"],
+            "notes": "Evening visit",
+            "confidence": "high"
+        }
+    ],
+    "summary": "Mrs Joan Smith, 82, requires twice-daily personal care and insulin "
+               "administration, 7 days a week. Female carer preferred. Key-safe access, "
+               "ground floor, zimmer frame user.",
+    "extraction_notes": [
+        "Only Monday occurrences shown - repeat pattern for all 7 days",
+        "Visit times assumed as 08:00 and 20:00 - not explicitly stated in referral"
+    ]
+}, indent=2)
+
+
+# ══════════════════════════════════════════════════════════════════
+# SECTION 4: LLM CLIENT (Talks to Hugging Face's AI)
+# ══════════════════════════════════════════════════════════════════
+
+def call_huggingface_model(referral_text: str, model_id: str = DEFAULT_MODEL) -> str:
+    """
+    Send the referral text to a Hugging Face model and get the response.
+
+    Args:
+        referral_text: The free-text referral from the coordinator.
+        model_id: Which AI model to use.
+
+    Returns:
+        The raw text response from the AI model.
+    """
+    # Build the conversation messages
+    messages = [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": f"Example referral:\n{FEW_SHOT_INPUT}"},
+        {"role": "assistant", "content": FEW_SHOT_OUTPUT},
+        {"role": "user", "content": f"Now extract a visit plan from this referral:\n\n{referral_text}"},
+    ]
+
+    # Format the prompt for Mistral-style models
+    prompt_parts = []
+    for msg in messages:
+        role = msg["role"]
+        content = msg["content"]
+        if role in ("system", "user"):
+            prompt_parts.append(f"[INST] {content} [/INST]")
+        elif role == "assistant":
+            prompt_parts.append(content)
+    formatted_prompt = "\n".join(prompt_parts)
+
+    # Call the Hugging Face Inference API
+    url = f"https://api-inference.huggingface.co/models/{model_id}"
+    headers = {
+        "Authorization": f"Bearer {HUGGINGFACE_API_TOKEN}",
+        "Content-Type": "application/json",
+    }
+    payload = {
+        "inputs": formatted_prompt,
+        "parameters": {
+            "max_new_tokens": 2048,
+            "temperature": 0.1,
+            "return_full_text": False,
+        },
+    }
+
+    response = requests.post(url, headers=headers, json=payload, timeout=120)
+    response.raise_for_status()
+
+    result = response.json()
+    if isinstance(result, list) and len(result) > 0:
+        return result[0].get("generated_text", "")
+    return str(result)
+
+
+# ══════════════════════════════════════════════════════════════════
+# SECTION 5: EXTRACTION & VALIDATION
+# ══════════════════════════════════════════════════════════════════
+
+def extract_json_from_text(text: str) -> str | None:
+    """Find JSON in the AI's response (handles markdown code fences)."""
+    # Try markdown code fence first
+    match = re.search(r'```(?:json)?\s*(\{.*?\})\s*```', text, re.DOTALL)
+    if match:
+        return match.group(1)
+    # Try raw JSON
+    match = re.search(r'(\{.*\})', text, re.DOTALL)
+    if match:
+        return match.group(1)
+    return None
+
+
+def validate_and_warn(visit_plan: dict) -> list[str]:
+    """Check the visit plan for potential issues."""
+    warnings = []
+
+    for i, occ in enumerate(visit_plan.get("occurrences", [])):
+        if occ.get("confidence") == "low":
+            day = occ.get("day_of_week", "Unknown")
+            warnings.append(
+                f"Visit {i+1} ({day}) has LOW confidence - please verify."
+            )
+
+    if not visit_plan.get("qualifications_required"):
+        warnings.append("No qualifications extracted - check the referral.")
+
+    if not visit_plan.get("occurrences"):
+        warnings.append("No visit times generated - the AI may have struggled to parse the schedule.")
+
+    if not visit_plan.get("environmental_requirements"):
+        warnings.append("No environmental requirements found - check for key-safe codes, access info, etc.")
+
+    return warnings
+
+
+def process_referral(referral_text: str, model_id: str) -> dict:
+    """
+    Main pipeline: referral text -> validated VisitPlan.
+
+    Returns a dict with success, visit_plan, raw_response, and errors.
+    """
+    # Call the AI
+    try:
+        raw_response = call_huggingface_model(referral_text, model_id)
+    except Exception as e:
+        return {
+            "success": False,
+            "visit_plan": None,
+            "raw_response": "",
+            "errors": [f"Error calling AI model: {str(e)}"],
+        }
+
+    # Extract JSON
+    json_str = extract_json_from_text(raw_response)
+    if not json_str:
+        return {
+            "success": False,
+            "visit_plan": None,
+            "raw_response": raw_response,
+            "errors": ["AI did not return valid JSON. Try again or use a different model."],
+        }
+
+    # Validate
+    try:
+        data = json.loads(json_str)
+        plan = VisitPlan(**data)
+        return {
+            "success": True,
+            "visit_plan": plan.model_dump(),
+            "raw_response": raw_response,
+            "errors": [],
+        }
+    except json.JSONDecodeError as e:
+        return {
+            "success": False,
+            "visit_plan": None,
+            "raw_response": raw_response,
+            "errors": [f"Invalid JSON from AI: {str(e)}"],
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "visit_plan": None,
+            "raw_response": raw_response,
+            "errors": [f"Output didn't match expected format: {str(e)}"],
+        }
+
+
+# ══════════════════════════════════════════════════════════════════
+# SECTION 6: SAMPLE REFERRALS (for testing)
+# ══════════════════════════════════════════════════════════════════
+
+SAMPLE_REFERRAL_1 = """
+Mr Arthur Davies, 78 years old. Referred by Dr Patel, Elm Surgery.
+Diagnosis: Type 2 diabetes, early-stage dementia, limited mobility (uses walking stick).
+Lives with wife (Margaret, 81) in a two-storey house - bedroom is upstairs.
+
+Care required:
+- Morning visit (approx 8am): assist with washing, dressing, breakfast prep, and
+  morning medication (metformin 500mg, donepezil 10mg).
+- Lunchtime check (approx 12:30): ensure lunch is prepared, prompt medication if
+  needed, welfare check.
+- Evening visit (approx 6pm): evening meal support, help preparing for bed,
+  evening medication (metformin 500mg).
+
+Frequency: 7 days a week. Carer must be medication-trained.
+No gender preference expressed. Wife is sometimes out at day centre (Tues/Thurs)
+so key-safe access needed - code 7890. Please note: Mr Davies can become confused
+in the late afternoon (sundowning).
+"""
+
+SAMPLE_REFERRAL_2 = """
+DISCHARGE SUMMARY - NHS Trust Reference: DIS-2024-8891
+Patient: Mr James Thompson, DOB 15/03/1945 (79 years)
+Diagnosis: Right hip replacement (total), Type 1 diabetes (insulin-dependent),
+mild cognitive impairment.
+
+Discharge to home. Lives with wife (Betty, 77) in semi-detached house.
+Stairs present - bedroom moved to ground floor temporarily.
+
+Post-operative care plan:
+AM visit 0730-0830: Personal care, wound dressing check, insulin
+administration (NovoRapid 8 units pre-breakfast), compression stockings.
+Must be moving and handling trained - patient cannot weight-bear fully.
+PM visit 1900-2000: Evening personal care, insulin administration
+(Lantus 20 units), wound check, help into bed.
+
+Duration: 6 weeks initially, review at 4 weeks.
+Frequency: BD, 7/7. Female carer preferred (patient request).
+Key-safe code: 5566. OT assessment pending for stair lift.
+District nurse visiting alternate days for wound management.
+"""
+
+SAMPLE_REFERRAL_3 = """
+Mrs Margaret Williams, 75. Lives alone in a bungalow. Key-safe: 3344.
+Needs help with personal care every morning, 7 days a week.
+Medication: paracetamol 500mg BD. No gender preference.
+Mobile with walking frame. Contact: son David 07700 111222.
+"""
+
+
+# ══════════════════════════════════════════════════════════════════
+# SECTION 7: GRADIO USER INTERFACE
+# ══════════════════════════════════════════════════════════════════
+
+def generate_visit_plan(referral_text: str, model_choice: str):
+    """Called when the user clicks 'Generate Visit Plan'."""
+    if not referral_text.strip():
+        return "Please paste referral text in the box on the left.", "", ""
+
+    if not HUGGINGFACE_API_TOKEN:
+        return (
+            "ERROR: No API token found.\n\n"
+            "Go to your Space's Settings > Repository secrets\n"
+            "and add a secret called HUGGINGFACE_API_TOKEN\n"
+            "with your Hugging Face token (starts with hf_...).",
+            "",
+            ""
+        )
+
+    result = process_referral(referral_text, model_choice)
+
+    if result["success"]:
+        plan_json = json.dumps(result["visit_plan"], indent=2)
+        warnings = validate_and_warn(result["visit_plan"])
+        all_notes = result["visit_plan"].get("extraction_notes", []) + warnings
+        if all_notes:
+            notes_text = "\n".join(f">> {note}" for note in all_notes)
+        else:
+            notes_text = "No issues detected. Please still review against the original referral."
+        return plan_json, notes_text, result["raw_response"]
+    else:
+        error_text = "ERRORS:\n" + "\n".join(result["errors"])
+        return error_text, "", result.get("raw_response", "")
+
+
+# Build the Gradio interface
+with gr.Blocks(
+    title="AI Visit Plan Generator",
+    theme=gr.themes.Soft(),
+) as demo:
+
+    gr.Markdown("# AI Visit Plan Generator")
+    gr.Markdown(
+        "Paste a free-text care referral below. The AI will extract a structured "
+        "visit plan for review. **Always verify the output against the original referral.**"
+    )
+
+    with gr.Row():
+        with gr.Column(scale=1):
+            gr.Markdown("### Input")
+            model_dropdown = gr.Dropdown(
+                choices=[
+                    "mistralai/Mistral-7B-Instruct-v0.3",
+                    "HuggingFaceH4/zephyr-7b-beta",
+                    "meta-llama/Llama-2-13b-chat-hf",
+                    "tiiuae/falcon-7b-instruct",
+                ],
+                value="mistralai/Mistral-7B-Instruct-v0.3",
+                label="AI Model",
+                info="Try different models to compare results"
+            )
+            referral_input = gr.Textbox(
+                label="Referral Text",
+                placeholder="Paste the GP referral, hospital discharge summary, "
+                           "or social worker assessment here...",
+                lines=15,
+            )
+            with gr.Row():
+                generate_btn = gr.Button("Generate Visit Plan", variant="primary")
+            with gr.Row():
+                example1_btn = gr.Button("Example 1: GP Referral", size="sm")
+                example2_btn = gr.Button("Example 2: Hospital Discharge", size="sm")
+                example3_btn = gr.Button("Example 3: Simple", size="sm")
+
+        with gr.Column(scale=1):
+            gr.Markdown("### Output")
+            plan_output = gr.Textbox(
+                label="Generated Visit Plan (JSON)",
+                lines=20,
+                interactive=False,
+            )
+            notes_output = gr.Textbox(
+                label="Notes & Warnings",
+                lines=5,
+                interactive=False,
+            )
+
+    with gr.Accordion("Debug: Raw Model Response", open=False):
+        gr.Markdown(
+            "*Shows the raw text from the AI model. Useful for troubleshooting.*"
+        )
+        raw_output = gr.Textbox(label="Raw Response", lines=10, interactive=False)
+
+    # Connect buttons to functions
+    generate_btn.click(
+        fn=generate_visit_plan,
+        inputs=[referral_input, model_dropdown],
+        outputs=[plan_output, notes_output, raw_output],
+    )
+    example1_btn.click(fn=lambda: SAMPLE_REFERRAL_1, outputs=referral_input)
+    example2_btn.click(fn=lambda: SAMPLE_REFERRAL_2, outputs=referral_input)
+    example3_btn.click(fn=lambda: SAMPLE_REFERRAL_3, outputs=referral_input)
+
+
+# Launch the app
+if __name__ == "__main__":
+    demo.launch()