Rendered view of README.md. Read it as a page; the download link gives you the raw Markdown working file.

Download README.md

Capstone starter pack — AI tagging on R2, the NAS and OpenRouter

The starter pack for the capstone: design and prototype the next phase of the campus media unit's catalogue. Add AI tagging to 5,000 assets, with a governance rule, inside a fixed monthly budget, using:

  • Cloudflare R2 for the canonical catalogue and tags (private) and the thumbnails (public, behind media.<root>);
  • the Nextcloud/RAID NAS as the local origin and backup for the 5,000 originals;
  • the S4 Worker, extended with a tag-ingest route, as the catalogue API and the write gate;
  • OpenRouter as the governed managed-inference path.

You choose the tagging method — managed inference, the fine-tuned Qwen3.5-4B, or the S10 classifier — and justify it in the proposal. Every implementation includes one refused and one accepted governed OpenRouter request, and every record passes the Worker's gate.

This pack is a starting point, not the answer: replace the canned offline stub with your method, extend the rule's vocabulary, and build your own evidence.

Architecture — what each piece does

        originals + backup                    canonical catalogue + tags
   ┌──────────────────────────┐          ┌──────────────────────────────┐
   │  Nextcloud on RAID1 NAS  │          │  private R2: capstone-       │
   │  /srv/nas/nextcloud      │          │  catalogue (Worker binding)  │
   └────────────┬─────────────┘          └──────────────┬───────────────┘
                │ rclone backup                          │ validated writes
                ▼                                        │
   ┌──────────────────────────┐          ┌──────────────┴───────────────┐
   │  private R2 backup       │          │  Worker: /health, /assets,   │
   │  capstone-nas-backup     │          │  /asset/:id, /ingest/tags    │
   └──────────────────────────┘          └──────────────┬───────────────┘
                                                        │ reads tags
   ┌──────────────────────────┐          ┌──────────────┴───────────────┐
   │  tag.py (laptop/Droplet) │─────────▶│  OpenRouter, ZDR + deny      │
   │  preflight → batch 100   │  governed │  data_collection, no         │
   │  → validate → post       │  request  │  fallbacks                   │
   └──────────────────────────┘          └──────────────────────────────┘
