Polish hackathon documentation

Add Backyard AI Space metadata and consolidate the project, Modal, llama.cpp, trace, and field-note evidence for submission.

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

FIELD_NOTES.md

@@ -1,49 +1,146 @@
-# Field notes
-
-## Architecture findings
-
-- Gradio 6 Server mode provides a FastAPI-compatible `Server`, queued
-  `@app.api` endpoints, SSE results, and `launch()`. This enables a custom
-  frontend without rendering a default Gradio interface.
-- Gradio's documented protocol posts `{"data": [...]}` and then reads an SSE
-  result using the returned event ID. In Server mode the verified routes are
-  `/gradio_api/call/{api_name}` and
-  `/gradio_api/call/{api_name}/{event_id}`.
-- Hugging Face Gradio Spaces launch the file named by `app_file` and honor
-  `sdk_version` from README metadata.
-- The OpenAI Python SDK accepts a custom `base_url`, so it can call llama.cpp
-  and Modal-hosted OpenAI-compatible endpoints without using OpenAI cloud.
-- The experimental Qwen deployment includes `mmproj-F16.gguf`; image analysis
-  depends on that projector. This application intentionally adds no OCR.
-- The application currently uses the deployed Modal URL and
-  `qwen3.6-27b-mtp` as built-in defaults. Environment variables can override
-  them for a future local deployment. Model failures do not trigger a
-  rule-based assessment.
+# Field Notes
+
+## Problem and scope
+
+People in Pakistan regularly receive messages that imitate banks, couriers,
+tax authorities, traffic police, utilities, and mobile operators. The difficult
+part is often not reading the message but deciding what to do next without
+opening an unsafe link, calling an untrusted number, or sharing an OTP.
+
+Pakistan Notice Helper is therefore a triage tool, not an authenticity checker.
+It accepts text or a screenshot and returns a risk label, a short explanation,
+visible red flags, and safe next steps. The wording deliberately avoids claims
+that a message is officially genuine or fraudulent.
+
+This scope fits the **Backyard AI** track: it addresses a specific local safety
+problem with a model small enough to run through `llama.cpp`.
+
+## Product decisions
+
+- Use simple English rather than legal or security terminology.
+- Support screenshots because many suspicious messages arrive through SMS,
+  WhatsApp, and social media.
+- Treat every URL, phone number, and contact instruction in the submitted
+  message as untrusted data.
+- Never invent an assessment when inference fails. The interface shows an
+  explicit error instead of falling back to rules or cached samples.
+- Keep built-in examples fast with model-generated cached results, while any
+  edited or new input always uses the live model.
+- Show a reply draft only for uncertain cases where clarification may be safe.
+  Likely scams do not encourage further engagement.
+
+## Small-model stack
+
+The primary model is `unsloth/Qwen3.6-27B-MTP-GGUF`, using the
+`Qwen3.6-27B-UD-Q4_K_XL.gguf` quantization and `mmproj-F16.gguf` vision
+projector. At 27B parameters it stays below the hackathon's 32B limit.
+
+Modal supplies an L40S GPU and persistent model storage. A pinned,
+CUDA-enabled `llama.cpp` build runs `llama-server` and exposes an
+OpenAI-compatible endpoint. The OpenAI Python package is used only as an HTTP
+client with a custom `base_url`; no request is sent to OpenAI.
+
+Key measured results:
+
+| Measurement | Result |
+| --- | --- |
+| Model file | 17,909,097,600 bytes |
+| Vision projector | 927,607,360 bytes |
+| Warm-volume model load | 12.03 seconds |
+| GPU memory after load | 17,909 MiB of 46,068 MiB |
+| Structured text inference | 5.27 seconds |
+| Screenshot tests | 8.94 and 9.07 seconds |
+| MTP draft acceptance | 127 of 212 tokens (59.9%) |
+
+The full setup and measurements are documented in
+[the model experiment notes](docs/model_experiment_notes.md).
+
+## Gradio and Space architecture
+
+`gradio.Server` provides queued API routes and Hugging Face Spaces hosting
+without imposing the default Gradio interface. A local HTML, CSS, and
+JavaScript frontend calls the Gradio POST and SSE protocol:
+
+```text
+Browser
+  -> custom mobile-first frontend
+  -> queued gradio.Server endpoint
+  -> OpenAI-compatible client
+  -> Modal proxy-authenticated web server
+  -> CUDA llama.cpp
+  -> Qwen3.6 27B MTP GGUF + vision projector
+```
+
+The verified Server mode routes are `/gradio_api/call/{api_name}` and
+`/gradio_api/call/{api_name}/{event_id}`. The Space README pins the Gradio
+version and names `app.py` as its entry point.
+
+## What failed and changed
+
+- Thinking mode initially consumed the 500-token output budget without
+  returning final JSON. Disabling thinking produced reliable structured
+  responses.
+- A dense Roman Urdu screenshot reached the original completion limit. Image
+  requests now receive a larger token budget.
+- One model response suggested an unverified official-looking domain. The
+  system prompt now forbids invented URLs, phone numbers, organizations, and
+  facts.
+- Modal CLI credentials returned HTTP 401 at the web endpoint. External calls
+  require dedicated Modal Proxy Auth credentials.
+- Model availability cannot be hidden behind a rule-based fallback without
+  making the product misleading. Failed requests therefore remain visible.
+
+## Privacy-safe traces
+
+The optional public trace feature is enabled in the interface but can be
+disabled before each request. It records only allow-listed scalar metadata and
+deterministic summaries.
+
+Text is redacted and capped at 500 characters. Images are represented by a
+fixed description and are never stored. Public traces exclude raw screenshots,
+links, identifiers, generated explanations, reply text, errors, and
+credentials. Upload failures do not block the user response; pending JSONL
+shards remain available for retry.
+
+The dataset and schema are published at
+[build-small-hackathon/pakistan-notice-helper-traces](https://huggingface.co/datasets/build-small-hackathon/pakistan-notice-helper-traces).
 
 ## Pakistan safety patterns
 
-Local checks focus on signals repeatedly present in Pakistani scam advisories
-and reported examples:
+The product focuses on patterns repeatedly present in Pakistani scam
+advisories and reported examples:
 
-- urgency, threats, account suspension, arrest, disconnection, or parcel loss;
+- urgency, threats, suspension, arrest, disconnection, or parcel loss;
 - requests for OTPs, PINs, passwords, CVVs, CNIC details, or card data;
 - payment through message links, personal mobile numbers, wallets, or unusual
   channels;
 - impersonation of tax, telecom, banking, traffic, customs, and courier bodies;
-- prizes, refunds, rewards, jobs, or benefits requiring an advance fee.
+- prizes, refunds, jobs, rewards, or benefits requiring an advance fee.
+
+These signals are warnings, not proof. A familiar logo, sender name, or
+accurate personal detail does not establish authenticity.
+
+## Remaining limitations
 
-Signals are not proof. A familiar logo, sender name, or accurate personal detail
-also does not prove authenticity.
+- The live Space depends on the Modal endpoint and its cold-start behavior.
+- Screenshot quality and dense Roman Urdu text can affect visual recognition.
+- The model can still miss subtle scams or flag legitimate notices.
+- The app does not query government, bank, courier, or telecom databases.
+- A result must always be confirmed through independently located official
+  channels before payment or disclosure of personal information.
 
-## Official references
+## References
 
+- [Build Small Hackathon](https://huggingface.co/build-small-hackathon)
 - [Gradio Server mode](https://www.gradio.app/main/guides/server-mode)
 - [Gradio curl and SSE protocol](https://www.gradio.app/main/guides/querying-gradio-apps-with-curl)
 - [Hugging Face Spaces configuration](https://huggingface.co/docs/hub/spaces-config-reference)
-- [Unsloth Qwen3.6 model](https://huggingface.co/unsloth/Qwen3.6-27B-MTP-GGUF)
+- [Qwen3.6 27B MTP GGUF](https://huggingface.co/unsloth/Qwen3.6-27B-MTP-GGUF)
+- [llama.cpp server](https://github.com/ggml-org/llama.cpp/tree/master/tools/server)
+- [Modal web servers](https://modal.com/docs/guide/webhooks)
 - [FBR fraudulent SMS warning](https://www.fbr.gov.pk/beware-fradulant-sms/152600)
 - [PTA Complaint Management System](https://complaint.pta.gov.pk/RegisterComplaint.aspx)
 - [State Bank of Pakistan](https://www.sbp.org.pk/)
 - [FIA complaint portal](https://complaint.fia.gov.pk/)
 
-Research was reviewed on June 6, 2026.
+Research and deployment results were reviewed on June 7, 2026.

README.md

@@ -1,88 +1,114 @@
----
-title: Pakistan Notice Helper
+---
+title: Pakistan Notice Helper
 emoji: 🛡️
-colorFrom: green
+colorFrom: green
 colorTo: green
-sdk: gradio
-sdk_version: 6.15.1
+sdk: gradio
+sdk_version: 6.15.1
 app_file: app.py
 pinned: false
 license: mit
+tags:
+  - backyard-ai
+  - build-small-hackathon
+  - gradio
+  - llama.cpp
+  - modal
 ---
-
-# Pakistan Notice Helper
-
-Pakistan Notice Helper is a model-powered safety assistant for confusing or
-suspicious Pakistani notices, bills, SMS messages, bank alerts, FBR-style
-messages, challans, and courier/customs messages. It accepts pasted text and
-screenshots, then returns:
-
-- **Risk label:** Looks normal, Verify first, Suspicious, or Likely scam
-- A simple English explanation
-- Red flags found
-- Safe next steps
-- A polite reply draft
-
-The interface is a custom mobile-first frontend served by
-[`gradio.Server`](https://www.gradio.app/main/guides/server-mode). Gradio
-provides queueing, API routes, and Hugging Face Spaces hosting without exposing
-a default Gradio UI.
-
-> **Pakistan Notice Helper does not provide official verification. It checks
-> common scam signals and gives safe next steps. Always verify through official
+
+# Pakistan Notice Helper
+
+Pakistan Notice Helper is a model-powered safety assistant for confusing or
+suspicious Pakistani notices, bills, SMS messages, bank alerts, FBR-style
+messages, challans, and courier/customs messages. It accepts pasted text and
+screenshots, then returns:
+
+- **Risk label:** Looks normal, Verify first, Suspicious, or Likely scam
+- A simple English explanation
+- Red flags found
+- Safe next steps
+- A polite reply draft
+
+The interface is a custom mobile-first frontend served by
+[`gradio.Server`](https://www.gradio.app/main/guides/server-mode). Gradio
+provides queueing, API routes, and Hugging Face Spaces hosting without exposing
+a default Gradio UI.
+
+> **Pakistan Notice Helper does not provide official verification. It checks
+> common scam signals and gives safe next steps. Always verify through official
 > websites or helplines before making payments or sharing personal
 > information.**
 
-## Run locally
-
-Python 3.10 or newer is recommended.
+## Build Small Hackathon
 
-```bash
-python -m pip install -r requirements.txt
-python app.py
-```
+This is a **Backyard AI** project built for the
+[Build Small Hackathon](https://huggingface.co/build-small-hackathon). It
+addresses a common local problem: people receive convincing payment notices,
+bank alerts, courier messages, challans, and government impersonation scams
+but may not know which details are unsafe.
 
-Open `http://127.0.0.1:7860`. Local runs bind to localhost by default. On
-Hugging Face Spaces, the app automatically binds to `0.0.0.0`.
+- **Space:** [build-small-hackathon/pakistan-notice-helper](https://huggingface.co/spaces/build-small-hackathon/pakistan-notice-helper)
+- **Source:** [kingabzpro/pakistan-notice-helper](https://github.com/kingabzpro/pakistan-notice-helper)
+- **Model:** `unsloth/Qwen3.6-27B-MTP-GGUF` (27B parameters)
+- **Inference:** CUDA-enabled `llama.cpp` on a Modal L40S
+- **Interface:** custom mobile-first frontend on `gradio.Server`
+- **Open traces:** [privacy-safe trace dataset](https://huggingface.co/datasets/build-small-hackathon/pakistan-notice-helper-traces)
+- **Build report:** [field notes](FIELD_NOTES.md)
 
-Useful checks:
+The project targets the Backyard AI main track, OpenAI Codex Track, Modal
+Awards, and the Llama Champion, Off-Brand, Sharing is Caring, and Field Notes
+bonus quests.
 
-```bash
-python -m py_compile app.py
-python app.py --self-test
-python app.py --test-endpoint
-```
-
-The last command requires Modal proxy credentials.
-
-## Model configuration
-
-The app uses the standard OpenAI Python SDK as a client for an
-OpenAI-compatible endpoint. It does not call OpenAI cloud APIs by default.
-
-| Variable | Purpose |
-| --- | --- |
-| `MODEL_BASE_URL` | Optional override for the built-in Modal endpoint |
-| `MODEL_NAME` | Optional override for the built-in model ID |
-| `MODEL_API_KEY` | Optional endpoint API key |
-| `MODEL_TIMEOUT_SECONDS` | Optional request timeout; default is 180 seconds |
+## Run locally
+
+Python 3.10 or newer is recommended.
+
+```bash
+python -m pip install -r requirements.txt
+python app.py
+```
+
+Open `http://127.0.0.1:7860`. Local runs bind to localhost by default. On
+Hugging Face Spaces, the app automatically binds to `0.0.0.0`.
+
+Useful checks:
+
+```bash
+python -m py_compile app.py
+python app.py --self-test
+python app.py --test-endpoint
+```
+
+The last command requires Modal proxy credentials.
+
+## Model configuration
+
+The app uses the standard OpenAI Python SDK as a client for an
+OpenAI-compatible endpoint. It does not call OpenAI cloud APIs by default.
+
+| Variable | Purpose |
+| --- | --- |
+| `MODEL_BASE_URL` | Optional override for the built-in Modal endpoint |
+| `MODEL_NAME` | Optional override for the built-in model ID |
+| `MODEL_API_KEY` | Optional endpoint API key |
+| `MODEL_TIMEOUT_SECONDS` | Optional request timeout; default is 180 seconds |
 | `MODAL_PROXY_KEY` | Optional Modal proxy authentication key |
 | `MODAL_PROXY_SECRET` | Optional Modal proxy authentication secret |
 | `HF_TOKEN` | Scoped Hugging Face token used by the background trace uploader |
 | `HF_TRACE_DATASET_REPO` | Trace dataset repo; defaults to `build-small-hackathon/pakistan-notice-helper-traces` |
 | `TRACE_BATCH_SIZE` | Trace records per shard; default is 20 |
 | `TRACE_FLUSH_SECONDS` | Maximum batching delay; default is 60 seconds |
-
-The current defaults are:
-
-```text
-MODEL_BASE_URL=https://abidali899--pakistan-scam-checker-qwen36-mtp-serve.modal.run
-MODEL_NAME=qwen3.6-27b-mtp
-```
-
-See [local model setup](docs/local_model_setup.md) and
-[endpoint testing](docs/model_endpoint_testing.md).
-
+
+The current defaults are:
+
+```text
+MODEL_BASE_URL=https://abidali899--pakistan-scam-checker-qwen36-mtp-serve.modal.run
+MODEL_NAME=qwen3.6-27b-mtp
+```
+
+See [local model setup](docs/local_model_setup.md) and
+[endpoint testing](docs/model_endpoint_testing.md).
+
 ## Model behavior
 
 The app sends text and optional image data to the configured multimodal
@@ -98,26 +124,32 @@ 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
-
-```text
-Custom HTML/CSS/JavaScript frontend
-        |
-        | Gradio POST + SSE protocol
-        v
-Queued gradio.Server backend
+
+## Architecture
+
+```text
+Custom HTML/CSS/JavaScript frontend
+        |
+        | Gradio POST + SSE protocol
+        v
+Queued gradio.Server backend
+        |
+        | OpenAI Python SDK
+        v
+Deployed/local OpenAI-compatible endpoint
         |
-        | OpenAI Python SDK
+        | Modal L40S + CUDA llama-server
         v
-Deployed/local OpenAI-compatible endpoint
+llama.cpp runtime
         |
         v
 unsloth/Qwen3.6-27B-MTP-GGUF
 ```
 
 All frontend assets are local. The app has no runtime CDN, analytics, OCR, MCP,
-or OpenAI Agents SDK. Analysis currently depends on the deployed Modal model.
+or OpenAI Agents SDK. The OpenAI Python package is only an HTTP client for the
+OpenAI-compatible `llama-server` endpoint; requests are not sent to OpenAI.
+Analysis currently depends on the deployed Modal model.
 
 ## Sharing is Caring: Open Traces
 
@@ -156,36 +188,39 @@ python -m traces.scripts.upload_trace_shards --dry-run
 See [the dataset card](traces/dataset_card.md) for the schema, privacy
 policy, provenance, and limitations.
 
-## Hugging Face Spaces
-
-Push this repository to a new Gradio Space. The metadata at the top of this
-README pins Gradio and launches `app.py`. Add `MODAL_PROXY_KEY` and
-`MODAL_PROXY_SECRET` under **Space Settings → Secrets**. The endpoint URL and
-model name are built into the app; `MODEL_BASE_URL` and `MODEL_NAME` remain
-available as overrides for a future local deployment.
-
-## Privacy and limitations
-
-- Submitted text and images are sent to the configured Modal endpoint and are
-  not saved by this app.
+## Deployment
+
+The app is deployed as a Gradio Space under the Build Small Hackathon
+organization. The metadata at the top of this README pins Gradio, identifies
+the Backyard AI track, and launches `app.py`.
+
+Add `MODAL_PROXY_KEY` and `MODAL_PROXY_SECRET` under
+**Space Settings → Secrets**. The endpoint URL and model name are built into
+the app; `MODEL_BASE_URL` and `MODEL_NAME` remain available as overrides for a
+future local deployment.
+
+## Privacy and limitations
+
+- Submitted text and images are sent to the configured Modal endpoint and are
+  not saved by this app.
 - Public traces contain only allow-listed metadata, buckets, booleans, counts,
   and fixed summaries. Tracing can be disabled per request.
-- Do not upload private personal data unless you trust the Modal deployment.
-- No automated result proves that a notice is genuine or fraudulent.
-- Image analysis requires a multimodal endpoint with its vision projector.
-
-## Project structure
-
-```text
-app.py
-requirements.txt
-README.md
-FIELD_NOTES.md
-docs/
-  local_model_setup.md
-  model_endpoint_testing.md
-  research_notes.md
-  model_experiment_notes.md
+- Do not upload private personal data unless you trust the Modal deployment.
+- No automated result proves that a notice is genuine or fraudulent.
+- Image analysis requires a multimodal endpoint with its vision projector.
+
+## Project structure
+
+```text
+app.py
+requirements.txt
+README.md
+FIELD_NOTES.md
+docs/
+  local_model_setup.md
+  model_endpoint_testing.md
+  research_notes.md
+  model_experiment_notes.md
 data/
   example_assessments.json
 traces/
@@ -200,26 +235,26 @@ traces/
     export_pending_traces.py
     upload_trace_shards.py
 static/
-  index.html
-  styles.css
-  app.js
-experiments/
-  modal_qwen36_mtp/
-```
-
+  index.html
+  styles.css
+  app.js
+experiments/
+  modal_qwen36_mtp/
+```
+
 The six bundled examples have cached Modal assessments and deterministic seed
 traces. Runtime trace shards are kept out of Git and uploaded separately.
-
-## Official reporting channels
-
-Use contact details that you navigate to independently:
-
-- [PTA Complaint Management System](https://complaint.pta.gov.pk/)
-- [FIA Complaint Portal](https://complaint.fia.gov.pk/)
-- [State Bank of Pakistan](https://www.sbp.org.pk/)
-- [Federal Board of Revenue](https://www.fbr.gov.pk/)
-- The official bank, courier, utility, traffic authority, or government website
-  relevant to the notice
-
-Never call a number or open a link merely because it appears inside the message
-being checked.
+
+## Official reporting channels
+
+Use contact details that you navigate to independently:
+
+- [PTA Complaint Management System](https://complaint.pta.gov.pk/)
+- [FIA Complaint Portal](https://complaint.fia.gov.pk/)
+- [State Bank of Pakistan](https://www.sbp.org.pk/)
+- [Federal Board of Revenue](https://www.fbr.gov.pk/)
+- The official bank, courier, utility, traffic authority, or government website
+  relevant to the notice
+
+Never call a number or open a link merely because it appears inside the message
+being checked.

experiments/modal_qwen36_mtp/README.md

@@ -6,10 +6,10 @@ with CUDA-enabled `llama-server` on one Modal L40S. It exposes llama.cpp's
 OpenAI-compatible `/v1/chat/completions` route without calling OpenAI or any
 cloud LLM API.
 
-This deployment is only an infrastructure and model-compatibility experiment.
-The hackathon application remains local-first and offline-capable. A Hugging
-Face Space may be offered as a fallback, but Modal is not the intended primary
-application backend.
+This deployment is the hackathon application's primary inference backend. The
+Hugging Face Space sends text and screenshots to this proxy-authenticated
+endpoint, while the same application code can target a local `llama-server`
+through environment-variable overrides.
 
 ## Configuration