Update app.py

app.py

@@ -1,321 +1,334 @@
 # app.py
-# ---------------------------------------------------------
-# Biomedical Troubleshooting Assistant (Topic-Locked + Guardrails)
-# - Only biomedical device troubleshooting.
-# - /manual to upload PDF/TXT (PHI redacted in excerpts), /clear to remove, /policy to view rules.
-# - Dual guardrails: local regex + LLM JSON classifier.
-# ---------------------------------------------------------
-import os, io, re, json
+import os, re
+from typing import List
 import chainlit as cl
 from dotenv import load_dotenv
-from openai import AsyncOpenAI
-from pypdf import PdfReader
+from pydantic import BaseModel, Field
 
-# =========================
-# Config: auto provider
-# =========================
+# === Your agents framework (shim included in ./agents) ===
+from agents import (
+    Agent,
+    Runner,
+    AsyncOpenAI,
+    OpenAIChatCompletionsModel,
+    set_tracing_disabled,
+    function_tool,
+)
+from agents.exceptions import InputGuardrailTripwireTriggered
+
+# -----------------------------
+# Setup: auto provider
+# -----------------------------
 load_dotenv()
-GEMINI_API_KEY  = os.getenv("GEMINI_API_KEY")
-OPENAI_API_KEY  = os.getenv("OPENAI_API_KEY")
+
+GEMINI_API_KEY = os.environ.get("Gem")
+OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY")
 
 if GEMINI_API_KEY:
     PROVIDER = "gemini"
+    API_KEY = GEMINI_API_KEY
+    BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/"
     MODEL_ID = "gemini-2.5-flash"
-    client = AsyncOpenAI(
-        api_key=GEMINI_API_KEY,
-        base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
-    )
 elif OPENAI_API_KEY:
     PROVIDER = "openai"
-    MODEL_ID = "gpt-4o-mini"  # any chat-capable model you have
-    client = AsyncOpenAI(api_key=OPENAI_API_KEY)
+    API_KEY = OPENAI_API_KEY
+    BASE_URL = None
+    MODEL_ID = "gpt-4o-mini"  # any chat-capable OpenAI model
 else:
-    raise RuntimeError("Missing GEMINI_API_KEY or OPENAI_API_KEY.")
-
-# =========================
-# Topic lock & guardrails
-# =========================
-ALLOWED_COMMANDS = ("/manual", "/clear", "/help", "/policy")
-
-TOPIC_KEYWORDS = [
-    "biomedical","biomed","device","equipment","oem","service manual",
-    "troubleshoot","troubleshooting","fault","error","alarm",
-    "probe","sensor","lead","cable","battery","power","calibration","qc","verification","analyzer",
-    "ecg","spo2","oximeter","nibp","ventilator","infusion","pump",
-    "defibrillator","patient monitor","ultrasound","anesthesia","syringe pump",
-]
-
-RE_FORBIDDEN_CLINICAL = re.compile(r"\b(diagnos(e|is|tic)|prescrib|medicat|treat(ment|ing)?|dose|drug|therapy)\b", re.I)
-RE_INVASIVE_REPAIR    = re.compile(r"\b(open(ing)?\s+(the\s+)?(device|casing|cover)|remove\s+cover|solder|reflow|short\s+pin|jumper|board\s+level|replace\s+capacitor|tear\s+down)\b", re.I)
-RE_ALARM_BYPASS       = re.compile(r"\b(bypass|disable|silence)\s+(alarm|alert|safety|interlock)\b", re.I)
-RE_FIRMWARE_TAMPER    = re.compile(r"\b(firmware|bootloader|root|jailbreak|unlock\s+(service|engineer)\s*mode|password\s*override|service\s*code|backdoor)\b", re.I)
+    raise RuntimeError(
+        "Missing GEMINI_API_KEY or OPENAI_API_KEY. Add it to a .env or Space secrets."
+    )
 
