Upload 2 files

app.py

@@ -10,7 +10,13 @@ import gradio as gr
 import spaces
 
 import database
-from report_workflow import list_reports_api, get_report_api, review_report_api, _identity
+from report_workflow import (
+    list_reports_api,
+    get_report_api,
+    review_report_api,
+    update_report_content_api,
+    _identity,
+)
 from inference import classes_info, health_info, predict_bytes, root_info
 
 logging.basicConfig(
@@ -19,16 +25,19 @@ logging.basicConfig(
 )
 logger = logging.getLogger("featurex-zerogpu-server")
 
-SERVER_VERSION = "3.5.0-authenticated-workflow-status"
+SERVER_VERSION = "3.5.1-authenticated-workflow-status"
 MAX_UPLOAD = 15 * 1024 * 1024
 
+
 def _runtime_info():
     info = {}
     try:
         import torch
         info["torch"] = torch.__version__
         info["cuda_available"] = bool(torch.cuda.is_available())
-        info["cuda_device"] = torch.cuda.get_device_name(0) if torch.cuda.is_available() else None
+        info["cuda_device"] = (
+            torch.cuda.get_device_name(0) if torch.cuda.is_available() else None
+        )
     except Exception as exc:
         info["torch_error"] = str(exc)
     try:
@@ -38,23 +47,19 @@ def _runtime_info():
         info["transformers_error"] = str(exc)
     info["janus_enabled"] = os.environ.get("JANUS_ENABLED", "true")
     info["janus_model_id"] = os.environ.get("JANUS_MODEL_ID", "ZrH42/Janus-Pro-CXR-Final")
-    info["model_path"] = os.environ.get("MODEL_PATH", os.path.join(os.path.dirname(os.path.abspath(__file__)), "best_efficientnet.pth"))
+    info["model_path"] = os.environ.get(
+        "MODEL_PATH",
+        os.path.join(os.path.dirname(os.path.abspath(__file__)), "best_efficientnet.pth"),
+    )
     info["model_file_exists"] = os.path.isfile(info["model_path"])
     return info
 
 
-
 def _json(payload: Any) -> str:
     return json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
 
 
 def _read_uploaded_image(image_path: str) -> tuple[bytes, str]:
-    """Read a real uploaded image file supplied by Gradio.
-
-    The browser/phone uploads the binary file to Gradio; the analysis
-    function receives the temporary server-side file path. No base64 is
-    used in the public UI or analysis function.
-    """
     if not image_path:
         raise ValueError("Please upload an X-ray image.")
 
@@ -168,8 +173,6 @@ def _build_unified(result: Dict[str, Any]) -> Dict[str, Any]:
         "quality_metrics": quality,
         "heatmap_stats": result.get("heatmap_stats", {}),
         "model_info": result.get("model_info", {}),
-        # Only Storage URLs are returned. Raw image/base64 payloads are never
-        # exposed through the public API response.
         "visualizations": {
             **((result.get("database") or {}).get("visualization_urls") or {}),
         },
@@ -183,7 +186,11 @@ def _build_unified(result: Dict[str, Any]) -> Dict[str, Any]:
             "recommendations": selected.get("recommendations", []),
             "raw_text": "\n".join(
                 str(x)
-                for x in [selected.get("title"), selected.get("findings"), selected.get("impression")]
+                for x in [
+                    selected.get("title"),
+                    selected.get("findings"),
+                    selected.get("impression"),
+                ]
                 if x
             ),
             "structured": selected,
@@ -194,17 +201,16 @@ def _build_unified(result: Dict[str, Any]) -> Dict[str, Any]:
         "gradcam": {
             "enabled": True,
             "heatmap_stats": result.get("heatmap_stats", {}),
-            # Only Storage URLs are returned. Raw image/base64 payloads are never
-        # exposed through the public API response.
-        "visualizations": {
-            **((result.get("database") or {}).get("visualization_urls") or {}),
-        },
+            "visualizations": {
+                **((result.get("database") or {}).get("visualization_urls") or {}),
+            },
             "visualization_keys": list((result.get("visualizations") or {}).keys()),
         },
         "discrepancies": {"flags": [], "count": 0},
         "safety": {
             "wording_flags": confidence_flags,
-            "manual_review_required": bool(safety_flags) or bool((result.get("report_integrity") or {}).get("manual_review_required")),
+            "manual_review_required": bool(safety_flags)
+            or bool((result.get("report_integrity") or {}).get("manual_review_required")),
             "reasons": safety_flags,
         },
         "database": result.get("database", {}),
@@ -234,15 +240,21 @@ def analyze(
 ) -> str:
     request_id = str(uuid.uuid4())
     try:
-        # Do not trust client-supplied user_id/role/department. Firebase ID token
-        # is verified server-side; role metadata comes from verified claims.
         identity = _identity(firebase_token, user_id)
         raw, filename = _read_uploaded_image(image_path)
         language = (language or "ar").strip().lower()
         if language not in {"ar", "en"}:
             language = "ar"
         patient, _client_user = _metadata(
-            patient_name, birth_date, gender, age, user_id, username, department, role, supervisor_id
+            patient_name,
+            birth_date,
+            gender,
+            age,
+            user_id,
+            username,
+            department,
+            role,
+            supervisor_id,
         )
         user = {
             "user_id": identity["uid"],
@@ -277,17 +289,15 @@ def analyze(
                 patient=patient,
                 user=user,
             )
-            db_info.update(
-                {
-                    "saved": bool(saved.get("saved", False)),
-                    "analysis_id": saved.get("analysis_id", result["analysis_id"]),
-                    "original_image_url": saved.get("original_image_url"),
-                    "visualization_urls": saved.get("visualization_urls", {}),
-                    "storage_saved": bool(
-                        saved.get("storage_saved", saved.get("original_image_url"))
-                    ),
-                }
-            )
+            db_info.update({
+                "saved": bool(saved.get("saved", False)),
+                "analysis_id": saved.get("analysis_id", result["analysis_id"]),
+                "original_image_url": saved.get("original_image_url"),
+                "visualization_urls": saved.get("visualization_urls", {}),
+                "storage_saved": bool(
+                    saved.get("storage_saved", saved.get("original_image_url"))
+                ),
+            })
             if saved.get("reason"):
                 db_info["reason"] = saved["reason"]
             if saved.get("error"):
@@ -295,19 +305,15 @@ def analyze(
                 db_info["error_type"] = saved.get("error_type")
         except Exception as exc:
             logger.exception("SUPABASE STORAGE/DATABASE SAVE FAILED request_id=%s", request_id)
-            db_info.update(
-                {
-                    "saved": False,
-                    "storage_saved": False,
-                    "error": str(exc),
-                    "error_type": type(exc).__name__,
-                }
-            )
+            db_info.update({
+                "saved": False,
+                "storage_saved": False,
+                "error": str(exc),
+                "error_type": type(exc).__name__,
+            })
 
         result["database"] = db_info
 
-        # A patient may submit an analysis request, but cannot receive diagnostic
-        # content until the protected get_report endpoint confirms approval.
         if identity["role"] == "patient":
             return _json({
                 "success": True,
@@ -320,65 +326,60 @@ def analyze(
                 "request_id": request_id,
             })
 
-        # Visualization bytes are server-side only. They are uploaded by
-        # database.save_analysis(); the public response contains Storage URLs only.
         result["visualizations"] = {}
         return _json(_build_unified(result))
 
     except PermissionError as exc:
         logger.warning("ANALYZE AUTH REJECTED request_id=%s reason=%s", request_id, str(exc))
-        return _json({"success": False, "status": "unauthorized", "request_id": request_id,
-                      "error": "Authentication required", "message": "يرجى تسجيل الدخول مجددًا ثم المحاولة."})
+        return _json({
+            "success": False,
+            "status": "unauthorized",
+            "request_id": request_id,
+            "error": "Authentication required",
+            "message": "يرجى تسجيل الدخول مجددًا ثم المحاولة.",
+        })
     except ValueError as exc:
         logger.warning("ANALYZE REJECTED request_id=%s reason=%s", request_id, str(exc))
-        return _json(
-            {
-                "success": False,
-                "status": "rejected",
-                "request_id": request_id,
-                "error": "Image validation failed",
-                "message": str(exc),
-            }
-        )
+        return _json({
+            "success": False,
+            "status": "rejected",
+            "request_id": request_id,
+            "error": "Image validation failed",
+            "message": str(exc),
+        })
     except Exception as exc:
         logger.exception("ANALYZE ERROR request_id=%s", request_id)
-        return _json(
-            {
-                "success": False,
-                "status": "error",
-                "request_id": request_id,
-                "error": "Internal server error",
-                "message": "حدث خطأ داخلي أثناء التحليل. يرجى المحاولة لاحقًا.",
-            }
-        )
+        return _json({
+            "success": False,
+            "status": "error",
+            "request_id": request_id,
+            "error": "Internal server error",
+            "message": "حدث خطأ داخلي أثناء التحليل. يرجى المحاولة لاحقًا.",
+        })
 
 
 @spaces.GPU(duration=30)
 def gpu_health() -> str:
     info = health_info()
-    info.update(
-        {
-            "server_version": SERVER_VERSION,
-            "transport": "Gradio Server + ZeroGPU",
-            "database": database.config_info(),
-            "runtime": _runtime_info(),
-            "api": {"analyze": True, "health": True, "classes": True},
-        }
-    )
+    info.update({
+        "server_version": SERVER_VERSION,
+        "transport": "Gradio Server + ZeroGPU",
+        "database": database.config_info(),
+        "runtime": _runtime_info(),
+        "api": {"analyze": True, "health": True, "classes": True},
+    })
     return _json(info)
 
 
 def health() -> str:
     info = root_info()
-    info.update(
-        {
-            "server_version": SERVER_VERSION,
-            "transport": "Gradio Server + ZeroGPU",
-            "zero_gpu": True,
-            "database": database.config_info(),
-            "runtime": _runtime_info(),
-        }
-    )
+    info.update({
+        "server_version": SERVER_VERSION,
+        "transport": "Gradio Server + ZeroGPU",
+        "zero_gpu": True,
+        "database": database.config_info(),
+        "runtime": _runtime_info(),
+    })
     return _json(info)
 
 
@@ -387,12 +388,6 @@ def classes() -> str:
 
 
 def db_health() -> str:
-    """
-    CPU-only Neon/R2 diagnostic.
-
-    This endpoint intentionally runs without @spaces.GPU so Storage/DB can be
-    tested before spending ZeroGPU time on EfficientNet/Janus inference.
-    """
     try:
         result = database.health_check()
     except Exception as exc:
@@ -406,45 +401,32 @@ def db_health() -> str:
     return _json(result)
 
 
-# ---------------------------------------------------------------------------
-# Gradio 6 Blocks API / ZeroGPU
-# ---------------------------------------------------------------------------
-# Hugging Face currently injects the Space-selected Gradio runtime (the
-# observed runtime is Gradio 6.x). Do not pin Gradio, spaces, or
-# huggingface-hub in requirements.txt.
-#
-# The public Android endpoint is the current Gradio queued API:
-#   POST /gradio_api/call/analyze
-#   GET  /gradio_api/call/analyze/<event_id>
-#
-# SSR is disabled deliberately. The API does not need the experimental SSR
-# frontend, and this removes one unnecessary HTTP/proxy layer for an
-# API-first medical inference Space.
-
 def _health_endpoint() -> str:
-    """Return a lightweight server health JSON document."""
     info = root_info()
-    info.update(
-        {
-            "server_version": SERVER_VERSION,
-            "transport": "Gradio Blocks + ZeroGPU",
-            "zero_gpu": True,
-            "database": database.config_info(),
-            "runtime": _runtime_info(),
-            "api": {"analyze": True, "health": True, "gpu_health": True, "classes": True},
-        }
-    )
+    info.update({
+        "server_version": SERVER_VERSION,
+        "transport": "Gradio Blocks + ZeroGPU",
+        "zero_gpu": True,
+        "database": database.config_info(),
+        "runtime": _runtime_info(),
+        "api": {
+            "analyze": True,
+            "health": True,
+            "gpu_health": True,
+            "classes": True,
+            "list_reports": True,
+            "get_report": True,
+            "review_report": True,
+            "update_report_content": True,
+        },
+    })
     return _json(info)
 
 
 def _classes_endpoint() -> str:
-    """Return the supported chest X-ray classification classes as JSON."""
     return _json(classes_info())
 
 
-# A small Gradio UI is intentionally kept here.  The API event is the actual
-# integration point for Android.  The browser/mobile UI uses a real Gradio file upload. The analysis function
-# receives a temporary server-side filepath; no base64 image field is used.
 with gr.Blocks(
     title="FeatureX Clinical AI — ZeroGPU",
     analytics_enabled=False,
@@ -462,11 +444,7 @@ with gr.Blocks(
             format="png",
             height=360,
         )
-        language = gr.Radio(
-            ["ar", "en"],
-            value="ar",
-            label="Report Language",
-        )
+        language = gr.Radio(["ar", "en"], value="ar", label="Report Language")
 
     with gr.Row():
         patient_name = gr.Textbox(label="patient_name")
@@ -485,7 +463,6 @@ with gr.Blocks(
     analyze_button = gr.Button("Analyze X-Ray", variant="primary")
     analyze_output = gr.Textbox(label="JSON response", lines=20)
 
-    # This is the public endpoint consumed by FeatureX Android.
     analyze_button.click(
         analyze,
         inputs=[
@@ -510,41 +487,28 @@ with gr.Blocks(
     health_button = gr.Button("Health")
     health_output = gr.Textbox(label="Health JSON")
     health_button.click(
-        _health_endpoint,
-        inputs=[],
-        outputs=health_output,
-        api_name="health",
+        _health_endpoint, inputs=[], outputs=health_output, api_name="health"
     )
 
     classes_button = gr.Button("Classes")
     classes_output = gr.Textbox(label="Classes JSON")
     classes_button.click(
-        _classes_endpoint,
-        inputs=[],
-        outputs=classes_output,
-        api_name="classes",
+        _classes_endpoint, inputs=[], outputs=classes_output, api_name="classes"
     )
 
     gpu_health_button = gr.Button("GPU Health")
     gpu_health_output = gr.Textbox(label="GPU Health JSON")
     gpu_health_button.click(
-        gpu_health,
-        inputs=[],
-        outputs=gpu_health_output,
-        api_name="gpu_health",
+        gpu_health, inputs=[], outputs=gpu_health_output, api_name="gpu_health"
     )
 
     db_health_button = gr.Button("Database / Storage Health")
     db_health_output = gr.Textbox(label="Database / Storage Health JSON", lines=12)
     db_health_button.click(
-        db_health,
-        inputs=[],
-        outputs=db_health_output,
-        api_name="db_health",
+        db_health, inputs=[], outputs=db_health_output, api_name="db_health"
     )
 
-    # Protected report workflow APIs. Each endpoint verifies the Firebase ID token
-    # server-side; client-supplied role/user_id fields are never authorization proof.
+    # ---------- Protected report workflow APIs ----------
     report_user_id = gr.Textbox(visible=False)
     report_token = gr.Textbox(visible=False)
     report_id = gr.Textbox(visible=False)
@@ -554,27 +518,49 @@ with gr.Blocks(
     list_reports_button = gr.Button("List Reports API", visible=False)
     list_reports_output = gr.Textbox(visible=False)
     list_reports_button.click(
-        list_reports_api, inputs=[report_user_id, report_token],
-        outputs=list_reports_output, api_name="list_reports"
+        list_reports_api,
+        inputs=[report_user_id, report_token],
+        outputs=list_reports_output,
+        api_name="list_reports",
     )
 
     get_report_button = gr.Button("Get Report API", visible=False)
     get_report_output = gr.Textbox(visible=False)
     get_report_button.click(
-        get_report_api, inputs=[report_id, report_token],
-        outputs=get_report_output, api_name="get_report"
+        get_report_api,
+        inputs=[report_id, report_token],
+        outputs=get_report_output,
+        api_name="get_report",
     )
 
     review_report_button = gr.Button("Review Report API", visible=False)
     review_report_output = gr.Textbox(visible=False)
     review_report_button.click(
-        review_report_api, inputs=[report_id, review_action, review_notes, report_token],
-        outputs=review_report_output, api_name="review_report"
+        review_report_api,
+        inputs=[report_id, review_action, review_notes, report_token],
+        outputs=review_report_output,
+        api_name="review_report",
+    )
+
+    # ---------- Report content editing (before approval) ----------
+    edit_id = gr.Textbox(visible=False)
+    edit_findings = gr.Textbox(visible=False)
+    edit_impression = gr.Textbox(visible=False)
+    edit_recs = gr.Textbox(visible=False)
+    edit_token = gr.Textbox(visible=False)
+    edit_output = gr.Textbox(visible=False)
+    edit_button = gr.Button("Update Report Content API", visible=False)
+    edit_button.click(
+        update_report_content_api,
+        inputs=[edit_id, edit_findings, edit_impression, edit_recs, edit_token],
+        outputs=edit_output,
+        api_name="update_report_content",
     )
 
+
 if __name__ == "__main__":
     demo.launch(
         show_error=True,
         max_file_size="15mb",
         ssr_mode=False,
-    )
+    )

report_workflow.py

@@ -1,5 +1,4 @@
 """Firebase-authenticated report workflow for FeatureX Gradio APIs."""
-
 import json
 import logging
 import os
@@ -8,556 +7,212 @@ from functools import lru_cache
 
 import database
 
-
 logger = logging.getLogger("featurex-report-workflow")
 
 
-# ============================================================
-# Firebase Admin initialization
-# ============================================================
-
 @lru_cache(maxsize=1)
 def _firebase_admin():
-    """Initialize Firebase Admin using server-side credentials only."""
+    """Initialize Firebase Admin from a Hugging Face secret, never from client data."""
     import firebase_admin
     from firebase_admin import credentials
-
     if firebase_admin._apps:
         return firebase_admin
-
-    raw = os.environ.get(
-        "FIREBASE_SERVICE_ACCOUNT_JSON", ""
-    ).strip()
-
+    raw = os.environ.get("FIREBASE_SERVICE_ACCOUNT_JSON", "").strip()
     if not raw:
-        raise RuntimeError(
-            "FIREBASE_SERVICE_ACCOUNT_JSON is not configured on the server."
-        )
-
+        raise RuntimeError("FIREBASE_SERVICE_ACCOUNT_JSON is not configured on the server.")
     try:
         service_account = json.loads(raw)
     except json.JSONDecodeError as exc:
-        raise RuntimeError(
-            "FIREBASE_SERVICE_ACCOUNT_JSON is invalid JSON."
-        ) from exc
-
-    firebase_admin.initialize_app(
-        credentials.Certificate(service_account)
-    )
-
+        raise RuntimeError("FIREBASE_SERVICE_ACCOUNT_JSON is invalid JSON.") from exc
+    firebase_admin.initialize_app(credentials.Certificate(service_account))
     return firebase_admin
 
 
-# ============================================================
-# Authentication and role normalization
-# ============================================================
-
 def _identity(token: str, claimed_user_id: str = "") -> dict:
-    """
-    Verify the Firebase ID token and normalize the user's role.
-
-    Legacy roles such as clinical and clinician are mapped to doctor.
-    The Firebase UID is the authoritative user identifier.
-    """
-
     token = (token or "").strip()
-
     if not token:
-        raise PermissionError(
-            "unauthorized: Firebase token is required"
-        )
-
+        raise PermissionError("unauthorized: Firebase token is required")
     admin = _firebase_admin()
-
     from firebase_admin import auth
-
-    decoded = auth.verify_id_token(
-        token,
-        check_revoked=True,
-    )
-
+    decoded = auth.verify_id_token(token, check_revoked=True)
     uid = str(decoded.get("uid") or "").strip()
-
     if not uid:
-        raise PermissionError(
-            "unauthorized: token has no uid"
-        )
-
-    claimed_user_id = (claimed_user_id or "").strip()
-
-    if claimed_user_id and claimed_user_id != uid:
-        raise PermissionError(
-            "forbidden: user_id does not match Firebase token"
-        )
-
-    raw_role = str(
-        decoded.get("role")
-        or decoded.get("user_role")
-        or "patient"
-    ).strip().lower()
-
+        raise PermissionError("unauthorized: token has no uid")
+    if claimed_user_id and claimed_user_id.strip() != uid:
+        raise PermissionError("forbidden: user_id does not match Firebase token")
+    role = str(decoded.get("role") or decoded.get("user_role") or "patient").strip().lower()
     role_aliases = {
-        # Doctor role and legacy aliases
-        "doctor": "doctor",
-        "clinical": "doctor",
-        "clinician": "doctor",
-        "specialist": "doctor",
-        "physician": "doctor",
-        "radiologist": "doctor",
-
-        # Department management
+        "doctor": "clinician",
+        "specialist": "clinician",
+        "physician": "clinician",
+        "radiologist": "clinician",
         "department head": "department_head",
         "head_of_department": "department_head",
-        "department_head": "department_head",
-        "department_manager": "department_manager",
-
-        # Other roles
         "supervisor": "supervisor",
         "admin": "admin",
         "administrator": "admin",
         "patient": "patient",
         "user": "patient",
+        "clinician": "clinician",
+        "department_head": "department_head",
     }
-
-    role = role_aliases.get(raw_role, raw_role)
-
+    role = role_aliases.get(role, role)
     return {
         "uid": uid,
         "role": role,
-        "department": str(
-            decoded.get("department") or ""
-        ).strip(),
-        "supervisor_id": str(
-            decoded.get("supervisor_id") or ""
-        ).strip(),
+        "department": str(decoded.get("department") or "").strip(),
+        "supervisor_id": str(decoded.get("supervisor_id") or "").strip(),
     }
 
 
-# ============================================================
-# JSON response helper
-# ============================================================
-
 def _ok(payload):
-    return json.dumps(
-        payload,
-        ensure_ascii=False,
-        separators=(",", ":"),
-    )
-
+    return json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
 
-# ============================================================
-# Database helpers
-# ============================================================
 
 def _row(analysis_id):
-    """Retrieve one analysis record by its ID."""
-
-    analysis_id = str(analysis_id or "").strip()
-
-    if not analysis_id:
-        return None
-
     rows = database._json_request(
-        "GET",
-        "analyses",
-        params={
-            "id": f"eq.{analysis_id}",
-            "limit": "1",
-        },
+        "GET", "analyses", params={"id": f"eq.{analysis_id}", "limit": "1"}
     )
+    return rows[0] if isinstance(rows, list) and rows else None
 
-    if isinstance(rows, list) and rows:
-        row = rows[0]
-
-        if isinstance(row, dict):
-            return row
-
-    return None
-
-
-# ============================================================
-# Report access authorization
-# ============================================================
 
 def _can_read(identity, row):
-    """
-    Check whether the authenticated user can access a report.
-
-    Patient access requires ownership, approval, and visibility.
-    Doctor access requires ownership or explicit assignment.
-    """
-
-    role = identity["role"]
-    uid = identity["uid"]
-
+    role, uid = identity["role"], identity["uid"]
     if role == "admin":
         return True
-
     if role == "patient":
         return (
             str(row.get("user_id") or "") == uid
             and row.get("visible_to_patient") is True
             and row.get("workflow_status") == "approved"
         )
-
-    if role == "doctor":
+    if role == "clinician":
         return (
             str(row.get("user_id") or "") == uid
             or str(row.get("assigned_to") or "") == uid
         )
-
-    if role in {
-        "supervisor",
-        "department_head",
-        "department_manager",
-    }:
+    if role in {"supervisor", "department_head"}:
         same_department = (
             bool(identity.get("department"))
-            and str(row.get("department") or "")
-            == identity["department"]
-        )
-
-        assigned = (
-            str(row.get("assigned_to") or "") == uid
+            and str(row.get("department") or "") == identity["department"]
         )
-
-        supervised = (
-            str(row.get("supervisor_id") or "") == uid
-        )
-
+        assigned = str(row.get("assigned_to") or "") == uid
+        supervised = str(row.get("supervisor_id") or "") == uid
         return same_department or assigned or supervised
-
     return False
 
 
-# ============================================================
-# List reports API
-# ============================================================
-
-def list_reports_api(
-    claimed_user_id: str,
-    firebase_token: str,
-) -> str:
-    """
-    Return reports visible to the authenticated user.
-
-    Patient responses contain only basic request metadata.
-    Clinical report content is not returned to patients before approval.
-    """
-
+# ----------------------------------------------------------------
+# LIST
+# ----------------------------------------------------------------
+def list_reports_api(claimed_user_id: str, firebase_token: str) -> str:
     try:
-        identity = _identity(
-            firebase_token,
-            claimed_user_id,
-        )
-
-        role = identity["role"]
-        uid = identity["uid"]
-
-        params = {
-            "order": "created_at.desc",
-            "limit": "200",
-        }
-
-        # ----------------------------------------------------
-        # Patient: retrieve only the patient's own requests.
-        # Sensitive report fields are removed below.
-        # ----------------------------------------------------
-
+        identity = _identity(firebase_token, claimed_user_id)
+        role, uid = identity["role"], identity["uid"]
+        params = {"order": "created_at.desc", "limit": "200"}
         if role == "patient":
-            params["user_id"] = f"eq.{uid}"
-
-        # ----------------------------------------------------
-        # Doctor: own reports or reports assigned to the doctor.
-        # ----------------------------------------------------
-
-        elif role == "doctor":
-            params["or"] = (
-                f"(user_id.eq.{uid},"
-                f"assigned_to.eq.{uid})"
-            )
-
-        # ----------------------------------------------------
-        # Supervisor and department management.
-        # ----------------------------------------------------
-
-        elif role in {
-            "supervisor",
-            "department_head",
-            "department_manager",
-        }:
+            params.update({"user_id": f"eq.{uid}"})
+        elif role == "clinician":
+            params["or"] = f"(user_id.eq.{uid},assigned_to.eq.{uid})"
+        elif role in {"supervisor", "department_head"}:
             department = identity.get("department", "")
-
             if department:
                 params["or"] = (
                     f"(department.eq.{department},"
-                    f"assigned_to.eq.{uid},"
-                    f"supervisor_id.eq.{uid})"
+                    f"assigned_to.eq.{uid},supervisor_id.eq.{uid})"
                 )
             else:
-                params["or"] = (
-                    f"(assigned_to.eq.{uid},"
-                    f"supervisor_id.eq.{uid})"
-                )
-
-        # ----------------------------------------------------
-        # Administrator: no additional user filter.
-        # ----------------------------------------------------
-
+                params["or"] = f"(assigned_to.eq.{uid},supervisor_id.eq.{uid})"
         elif role != "admin":
-            return _ok({
-                "status": "forbidden",
-                "message": (
-                    "Role is not permitted to list reports."
-                ),
-            })
-
-        rows = database._json_request(
-            "GET",
-            "analyses",
-            params=params,
-        )
-
-        if not isinstance(rows, list):
-            rows = []
-
-        # ----------------------------------------------------
-        # Minimize patient-facing report data.
-        # ----------------------------------------------------
-
+            return _ok({"status": "forbidden", "message": "Role is not permitted to list reports."})
+        rows = database._json_request("GET", "analyses", params=params)
+        rows = rows if isinstance(rows, list) else []
         if role == "patient":
             safe_rows = []
-
             for row in rows:
-                if not isinstance(row, dict):
-                    continue
-
-                if str(row.get("user_id") or "") != uid:
+                if not isinstance(row, dict) or str(row.get("user_id") or "") != uid:
                     continue
-
                 safe_rows.append({
                     "id": row.get("id"),
                     "created_at": row.get("created_at"),
                     "updated_at": row.get("updated_at"),
                     "status": row.get("status"),
-                    "workflow_status": (
-                        row.get("workflow_status")
-                        or row.get("status")
-                        or "pending_clinician_review"
-                    ),
-                    "visible_to_patient": bool(
-                        row.get("visible_to_patient")
-                    ),
-                    "approval_required": row.get(
-                        "approval_required",
-                        True,
-                    ),
+                    "workflow_status": row.get("workflow_status") or row.get("status") or "pending_clinician_review",
+                    "visible_to_patient": bool(row.get("visible_to_patient")),
+                    "approval_required": row.get("approval_required", True),
                 })
-
             rows = safe_rows
-
-        return _ok({
-            "status": "success",
-            "analyses": rows,
-            "count": len(rows),
-        })
-
+        return _ok({"status": "success", "analyses": rows, "count": len(rows)})
     except PermissionError as exc:
-        message = str(exc)
-
         return _ok({
-            "status": (
-                "unauthorized"
-                if "unauthorized" in message
-                else "forbidden"
-            ),
-            "message": message,
+            "status": "unauthorized" if "unauthorized" in str(exc) else "forbidden",
+            "message": str(exc),
         })
-
     except Exception:
         logger.exception("list_reports failed")
+        return _ok({"status": "error", "message": "Unable to list reports."})
 
-        return _ok({
-            "status": "error",
-            "message": "Unable to list reports.",
-        })
-
-
-# ============================================================
-# Get report API
-# ============================================================
-
-def get_report_api(
-    analysis_id: str,
-    firebase_token: str,
-) -> str:
-    """Retrieve a report after checking access permissions."""
 
+# ----------------------------------------------------------------
+# GET
+# ----------------------------------------------------------------
+def get_report_api(analysis_id: str, firebase_token: str) -> str:
     try:
         identity = _identity(firebase_token)
-
-        row = _row(
-            (analysis_id or "").strip()
-        )
-
+        row = _row((analysis_id or "").strip())
         if not row or not _can_read(identity, row):
             return _ok({
                 "status": "not_found",
-                "message": (
-                    "Report not found or access denied."
-                ),
+                "message": "Report not found or access denied.",
             })
-
-        return _ok({
-            "status": "success",
-            "analysis": row,
-        })
-
+        return _ok({"status": "success", "analysis": row})
     except PermissionError as exc:
-        message = str(exc)
-
         return _ok({
-            "status": (
-                "unauthorized"
-                if "unauthorized" in message
-                else "forbidden"
-            ),
-            "message": message,
+            "status": "unauthorized" if "unauthorized" in str(exc) else "forbidden",
+            "message": str(exc),
         })
-
     except Exception:
         logger.exception("get_report failed")
+        return _ok({"status": "error", "message": "Unable to retrieve report."})
 
-        return _ok({
-            "status": "error",
-            "message": "Unable to retrieve report.",
-        })
-
-
-# ============================================================
-# Review report API
-# ============================================================
-
-def review_report_api(
-    analysis_id: str,
-    action: str,
-    notes: str,
-    firebase_token: str,
-) -> str:
-    """
-    Review a report.
-
-    Doctors can move eligible reports to supervisor review.
-    Supervisor, department management, and admin roles can
-    finalize approval according to the workflow rules below.
-    """
 
+# ----------------------------------------------------------------
+# REVIEW (approve / request_revision)
+# ----------------------------------------------------------------
+def review_report_api(analysis_id: str, action: str, notes: str, firebase_token: str) -> str:
     try:
         identity = _identity(firebase_token)
-
         role = identity["role"]
+        if role not in {"clinician", "supervisor", "department_head", "admin"}:
+            return _ok({"status": "forbidden", "message": "Clinician review role required."})
 
-        permitted_roles = {
-            "doctor",
-            "clinician",            
-            "supervisor",
-            "department_head",
-            "department_manager",
-            "admin",
-        }
-
-        if role not in permitted_roles:
-            return _ok({
-                "status": "forbidden",
-                "message": (
-                    "Doctor review role required."
-                ),
-            })
-
-        analysis_id = (
-            analysis_id or ""
-        ).strip()
-
-        action = (
-            action or ""
-        ).strip().lower()
-
-        notes = (
-            notes or ""
-        ).strip()[:4000]
-
-        if not analysis_id:
-            return _ok({
-                "status": "invalid_request",
-                "message": "Analysis ID is required.",
-            })
-
-        if action not in {
-            "approve",
-            "request_revision",
-        }:
-            return _ok({
-                "status": "invalid_action",
-                "message": "Unsupported review action.",
-            })
+        analysis_id = (analysis_id or "").strip()
+        action = (action or "").strip().lower()
+        notes = (notes or "").strip()[:4000]
+        if action not in {"approve", "request_revision"}:
+            return _ok({"status": "invalid_action", "message": "Unsupported review action."})
 
         row = _row(analysis_id)
-
         if not row:
-            return _ok({
-                "status": "not_found",
-                "message": "Report not found.",
-            })
-
-        # ----------------------------------------------------
-        # Authorization
-        # ----------------------------------------------------
-
+            return _ok({"status": "not_found", "message": "Report not found."})
         if role != "admin" and not _can_read(identity, row):
-            return _ok({
-                "status": "forbidden",
-                "message": (
-                    "Report is outside your assigned scope."
-                ),
-            })
+            return _ok({"status": "forbidden", "message": "Report is outside your assigned scope."})
 
         current_status = str(
-            row.get("workflow_status")
-            or row.get("status")
-            or "pending_clinician_review"
+            row.get("workflow_status") or row.get("status") or "pending_clinician_review"
         )
 
-        # ----------------------------------------------------
-        # Validate approval transitions.
-        # ----------------------------------------------------
-
         if action == "approve":
-
-            if role == "doctor" and current_status not in {
-                "pending_clinician_review",
-                "needs_revision",
-            }:
+            if role == "clinician" and current_status not in {"pending_clinician_review", "needs_revision"}:
                 return _ok({
                     "status": "invalid_transition",
-                    "message": (
-                        "Doctors can review only reports awaiting "
-                        "doctor review or revision."
-                    ),
+                    "message": "Clinicians can review only reports awaiting clinician review or revision.",
                 })
-
-            if role in {
-                "supervisor",
-                "department_head",
-                "department_manager",
-            } and current_status != "pending_supervisor_review":
+            if role in {"supervisor", "department_head"} and current_status != "pending_supervisor_review":
                 return _ok({
                     "status": "invalid_transition",
-                    "message": (
-                        "Supervisor approval requires "
-                        "pending_supervisor_review status."
-                    ),
+                    "message": "Supervisor approval requires pending_supervisor_review status.",
                 })
-
             if role == "admin" and current_status not in {
                 "pending_clinician_review",
                 "needs_revision",
@@ -566,18 +221,10 @@ def review_report_api(
             }:
                 return _ok({
                     "status": "invalid_transition",
-                    "message": (
-                        "Report cannot be approved "
-                        "from its current status."
-                    ),
+                    "message": "Report cannot be approved from its current status.",
                 })
 
-        # ----------------------------------------------------
-        # Prepare update
-        # ----------------------------------------------------
-
         now = datetime.now(timezone.utc).isoformat()
-
         patch = {
             "reviewed_by": identity["uid"],
             "review_notes": notes,
@@ -585,10 +232,6 @@ def review_report_api(
             "updated_at": now,
         }
 
-        # ----------------------------------------------------
-        # Request revisions
-        # ----------------------------------------------------
-
         if action == "request_revision":
             patch.update({
                 "workflow_status": "needs_revision",
@@ -596,25 +239,14 @@ def review_report_api(
                 "visible_to_patient": False,
                 "approval_required": True,
             })
-
-        # ----------------------------------------------------
-        # Doctor approval is not final patient approval.
-        # The report proceeds to supervisor review.
-        # ----------------------------------------------------
-
-        elif role == "doctor":
+        elif role == "clinician":
+            # A clinician review is not final patient approval.
             patch.update({
                 "workflow_status": "pending_supervisor_review",
                 "status": "pending_supervisor_review",
                 "visible_to_patient": False,
                 "approval_required": True,
             })
-
-        # ----------------------------------------------------
-        # Final approval by supervisor, department management,
-        # or admin.
-        # ----------------------------------------------------
-
         else:
             patch.update({
                 "workflow_status": "approved",
@@ -625,52 +257,124 @@ def review_report_api(
                 "approved_at": now,
             })
 
-        # ----------------------------------------------------
-        # Persist update
-        # ----------------------------------------------------
-
         updated = database._json_request(
-            "PATCH",
-            "analyses",
-            patch,
-            params={
-                "id": f"eq.{analysis_id}",
-            },
+            "PATCH", "analyses", patch, params={"id": f"eq.{analysis_id}"}
         )
-
-        updated_row = (
+        saved_row = (
             updated[0]
             if isinstance(updated, list) and updated
-            else {
-                "id": analysis_id,
-                **patch,
-            }
+            else {"id": analysis_id, **patch}
         )
 
+        # Return the resolved workflow status so the client knows exactly
+        # what state the report is in after this action.
         return _ok({
             "status": "success",
             "message": "Review status updated.",
-            "analysis": updated_row,
+            "workflow_status": saved_row.get("workflow_status") or patch.get("workflow_status"),
+            "visible_to_patient": bool(saved_row.get("visible_to_patient")),
+            "analysis": saved_row,
         })
-
     except PermissionError as exc:
-        message = str(exc)
-
         return _ok({
-            "status": (
-                "unauthorized"
-                if "unauthorized" in message
-                else "forbidden"
-            ),
-            "message": message,
+            "status": "unauthorized" if "unauthorized" in str(exc) else "forbidden",
+            "message": str(exc),
         })
-
     except Exception:
         logger.exception("review_report failed")
+        return _ok({"status": "error", "message": "Unable to update report review status."})
+
+
+# ----------------------------------------------------------------
+# UPDATE REPORT CONTENT (clinician/supervisor editing before approval)
+# ----------------------------------------------------------------
+def update_report_content_api(
+    analysis_id: str,
+    findings: str,
+    impression: str,
+    recommendations_json: str,
+    firebase_token: str,
+) -> str:
+    """Allow a clinician/supervisor to edit report content before approval.
+
+    Approval is final; once approved the report cannot be edited via this
+    endpoint. The edit is applied to both report_ar and report_en so both
+    language payloads remain consistent, and the editor identity is stored
+    in each payload for audit purposes.
+    """
+    try:
+        identity = _identity(firebase_token)
+        role = identity["role"]
+        if role not in {"clinician", "supervisor", "department_head", "admin"}:
+            return _ok({"status": "forbidden", "message": "Review role required."})
+
+        analysis_id = (analysis_id or "").strip()
+        if not analysis_id:
+            return _ok({"status": "invalid_action", "message": "analysis_id is required."})
+
+        row = _row(analysis_id)
+        if not row:
+            return _ok({"status": "not_found", "message": "Report not found."})
+        if role != "admin" and not _can_read(identity, row):
+            return _ok({"status": "forbidden", "message": "Report is outside your assigned scope."})
+
+        current_status = str(row.get("workflow_status") or "").strip().lower()
+        if current_status == "approved":
+            return _ok({
+                "status": "invalid_transition",
+                "message": "Approved reports cannot be edited.",
+            })
+
+        # Parse recommendations JSON. Accept either a JSON array of strings
+        # or a single string; fall back to an empty list on parse failure.
+        recommendations: list = []
+        if recommendations_json:
+            try:
+                parsed = json.loads(recommendations_json)
+                if isinstance(parsed, list):
+                    recommendations = [str(x) for x in parsed if str(x).strip()]
+                elif isinstance(parsed, str) and parsed.strip():
+                    recommendations = [parsed]
+            except Exception:
+                recommendations = [recommendations_json]
+
+        now = datetime.now(timezone.utc).isoformat()
+        updated_reports = {}
+
+        for lang_key in ("report_ar", "report_en"):
+            existing = row.get(lang_key) or {}
+            if not isinstance(existing, dict):
+                existing = {}
+
+            if (findings or "").strip():
+                existing["findings"] = findings.strip()
+            if (impression or "").strip():
+                existing["impression"] = impression.strip()
+            if recommendations:
+                existing["recommendations"] = recommendations
+
+            existing["edited_by"] = identity["uid"]
+            existing["edited_at"] = now
+            updated_reports[lang_key] = existing
+
+        patch = {
+            "report_ar": updated_reports.get("report_ar"),
+            "report_en": updated_reports.get("report_en"),
+            "updated_at": now,
+        }
+
+        database._json_request("PATCH", "analyses", patch, params={"id": f"eq.{analysis_id}"})
 
         return _ok({
-            "status": "error",
-            "message": (
-                "Unable to update report review status."
-            ),
-        })
+            "status": "success",
+            "message": "Report content updated.",
+            "analysis_id": analysis_id,
+        })
+    except PermissionError as exc:
+        return _ok({
+            "status": "unauthorized" if "unauthorized" in str(exc) else "forbidden",
+            "message": str(exc),
+        })
+    except Exception:
+        logger.exception("update_report_content failed")
+        return _ok({"status": "error", "message": "Unable to update report content."})