Token Estimation CLI

Configure how PraisonAI estimates token counts from the CLI

from praisonaiagents import Agent

agent = Agent(name="estimator", instructions="Preview token usage before heavy runs.")
agent.start("Estimate how many tokens this prompt will use.")

Control token estimation mode from the CLI — choose fast heuristics or accurate tiktoken counts when debugging context usage.

The user runs CLI token estimation to preview context size before starting an expensive chat session.

How It Works

Quick Start

1. Run an agent with accurate token counts

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Assistant",
       instructions="Answer questions concisely.",
   )
   
   agent.start("Explain token estimation in one paragraph")
   

   Then check counts from the CLI:

   praisonai chat --context-estimation-mode accurate
   # In session: /context stats
   
2. Enable mismatch logging for debugging

   praisonai chat \
     --context-estimation-mode validated \
     --context-log-mismatch
   

   Validated mode compares heuristic vs accurate estimates and logs when they diverge by more than 15%.

CLI Flags

Flag	Values	Default	Description
--context-estimation-mode	heuristic, accurate, validated	heuristic	How tokens are counted
--context-log-mismatch	flag	off	Log when heuristic differs from accurate

# Fast heuristic (default)
praisonai chat --context-estimation-mode heuristic

# Accurate with tiktoken
praisonai chat --context-estimation-mode accurate

Interactive Commands

> /context config   # View estimation mode
> /context stats    # Token counts per segment

config.yaml

context:
  estimation:
    mode: heuristic
    log_mismatch: false
    mismatch_threshold_pct: 15.0

Environment variables: PRAISONAI_CONTEXT_ESTIMATION_MODE, PRAISONAI_CONTEXT_LOG_MISMATCH.

Best Practices

Use heuristic in production

Heuristic mode is fastest and sufficient for compaction triggers in normal use.

Switch to accurate when counts look wrong

If compaction fires too early or too late, run with --context-estimation-mode accurate and check /context stats.

Use validated mode briefly when tuning

Enable validated + log-mismatch for a short session to calibrate heuristic accuracy for your model and prompt style.

Related

Context Budgeter CLI

Allocate token budgets per segment

Context Management

Full context system overview