Phase 5: Provider Portal¶

# New middleware: extract provider context from Clerk JWT
# app/middleware/provider_auth.py

async def get_provider_context(request: Request) -> ProviderContext:
    """Extract provider_id, doctor_id, role from Clerk JWT claims."""
    claims = verify_clerk_jwt(request.headers.get("Authorization"))
    org_id = claims.get("org_id")  # Clerk organization = provider
    role = claims.get("org_role")  # provider_admin, provider_doctor, provider_coordinator

    # Map Clerk org_id to our provider_id
    provider = await get_provider_by_clerk_org(db, org_id)

    return ProviderContext(
        provider_id=provider.id,
        provider_name=provider.name,
        doctor_id=claims.get("doctor_id"),  # custom claim for doctor users
        role=role,
        tenant_id=provider.tenant_id,
    )

┌──────────────────────────────────────────────────────────┐
│  Apollo Hospitals Chennai — Provider Dashboard           │
│  ─────────────────────────────────────────────────────── │
│                                                          │
│  Cases This Month: 12    │  Response Rate: 91%           │
│  Avg Response Time: 4.2h │  Satisfaction: 4.6/5.0        │
│                                                          │
│  ┌────────────────────────────────────────────────────┐  │
│  │  Pending Cases (3)                                 │  │
│  │                                                    │  │
│  │  CRW-2026-00015 · TKR · Aisha A. · 2h ago        │  │
│  │  CRW-2026-00014 · CABG · Mohammed K. · 5h ago     │  │
│  │  CRW-2026-00013 · TKR · Sarah L. · 1d ago         │  │
│  └────────────────────────────────────────────────────┘  │
│                                                          │
│  ┌────────────────────────────────────────────────────┐  │
│  │  Responded (9)                                     │  │
│  │  Scheduled: 6  │  Acknowledged: 2  │  Declined: 1  │  │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

┌─────────────────────────┬───────────────────────────────┐
│  AI-Generated EHR       │  Source Documents              │
│  ────────────────────── │  ──────────────────────────── │
│                         │                               │
│  Conditions:            │  [PDF Viewer]                 │
│  ✅ M17.11 OA Right Knee│  blood_work_feb2024.pdf       │
│  ⚠️  K76.0 Fatty Liver  │                               │
│  ⚠️  R00.1 Bradycardia  │  Page 1 of 3                  │
│  ➕ Add condition...     │  ┌───────────────────────┐    │
│                         │  │                       │    │
│  Lab Values:            │  │  [PDF content]        │    │
│  Hemoglobin: 13.5 g/dL │  │                       │    │
│  HbA1c: 5.8%    [Edit] │  │                       │    │
│  eGFR: 88       [Edit] │  └───────────────────────┘    │
│  Creatinine: 0.9 [Edit]│                               │
│                         │  Uploaded: 2026-03-31          │
│  Comorbidities:         │  OCR Confidence: 94%          │
│  • Fatty liver (K76.0)  │                               │
│  • Bradycardia (R00.1)  │                               │
│  ➕ Add comorbidity...   │                               │
│                         │                               │
│  [Confirm Accurate]     │                               │
│  [Submit Corrections]   │                               │
└─────────────────────────┴───────────────────────────────┘

# What the provider submits
{
    "reviewer": "Dr. Rajesh Patel",
    "reviewer_doctor_id": "uuid",
    "review_time_minutes": 8,

    "conditions_confirmed": ["M17.11"],  # AI got these right
    "conditions_added": [
        {"icd10": "E11.9", "name": "Type 2 Diabetes Mellitus", "note": "HbA1c trending upward, 6.2 not 5.8"}
    ],
    "conditions_removed": [],

    "observations_corrected": [
        {"parameter": "HbA1c", "ai_value": 5.8, "correct_value": 6.2, "note": "Misread from report"}
    ],

    "overall_accuracy_rating": 4,  # 1-5 stars
    "clinical_notes": "Good extraction overall. Missed pre-diabetic indication.",

    "response_action": "scheduled",  # acknowledged | scheduled | declined
    "scheduled_date": "2026-04-15T10:00:00Z",
    "assigned_doctor_id": "uuid",
}

# Runs daily at 4am via QStash
patterns = await get_correction_patterns(db, tenant_id, min_occurrences=3)

# Example output:
# [
#   {"correction_type": "condition_missed", "occurrences": 7,
#    "details": [{"icd10": "E11.9", "context": "HbA1c 6.0-6.4 range"}]},
#   {"correction_type": "observation_wrong", "occurrences": 4,
#    "details": [{"parameter": "HbA1c", "typical_error": "off by 0.2-0.5"}]},
# ]

# app/services/prompt_improver.py

async def generate_correction_example(pattern: dict) -> dict:
    """Generate a few-shot example from a recurring correction pattern."""

    if pattern["correction_type"] == "condition_missed":
        # Build an example showing the correct extraction
        return {
            "input": "Patient lab values: HbA1c 6.2%, fasting glucose 118 mg/dL",
            "expected_output": {
                "conditions": [
                    {"name": "Pre-diabetes", "icd10": "R73.03", "confidence": 0.85},
                    {"name": "Type 2 Diabetes Mellitus", "icd10": "E11.9", "confidence": 0.70,
                     "note": "HbA1c >= 6.0 warrants diabetes screening"}
                ]
            },
            "explanation": "HbA1c in 6.0-6.4 range indicates pre-diabetic state. "
                          "Combined with elevated fasting glucose, Type 2 DM should be flagged.",
            "source": f"Provider corrections (n={pattern['occurrences']})",
        }

    elif pattern["correction_type"] == "observation_wrong":
        return {
            "input": "Lab report shows HbA1c: 6.2%",
            "expected_output": {"value": 6.2, "unit": "%"},
            "explanation": "Ensure exact value extraction — do not round or approximate.",
            "source": f"Provider corrections (n={pattern['occurrences']})",
        }

# Stage a new prompt version in Langfuse
from langfuse import Langfuse

langfuse = Langfuse()

# Add the correction-derived example to the prompt
current_prompt = langfuse.get_prompt("clinical_context_extraction")
new_examples = current_prompt.config.get("few_shot_examples", [])
new_examples.append(correction_example)

langfuse.create_prompt(
    name="clinical_context_extraction",
    prompt=current_prompt.prompt,
    config={
        **current_prompt.config,
        "few_shot_examples": new_examples,
        "version_note": f"Added {len(new_examples)} correction-derived examples",
    },
    labels=["draft"],  # Not yet production
)

┌─────────────────────────────────────────────────┐
│  AI Accuracy for Your Cases                     │
│  ──────────────────────────────────────────────  │
│                                                  │
│  Extraction Accuracy: 87% (↑3% from last month) │
│  Conditions correctly identified: 94%            │
│  Lab values correctly extracted: 91%             │
│  Most common corrections:                        │
│    1. HbA1c value misread (4 cases)              │
│    2. Pre-diabetes not flagged (3 cases)         │
│                                                  │
│  Your corrections are improving the AI!          │
│  12 corrections applied to prompts this month    │
└─────────────────────────────────────────────────┘