navigate_models

The primary recommendation engine. Decompose the user's natural language
query into these structured parameters — ModelAtlas does deterministic math.

── START HERE: NARROW, THEN ORDER ──────────────────────────────────

  `require_anchors` is the ONLY parameter that narrows the candidate set.
  Bank directions, `prefer_anchors`, `avoid_anchors`, and `similar_to`
  all SCORE a set they never shrink. Omit `require_anchors` and every
  model in the corpus is scored, with `limit` lopping off the tail — you
  get the top slice of an unfiltered corpus, not the best of a considered
  field. The response says so: `refine.scope_unfiltered: true`.

  So drive it in that order:

    1. NARROW — one or two `require_anchors` naming what the model must
       have ("code-generation", "GGUF-available"). The vocabulary is
       CLOSED — an anchor that does not exist returns zero results, so do
       not invent labels. If you do not know it, call with no
       `require_anchors` and read the anchors offered by
       `refine.options` and `refine.splitting_anchors`: they are real
       labels drawn from the returned window. The `anchors` list on each
       result is the same vocabulary seen from the other side.
    2. ORDER — `prefer_anchors` for what would be nice. Without them the
       ranking is filtered but not meaningfully sorted
       (`refine.ranking_degraded: true`).
    3. SHAPE — bank directions, `mode`, `bank_weights` to tilt the result.
    4. REFINE — answer `refine.question` and re-call (see below).

  A well-formed query considers hundreds of candidates, not tens of
  thousands. If you find yourself reaching for `limit` to make a broad
  query manageable, add a `require_anchor` instead — `limit` truncates,
  it does not select.

BANK DIRECTIONS (-1, 0, or +1 for each; omit to express "don't care"):

  architecture:  -1=simpler/older (encoder-only, RNN)
                  0=standard transformer decoder (most models)
                 +1=novel/specialized (Mamba, RWKV, SSM, MoE)

  capability:    -1=narrow/single-task (classifier, embedding-only)
                  0=general language model
                 +1=rich/multi-capability (code, reasoning, tool-calling)

  efficiency:    -1=smaller/lighter (3B, 1B, sub-1B, edge)
                  0=~7B mainstream sweet spot
                 +1=larger/frontier (13B, 30B, 70B+)

  compatibility:  0=standard PyTorch/transformers
                 +1=specific format/hardware (GGUF, MLX, Apple Silicon)

  lineage:       -1=predecessor/earlier in family
                  0=base/foundational model
                 +1=derivative (fine-tune, quantized, community merge)

  domain:         0=general knowledge
                 +1=domain-specialized (code, medical, legal, finance)

  quality:       -1=legacy/declining/abandoned
                  0=established mainstream
                 +1=trending/rising momentum

  training:      -1=simpler methods (LoRA, adapter, distillation)
                  0=standard supervised fine-tuning (SFT)
                 +1=complex alignment (RLHF, DPO, multi-stage)

ANCHOR TARGETING:
  require_anchors: Model MUST have ALL of these (hard filter).
    Examples: "code-generation", "instruction-following", "Llama-family",
              "GGUF-available", "consumer-GPU-viable", "tool-calling"
  prefer_anchors: Boost models with these (soft preference, IDF-weighted).
  avoid_anchors: Penalize models with these (each halves the score).
  context_anchors: Anchors the CALLING CONTEXT has already established
    as relevant (e.g. earlier-turn state, the user's stated situation).
    Soft multiplicative bias in [1.0, 1.5]× based on IDF-weighted
    overlap — never a filter. Use for "the same query would resolve
    differently in a different context" cases: passing
    `["Apple-Silicon-native"]` on a Mac user's session biases toward
    MLX/GGUF-Metal without excluding CUDA-only models from the ranking.

QUERY MODE:
  mode: How aggressively to weight the soft signals.
    - "auto" (default) — derives from the query's mechanical (size,
      format, structure) vs semantic (capability, domain, quality)
      character. Mechanical-heavy queries let PageRank dominate;
      semantic-heavy queries let rare-anchor / absence-bonus signals
      dominate. Sensible default for most callers.
    - "canonical" — amps PageRank. Established mainstream models rise.
      Use for "give me the well-known thing that matches."
    - "niche" — amps rare-match, absence-bonus, superadditive signals.
      Specialists rise over popular near-misses. Use for
      "find the specific specialist, not the popular generalist."
    - "balanced" — fixed default weights (no auto-adaptation).

