README.md

---
title: Off-Grid Field Repair Logbook
emoji: 🔧
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
app_port: 7860
tags: ["track:wood", "sponsor:nvidia", "sponsor:openbmb", "achievement:offgrid", "achievement:offbrand", "achievement:fieldnotes", "achievement:llama"]
---
# Off-Grid Field Repair Logbook

> Rugged, off-grid AI terminal for generating offline hardware repair checklists.

## 📝 Read our Article
Check out our detailed article about this project here: [Off-Grid Field Repair Logbook: AI Diagnostics Without the Cloud](https://huggingface.co/spaces/build-small-hackathon/Off-Grid-Field-Repair-Logbook/blob/main/BLOG_POST.md)

## About this Project
**Idea:** A rugged, off-grid AI terminal designed to generate reliable hardware repair checklists in disconnected environments.
**Tech:** Built for the "Thousand Token Wood" track, it integrates `nvidia/NeMoTRON-3-Nano-4B-Instruct` for reasoning, `openbmb/MiniCPM-V-4_6` for vision, and `NeMoTRON-PARS` for manual parsing. It features a dark terminal UI and strict network-blocked verification.

Standalone Hugging Face Space for the P3 field-repair demo.

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:

```bash
./run_local.sh
```

If you prefer an isolated environment:

```bash
python -m pip install -r requirements.txt
python app.py
```

The Gradio app listens on SERVER_PORT/PORT and 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 report JSON `trace_path` field to find the file under `data/artifacts/p3_field_repair_logbook/traces/`.

## Off-brand UI

Custom styling lives in `assets/theme.css`.
Edit that file to tune the dark terminal look, neon accents, and monospace typography.
The app loads it at launch via Gradio `css_paths`.

## Llama Champion smoke

The main app stays on its normal offline-first path; the badge is satisfied by a dedicated local GGUF smoke that exercises `llama-cpp-python` end-to-end and writes a small verification artifact.

P3 uses `openbmb/MiniCPM-V-4.6-gguf` (`MiniCPM-V-4_6-F16.gguf`) as the preferred local GGUF because it matches the repo's MiniCPM-V-4_6 vision family, which has a public GGUF mirror.

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/`:

```bash
mkdir -p models
huggingface-cli download openbmb/MiniCPM-V-4.6-gguf MiniCPM-V-4_6-F16.gguf --local-dir models
```

Direct smoke from the repo root:

```bash
LLAMA_CHAMPION_MODEL=models/MiniCPM-V-4_6-F16.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:

```bash
LLAMA_CHAMPION_MODEL=models/MiniCPM-V-4_6-F16.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:

```bash
docker build -t all4-p3 .
```

Run the app container:

```bash
docker run --rm -p 7860:7860 all4-p3
```

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

```bash
docker run --rm -p 8080:8080 -v "$PWD/models:/models" --entrypoint llama-server all4-p3   --model /models/MiniCPM-V-4_6-F16.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
bash scripts/offline_smoke.sh
```

CI-friendly pytest wrapper:

```bash
python -m pytest -q tests/test_offline_smoke.py
```

Docker variant with outbound networking disabled:

```bash
docker run --rm --network none -v "$PWD:/repo" -w /repo all4-p3 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:

```bash
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](FIELD_NOTES.md) for the badge artifact, evidence notes, and next steps.

## 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-p3-field-repair/`.

- 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 repair logs and prompts only; no safety-critical advice is guaranteed.
- [ ] TODO Sponsor model attribution list:
  - Reasoning LLM: `nvidia/NeMoTRON-3-Nano-4B-Instruct`
  - Vision LLM: `openbmb/MiniCPM-V-4_6`
  - Manual parser: `nvidia/NeMoTRON-PARS`

## 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-approved model set for this repo includes `nvidia/NeMoTRON-3-Nano-4B-Instruct`, `openbmb/MiniCPM-V-4_6`, and `nvidia/NeMoTRON-PARS`; keep the submission-assets attribution aligned with `configs/model_registry.yaml`.
- 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.