Abid Ali Awan Codex commited on
Commit
1663316
·
1 Parent(s): cde909f

Refine hackathon documentation

Browse files

Shorten 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>

Files changed (3) hide show
  1. FIELD_NOTES.md +72 -6
  2. README.md +80 -219
  3. 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
- - Use simple English rather than legal or security terminology.
 
 
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
- | Evaluation strict passes | 9 of 10 |
73
- | Evaluation average score | 89.5/100 |
 
 
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. Disabling thinking produced reliable structured
121
- responses.
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
- Research and deployment results were reviewed on June 7, 2026.
 
 
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 and messages for scam/fraud risks.
27
  ---
28
 
29
  # Pakistan Notice Helper
30
 
31
- Pakistan Notice Helper is a Qwen3.5-powered safety assistant for confusing or
32
- suspicious Pakistani notices, bills, SMS messages, bank alerts, FBR-style
33
- messages, challans, and courier/customs messages. It accepts pasted text and
34
- screenshots, then returns:
35
 
36
- - **Risk label:** Looks normal, Verify first, Suspicious, or Likely scam
37
- - A simple English explanation
38
- - Red flags found
39
- - Safe next steps
40
- - A polite reply draft
41
 
42
- The interface is a custom mobile-first frontend served by
43
- [`gradio.Server`](https://www.gradio.app/main/guides/server-mode). Gradio
44
- provides queueing, API routes, and Hugging Face Spaces hosting without exposing
45
- a default Gradio UI.
46
 
47
- > **Pakistan Notice Helper does not provide official verification. It checks
48
- > common scam signals and gives safe next steps. Always verify through official
49
- > websites or helplines before making payments or sharing personal
50
- > information.**
51
 
52
- ## Build Small Hackathon
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
- | **Small Models Only** | Uses Qwen3.5 4B MTP, well below the 32B parameter limit. |
77
- | **Built on Gradio** | Runs as a Gradio Space under the hackathon organization using `gradio.Server`. |
78
- | **Backyard AI: specific problem** | Helps people in Pakistan assess suspicious local notices, payment demands, courier messages, challans, and government impersonation scams. |
79
- | **Backyard AI: small-model fit** | A quantized 4B Q8 GGUF handles text, screenshots, Roman Urdu, and structured safety guidance through `llama.cpp`. |
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
- ## Model configuration
117
 
118
- The app uses the standard OpenAI Python SDK as a client for an
119
- OpenAI-compatible endpoint. It does not call OpenAI cloud APIs by default.
 
120
 
121
- | Variable | Purpose |
122
  | --- | --- |
123
- | `MODEL_BASE_URL` | Optional override for the built-in Modal endpoint |
124
- | `MODEL_NAME` | Optional override for the built-in model ID |
125
- | `MODEL_API_KEY` | Optional endpoint API key |
126
- | `MODEL_TIMEOUT_SECONDS` | Optional request timeout; default is 180 seconds |
127
- | `MODAL_PROXY_KEY` | Optional Modal proxy authentication key |
128
- | `MODAL_PROXY_SECRET` | Optional Modal proxy authentication secret |
129
- | `HF_TOKEN` | Scoped Hugging Face token used by the background trace uploader |
130
- | `HF_TRACE_DATASET_REPO` | Trace dataset repo; defaults to `build-small-hackathon/pakistan-notice-helper-traces` |
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
- Custom HTML/CSS/JavaScript frontend
164
  |
165
- | Gradio POST + SSE protocol
166
  v
167
- Queued gradio.Server backend
168
  |
169
- | OpenAI Python SDK
170
  v
171
- Deployed/local OpenAI-compatible endpoint
172
  |
173
- | Modal L4 + CUDA llama-server
174
  v
175
- llama.cpp runtime
176
  |
177
  v
178
- unsloth/Qwen3.5-4B-MTP-GGUF
 
 
 
179
  ```
180
 
181
- All frontend assets are local. The app has no runtime CDN, analytics, OCR, MCP,
182
- or OpenAI Agents SDK. The OpenAI Python package is only an HTTP client for the
183
- OpenAI-compatible `llama-server` endpoint; requests are not sent to OpenAI.
184
- Analysis currently depends on the deployed Modal model.
185
-
186
- ## Sharing is Caring: Open Traces
187
 
188
- The app publishes optional privacy-safe backend traces to
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
- Trace creation is deterministic Python logic and makes no additional model
194
- request. Text inputs are aggressively redacted and capped at 500 characters;
195
- images use a fixed `image: ...` description without OCR or image storage. The
196
- trace also records category, urgency, fixed signals, result counts, and a
197
- deterministic `result_summary` explaining the scam pattern and risk label.
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
- Safe records are queued without blocking the response, written in batches of
205
- 20 or after 60 seconds, and uploaded as unique JSONL shards. Hub failures leave
206
- the shard pending for a later retry and do not affect scam analysis.
207
 
208
- Operator commands:
209
 
210
  ```bash
211
- python -m traces.scripts.seed_trace_dataset
212
- python -m traces.scripts.validate_traces
213
- python -m traces.scripts.create_trace_dataset --dry-run
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
- See [the dataset card](traces/dataset_card.md) for the schema, privacy
221
- policy, provenance, and limitations.
222
-
223
- ## Deployment
224
 
225
- The app is deployed as a Gradio Space under the Build Small Hackathon
226
- organization. The metadata at the top of this README pins Gradio, identifies
227
- the Backyard AI track, and launches `app.py`.
228
 
229
- Add `MODAL_PROXY_KEY` and `MODAL_PROXY_SECRET` under
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
- ## Privacy and limitations
 
 
235
 
236
- - Submitted text and images are sent to the configured Modal endpoint and are
237
- not saved by this app.
238
- - Public traces contain only allow-listed metadata, buckets, booleans, counts,
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
- The six bundled examples have cached Modal assessments and deterministic seed
278
- traces. Runtime trace shards are kept out of Git and uploaded separately.
279
 
280
- ## Official reporting channels
 
 
 
 
281
 
282
- Use contact details that you navigate to independently:
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 call a number or open a link merely because it appears inside the message
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
- - [ ] Record and publish a short demo video.
9
- - [ ] Publish a social-media post with the Space, video, and GitHub links.
 
10
  - [ ] Add the demo and social-post links to `README.md`.
 
 
11
  - [ ] Test all public links and confirm the Space is running.
12
- - [ ] Submit the Space, demo video, and social post through the official form.
13
- - [ ] Save the submission confirmation.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
14
 
15
- Social-media `@` mentions are optional, not required.
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