[cross-cutting] Unify cache-control flags (--rebuild / --use-cache / --cache-dir) across build, perf, eval

[xieofxie]

Summary

Commands that build a model from HF (build, perf, eval, and future model-loaders like run/serve) all flow through WinMLAutoModel.from_pretrained / from_onnx, which share the same cache kwargs:

cache_dir: str | Path | None = None
use_cache: bool = True
force_rebuild: bool = False

But each command exposes (or hides) these inconsistently — different flag names, different defaults, and eval exposes nothing. We should unify them behind a shared decorator in utils/cli.py (the same pattern already used for build_pipeline_extra_kwargs() and overwrite_option()).

Current state

Command	Cache opt-in/out	Force recompute	cache-dir	Default
build	--use-cache/--no-use-cache (mutually exclusive with -o)	--rebuild/--no-rebuild	— (uses internal get_cache_dir())	cache off by default
perf	--ignore-cache/--no-ignore-cache	--rebuild/--no-rebuild	—	cache on by default
eval	— (none)	— (none)	—	cache on (library default), no way to override
library default	use_cache=True	force_rebuild=False	cache_dir=None	cache on

Problems

1. Opposite spelling for the same concept — build --no-use-cache vs perf --ignore-cache both set use_cache=False.
2. Opposite defaults — build defaults to no-cache; perf/eval default to cache-on. Same library, different command behavior.
3. eval has no cache control at all — a stale cached model is silently reused with no --rebuild to force a fresh build, and no opt-out.
4. --cache-dir is never exposed — users can't relocate or pin the cache from the CLI even though the library supports it.
5. --rebuild (force_rebuild) is on build/perf but not eval.

Proposal

Add a shared cache-flags decorator (e.g. cache_options()) + a mapping helper (e.g. cache_extra_kwargs()) in utils/cli.py, analogous to build_pipeline_extra_kwargs(), and wire it into build, perf, eval so they share:

• --rebuild/--no-rebuild -> force_rebuild
• a single consistent cache opt-out spelling (pick one: --cache/--no-cache or --use-cache/--no-use-cache) -> use_cache
• --cache-dir PATH -> cache_dir

…with one consistent default across commands.

Open questions (need a decision)

• Default: cache on (perf/eval today, matches library) or off (build today)? Leaning cache-on for consistency with the library, but build's -o mode deliberately bypasses cache — need to preserve that (--cache/-o mutual exclusion, or -o implies --no-cache).
• Canonical opt-out spelling: --no-cache vs --no-use-cache vs keep --ignore-cache. Recommend --cache/--no-cache (shortest, clearest).
• Back-compat: keep perf --ignore-cache and build --use-cache as hidden deprecated aliases during a transition.
• Scope: include run/serve now or follow up?

Out of scope

This is the cache-control axis only. It is orthogonal to --overwrite/--no-overwrite (#970, which guards one-shot output files like the eval/perf JSON report — a different artifact from the model cache). The two never refer to the same thing, so --rebuild (cache) and --overwrite (output) correctly coexist (e.g. in perf).

Related: #561, #970

[DingmaomaoBJTU]

Triage Summary (auto-generated 2026-07-27)

Field	Value
Priority	P2
Type	refactor
Component	build
Owner	vortex-captain

This issue has been triaged. Please update priority/assignment if needed.

[xieofxie]

Implementation scope decision

We reviewed the current command paths and are narrowing this issue before implementation:

• Canonical flags: --use-cache/--no-use-cache and --rebuild/--no-rebuild.
• build keeps its current behavior: cache remains opt-in and callers must provide either --output-dir or --use-cache.
• perf keeps cache on by default. --no-use-cache uses a temporary build and implies a rebuild. Existing --ignore-cache/--no-ignore-cache forms remain as hidden deprecated compatibility aliases.
• eval gains the same cache-on/default, temporary no-cache, and rebuild behavior as perf.
• --cache-dir, run, and serve are removed from this issue's scope with no follow-up planned.
• Cache controls apply only to model build artifacts; --overwrite continues to control result/output files independently.

The work will be split into a behavior-preserving shared/build foundation PR, followed by independently reviewable eval and perf PRs.

[xieofxie]

Implementation is now split into three reviewable stacked PRs:

1. refactor(cli): centralize cache-control options #1269 centralizes the shared cache option contract without changing build behavior.
2. feat(eval): add model cache controls #1270 adds cache/rebuild controls to eval and reports ignored controls on non-building paths.
3. feat(perf): standardize cache controls #1271 migrates perf to canonical positive cache semantics across normal, module, and GenAI paths while retaining hidden deprecated aliases.

The issue should remain open until the stack lands and the final cross-command help/default matrix is confirmed.