Skip to content

fix: correct HuggingFace checkpoint filenames in code and installers#235

Merged
nikopueringer merged 1 commit intonikopueringer:mainfrom
mountarreat:fix/hf-safetensors-filename
Apr 22, 2026
Merged

fix: correct HuggingFace checkpoint filenames in code and installers#235
nikopueringer merged 1 commit intonikopueringer:mainfrom
mountarreat:fix/hf-safetensors-filename

Conversation

@mountarreat
Copy link
Copy Markdown
Contributor

What does this change?

The Python auto-download path in CorridorKeyModule/backend.py
and the bundled Windows/Linux install scripts point at
HuggingFace URLs that do not match the filenames actually hosted
on the model repo.

On a fresh clone with an empty CorridorKeyModule/checkpoints/
directory, the Python auto-download path raises:

RuntimeError: Failed to download CorridorKey checkpoint from
https://huggingface.co/nikopueringer/CorridorKey_v1.0.
Check your network connection and try again.
Original error: 404 Client Error. Entry Not Found for url:
https://huggingface.co/nikopueringer/CorridorKey_v1.0/resolve/main/CorridorKey.pth.

Network is fine. The URL is wrong. The error message blames the
network, which sends users looking in the wrong place first.

Running the bundled Install_CorridorKey_Windows.bat or
Install_CorridorKey_Linux_Mac.sh instead produces:

Downloading CorridorKey.safetensors...
curl: (22) The requested URL returned error: 404
safetensors not available yet -- falling back to CorridorKey.pth...

The safetensors file IS available on HF; the curl URL is just
misspelled. Current installer users get silently downgraded to
the legacy .pth format.

Ground truth from HuggingFace's model API
(https://huggingface.co/api/models/nikopueringer/CorridorKey_v1.0):
the repo hosts only CorridorKey_v1.0.safetensors and
CorridorKey_v1.0.pth. The unversioned filenames
CorridorKey.safetensors and CorridorKey.pth do not exist.

Five files fixed, all one-line string changes, six insertions
and six deletions:

  • CorridorKeyModule/backend.py:33-34:
    HF_CHECKPOINT_FILENAME_SAFETENSORS and HF_CHECKPOINT_FILENAME
    get the _v1.0 suffix. The .pth constant is also corrected
    by the open PR perf: unblock benchmark harness, add setup docs and perf PR template #221; the two changes are content-identical, so
    the PRs merge cleanly either way around.
  • Install_CorridorKey_Windows.bat:64: curl URL for the
    .safetensors download.
  • Install_CorridorKey_Linux_Mac.sh:79: curl URL for the
    .safetensors download.
  • README.md:78: doc claim that the auto-download saves the file
    as CorridorKey.safetensors, now correctly
    CorridorKey_v1.0.safetensors.
  • tests/test_backend.py:219: stale docstring.

A few adjacent items were considered and deliberately left alone:

  • The .pth URLs in the installer scripts are already correct
    (CorridorKey_v1.0.pth).
  • The installer scripts' local save paths (SAFETENSORS_PATH,
    PTH_PATH) keep their unversioned filenames on disk, so the
    installer's idempotent if exist skip check still hits for
    users who ran the prior installer. _discover_checkpoint globs
    *.safetensors and *.pth, so the local stem does not affect
    runtime behavior.
  • Prose references to the filenames in CONTRIBUTING.md,
    docs/LLM_HANDOVER.md, and the convert_pth_to_safetensors.py
    usage docstring describe the file formats generically, not
    specific HF paths.

How was it tested?

  • uv run ruff format --check: clean
  • uv run ruff check: clean
  • uv run pytest -q --tb=short -m "not gpu": 363 passed, 1
    skipped (MLX), 4 deselected (GPU). Same count as upstream.
  • HuggingFace API filename listing cross-checked against the
    constants via
    https://huggingface.co/api/models/nikopueringer/CorridorKey_v1.0.
  • uv run corridorkey --help: exits 0.

Checklist

  • uv run pytest passes
  • uv run ruff check passes
  • uv run ruff format --check passes

The auto-download path in `CorridorKeyModule/backend.py` and the
bundled installer scripts point at HuggingFace URLs that do not
match the filenames actually hosted on the model repo. New users
who rely on the Python auto-download see

    RuntimeError: Failed to download CorridorKey checkpoint from
    https://huggingface.co/nikopueringer/CorridorKey_v1.0.
    Check your network connection and try again.
    Original error: 404 Client Error. Entry Not Found for url:
    https://huggingface.co/nikopueringer/CorridorKey_v1.0/resolve/main/CorridorKey.pth.

Users running the `.bat`/`.sh` installers see a misleading

    safetensors not available yet -- falling back to CorridorKey.pth...

(the safetensors file IS available; the URL is just misspelled),
then get silently downgraded to the legacy `.pth` format.

Verified via HuggingFace's model API
(`https://huggingface.co/api/models/nikopueringer/CorridorKey_v1.0`):
the repo hosts only `CorridorKey_v1.0.safetensors` and
`CorridorKey_v1.0.pth`. The unversioned names `CorridorKey.safetensors`
and `CorridorKey.pth` do not exist.

Files fixed (all one-line string changes):

- `CorridorKeyModule/backend.py:33`: `HF_CHECKPOINT_FILENAME_SAFETENSORS`
  gets the `_v1.0` suffix.
- `CorridorKeyModule/backend.py:34`: `HF_CHECKPOINT_FILENAME` gets the
  `_v1.0` suffix. The second line is also corrected by the open
  PR nikopueringer#221; the two changes are content-identical so there is no
  merge conflict either way around.
- `Install_CorridorKey_Windows.bat:64`: curl URL for the `.safetensors`
  download.
- `Install_CorridorKey_Linux_Mac.sh:79`: curl URL for the `.safetensors`
  download.
- `README.md:78`: doc claim that the auto-download saves the file as
  `CorridorKey.safetensors`, now correctly
  `CorridorKey_v1.0.safetensors`.
- `tests/test_backend.py:219`: docstring referencing the stale local
  filename.

Intentionally not changed:

- The `.pth` URLs in the installer scripts are already correct
  (`CorridorKey_v1.0.pth`).
- The installer scripts' local save paths (`SAFETENSORS_PATH`,
  `PTH_PATH`) keep their unversioned filenames on disk. They only
  matter for the installer's idempotent `if exist` skip check, and
  renaming them would trigger a re-download on machines that ran
  the prior installer. `_discover_checkpoint` globs `*.safetensors`
  and `*.pth`, so the local stem does not affect runtime behavior.
- Descriptive prose in `CONTRIBUTING.md`, `docs/LLM_HANDOVER.md`,
  and the `scripts/convert_pth_to_safetensors.py` usage docstring
  refers to the `CorridorKey.safetensors` and `CorridorKey.pth`
  format names generically, not as HF paths. Left alone.

Verified locally on Windows with Python 3.13.11:
- `uv run ruff format --check`: clean
- `uv run ruff check`: clean
- `uv run pytest -q --tb=short -m "not gpu"`: 363 passed, 1 skipped
  (MLX), 4 deselected (GPU), 2 warnings. Same pass count as
  upstream. Both warnings are pre-existing (`env` config warning
  and a torch autocast warning on a no-CUDA machine); neither is
  introduced here.
@mountarreat mountarreat marked this pull request as ready for review April 18, 2026 03:17
@nikopueringer nikopueringer merged commit 422f999 into nikopueringer:main Apr 22, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants