Struct ContextBudget

Source

pub struct ContextBudget { /* private fields */ }

Expand description

Token budget for a single agent session.

Tracks the maximum token window and divides it across context slots. Call ContextBudget::allocate or ContextBudget::allocate_with_opts to get a BudgetAllocation that can be fed to crate::assembler::ContextAssembler.

Implementations§

Source §

impl ContextBudget

Source

pub fn new(max_tokens: usize, reserve_ratio: f32) -> Self

Create a new budget with max_tokens capacity and reserve_ratio fraction reserved for the model response.

§Examples

use zeph_context::budget::ContextBudget;

let budget = ContextBudget::new(128_000, 0.15);
assert_eq!(budget.max_tokens(), 128_000);

Source

pub fn with_graph_enabled(self, enabled: bool) -> Self

Enable or disable graph fact allocation in the budget split.

When enabled, 4% of available tokens are routed to the graph_facts slot, and the summaries/semantic_recall slices are each reduced by 1%.

Source

pub fn max_tokens(&self) -> usize

Maximum token capacity for this session.

Source

pub fn allocate( &self, system_prompt: &str, skills_prompt: &str, tc: &dyn TokenCounting, graph_enabled: bool, ) -> BudgetAllocation

Allocate the budget across context slots for one turn.

Equivalent to allocate_with_opts(…, 0, false).

§Examples

use zeph_context::budget::ContextBudget;

// Any type implementing `zeph_common::memory::TokenCounting` can be used.
let budget = ContextBudget::new(128_000, 0.15);
let tc = Tc;
let alloc = budget.allocate("system prompt", "skills prompt", &tc, false);
assert!(alloc.recent_history > 0);

Source

pub fn allocate_with_opts( &self, system_prompt: &str, skills_prompt: &str, tc: &dyn TokenCounting, graph_enabled: bool, digest_tokens: usize, memory_first: bool, ) -> BudgetAllocation

Allocate context budget with optional digest pre-reservation and MemoryFirst mode.

This method provides fine-grained control over token allocation by allowing callers to pre-reserve tokens for session digests and toggle MemoryFirst mode. Use this when digest blocks or memory-focused allocation is needed; otherwise, call allocate for simpler usage.

§Parameters

system_prompt — the system prompt string; its token count is deducted from available tokens
skills_prompt — the skills block; its token count is also deducted
tc — a token counter implementing TokenCounting (e.g., the LLM provider)
graph_enabled — when true, allocates 4% of available tokens to graph_facts
digest_tokens — pre-counted tokens for the session digest block; deducted from available tokens BEFORE percentage splits so it does not silently crowd out other slots
memory_first — when true, sets recent_history to 0 and redistributes those tokens across summaries, semantic_recall, and cross_session

§Returns

A BudgetAllocation with all context slots populated according to the budget strategy.

§Examples

use zeph_context::budget::ContextBudget;

let budget = ContextBudget::new(128_000, 0.15);
let tc = Tc;
// Allocate with a pre-counted digest of 500 tokens in MemoryFirst mode
let alloc = budget.allocate_with_opts(
    "system prompt",
    "skills prompt",
    &tc,
    false,
    500,  // digest_tokens
    true, // memory_first
);
assert_eq!(alloc.recent_history, 0);