Crate harpe 

harpe

Deterministic context synthesis and token budgeting for autonomous AI agents.

Harpe provides deterministic, microsecond token budgeting and priority-based context trimming for agentic loops. When language models run multi-turn agent workflows, context windows can quickly exceed hardware or inference limits. Uncontrolled growth results in context truncation, lost system prompts, or excessive inference latency.

Harpe solves this by calculating available context headroom, prioritizing pinned instructions, and pruning lower-priority context items before model invocation.

Architecture Overview

1. Token Accounting: TokenBudget defines the maximum context envelope, deducting reserved tokens for model output, tool specifications, and safety margin.
2. Context Entities: ContextItem represents individual context components (system prompts, active tool outputs, conversation turns) tagged with numeric priorities.
3. Synthesis Engine: ContextBudgetEngine resolves token counts and applies pruning strategies such as PrunePolicy::LowestPriority or PrunePolicy::Fifo to produce an exact SynthesisReport fitting within the budget.

Quick Start

use harpe::{ContextBudgetEngine, ContextItem, ContextSynthesizer, PrunePolicy, TokenBudget};

// Define a total context envelope of 4096 tokens, reserving 1024 for output and tools
let mut budget = TokenBudget::new(4096);
budget.reserved_completion = 512;
budget.reserved_tools = 256;
budget.safety_margin = 256;

assert_eq!(budget.available_context(), 3072);

// Prepare context items with explicit priorities (0 is pinned/highest priority)
let system_prompt = ContextItem::new("sys", "You are an autonomous systems assistant.", 0);
let conversation = ContextItem::new("hist", "Previous user query and reasoning traces.", 50);
let scratchpad = ContextItem::new("scratch", "Temporary debug buffer with logs.", 90);

let engine = ContextBudgetEngine::default();
let report = engine.synthesize(
    &[system_prompt, conversation, scratchpad],
    &budget,
    PrunePolicy::LowestPriority,
).expect("Synthesis should succeed");

println!("Consumed tokens: {}", report.consumed_tokens);
println!("Remaining tokens: {}", report.budget_remaining);

Structs

ContextBudgetEngine

Primary context synthesis and budgeting engine.

ContextItem

A discreet unit of context presented to the synthesis engine.

HeuristicTokenCounter

Fast heuristic token counter estimating tokens via word and character ratios.

SynthesisReport

Detailed outcome of a context synthesis execution.

TokenBudget

Token budget configuration for an agent invocation turn.

Enums

HarpeError

Errors returned during context synthesis and budgeting operations.

PrunePolicy

Pruning policies supported by the context synthesis engine.

Constants

VERSION

Traits

ContextSynthesizer

Trait implemented by context synthesis engines.

PruningHook

Hook for lifecycle interception before and after pruning runs.

TokenCounter

Trait for measuring token counts of text slices.