Module: Legion::LLM::Routing::Rank

Includes:
Legion::Logging::Helper
Included in:
Legion::LLM::Router
Defined in:
lib/legion/llm/routing/rank.rb

Overview

Soft ordering of eligible lanes: preferred-context band, weight x affinity, rendezvous tie-break, winner selection.

A stateless ranking engine. Pure function of its inputs — it reads no inventory and reaches no Settings at call time; the caller resolves the per-lane preferred-context range and the affinity strength beforehand and hands them in. Reproduces the baseline Ranker's ranking math exactly.

Defined Under Namespace

Classes: RankedLane

Instance Method Summary collapse

Instance Method Details

#rank(lanes:, routing_seed:, routing_affinities:, affinity_strength_bps:, context_budget:, preferred_context_range_for:) ⇒ RankedLane?

Rank the eligible lanes and return the winner as a RankedLane, or nil when there are no lanes.

Winner selection is: greatest effective_weight bucket, then greatest rendezvous score, then ascending lane_id (cryptographically improbable SHA256 collision). The preferred-context band is a priority, not a filter: pass 1 ranks the in-band lanes; pass 2 (only when pass 1 is empty) ranks everything else, band-ignoring.

Parameters:

  • lanes (Array) —

    eligible inventory lanes (LaneRecord shape).

  • routing_seed (String) —

    per-attempt seed for the rendezvous frame.

  • routing_affinities (Array<Hash>) —

    request affinities, each { target_kind:, target:, score_bps: }.

  • affinity_strength_bps (Integer) —

    0..10_000 affinity strength.

  • context_budget (Integer) —

    the request's required context budget.

  • preferred_context_range_for (#call) —

    resolves a lane's preferred { min:, max: } range (nil-open bounds) or nil when unconfigured.

Returns:



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/legion/llm/routing/rank.rb', line 65

def rank(lanes:, routing_seed:, routing_affinities:, affinity_strength_bps:,
         context_budget:, preferred_context_range_for:, **)
  lanes = Array(lanes)
  return nil if lanes.empty?

  log.debug("[llm][rank] action=rank eligible_count=#{lanes.size} " \
            "seed=#{routing_seed[0, 8]}...")

  in_band, out_of_band = rank_band_partition(
    lanes:                       lanes,
    context_budget:              context_budget,
    preferred_context_range_for: preferred_context_range_for
  )

  log.debug("[llm][rank] action=preferred_band_partition eligible=#{lanes.size} " \
            "in_band=#{in_band.size} out_of_band=#{out_of_band.size}")

  # Only the selected pass is ranked, so the ranked set is exactly the
  # lanes eligible for this attempt.
  ranked = if in_band.any?
             rank_compute_ranked(
               lanes:                 in_band,
               routing_seed:          routing_seed,
               routing_affinities:    routing_affinities,
               affinity_strength_bps: affinity_strength_bps
             )
           else
             rank_compute_ranked(
               lanes:                 out_of_band,
               routing_seed:          routing_seed,
               routing_affinities:    routing_affinities,
               affinity_strength_bps: affinity_strength_bps
             )
           end

  rank_select_winner(ranked:)
end