Tiers 3-4: code organization, map placeholder, download, accessibility

app.py

@@ -2,23 +2,33 @@
 """
 Connecticut Hospital Financial Assistance Screener v4
 Deployed on Hugging Face Spaces
+
+Single-file Gradio application that screens CT residents for hospital
+financial assistance eligibility based on FPL thresholds and PA 24-81.
 """
 
+# === IMPORTS AND CONFIGURATION ===
+
 import os
 import re
+import tempfile
 import gradio as gr
 from openai import OpenAI
 from geopy.geocoders import Nominatim
 from geopy.distance import geodesic
 import time
 
-# Load API key from environment variable (set in HF Spaces secrets)
 OPENAI_API_KEY = os.environ["OPENAI_API_KEY"]
 client = OpenAI(api_key=OPENAI_API_KEY)
 DEMO_PASSWORD = "ct2026"
 
 geolocator = Nominatim(user_agent="ct_hospital_screener")
 
+# Simple in-memory cache for ZIP code geocoding results
+_zip_geocode_cache = {}
+
+# === HOSPITAL DATA ===
+
 HOSPITALS = {
     "Yale New Haven Health": {
         "free_care_threshold": 250,
@@ -46,7 +56,7 @@ HOSPITALS = {
         "asset_limit": None,
         "contact": "860-714-1657",
         "special_notes": "Medicaid exhaustion required",
-        "location": (41.7658, -72.6734),
+        "location": (41.7726, -72.6932),  # Saint Francis Hospital, Hartford
         "city": "Hartford",
         "fap_url": "https://www.trinityhealthofne.org/for-patients/billing-and-financial-resources"
     },
@@ -112,11 +122,14 @@ HOSPITALS = {
     }
 }
 
-# 2025 Federal Poverty Level Guidelines
+# === FEDERAL POVERTY LEVEL DATA ===
 # Source: https://aspe.hhs.gov/topics/poverty-economic-mobility/poverty-guidelines
 # Updated: January 2025. Check annually for new guidelines.
+
 FPL_2025 = {1: 15650, 2: 21150, 3: 26650, 4: 32150, 5: 37650, 6: 43150, 7: 48650, 8: 54150}
 
+# === TRANSLATIONS ===
+
 TRANSLATIONS = {
     "en": {
         "title": "Connecticut Hospital Financial Assistance Screener",
@@ -144,7 +157,8 @@ TRANSLATIONS = {
         "sources": "Source Documents",
         "disclaimer": "⚠️ This result was generated by AI and is for informational purposes only. It does not guarantee accuracy or constitute legal or financial advice. Please contact the hospital directly to confirm eligibility and complete the formal application process.",
         "eligible": "LIKELY ELIGIBLE",
-        "not_eligible": "MAY NOT QUALIFY"
+        "not_eligible": "MAY NOT QUALIFY",
+        "download_button": "Download Results"
     },
     "es": {
         "title": "Evaluador de Asistencia Financiera Hospitalaria de Connecticut",
@@ -172,27 +186,51 @@ TRANSLATIONS = {
         "sources": "Documentos Fuente",
         "disclaimer": "⚠️ Este resultado fue generado por IA y es solo para fines informativos. No garantiza precisión ni constituye asesoramiento legal o financiero. Comuníquese directamente con el hospital para confirmar la elegibilidad y completar el proceso de solicitud formal.",
         "eligible": "PROBABLEMENTE ELEGIBLE",
-        "not_eligible": "PUEDE NO CALIFICAR"
+        "not_eligible": "PUEDE NO CALIFICAR",
+        "download_button": "Descargar Resultados"
     }
 }
 
+# === ELIGIBILITY LOGIC ===
+
 def calculate_fpl_percentage(income, household_size):
+    """Calculate income as a percentage of the Federal Poverty Level.
+
+    For households larger than 8, adds $5,500 per additional person
+    to the base FPL amount per HHS guidelines.
+    """
     if household_size <= 8:
         fpl_base = FPL_2025[household_size]
     else:
         fpl_base = FPL_2025[8] + (5500 * (household_size - 8))
     return round((income / fpl_base) * 100, 1)
 
+# === HOSPITAL SEARCH ===
+
+def _geocode_zip(zip_code):
+    """Geocode a CT ZIP code with in-memory caching to avoid redundant API calls."""
+    zip_code = str(zip_code).strip()
+    if zip_code in _zip_geocode_cache:
+        return _zip_geocode_cache[zip_code]
+    location = geolocator.geocode(f"{zip_code}, Connecticut, USA")
+    _zip_geocode_cache[zip_code] = location
+    return location
+
 def find_nearby_hospitals(zip_code, lang):
+    """Find the 3 nearest CT hospitals to a given ZIP code.
+
+    Validates the ZIP is a CT format (060xx-069xx), geocodes it,
+    then returns markdown cards and choice labels sorted by distance.
+    """
     t = TRANSLATIONS[lang]
     try:
         if not re.match(r'^06[0-9]{3}$', str(zip_code).strip()):
-            msg = "Please enter a valid Connecticut ZIP code (060xx–069xx)." if lang == "en" else "Ingrese un código postal válido de Connecticut (060xx–069xx)."
+            msg = "Please enter a valid Connecticut ZIP code (060xx\u2013069xx)." if lang == "en" else "Ingrese un c\u00f3digo postal v\u00e1lido de Connecticut (060xx\u2013069xx)."
             return msg, []
 
-        location = geolocator.geocode(f"{zip_code}, Connecticut, USA")
+        location = _geocode_zip(zip_code)
         if not location:
-            return "Invalid ZIP code" if lang == "en" else "Código postal inválido", []
+            return "Invalid ZIP code" if lang == "en" else "C\u00f3digo postal inv\u00e1lido", []
 
         user_coords = (location.latitude, location.longitude)
         distances = []
@@ -209,9 +247,9 @@ def find_nearby_hospitals(zip_code, lang):
             choice_label = f"{name} ({data['city']}, {dist:.1f} mi)"
             choices.append(choice_label)
             cards += f"""### {name}
-📍 {data['city']} — {dist:.1f} {t['miles_away']}
-💰 {t['free_care']} {data['free_care_threshold']}% FPL | {t['sliding_scale']} {data['sliding_scale_max']}% FPL
-📞 {data['contact']}
+📍 Location: {data['city']} — {dist:.1f} {t['miles_away']}
+💰 Assistance: {t['free_care']} {data['free_care_threshold']}% FPL | {t['sliding_scale']} {data['sliding_scale_max']}% FPL
+📞 Phone: {data['contact']}
 
 ---
 """
@@ -221,6 +259,12 @@ def find_nearby_hospitals(zip_code, lang):
         return f"Error: {str(e)}", []
 
 def determine_eligibility(hospital_name, income, household_size, has_snap_wic, lang, has_insurance=False):
+    """Determine financial assistance eligibility for a given hospital.
+
+    Checks PA 24-81 presumptive eligibility first, then free care and
+    sliding scale thresholds. Returns a result dict with all data needed
+    for the explanation and display.
+    """
     if "(" in hospital_name:
         hospital_name = hospital_name.split(" (")[0]
 
@@ -280,10 +324,14 @@ def determine_eligibility(hospital_name, income, household_size, has_snap_wic, l
 
     return result
 
+# === AI EXPLANATION GENERATION ===
+
 def generate_explanation_streaming(data):
-    """
-    Streaming version - yields text as it's generated
-    Uses confidence-based language tiers
+    """Stream an AI-generated explanation of the eligibility result.
+
+    Selects a confidence tier (statutory / strong / moderate / negative)
+    to calibrate the language used by the LLM, then streams the response
+    token-by-token. Falls back to a static message on API failure.
     """
     lang = data["lang"]
     t = TRANSLATIONS[lang]
@@ -401,9 +449,14 @@ PA 24-81 Eligible: {'Yes' if data['pa_24_81_eligible'] else 'No'}"""
         fallback = "Detailed explanation temporarily unavailable. Please review the eligibility summary above and contact the hospital directly." if lang == "en" else "La explicación detallada no está disponible temporalmente. Revise el resumen de elegibilidad anterior y comuníquese directamente con el hospital."
         yield fallback
 
+# === RESULTS FORMATTING ===
+
 def format_results_streaming(data, lang):
-    """
-    Generator that yields progressive updates to the results
+    """Build and stream the full results page as markdown.
+
+    Renders a disclaimer banner, eligibility header, streamed AI explanation,
+    and a footer with contact info and source links. The footer is always
+    appended regardless of whether the AI call succeeded.
     """
     t = TRANSLATIONS[lang]
 
@@ -419,7 +472,7 @@ def format_results_streaming(data, lang):
 
 ### {t['status']}: {data['eligibility_status']}
 
-💵 ${data['income']:,.0f} ({data['fpl_percentage']}% FPL)
+💵 Income: ${data['income']:,.0f} ({data['fpl_percentage']}% FPL)
 
 ---
 
@@ -430,19 +483,19 @@ def format_results_streaming(data, lang):
 
 ---
 
-📞 **{t['contact']}:** {data['contact']}
+📞 Contact: **{data['contact']}**
 
 ---
 
-### {t['sources']}
+### 📄 {t['sources']}
 
-📄 [**{data['hospital']} Financial Assistance Policy**]({data['fap_url']})
+📄 Document: [**{data['hospital']} Financial Assistance Policy**]({data['fap_url']})
 
-📄 [**Connecticut Public Act 24-81**](https://www.cga.ct.gov/2024/ba/pdf/2024HB-05320-R000149-BA.pdf)
+📄 Document: [**Connecticut Public Act 24-81**](https://www.cga.ct.gov/2024/ba/pdf/2024HB-05320-R000149-BA.pdf)
 
-📄 [**2025 Federal Poverty Level Guidelines**](https://www.healthcare.gov/glossary/federal-poverty-level-fpl/)
+📄 Document: [**2025 Federal Poverty Level Guidelines**](https://www.healthcare.gov/glossary/federal-poverty-level-fpl/)
 
-📄 [**CT Office of the Healthcare Advocate**](https://portal.ct.gov/oha)
+📄 Document: [**CT Office of the Healthcare Advocate**](https://portal.ct.gov/oha)
 
 ---
 
@@ -460,7 +513,37 @@ def format_results_streaming(data, lang):
     # Always append footer after streaming completes
     yield base + partial_explanation + footer
 
-# Custom CSS for CT.gov styling
+
+def generate_download_content(data, lang):
+    """Generate a plain-text summary of the eligibility result for download."""
+    t = TRANSLATIONS[lang]
+    lines = [
+        f"Connecticut Hospital Financial Assistance — Eligibility Summary",
+        f"={'=' * 59}",
+        f"",
+        f"Hospital: {data['hospital']}",
+        f"Status: {data['eligibility_status']}",
+        f"Discount Level: {data['discount_level']}",
+        f"",
+        f"Annual Household Income: ${data['income']:,.0f}",
+        f"Household Size: {data['household_size']}",
+        f"FPL Percentage: {data['fpl_percentage']}%",
+        f"SNAP/WIC Enrolled: {'Yes' if data['has_snap_wic'] else 'No'}",
+        f"Has Insurance: {'Yes' if data.get('has_insurance') else 'No'}",
+        f"PA 24-81 Eligible: {'Yes' if data['pa_24_81_eligible'] else 'No'}",
+        f"",
+        f"Contact: {data['contact']}",
+        f"Asset Limit: {data['asset_limit'] or 'None'}",
+        f"FAP URL: {data['fap_url']}",
+        f"",
+        f"---",
+        f"",
+        t['disclaimer'],
+    ]
+    return "\n".join(lines)
+
+# === CUSTOM CSS ===
+
 custom_css = """
 /* CT.gov inspired styling */
 .gradio-container {
@@ -538,7 +621,10 @@ label {
 }
 """
 
+# === GRADIO UI ===
+
 def create_interface():
+    """Build and return the Gradio Blocks interface with all steps and event wiring."""
     with gr.Blocks(
         theme=gr.themes.Default(primary_hue="blue", neutral_hue="slate"),
         css=custom_css
@@ -546,6 +632,7 @@ def create_interface():
 
         lang_state = gr.State("en")
         selected_hospital = gr.State("")
+        last_result_state = gr.State(None)  # Stores the most recent eligibility result dict
 
         # Header with Beta tag
         with gr.Row():
@@ -564,8 +651,17 @@ def create_interface():
         with step1:
             gr.Markdown("### How would you like to start?")
             with gr.Row():
-                help_btn = gr.Button("🔍 Help me find a hospital", variant="primary", size="lg")
-                know_btn = gr.Button("🏥 I know my hospital", variant="secondary", size="lg")
+                help_btn = gr.Button("🔍 Search: Help me find a hospital", variant="primary", size="lg")
+                know_btn = gr.Button("🏥 Select: I know my hospital", variant="secondary", size="lg")
+
+            # TODO: Replace with actual OHA Google Map embed code
+            gr.HTML(
+                '<div style="background: #e9ecef; border: 2px dashed #adb5bd; border-radius: 8px; '
+                'padding: 2rem; text-align: center; color: #6c757d; margin-top: 1rem;">'
+                '<p style="font-size: 1.1rem; margin: 0;">🗺️ Map: Connecticut Hospital Locations</p>'
+                '<p style="font-size: 0.85rem; margin: 0.5rem 0 0 0;">Interactive map coming soon</p>'
+                '</div>'
+            )
 
         # Step 2a: Find hospital by ZIP
         step2a = gr.Group(visible=False)
@@ -607,10 +703,15 @@ def create_interface():
         step4 = gr.Group(visible=False)
         with step4:
             results_output = gr.Markdown()
-            restart_btn = gr.Button("Check Another Hospital", variant="secondary")
+            with gr.Row():
+                restart_btn = gr.Button("🔄 Restart: Check Another Hospital", variant="secondary")
+                download_btn = gr.Button("📥 Download: Save Results", variant="secondary")
+            download_file = gr.File(visible=False, label="Download")
+
+        # --- Navigation functions ---
 
-        # Navigation functions
         def show_find_path():
+            """Show the ZIP code search path (Step 2a)."""
             return [
                 gr.update(visible=False),
                 gr.update(visible=True),
@@ -620,6 +721,7 @@ def create_interface():
             ]
 
         def show_know_path():
+            """Show the hospital dropdown path (Step 2b)."""
             return [
                 gr.update(visible=False),
                 gr.update(visible=False),
@@ -629,6 +731,7 @@ def create_interface():
             ]
 
         def back_to_start():
+            """Return to Step 1."""
             return [
                 gr.update(visible=True),
                 gr.update(visible=False),
@@ -638,12 +741,14 @@ def create_interface():
             ]
 
         def search_hospitals_wrapper(zip_code, lang):
+            """Geocode a ZIP and return nearby hospital cards and radio choices."""
             cards, choices = find_nearby_hospitals(zip_code, lang)
             if choices:
                 return cards, gr.update(choices=choices, visible=True, value=choices[0]), gr.update(visible=True)
             return cards, gr.update(visible=False), gr.update(visible=False)
 
         def continue_from_search(hospital_choice, lang):
+            """Advance from ZIP search results to the eligibility form."""
             t = TRANSLATIONS[lang]
             hospital_name = hospital_choice.split(" (")[0] if "(" in hospital_choice else hospital_choice
             return [
@@ -658,6 +763,7 @@ def create_interface():
             ]
 
         def continue_from_dropdown(hospital_name, lang):
+            """Advance from hospital dropdown to the eligibility form."""
             t = TRANSLATIONS[lang]
             return [
                 hospital_name,
@@ -671,16 +777,17 @@ def create_interface():
             ]
 
         def check_eligibility_wrapper(hospital, income, household, snap, insurance, lang):
+            """Validate inputs, run eligibility check, and stream results."""
             t = TRANSLATIONS[lang]
 
             # Input validation
             if income is None or income <= 0:
-                gr.Warning("Please enter a valid income greater than $0." if lang == "en" else "Ingrese un ingreso válido mayor que $0.")
-                yield [gr.update(), gr.update(), gr.update(), gr.update(), gr.update()]
+                gr.Warning("Please enter a valid income greater than $0." if lang == "en" else "Ingrese un ingreso v\u00e1lido mayor que $0.")
+                yield [gr.update(), gr.update(), gr.update(), gr.update(), gr.update(), None]
                 return
             if household is None or int(household) < 1:
-                gr.Warning("Household size must be at least 1." if lang == "en" else "El tamaño del hogar debe ser al menos 1.")
-                yield [gr.update(), gr.update(), gr.update(), gr.update(), gr.update()]
+                gr.Warning("Household size must be at least 1." if lang == "en" else "El tama\u00f1o del hogar debe ser al menos 1.")
+                yield [gr.update(), gr.update(), gr.update(), gr.update(), gr.update(), None]
                 return
 
             has_snap = (snap == t['yes'])
@@ -692,7 +799,8 @@ def create_interface():
                 gr.update(visible=False),
                 gr.update(visible=False),
                 gr.update(visible=False),
-                gr.update(visible=True)
+                gr.update(visible=True),
+                data
             ]
 
             for partial_result in format_results_streaming(data, lang):
@@ -701,11 +809,24 @@ def create_interface():
                     gr.update(),
                     gr.update(),
                     gr.update(),
-                    gr.update()
+                    gr.update(),
+                    data
                 ]
 
+        def download_results(last_result, lang):
+            """Generate a temporary text file with the eligibility summary for download."""
+            if not last_result:
+                gr.Warning("No results to download." if lang == "en" else "No hay resultados para descargar.")
+                return gr.update(visible=False)
+            content = generate_download_content(last_result, lang)
+            tmp = tempfile.NamedTemporaryFile(mode='w', suffix='.txt', prefix='eligibility_summary_', delete=False)
+            tmp.write(content)
+            tmp.close()
+            return gr.update(value=tmp.name, visible=True)
+
         def update_lang(choice):
-            return "es" if choice == "Español" else "en"
+            """Convert the language toggle selection to a language code."""
+            return "es" if choice == "Espa\u00f1ol" else "en"
 
         # Wire up events
         lang_toggle.change(fn=update_lang, inputs=[lang_toggle], outputs=[lang_state])
@@ -738,12 +859,103 @@ def create_interface():
         check_btn.click(
             fn=check_eligibility_wrapper,
             inputs=[selected_hospital, income_input, household_input, snap_radio, insurance_radio, lang_state],
-            outputs=[results_output, step1, step2a, step3, step4],
+            outputs=[results_output, step1, step2a, step3, step4, last_result_state],
             api_name=False,
             concurrency_limit=5
         )
 
+        download_btn.click(
+            fn=download_results,
+            inputs=[last_result_state, lang_state],
+            outputs=[download_file]
+        )
+
     return demo
 
+# === LAUNCH ===
+# HF Spaces auto-detects the `demo` Blocks instance.
+# The explicit launch() is guarded so pytest can import without starting a server.
+
 demo = create_interface()
-demo.launch(auth=("oha", DEMO_PASSWORD))
+
+if __name__ == "__main__":
+    demo.launch(auth=("oha", DEMO_PASSWORD))
+
+
+# === TESTS (pytest-compatible) ===
+# Run with: OPENAI_API_KEY=test pytest app.py -v
+
+
+def test_calculate_fpl_percentage_single_person():
+    """FPL for a single person earning exactly the FPL amount should be 100%."""
+    result = calculate_fpl_percentage(15650, 1)
+    assert result == 100.0
+
+
+def test_calculate_fpl_percentage_household_of_4():
+    """A family of 4 at $32,150 should be exactly 100% FPL."""
+    result = calculate_fpl_percentage(32150, 4)
+    assert result == 100.0
+
+
+def test_calculate_fpl_percentage_large_household():
+    """Household of 10 should use the overflow formula: FPL_8 + 5500*(10-8)."""
+    expected_base = 54150 + (5500 * 2)  # 65150
+    income = expected_base
+    result = calculate_fpl_percentage(income, 10)
+    assert result == 100.0
+
+
+def test_calculate_fpl_percentage_half():
+    """Income at half of FPL for household of 1 should be ~50%."""
+    result = calculate_fpl_percentage(15650 / 2, 1)
+    assert result == 50.0
+
+
+def test_determine_eligibility_free_care():
+    """Income well below the free care threshold should yield 100% Discount."""
+    result = determine_eligibility("Yale New Haven Health", 10000, 1, False, "en")
+    assert result["eligibility_status"] == "LIKELY ELIGIBLE"
+    assert result["discount_level"] == "100% Discount"
+
+
+def test_determine_eligibility_sliding_scale():
+    """Income between free care and sliding scale thresholds → Partial Discount."""
+    # Yale: free_care=250%, sliding=550%. For household of 1, FPL=$15,650.
+    # 300% FPL = $46,950 → above 250% but below 550%.
+    result = determine_eligibility("Yale New Haven Health", 46950, 1, False, "en")
+    assert result["eligibility_status"] == "LIKELY ELIGIBLE"
+    assert result["discount_level"] == "Partial Discount"
+
+
+def test_determine_eligibility_not_eligible():
+    """Income above sliding scale max should not qualify."""
+    # 600% FPL for household of 1 = $93,900 → above Yale's 550%.
+    result = determine_eligibility("Yale New Haven Health", 93900, 1, False, "en")
+    assert result["eligibility_status"] == "MAY NOT QUALIFY"
+
+
+def test_determine_eligibility_pa_24_81():
+    """SNAP/WIC enrollee under 250% FPL triggers PA 24-81 presumptive eligibility."""
+    result = determine_eligibility("Yale New Haven Health", 20000, 1, True, "en")
+    assert result["pa_24_81_eligible"] is True
+    assert "PA 24-81" in result["discount_level"]
+
+
+def test_determine_eligibility_unknown_hospital():
+    """An unknown hospital name should return an error result, not crash."""
+    result = determine_eligibility("Nonexistent Hospital", 30000, 2, False, "en")
+    assert result.get("error") is True
+    assert "not found" in result["eligibility_status"].lower()
+
+
+def test_determine_eligibility_insurance_flag():
+    """The has_insurance flag should be passed through to the result dict."""
+    result = determine_eligibility("Yale New Haven Health", 10000, 1, False, "en", has_insurance=True)
+    assert result["has_insurance"] is True
+
+
+def test_determine_eligibility_spanish():
+    """Spanish language should return Spanish status strings."""
+    result = determine_eligibility("Yale New Haven Health", 10000, 1, False, "es")
+    assert result["eligibility_status"] == "PROBABLEMENTE ELEGIBLE"