Budget

Budget tracking for elicitation episodes.

Tracks per-episode consumption across five dimensions (turns, runtime, tokens, questions, unique items) and signals when any configured limit is exceeded.

BudgetTracker(budget_turns=None, budget_runtime=None, budget_tokens=None, budget_questions=None, budget_unique_items=None, policy_budget_weight=1.0, user_budget_weight=1.0)

Tracks multiple budget dimensions and signals when any limit is exhausted.

Each budget dimension is optional — pass None (the default) to impose no limit on that dimension. Budgets are checked in is_exhausted(), which returns a (bool, reason_str) pair.

Runtime and token costs are weighted before accumulation to allow asymmetric penalization of policy vs. user simulator costs:

• weighted_runtime = policy_budget_weight * policy_runtime + user_budget_weight * user_runtime
• weighted_tokens = policy_budget_weight * policy_tokens + user_budget_weight * user_tokens

Set a weight to 0.0 to ignore that component entirely (e.g. exclude user simulator costs from the token budget).

Attributes:

Name	Type	Description
budget_turns		Maximum number of conversation turns allowed.
budget_runtime		Maximum weighted wall-clock seconds allowed.
budget_tokens		Maximum weighted token count allowed.
budget_questions		Maximum clarifying questions the user simulator may ask.
budget_unique_items		Maximum distinct catalog items the agent may surface.
policy_budget_weight		Multiplier applied to policy-side runtime/token costs.
user_budget_weight		Multiplier applied to user-simulator runtime/token costs.
current_turns		Turns consumed so far.
current_runtime		Weighted seconds consumed so far.
current_tokens		Weighted tokens consumed so far (policy + user).
current_policy_tokens		Raw policy token count (unweighted).
current_user_tokens		Raw user-simulator token count (unweighted).
current_questions		Clarifying questions asked so far.
current_unique_items		Distinct catalog items surfaced so far.

Initialize a BudgetTracker.

Parameters:

Name	Type	Description	Default
budget_turns	Optional[int]	Maximum conversation turns before exhaustion. None means no turn limit.	None
budget_runtime	Optional[float]	Maximum weighted wall-clock seconds before exhaustion. None means no runtime limit.	None
budget_tokens	Optional[int]	Maximum weighted tokens before exhaustion. None means no token limit.	None
budget_questions	Optional[int]	Maximum clarifying questions the user simulator may ask. Checked externally via get_remaining_questions(); does not trigger is_exhausted(). None means no limit.	None
budget_unique_items	Optional[int]	Maximum distinct catalog items the agent may surface. Checked externally via get_remaining_unique_items(); does not trigger is_exhausted(). None means no limit.	None
policy_budget_weight	float	Multiplier for policy-side runtime/token costs. Defaults to 1.0.	1.0
user_budget_weight	float	Multiplier for user-simulator runtime/token costs. Defaults to 1.0.	1.0

add_questions(count)

Add to the clarifying-question counter.

Parameters:

Name	Type	Description	Default
count	int	Number of questions asked in the current turn.	required

add_runtime(policy_runtime, user_runtime)

Accumulate weighted wall-clock runtime.

Parameters:

Name	Type	Description	Default
policy_runtime	float	Seconds spent in the policy (agent) this turn.	required
user_runtime	float	Seconds spent in the user simulator this turn.	required

add_tokens(policy_tokens, user_tokens)

Accumulate weighted token usage.

Internally tracks raw policy and user token counts separately, then recomputes current_tokens as: policy_budget_weight * total_policy_tokens + user_budget_weight * total_user_tokens.

Parameters:

Name	Type	Description	Default
policy_tokens	int	Tokens used by the policy this turn.	required
user_tokens	int	Tokens used by the user simulator this turn.	required

add_turn()

Increment the turn counter by one.

add_unique_items(count)

Add to the unique-items-surfaced counter.

Parameters:

Name	Type	Description	Default
count	int	Number of new distinct catalog items shown in the current turn.	required

get_metrics()

Return a snapshot of current usage and remaining budget for all dimensions.

Returns:

Type	Description
Dict[str, Any]	A dict with keys "turns", "runtime", "tokens",
Dict[str, Any]	"questions", and "unique_items". Each value is a dict with
Dict[str, Any]	"current", "budget" (limit or None), and "remaining"
Dict[str, Any]	(remaining capacity or None if unlimited) sub-keys. The
Dict[str, Any]	"tokens" entry additionally includes "policy_tokens" and
Dict[str, Any]	"user_tokens" (raw unweighted counts) plus "policy_breakdown"
Dict[str, Any]	and "user_breakdown" (per-bucket input/input_cached/output/
Dict[str, Any]	reasoning splits, populated via set_*_token_breakdown).

get_remaining_questions()

Return the number of clarifying questions still permitted.

Returns:

Type	Description
Optional[int]	Remaining question budget (≥ 0), or None if no limit is set.

get_remaining_unique_items()

Return the number of additional unique items that may still be surfaced.

Returns:

Type	Description
Optional[int]	Remaining unique-items budget (≥ 0), or None if no limit is set.

is_exhausted()

Check whether any hard budget limit has been reached.

Checks turns, runtime, and tokens in that order. Questions and unique-items budgets are soft limits surfaced via get_remaining_questions() / get_remaining_unique_items() and are not checked here.

Returns:

Type	Description
bool	A (exhausted, reason) tuple where exhausted is True if
str	any limit is reached and reason is one of
Tuple[bool, str]	"turns_exhausted", "runtime_exhausted",
Tuple[bool, str]	"tokens_exhausted", or "" (not exhausted).

set_policy_token_breakdown(breakdown)

Overwrite policy token breakdown with the agent's cumulative counts.

set_user_token_breakdown(breakdown)

Overwrite user token breakdown with the simulator's cumulative counts.