Metadata-Version: 2.4
Name: agent-cost-estimator
Version: 0.2.1
Summary: Report token usage and estimated USD cost of AI agent sessions from local harness logs
Author: nvaldez
License-Expression: GPL-3.0-only
Keywords: ai,agents,llm,tokens,cost,cli,mistral,vibe
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: license-file

# 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

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

## Usage

```bash
agent-cost-estimator                        # mistral:model | session:$X | turn:$Y
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
agent-cost-estimator --integrate            # install Vibe hooks automatically
```

With no output flag the tool prints one line: provider:model and
costs for the session and latest turn. `-d/--details` prints the
full table; `-s/--session` and `-t/--turn` print one bare number
each, for scripting.

Use `--integrate` to automatically set up Vibe CLI hooks:
```bash
agent-cost-estimator --integrate
```
This installs the hook script and configuration, and adds
`agent-cost-estimator` to Vibe's bash allowlist. 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:

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

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

```bash
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

```json
{
  "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:

```toml
[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

```bash
python -m pytest tests/
```

Standard library only; no runtime dependencies.
