Abid Ali Awan Codex commited on
Commit ·
1663316
1
Parent(s): cde909f
Refine hackathon documentation
Browse filesShorten the README, clarify award evidence, expand the Urdu feature notes, and align the final submission checklist with current hackathon requirements.
Co-Authored-By: Codex <noreply@openai.com>
- FIELD_NOTES.md +72 -6
- README.md +80 -219
- SUBMISSION_TODO.md +40 -5
FIELD_NOTES.md
CHANGED
|
@@ -42,7 +42,9 @@ stack and API behavior remain under my control.
|
|
| 42 |
|
| 43 |
## Product decisions
|
| 44 |
|
| 45 |
-
-
|
|
|
|
|
|
|
| 46 |
- Support screenshots because many suspicious messages arrive through SMS,
|
| 47 |
WhatsApp, and social media.
|
| 48 |
- Treat every URL, phone number, and contact instruction in the submitted
|
|
@@ -54,6 +56,32 @@ stack and API behavior remain under my control.
|
|
| 54 |
- Show a reply draft only for uncertain cases where clarification may be safe.
|
| 55 |
Likely scams do not encourage further engagement.
|
| 56 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 57 |
## Small-model stack
|
| 58 |
|
| 59 |
The primary model is `unsloth/Qwen3.5-4B-MTP-GGUF`, using the
|
|
@@ -69,13 +97,19 @@ Key measured results:
|
|
| 69 |
|
| 70 |
| Measurement | Result |
|
| 71 |
| --- | --- |
|
| 72 |
-
|
|
| 73 |
-
|
|
|
|
|
|
|
|
| 74 |
| High-risk scam cases | All passed |
|
| 75 |
| Screenshot cases | Both passed |
|
| 76 |
| MTP draft acceptance | 222 of 440 tokens (50.5%) |
|
| 77 |
| MTP draft limit | `n_max=2` |
|
| 78 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 79 |
The full setup and measurements are documented in
|
| 80 |
[the model experiment notes](docs/model_experiment_notes.md).
|
| 81 |
|
|
@@ -103,6 +137,7 @@ JavaScript frontend calls the Gradio POST and SSE protocol:
|
|
| 103 |
```text
|
| 104 |
Browser
|
| 105 |
-> custom mobile-first frontend
|
|
|
|
| 106 |
-> queued gradio.Server endpoint
|
| 107 |
-> OpenAI-compatible client
|
| 108 |
-> Modal proxy-authenticated web server
|
|
@@ -117,10 +152,16 @@ version and names `app.py` as its entry point.
|
|
| 117 |
## What failed and changed
|
| 118 |
|
| 119 |
- Thinking mode initially consumed the 500-token output budget without
|
| 120 |
-
returning final JSON.
|
| 121 |
-
|
| 122 |
- A dense Roman Urdu screenshot reached the original completion limit. Image
|
| 123 |
requests now receive a larger token budget.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 124 |
- One model response suggested an unverified official-looking domain. The
|
| 125 |
system prompt now forbids invented URLs, phone numbers, organizations, and
|
| 126 |
facts.
|
|
@@ -176,6 +217,8 @@ accurate personal detail does not establish authenticity.
|
|
| 176 |
|
| 177 |
- The live Space depends on the Modal endpoint and its cold-start behavior.
|
| 178 |
- Screenshot quality and dense Roman Urdu text can affect visual recognition.
|
|
|
|
|
|
|
| 179 |
- The model can still miss subtle scams or flag legitimate notices.
|
| 180 |
- The app does not query government, bank, courier, or telecom databases.
|
| 181 |
- A result must always be confirmed through independently located official
|
|
@@ -196,6 +239,28 @@ distinction between evidence and inference. The current project stops at
|
|
| 196 |
triage because adding web access without those controls could make a safety
|
| 197 |
tool less safe.
|
| 198 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 199 |
## References
|
| 200 |
|
| 201 |
- [Build Small Hackathon](https://huggingface.co/build-small-hackathon)
|
|
@@ -210,4 +275,5 @@ tool less safe.
|
|
| 210 |
- [State Bank of Pakistan](https://www.sbp.org.pk/)
|
| 211 |
- [FIA complaint portal](https://complaint.fia.gov.pk/)
|
| 212 |
|
| 213 |
-
|
|
|
|
|
|
| 42 |
|
| 43 |
## Product decisions
|
| 44 |
|
| 45 |
+
- Offer both English and Urdu instead of assuming every user is comfortable
|
| 46 |
+
interpreting safety guidance in English.
|
| 47 |
+
- Use simple, direct wording rather than legal or security terminology.
|
| 48 |
- Support screenshots because many suspicious messages arrive through SMS,
|
| 49 |
WhatsApp, and social media.
|
| 50 |
- Treat every URL, phone number, and contact instruction in the submitted
|
|
|
|
| 56 |
- Show a reply draft only for uncertain cases where clarification may be safe.
|
| 57 |
Likely scams do not encourage further engagement.
|
| 58 |
|
| 59 |
+
## English and Urdu experience
|
| 60 |
+
|
| 61 |
+
I added an English/Urdu switch to make the app more useful for people who can
|
| 62 |
+
read a suspicious message but would understand the safety advice more clearly
|
| 63 |
+
in Urdu. The selected language is remembered in the browser, so returning users
|
| 64 |
+
do not have to switch it again.
|
| 65 |
+
|
| 66 |
+
Urdu mode is more than a translated navigation layer. It changes the page to a
|
| 67 |
+
right-to-left layout and translates headings, form labels, validation errors,
|
| 68 |
+
status messages, risk labels, examples, disclaimers, and result-card controls.
|
| 69 |
+
Live assessments also ask the model to return the explanation, red flags, safe
|
| 70 |
+
next steps, and optional reply draft in clear Urdu script. English cached
|
| 71 |
+
examples remain cached; selecting one in Urdu mode sends it through the live
|
| 72 |
+
model so the result language matches the interface.
|
| 73 |
+
|
| 74 |
+
The first Urdu layout exposed details that were easy to miss in English:
|
| 75 |
+
headings needed different line heights, mixed Urdu and Latin model names could
|
| 76 |
+
reorder unexpectedly, and mobile controls required more vertical space. I
|
| 77 |
+
tested the interface at desktop and 390-pixel mobile widths, adjusted the RTL
|
| 78 |
+
spacing, and rewrote literal translations into shorter, more natural Urdu.
|
| 79 |
+
|
| 80 |
+
I also tested a bundled Nastaliq webfont. It made the interface feel less
|
| 81 |
+
consistent and reduced readability at the sizes used by the app, so I removed
|
| 82 |
+
it and returned to the earlier system Arabic font stack. This kept the improved
|
| 83 |
+
Urdu copy and RTL layout without forcing a decorative typeface on every device.
|
| 84 |
+
|
| 85 |
## Small-model stack
|
| 86 |
|
| 87 |
The primary model is `unsloth/Qwen3.5-4B-MTP-GGUF`, using the
|
|
|
|
| 97 |
|
| 98 |
| Measurement | Result |
|
| 99 |
| --- | --- |
|
| 100 |
+
| Initial evaluation strict passes | 9 of 10 |
|
| 101 |
+
| Initial evaluation average score | 89.5/100 |
|
| 102 |
+
| Final regression evaluation | 10 of 10 |
|
| 103 |
+
| Final regression average score | 100/100 |
|
| 104 |
| High-risk scam cases | All passed |
|
| 105 |
| Screenshot cases | Both passed |
|
| 106 |
| MTP draft acceptance | 222 of 440 tokens (50.5%) |
|
| 107 |
| MTP draft limit | `n_max=2` |
|
| 108 |
|
| 109 |
+
The final score comes from the same small ten-case suite after prompt and
|
| 110 |
+
output-contract fixes. It is useful as a regression check, but it is not a
|
| 111 |
+
real-world accuracy estimate.
|
| 112 |
+
|
| 113 |
The full setup and measurements are documented in
|
| 114 |
[the model experiment notes](docs/model_experiment_notes.md).
|
| 115 |
|
|
|
|
| 137 |
```text
|
| 138 |
Browser
|
| 139 |
-> custom mobile-first frontend
|
| 140 |
+
-> English or Urdu interface and response-language request
|
| 141 |
-> queued gradio.Server endpoint
|
| 142 |
-> OpenAI-compatible client
|
| 143 |
-> Modal proxy-authenticated web server
|
|
|
|
| 152 |
## What failed and changed
|
| 153 |
|
| 154 |
- Thinking mode initially consumed the 500-token output budget without
|
| 155 |
+
returning final JSON. The production app disables thinking so the bounded
|
| 156 |
+
completion budget is used for the final structured response.
|
| 157 |
- A dense Roman Urdu screenshot reached the original completion limit. Image
|
| 158 |
requests now receive a larger token budget.
|
| 159 |
+
- The first Urdu interface used direct translations and generic spacing. It
|
| 160 |
+
was revised with more natural wording, RTL-specific typography, responsive
|
| 161 |
+
spacing, and cleaner handling of mixed Urdu and Latin text.
|
| 162 |
+
- A bundled Nastaliq font looked worse in the product UI than the original
|
| 163 |
+
system font stack. The font was removed while retaining the improved Urdu
|
| 164 |
+
layout and copy.
|
| 165 |
- One model response suggested an unverified official-looking domain. The
|
| 166 |
system prompt now forbids invented URLs, phone numbers, organizations, and
|
| 167 |
facts.
|
|
|
|
| 217 |
|
| 218 |
- The live Space depends on the Modal endpoint and its cold-start behavior.
|
| 219 |
- Screenshot quality and dense Roman Urdu text can affect visual recognition.
|
| 220 |
+
- Urdu output quality still depends on the model, and mixed technical terms
|
| 221 |
+
may occasionally need English wording for clarity.
|
| 222 |
- The model can still miss subtle scams or flag legitimate notices.
|
| 223 |
- The app does not query government, bank, courier, or telecom databases.
|
| 224 |
- A result must always be confirmed through independently located official
|
|
|
|
| 239 |
triage because adding web access without those controls could make a safety
|
| 240 |
tool less safe.
|
| 241 |
|
| 242 |
+
## Hackathon submission status
|
| 243 |
+
|
| 244 |
+
The project meets the core technical constraints: a model at or below 32B,
|
| 245 |
+
Gradio hosting as a Space under the hackathon organization, and a public app.
|
| 246 |
+
It is intended for Backyard AI because the problem is specific and local, the
|
| 247 |
+
4B model is an honest fit for the task, and the interface is designed for the
|
| 248 |
+
people receiving these messages. The final submission form is still pending.
|
| 249 |
+
|
| 250 |
+
The strongest additional award targets are Modal Awards, Tiny Titan, Off-Brand
|
| 251 |
+
Award, and the OpenAI Track. The implemented bonus-quest evidence clearly
|
| 252 |
+
covers Llama Champion, Off-Brand, and Field Notes. The public trace dataset is
|
| 253 |
+
a Sharing is Caring candidate, but the official wording says “agent trace”
|
| 254 |
+
while this project publishes deterministic request traces rather than an
|
| 255 |
+
autonomous-agent trajectory; that eligibility should be confirmed with the
|
| 256 |
+
organizers. The project does not claim Off the Grid, Well-Tuned, the Nemotron
|
| 257 |
+
Quest, or Best Agent.
|
| 258 |
+
|
| 259 |
+
Before the June 15, 2026 deadline, the remaining submission work is to record
|
| 260 |
+
target-user use and any resulting change, publish the short demo video and
|
| 261 |
+
social post, verify that GitHub mirrors the final Space source, and submit the
|
| 262 |
+
three required links. The operational checklist is in `SUBMISSION_TODO.md`.
|
| 263 |
+
|
| 264 |
## References
|
| 265 |
|
| 266 |
- [Build Small Hackathon](https://huggingface.co/build-small-hackathon)
|
|
|
|
| 275 |
- [State Bank of Pakistan](https://www.sbp.org.pk/)
|
| 276 |
- [FIA complaint portal](https://complaint.fia.gov.pk/)
|
| 277 |
|
| 278 |
+
Hackathon requirements, public links, and deployment claims were reviewed on
|
| 279 |
+
June 8, 2026.
|
README.md
CHANGED
|
@@ -21,272 +21,133 @@ tags:
|
|
| 21 |
- scam-detection
|
| 22 |
- online-safety
|
| 23 |
- pakistan
|
|
|
|
|
|
|
| 24 |
- roman-urdu
|
| 25 |
- openai-compatible
|
| 26 |
-
short_description: Check notices
|
| 27 |
---
|
| 28 |
|
| 29 |
# Pakistan Notice Helper
|
| 30 |
|
| 31 |
-
Pakistan Notice Helper is a
|
| 32 |
-
suspicious Pakistani notices, bills, SMS messages, bank alerts,
|
| 33 |
-
|
| 34 |
-
screenshots, then returns:
|
| 35 |
|
| 36 |
-
-
|
| 37 |
-
-
|
| 38 |
-
-
|
| 39 |
-
- Safe next steps
|
| 40 |
-
- A polite reply draft
|
| 41 |
|
| 42 |
-
The interface
|
| 43 |
-
|
| 44 |
-
|
| 45 |
-
a default Gradio UI.
|
| 46 |
|
| 47 |
-
>
|
| 48 |
-
>
|
| 49 |
-
>
|
| 50 |
-
> information.**
|
| 51 |
|
| 52 |
-
|
| 53 |
-
|
| 54 |
-
This is a **Backyard AI** project built for the
|
| 55 |
-
[Build Small Hackathon](https://huggingface.co/build-small-hackathon). It
|
| 56 |
-
addresses a common local problem: people receive convincing payment notices,
|
| 57 |
-
bank alerts, courier messages, challans, and government impersonation scams
|
| 58 |
-
but may not know which details are unsafe.
|
| 59 |
-
|
| 60 |
-
- **Space:** [build-small-hackathon/pakistan-notice-helper](https://huggingface.co/spaces/build-small-hackathon/pakistan-notice-helper)
|
| 61 |
-
- **Source:** [kingabzpro/pakistan-notice-helper](https://github.com/kingabzpro/pakistan-notice-helper)
|
| 62 |
-
- **Model:** `unsloth/Qwen3.5-4B-MTP-GGUF` (`Qwen3.5-4B-Q8_0.gguf`)
|
| 63 |
-
- **Inference:** CUDA-enabled `llama.cpp` on a Modal L4
|
| 64 |
-
- **Interface:** custom mobile-first frontend on `gradio.Server`
|
| 65 |
-
- **Open traces:** [privacy-safe trace dataset](https://huggingface.co/datasets/build-small-hackathon/pakistan-notice-helper-traces)
|
| 66 |
-
- **Build report:** [field notes](FIELD_NOTES.md)
|
| 67 |
-
|
| 68 |
-
The project targets the Backyard AI main track, OpenAI Codex Track, Modal
|
| 69 |
-
Awards, and the Llama Champion, Off-Brand, Sharing is Caring, and Field Notes
|
| 70 |
-
bonus quests.
|
| 71 |
-
|
| 72 |
-
### Why it qualifies
|
| 73 |
-
|
| 74 |
-
| Requirement or category | Project evidence |
|
| 75 |
| --- | --- |
|
| 76 |
-
|
|
| 77 |
-
|
|
| 78 |
-
|
|
| 79 |
-
|
|
| 80 |
-
| **Backyard AI: polished app** | Provides a custom responsive interface, bundled examples, clear failures, safety disclaimers, and structured results. |
|
| 81 |
-
| **Modal Awards** | The live model endpoint runs on a Modal L4 with persistent model storage and proxy authentication. |
|
| 82 |
-
| **OpenAI Codex Track** | The public GitHub repository contains Codex-attributed commits and is linked from this Space. |
|
| 83 |
-
| **Llama Champion** | Model inference runs through a pinned CUDA-enabled `llama.cpp` build. |
|
| 84 |
-
| **Off-Brand** | Uses a custom HTML, CSS, and JavaScript frontend instead of the default Gradio interface. |
|
| 85 |
-
| **Sharing is Caring** | Publishes opt-out, privacy-safe traces as a public Hugging Face dataset. |
|
| 86 |
-
| **Field Notes** | Documents design decisions, measured performance, failed approaches, privacy tradeoffs, and limitations. |
|
| 87 |
-
|
| 88 |
-
The final submission must also include a short demo video, a social-media post,
|
| 89 |
-
and evidence that a target user tried the app. These are submission and
|
| 90 |
-
Backyard AI judging requirements, not features that repository metadata can
|
| 91 |
-
prove.
|
| 92 |
-
|
| 93 |
-
## Run locally
|
| 94 |
-
|
| 95 |
-
Python 3.10 or newer is recommended.
|
| 96 |
-
|
| 97 |
-
```bash
|
| 98 |
-
python -m pip install -r requirements.txt
|
| 99 |
-
python app.py
|
| 100 |
-
```
|
| 101 |
-
|
| 102 |
-
Open `http://127.0.0.1:7860`. Local runs bind to localhost by default. On
|
| 103 |
-
Hugging Face Spaces, the app automatically binds to `0.0.0.0`.
|
| 104 |
-
|
| 105 |
-
Useful checks:
|
| 106 |
-
|
| 107 |
-
```bash
|
| 108 |
-
python -m py_compile app.py
|
| 109 |
-
python app.py --self-test
|
| 110 |
-
python app.py --test-endpoint
|
| 111 |
-
python scripts/generate_example_cache.py
|
| 112 |
-
```
|
| 113 |
-
|
| 114 |
-
The last command requires Modal proxy credentials.
|
| 115 |
|
| 116 |
-
##
|
| 117 |
|
| 118 |
-
|
| 119 |
-
|
|
|
|
| 120 |
|
| 121 |
-
|
|
| 122 |
| --- | --- |
|
| 123 |
-
|
|
| 124 |
-
|
|
| 125 |
-
|
|
| 126 |
-
|
|
| 127 |
-
|
|
| 128 |
-
| `
|
| 129 |
-
|
|
| 130 |
-
|
|
| 131 |
-
| `TRACE_BATCH_SIZE` | Trace records per shard; default is 20 |
|
| 132 |
-
| `TRACE_FLUSH_SECONDS` | Maximum batching delay; default is 60 seconds |
|
| 133 |
-
|
| 134 |
-
The current defaults are:
|
| 135 |
-
|
| 136 |
-
```text
|
| 137 |
-
MODEL_BASE_URL=https://abidali899--pakistan-scam-checker-qwen35-4b-q8-serve.modal.run
|
| 138 |
-
MODEL_NAME=qwen3.5-4b-q8
|
| 139 |
-
```
|
| 140 |
-
|
| 141 |
-
See [local model setup](docs/local_model_setup.md) and
|
| 142 |
-
[endpoint testing](docs/model_endpoint_testing.md).
|
| 143 |
-
|
| 144 |
-
## Model behavior
|
| 145 |
-
|
| 146 |
-
The app sends text and optional image data to the configured multimodal
|
| 147 |
-
OpenAI-compatible endpoint and validates its structured response.
|
| 148 |
-
|
| 149 |
-
The six built-in text and screenshot examples use assessments generated by the
|
| 150 |
-
deployed Qwen3.5 model and stored in `data/example_assessments.json`. Trying
|
| 151 |
-
those examples does not call or wake the Modal endpoint, and the UI labels them
|
| 152 |
-
as **Cached model result**. Editing an example or uploading a different image
|
| 153 |
-
switches back to normal model analysis.
|
| 154 |
-
|
| 155 |
-
There is no rule-based or sample fallback for user-submitted input. If
|
| 156 |
-
credentials are missing, the endpoint is unavailable, or the model returns
|
| 157 |
-
invalid output, the app displays a clear error and does not manufacture an
|
| 158 |
-
assessment.
|
| 159 |
|
| 160 |
## Architecture
|
| 161 |
|
| 162 |
```text
|
| 163 |
-
|
| 164 |
|
|
| 165 |
-
| Gradio POST + SSE protocol
|
| 166 |
v
|
| 167 |
-
|
| 168 |
|
|
| 169 |
-
| OpenAI Python SDK
|
| 170 |
v
|
| 171 |
-
|
| 172 |
|
|
| 173 |
-
| Modal L4 + CUDA llama-server
|
| 174 |
v
|
| 175 |
-
llama.cpp
|
| 176 |
|
|
| 177 |
v
|
| 178 |
-
|
|
|
|
|
|
|
|
|
|
| 179 |
```
|
| 180 |
|
| 181 |
-
|
| 182 |
-
|
| 183 |
-
|
| 184 |
-
|
| 185 |
-
|
| 186 |
-
## Sharing is Caring: Open Traces
|
| 187 |
|
| 188 |
-
|
| 189 |
-
[`build-small-hackathon/pakistan-notice-helper-traces`](https://huggingface.co/datasets/build-small-hackathon/pakistan-notice-helper-traces).
|
| 190 |
-
The checkbox is visible and enabled by default on each request, and users can
|
| 191 |
-
turn it off before submitting.
|
| 192 |
|
| 193 |
-
|
| 194 |
-
|
| 195 |
-
|
| 196 |
-
|
| 197 |
-
|
| 198 |
-
All trace columns are flat scalar values; no dataset cell contains a nested
|
| 199 |
-
dictionary. Detected signals are combined into the readable `scam_tactics`
|
| 200 |
-
column.
|
| 201 |
-
It never stores raw messages, screenshots, links, detected identifiers, model
|
| 202 |
-
explanations, reply text, exceptions, or credentials.
|
| 203 |
|
| 204 |
-
|
| 205 |
-
|
| 206 |
-
|
| 207 |
|
| 208 |
-
|
| 209 |
|
| 210 |
```bash
|
| 211 |
-
|
| 212 |
-
|
| 213 |
-
python
|
| 214 |
-
python -m traces.scripts.create_trace_dataset
|
| 215 |
-
python -m traces.scripts.create_trace_dataset --replace-data
|
| 216 |
-
python -m traces.scripts.export_pending_traces --dry-run
|
| 217 |
-
python -m traces.scripts.upload_trace_shards --dry-run
|
| 218 |
```
|
| 219 |
|
| 220 |
-
|
| 221 |
-
|
| 222 |
-
|
| 223 |
-
## Deployment
|
| 224 |
|
| 225 |
-
|
| 226 |
-
|
| 227 |
-
the Backyard AI track, and launches `app.py`.
|
| 228 |
|
| 229 |
-
|
| 230 |
-
**Space Settings → Secrets**. The endpoint URL and model name are built into
|
| 231 |
-
the app; `MODEL_BASE_URL` and `MODEL_NAME` remain available as overrides for a
|
| 232 |
-
future local deployment.
|
| 233 |
|
| 234 |
-
|
|
|
|
|
|
|
| 235 |
|
| 236 |
-
|
| 237 |
-
|
| 238 |
-
|
| 239 |
-
and fixed summaries. Tracing can be disabled per request.
|
| 240 |
-
- Do not upload private personal data unless you trust the Modal deployment.
|
| 241 |
-
- No automated result proves that a notice is genuine or fraudulent.
|
| 242 |
-
- Image analysis requires a multimodal endpoint with its vision projector.
|
| 243 |
-
|
| 244 |
-
## Project structure
|
| 245 |
-
|
| 246 |
-
```text
|
| 247 |
-
app.py
|
| 248 |
-
requirements.txt
|
| 249 |
-
README.md
|
| 250 |
-
FIELD_NOTES.md
|
| 251 |
-
docs/
|
| 252 |
-
local_model_setup.md
|
| 253 |
-
model_endpoint_testing.md
|
| 254 |
-
research_notes.md
|
| 255 |
-
model_experiment_notes.md
|
| 256 |
-
data/
|
| 257 |
-
example_assessments.json
|
| 258 |
-
traces/
|
| 259 |
-
runtime.py
|
| 260 |
-
dataset_card.md
|
| 261 |
-
data/
|
| 262 |
-
trace_samples.jsonl
|
| 263 |
-
scripts/
|
| 264 |
-
create_trace_dataset.py
|
| 265 |
-
seed_trace_dataset.py
|
| 266 |
-
validate_traces.py
|
| 267 |
-
export_pending_traces.py
|
| 268 |
-
upload_trace_shards.py
|
| 269 |
-
static/
|
| 270 |
-
index.html
|
| 271 |
-
styles.css
|
| 272 |
-
app.js
|
| 273 |
-
experiments/
|
| 274 |
-
modal_qwen35_4b_q8/
|
| 275 |
-
```
|
| 276 |
|
| 277 |
-
|
| 278 |
-
traces. Runtime trace shards are kept out of Git and uploaded separately.
|
| 279 |
|
| 280 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 281 |
|
| 282 |
-
|
| 283 |
|
| 284 |
- [PTA Complaint Management System](https://complaint.pta.gov.pk/)
|
|
|
|
| 285 |
- [FIA Complaint Portal](https://complaint.fia.gov.pk/)
|
| 286 |
- [State Bank of Pakistan](https://www.sbp.org.pk/)
|
| 287 |
- [Federal Board of Revenue](https://www.fbr.gov.pk/)
|
| 288 |
-
- The official bank, courier, utility, traffic authority, or government website
|
| 289 |
-
relevant to the notice
|
| 290 |
|
| 291 |
-
Never
|
| 292 |
-
being checked.
|
|
|
|
| 21 |
- scam-detection
|
| 22 |
- online-safety
|
| 23 |
- pakistan
|
| 24 |
+
- urdu
|
| 25 |
+
- bilingual
|
| 26 |
- roman-urdu
|
| 27 |
- openai-compatible
|
| 28 |
+
short_description: Check Pakistani notices for scam risks in English or Urdu.
|
| 29 |
---
|
| 30 |
|
| 31 |
# Pakistan Notice Helper
|
| 32 |
|
| 33 |
+
Pakistan Notice Helper is a bilingual safety assistant for confusing or
|
| 34 |
+
suspicious Pakistani notices, bills, SMS messages, bank alerts, challans, and
|
| 35 |
+
courier or customs messages. Paste text or upload a screenshot to receive:
|
|
|
|
| 36 |
|
| 37 |
+
- a risk label: **Looks normal**, **Verify first**, **Suspicious**, or **Likely scam**
|
| 38 |
+
- a simple English or Urdu explanation
|
| 39 |
+
- red flags, safe next steps, and a polite reply draft
|
|
|
|
|
|
|
| 40 |
|
| 41 |
+
The mobile-first interface has a persistent English/Urdu switch. Urdu mode uses
|
| 42 |
+
a right-to-left layout and asks the live model to answer in Urdu. Roman Urdu and
|
| 43 |
+
mixed-language inputs are also supported.
|
|
|
|
| 44 |
|
| 45 |
+
> Pakistan Notice Helper checks common scam signals but does not provide
|
| 46 |
+
> official verification, legal advice, or financial advice. Verify through an
|
| 47 |
+
> official website or helpline before paying or sharing personal information.
|
|
|
|
| 48 |
|
| 49 |
+
| Resource | Link |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 50 |
| --- | --- |
|
| 51 |
+
| Live app | [Hugging Face Space](https://huggingface.co/spaces/build-small-hackathon/pakistan-notice-helper) |
|
| 52 |
+
| Source | [GitHub repository](https://github.com/kingabzpro/pakistan-notice-helper) |
|
| 53 |
+
| Open traces | [Privacy-safe trace dataset](https://huggingface.co/datasets/build-small-hackathon/pakistan-notice-helper-traces) |
|
| 54 |
+
| Build report | [`FIELD_NOTES.md`](FIELD_NOTES.md) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 55 |
|
| 56 |
+
## Hackathon Fit
|
| 57 |
|
| 58 |
+
This is an intended **Backyard AI** submission for the
|
| 59 |
+
[Build Small. Play Big. Hackathon](https://huggingface.co/build-small-hackathon).
|
| 60 |
+
It applies a small model to a practical regional safety problem.
|
| 61 |
|
| 62 |
+
| Area | Project evidence |
|
| 63 |
| --- | --- |
|
| 64 |
+
| Core constraints | Public Gradio Space using Qwen3.5-4B, below the 7B limit |
|
| 65 |
+
| Backyard AI | Notice and scam triage designed for Pakistani users |
|
| 66 |
+
| Modal | Qwen3.5-4B is hosted on a Modal L4 GPU endpoint |
|
| 67 |
+
| Tiny Titan | The 4B Q8 model passed the final 10-case internal regression suite |
|
| 68 |
+
| Llama Champion | Qwen3.5-4B runs through a CUDA-enabled `llama.cpp` server using its OpenAI-compatible API |
|
| 69 |
+
| Off-Brand | Custom mobile-first HTML, CSS, and JavaScript interface served through `gradio.Server` instead of the default Gradio UI |
|
| 70 |
+
| Bonus quests | Runtime notes for Local Llama, privacy-safe traces, and published field notes |
|
| 71 |
+
| Pending | Track form, user test, demo video, public announcement, and final repository sync |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 72 |
|
| 73 |
## Architecture
|
| 74 |
|
| 75 |
```text
|
| 76 |
+
Text or screenshot
|
| 77 |
|
|
|
|
|
| 78 |
v
|
| 79 |
+
Custom bilingual frontend on gradio.Server
|
| 80 |
|
|
|
|
|
| 81 |
v
|
| 82 |
+
Image preprocessing and structured safety prompt
|
| 83 |
|
|
|
|
|
| 84 |
v
|
| 85 |
+
Qwen3.5-4B Q8_0 MTP on llama.cpp
|
| 86 |
|
|
| 87 |
v
|
| 88 |
+
Modal L4 endpoint
|
| 89 |
+
|
|
| 90 |
+
v
|
| 91 |
+
Risk label, explanation, red flags, and safe next steps
|
| 92 |
```
|
| 93 |
|
| 94 |
+
Gradio provides queueing, API routes, and Hugging Face Spaces hosting without
|
| 95 |
+
exposing a default Gradio UI. Live analyses always use the configured model
|
| 96 |
+
endpoint. There is no heuristic fallback, and endpoint failures are shown
|
| 97 |
+
explicitly. Bundled English examples are cached; Urdu analyses are generated
|
| 98 |
+
live.
|
|
|
|
| 99 |
|
| 100 |
+
## Model and Evaluation
|
|
|
|
|
|
|
|
|
|
| 101 |
|
| 102 |
+
- **Model:** `unsloth/Qwen3.5-4B-MTP-GGUF` using `Qwen3.5-4B-Q8_0.gguf`
|
| 103 |
+
- **Runtime:** [`llama.cpp` OpenAI-compatible server](https://github.com/ggml-org/llama.cpp/tree/master/examples/server)
|
| 104 |
+
- **Client:** [OpenAI Python SDK with a custom `base_url`](https://github.com/openai/openai-python#configuring-the-http-client)
|
| 105 |
+
- **Hosting:** Modal L4 GPU
|
| 106 |
+
- **Internal evaluation:** 10/10 final regression cases, up from 9/10 initially
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 107 |
|
| 108 |
+
The focused test set covers banking notices, authority impersonation, prize
|
| 109 |
+
scams, service messages, Urdu text, and screenshots. It is not a claim of
|
| 110 |
+
general fraud-detection accuracy.
|
| 111 |
|
| 112 |
+
## Run Locally
|
| 113 |
|
| 114 |
```bash
|
| 115 |
+
pip install -r requirements.txt
|
| 116 |
+
copy .env.example .env
|
| 117 |
+
python app.py
|
|
|
|
|
|
|
|
|
|
|
|
|
| 118 |
```
|
| 119 |
|
| 120 |
+
On macOS or Linux, use `cp .env.example .env`. Add `MODAL_PROXY_KEY` and
|
| 121 |
+
`MODAL_PROXY_SECRET` to `.env` before starting live inference. Model URL, name,
|
| 122 |
+
token limit, timeout, and retry settings are optional.
|
|
|
|
| 123 |
|
| 124 |
+
See [`docs/local_model_setup.md`](docs/local_model_setup.md) for full setup and deployment
|
| 125 |
+
instructions.
|
|
|
|
| 126 |
|
| 127 |
+
## Privacy-Safe Traces
|
|
|
|
|
|
|
|
|
|
| 128 |
|
| 129 |
+
Users can explicitly consent to sharing a minimized workflow trace. Traces may
|
| 130 |
+
include language, input type, risk label, latency, response length, and a coarse
|
| 131 |
+
error category.
|
| 132 |
|
| 133 |
+
They do **not** include raw notice text, OCR text, screenshots, names, phone
|
| 134 |
+
numbers, credentials, or full model responses. See
|
| 135 |
+
the trace [`dataset card`](traces/dataset_card.md).
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 136 |
|
| 137 |
+
## Privacy and Limitations
|
|
|
|
| 138 |
|
| 139 |
+
- Inputs are processed in memory and are not written to disk by the app.
|
| 140 |
+
- Model requests are sent to the configured Modal endpoint.
|
| 141 |
+
- Redact CNIC numbers, account details, OTPs, PINs, and other sensitive data.
|
| 142 |
+
- Poor images, mixed scripts, abbreviations, or missing context can reduce reliability.
|
| 143 |
+
- Verify using contact details obtained independently from the message.
|
| 144 |
|
| 145 |
+
## Official Verification
|
| 146 |
|
| 147 |
- [PTA Complaint Management System](https://complaint.pta.gov.pk/)
|
| 148 |
+
- [PTA Numbering and Short Codes](https://www.pta.gov.pk/category/numbering-and-short-codes)
|
| 149 |
- [FIA Complaint Portal](https://complaint.fia.gov.pk/)
|
| 150 |
- [State Bank of Pakistan](https://www.sbp.org.pk/)
|
| 151 |
- [Federal Board of Revenue](https://www.fbr.gov.pk/)
|
|
|
|
|
|
|
| 152 |
|
| 153 |
+
Never rely on a verification link contained inside a suspicious message.
|
|
|
SUBMISSION_TODO.md
CHANGED
|
@@ -2,17 +2,52 @@
|
|
| 2 |
|
| 3 |
Deadline: **June 15, 2026**
|
| 4 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5 |
- [ ] Ask at least one target user to try the Space.
|
| 6 |
- [ ] Save a short, anonymized quote or note about their experience.
|
| 7 |
- [ ] Add the user feedback and any resulting improvement to `FIELD_NOTES.md`.
|
| 8 |
-
|
| 9 |
-
|
|
|
|
| 10 |
- [ ] Add the demo and social-post links to `README.md`.
|
|
|
|
|
|
|
| 11 |
- [ ] Test all public links and confirm the Space is running.
|
| 12 |
-
- [ ]
|
| 13 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 14 |
|
| 15 |
-
|
| 16 |
|
| 17 |
## Links
|
| 18 |
|
|
|
|
| 2 |
|
| 3 |
Deadline: **June 15, 2026**
|
| 4 |
|
| 5 |
+
## Required submission package
|
| 6 |
+
|
| 7 |
+
- [x] Host the Gradio app as a Space under the hackathon organization.
|
| 8 |
+
- [ ] Record and publish a short demo video.
|
| 9 |
+
- [ ] Publish a social-media post.
|
| 10 |
+
- [ ] Submit the Space, demo video, and social-post links by June 15, 2026.
|
| 11 |
+
- [ ] Save the submission confirmation.
|
| 12 |
+
|
| 13 |
+
## Backyard AI evidence
|
| 14 |
+
|
| 15 |
- [ ] Ask at least one target user to try the Space.
|
| 16 |
- [ ] Save a short, anonymized quote or note about their experience.
|
| 17 |
- [ ] Add the user feedback and any resulting improvement to `FIELD_NOTES.md`.
|
| 18 |
+
|
| 19 |
+
## Final documentation and verification
|
| 20 |
+
|
| 21 |
- [ ] Add the demo and social-post links to `README.md`.
|
| 22 |
+
- [ ] Confirm the public GitHub repository contains the final Space source and
|
| 23 |
+
Codex-attributed commits.
|
| 24 |
- [ ] Test all public links and confirm the Space is running.
|
| 25 |
+
- [ ] Test one English text, one Urdu text, and one screenshot through live
|
| 26 |
+
inference.
|
| 27 |
+
- [ ] Confirm the Modal endpoint is warm or starts successfully before
|
| 28 |
+
recording and submitting.
|
| 29 |
+
|
| 30 |
+
Current audit: the GitHub and Hugging Face repositories have different HEAD
|
| 31 |
+
commits, so synchronization is still required.
|
| 32 |
+
|
| 33 |
+
The official page requires a Space link, short demo video, and social post.
|
| 34 |
+
Backyard AI also judges whether the intended person actually used the app.
|
| 35 |
+
Social-media `@` mentions are not listed as a core requirement.
|
| 36 |
+
|
| 37 |
+
## Award and bonus-quest claims
|
| 38 |
+
|
| 39 |
+
- [x] Backyard AI selected as the intended main track
|
| 40 |
+
- [x] Modal-powered app
|
| 41 |
+
- [x] Tiny Titan target: production model is 4B
|
| 42 |
+
- [x] Off-Brand: custom `gradio.Server` frontend
|
| 43 |
+
- [x] Llama Champion: inference through `llama.cpp`
|
| 44 |
+
- [ ] Sharing is Caring: public privacy-safe request traces exist, but confirm
|
| 45 |
+
that deterministic request traces qualify as an “agent trace”
|
| 46 |
+
- [x] Field Notes: public build report
|
| 47 |
+
- [x] OpenAI Track target: public repo with Codex-attributed commits
|
| 48 |
+
- [ ] Best Demo: complete only after the video and social post are published
|
| 49 |
|
| 50 |
+
Not claimed: Off the Grid, Well-Tuned, NVIDIA Nemotron Quest, Best Agent.
|
| 51 |
|
| 52 |
## Links
|
| 53 |
|