Finalize hackathon submission documentation

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

FIELD_NOTES.md

@@ -1,279 +0,0 @@
-# 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`.
-
-## Why I built it this way
-
-I initially built with a larger Qwen model, then tested whether a much smaller
-model could preserve the safety behavior while reducing serving requirements.
-Qwen3.5 4B Q8 passed all high-risk scam cases and both screenshot cases in the
-ten-case evaluation, making it the practical production choice.
-
-The MTP variant was especially appealing because speculative multi-token
-prediction can improve generation speed when the draft tokens are accepted. In
-the deployed experiment, Qwen3.5 generated 440 draft tokens and accepted 222,
-for a 50.5% draft acceptance rate with `n_max=2`.
-
-I chose Modal because it provides a serverless GPU endpoint that scales to zero
-after inactivity and starts again on demand. That is a strong cost model for a
-demo with irregular traffic because compute is paid for when the deployment is
-actually used instead of keeping a GPU running continuously. Persistent
-Volumes avoid downloading the model and projector on every cold start.
-
-Control was another reason for using Modal. I build and pin the `llama.cpp`
-runtime, choose the model and quantization, manage the endpoint, and protect it
-with proxy authentication. Inputs are not sent to a third-party hosted LLM
-API. Modal still processes the request on its infrastructure, so this is
-self-managed inference rather than fully local inference, but the model-serving
-stack and API behavior remain under my control.
-
-## Product decisions
-
-- Offer both English and Urdu instead of assuming every user is comfortable
-  interpreting safety guidance in English.
-- Use simple, direct wording 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.
-
-## English and Urdu experience
-
-I added an English/Urdu switch to make the app more useful for people who can
-read a suspicious message but would understand the safety advice more clearly
-in Urdu. The selected language is remembered in the browser, so returning users
-do not have to switch it again.
-
-Urdu mode is more than a translated navigation layer. It changes the page to a
-right-to-left layout and translates headings, form labels, validation errors,
-status messages, risk labels, examples, disclaimers, and result-card controls.
-Live assessments also ask the model to return the explanation, red flags, safe
-next steps, and optional reply draft in clear Urdu script. English cached
-examples remain cached; selecting one in Urdu mode sends it through the live
-model so the result language matches the interface.
-
-The first Urdu layout exposed details that were easy to miss in English:
-headings needed different line heights, mixed Urdu and Latin model names could
-reorder unexpectedly, and mobile controls required more vertical space. I
-tested the interface at desktop and 390-pixel mobile widths, adjusted the RTL
-spacing, and rewrote literal translations into shorter, more natural Urdu.
-
-I also tested a bundled Nastaliq webfont. It made the interface feel less
-consistent and reduced readability at the sizes used by the app, so I removed
-it and returned to the earlier system Arabic font stack. This kept the improved
-Urdu copy and RTL layout without forcing a decorative typeface on every device.
-
-## Small-model stack
-
-The primary model is `unsloth/Qwen3.5-4B-MTP-GGUF`, using the
-`Qwen3.5-4B-Q8_0.gguf` quantization and `mmproj-F16.gguf` vision projector.
-At 4B parameters it stays well below the hackathon's 32B limit.
-
-Modal supplies an L4 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 |
-| --- | --- |
-| Initial evaluation strict passes | 9 of 10 |
-| Initial evaluation average score | 89.5/100 |
-| Final regression evaluation | 10 of 10 |
-| Final regression average score | 100/100 |
-| High-risk scam cases | All passed |
-| Screenshot cases | Both passed |
-| MTP draft acceptance | 222 of 440 tokens (50.5%) |
-| MTP draft limit | `n_max=2` |
-
-The final score comes from the same small ten-case suite after prompt and
-output-contract fixes. It is useful as a regression check, but it is not a
-real-world accuracy estimate.
-
-The full setup and measurements are documented in
-[the model experiment notes](docs/model_experiment_notes.md).
-
-## Building with Codex
-
-Codex helped build most of the project, especially the custom frontend,
-Gradio Server integration, tests, trace pipeline, documentation, and repeated
-UI refinements. I was surprised by how quickly a fully custom HTML, CSS, and
-JavaScript interface could be connected to Gradio's queue and SSE protocol.
-This let me keep Hugging Face Spaces compatibility without settling for the
-default Gradio component layout.
-
-I used Codex as an engineering collaborator rather than only a code generator.
-It inspected the existing repository, implemented changes, ran tests, checked
-the live Space metadata, and helped keep the Modal and `llama.cpp`
-documentation consistent with the deployed system. The public Git history
-includes Codex co-author attribution for that work.
-
-## 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
-  -> English or Urdu interface and response-language request
-  -> queued gradio.Server endpoint
-  -> OpenAI-compatible client
-  -> Modal proxy-authenticated web server
-  -> CUDA llama.cpp
-  -> Qwen3.5 4B Q8 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. The production app disables thinking so the bounded
-  completion budget is used for the final structured response.
-- A dense Roman Urdu screenshot reached the original completion limit. Image
-  requests now receive a larger token budget.
-- The first Urdu interface used direct translations and generic spacing. It
-  was revised with more natural wording, RTL-specific typography, responsive
-  spacing, and cleaner handling of mixed Urdu and Latin text.
-- A bundled Nastaliq font looked worse in the product UI than the original
-  system font stack. The font was removed while retaining the improved Urdu
-  layout and copy.
-- 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.
-
-I designed the trace format this way because personal information can leak
-from more than the original input. A model explanation, reply draft, extracted
-phone number, URL, or exception can repeat private details even when the raw
-message is omitted. The trace serializer therefore does not publish the user's
-input, the model's free-form reasoning, the generated reply, or the final
-response text. It derives a limited set of redacted categories, booleans,
-counts, and fixed summaries instead.
-
-This minimizes what the application publishes, but it is not a claim that
-model inference itself is anonymous. Live text and images still travel to the
-private Modal endpoint for analysis. Users are warned not to submit sensitive
-personal data, and public trace sharing can be disabled before a request.
-
-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
-
-The product focuses on patterns repeatedly present in Pakistani scam
-advisories and reported examples:
-
-- 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, 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
-
-- The live Space depends on the Modal endpoint and its cold-start behavior.
-- Screenshot quality and dense Roman Urdu text can affect visual recognition.
-- Urdu output quality still depends on the model, and mixed technical terms
-  may occasionally need English wording for clarity.
-- 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.
-
-## Future direction
-
-The next major feature would be an agentic verification workflow. After
-understanding the submitted text or screenshot, the agent could search the web
-for current scam warnings, identify the organization being impersonated, and
-compare claims against independently discovered official sources. It could
-then present the evidence it found alongside the model's assessment.
-
-That workflow needs strict boundaries. It must never follow links or call
-numbers supplied by the suspicious message as if they were trusted. Search
-results would need source ranking, domain verification, citations, and a clear
-distinction between evidence and inference. The current project stops at
-triage because adding web access without those controls could make a safety
-tool less safe.
-
-## Hackathon submission status
-
-The project meets the core technical constraints: a model at or below 32B,
-Gradio hosting as a Space under the hackathon organization, and a public app.
-It is intended for Backyard AI because the problem is specific and local, the
-4B model is an honest fit for the task, and the interface is designed for the
-people receiving these messages. The final submission form is still pending.
-
-The strongest additional award targets are Modal Awards, Tiny Titan, Off-Brand
-Award, and the OpenAI Track. The implemented bonus-quest evidence clearly
-covers Llama Champion, Off-Brand, and Field Notes. The public trace dataset is
-a Sharing is Caring candidate, but the official wording says “agent trace”
-while this project publishes deterministic request traces rather than an
-autonomous-agent trajectory; that eligibility should be confirmed with the
-organizers. The project does not claim Off the Grid, Well-Tuned, the Nemotron
-Quest, or Best Agent.
-
-Before the June 15, 2026 deadline, the remaining submission work is to record
-target-user use and any resulting change, publish the short demo video and
-social post, verify that GitHub mirrors the final Space source, and submit the
-three required links. The operational checklist is in `SUBMISSION_TODO.md`.
-
-## 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)
-- [Qwen3.5 4B MTP GGUF](https://huggingface.co/unsloth/Qwen3.5-4B-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/)
-
-Hackathon requirements, public links, and deployment claims were reviewed on
-June 8, 2026.

README.md

@@ -51,24 +51,36 @@ mixed-language inputs are also supported.
 | Live app | [Hugging Face Space](https://huggingface.co/spaces/build-small-hackathon/pakistan-notice-helper) |
 | Source | [GitHub repository](https://github.com/kingabzpro/pakistan-notice-helper) |
 | Open traces | [Privacy-safe trace dataset](https://huggingface.co/datasets/build-small-hackathon/pakistan-notice-helper-traces) |
-| Build report | [`FIELD_NOTES.md`](FIELD_NOTES.md) |
+| Demo video | [Watch on YouTube](https://www.youtube.com/watch?v=EgYA3jrZTm0) |
+| Build story | [Building Pakistan Notice Helper](https://huggingface.co/blog/build-small-hackathon/building-pakistan-notice-helper) |
+| Social post | [Project announcement on LinkedIn](https://www.linkedin.com/posts/1abidaliawan_after-3-straight-days-of-building-testing-ugcPost-7469716521095794688-TlqZ/) |
 
 ## Hackathon Fit
 
-This is an intended **Backyard AI** submission for the
+This is a **Backyard AI** submission for the
 [Build Small. Play Big. Hackathon](https://huggingface.co/build-small-hackathon).
 It applies a small model to a practical regional safety problem.
 
 | Area | Project evidence |
 | --- | --- |
-| Core constraints | Public Gradio Space using Qwen3.5-4B, below the 7B limit |
-| Backyard AI | Notice and scam triage designed for Pakistani users |
+| Core constraints | Public Gradio Space using Qwen3.5-4B, below the 32B limit |
+| Backyard AI | A real user tested the phone workflow and plans to use it for future suspicious messages |
 | Modal | Qwen3.5-4B is hosted on a Modal L4 GPU endpoint |
 | Tiny Titan | The 4B Q8 model passed the final 10-case internal regression suite |
 | Llama Champion | Qwen3.5-4B runs through a CUDA-enabled `llama.cpp` server using its OpenAI-compatible API |
 | Off-Brand | Custom mobile-first HTML, CSS, and JavaScript interface served through `gradio.Server` instead of the default Gradio UI |
-| Bonus quests | Runtime notes for Local Llama, privacy-safe traces, and published field notes |
-| Pending | Track form, user test, demo video, public announcement, and final repository sync |
+| Sharing is Caring | Privacy-safe workflow traces are published as a Hugging Face dataset |
+| Field Notes | Published a blog in the Build Small Hackathon organization sharing my opinions, development experience, model experiments, and lessons learned |
+
+## Demo and User Feedback
+
+The [demo video](https://www.youtube.com/watch?v=EgYA3jrZTm0) includes a real
+user using the app on a phone, taking screenshots of messages, and checking
+them with Pakistan Notice Helper.
+
+The user especially liked the app's speed and the accuracy of its responses.
+They said they plan to use it in the future to check different scam or
+suspicious messages.
 
 ## Architecture
 

SUBMISSION_TODO.md

@@ -1,59 +0,0 @@
-# Build Small Submission TODO
-
-Deadline: **June 15, 2026**
-
-## Required submission package
-
-- [x] Host the Gradio app as a Space under the hackathon organization.
-- [ ] Record and publish a short demo video.
-- [ ] Publish a social-media post.
-- [ ] Submit the Space, demo video, and social-post links by June 15, 2026.
-- [ ] Save the submission confirmation.
-
-## Backyard AI evidence
-
-- [ ] Ask at least one target user to try the Space.
-- [ ] Save a short, anonymized quote or note about their experience.
-- [ ] Add the user feedback and any resulting improvement to `FIELD_NOTES.md`.
-
-## Final documentation and verification
-
-- [ ] Add the demo and social-post links to `README.md`.
-- [ ] Confirm the public GitHub repository contains the final Space source and
-      Codex-attributed commits.
-- [ ] Test all public links and confirm the Space is running.
-- [ ] Test one English text, one Urdu text, and one screenshot through live
-      inference.
-- [ ] Confirm the Modal endpoint is warm or starts successfully before
-      recording and submitting.
-
-Current audit: the GitHub and Hugging Face repositories have different HEAD
-commits, so synchronization is still required.
-
-The official page requires a Space link, short demo video, and social post.
-Backyard AI also judges whether the intended person actually used the app.
-Social-media `@` mentions are not listed as a core requirement.
-
-## Award and bonus-quest claims
-
-- [x] Backyard AI selected as the intended main track
-- [x] Modal-powered app
-- [x] Tiny Titan target: production model is 4B
-- [x] Off-Brand: custom `gradio.Server` frontend
-- [x] Llama Champion: inference through `llama.cpp`
-- [ ] Sharing is Caring: public privacy-safe request traces exist, but confirm
-      that deterministic request traces qualify as an “agent trace”
-- [x] Field Notes: public build report
-- [x] OpenAI Track target: public repo with Codex-attributed commits
-- [ ] Best Demo: complete only after the video and social post are published
-
-Not claimed: Off the Grid, Well-Tuned, NVIDIA Nemotron Quest, Best Agent.
-
-## Links
-
-- Space: https://huggingface.co/spaces/build-small-hackathon/pakistan-notice-helper
-- GitHub: https://github.com/kingabzpro/pakistan-notice-helper
-- Traces: https://huggingface.co/datasets/build-small-hackathon/pakistan-notice-helper-traces
-- Demo video: TODO
-- Social post: TODO
-- Submission confirmation: TODO