Struct UtilityScorer 

pub struct UtilityScorer { /* private fields */ }

Computes utility scores for tool calls before dispatch.

Not Send + Sync — lives on the agent’s single-threaded tool loop (same lifecycle as ToolResultCache and recent_tool_calls).

Implementations

impl UtilityScorer

pub fn new(config: UtilityScoringConfig) -> Self

Create a new scorer from the given config.

pub fn is_enabled(&self) -> bool

Whether utility scoring is enabled.

pub fn score( &self, call: &ToolCall, ctx: &UtilityContext, ) -> Option<UtilityScore>

Score a candidate tool call.

Returns None when scoring is disabled. When scoring produces a non-finite result (misconfigured weights), returns None — the caller treats None as fail-closed (skip the tool call) unless user_requested is set.

pub fn recommend_action( &self, score: Option<&UtilityScore>, ctx: &UtilityContext, ) -> UtilityAction

Recommend an action based on the utility score and turn context.

Decision tree (thresholds from arXiv:2603.19896):

1. user_requested → always ToolCall (bypass policy).
2. Scoring disabled → always ToolCall.
3. score is None (invalid score, scoring enabled) → Stop (fail-closed).
4. cost > 0.9 (budget nearly exhausted) → Stop.
5. redundancy == 1.0 (duplicate call) → Respond.
6. gain >= 0.7 && total >= threshold → ToolCall.
7. gain >= 0.5 && uncertainty > 0.5 → Retrieve.
8. total < threshold && tool_calls_this_turn > 0 → Verify.
9. total >= threshold → ToolCall.
10. Default → Respond.

pub fn record_call(&mut self, call: &ToolCall)

Record a call as executed for redundancy tracking.

Must be called after score() and before the next call to score() for the same tool in the same turn.

pub fn clear(&mut self)

Reset per-turn state. Call at the start of each LLM tool round.

pub fn is_exempt(&self, tool_name: &str) -> bool

Returns true when tool_name is in the exempt list (case-insensitive).

Exempt tools bypass the utility gate unconditionally and always receive ToolCall.

pub fn threshold(&self) -> f32

The configured threshold.

Trait Implementations

impl Debug for UtilityScorer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.