genmodelfit 0.2.0__tar.gz → 0.4.0__tar.gz

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

@@ -7,7 +7,105 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
-## [0.2.0] - Unreleased
+## [0.4.0] - 2026-10-21
+
+### Added
+
+- `genmodelfit diff OLD NEW [--json]` and `gmf.diff_db(old, new)` (Issue #19): what changed between two lists —
+  added / removed models, license changes (changes toward the permissive side are marked), auto-recommendation
+  changes under one policy for both lists (HEAD age ignored), size / precision changes beyond a threshold, newly
+  uncensored models, failed HEAD checks, 401 repos and changed `sources` numbers. JSON: docs/schema.md "diff".
+  2 つの一覧の違いをまとめる `diff` を足した。
+- Weekly data refresh (Issue #19): `.github/workflows/weekly-data.yml` rebuilds the list every Monday with
+  `python -m genmodelfit.weekly` (caches kept between runs), checks it (auto count, the HEAD expiry must be more than
+  7 days away, ruff and pytest with the new list) and opens a pull request `automated/weekly-data` whose body is the
+  diff. It is never merged automatically; publishing stays in data.yml after the owner merges. A partial rebuild
+  fails unless run by hand with `allow_partial` and only HF repos failed transiently. docs/release.md.
+  毎週、作り直した一覧を PR にする(自動ではマージしない。配るのはマージした一覧だけ)。
+
+- Measurement submissions from users (Issue #34). `genmodelfit bench … --submission PATH` and
+  `genmodelfit contrib make --from <bench result>` write a submission file (`contrib_schema` 1:
+  `data/contrib/<gpu>/<date>-<sha8>.json`) with the GPU name / VRAM / generation / compute capability / driver, the ComfyUI
+  version, the OS family, RAM rounded to GiB and the results — never host / user names, paths, GPU UUID, PCI address,
+  IP, CPU name or exact times (the note is scrubbed). genmodelfit sends nothing; users open the pull request themselves.
+  `contrib show` prints exactly what will be shared with a privacy checklist; `contrib validate` checks schema, value
+  ranges, privacy patterns, GPU name / generation consistency, file name and duplicates (exit 0 / 1 / 2);
+  `.github/workflows/contrib.yml` runs it on pull requests touching `data/contrib/**` (read-only, the tool installed
+  from the base commit, results in the job summary). `contrib aggregate` groups submissions by model, settings and GPU
+  with median / MAD outlier removal into the new bundled `measurements_community.json` (empty for now), and
+  `--report` re-runs the calibration and flags errors above a threshold (default 25%, exit 3 with `--fail-on-breach`)
+  for the weekly job of #19.
+- `Estimate.basis_detail` (`measured` > `measured_community` > `calibrated` > `estimated`); `basis` stays
+  `measured` / `estimated`. Community measurements are used only when at least two consistent submissions agree (and
+  no OOM), rank after the maintainer's measurements at the same settings, and can only raise the needs (never lower
+  VRAM / RAM, never improve a level, never raise the score: `basis` points 0 like estimates). `validate` marks
+  implausible values (more than 40% from the formula, below the weights with `offload: none`), values that would raise
+  the estimate by more than 15% or change a level at common VRAM / RAM sizes, unknown models and unknown GPUs as
+  review-required; approval is per submission (`--allow-review <sha8>` or the maintainers' `data/contrib/REVIEWED`).
+  Unapproved community rows raise needs by at most 15% and are ignored where they would change the level.
+  `aggregate --report` lists the level changes caused by community data.
+- `torch_reserved` measurements (bench; without the CUDA context) are now lower bounds: below the formula they no
+  longer lower the estimate (the bundled RTX 3070 rows for BiRefNet and MoGe now use the formula value).
+  `Measurement.origin` / `n_submissions` / `consistent` (optional fields).
+- `python -m genmodelfit.calibrate` also writes the check rows (measurements in another `vram_metric`, such as the
+  RTX 3070 runs) to `calibration.json` (`check`) and the accuracy table; LOO rows carry `gpu_name` and `origin`.
+  Coefficients are unchanged.
+  利用者の実測の提出(作る・見る・検査・まとめ・毎週の精度の点検)と、根拠の段階 `basis_detail` を足した。
+
+### Changed
+
+- Hugging Face selection (Issue #19): the 1,000 all-time floor for models found only by the trending / likes30d
+  searches now needs a trendingScore of at least 0.5 and at least 100 downloads in the last 30 days (otherwise
+  10,000 applies); repo names containing `merge` / `mergekit` are skipped like the tag; quantized / format copies
+  are recognized by name (`-GGUF`, `-Q8_0`, `_K_M`, `-fp8`, `-nf4`, `-int8`, `_diffusers`, `-Quantized`, …) and
+  only the most downloaded is kept; uncensored models also need 100 downloads in the last 30 days.
+  HF の選び方を締めた(伸びている条件・名前の merge・量子化の写し・無検閲は直近 30 日も使われているもの)。
+- The bundled list was rebuilt with these rules (326 entries: HF 48, uncensored 26; auto 99 unchanged).
+  Added: 6 uncensored HF models that meet the rules and the new official template `video_fasth3_ominiref_r2v`;
+  removed: `hf:0xSojalSec/Qwen-Image-2.1-Uncensored-GGUF` (a quantized copy of
+  `hf:abenzerps/Qwen-Image-2.1-Uncensored-Quantized`) and `hf:TheImposterImposters/lustifySDXLNSFW_v20-inpainting`
+  (the same weights, by sha256, as the more downloaded `hf:andro-flock/LUSTIFY-SDXL-NSFW-checkpoint-v2-0-INPAINTING`).
+  同梱の一覧を新しい規則で作り直した。
+- Weekly PR body: every upstream string is HTML-escaped and Markdown-neutralized (`weekly.md`), mentions are
+  broken, truncation keeps `<details>` balanced; a scheduled run fails when more than 5 entries become uncensored
+  or when HF / template / uncensored / auto counts fall below half.
+
+### Fixed
+
+- Exclusion (safety): uncensored models whose ID, name, tags or card mention a dataset known to include a category
+  of sexual content involving minors (`DATASET_TERMS`: e621) are excluded, even when that is not their purpose
+  (owner decision, 2026-10-21; `hf:hearmeneigh/sd21-e621-rising-v2` and `hf:Laxhar/noobai-XL-1.1` — its card says it was trained on the full Danbooru and e621 datasets — removed from the bundled list).
+  学習データに未成年の性的表現の分類を含む画像の集まり(e621)を使う無検閲のモデルは外す(安全側)。
+
+- When a Hugging Face repo was renamed, `update` applied the license-source table with the new name from the API
+  while re-applying it uses the name in the file URL, so the two disagreed (`license_path`). Both now use the URL's
+  name. Found by the first weekly rebuild (Comfy-Org/flux2-klein-9B → vae-text-encorder-for-flux-klein-9b).
+  リポジトリの名前が変わったとき、出どころの表をファイルの URL の名前で当てるようにした。
+- Tests no longer pin numbers of the bundled list (uncensored count, HEAD check date) so that the weekly rebuild
+  can pass them.
+
+
+## [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.4.0}/CONTRIBUTING.md

@@ -3,13 +3,15 @@
 genmodelfit の見積もりは、実際の PC で測った値(実測)があるとそれを優先します。いろいろな GPU の実測が
 集まるほど、見積もりが正確になります。`genmodelfit bench` で測った結果を Pull Request で送ってください。
 
-**English summary:** Run `genmodelfit bench <template> --url http://127.0.0.1:<port>` against your own ComfyUI,
-check the JSON it writes, then open a pull request that adds the record to
-`src/genmodelfit/data/measurements.json`. Required fields: `model_id`, `gpu_name`, `gpu_vram_gb`, `peak_vram_gb`,
-`settings`, `seconds`, `driver`, `comfyui_version`, `offload`, `outcome`, `standard`, `source`, `date`. Do not include
-paths, user names, host names or prompts. One model per PR is easiest to review. Out-of-memory runs are welcome too,
-but they must keep `outcome: "oom"` (bench prints them and does not save them unless you pass `--save-failed` or
-`--output`).
+**English summary:** Run `genmodelfit bench <template> --url http://127.0.0.1:<port> --submission data/contrib/`
+against your own ComfyUI (in a clone of your fork). It writes a submission file
+`data/contrib/<gpu>/<date>-<sha8>.json` (`contrib_schema` 1: GPU name / VRAM / generation / driver, ComfyUI version,
+OS family, RAM rounded to GiB, the model, settings and results). Check exactly what will be shared with
+`genmodelfit contrib show <file>` (it also runs a privacy checklist), then open a pull request that adds only that file.
+**genmodelfit itself never sends anything**; sharing happens only through the pull request you open. The file never
+contains your host name, user name, paths, GPU UUID, PCI address, IP, CPU name or exact time. CI runs
+`genmodelfit contrib validate` on the pull request. Out-of-memory runs are welcome too (`outcome: "oom"`).
+Already have a saved bench result? `genmodelfit contrib make --from <file>` converts it.
 
 **License of contributions:** genmodelfit (code and bundled data) is under MPL-2.0. By opening a pull request you
 agree that your contribution (code, measurements or other data) is licensed under MPL-2.0 like the rest of the
@@ -77,44 +79,79 @@ genmodelfit bench 3d_hunyuan3d_image_to_model --url http://127.0.0.1:8188 --step
 `--output パス` を付けます。「標準でない」結果も同じで、`--save-nonstandard` か `--output` で保存できます。
 見積もりは `outcome` が `ok` で `standard` が `true` の実測だけを使います。
 
-## 2. 確かめる
+## 2. 提出用の JSON を作る
 
-bench は、最後まで動いた標準の結果を `<キャッシュ>/measurements/<モデル>_<GPU>_<日時>.json` に保存し、
-保存先を表示します(`--output` で場所を変えられます)。キャッシュに置いた実測は、その PC の `genmodelfit` の見積もりにすぐ使われます。
+自分のフォーク(GitHub の Fork)を手元に clone し、そのフォルダで bench に `--submission` を付けて測ります。
 
-ファイルを開いて、次を確かめてください。
+```powershell
+git clone https://github.com/<あなたの名前>/genmodelfit
+cd genmodelfit
+genmodelfit bench image_sdxl_simple --url http://127.0.0.1:8188 --resolution 832x832 --submission data/contrib/
+```
+
+- `--submission` にフォルダを渡すと、`data/contrib/<GPU>/<日付>-<sha8>.json` という名前で書きます
+  (例 `data/contrib/rtx-3070/2026-10-21-1a2b3c4d.json`。`sha8` は中身の sha256 の先頭 8 桁)。ファイル名を渡せばその名前で書きます
+- 前に測って保存した結果(`<キャッシュ>/measurements/….json` や `--output` のファイル)からも作れます:
+  `genmodelfit contrib make --from <bench の結果> --output data/contrib/`
+  (ComfyUI が別の PC だったときは `--no-pc-info` を付けると、この PC の OS・メモリ・GPU の世代を入れません)
+- 失敗(OOM)の結果も、そのまま出してください。標準でない条件の結果は記録として受け付けますが、まとめには使いません
+
+### 入るもの・入らないもの
+
+| 入るもの | 例 |
+|---|---|
+| GPU の名前・VRAM の総量・世代・compute capability・ドライバの版 | `NVIDIA GeForce RTX 3070`, `8.0`, `ampere`, `8.6`, `566.03` |
+| ComfyUI の版、OS の種類(版・ビルドは入れない)、メインメモリ(GiB の整数に丸める) | `0.40.0`, `windows`, `32` |
+| モデル ID・設定・結果・最大 VRAM / メモリ・時間・載せ方・測り方 | `image_sdxl_simple`, `832x832`, `ok`, `6.9` … |
+| 日付(UTC の日付だけ) | `2026-10-21` |
+| メモ(note。bench が書いた測り方の説明) | パス・URL・PC 名・ユーザ名・メール・UUID・IP・時刻らしい文字を含む文は、文ごと消す |
+
+**入らないもの**: PC の名前、ユーザー名、フォルダのパス、GPU の UUID、PCI の差し場所、シリアル番号、IP / MAC アドレス、
+CPU の名前、時刻、bench の `--source` に書いた文、プロンプト。決まった項目以外は CI の検査で断ります。
+ただし自動の点検は文字の形を見るだけで、note に普通の言葉で書いた名前(「山田太郎の PC で測った」など)や、base64 などで
+書き換えたパスは見分けられません(下の 3 で自分で読んでください)。
+
+## 3. 中身を確かめる(送る前に必ず)
+
+```powershell
+genmodelfit contrib show data/contrib/rtx-3070/2026-10-21-1a2b3c4d.json
+```
+
+ファイルの中身をすべて読める形で出し、個人の情報の点検(パス・PC 名・ユーザ名・UUID・PCI・IP・URL・メール・時刻・
+知らない項目が無いか。この PC の名前・ユーザ名が入っていないかも見ます)の結果を `[ok]` / `[NG]` で出します。
+
+- `[NG]` があれば、直してから出してください(手で書き換えたら、名前の `sha8` が変わるので `contrib validate` が
+  正しい名前を教えます)
+- **note(メモ)は自分で読んでください**。自動の点検は文の意味までは分かりません。気になる文は消して構いません
+- `genmodelfit contrib validate data/contrib` で、CI と同じ検査を手元で動かせます
+- 「要確認」(review)は、式の見積もりから 40% より外れた値・全部 GPU に載せたのに重みより小さい値・見積もりを 15% より
+  上げる値・よくある VRAM で段階を変える値・一覧に無いモデル・知らない GPU です。誤りではありませんが、PR を見る人が
+  確かめるまで受け付けません(測り直すか、PR の説明に事情を書いてください)。確かめた提出は、作者が
+  `data/contrib/REVIEWED` に sha8 と理由を書きます(提出の PR ではこのファイルを変えないでください。CI が失敗にします)
+
+## 4. 送る(Pull Request)
 
-- **個人の情報が入っていないこと**: フォルダのパス、ユーザー名、PC の名前、プロンプトの文を入れないでください。
-  bench はこれらを書きませんが、`--source` や `--note` に自分で書いたものは確かめてください
-- `gpu_name` と `driver` が自分の PC と合っていること
-- `settings` が測りたかった設定になっていること
+1. 足すのは `data/contrib/<GPU>/<日付>-<sha8>.json` のファイルだけにします(ほかのファイルは変えない。コードの変更は別の PR に)
+2. コミットして自分のフォークに push し、Pull Request を作ります。説明に、ComfyUI の起動オプション
+   (`--lowvram` など、変えたものだけ)を書いてもらえると助かります。個人名やメールアドレスは不要です
+3. CI(`Contrib` のワークフロー)が `genmodelfit contrib validate` で形・値の範囲・個人の情報・重複・ファイル名を検査し、
+   結果をジョブのまとめ(Summary)に出します。検査は、PR の向き先(main)の genmodelfit で動きます
 
-## 3. 送る
+**genmodelfit は何も送りません**。共有されるのは、あなたが自分の GitHub で出した Pull Request の中身だけです
+(自動で PR を作る機能はありません)。マージされると、提出は MPL-2.0 で公開されます(下の「ライセンス」)。
 
-1. このリポジトリをフォークして、ブランチを作ります
-2. 保存された JSON の `measurements` の中身を、`src/genmodelfit/data/measurements.json` の `measurements` の
-   最後に足します(書き方は既存の行にそろえてください)
-3. `source` に、測った環境が分かる短い説明を書きます(例: `"genmodelfit bench, RTX 4060 8GB, ComfyUI portable"`)。
-   個人名やメールアドレスは不要です
-4. `pytest -q` が通ることを確かめて、Pull Request を作ります。説明に、PC の構成(GPU・メモリ・OS)と、
-   ComfyUI の起動オプション(`--lowvram` など、変えたものだけ)を書いてください
+### 受け付けたあと
 
-### 必要な項目
+- 作者が `genmodelfit contrib aggregate --output src/genmodelfit/data/measurements_community.json` で、同じモデル・設定・GPU の
+  提出をまとめます(中央値と MAD で外れ値を除く)。同じ構成の提出が **2 件以上そろい、OOM が無いと**、その構成の見積もりの
+  根拠が `measured_community`(ほかの利用者の実測)になります。1 件だけの提出は、もう 1 件そろうまで見積もりには使いません。
+  ほかの利用者の実測は、必要量を**上げる向きにだけ**使います(見積もりより小さい値では、段階も点数も変わりません)
+- 毎週の点検(`contrib aggregate --report`)が、校正の誤差の表を作り直します(docs/accuracy.md)
 
-| 項目 | 必須 | 例 |
-|---|---|---|
-| `model_id` | ○ | `image_z_image_turbo_int8`(一覧の ID) |
-| `gpu_name`, `gpu_vram_gb` | ○ | `NVIDIA GeForce RTX 3070`, `8.0` |
-| `peak_vram_gb` | ○ | `5.43` |
-| `settings` | ○ | `{"width": 768, "height": 768, "steps": 6}` |
-| `seconds` | ○ | `41.2` |
-| `driver`, `comfyui_version` | ○ | `566.03`, `0.40.0` |
-| `offload` | ○ | `dynamic` |
-| `outcome`, `standard` | ○ | `ok`, `true`(OOM なら `oom` のまま送る) |
-| `source`, `date` | ○ | 上の例、`2026-10-20` |
-| `peak_ram_gb`, `note` | | bench が書いたものをそのまま |
+### 作者の実測(measurements.json)
 
-形の正本は `src/genmodelfit/models.py` の `Measurement` で、説明は [docs/schema.md](docs/schema.md) にあります。
+同梱の `src/genmodelfit/data/measurements.json` は作者が測った実測です。項目は docs/schema.md の「Measurement」、
+提出の形は「contrib」にあります。利用者の実測は data/contrib に出してください(measurements.json は直接変えない)。
 
 ## そのほかの変更
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: genmodelfit
-Version: 0.2.0
+Version: 0.4.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
@@ -309,7 +395,8 @@ Measured values win. Models whose download size is unknown are not judged (shown
 
 ## Data sources / データ源
 
-The bundled list has 323 entries (image 161, video 114, TTS 20, music 15, 3D 10, SFX 3) that make 204 models.
+The bundled list has 326 entries (image 163, video 115, TTS 20, music 15, 3D 10, SFX 3) that make 207 models
+(2026-10-21; refreshed weekly, see "Maintenance").
 Like llmfit, Hugging Face models are included only with at least 10,000 all-time downloads (1,000 for trending
 ones), and merges and test stubs are skipped ([docs/sources.md](https://github.com/laxshmate/genmodelfit/blob/main/docs/sources.md)).
 llmfit と同じく、Hugging Face のモデルは全期間のダウンロード数が 10,000 以上のもの(伸びているものは 1,000 以上)だけを入れます。
@@ -349,12 +436,55 @@ upstream, not the uploader's label) is on a commercial-use allowlist (apache-2.0
 replaceable), nothing is gated, an official ComfyUI workflow without custom nodes, the ComfyUI version is
 supported, every download URL answered an anonymous HEAD within the last 30 days, sha256 is known, the size is
 known, and the content is `sfw`. Otherwise it is held with machine-readable reasons (`held_reasons` in JSON, e.g. `license`; the table's Auto column shows the first one).
-In the bundled list 83 of 323 entries are auto. When a license cannot be verified it is treated as unknown
+In the bundled list 99 of 326 entries are auto (2026-10-21). When a license cannot be verified it is treated as unknown
 and held. See [docs/gate.md](https://github.com/laxshmate/genmodelfit/blob/main/docs/gate.md).
 
 すべての条件を満たすものだけを自動でおすすめに出し、残りは理由付きで保留にします。ライセンスが確かめられない
 ものは「不明」として保留にします。アプリは使う ComfyUI の版を `--comfyui-version` で渡してください。
 
+## Maintenance / 一覧の保守
+
+Like llmfit, the list is rebuilt every week and published only after a person has reviewed it:
+
+1. Every Monday (03:00 UTC) `.github/workflows/weekly-data.yml` rebuilds the list from upstream
+   (`python -m genmodelfit.weekly`: templates, Hugging Face, HEAD checks, file headers; caches are kept between
+   runs), checks it (schema, auto count, the 30-day HEAD expiry must be more than 7 days away), runs ruff and
+   pytest with the new list, and opens or updates the pull request `automated/weekly-data` (labels `automated`,
+   `data-update`). The body is made by `genmodelfit diff` (added / removed models, license changes — the
+   ones toward the permissive side are marked —, auto-recommendation changes, failed HEAD checks).
+   It is never merged automatically.
+2. The owner reviews and merges it.
+3. On merge, `.github/workflows/data.yml` signs main's `db.json` and replaces the `data-latest` release.
+4. Apps take it with `genmodelfit update --from-release` (signature checked).
+
+```powershell
+genmodelfit diff old_db.json new_db.json            # what changed between two lists (--json for tools)
+python -m genmodelfit.weekly --dry-run --out weekly-out   # the same pipeline locally (writes only weekly-out)
+```
+
+毎週、上流から作り直した一覧を自動で PR にし(自動ではマージしない)、作者が見てマージしたものだけを
+署名して配ります。PR で確かめることは [docs/release.md](https://github.com/laxshmate/genmodelfit/blob/main/docs/release.md)
+「毎週の一覧の更新」。
+
+## Contributing measurements / 実測を送る
+
+Measured runs on more GPUs make the estimates better. In a clone of your fork:
+
+```powershell
+genmodelfit bench image_sdxl_simple --url http://127.0.0.1:8188 --resolution 832x832 --submission data/contrib/
+genmodelfit contrib show data/contrib/rtx-3070/2026-10-21-1a2b3c4d.json   # exactly what will be shared + privacy checklist
+```
+
+Then open a pull request that adds only that file. **genmodelfit sends nothing**; the file holds the GPU name / VRAM /
+generation / driver, ComfyUI version, OS family, RAM rounded to GiB and the results — never host or user names, paths,
+GPU UUID, PCI address, IP or exact times (the checks are pattern based, so read the note yourself). CI checks it with
+`genmodelfit contrib validate`. Once two or more consistent submissions exist for the same model, settings and GPU,
+estimates for that setup become `basis_detail: "measured_community"`; community values can only raise the estimated
+needs, never lower them. Steps: [CONTRIBUTING.md](https://github.com/laxshmate/genmodelfit/blob/main/CONTRIBUTING.md).
+
+自分のフォークで `bench --submission data/contrib/` を付けて測り、`contrib show` で中身を確かめてから、そのファイルだけを
+Pull Request で出してください。genmodelfit は何も送りません(PC の名前・ユーザー名・パス・GPU の UUID などは入りません)。
+
 ## Privacy / 送るもの・送らないもの
 
 - `recommend`, `fit`, `search`, `info`, `system`, `types`, `gate` and the Python API (`gmf.recommend()`,
@@ -366,13 +496,16 @@ 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.
+  Saved measurements hold no host name, user name, paths or GPU UUID. Submission files (`bench --submission`,
+  `contrib make`) are written locally only; `genmodelfit contrib` never touches the network.
 - 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,9 +515,12 @@ 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 は入りません)。
+  (保存する実測に PC の名前・ユーザー名・パス・GPU の UUID は入りません)。提出用の JSON(`bench --submission`・`contrib make`)も
+  手元に書くだけで、`genmodelfit contrib` は通信しません。
 - 利用状況の送信(テレメトリ)はありません。PC の情報・実測・プロンプトなどを送ることはありません。User-Agent は
   `genmodelfit/<版>` で、`~/.netrc` の資格情報は付けません(プロキシ・証明書の設定は使います)。