build-small-hackathon/Household-Food-Waste-Forensics

Household Food Waste Forensics

Smart local app cross-referencing grocery receipts to reduce food waste.

📝 Read our Article

Check out our detailed article about this project here: Household Food Waste Forensics: Smart Tracking for Sustainable Kitchens

About this Project

Idea: A smart household app that cross-references grocery receipts with fridge photos to help reduce food waste. Tech: Employs MiniCPM-V for fridge analysis and NeMoTRON-PARS for receipt parsing. It includes a custom LoRA adapter trained using Modal for enhanced receipt understanding, all wrapped in a custom eco-green Gradio UI running fully offline.

Standalone Hugging Face Space / local repo for the P4 demo only.

What this repo contains:

• —the split app entrypoint for this repo only
• —the shared helper modules needed by the app and its eval runner
• —only the demo packs that belong to this split repo

Local run

From the repo root:

python app.py

If you prefer an isolated environment:

python -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
python app.py

The app listens on PORT when provided, otherwise defaults to 7860.

Trace artifacts are written on every demo-pack load or eval run. Use the Load sample data button in the UI or the eval runner JSON trace_path field to find the file under data/artifacts/<project>/traces/.

Off-brand UI

Custom styling lives in assets/theme.css. Edit that file to tune the clean green eco palette, spacing, and typography. The app loads it at launch via Gradio css_paths.

Llama Champion smoke

The main app now uses a model-only, fail-fast path: if the local GGUF is missing it raises a clear error instead of fabricating a response. The badge is still satisfied by a dedicated local GGUF smoke that exercises llama-cpp-python end-to-end and writes a small verification artifact.

P4 uses openbmb/MiniCPM5-1B-GGUF (MiniCPM5-1B-Q4_K_M.gguf) as the preferred local GGUF because it matches the registry's MiniCPM-5-1B family.

Install dependencies with your normal venv flow; requirements.txt already points pip at the CPU wheel index for llama-cpp-python==0.3.28.

Download the model into models/:

mkdir -p models
huggingface-cli download openbmb/MiniCPM5-1B-GGUF MiniCPM5-1B-Q4_K_M.gguf --local-dir models

Direct smoke from the repo root:

LLAMA_CHAMPION_MODEL=models/MiniCPM5-1B-Q4_K_M.gguf python scripts/llama_champion_smoke.py --artifact-path artifacts/verification/$(date +%F)/llama_champion_smoke.json

The script writes artifacts/verification/<YYYY-MM-DD>/llama_champion_smoke.json by default if you omit --artifact-path.

Pytest wrapper:

LLAMA_CHAMPION_MODEL=models/MiniCPM5-1B-Q4_K_M.gguf .venv/bin/python -m pytest -q tests/test_llama_champion_smoke.py

If the pytest env does not already have llama_cpp, set LLAMA_CHAMPION_PYTHON to the interpreter that does.

Docker

Build the image:

docker build -t all4-p4 .

Run the app container:

docker run --rm -p 7860:7860 all4-p4

Optional: run the bundled llama.cpp server from the same image with the same GGUF used above:

docker run --rm -p 8080:8080 -v "$PWD/models:/models" --entrypoint llama-server all4-p4   --model /models/MiniCPM5-1B-Q4_K_M.gguf --host 0.0.0.0 --port 8080

Notes:

• —The image is CPU-only and multi-stage; it builds llama.cpp in a builder stage and keeps the runtime stage lean.
• —.venv/ is ignored by the Docker build context, so local virtualenvs do not get baked into the image.
• —The app and llama-server share the same image but are launched separately.

Offline verification

Run the bundled offline smoke check from the repo root:

bash scripts/offline_smoke.sh

CI-friendly pytest wrapper:

python -m pytest -q tests/test_offline_smoke.py

Docker variant with outbound networking disabled:

docker run --rm --network none -v "$PWD:/repo" -w /repo all4-p4 bash scripts/offline_smoke.sh

The smoke check loads a bundled demo pack, blocks socket/HTTP client creation, and fails if any runtime code tries to reach the network.

Sponsor model policy gate

Run the repo-local sponsor gate without Docker:

python scripts/check_sponsor_model_policy.py
pytest -q tests/test_sponsor_model_policy.py

The gate checks that the registry matches the sponsor-approved model policy before any packaging or Docker verification step.

Field notes

See FIELD_NOTES.md for the badge artifact, evidence notes, and next steps.

Well-Tuned receipt adapter

The local receipt parser now uses a small real LoRA-style adapter rather than a deterministic proxy artifact, and the main model path logs model ID, adapter name, and generation stats on every successful inference. The committed artifact lives under models/p4_receipt_parser_real_lora/adapter.json, and the tiny synthetic training set that produces it lives in data/well_tuned/p4_receipt_adapter/train_examples.jsonl.

Rebuild it locally with:

python scripts/train_p4_receipt_adapter.py --examples data/well_tuned/p4_receipt_adapter/train_examples.jsonl --output models/p4_receipt_parser_real_lora

Run the Modal GPU entrypoint and copy the final adapter back to the repo with:

python scripts/modal_train_p4_receipt_adapter.py --examples data/well_tuned/p4_receipt_adapter/train_examples.jsonl --output models/p4_receipt_parser_real_lora

Notes:

• —You need Modal installed (pip install modal) and authenticated (modal token new, or provide MODAL_TOKEN_ID/MODAL_TOKEN_SECRET).
• —If Modal isn't configured, the script falls back to the local path unless you pass --no-modal-fallback.

Verify the adapter with the bundled smoke test:

bash scripts/well_tuned_smoke.sh

Sharing traces

Use python scripts/share_traces_to_hf_dataset.py <traces-dir> to materialize a deterministic JSONL + metadata bundle under artifacts/verification/<YYYY-MM-DD>/sharing_is_caring/all4-p4-food-waste/.

• —The default mode is local-only; pass --push plus --repo-id and HF_TOKEN to publish a Hugging Face Dataset bundle.
• —--dry-run forces offline materialization even when --push is present.
• —See CHANGELOG.md for the latest trace-sharing notes.

Submission assets

Fill these TODO fields before final submission; they are placeholders only and do not imply the assets already exist.

• —[ ] TODO Hugging Face Space URL (build-small org): <SPACE_URL>
• —[ ] TODO Public GitHub repo URL: <REPO_URL>
• —[ ] TODO Demo video URL: <VIDEO_URL>
• —[ ] TODO Social post URL: <SOCIAL_POST_URL>
• —[ ] TODO Concise disclaimer: synthetic/repo-authored food photos and receipts only; no household data from real users.
• —[ ] TODO Sponsor model attribution list:
• —MiniCPM: openbmb/MiniCPM-V-4_6 for fridge-photo analysis and openbmb/MiniCPM-5-1B for spend summaries and suggestions
• —NeMoTRON: nvidia/NeMoTRON-PARS for receipt parsing and table extraction

Models and data attributions

• —The bundled demo packs are synthetic or repo-authored and are licensed CC0-1.0 unless a subfolder README says otherwise.
• —The sponsor models for this repo are MiniCPM and NeMoTRON-PARS; keep the submission-assets attribution aligned with configs/model_registry.yaml.
• —The committed local receipt adapter lives at models/p4_receipt_parser_real_lora/adapter.json and is rebuilt from the synthetic JSONL examples under data/well_tuned/p4_receipt_adapter/.
• —The sample GGUF above is only an example; use a model whose license and size are suitable for your deployment.
• —No PII/PHI is included in the shipped demo packs.