HF prerequisites: create sumpalabs/petrodb dataset repo, stage branch, HF_TOKEN secret, BASE_URL vars

[oskrgab]

What to build

One-time account/settings setup that unblocks the Hugging Face migration (ADR-0005). These are manual actions an agent cannot perform without credentials.

Status (2026-06-15) — GitHub transfer done, HF scaffolding partly done.

• The GitHub repo has been transferred to the sumpalabs org → sumpalabs/petrodb. The old oskrgab/petrodb path redirects, but all secrets/variables below must be created under github.com/sumpalabs/petrodb → Settings → Secrets and variables → Actions (repo-level). Existing Cloudflare secrets carried over with the transfer; HF_TOKEN + BASE_URL_* are new and do not exist yet.
• On Hugging Face, the sumpalabs org and the sumpalabs/petrodb dataset repo already exist (no data pushed yet). Remaining: the stage branch, the HF_TOKEN secret, and the BASE_URL_* variables.

Remaining manual actions:

• Create the Hugging Face dataset repo sumpalabs/petrodb — done (monorepo mirroring the parquet/ root).
• Create a stage branch in that HF repo alongside main. (CI in CI uploads parquet data to Hugging Face on push (data path tracer bullet) #37 can also create it on first push; do it here only if you want it to exist up front.)
• Generate a fine-grained, write-scoped HF access token from an account with write access to the sumpalabs HF org, limited to the sumpalabs/petrodb dataset; add it as a GitHub Actions secret named HF_TOKEN on sumpalabs/petrodb.
• Set GitHub Actions variables on sumpalabs/petrodb: BASE_URL_MAIN = https://huggingface.co/datasets/sumpalabs/petrodb/resolve/main and BASE_URL_STAGE = https://huggingface.co/datasets/sumpalabs/petrodb/resolve/stage.

Acceptance criteria

• sumpalabs/petrodb exists as a public HF dataset repo (org + dataset already created; main exists by default)
• stage branch exists in the HF dataset repo alongside main
• HF_TOKEN secret present on sumpalabs/petrodb (fine-grained, write, scoped to sumpalabs/petrodb)
• BASE_URL_MAIN and BASE_URL_STAGE variables set on sumpalabs/petrodb to the HF resolve bases above
• A manual curl -A 'Mozilla/5.0' -H 'Range: bytes=0-99' -sI <a test parquet resolve URL> returns 206 + Content-Range (confirms HF honors Range as expected)

Blocked by

None - can start immediately

Context: ADR-0005 (docs/adr/0005-host-parquet-on-huggingface.md), CONTEXT.md "PetroDB — hosting & environments".

[oskrgab]

This was generated by AI during triage.

Triage outcome

Category: enhancement · State: ready-for-human

The HF-CLI-completable parts were just executed; the residual blockers genuinely need human credentials/judgment.

Done now (via hf CLI, authed as a sumpalabs member)

• ✅ Created the HF dataset repo sumpalabs/petrodb (public). ⚠️ The issue body marked this AC [x], but it did not actually exist — hf datasets info returned "not found". It exists now.
• ✅ Created the stage branch off main.
• ✅ Pushed a thin dataset card (README.md) so HF will host the dataset (ADR-0005), linking to petrodb.ocortez.com.
• ✅ Range sanity: both main and stage resolve URLs return accept-ranges: bytes.

Remaining — human only

• ⛔ HF_TOKEN: generate a fine-grained, write-scoped token (limited to sumpalabs/petrodb) in the HF web console, then add it as a GitHub Actions secret named HF_TOKEN on sumpalabs/petrodb. Cannot be done by an agent — token generation is web-console only and the secret value requires credentials.
• ⚠️ BASE_URL_MAIN / BASE_URL_STAGE: these vars already exist but hold the old Cloudflare URLs (https://petrodb.ocortez.com/, https://stage.petrodb.ocortez.com) — contrary to the "do not exist yet" note. They need to be updated to the HF resolve bases:
  • BASE_URL_MAIN = https://huggingface.co/datasets/sumpalabs/petrodb/resolve/main
  • BASE_URL_STAGE = https://huggingface.co/datasets/sumpalabs/petrodb/resolve/stage
  • Sequencing caution: changing these before the CI migration (CI uploads parquet data to Hugging Face on push (data path tracer bullet) #37) lands and before data is pushed would point the live build at an empty HF repo. Recommend doing this update as part of / immediately before CI uploads parquet data to Hugging Face on push (data path tracer bullet) #37, not now.
• ⬜ Final Range AC (curl … -H 'Range: bytes=0-99' … → 206 + Content-Range): best validated against a real .parquet after the first data upload (CI uploads parquet data to Hugging Face on push (data path tracer bullet) #37), since the README is a small non-LFS file.

Updated acceptance criteria

• sumpalabs/petrodb exists as a public HF dataset repo
• stage branch exists alongside main
• HF_TOKEN secret present (human)
• BASE_URL_MAIN/BASE_URL_STAGE updated to HF resolve bases (human; sequence with CI uploads parquet data to Hugging Face on push (data path tracer bullet) #37)
• Range test returns 206 + Content-Range against a real parquet (after CI uploads parquet data to Hugging Face on push (data path tracer bullet) #37 upload)

[oskrgab]

This was generated by AI during triage.

Correction — landing host is now sumpalabs.com/petrodb

petrodb is moving under the sumpalabs umbrella, and the Cloudflare-served landing moves from the petrodb.ocortez.com subdomain to the subpath https://sumpalabs.com/petrodb/ (apex SEO consolidation; served same-origin via a new umbrella router — #41, ADR-0006).

Impact on this issue: none to the HF prerequisites — HF_TOKEN and the data-side BASE_URL_MAIN/STAGE (the HF resolve bases) are unchanged. The only knock-on is the dataset card link: the thin hf/README.md card created here currently links to petrodb.ocortez.com; it gets repointed to https://sumpalabs.com/petrodb/ as part of #38. No action needed here.