Adaptive Computational Time (ACT) module for TRM strategy.
Uses Jido.AI.Reasoning.TRM.Helpers.clamp/3 for value clamping.
This module implements early stopping logic based on confidence thresholds and convergence detection. It helps the TRM strategy decide when to stop iterating and return the best answer found.
Overview
ACT monitors the progression of answer quality across supervision steps and decides whether to continue iterating or halt early. Key mechanisms:
- Confidence Threshold: Stop when confidence exceeds a threshold
- Convergence Detection: Stop when improvements have plateaued
- Expected Improvement: Estimate whether continuing is worthwhile
Usage
# Calculate combined confidence
confidence = ACT.calculate_confidence(latent_state, quality_score)
# Check if should halt
ACT.should_halt?(confidence, threshold)
#=> true
# Detect convergence from history
ACT.detect_convergence([0.5, 0.6, 0.62, 0.63, 0.63])
#=> true
# Make a decision with full context
state = %{threshold: 0.9, current_confidence: 0.85, history: [0.5, 0.7, 0.85]}
ACT.make_decision(state, latent_state)
#=> {:continue, %{expected_improvement: 0.08}}Summary
Functions
Calculates combined confidence from latent state and quality score.
Calculates the expected improvement from continuing.
Detects if improvements have plateaued based on confidence history.
Detects convergence with custom window and epsilon parameters.
Estimates the number of steps remaining to reach a target confidence.
Returns the reason for halting based on the ACT state.
Calculates the improvement rate from confidence history.
Makes a continue/halt decision based on ACT state and latent state.
Creates a new ACT state with the given threshold.
Checks if the current confidence exceeds the threshold for early stopping.
Calculates the total improvement from first to last confidence score.
Updates the ACT state with a new confidence value.
Updates the confidence history with a new value.
Types
Functions
Calculates combined confidence from latent state and quality score.
Combines the reasoning confidence from latent state with the quality score from supervision feedback using weighted averaging.
Parameters
latent_state- The machine's latent state containing reasoning confidencequality_score- Quality score from supervision (0.0-1.0)
Returns
Combined confidence score between 0.0 and 1.0.
Examples
iex> latent_state = %{confidence_score: 0.8}
iex> ACT.calculate_confidence(latent_state, 0.9)
0.86Calculates the expected improvement from continuing.
Uses the recent improvement trend to estimate how much additional improvement is likely from another iteration.
Parameters
history- List of confidence scores
Returns
Expected improvement as a float (0.0-1.0).
Examples
iex> ACT.calculate_expected_improvement([0.5, 0.6, 0.7, 0.8])
0.1
iex> ACT.calculate_expected_improvement([0.8, 0.82, 0.83])
0.02Detects if improvements have plateaued based on confidence history.
Analyzes the recent confidence scores to determine if the improvement rate has dropped below a meaningful threshold.
Parameters
history- List of confidence scores from oldest to newest
Returns
true if improvements have plateaued, false otherwise.
Examples
iex> ACT.detect_convergence([0.5, 0.6, 0.7, 0.8])
false
iex> ACT.detect_convergence([0.7, 0.72, 0.73, 0.73])
true@spec detect_convergence([float()], pos_integer(), float()) :: boolean()
Detects convergence with custom window and epsilon parameters.
Parameters
history- List of confidence scoreswindow- Number of recent scores to considerepsilon- Maximum range for convergence
Examples
iex> ACT.detect_convergence([0.7, 0.71, 0.72], 3, 0.05)
true@spec estimated_steps_remaining(float(), float(), [float()]) :: non_neg_integer() | :infinity
Estimates the number of steps remaining to reach a target confidence.
Parameters
current- Current confidence scoretarget- Target confidence to reachhistory- Confidence history for trend estimation
Returns
Estimated steps remaining, or :infinity if improvement rate is too low.
Examples
iex> ACT.estimated_steps_remaining(0.7, 0.9, [0.5, 0.6, 0.7])
2@spec get_halt_reason(act_state()) :: halt_reason() | nil
Returns the reason for halting based on the ACT state.
Parameters
act_state- Current ACT state
Returns
A halt reason atom or nil if should continue.
Examples
iex> state = %{threshold: 0.9, current_confidence: 0.95, history: [0.9, 0.92, 0.95]}
iex> ACT.get_halt_reason(state)
:threshold_exceededCalculates the improvement rate from confidence history.
Returns the average rate of improvement per step.
Parameters
history- List of confidence scores
Examples
iex> ACT.improvement_rate([0.5, 0.6, 0.7, 0.8])
0.1@spec make_decision(act_state(), map()) :: {:continue, map()} | {:halt, halt_reason()}
Makes a continue/halt decision based on ACT state and latent state.
Evaluates multiple factors:
- Whether confidence exceeds threshold
- Whether improvements have converged
- Expected improvement from continuing
Parameters
act_state- Current ACT state with threshold and historylatent_state- Machine's latent state (optional)
Returns
A tuple of {:continue, metadata} or {:halt, reason}.
Examples
iex> state = %{threshold: 0.9, current_confidence: 0.95, history: [0.8, 0.9, 0.95]}
iex> ACT.make_decision(state, %{})
{:halt, :threshold_exceeded}
iex> state = %{threshold: 0.9, current_confidence: 0.7, history: [0.5, 0.6, 0.7]}
iex> ACT.make_decision(state, %{})
{:continue, %{expected_improvement: ...}}Creates a new ACT state with the given threshold.
Parameters
threshold- Confidence threshold for early stopping (0.0-1.0)
Examples
iex> ACT.new(0.9)
%{threshold: 0.9, current_confidence: 0.0, history: []}Checks if the current confidence exceeds the threshold for early stopping.
Parameters
confidence- Current confidence scorethreshold- Threshold for early stopping
Returns
true if confidence >= threshold, false otherwise.
Examples
iex> ACT.should_halt?(0.95, 0.9)
true
iex> ACT.should_halt?(0.85, 0.9)
falseCalculates the total improvement from first to last confidence score.
Parameters
history- List of confidence scores
Examples
iex> ACT.total_improvement([0.5, 0.6, 0.7, 0.8])
0.3Updates the ACT state with a new confidence value.
Adds the new confidence to the history and updates the current confidence.
Parameters
state- Current ACT stateconfidence- New confidence value to record
Examples
iex> state = ACT.new(0.9)
iex> ACT.update(state, 0.7)
%{threshold: 0.9, current_confidence: 0.7, history: [0.7]}Updates the confidence history with a new value.
Maintains a rolling history of confidence scores for convergence detection.
Parameters
history- List of previous confidence scoresnew_confidence- New confidence score to add
Returns
Updated history list.
Examples
iex> ACT.update_confidence_history([0.5, 0.6], 0.7)
[0.5, 0.6, 0.7]