genmodelfit 0.2.0__tar.gz → 0.3.0__tar.gz

{genmodelfit-0.2.0 → genmodelfit-0.3.0}/CHANGELOG.md

@@ -7,7 +7,27 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
-## [0.2.0] - Unreleased
+## [0.3.0] - 2026-10-21
+
+### Added
+
+- `genmodelfit download <model>` and `gmf.plan_download()` / `gmf.download()` (Issue #31): download all files of a
+  model's workflow, with the precision chosen like `recommend` (`--precision`, `--budget GB`), into a ComfyUI folder by
+  each file's template folder (`--comfyui-dir`) or the same layout elsewhere (`--output-dir`). `--list` shows the plan
+  without any network access. Before downloading it shows every file's license and URL, the total size and the free
+  disk and asks for consent (`--yes` to skip). sha256 is checked while writing (a mismatch deletes the file),
+  `.part` files resume with HTTP Range, files already there are skipped, and it needs the download + 1 GB free.
+  Gated files, uncensored models (unless `--content all|uncensored`) and unknown licenses (unless
+  `--include-unknown-license`) are refused; only https URLs on Hugging Face / GitHub hosts are followed (each
+  redirect is checked, and URLs that urlsplit and urllib3 would read as different hosts are refused before
+  connecting); nothing is written outside the destination. Existing files are hashed again right before they
+  are skipped, restarts against servers that ignore Range are capped, and a `.lock` file stops two downloads of
+  the same file. URL paths may contain spaces (they are percent-encoded as requests does); spaces, `%` and `@` are
+  refused only in the scheme and host, and refusals say whether the URL is malformed or the host is not allowed.
+  JSON: docs/schema.md "download".
+  モデルを落とす `download` を足した(同意・sha256・続きから・ComfyUI のフォルダ)。
+
+## [0.2.0] - 2026-10-20
 
 Fewer unknowns in the table and a clear meaning for `?` and `-` (Issue #30). The JSON output changes in a way that
 can break apps (below), so this is a minor release under 0.x semver (owner's decision).

{genmodelfit-0.2.0 → genmodelfit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: genmodelfit
-Version: 0.2.0
+Version: 0.3.0
 Summary: Right-size image / video / audio / 3D generation models to your PC (inspired by llmfit).
 Project-URL: Homepage, https://github.com/laxshmate/genmodelfit
 Project-URL: Issues, https://github.com/laxshmate/genmodelfit/issues
@@ -189,6 +189,7 @@ Python 3.10+. Windows and Linux. GPUs: NVIDIA (CUDA) in v0.1; other PCs are judg
 | `genmodelfit gate` | how many models can be auto-recommended, and why the rest are held / 自動でおすすめに出せる数と保留の理由 |
 | `genmodelfit update` | rebuild the model list from upstream / 一覧を上流から作り直す |
 | `genmodelfit update --from-release` | fetch the signed model list published by this project / 署名付きの配布の一覧を取り込む |
+| `genmodelfit download <model> [--comfyui-dir DIR] [--list]` | download all files of the model for this PC (precision chosen like `recommend`), after showing licenses, sizes and free disk and asking you; sha256-checked, resumable ([below](#download--モデルを落とす)) / この PC に合う精度でモデルのファイルを落とす(ライセンス・大きさ・空きを見せて同意を取る。sha256 で確かめ、続きから再開できる) |
 | `genmodelfit bench <template> --url URL` | measure VRAM / RAM / time on a running ComfyUI / 動いている ComfyUI で実測 |
 
 Common options / 共通の指定:
@@ -275,6 +276,91 @@ if st.expired:  # HEAD checks older than 30 days → auto-recommendations drop /
     print("run: genmodelfit update --from-release", st.expires_at, st.auto_count)
 ```
 
+## Download / モデルを落とす
+
+```
+genmodelfit download "Z-Image-Turbo" --list                 # what would be downloaded (no network, writes nothing)
+genmodelfit download "Z-Image-Turbo" --comfyui-dir C:\ComfyUI
+genmodelfit download image_z_image_turbo_int8 --output-dir D:\models --budget 15 --yes
+```
+
+- **Which files**: all files of one workflow. A model name (as in the tables) picks the workflow and precision like
+  `recommend`: the highest precision that runs on this PC without offloading. A workflow id is used as is.
+  `--precision int8` picks a precision; `--budget 15` (GB) caps the download (files already there are not counted).
+- **Where**: `--comfyui-dir` puts each file in the ComfyUI folder the template names
+  (`models/diffusion_models`, `text_encoders`, `vae`, `loras`, `checkpoints`, …; subfolders in the file name are kept).
+  `--output-dir` (default: genmodelfit's user data folder, `models`) uses the same layout, so it can be added to
+  ComfyUI's `extra_model_paths.yaml`.
+- **Consent first**: before anything is downloaded you see every file with its license and the license URL, licenses
+  that are not on the allowlist (commercial use without use restrictions; [docs/gate.md](https://github.com/laxshmate/genmodelfit/blob/main/docs/gate.md))
+  are marked, then the total size and the free disk, and you are asked `[y/N]`. `--yes` skips the question
+  (required with `--json`). Read the terms of each file before you use the model.
+- **Not downloaded**: gated files (genmodelfit never handles logins or tokens; request access on the model page and
+  download them yourself), uncensored models unless you pass `--content all` (or `uncensored`), files whose license is
+  unknown unless you pass `--include-unknown-license`, files without a sha256 or size in the list, hosts other than
+  Hugging Face / GitHub.
+- **Safety**: every file is checked with the sha256 in the list while it is written; a mismatch deletes it and fails.
+  A download goes to `<file>.part` first; after Ctrl-C or a network error run the same command again and it resumes
+  with an HTTP Range request (if the server ignores Range it starts over, at most 3 times). Files already there are
+  hashed again right before they are skipped; a different file with the same name is never overwritten. A
+  `<file>.lock` next to it stops two downloads of the same file at once (a lock left by a process that is gone is
+  cleaned up). It does not start unless the free disk is
+  the download + 1 GB. Nothing is written outside the destination: names with `..`, absolute paths, drive letters,
+  `\`, reserved Windows names (also as folder names), control / bidi characters, and symbolic links / junctions
+  that lead outside are refused.
+- **Network**: only the URLs in the list (checked anonymously with HEAD), https only. Every redirect must stay on
+  the hosts below; a URL that could be read as two different hosts (`\`, spaces, control characters, `%` or `@`
+  in the host, non-ASCII hosts) is refused before any connection, and the host is read the way requests / urllib3
+  read it. Allowed:
+  `huggingface.co` / `*.hf.co` (CDN, Xet) / `github.com` / `objects.githubusercontent.com` /
+  `release-assets.githubusercontent.com`. No `~/.netrc` credentials, no tokens, nothing about this PC (User-Agent and
+  Range only). Waits for `Retry-After` on 429 / 503.
+
+- **落とすもの**: 1 つのワークフローの全部のファイル。モデル名(表の Model)なら、`recommend` と同じく、この PC で
+  逃がさずに載る中で一番精度の高いワークフローを選びます。ID を指定すればそのまま。`--precision` で精度を、
+  `--budget`(GB)で落とす量の上限を決められます(既にあるファイルは数えません)。
+- **置き場所**: `--comfyui-dir` なら、テンプレートの置き場所(`models/diffusion_models`・`text_encoders`・`vae`・`loras`・
+  `checkpoints` など)に置きます。`--output-dir`(既定は genmodelfit のデータのフォルダの `models`)も同じ並びです。
+- **先に同意**: 落とす前に、ファイルごとのライセンスと原文の URL(許可リストに無いものは印付き)・合計の大きさ・空きを
+  出して `[y/N]` で尋ねます。`--yes` で省けます(`--json` で落とすときは必須)。使う前に各ファイルの条件を読んでください。
+- **落とさないもの**: gated(ログインや利用申請が要る。genmodelfit はログイン情報を扱いません)、無検閲のモデル
+  (`--content all` か `uncensored` を明示したときだけ)、ライセンス不明(`--include-unknown-license` のときだけ)、
+  一覧に sha256・大きさの無いもの、Hugging Face・GitHub 以外の取得先。
+- **安全**: 書きながら sha256 を計り、合わなければ消して失敗にします。途中は `<名前>.part` に書き、Ctrl-C や通信の失敗の
+  あとで同じコマンドを実行すると HTTP Range で続きから落とします(相手が Range に応じなければ最初から。3 回まで)。
+  既にあるファイルは飛ばす直前に sha256 を計り直し、同じ名前の別のファイルは上書きしません。同じファイルを
+  2 つの download が同時に書かないよう `<名前>.lock` を置きます(止まったプロセスの残りは片付けます)。空きが「落とす量 + 1 GB」に足りなければ
+  始めません。置き場所の外には書きません(`..`・絶対パス・ドライブ名・`\`・Windows の予約名・外へ出るリンクを拒みます)。
+- **通信**: 一覧の URL(匿名の HEAD で確かめたもの)だけを https で使い、転送先は Hugging Face(CDN・Xet を含む)と
+  GitHub の決めたホストだけ。2 通りのホストに読める URL(`\`・空白・制御文字・ホストの中の `%` や `@`・ASCII でない
+  ホスト)は、つなぐ前に拒みます。`~/.netrc` もトークンも使わず、PC の情報も送りません。
+
+Python:
+
+```python
+import genmodelfit as gmf
+
+plan = gmf.plan_download("Z-Image-Turbo", comfyui_dir=r"C:\ComfyUI")  # no network, writes nothing
+for f in plan.files:  # status: download / resume / present / conflict / unavailable
+    print(f.relpath, f.size_bytes, f.license, f.license_url, f.status)
+print(plan.blocked, plan.warnings, plan.download_bytes, plan.disk_free_bytes)
+
+
+def ask(plan) -> bool:  # show licenses, URLs, total and free disk; True to go on
+    ...
+
+
+def show(p):  # gmf.DownloadProgress
+    print(p.phase, p.name, p.done_bytes, p.total_bytes)
+
+
+result = gmf.download(plan, confirm=ask, progress=show)
+# or gmf.download("Z-Image-Turbo", yes=True, comfyui_dir=...) when the app already asked
+```
+
+The library prints nothing. `gmf.download` raises `gmf.DownloadRefused` (blocked, no consent), `gmf.DownloadError`
+(network, sha256 mismatch, disk) and lets `KeyboardInterrupt` through, keeping the `.part` file for the next call.
+
 ## Hardware / ハードウェアの検出
 
 - Only NVIDIA GPUs confirmed by `nvidia-smi` are used for judging (v0.1). A GPU is judged as **CPU** when no PyTorch
@@ -366,13 +452,15 @@ and held. See [docs/gate.md](https://github.com/laxshmate/genmodelfit/blob/main/
   main weight files to read their header — dtype and tensor shapes; no weights are downloaded).
 - `genmodelfit bench` talks only to the ComfyUI URL you give with `--url` (plus the official template files on
   GitHub when ComfyUI does not have them).
+- `genmodelfit download` (and `gmf.download()`) only GETs the model URLs in the list, over https, following
+  redirects only to Hugging Face / GitHub hosts; `--list` and `gmf.plan_download()` make no network access.
 - Hardware information (GPU name, VRAM, RAM, CPU, disk) is read locally with `nvidia-smi` and psutil and is
   **never sent**. Measurements from `bench` are saved only on your PC; they are shared only if you open a pull
   request yourself ([CONTRIBUTING.md](https://github.com/laxshmate/genmodelfit/blob/main/CONTRIBUTING.md)).
   Saved measurements hold no host name, user name, paths or GPU UUID.
 - No telemetry. No hardware information, measurements, prompts or other user content is ever sent anywhere.
   Tests replace the PC's details with marker strings and check that no request URL, header or body of `update`,
-  `update --from-release` or `bench` contains them.
+  `update --from-release`, `bench` or `download` contains them.
   Requests carry the User-Agent `genmodelfit/<version> (+https://github.com/laxshmate/genmodelfit)`, and never the
   credentials in your `~/.netrc` (proxy and certificate settings such as `HTTPS_PROXY` are still honored).
 
@@ -382,6 +470,8 @@ and held. See [docs/gate.md](https://github.com/laxshmate/genmodelfit/blob/main/
 - `update` は公開の情報を読むだけです(GitHub の ComfyUI テンプレート、Hugging Face Hub の API、モデルの URL への HEAD と、
   本体のファイルの先頭の見出し(dtype・テンソルの形)だけの Range 要求。モデル本体は落としません)。
 - `bench` は `--url` で指定した ComfyUI とだけ話します(ComfyUI に無い公式テンプレートは GitHub から取ります)。
+- `download` は一覧のモデルの URL へ https の GET を送るだけです(転送先は Hugging Face・GitHub の決めたホストだけ)。
+  `--list` と `gmf.plan_download()` は通信しません。
 - PC の情報(GPU の名前・VRAM・メモリ・CPU・空き)は `nvidia-smi` と psutil で手元で読むだけで、**送りません**。
   `bench` の実測は手元に保存するだけで、利用者が自分で Pull Request を出したときだけ共有されます
   (保存する実測に PC の名前・ユーザー名・パス・GPU の UUID は入りません)。

{genmodelfit-0.2.0 → genmodelfit-0.3.0}/README.md

@@ -149,6 +149,7 @@ Python 3.10+. Windows and Linux. GPUs: NVIDIA (CUDA) in v0.1; other PCs are judg
 | `genmodelfit gate` | how many models can be auto-recommended, and why the rest are held / 自動でおすすめに出せる数と保留の理由 |
 | `genmodelfit update` | rebuild the model list from upstream / 一覧を上流から作り直す |
 | `genmodelfit update --from-release` | fetch the signed model list published by this project / 署名付きの配布の一覧を取り込む |
+| `genmodelfit download <model> [--comfyui-dir DIR] [--list]` | download all files of the model for this PC (precision chosen like `recommend`), after showing licenses, sizes and free disk and asking you; sha256-checked, resumable ([below](#download--モデルを落とす)) / この PC に合う精度でモデルのファイルを落とす(ライセンス・大きさ・空きを見せて同意を取る。sha256 で確かめ、続きから再開できる) |
 | `genmodelfit bench <template> --url URL` | measure VRAM / RAM / time on a running ComfyUI / 動いている ComfyUI で実測 |
 
 Common options / 共通の指定:
@@ -235,6 +236,91 @@ if st.expired:  # HEAD checks older than 30 days → auto-recommendations drop /
     print("run: genmodelfit update --from-release", st.expires_at, st.auto_count)
 ```
 
+## Download / モデルを落とす
+
+```
+genmodelfit download "Z-Image-Turbo" --list                 # what would be downloaded (no network, writes nothing)
+genmodelfit download "Z-Image-Turbo" --comfyui-dir C:\ComfyUI
+genmodelfit download image_z_image_turbo_int8 --output-dir D:\models --budget 15 --yes
+```
+
+- **Which files**: all files of one workflow. A model name (as in the tables) picks the workflow and precision like
+  `recommend`: the highest precision that runs on this PC without offloading. A workflow id is used as is.
+  `--precision int8` picks a precision; `--budget 15` (GB) caps the download (files already there are not counted).
+- **Where**: `--comfyui-dir` puts each file in the ComfyUI folder the template names
+  (`models/diffusion_models`, `text_encoders`, `vae`, `loras`, `checkpoints`, …; subfolders in the file name are kept).
+  `--output-dir` (default: genmodelfit's user data folder, `models`) uses the same layout, so it can be added to
+  ComfyUI's `extra_model_paths.yaml`.
+- **Consent first**: before anything is downloaded you see every file with its license and the license URL, licenses
+  that are not on the allowlist (commercial use without use restrictions; [docs/gate.md](https://github.com/laxshmate/genmodelfit/blob/main/docs/gate.md))
+  are marked, then the total size and the free disk, and you are asked `[y/N]`. `--yes` skips the question
+  (required with `--json`). Read the terms of each file before you use the model.
+- **Not downloaded**: gated files (genmodelfit never handles logins or tokens; request access on the model page and
+  download them yourself), uncensored models unless you pass `--content all` (or `uncensored`), files whose license is
+  unknown unless you pass `--include-unknown-license`, files without a sha256 or size in the list, hosts other than
+  Hugging Face / GitHub.
+- **Safety**: every file is checked with the sha256 in the list while it is written; a mismatch deletes it and fails.
+  A download goes to `<file>.part` first; after Ctrl-C or a network error run the same command again and it resumes
+  with an HTTP Range request (if the server ignores Range it starts over, at most 3 times). Files already there are
+  hashed again right before they are skipped; a different file with the same name is never overwritten. A
+  `<file>.lock` next to it stops two downloads of the same file at once (a lock left by a process that is gone is
+  cleaned up). It does not start unless the free disk is
+  the download + 1 GB. Nothing is written outside the destination: names with `..`, absolute paths, drive letters,
+  `\`, reserved Windows names (also as folder names), control / bidi characters, and symbolic links / junctions
+  that lead outside are refused.
+- **Network**: only the URLs in the list (checked anonymously with HEAD), https only. Every redirect must stay on
+  the hosts below; a URL that could be read as two different hosts (`\`, spaces, control characters, `%` or `@`
+  in the host, non-ASCII hosts) is refused before any connection, and the host is read the way requests / urllib3
+  read it. Allowed:
+  `huggingface.co` / `*.hf.co` (CDN, Xet) / `github.com` / `objects.githubusercontent.com` /
+  `release-assets.githubusercontent.com`. No `~/.netrc` credentials, no tokens, nothing about this PC (User-Agent and
+  Range only). Waits for `Retry-After` on 429 / 503.
+
+- **落とすもの**: 1 つのワークフローの全部のファイル。モデル名(表の Model)なら、`recommend` と同じく、この PC で
+  逃がさずに載る中で一番精度の高いワークフローを選びます。ID を指定すればそのまま。`--precision` で精度を、
+  `--budget`(GB)で落とす量の上限を決められます(既にあるファイルは数えません)。
+- **置き場所**: `--comfyui-dir` なら、テンプレートの置き場所(`models/diffusion_models`・`text_encoders`・`vae`・`loras`・
+  `checkpoints` など)に置きます。`--output-dir`(既定は genmodelfit のデータのフォルダの `models`)も同じ並びです。
+- **先に同意**: 落とす前に、ファイルごとのライセンスと原文の URL(許可リストに無いものは印付き)・合計の大きさ・空きを
+  出して `[y/N]` で尋ねます。`--yes` で省けます(`--json` で落とすときは必須)。使う前に各ファイルの条件を読んでください。
+- **落とさないもの**: gated(ログインや利用申請が要る。genmodelfit はログイン情報を扱いません)、無検閲のモデル
+  (`--content all` か `uncensored` を明示したときだけ)、ライセンス不明(`--include-unknown-license` のときだけ)、
+  一覧に sha256・大きさの無いもの、Hugging Face・GitHub 以外の取得先。
+- **安全**: 書きながら sha256 を計り、合わなければ消して失敗にします。途中は `<名前>.part` に書き、Ctrl-C や通信の失敗の
+  あとで同じコマンドを実行すると HTTP Range で続きから落とします(相手が Range に応じなければ最初から。3 回まで)。
+  既にあるファイルは飛ばす直前に sha256 を計り直し、同じ名前の別のファイルは上書きしません。同じファイルを
+  2 つの download が同時に書かないよう `<名前>.lock` を置きます(止まったプロセスの残りは片付けます)。空きが「落とす量 + 1 GB」に足りなければ
+  始めません。置き場所の外には書きません(`..`・絶対パス・ドライブ名・`\`・Windows の予約名・外へ出るリンクを拒みます)。
+- **通信**: 一覧の URL(匿名の HEAD で確かめたもの)だけを https で使い、転送先は Hugging Face(CDN・Xet を含む)と
+  GitHub の決めたホストだけ。2 通りのホストに読める URL(`\`・空白・制御文字・ホストの中の `%` や `@`・ASCII でない
+  ホスト)は、つなぐ前に拒みます。`~/.netrc` もトークンも使わず、PC の情報も送りません。
+
+Python:
+
+```python
+import genmodelfit as gmf
+
+plan = gmf.plan_download("Z-Image-Turbo", comfyui_dir=r"C:\ComfyUI")  # no network, writes nothing
+for f in plan.files:  # status: download / resume / present / conflict / unavailable
+    print(f.relpath, f.size_bytes, f.license, f.license_url, f.status)
+print(plan.blocked, plan.warnings, plan.download_bytes, plan.disk_free_bytes)
+
+
+def ask(plan) -> bool:  # show licenses, URLs, total and free disk; True to go on
+    ...
+
+
+def show(p):  # gmf.DownloadProgress
+    print(p.phase, p.name, p.done_bytes, p.total_bytes)
+
+
+result = gmf.download(plan, confirm=ask, progress=show)
+# or gmf.download("Z-Image-Turbo", yes=True, comfyui_dir=...) when the app already asked
+```
+
+The library prints nothing. `gmf.download` raises `gmf.DownloadRefused` (blocked, no consent), `gmf.DownloadError`
+(network, sha256 mismatch, disk) and lets `KeyboardInterrupt` through, keeping the `.part` file for the next call.
+
 ## Hardware / ハードウェアの検出
 
 - Only NVIDIA GPUs confirmed by `nvidia-smi` are used for judging (v0.1). A GPU is judged as **CPU** when no PyTorch
@@ -326,13 +412,15 @@ and held. See [docs/gate.md](https://github.com/laxshmate/genmodelfit/blob/main/
   main weight files to read their header — dtype and tensor shapes; no weights are downloaded).
 - `genmodelfit bench` talks only to the ComfyUI URL you give with `--url` (plus the official template files on
   GitHub when ComfyUI does not have them).
+- `genmodelfit download` (and `gmf.download()`) only GETs the model URLs in the list, over https, following
+  redirects only to Hugging Face / GitHub hosts; `--list` and `gmf.plan_download()` make no network access.
 - Hardware information (GPU name, VRAM, RAM, CPU, disk) is read locally with `nvidia-smi` and psutil and is
   **never sent**. Measurements from `bench` are saved only on your PC; they are shared only if you open a pull
   request yourself ([CONTRIBUTING.md](https://github.com/laxshmate/genmodelfit/blob/main/CONTRIBUTING.md)).
   Saved measurements hold no host name, user name, paths or GPU UUID.
 - No telemetry. No hardware information, measurements, prompts or other user content is ever sent anywhere.
   Tests replace the PC's details with marker strings and check that no request URL, header or body of `update`,
-  `update --from-release` or `bench` contains them.
+  `update --from-release`, `bench` or `download` contains them.
   Requests carry the User-Agent `genmodelfit/<version> (+https://github.com/laxshmate/genmodelfit)`, and never the
   credentials in your `~/.netrc` (proxy and certificate settings such as `HTTPS_PROXY` are still honored).
 
@@ -342,6 +430,8 @@ and held. See [docs/gate.md](https://github.com/laxshmate/genmodelfit/blob/main/
 - `update` は公開の情報を読むだけです(GitHub の ComfyUI テンプレート、Hugging Face Hub の API、モデルの URL への HEAD と、
   本体のファイルの先頭の見出し(dtype・テンソルの形)だけの Range 要求。モデル本体は落としません)。
 - `bench` は `--url` で指定した ComfyUI とだけ話します(ComfyUI に無い公式テンプレートは GitHub から取ります)。
+- `download` は一覧のモデルの URL へ https の GET を送るだけです(転送先は Hugging Face・GitHub の決めたホストだけ)。
+  `--list` と `gmf.plan_download()` は通信しません。
 - PC の情報(GPU の名前・VRAM・メモリ・CPU・空き)は `nvidia-smi` と psutil で手元で読むだけで、**送りません**。
   `bench` の実測は手元に保存するだけで、利用者が自分で Pull Request を出したときだけ共有されます
   (保存する実測に PC の名前・ユーザー名・パス・GPU の UUID は入りません)。

{genmodelfit-0.2.0 → genmodelfit-0.3.0}/docs/schema.md

@@ -14,7 +14,7 @@ Every command with `--json` prints one object:
 | key | type | meaning |
 |---|---|---|
 | `genmodelfit` | str | tool version |
-| `command` | str | `system` / `recommend` / `fit` / `search` / `types` / `info` / `update` / `bench` / `gate` |
+| `command` | str | `system` / `recommend` / `fit` / `search` / `types` / `info` / `update` / `bench` / `gate` / `download` |
 | `system` | System | the PC that was judged (after `--vram` / `--ram` overrides). Not in `gate` / `update` / `bench` |
 | `database` | object | `origin` (`bundled` / `cache` / `path`), `generated_at`, `models`, `measurements` (counts). In `system` also `status` (DataStatus, below). Not in `bench` / `update --from-release` |
 | `error` | str | only on failure (exit code 1) |
@@ -31,6 +31,7 @@ The same as the SIDE EFFECTS of each command's `--help` and README "Privacy":
 | `update --inspect-only` | ranged GET of the headers of the main weight files on Hugging Face, GET of the ComfyUI template JSONs; nothing with `--offline` | the cache `db.json` (or `--output`), `file_headers.json` in the cache |
 | `update --from-release` | GET `db.json` and `db.json.sig` from this project's `data-latest` release | the cache `db.json` (or `--output`), `release_state.json` |
 | `bench` | only the ComfyUI `--url` (+ official template files on GitHub if ComfyUI lacks them) | a measurement JSON in the cache (or `--output`) |
+| `download` | GET of the model URLs in the list (https; redirects only to Hugging Face / GitHub hosts); none with `--list` | the files under the destination (`<file>.part` while downloading); nothing with `--list` |
 
 No telemetry; nothing about the PC or the user is sent. HTTP uses `fetch.make_session()`: User-Agent
 `genmodelfit/<version> (+https://github.com/laxshmate/genmodelfit)`, proxy / CA environment variables honored, `~/.netrc`
@@ -609,6 +610,79 @@ How bench fills Measurement / 測り方:
 - `--set` values: only numbers are written to `note`; for other values only the input name is kept.
 - The saved file is `{"measurements": [Measurement]}` and holds no paths, user names or prompts.
 
+## download
+
+`genmodelfit download <model> --json` prints the envelope (with `system` and `database`) plus the keys below.
+`--list --json` prints the plan only (`listed: true`, `result: null`; no network access, nothing written, exit 0 even
+when `plan.ok` is false). Downloading with `--json` needs `--yes`. On failure (exit 1, or 130 after Ctrl-C) `error` is
+set, `result` is null and `plan` is the plan (when it was made). A model that is not found or matches several
+models gives `error` (and `candidates`) without `plan`.
+Python: `gmf.plan_download(...)` returns `DownloadPlan` (`.to_dict()` is `plan`), `gmf.download(...)` returns
+`DownloadResult` (`.to_dict()` is `result`).
+
+| key | type | meaning |
+|---|---|---|
+| `listed` | bool | true for `--list` (nothing downloaded) |
+| `plan` | DownloadPlan | what is (or would be) downloaded |
+| `result` | DownloadResult \| null | what happened; null for `--list` and on failure |
+
+DownloadPlan:
+
+| key | type | meaning |
+|---|---|---|
+| `model_id`, `name` | str | the workflow (list entry) chosen |
+| `model_name` | str | the model name shown in the tables |
+| `modality`, `content`, `precision` | str / str / str \| null | as in ModelEntry |
+| `fit_level`, `run_mode_label`, `auto` | str / str / bool | the judgement on this PC (as in `recommend`) |
+| `chosen` | str | why this workflow was chosen (Japanese) |
+| `layout` | str | `comfyui` (`--comfyui-dir`: `root` is `<dir>/models`) / `output` (`--output-dir` or the default; same layout) |
+| `root` | str | absolute path of the folder files go into (`<root>/<directory>/<name>`) |
+| `files` | PlannedFile[] | one per file of the workflow |
+| `total_bytes` | int | sum of the file sizes |
+| `download_bytes` | int | still to download (minus files already there and `.part` bytes) |
+| `present_bytes` | int | files already there with the right sha256 |
+| `disk_free_bytes` | int \| null | free space at `root` (or its nearest existing parent) |
+| `disk_needed_bytes` | int | `download_bytes` + `margin_bytes` (0 when nothing to download) |
+| `margin_bytes` | int | 1 GiB |
+| `budget_bytes` | int \| null | `--budget` in bytes |
+| `blocked` | str[] | why it will not download (Japanese). Empty = can download |
+| `warnings` | str[] | things to know (licenses not on the allowlist, will not run on this PC, layout hint) |
+| `alternatives` | object[] | the other workflows considered: `id`, `precision`, `use`, `fit_level`, `memory_required_gb`, `size_bytes`, `auto` |
+| `license_url` | str \| null | the model's license page |
+| `ok` | bool | `blocked` is empty |
+
+PlannedFile:
+
+| key | type | meaning |
+|---|---|---|
+| `name` | str | file name in the list (may contain ComfyUI subfolders, `/`) |
+| `relpath` | str | path under `root` (`<directory>/<name>`; `other/<name>` when the list has no directory); "" when refused |
+| `dest` | str | absolute destination path; "" when refused |
+| `url`, `sha256`, `size_bytes`, `directory`, `role` | | from ModelFile |
+| `license`, `license_name` | str \| null | the license used for the check (gate's conservative reading; null = unknown) |
+| `license_url` | str \| null | where the license text is |
+| `license_note` | str \| null | why the license differs from the list's value, or why it could not be confirmed |
+| `license_allowed` | bool | on the license allowlist (gate default or `--license-allowlist`) |
+| `gated` | bool \| null | access request needed (also when the upstream of a component asks for it) |
+| `status` | str | `download` / `resume` (a `.part` exists) / `present` (already there, sha256 matches) / `conflict` (a different file has the name; never overwritten) / `unavailable` (see `reason`) |
+| `part_bytes` | int | size of the existing `.part` |
+| `remaining_bytes` | int | bytes still to download for this file |
+| `reason` | str \| null | why `conflict` / `unavailable` (Japanese) |
+| `verified` | bool | for `present`: the sha256 was measured while planning (false with `verify_existing=False`: size only). `download` always measures existing files again before skipping them |
+
+DownloadResult:
+
+| key | type | meaning |
+|---|---|---|
+| `model_id`, `root` | str | as in the plan |
+| `downloaded` | str[] | `relpath` of the files downloaded (sha256 checked) |
+| `resumed` | str[] | of those, continued from a `.part` with HTTP Range |
+| `restarted` | str[] | of those, started over because the server ignored Range |
+| `skipped` | str[] | already there; the sha256 was measured in this run and matched |
+| `bytes_downloaded` | int | bytes received in this run |
+| `seconds` | float | wall time |
+| `files` | object[] | `relpath`, `dest`, `sha256` of every file |
+
 ## Database file (`db.json`)
 
 ```json

{genmodelfit-0.2.0 → genmodelfit-0.3.0}/src/genmodelfit/__init__.py

@@ -12,6 +12,8 @@ Python から:
         fit.to_dict()  # `recommend --json` の models の 1 件と同じ形
     if gmf.data_status().expired:  # 同梱・取り込んだ一覧の HEAD の確認が古い(30 日)
         ...
+    plan = gmf.plan_download("Z-Image-Turbo", comfyui_dir="C:/ComfyUI")  # 落とさずに計画だけ(通信しない)
+    gmf.download(plan, confirm=ask_user, progress=show)  # 同意を取ってから落とす(sha256 で確かめる)
 """
 
 from __future__ import annotations
@@ -23,6 +25,14 @@ from datetime import datetime
 from ._version import __version__
 from .db import Database
 from .db import load as load_db
+from .downloader import (
+    DownloadError,
+    DownloadPlan,
+    DownloadProgress,
+    DownloadRefused,
+    DownloadResult,
+    plan_download,
+)
 from .estimate import estimate
 from .hardware import detect
 from .models import (
@@ -228,12 +238,36 @@ def info(model_id: str, *, db: Database | None = None) -> ModelEntry | None:
     return (db or load_db()).get(model_id)
 
 
+def download(
+    plan_or_model, *, progress=None, confirm=None, yes: bool = False, **plan_kwargs
+) -> DownloadResult:
+    """モデルを落とす(CLI の `download`)。何も表示しない。
+
+    plan_or_model: plan_download() の計画、またはモデルの名前・ID
+    (そのときは plan_kwargs を plan_download に渡す。
+    precision / budget_gb / output_dir / comfyui_dir / content / include_unknown_license など)。
+    confirm(plan) -> bool で利用者の同意を取る(ライセンス・利用条件の URL・大きさ・空きを見せる)。
+    confirm を渡さないときは yes=True で同意済みを示す(どちらも無ければ DownloadRefused)。
+    progress(DownloadProgress) で進み具合を受け取る。止める理由(gated・無検閲・ライセンス不明・空き不足・
+    置き場所の外・許していない取得先)は DownloadRefused / DownloadError(.plan に計画)。
+    中断(KeyboardInterrupt)は .part を残すので、もう一度呼ぶと続きから落とす。
+    """
+    from .downloader import download as _download
+
+    return _download(plan_or_model, progress=progress, confirm=confirm, yes=yes, **plan_kwargs)
+
+
 __all__ = [
     "CONTENT_LEVELS",
     "FIT_LEVELS",
     "MODALITIES",
     "DataStatus",
     "Database",
+    "DownloadError",
+    "DownloadPlan",
+    "DownloadProgress",
+    "DownloadRefused",
+    "DownloadResult",
     "Estimate",
     "Fit",
     "Measurement",
@@ -244,11 +278,13 @@ __all__ = [
     "__version__",
     "data_status",
     "detect",
+    "download",
     "estimate",
     "evaluate",
     "fit_list",
     "info",
     "load_db",
+    "plan_download",
     "recommend",
     "search",
     "system",

{genmodelfit-0.2.0 → genmodelfit-0.3.0}/src/genmodelfit/_version.py

@@ -4,4 +4,4 @@
 
 """版の番号(ここだけが正本。pyproject.toml は hatch がここから読む)。"""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"