Unslop the codebase: pay down ai slop in oversized core modules

[Andyyyy64]

Problem

The codebase works, but several core modules have accumulated too much responsibility in single files. This is intentionally blunt: parts of the implementation now read like ai slop, where CLI orchestration, external I/O, domain rules, scoring heuristics, rendering, and curated data all sit together.

That makes future ranking changes riskier than they need to be. Small edits to benchmark logic, model fetching, output formatting, or CLI behavior can have a wide blast radius because the boundaries are not clean.

Current hotspots

Measured with wc -l:

1087  src/whichllm/cli.py
 880  src/whichllm/models/fetcher.py
 835  src/whichllm/output/display.py
 803  src/whichllm/engine/ranker.py
 751  src/whichllm/models/benchmark.py
 404  src/whichllm/constants.py

Tests with similar size pressure:

574  tests/test_cli.py
553  tests/test_ranker.py
500  tests/test_p1_p3_regressions.py
459  tests/test_r3_regressions.py

Suggested direction

Refactor toward clearer responsibility boundaries:

• Keep cli.py as a thin Typer layer: option parsing, validation, and command dispatch only.
• Add application/use-case modules for command flows, e.g. recommend, plan, upgrade, run, snippet, and hardware.
• Split ranker.py into candidate generation, filtering, scoring, family deduplication, and ranking orchestration.
• Split benchmark.py into benchmark fetching, source normalization, score lookup, and evidence resolution.
• Split fetcher.py into HuggingFace client calls, model parsing, GGUF extraction, MoE/param overrides, and serialization.
• Split display.py by output surface: ranking, plan, upgrade, JSON, and shared formatting helpers.
• Move large curated registries out of constants.py where practical, or at least separate GPU, quantization, lineage, and model override data.

Acceptance criteria

• Core runtime modules are below 400 lines where practical, excluding intentionally data-only files.
• CLI command functions do not contain model loading, benchmark fetching, ranking, and rendering logic inline.
• Ranking behavior is preserved by existing tests.
• The current regression suite still passes.
• New module boundaries make it possible to modify benchmark evidence, scoring, or Rich output without touching unrelated command code.

Non-goals

• Do not change ranking behavior as part of the first cleanup unless required by extraction.
• Do not reformat the entire codebase mechanically.
• Do not remove existing regression tests; split them only if it improves maintainability.

[RaghavRD]

Hi! I'd like to take a stab at this. To keep PRs small and reviewable, I'd plan to ship the refactor as a sequence rather than one mega-PR — each PR is behavior-preserving and keeps the existing test suite green (207 tests, currently passing locally on main).

Proposed order, lowest-risk first:

constants.py — split curated registries (GPU bandwidth, quantization, lineage, model overrides) into a whichllm/data/ package. Pure data move, near-zero behavior risk.
output/display.py — split by output surface (ranking / plan / upgrade / JSON / shared helpers). Pure rendering.
models/fetcher.py — split HF client calls, model parsing, GGUF extraction, MoE/param overrides, serialization.
models/benchmark.py — split fetching, source normalization, score lookup, evidence resolution.
engine/ranker.py — split candidate generation, filtering, scoring, family dedup, ranking orchestration. Highest behavior risk — deliberately last.
cli.py — extract use-case modules (recommend, plan, upgrade, run, snippet, hardware); leave Typer layer thin.

Each PR: no functional changes, all 207 tests still green, imports re-exported from old paths during the transition so nothing breaks for in-flight branches.

Happy to adjust the ordering or scope if you'd prefer a different starting point — does this direction work for you? If so I'll open PR 1 (constants split) first.

[Andyyyy64]

Thanks, this direction works. Sorry I missed the comment.

Please start with the constants.py split. That is the lowest-risk first PR.

For the first PR, I would like it to stay behavior-preserving:

• move curated registries into a whichllm/data/ style package
• keep imports stable, or re-export from the old path during the transition
• avoid ranking, display, or CLI behavior changes
• keep the current test suite green

After that lands, we can move to output/display.py.