Cache built-in example assessments

Co-Authored-By: codex <codex@openai.com>

README.md

@@ -84,9 +84,14 @@ See [local model setup](docs/local_model_setup.md) and
 The app sends text and optional image data to the configured multimodal
 OpenAI-compatible endpoint and validates its structured response.
 
-There is no rule-based or sample fallback. If credentials are missing, the
-endpoint is unavailable, or the model returns invalid output, the app displays
-a clear error and does not manufacture an assessment.
+The six built-in text and screenshot examples use precomputed assessments.
+Trying those examples does not call or wake the Modal endpoint. Editing an
+example or uploading a different image switches back to normal model analysis.
+
+There is no rule-based or sample fallback for user-submitted input. If
+credentials are missing, the endpoint is unavailable, or the model returns
+invalid output, the app displays a clear error and does not manufacture an
+assessment.
 
 ## Architecture
 

app.py

@@ -36,6 +36,116 @@ REQUIRED_FIELDS = {
     "safe_next_steps",
     "reply_draft",
 }
+EXAMPLE_ASSESSMENTS: dict[str, dict[str, Any]] = {
+    "text-courier": {
+        "risk_label": "Likely scam",
+        "simple_explanation": (
+            "This message uses an urgent parcel fee and an unofficial-looking "
+            "link to pressure the recipient into paying."
+        ),
+        "red_flags": [
+            "Unexpected delivery fee",
+            "Threat that the parcel will be destroyed",
+            "Link does not clearly belong to Pakistan Post",
+        ],
+        "safe_next_steps": [
+            "Do not open the link or make the payment.",
+            "Check the parcel through the courier's independently found official website.",
+            "Report the message as spam or phishing.",
+        ],
+        "reply_draft": "",
+    },
+    "text-fbr": {
+        "risk_label": "Likely scam",
+        "simple_explanation": (
+            "An unexpected tax refund that asks for CNIC and bank-card details "
+            "is a common identity and payment phishing pattern."
+        ),
+        "red_flags": [
+            "Unexpected refund offer",
+            "Request for CNIC and card details",
+            "Pressure to act today",
+        ],
+        "safe_next_steps": [
+            "Do not submit personal or banking information.",
+            "Check your tax account by navigating to the official FBR website yourself.",
+            "Report the sender through an official complaint channel.",
+        ],
+        "reply_draft": "",
+    },
+    "text-bank": {
+        "risk_label": "Likely scam",
+        "simple_explanation": (
+            "A bank or support representative should never ask you to share an "
+            "OTP. The account-suspension threat is intended to create panic."
+        ),
+        "red_flags": [
+            "Direct request for an OTP",
+            "Threat of immediate account suspension",
+            "Pressure to bypass normal bank security",
+        ],
+        "safe_next_steps": [
+            "Do not share the OTP or reply to the sender.",
+            "Contact the bank using the number on your card or official app.",
+            "Change credentials immediately if an OTP or password was already shared.",
+        ],
+        "reply_draft": "",
+    },
+    "image-courier": {
+        "risk_label": "Likely scam",
+        "simple_explanation": (
+            "This sample screenshot shows a fake delivery-fee message designed "
+            "to send the recipient to an untrusted payment link."
+        ),
+        "red_flags": [
+            "Unexpected courier payment request",
+            "Urgent delivery language",
+            "Untrusted link in the message",
+        ],
+        "safe_next_steps": [
+            "Do not use the link in the screenshot.",
+            "Verify any shipment through the courier's official tracking page.",
+            "Block and report the sender.",
+        ],
+        "reply_draft": "",
+    },
+    "image-mobile": {
+        "risk_label": "Likely scam",
+        "simple_explanation": (
+            "This sample screenshot uses a fake mobile-related offer or alert "
+            "to prompt unsafe contact or disclosure of personal information."
+        ),
+        "red_flags": [
+            "Unsolicited mobile-related claim",
+            "Pressure to respond outside an official app",
+            "Unverified sender details",
+        ],
+        "safe_next_steps": [
+            "Do not reply or share account information.",
+            "Check the claim in the mobile operator's official app or website.",
+            "Report and block the sender.",
+        ],
+        "reply_draft": "",
+    },
+    "image-traffic": {
+        "risk_label": "Likely scam",
+        "simple_explanation": (
+            "This sample screenshot imitates an e-challan notice and pressures "
+            "the recipient to use an unverified payment route."
+        ),
+        "red_flags": [
+            "Unexpected traffic fine",
+            "Unverified payment instructions",
+            "Urgency intended to discourage independent checks",
+        ],
+        "safe_next_steps": [
+            "Do not pay through the message link.",
+            "Check the challan on the relevant official traffic authority website.",
+            "Report the message if no official record exists.",
+        ],
+        "reply_draft": "",
+    },
+}
 
 SYSTEM_PROMPT = """You help people in Pakistan assess notices and messages.
 Return only JSON matching the supplied schema. Use simple, calm English.
@@ -251,10 +361,20 @@ def call_model(text: str, image_data_url: str) -> dict[str, Any]:
     raise RuntimeError("Model request ended without a response.")
 
 
-def analyze_notice(text: str = "", image_data_url: str = "") -> dict[str, Any]:
+def analyze_notice(
+    text: str = "", image_data_url: str = "", example_id: str = ""
+) -> dict[str, Any]:
     """Analyze supplied text/image using the configured model only."""
     text = (text or "").strip()
     image_data_url = image_data_url or ""
+    example_id = (example_id or "").strip()
+    if example_id in EXAMPLE_ASSESSMENTS:
+        return {
+            "ok": True,
+            "assessment": dict(EXAMPLE_ASSESSMENTS[example_id]),
+            "status": model_status(),
+            "source": "cached_example",
+        }
     if not text and not image_data_url:
         return {
             "ok": False,
@@ -298,8 +418,10 @@ app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
 
 
 @app.api(name="analyze", description="Assess a notice for common scam signals.", concurrency_limit=1)
-def analyze_api(text: str = "", image_data_url: str = "") -> dict[str, Any]:
-    return analyze_notice(text, image_data_url)
+def analyze_api(
+    text: str = "", image_data_url: str = "", example_id: str = ""
+) -> dict[str, Any]:
+    return analyze_notice(text, image_data_url, example_id)
 
 
 @app.api(name="status", description="Return model and privacy status.", queue=False)
@@ -351,6 +473,10 @@ def run_self_tests() -> None:
         }
     )
     assert inappropriate["reply_draft"] == ""
+    cached = analyze_notice(example_id="text-bank")
+    assert cached["ok"] is True
+    assert cached["source"] == "cached_example"
+    assert cached["assessment"]["risk_label"] == "Likely scam"
     assert analyze_notice("", "")["ok"] is False
     try:
         normalize_assessment({"risk_label": "Looks normal"})

static/app.js

@@ -19,6 +19,7 @@ const elements = {
 
 let imageDataUrl = "";
 let activeMode = null;
+let activeExampleId = "";
 
 async function callGradioApi(name, data) {
   const response = await fetch(`/gradio_api/call/${name}`, {
@@ -124,13 +125,16 @@ function renderResult(payload) {
 
   elements.source.textContent = payload.source === "model"
     ? "Analyzed by the deployed Qwen model endpoint."
-    : "";
+    : payload.source === "cached_example"
+      ? "Loaded from a precomputed example assessment. No model request was made."
+      : "";
   elements.results.hidden = false;
   elements.results.scrollIntoView({ behavior: "smooth", block: "start" });
 }
 
 function useImage(file) {
   if (!file) return;
+  activeExampleId = "";
   const allowed = ["image/png", "image/jpeg", "image/webp"];
   if (!allowed.includes(file.type)) return showError("Use a PNG, JPG, or WebP image.");
   if (file.size > 8 * 1024 * 1024) return showError("Please choose an image smaller than 8 MB.");
@@ -150,6 +154,7 @@ elements.removeImage.addEventListener("click", (event) => {
   event.preventDefault();
   event.stopPropagation();
   imageDataUrl = "";
+  activeExampleId = "";
   elements.image.value = "";
   elements.preview.removeAttribute("src");
   elements.dropZone.classList.remove("has-image");
@@ -165,6 +170,7 @@ elements.removeImage.addEventListener("click", (event) => {
 }));
 elements.dropZone.addEventListener("drop", (event) => useImage(event.dataTransfer.files[0]));
 elements.text.addEventListener("input", () => {
+  activeExampleId = "";
   elements.charCount.textContent = `${elements.text.value.length.toLocaleString()} / 12,000`;
   if (elements.text.value.trim().length === 1) {
     setMode("text");
@@ -183,6 +189,7 @@ document.querySelectorAll(".example-card").forEach((button) => {
         const reader = new FileReader();
         reader.addEventListener("load", () => {
           imageDataUrl = String(reader.result);
+          activeExampleId = button.dataset.exampleId || "";
           elements.preview.src = imageDataUrl;
           elements.dropZone.classList.add("has-image");
           showError();
@@ -196,6 +203,7 @@ document.querySelectorAll(".example-card").forEach((button) => {
     } else if (button.dataset.example) {
       elements.text.value = button.dataset.example;
       elements.text.dispatchEvent(new Event("input"));
+      activeExampleId = button.dataset.exampleId || "";
       elements.text.focus();
       setMode("text");
       document.querySelector(".workspace").scrollIntoView({ behavior: "smooth" });
@@ -205,6 +213,7 @@ document.querySelectorAll(".example-card").forEach((button) => {
 
 elements.resetButton.addEventListener("click", () => {
   imageDataUrl = "";
+  activeExampleId = "";
   elements.image.value = "";
   elements.preview.removeAttribute("src");
   elements.dropZone.classList.remove("has-image");
@@ -234,7 +243,11 @@ elements.form.addEventListener("submit", async (event) => {
 
   setLoading(true);
   try {
-    renderResult(await callGradioApi("analyze", [elements.text.value, imageDataUrl]));
+    const submittedImage = activeExampleId ? "" : imageDataUrl;
+    renderResult(await callGradioApi(
+      "analyze",
+      [elements.text.value, submittedImage, activeExampleId],
+    ));
   } catch (error) {
     showError(error.message || "The request could not be completed.");
   } finally {

static/index.html

@@ -91,28 +91,28 @@
         <div><p class="eyebrow">Try an example</p><h2 id="examplesTitle">Common messages in Pakistan</h2></div>
       </div>
       <div class="example-grid">
-        <button class="example-card" data-example="PAKISTAN POST: Your parcel address is incomplete. Pay Rs. 85 today at http://pakpost-delivery.xyz or the parcel will be destroyed.">
+        <button class="example-card" data-example-id="text-courier" data-example="PAKISTAN POST: Your parcel address is incomplete. Pay Rs. 85 today at http://pakpost-delivery.xyz or the parcel will be destroyed.">
           <span class="example-icon">PK</span><span><strong>Courier fee</strong><small>Urgent parcel payment link</small></span>
         </button>
-        <button class="example-card" data-example="FBR REFUND: You are eligible for Rs 42,500. Submit your CNIC and bank card details at the link today to receive payment.">
+        <button class="example-card" data-example-id="text-fbr" data-example="FBR REFUND: You are eligible for Rs 42,500. Submit your CNIC and bank card details at the link today to receive payment.">
           <span class="example-icon">FBR</span><span><strong>Tax refund</strong><small>Unexpected refund request</small></span>
         </button>
-        <button class="example-card" data-example="HBL Security: Your account will be suspended. Share the OTP sent to your phone with our support team immediately.">
+        <button class="example-card" data-example-id="text-bank" data-example="HBL Security: Your account will be suspended. Share the OTP sent to your phone with our support team immediately.">
           <span class="example-icon">OTP</span><span><strong>Bank alert</strong><small>Security code request</small></span>
         </button>
       </div>
 
       <p class="eyebrow" style="margin:28px 0 14px">Real scam screenshots</p>
       <div class="example-grid example-grid-images">
-        <button class="example-card example-image-card" data-image="/static/example-courier.jpeg">
+        <button class="example-card example-image-card" data-example-id="image-courier" data-image="/static/example-courier.jpeg">
           <img src="/static/example-courier.jpeg" alt="Courier scam screenshot" class="example-thumb">
           <span><strong>Courier scam</strong><small>Fake delivery fee message</small></span>
         </button>
-        <button class="example-card example-image-card" data-image="/static/example-mobile.png">
+        <button class="example-card example-image-card" data-example-id="image-mobile" data-image="/static/example-mobile.png">
           <img src="/static/example-mobile.png" alt="Mobile scam screenshot" class="example-thumb">
           <span><strong>Mobile scam</strong><small>Fake mobile operator message</small></span>
         </button>
-        <button class="example-card example-image-card" data-image="/static/example-trafic.png">
+        <button class="example-card example-image-card" data-example-id="image-traffic" data-image="/static/example-trafic.png">
           <img src="/static/example-trafic.png" alt="Traffic challan scam screenshot" class="example-thumb">
           <span><strong>Traffic challan</strong><small>Fake e-challan fine message</small></span>
         </button>