agent-cost-estimator

Report token usage and estimated USD cost of an AI agent session, parsed from the harness's local logs. Ships with a Mistral Vibe adapter; other AI harnesses plug in through the adapter interface.

The result is a local estimate priced from pricing.json. The authoritative monthly usage is your provider's console (for Mistral: admin.mistral.ai/subscription).

Install

pip install .        # from this directory
# or run in place:
python -m agent_cost_estimator --help

Usage

agent-cost-estimator                        # session: $2.11, turn: $2.50
agent-cost-estimator -d                     # the full report table
agent-cost-estimator -s                     # session cost only, e.g. 2.1148
agent-cost-estimator -t                     # latest turn cost only
agent-cost-estimator -d --turns             # table plus per-turn breakdown
agent-cost-estimator --session-id 5732da2a  # a specific session id or path
agent-cost-estimator --json                 # machine-readable output
agent-cost-estimator --list-harnesses       # available adapters

With no output flag the tool prints one line: what the whole session costs and what the latest turn cost. -d/--details prints the full table; -s/--session and -t/--turn print one bare number each, for scripting. The turn cost is the most recent turn in the journal window.

Prices come from the bundled agent_cost_estimator/pricing.json, keyed by model (with a default fallback). Bring your own table:

agent-cost-estimator --pricing my-prices.json

Or persist overrides into the pricing table (the built-in one, or the file passed with --pricing):

agent-cost-estimator --model zai-glm-5-3 \
    --input-price 1.2 --cached-input-price 0.12 --output-price 6.0 \
    --update-pricing          # add --dry-run to preview

pricing.json format

{
  "currency": "USD",
  "models": {
    "default":     {"input_price": 1.5, "cached_input_price": 0.15, "output_price": 7.5},
    "zai-glm-5-3": {"input_price": 1.5, "cached_input_price": 0.15, "output_price": 7.5}
  }
}

Prices are USD per million tokens. Lookup order: session's model name, then its alias, then default. On the command line, --input-price, --cached-input-price, and --output-price override the table for that run.

Adding a harness

A harness adapter is a subclass of agent_cost_estimator.harnesses.base.HarnessAdapter implementing three read-only methods:

• resolve_session_dir(session_arg, home) - find the session directory (or the most recently active one when the argument is None)
• read_meta(session_dir) - return a SessionMeta (title, model_name, alias)
• collect_usage(session_dir) - return a SessionUsage (input/cached/output tokens, call count, per-turn list)

Set name, home_env_var, and home_dir_name so --home and the session lookup have a sane default root. Register the adapter either by adding it to BUILTIN_HARNESSES (in-tree) or by exposing it through the agent_cost_estimator.harnesses entry-point group from your own package:

[project.entry-points."agent_cost_estimator.harnesses"]
mytool = "my_package.adapters:MyToolHarness"

Built-ins always win a name clash; a broken plugin is skipped with a warning.

Development

python -m pytest tests/

Standard library only; no runtime dependencies.