DEPTH — HOW FAR, NOT JUST WHICH WAY:
  min_depth: {BANK: minimum steps from the zero state}, e.g.
    {"EFFICIENCY": 3} alongside `efficiency=1`. A bank position is
    [SIGN][DEPTH]; a direction alone says only which way, so
    `efficiency=+1` admits a 13B model and a 400B one equally. Depth is
    the "how far" half.

    This is a FILTER, applied by set intersection when candidates are
    selected — not a scoring term. Depth decides who is admissible;
    what ORDERS the admissible set is the separate scalar signal. Ask
    for the shape you want, then let ranking do its own job.

    Ignored for a bank whose direction is 0 or unset — the zero state
    is depth 0, so "at least N steps from it" means nothing there.

  max_depth: the ceiling to min_depth's floor, e.g.
    {"EFFICIENCY": 1}. Unlike min_depth this DOES apply at direction 0,
    where it reads as a band around the zero state:
    `efficiency=0, max_depth={"EFFICIENCY": 1}` is "the ~7B sweet spot,
    give or take one class" and excludes a 400B model that happens to sit
    at the zero state because nobody recorded its size.

    Rough EFFICIENCY guide: 1 ~ one class out (3B / 13B), 2 ~ two
    (1B / 30B), 3+ ~ the far end (sub-1B / 70B+).

BANK WEIGHTS:
  bank_weights: Optional per-bank exponent overrides,
    e.g. {"QUALITY": 0.0, "CAPABILITY": 2.0} to neutralize quality-
    tiering and double-weight capability alignment. Missing bank →
    weight 1.0 (default). Zero → the bank contributes nothing to
    alignment (neutralized). > 1 → the bank counts extra.
    Renormalized across active banks so total attention-mass is
    preserved. Feature, not a knob-to-hide: sometimes the caller
    knows better than the defaults.

SEED SIMILARITY:
  similar_to: A model_id to use as similarity seed (IDF-weighted Jaccard
              on anchor sets). Example: "meta-llama/Llama-3.1-8B-Instruct"

SCORING:
  score = bank_alignment * anchor_relevance * seed_similarity * coherence
          * context_bias * epa_alignment * soft_combined
  Multiplicative, so any zero factor kills the result. The first six are
  ≤ 1.0 and filter; `soft_combined` REWARDS (PageRank, PMI-match, rare
  boost, absence bonus, folded submodularly), so scores are NOT bounded
  at 1.0. Every factor is returned in `score_breakdown`.

THE REFINEMENT LOOP — read this before reporting results to a user:

  Every response carries a `refine` block. The engine is deterministic:
  it knows which dimensions its own answer is silent on, and it will not
  pretend to an ordering it cannot justify. Use it.

    1. Call navigate_models with whatever the user gave you.
    2. Read `refine.question` — one plain question naming the single
       most useful thing still unspecified.
    3. Ask the user that question (or answer it yourself if the earlier
       conversation already settles it).
    4. Merge the chosen option's `apply` dict into the SAME arguments you
       just sent — do NOT rebuild the query from scratch. Scalar keys
       (`efficiency`) replace; list keys (`require_anchors`) append.
    5. Re-call. Repeat until `refine.question` is empty.

  `refine.scope_unfiltered: true` means you passed no `require_anchors`,
  so the candidate set was the whole corpus. This is the sibling of
  `ranking_degraded` one stage earlier, and it is asked FIRST — no
  ordering signal repairs a field that was never narrowed. The options
  on that question are anchors drawn from the window itself, so each one
  names something at least one returned model actually has.

  `refine.ranking_degraded: true` means you passed no `prefer_anchors`.
  The results are correctly FILTERED but not meaningfully ORDERED —
  three of five soft signals score identically for every candidate that
  clears the `require` filter. Treat the window as a SET, not a ranking,
  and do not tell the user result #1 beats result #2. Add prefer_anchors.

  `tie_cluster_id` on a result means the same thing locally: those
  results are indistinguishable given the constraints, and
  `discriminating_axis` names the bank that would separate them.

Args:
    architecture: Bank direction for ARCHITECTURE (-1, 0, or +1)
    capability: Bank direction for CAPABILITY (-1, 0, or +1)
    efficiency: Bank direction for EFFICIENCY (-1, 0, or +1)
    compatibility: Bank direction for COMPATIBILITY (-1, 0, or +1)
    lineage: Bank direction for LINEAGE (-1, 0, or +1)
    domain: Bank direction for DOMAIN (-1, 0, or +1)
    quality: Bank direction for QUALITY (-1, 0, or +1)
    training: Bank direction for TRAINING (-1, 0, or +1)
    require_anchors: Anchors the model MUST have (hard filter)
    prefer_anchors: Anchors that boost score (soft, IDF-weighted)
    avoid_anchors: Anchors that penalize score
    context_anchors: Ambient-context anchors (soft bias, ≤ 1.5× boost)
    mode: Query mode — "auto" | "canonical" | "niche" | "balanced"
    bank_weights: Optional {bank: exponent} per-bank weight overrides
    min_depth: Optional {bank: minimum depth} hard filter, e.g.
        {"EFFICIENCY": 3}. Needs that bank's direction set to +1/-1.
    max_depth: Optional {bank: maximum depth} hard filter. Applies at
        direction 0 as a band around the zero state.
    similar_to: Model ID for anchor-similarity seed
    limit: Max results to return (default 20)