-# PHI patterns (best-effort)
-RE_EMAIL = re.compile(r"[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}", re.I)
-RE_PHONE = re.compile(r"(?:\+\d{1,3}[-\s.]*)?(?:\(?\d{3,4}\)?[-\s.]*)?\d{3}[-\s.]?\d{4}")
-RE_CNIC  = re.compile(r"\b\d{5}-\d{7}-\d\b")  # Pakistan CNIC
-RE_MRN   = re.compile(r"\b(MRN|Medical\s*Record(?:\s*Number)?)[:\s]*\d{4,}\b", re.I)
-RE_ADDRESS_HINT = re.compile(r"\b(address|street|road|block|apt|flat|house)\b", re.I)
+set_tracing_disabled(disabled=True)
 
-def on_topic(text: str) -> bool:
-    low = (text or "").lower().strip()
-    if not low:
-        return False
-    if any(low.startswith(cmd) for cmd in ALLOWED_COMMANDS):
-        return True
-    return any(k in low for k in TOPIC_KEYWORDS)
+ext_client: AsyncOpenAI = AsyncOpenAI(
+    api_key=API_KEY,
+    base_url=BASE_URL,
+)
+llm_model: OpenAIChatCompletionsModel = OpenAIChatCompletionsModel(
+    model=MODEL_ID,
+    openai_client=ext_client,
+)
 
-def local_guard_check(text: str) -> list:
-    """Return a list of violations detected locally (fast, offline)."""
-    low = (text or "").lower()
-    issues = []
-    if RE_FORBIDDEN_CLINICAL.search(low): issues.append("clinical_advice")
-    if RE_INVASIVE_REPAIR.search(low):    issues.append("invasive_repair")
-    if RE_ALARM_BYPASS.search(low):       issues.append("alarm_bypass")
-    if RE_FIRMWARE_TAMPER.search(low):    issues.append("firmware_tamper")
-    # PHI sharing/collection indicators
-    if RE_EMAIL.search(text) or RE_PHONE.search(text) or RE_CNIC.search(text) or RE_MRN.search(text) or RE_ADDRESS_HINT.search(text):
-        issues.append("phi_share_or_collect")
-    return issues
+# -----------------------------
+# Tools (function calling)
+# -----------------------------
+@function_tool
+def infer_modality_from_filename(filename: str) -> dict:
+    """
+    Guess modality (MRI / X-ray / CT / Ultrasound) from filename hints.
+    Returns: {"modality": "<guess or unknown>"}
+    """
+    f = (filename or "").lower()
+    mapping = {
+        "xray": "X-ray", "x_ray": "X-ray", "xr": "X-ray", "chest": "X-ray",
+        "mri": "MRI", "t1": "MRI", "t2": "MRI", "flair": "MRI", "dwi": "MRI",
+        "ct": "CT", "cta": "CT",
+        "ultrasound": "Ultrasound", "usg": "Ultrasound", "echo": "Ultrasound",
+    }
+    for key, mod in mapping.items():
+        if key in f:
+            return {"modality": mod}
+    return {"modality": "unknown"}
 