Piece Holds Visibility
capstone-catalogue (R2) catalogue.json, tags.json, private files Worker binding only
capstone-media-public (R2) thumbs/*.png public, R2 custom domain media.<root>
NAS /srv/nas the 5,000 originals, Nextcloud data private network, nas.<root>
Worker capstone-catalogue API + ingest gate workers.dev or a custom domain
tag.py the pipeline and its checkpoints your laptop or the Droplet

Two R2 buckets, because an R2 custom domain exposes every key in the bucket it is attached to. Public thumbnails and the private catalogue cannot share one.

What to run, in what order

COMMANDS.md is the authoritative sequence: every command, in order, with an explanation. The short version for the local profile:

python3 -m unittest discover -s tests
npm install && npm test
python3 generate_assets.py --count 5000 --seed 20261113 --out data/library
python3 strip_exif.py --check data/library
bash run.sh                       # the full local reference run

run.sh is the verified reference: it starts the Worker locally, seeds the emulated R2 bucket, tags through the gate, proves the gate refuses a bad record, reconciles the budget, verifies the evidence and writes a sanitized log. The learner still types each command from COMMANDS.md and observes it.

Files

File Purpose
governance-rule.json The S8 six-part rule plus tag_schema and ingest; the single source the Worker and pipeline both read
generate_assets.py Seeded 5,000-asset generator: catalogue, 400 px PNGs, labels, 200-asset holdout, hashes
tag.py Preflight, batches of 100, checkpoint/resume, local validation, Worker post, failure log, monthly batch, review sample
reconcile.py Reconciles actuals against the $80 spine and the $5/$10 envelopes
reconcile.ipynb The same reconciliation as a notebook
budget.csv The monthly spine and the capstone's actual lines, with a basis and note per line
strip_exif.py Checks or strips EXIF before an image leaves the laptop
scripts/sanitize_log.py Removes tokens, account IDs, emails and keys from a log
src/index.js The S4 Worker extended with POST /ingest/tags and rule validation
test/worker.test.js 14 Worker tests, including the gate's refusals
tests/test_capstone.py 18 Python tests for the generator, pipeline, budget, EXIF and sanitizer
compose.yaml, Caddyfile, .env.example The S5 Nextcloud/MariaDB/Redis/Caddy NAS stack
compose.local.yaml The laptop fallback stack on port 8080
up.sh, down.sh Open and close the bounded 72-hour window; write the teardown log
run.sh The verified reference runner
verify.sh The machine proof over the evidence bundle
COMMANDS.md Every command with an explanation

The ten-item evidence bundle

  1. The generated manifest: seed, count, generator hash, catalogue hash.
  2. The tag output (tags.jsonl, report.json): schema validity, coverage, and every failed asset in failures.jsonl.
  3. Worker proof: /health, /asset/:id with tags, /assets?tag=<tag>, the refused record and the accepted governed write.
  4. Governance: the rule file, the dated endpoint snapshot, the refused and accepted OpenRouter requests, and the 10% sample-review sheet.
  5. NAS proof: RAID1 status, originals in Nextcloud, the rclone backup and the restore checksum.
  6. One measured 40-item monthly batch and its run-rate projection.
  7. Cost actuals: OpenRouter usage, the DigitalOcean balance and bill, R2 usage, reconciled against $5 and $80; no-auto-top-up proof.
  8. The budget sheet: forecast versus actuals, with every delta explained.
  9. The sanitized command log, COMMANDS.md and your runner.
  10. The teardown log and the final balance, with the no-resources-running check.

Budget

Line Monthly spine Capstone actual Why
Storage $25 ≈ $0.20 20 GiB of block storage for 72 hours; R2 stays in the free tier
Compute and CDN $25 ≈ $2.36 one s-2vcpu-4gb Droplet for 72 hours; Workers and CDN are free
Egress $15 $0.00 R2 egress is free
Inference $5 measured the 40-item monthly batch projected to 40/month
Buffer $10 $10.00 held, not spent
Total $80 ≈ $12.56 + inference the bounded window, not a month of Droplet

The $12.56 is the envelope, including the $10 the buffer holds back; cash spend is about $2.56 plus the measured inference line. budget-reconciliation.json reports both actual_total_usd and spent_usd so the distinction is explicit.

The one-off backfill is capped at the $10 OpenRouter credit carried from S8, separately from the monthly line. python3 reconcile.py --check exits non-zero if inference exceeds $5, the total exceeds $80, or the backfill exceeds $10.

Governance

governance-rule.json is the S8 rule extended for the capstone:

  • Part 1: synthetic/public/internal data only; real personal or sensitive media never leaves the laptop.
  • Part 2: names, emails, phones, student IDs, GPS, device and timestamp metadata are removed before any request (strip_exif.py checks images).
  • Part 3: the endpoint must satisfy the rule — zdr: true, data_collection: "deny", allow_fallbacks: false — and the pipeline refuses to start if the dated snapshot has no qualifying endpoint.
  • Part 4–5: no in-region route on the student plan; nothing retained.
  • Part 6: a 10% sample is reviewed; exceptions are approved in writing.

The Worker's ingest route validates every record against tag_schema and ingest and writes nothing if any record fails. The refused and accepted pair in data/run/govern-pair.json is the evidence, not an assertion.

The 72-hour window

Cloud resources run in a bounded window: up.sh opens it (and refuses a second window while one is live), down.sh closes it, and both write timestamps to data/run/teardown.log. The window is why the compute and storage lines are window costs, not a month's Droplet. Deleting the Droplet does not delete its volumes; deleting an R2 bucket does not remove a DNS record. COMMANDS.md section K lists both checks.

Fallback chain

Every fallback keeps the evidence shape and earns full points when labelled: workers.dev + r2.dev; the instructor demo bucket + wrangler dev --local; compose.local.yaml for the NAS; a free-tier or instructor OpenRouter key; the classifier on MPS/CPU. A fallback that changes the evidence shape is a defect.

Safety

Synthetic media only. No real people, client footage, brands or personal data. Never commit .env, .dev.vars or a token; chmod 600 both. Sanitize the log before publishing it. The generated labels are the generator's ground truth and must not be read by a managed pipeline; the canned stub reads them and is labelled canned in the report.