fix: correct HuggingFace checkpoint filenames in code and installers#235
Merged
nikopueringer merged 1 commit intonikopueringer:mainfrom Apr 22, 2026
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this change?
The Python auto-download path in
CorridorKeyModule/backend.pyand 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:
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.batorInstall_CorridorKey_Linux_Mac.shinstead produces:The safetensors file IS available on HF; the curl URL is just
misspelled. Current installer users get silently downgraded to
the legacy
.pthformat.Ground truth from HuggingFace's model API
(
https://huggingface.co/api/models/nikopueringer/CorridorKey_v1.0):the repo hosts only
CorridorKey_v1.0.safetensorsandCorridorKey_v1.0.pth. The unversioned filenamesCorridorKey.safetensorsandCorridorKey.pthdo not exist.Five files fixed, all one-line string changes, six insertions
and six deletions:
CorridorKeyModule/backend.py:33-34:HF_CHECKPOINT_FILENAME_SAFETENSORSandHF_CHECKPOINT_FILENAMEget the
_v1.0suffix. The.pthconstant is also correctedby 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.safetensorsdownload.Install_CorridorKey_Linux_Mac.sh:79: curl URL for the.safetensorsdownload.README.md:78: doc claim that the auto-download saves the fileas
CorridorKey.safetensors, now correctlyCorridorKey_v1.0.safetensors.tests/test_backend.py:219: stale docstring.A few adjacent items were considered and deliberately left alone:
.pthURLs in the installer scripts are already correct(
CorridorKey_v1.0.pth).SAFETENSORS_PATH,PTH_PATH) keep their unversioned filenames on disk, so theinstaller's idempotent
if existskip check still hits forusers who ran the prior installer.
_discover_checkpointglobs*.safetensorsand*.pth, so the local stem does not affectruntime behavior.
CONTRIBUTING.md,docs/LLM_HANDOVER.md, and theconvert_pth_to_safetensors.pyusage docstring describe the file formats generically, not
specific HF paths.
How was it tested?
uv run ruff format --check: cleanuv run ruff check: cleanuv run pytest -q --tb=short -m "not gpu": 363 passed, 1skipped (MLX), 4 deselected (GPU). Same count as upstream.
constants via
https://huggingface.co/api/models/nikopueringer/CorridorKey_v1.0.uv run corridorkey --help: exits 0.Checklist
uv run pytestpassesuv run ruff checkpassesuv run ruff format --checkpasses