-async def llm_guard_check(text: str) -> dict:
-    """Ask model for a strict JSON classification; fallback to {} on error."""
-    guard_system = (
-        "You are a strict safety classifier. Return ONLY a compact JSON object with boolean fields:\n"
-        "{in_scope, clinical_advice, invasive_repair, alarm_bypass, firmware_tamper, phi_share_or_collect}.\n"
-        "Definitions:\n"
-        "- in_scope: true only if user asks about biomedical equipment troubleshooting.\n"
-        "- clinical_advice: true if asking diagnosis/treatment/dosing/medication/therapy.\n"
-        "- invasive_repair: true if asking to open casing, solder, board-level repair.\n"
-        "- alarm_bypass: true if asking to silence/disable/bypass alarms/interlocks.\n"
-        "- firmware_tamper: true if asking to root, jailbreak, firmware hacks, unlock service mode, passwords.\n"
-        "- phi_share_or_collect: true if asking to share/collect personal identifiers or appears to share them.\n"
-        "Respond with JSON only, no prose."
-    )
-    try:
-        resp = await client.chat.completions.create(
-            model=MODEL_ID,
-            messages=[
-                {"role": "system", "content": guard_system},
-                {"role": "user", "content": text}
+@function_tool
+def imaging_reference_guide(modality: str) -> dict:
+    """
+    Educational bullets for acquisition, artifacts, preprocessing, and study tips by modality.
+    No diagnosis. Teaching focus only.
+    """
+    mod = (modality or "").strip().lower()
+    if mod in ["xray", "x-ray", "x_ray"]:
+        return {
+            "acquisition": [
+                "Projection radiography with ionizing radiation.",
+                "Common views: AP/PA/lateral; adjust kVp/mAs and positioning.",
+                "Grids/collimation reduce scatter and improve contrast."
             ],
-        )
-        raw = resp.choices[0].message.content or "{}"
-        # best-effort JSON extraction
-        m = re.search(r"\{.*\}", raw, re.S)
-        if m:
-            return json.loads(m.group(0))
-        return json.loads(raw)  # may already be JSON
-    except Exception:
-        return {}
-
-def redact_phi(s: str) -> str:
-    if not s: return s
-    s = RE_EMAIL.sub("[REDACTED_EMAIL]", s)
-    s = RE_CNIC.sub("[REDACTED_CNIC]", s)
-    s = RE_PHONE.sub("[REDACTED_PHONE]", s)
-    s = RE_MRN.sub("[REDACTED_MRN]", s)
-    # light address hint → don't remove whole text; just bracket note near keyword
-    s = RE_ADDRESS_HINT.sub("[ADDRESS]", s)
-    return s
-
-# =========================
-# Manual helpers
-# =========================
-def extract_pdf_pages(data: bytes):
-    pages = []
-    reader = PdfReader(io.BytesIO(data))
-    for i, pg in enumerate(reader.pages, start=1):
-        try:
-            txt = pg.extract_text() or ""
-        except Exception:
-            txt = ""
-        pages.append({"page": i, "text": txt})
-    return pages
+            "artifacts": [
+                "Motion blur; under/overexposure.",
+                "Grid cut-off, foreign objects (jewelry, buttons).",
+                "Magnification/distortion from object-detector distance."
+            ],
+            "preprocessing": [
+                "Denoising (median/NLM); contrast equalization.",
+                "Window/level exploration for teaching (bone, soft tissue).",
+                "Edge enhancement (unsharp) used sparingly to avoid halos."
+            ],
+            "study_tips": [
+                "Use a systematic pattern (e.g., ABCDE for chest).",
+                "Compare sides; verify markers/labels/devices.",
+                "Relate to clinical scenario during study practice."
+            ],
+        }
+    if mod in ["mri", "mr"]:
+        return {
+            "acquisition": [
+                "MR signal via RF pulses in a magnetic field; sequences set contrast.",
+                "Common: T1, T2, FLAIR, DWI/ADC, GRE/SWI.",
+                "TR/TE/flip angle trade off SNR, contrast, and scan time."
+            ],
+            "artifacts": [
+                "Motion/ghosting; susceptibility near metal/air.",
+                "Chemical shift; Gibbs ringing.",
+                "B0/B1 inhomogeneity causing intensity non-uniformity."
+            ],
+            "preprocessing": [
+                "Bias-field correction (N4).",
+                "Denoising (NLM); spatial normalization/registration.",
+                "Skull stripping (brain) and intensity standardization."
+            ],
+            "study_tips": [
+                "Know each sequence��s emphasis (T1 anatomy; T2 fluid; FLAIR edema).",
+                "Always review diffusion for acute ischemia (with ADC).",
+                "Match window/level across timepoints for fair comparison."
+            ],
+        }
+    if mod in ["ct"]:
+        return {
+            "acquisition": [
+                "Helical CT; HU reflect X-ray attenuation.",
+                "Reconstruction kernels (soft tissue vs bone) affect sharpness/noise.",
+                "Contrast timing (arterial/venous) tailored to clinical question."
+            ],
+            "artifacts": [
+                "Beam hardening streaks; partial volume; motion.",
+                "Metal artifacts; MAR algorithms can help."
+            ],
+            "preprocessing": [
+                "Denoising (bilateral/NLM) with edge preservation.",
+                "Window/level by organ system; iterative recon options.",
+                "Metal artifact reduction if available."
+            ],
+            "study_tips": [
+                "Use standard planes; scroll systematically.",
+                "Check multiple windows (lung, mediastinum, bone).",
+                "Note size/location; reference HU where teaching-appropriate."
+            ],
+        }
+    # Generic fallback
+    return {
+        "acquisition": [
+            "Acquisition parameters impact contrast, resolution, and noise.",
+            "Positioning and motion control are key to quality."
+        ],
+        "artifacts": [
+            "Motion blur/ghosting; foreign objects can degrade interpretability.",
+            "Under/overexposure or parameter misconfiguration."
+        ],
+        "preprocessing": [
+            "Denoising and contrast normalization for clearer teaching images.",
+            "Registration and standard planes for consistent reviews."
+        ],
+        "study_tips": [
+            "Adopt a checklist and be consistent.",
+            "Understand modality-specific controls (window/level; sequence choice)."
+        ],
+    }
 
-def extract_txt_pages(data: bytes, chunk_chars: int = 1600):
-    try:
-        txt = data.decode("utf-8", errors="ignore")
-    except Exception:
-        txt = ""
-    return [{"page": i + 1, "text": txt[i:i + chunk_chars]} for i in range(0, len(txt), chunk_chars)] or [{"page": 1, "text": ""}]
+@function_tool
+def file_facts(filename: str, size_bytes: int) -> dict:
+    """
+    Lightweight file facts (name and size).
+    """
+    return {"filename": filename, "size_bytes": size_bytes}
 
-def manual_hits(pages, query: str, topk: int = 3):
-    if not pages:
-        return []
-    terms = [w for w in re.findall(r"\w+", (query or "").lower()) if len(w) > 2]
-    scored = []
-    for p in pages:
-        low = (p.get("text") or "").lower()
-        score = sum(low.count(t) for t in terms)
-        if score > 0:
-            scored.append((score, p))
-    scored.sort(key=lambda x: x[0], reverse=True)
-    hits = [p for _, p in scored[:topk]] or pages[:1]
-    def excerpt(text: str, window: int = 380):
-        t = text or ""
-        low = t.lower()
-        idxs = [low.find(tk) for tk in terms if tk in low]
-        start = max(0, min([i for i in idxs if i >= 0], default=0) - window)
-        end = min(len(t), start + 2 * window)
-        return re.sub(r"\s+", " ", t[start:end]).strip()
-    # Redact PHI in excerpts
-    return [f"[p.{h['page']}] {redact_phi(excerpt(h.get('text','')))}" for h in hits]
+# -----------------------------
+# Guardrails (LLM classifier)
+# -----------------------------
+class SafetyCheck(BaseModel):
+    in_scope: bool = Field(description="True if about biomedical imaging education/troubleshooting.")
+    clinical_advice: bool = Field(description="True if asking diagnosis/treatment/dosing/medication.")
+    invasive_repair: bool = Field(description="True if asking to open device/board-level fixes.")
+    alarm_bypass: bool = Field(description="True if asking to bypass/disable safety alarms.")
+    firmware_tamper: bool = Field(description="True if asking for firmware hacks/unlock codes/passwords.")
+    phi_share_or_collect: bool = Field(description="True if trying to share/collect personal identifiers.")
+    reasoning: str
 
-# =========================
-# Tutor prompt
-# =========================
-SYSTEM_PROMPT = (
-    "You are a biomedical device troubleshooting assistant for clinical engineers.\n"
-    "STRICT SCOPE: Only biomedical equipment troubleshooting. If any content appears clinical, you must refuse.\n"
-    "Safety: Education-only. No diagnosis/treatment. No invasive repairs. No alarm bypass. No firmware hacks. "
-    "Do not ask users to share personal identifiers. Defer to OEM manuals and local policy if any conflict.\n\n"
-    "Given a user description of a device and symptom, produce concise bullet lists with exactly these sections:\n"
-    "1) Safety First (non-invasive, patient-first)\n"
-    "2) Likely Causes (ranked)\n"
-    "3) Step-by-Step Checks (do-not-open device; do-not-bypass alarms)\n"
-    "4) Quick Tests / Verification (what, how, with what reference/simulator)\n"
-    "5) Escalate When (clear triggers)\n"
-    "End with a one-line summary. If manual excerpts are provided, incorporate them but state OEM manual prevails.\n"
+guardrail_agent = Agent(
+    name="Safety Classifier",
+    instructions=(
+        "You are a strict safety classifier for a **biomedical imaging education tutor**.\n"
+        "Return ONLY JSON with keys: {in_scope, clinical_advice, invasive_repair, alarm_bypass, "
+        "firmware_tamper, phi_share_or_collect, reasoning}.\n"
+        "- in_scope: true ONLY if the message is about biomedical imaging education/troubleshooting (no diagnosis).\n"
+        "- clinical_advice: diagnosis/treatment/dose/medication/therapy requests.\n"
+        "- invasive_repair: opening casing, soldering, board-level steps.\n"
+        "- alarm_bypass: silencing/disabling alarms or interlocks.\n"
+        "- firmware_tamper: rooting/jailbreaking/unlocking firmware/service modes/passwords.\n"
+        "- phi_share_or_collect: asking to share or store personal identifiers.\n"
+        "Respond with compact JSON, no extra text."
+    ),
+    model=llm_model,
+    output_type=SafetyCheck,
 )
 
-async def call_llm(user_desc: str, manual_excerpts: str = "") -> str:
-    user_block = f"Device/symptom:\n{user_desc.strip()}"
-    if manual_excerpts:
-        user_block += f"\n\nManual excerpts (for reference):\n{manual_excerpts.strip()}"
-    resp = await client.chat.completions.create(
-        model=MODEL_ID,
-        messages=[
-            {"role": "system", "content": SYSTEM_PROMPT},
-            {"role": "user", "content": user_block},
-        ],
-    )
-    return resp.choices[0].message.content or ""
-
-# =========================
-# Session utils & UI
-# =========================
-def set_manual(m): cl.user_session.set("manual", m)
-def get_manual(): return cl.user_session.get("manual")
+# -----------------------------
+# Tutor Agent
+# -----------------------------
+tutor_instructions = (
+    "You are a Biomedical Imaging **Education** Tutor. You explain **how images are acquired**, common **artifacts**, "
+    "and **preprocessing for study/teaching**. You do **NOT** diagnose, identify diseases, or give clinical advice.\n\n"
+    "Always produce a concise, structured answer with bullet points and the following sections in this order:\n"
+    "1) Acquisition overview\n"
+    "2) Common artifacts\n"
+    "3) Preprocessing methods (education/study only)\n"
+    "4) Study tips\n"
+    "5) Caution (one line: education-only; consult qualified clinicians for clinical questions)\n\n"
+    "Use tools to infer modality (from filename) and to fetch a modality-specific reference guide. "
+    "If the modality is unclear, provide a generic but accurate overview and invite the user to specify."
+)
 
-POLICY_TEXT = (
-    "🛡️ **Safety & Scope Policy**\n"
-    "- Scope: Only **biomedical equipment troubleshooting**.\n"
-    "- No clinical advice: diagnosis, treatment, dosing, medications.\n"
-    "- No invasive repairs: opening casing, soldering, board-level fixes.\n"
-    "- No alarm bypass / interlock disable.\n"
-    "- No firmware tampering / service mode hacks / passwords.\n"
-    "- No collection or sharing of personal identifiers (emails, phone, CNIC, MRN, addresses).\n"
-    "- OEM manuals & local policy take priority."
+tutor_agent = Agent(
+    name="Biomedical Imaging Tutor",
+    instructions=tutor_instructions,
+    model=llm_model,
+    tools=[infer_modality_from_filename, imaging_reference_guide, file_facts],
 )
 
+# -----------------------------
+# UI strings
+# -----------------------------
 WELCOME = (
-    "🛠️ **Biomedical Troubleshooting Assistant (Topic-Locked + Guardrails)**\n"
-    "Describe the **device & symptom** (e.g., “ECG noisy baseline”).\n"
-    "Commands: **/manual** upload PDF/TXT (PHI auto-redacted in excerpts), **/clear** remove manual, **/policy** view rules, **/help** usage.\n"
-    "Education-only. OEM manual & policy take priority."
+    "🎓 **Multimodal Biomedical Imaging Tutor**\n\n"
+    "Upload an **MRI/X-ray/CT/Ultrasound** image (PNG/JPG), then ask what you’d like to learn.\n"
+    "I’ll explain acquisition, common artifacts, and preprocessing methods for study.\n\n"
+    "⚠️ Education only — no diagnosis or clinical advice."
 )
 
+REFUSAL = (
+    "🚫 I can’t help with diagnosis/treatment, invasive repair, alarm bypass, firmware hacks, or collecting personal data.\n"
+    "I can explain **imaging acquisition, artifacts, and preprocessing** for education."
+)
+
+# -----------------------------
+# Chainlit flows
+# -----------------------------
 @cl.on_chat_start
-async def start():
-    set_manual(None)
+async def on_chat_start():
     await cl.Message(content=WELCOME).send()
+    files = await cl.AskFileMessage(
+        content="Please upload an **MRI/X-ray/CT/Ultrasound** image (PNG/JPG).",
+        accept=["image/png", "image/jpeg"],
+        max_size_mb=15,
+        max_files=1,
+        timeout=180,
+    ).send()
 
-# =========================
-# Main handler
-# =========================
-@cl.on_message
-async def main(message: cl.Message):
-    text = (message.content or "").strip()
+    if not files:
+        await cl.Message(content="No file uploaded yet. You can still ask general imaging questions.").send()
+        return
 
-    # Commands
-    if text.lower().startswith("/help"):
-        await cl.Message(content=WELCOME).send(); return
-    if text.lower().startswith("/policy"):
-        await cl.Message(content=POLICY_TEXT).send(); return
+    f = files[0]
+    cl.user_session.set("last_file_name", f.name)
+    cl.user_session.set("last_file_size", f.size)
 
-    if text.lower().startswith("/manual"):
-        files = await cl.AskFileMessage(
-            content="Upload the **service manual** (PDF or TXT). Max ~20 MB.",
-            accept=["application/pdf", "text/plain"],
-            max_files=1, max_size_mb=20, timeout=240
-        ).send()
-        if not files:
-            await cl.Message(content="No file received.").send(); return
-        f = files[0]
-        data = getattr(f, "content", None)
-        if data is None and getattr(f, "path", None):
-            with open(f.path, "rb") as fh: data = fh.read()
-        try:
-            pages = extract_pdf_pages(data) if (f.mime == "application/pdf" or f.name.lower().endswith(".pdf")) else extract_txt_pages(data)
-        except Exception as e:
-            await cl.Message(content=f"Couldn't read the manual: {e}").send(); return
-        set_manual({"name": f.name, "pages": pages})
-        await cl.Message(content=f"✅ Manual indexed: **{f.name}** — {len(pages)} page-chunks.").send()
-        return
+    await cl.Message(
+        content=f"Received **{f.name}** ({f.size} bytes). "
+                "Now type what you want to learn (e.g., *Explain acquisition & artifacts for this image*)."
+    ).send()
 
-    if text.lower().startswith("/clear"):
-        set_manual(None)
-        await cl.Message(content="Manual cleared.").send()
+@cl.on_message
+async def on_message(message: cl.Message):
+    text = (message.content or "").strip()
+    if not text:
+        await cl.Message(content="Please describe what you want to learn about the uploaded image.").send()
         return
 
-    # Topic lock (coarse)
-    if not on_topic(text):
-        await cl.Message(
-            content="🚫 I only handle **biomedical device troubleshooting**.\n"
-                    "Describe the *device & symptom* (e.g., “Infusion pump occlusion alarm”).\n"
-                    "Use **/manual** to upload a service manual."
-        ).send()
-        return
+    # ---- Guardrails pass
+    try:
+        verdict = await Runner.run(guardrail_agent, text)
+        flags = verdict.final_output_as(SafetyCheck)
+        if (not flags.in_scope) or flags.clinical_advice or flags.invasive_repair or flags.alarm_bypass \
+           or flags.firmware_tamper or flags.phi_share_or_collect:
+            await cl.Message(content=REFUSAL).send()
+            return
+    except Exception:
+        # If guard fails, continue but still remain educational-only in the tutor prompt.
+        pass
 
-    # Local guard (fast)
-    local_issues = local_guard_check(text)
-    if local_issues:
-        reason_map = {
-            "clinical_advice": "clinical diagnosis/treatment",
-            "invasive_repair": "invasive repair steps",
-            "alarm_bypass": "bypassing alarms/interlocks",
-            "firmware_tamper": "firmware tampering or service-mode hacks",
-            "phi_share_or_collect": "sharing or collecting personal identifiers",
-        }
-        reasons = ", ".join(reason_map[k] for k in local_issues if k in reason_map)
-        await cl.Message(
-            content=f"🚫 I can’t help with {reasons}. I only provide **safe, non-invasive biomedical equipment troubleshooting**.\n{POLICY_TEXT}"
-        ).send()
-        return
+    # Context from uploaded file
+    file_name = cl.user_session.get("last_file_name")
+    file_size = cl.user_session.get("last_file_size")
 
-    # LLM guard (nuanced)
-    verdict = await llm_guard_check(text)
-    if verdict:
-        if not verdict.get("in_scope", True):
-            await cl.Message(
-                content="🚫 Off-topic. I only support **biomedical device troubleshooting**.\n" + POLICY_TEXT
-            ).send(); return
-        for key, msg in [
-            ("clinical_advice", "clinical diagnosis/treatment"),
-            ("invasive_repair", "invasive repair steps"),
-            ("alarm_bypass", "bypassing alarms/interlocks"),
-            ("firmware_tamper", "firmware tampering or service-mode hacks"),
-            ("phi_share_or_collect", "sharing or collecting personal identifiers"),
-        ]:
-            if verdict.get(key):
-                await cl.Message(
-                    content=f"🚫 I can’t help with {msg}. I only provide **safe, non-invasive biomedical equipment troubleshooting**.\n{POLICY_TEXT}"
-                ).send()
-                return
+    context_note = []
+    if file_name: context_note.append(f"File: {file_name}")
+    if file_size is not None: context_note.append(f"Size: {file_size} bytes")
+    context_block = "\n".join(context_note)
 
-    # Manual excerpts (with PHI redaction)
-    manual = cl.user_session.get("manual")
-    excerpts = ""
-    if manual and manual.get("pages"):
-        excerpts = "\n".join(manual_hits(manual["pages"], text, topk=3))
+    # Compose user query for the tutor
+    user_query = text
+    if context_block:
+        user_query = f"{text}\n\n[Context]\n{context_block}"
 
-    # Call LLM for the plan
+    # Run tutor agent
     try:
-        answer = await call_llm(text, excerpts)
+        result = await Runner.run(tutor_agent, user_query)
+    except InputGuardrailTripwireTriggered:
+        await cl.Message(content=REFUSAL).send()
+        return
     except Exception as e:
-        await cl.Message(content=f"⚠️ LLM call failed ({PROVIDER}): {e}").send()
+        await cl.Message(content=f"⚠️ Tutor failed: {e}").send()
         return
 
-    prefix = f"📄 Using manual: **{manual['name']}**\n\n" if (manual and manual.get("name")) else ""
-    await cl.Message(content=prefix + (answer or "I couldn’t generate a plan.")).send()
+    # Tool-derived quick guide (deterministic; helpful even if the model didn’t call tools)
+    try:
+        mod_guess = infer_modality_from_filename(file_name or "")
+        modality = mod_guess.get("modality", "unknown")
+        guide = imaging_reference_guide(modality)
+        def bullets(arr: List[str]): return "\n".join(f"- {x}" for x in (arr or [])) or "- (general)"
+        facts_md = (
+            f"### 📁 File\n- Name: `{file_name or 'unknown'}`\n- Size: `{file_size if file_size is not None else 'unknown'} bytes`\n\n"
+            f"### 🔎 Modality (guess)\n- {modality}\n\n"
+            f"### 📚 Reference Guide\n"
+            f"**Acquisition**\n{bullets(guide.get('acquisition'))}\n\n"
+            f"**Common Artifacts**\n{bullets(guide.get('artifacts'))}\n\n"
+            f"**Preprocessing**\n{bullets(guide.get('preprocessing'))}\n\n"
+            f"**Study Tips**\n{bullets(guide.get('study_tips'))}\n\n"
+            f"> ⚠️ Education only — no diagnosis.\n"
+        )
+    except Exception:
+        facts_md = ""
+
+    answer = result.final_output or "I couldn’t generate an explanation."
+    await cl.Message(content=f"{facts_md}\n---\n{answer}").send()