Praison AI

Token Estimation CLI

Configure how PraisonAI estimates token counts from the CLI

python
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.

Diagram

User / CLI

Estimation Mode

Heuristic

Accurate tiktoken

Validated

Context Stats

How It Works

Diagram
Token Estimation CLIAgentUserToken Estimation CLIAgentUserRequestProcess requestResult Agent–>>User: Response

Quick Start

  1. Run an agent with accurate token counts
    python
    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:

    bash
    praisonai chat --context-estimation-mode accurate
# In session: /context stats
  2. Enable mismatch logging for debugging
    bash
    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

FlagValuesDefaultDescription
--context-estimation-modeheuristic, accurate, validatedheuristicHow tokens are counted
--context-log-mismatchflagoffLog when heuristic differs from accurate
bash
# Fast heuristic (default)
praisonai chat --context-estimation-mode heuristic

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

Interactive Commands

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

config.yaml

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