Module budget 

Per-session token spend budgeting with hard/soft limits and daily reset.

Overview

SessionBudget tracks cumulative token usage per SessionId and enforces configurable spending limits:

• Hard limit — requests are rejected with BudgetError::HardLimitExceeded before inference when spend would exceed this cap.
• Soft limit — requests are allowed but a BudgetWarning signal is returned so callers can notify users or throttle gracefully.
• Daily reset — accumulated spend is zeroed at UTC midnight (or on explicit call to SessionBudget::reset_session).

REST API surface

The budget store is intended to back two REST endpoints wired in web_api.rs:

• GET /v1/sessions/{id}/budget → SessionBudgetSnapshot
• POST /v1/sessions/{id}/budget/reset → resets spend to zero

Units

All limits and accumulated spend are in tokens (not USD), because token counts are provider-agnostic and directly observable. Callers that want cost-based limits should convert via a token-to-cost rate before recording.

Example

use tokio_prompt_orchestrator::session::budget::{
    SessionBudget, SessionLimits, BudgetOutcome,
};

let budget = SessionBudget::new();
budget.set_limits("alice", SessionLimits {
    soft_limit_tokens: 8_000,
    hard_limit_tokens: 10_000,
});

// First request: well within budget
let outcome = budget.record_tokens("alice", 500).unwrap();
assert!(matches!(outcome, BudgetOutcome::Ok));

// Another request pushing past soft limit
let outcome = budget.record_tokens("alice", 8_000).unwrap();
assert!(matches!(outcome, BudgetOutcome::SoftLimitWarning { .. }));

// Reset daily spend
budget.reset_session("alice");

Structs

SessionBudget

Thread-safe per-session token budget tracker.

SessionBudgetSnapshot

A point-in-time snapshot of a session’s budget state.

SessionLimits

Per-session budget limits.

Enums

BudgetError

Errors returned by SessionBudget operations.

BudgetOutcome

Outcome of a SessionBudget::record_tokens call.