Add notice image guidance and update runtime docs

Show a clear warning when an uploaded image has no readable notice text, and document the English-only ZeroGPU Transformers deployment.

Co-authored-by: Codex <codex@openai.com>

README.md

@@ -32,8 +32,13 @@ short_description: Review suspicious Pakistani messages before you act.
 
 # NoticeCheck
 
-NoticeCheck is a local-first safety assistant for suspicious Pakistani messages,
-bills, bank alerts, challans, courier notices, and screenshots. It returns:
+This repository is the local version of the
+[Pakistan Notice Helper Hugging Face Space](https://huggingface.co/spaces/build-small-hackathon/pakistan-notice-helper).
+It keeps the same notice-checking purpose, but uses a redesigned interface and
+uses the Hugging Face ZeroGPU runtime.
+
+NoticeCheck is a safety assistant for suspicious Pakistani messages, bills,
+bank alerts, challans, courier notices, and screenshots. It returns:
 
 - a risk label
 - a short explanation based on visible evidence
@@ -61,14 +66,17 @@ MiniCPM5-1B through Transformers on ZeroGPU
 Structured risk assessment
 ```
 
-- **Space reasoning:** `openbmb/MiniCPM5-1B` through Transformers
+- **Reasoning:** `openbmb/MiniCPM5-1B` through Transformers
 - **OCR:** `nvidia/NVIDIA-Nemotron-Parse-v1.2` through Transformers
-- **Hosting:** Hugging Face Spaces ZeroGPU
-- **Interface:** custom English HTML, CSS, and JavaScript
+- **Compute:** Hugging Face Spaces ZeroGPU
+- **Interface:** redesigned custom HTML, CSS, and JavaScript
+- **Language:** English only
 
 The application does not use a remote model API and has no heuristic assessment
 fallback. Model and OCR failures are returned explicitly.
 
+Both models run through Transformers on the Hugging Face ZeroGPU deployment.
+
 ## Repository Layout
 
 ```text
@@ -104,13 +112,17 @@ python -m unittest
 node --check static/app.js
 ```
 
-## Language Limits
+## English-Only Interface
 
-Nemotron-Parse v1.2 supports document text extraction across multiple
-languages. Urdu-script screenshots are best effort.
+This version intentionally uses an English-only interface and requests English
+analysis from the model. Most notices and scam messages targeted by the project
+contain English or English mixed with common local terms. The local model also
+understands the task instructions and produces structured English results more
+reliably than Urdu output.
 
-MiniCPM5-1B is officially evaluated in English and Chinese. Urdu and Roman Urdu
-responses remain best effort and require task-specific evaluation.
+Screenshot OCR may detect text from other languages, but the generated
+assessment is intended to be in English. Urdu-language output is not currently
+supported.
 
 ## Privacy-Safe Traces
 

app/model_endpoint.py

@@ -16,7 +16,7 @@ import spaces
 from huggingface_hub import hf_hub_download
 
 from app.config import ModelConfig, model_config
-from app.ocr import OCRRuntimeError, extract_text, ocr_installed
+from app.ocr import NoReadableTextError, OCRRuntimeError, extract_text, ocr_installed
 from app.prompts import SYSTEM_PROMPT
 from app.schema import OUTPUT_SCHEMA, normalize_assessment
 
@@ -34,6 +34,10 @@ class ModelRuntimeError(RuntimeError):
     """A sanitized local model failure safe to expose through the API."""
 
 
+class NoticeImageInputError(ModelRuntimeError):
+    """The uploaded image is not a readable notice or message."""
+
+
 def model_status() -> dict[str, Any]:
     config = model_config()
     on_space = bool(os.getenv("SPACE_ID"))
@@ -297,6 +301,8 @@ def call_model(
     if image_data_url:
         try:
             ocr_text = extract_text(image_data_url)
+        except NoReadableTextError as exc:
+            raise NoticeImageInputError(str(exc)) from exc
         except OCRRuntimeError as exc:
             raise ModelRuntimeError(str(exc)) from exc
         input_text = (

app/ocr.py

@@ -32,6 +32,17 @@ class OCRRuntimeError(RuntimeError):
     """A sanitized OCR failure safe to expose through the API."""
 
 
+class NoReadableTextError(OCRRuntimeError):
+    """The image was valid, but it did not contain useful notice text."""
+
+
+def _has_readable_text(text: str) -> bool:
+    """Reject empty OCR output and model markup without visible notice text."""
+    visible_text = re.sub(r"<[^>]+>", " ", text)
+    alphanumeric = [char for char in visible_text if char.isalnum()]
+    return len(alphanumeric) >= 4 and any(char.isalpha() for char in alphanumeric)
+
+
 def ocr_installed() -> bool:
     try:
         from transformers import AutoModel, AutoProcessor  # noqa: F401
@@ -144,8 +155,10 @@ def extract_text(image_data_url: str) -> str:
         else:
             text = generated_text.strip()
 
-        if not text:
-            raise OCRRuntimeError("No readable text was found in the screenshot.")
+        if not _has_readable_text(text):
+            raise NoReadableTextError(
+                "No readable notice text was found in the screenshot."
+            )
         return text
     except OCRRuntimeError:
         raise

app/service.py

@@ -176,13 +176,23 @@ def analyze_notice(
                 "source": "local_model",
             }
         )
+    except model_endpoint.NoticeImageInputError:
+        return finish(
+            {
+                "ok": False,
+                "warning": True,
+                "error": (
+                    "This image does not contain readable notice text. "
+                    "Upload a clear screenshot of the full notice or message."
+                ),
+                "error_code": "noticeImageRequiredWarning",
+                "status": status,
+            }
+        )
     except model_endpoint.ModelRuntimeError as exc:
         if image_data_url and "Nemotron-Parse" in str(exc):
             message = str(exc)
             error_code = "ocrUnavailableError"
-        elif image_data_url and "No readable text" in str(exc):
-            message = str(exc)
-            error_code = "ocrNoTextError"
         else:
             message = "The local model is unavailable or could not be loaded."
             error_code = "modelUnavailableError"

requirements-local.txt

@@ -1,7 +0,0 @@
---extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
-
-gradio==6.17.3
-huggingface-hub>=0.34,<2
-llama-cpp-python==0.3.28
-numpy>=1.26
-pillow>=12

static/app.js

@@ -92,7 +92,7 @@ const translations = {
     modelInvalidError: "The model returned an incomplete response. Please try again.",
     gpuQuotaError: "GPU quota exceeded. Please try again later or authenticate with a Hugging Face token for more quota.",
     ocrUnavailableError: "Nemotron-Parse is unavailable. Paste the notice text instead.",
-    ocrNoTextError: "No readable text was found in the screenshot.",
+    noticeImageRequiredWarning: "This image does not contain readable notice text. Upload a clear screenshot of the full notice or message.",
     ocrLanguageError: "This language may not be fully supported. Results may vary.",
     imageTypeError: "Use a PNG, JPG, or WebP image.",
     imageSizeError: "Please choose an image smaller than 8 MB.",
@@ -177,7 +177,7 @@ const translations = {
     modelInvalidError: "ماڈل کا جواب مکمل نہیں تھا۔ براہ کرم دوبارہ کوشش کریں۔",
     gpuQuotaError: "GPU کوٹہ ختم ہو گیا۔ براہ کرم بعد میں دوبارہ کوشش کریں یا مزید کوٹہ کے لیے Hugging Face ٹوکن سے تصدیق کریں۔",
     ocrUnavailableError: "Nemotron-Parse دستیاب نہیں۔ نوٹس کا متن پیسٹ کریں۔",
-    ocrNoTextError: "اسکرین شاٹ میں پڑھنے کے قابل متن نہیں ملا۔",
+    noticeImageRequiredWarning: "اس تصویر میں نوٹس کا واضح متن موجود نہیں ہے۔ مکمل نوٹس یا پیغام کا صاف اسکرین شاٹ اپ لوڈ کریں۔",
     ocrLanguageError: "یہ زبان مکمل طور پر سپورٹ نہیں ہو سکتی۔ نتائج مختلف ہو سکتے ہیں۔",
     imageTypeError: "PNG، JPG یا WebP تصویر استعمال کریں۔",
     imageSizeError: "براہ کرم 8 MB سے چھوٹی تصویر منتخب کریں۔",
@@ -329,9 +329,10 @@ async function loadStatus() {
   }
 }
 
-function showError(message = "") {
+function showError(message = "", tone = "error") {
   elements.error.textContent = message;
   elements.error.classList.toggle("visible", Boolean(message));
+  elements.error.classList.toggle("warning", Boolean(message) && tone === "warning");
 }
 
 function setMode(mode) {
@@ -369,6 +370,12 @@ function renderResult(payload) {
     const localizedError = payload.error_code
       ? translations[currentLanguage][payload.error_code]
       : "";
+    if (payload.warning) {
+      elements.results.hidden = true;
+      setStatus(payload.status);
+      showError(localizedError || payload.error || t("analyzeError"), "warning");
+      return;
+    }
     throw new Error(localizedError || payload.error || t("analyzeError"));
   }
   const result = payload.assessment;

static/styles.css

@@ -196,6 +196,7 @@ textarea:disabled { opacity: .45; background: #f5f3ff; cursor: not-allowed; }
 .form-actions { display: flex; justify-content: center; align-items: center; gap: 14px; margin-top: 26px; }
 .form-error { display: none; margin-top: 16px; padding: 12px 14px; border-radius: 12px; background: #fff0ef; color: #8d2722; font-size: 13px; }
 .form-error.visible { display: block; }
+.form-error.warning { background: #fff8df; color: #72520b; border: 1px solid #ead58d; }
 .trace-consent {
   margin-top: 18px; padding: 13px 15px; display: flex; align-items: flex-start; gap: 11px;
   border: 1px solid var(--line); border-radius: 14px; background: #faf9ff; cursor: pointer;

tests/test_tracing.py

@@ -400,6 +400,26 @@ class TraceTests(unittest.TestCase):
         self.assertEqual(result["error_code"], "modelInvalidError")
         self.assertNotIn("PRIVATE RAW OUTPUT", json.dumps(queue_mock.call_args.kwargs))
 
+    def test_image_without_notice_text_returns_input_warning(self) -> None:
+        with patch(
+            "app.model_endpoint.model_status",
+            return_value={"connected": True, "label": "ready"},
+        ), patch(
+            "app.model_endpoint.call_model",
+            side_effect=model_endpoint.NoticeImageInputError(
+                "No readable notice text was found in the screenshot."
+            ),
+        ):
+            result = app.analyze_notice(
+                image_data_url="data:image/png;base64,AAAA",
+                save_trace=False,
+            )
+
+        self.assertFalse(result["ok"])
+        self.assertTrue(result["warning"])
+        self.assertEqual(result["error_code"], "noticeImageRequiredWarning")
+        self.assertTrue(result["status"]["connected"])
+
     def test_normalization_failure_uses_normalize_stage(self) -> None:
         telemetry: dict = {}
         with self.assertRaises(ValueError):
@@ -467,6 +487,28 @@ class TraceTests(unittest.TestCase):
         self.assertEqual(text, "PAKISTAN POST\n\nPay Rs. 85 now")
         fake_pipeline.assert_called_once()
 
+    def test_ocr_readability_rejects_parser_markup_without_notice_text(self) -> None:
+        self.assertFalse(
+            ocr._has_readable_text(
+                "<picture><x_10><y_20><x_900><y_700></picture>"
+            )
+        )
+        self.assertTrue(ocr._has_readable_text("Pay Rs. 85 now"))
+        self.assertTrue(ocr._has_readable_text("آپ کا بل 500 روپے ہے"))
+
+    def test_no_text_ocr_error_becomes_notice_image_input_error(self) -> None:
+        with patch(
+            "app.model_endpoint.extract_text",
+            side_effect=ocr.NoReadableTextError(
+                "No readable notice text was found in the screenshot."
+            ),
+        ):
+            with self.assertRaises(model_endpoint.NoticeImageInputError):
+                model_endpoint.call_model(
+                    "",
+                    "data:image/png;base64,AAAA",
+                )
+
     def test_image_ocr_text_is_passed_to_minicpm(self) -> None:
         config = model_endpoint.model_config()
         fake_model = object()