Module: Legion::LLM::Router::InputBound

Extended by:
Legion::Logging::Helper
Includes:
Legion::Logging::Helper
Defined in:
lib/legion/llm/router/input_bound.rb

Overview

Conservative provider-neutral pre-selection input token upper bound (SSOT v3 ยง9.1).

The bound is deliberately over-estimated: one token cannot require more than one input byte under any currently admitted encoding contract. We therefore sum UTF-8 byte lengths of all textual content and canonical JSON-serialised byte lengths of structured inputs, then add the configured framing overhead. No chars/4 heuristic, no tokenizer call, no Float arithmetic, no provider-specific estimation.

This bound gates hard admission decisions before a lane is selected. Existing TokenEstimation/ContextAccounting helpers remain available for telemetry and post-selection curation but their output cannot authorize a lane.

Class Method Summary collapse

Class Method Details

.call(messages: nil, system: nil, tools: nil, tool_choice: nil, thinking: nil, response_format: nil, operation_payload: nil, framing_overhead_tokens: 0) ⇒ Integer

Returns a nonnegative Integer upper bound on the number of tokens required to represent all supplied inputs.

Parameters:

  • operation (Symbol) —

    the canonical operation (unused here; present for call-site symmetry with RequiredCapabilities)

  • messages (Array, nil) (defaults to: nil) —

    canonical message hashes/objects

  • system (String, nil) (defaults to: nil) —

    system prompt text

  • tools (Array, nil) (defaults to: nil) —

    canonical tool-schema objects/hashes

  • tool_choice (Hash, nil) (defaults to: nil) —

    canonical tool-choice value

  • thinking (Hash, nil) (defaults to: nil) —

    thinking configuration hash

  • response_format (Hash, nil) (defaults to: nil) —

    response format hash

  • operation_payload (Hash, nil) (defaults to: nil) —

    operation-specific extra payload

  • framing_overhead_tokens (Integer) (defaults to: 0) —

    configured framing overhead (e.g. from SettingsSnapshot#input_framing_overhead_tokens)

Returns:

  • (Integer) —

    nonnegative token upper bound

Raises:

  • (ArgumentError) 


38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/legion/llm/router/input_bound.rb', line 38

def call(
  messages: nil,
  system: nil,
  tools: nil,
  tool_choice: nil,
  thinking: nil,
  response_format: nil,
  operation_payload: nil,
  framing_overhead_tokens: 0,
  **
)
  total = 0

  # System prompt
  total = Integer(total) + text_bytes(system)

  # Messages: each message may have String content or Array-of-content-blocks
  Array(messages).each do |msg|
    total += message_text_bytes(msg)
  end

  # Structured inputs serialised to canonical JSON
  total += serialized_bytes(tools)          unless nil_or_empty?(tools)
  total += serialized_bytes(tool_choice)    unless nil_or_empty?(tool_choice)
  total += serialized_bytes(thinking)       unless nil_or_empty?(thinking)
  total += serialized_bytes(response_format) unless nil_or_empty?(response_format)
  total += serialized_bytes(operation_payload) unless nil_or_empty?(operation_payload)

  # Framing overhead (caller-supplied configured Integer)
  overhead = Integer(framing_overhead_tokens.to_i)
  raise ArgumentError, "framing_overhead_tokens must be nonnegative, got #{overhead}" if overhead.negative?

  total += overhead

  log.debug("[llm][input_bound] action=compute total_bytes=#{total}")
  total
end