Different credit pools can share one pricing table, so the display key
now reports the pool a session actually bills. Two optional pricing
fields drive it:
- harness_credit_pools ({"vibe": "mistral-vibe", "hermes": "mistral-api"})
for harnesses whose logs do not record the billing API (Vibe session
logs carry only the model name)
- billing_url_pools ({"api.mistral.ai": "mistral-api"}) for harnesses
that do: Hermes logs session_model_usage.billing_base_url, and a URL
match wins over the harness mapping
SessionMeta gains base_url; the Hermes adapter exposes the logged
billing base URL (tolerates older schemas without the column). The pool
overrides the provider part of the display key (mistral-api:mistral-
large-4 for a Hermes session on the pay-as-you-go API, mistral-vibe:
zai-glm-5-3 for a Vibe session), appears as a "credit pool" line in -d
and credit_pool in --json, and the GUI refresh resolver maps
pool-prefixed strings back to the model's real rates. Rates always
come from the matched pricing entry.
Verified live against both harnesses: mistral-vibe:zai-glm-5-3
(Vibe) and mistral-api:mistral-large-4 (Hermes on api.mistral.ai).
Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
12 KiB
Agent Instructions for agent-cost-estimator
This file provides instructions for AI agents working on the agent-cost-estimator project.
Project Overview
agent-cost-estimator is a Python CLI tool that provides real-time visibility into AI agent session costs by reading usage data directly from harness log files.
- Repository: gitea.nolivaldeziii.com/nvaldez/agent-cost-estimator
- Primary Language: Python 3.9+
- License: GPL-3.0-only
- Status: Active development
Development Workflow
Before Starting Work
- Read the SPEC: Review
SPEC.mdto understand the architecture and requirements - Check existing issues: Look at open issues or requests in the repository
- Understand the current state: Run
agent-cost-estimator --skillto see current capabilities
During Development
- Follow the architecture: Maintain the modular design (harness adapters, pricing providers)
- Add tests: All new features must have corresponding tests in
tests/test_agent_cost_estimator.py - Update documentation: Update SPEC.md for any architectural changes
- Track costs: Record AI usage in
.vibe/ai-usage-cost.md
Before Committing
- Run all tests:
python -m pytest tests/test_agent_cost_estimator.py -v - Record AI usage cost:
# Get your current session ID SESSION_ID=$(ls -t ~/.vibe/logs/session/unified/ | head -1) # Get cost for this session agent-cost-estimator --session-id ~/.vibe/logs/session/unified/$SESSION_ID # Add to .vibe/ai-usage-cost.md with commit info - Bump version ALWAYS: Update
pyproject.tomlversion for ANY code change- Bump version BEFORE committing
- Use semantic versioning (MAJOR.MINOR.PATCH)
- PATCH: Bug fixes, small improvements
- MINOR: New features, backward-compatible changes
- MAJOR: Breaking changes, major refactors
- Example: Change
0.2.1to0.2.2for the next commit
- Clear commit messages: Use descriptive commit messages
Commit Message Format
<type>: <description>
<optional body>
Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
Types: feat, fix, docs, refactor, test, chore, bump
Cost Tracking
MANDATORY: All AI-assisted commits must have their cost recorded in .vibe/ai-usage-cost.md
How to Track Costs
-
After completing work on a feature/fix, run:
agent-cost-estimator -d -
Copy the output which shows:
mistral:mistral-medium | session:$X.XX | turn:$Y.YY -
Add an entry to
.vibe/ai-usage-cost.md:### <commit-hash> - <commit-message> - **Date**: YYYY-MM-DD - **Model**: mistral:mistral-medium - **Session Cost**: $X.XX - **Turn Cost**: $Y.YY - **Total for commit**: $Z.ZZ - **Notes**: <any context>
Cost Transparency
- This project tracks AI usage costs to maintain transparency
- Costs help understand the ROI of AI assistance
- All contributors should follow this practice
Architecture Principles
Modular Design
ALWAYS maintain modularity:
-
Harness Adapters: Each AI harness (Vibe, OpenAI, etc.) has its own adapter
- Implement
HarnessAdapterinterface frombase.py - Register via entry point in
pyproject.toml - Never hardcode harness-specific logic in core modules
- Implement
-
Provider Support: Pricing supports multiple AI providers
- Each provider has its own section in
pricing.json - Each provider can have its own currency
- Models can override provider-level settings
- Each provider has its own section in
-
Hook System: Integration hooks are harness-specific
- Vibe CLI hooks go in
hooks/directory - Each harness can have different hook mechanisms
- Vibe CLI hooks go in
File Structure
agent-cost-estimator/
├── agent_cost_estimator/
│ ├── __init__.py # Public API
│ ├── __main__.py # Entry point
│ ├── cli.py # CLI interface (harness-agnostic)
│ ├── core.py # Cost calculations (harness-agnostic)
│ ├── pricing.py # Pricing lookup (harness-agnostic)
│ │
│ ├── harnesses/
│ │ ├── __init__.py # Registry
│ │ ├── base.py # Interface (ABC)
│ │ └── vibe.py # Vibe implementation
│ │
│ ├── hooks/
│ │ └── post_turn.py # Vibe-specific hook
│ │
│ └── skill/
│ └── SKILL.md # LLM instructions
│
├── .vibe/
│ └── ai-usage-cost.md # Cost tracking per commit
│
├── pyproject.toml # Package config
├── pricing.json # Default pricing
├── SPEC.md # This specification
├── AGENTS.md # This file
└── tests/
└── test_agent_cost_estimator.py
Coding Standards
Python
- Type Hints: Use Python type hints for all public functions
- Dataclasses: Use
@dataclassfor data structures (SessionMeta, SessionUsage, etc.) - Error Handling: Use specific exceptions, not generic ones
- Logging: Use
loggingmodule, notprint()for diagnostics - Style: Follow PEP 8, match existing code style
Testing
- Test Coverage: All new code must have tests
- Test File:
tests/test_agent_cost_estimator.py - Test runner: pytest
- Test naming:
test_<feature>_<behavior>(e.g.,test_cli_json_with_custom_pricing)
Documentation
- SPEC.md: Update for architectural changes
- Inline docs: Use Google-style docstrings
- Examples: Include usage examples in docstrings
Specific Guidelines
Adding a New Harness
To add support for a new AI harness (e.g., openai):
-
Create adapter:
touch agent_cost_estimator/harnesses/openai.py -
Implement interface from
base.py:default_home()resolve_session_dir()read_meta()collect_usage()
-
Register adapter in
pyproject.toml:[project.entry-points."agent_cost_estimator.harnesses"] openai = "agent_cost_estimator.harnesses.openai:OpenAITHarness" -
Add tests for the new harness
-
Update SPEC.md with the new harness documentation
-
Add integration support (if applicable) in
integrate_hooks()
Adding a New Provider
To add pricing for a new AI provider:
-
Add to pricing.json:
{ "providers": { "new-provider": { "currency": "USD", "models": { "default": { "input_price": X, "cached_input_price": Y, "output_price": Z }, "model-1": {...}, "model-2": {...} } } } } -
Test the pricing lookup
-
Update SPEC.md if this is a significant provider addition
Common Tasks
Updating Pricing
Pricing lives in agent_cost_estimator/pricing.json. Every model entry has
input_price, cached_input_price, output_price (all USD per million
tokens), a note, a source URL, and the date the prices were verified.
Keep all fields in sync when you touch an entry.
How to update prices in the future:
- Check the official sources online (never rely on memory or third-party blogs):
- Mistral models and marketplace-hosted third-party models: https://docs.mistral.ai/inference/pricing
- Z.ai models (direct API, incl. cached-input and Flash/FlashX variants): https://docs.z.ai/guides/overview/pricing
- Record all three rates per model: input, cached input, and output.
Cached input matters most for agent sessions (most input tokens are cached).
Mistral bills cached input at ~10% of the input rate; Z.ai direct does not
follow that rule (e.g. GLM 5.3 direct: $0.26/M cached vs $0.14 via Mistral's
marketplace) - always take the cached price from the same page as the rate
you record, and say in the
notewhich route the entry prices. Name a provider section after the provider/model prefix the harness logs use (e.g. "zai-glm-5-3" -> the "zai" section), even when the model is billed through another host; then say so in the sectionnote(e.g. the zai section's "(Mistral hosted)" note) so nobody expects a second API account. - Watch for promotional/sale rates. If a price is promotional (e.g.
Mistral Large 4's sale), record the sale rate in the price fields and keep the
regular rate in the
note, so it can be restored when the sale ends. - Update the entry fields: prices,
note(what changed),source(the page you checked), anddate(the day you checked,YYYY-MM-DD). Re-date unchanged entries only when you actually re-verified them. - Display aliases (optional): a provider section may set
provider_aliasand a model entry may setmodel_alias. They change only what the cost tracker displays, never the lookup: the zai section setsprovider_alias: "mistral"so GLM sessions display asmistral:zai-glm-5-3even though the pricing lookup still matcheszai:zai-glm-5-3. Set an alias when the harness logs use one provider prefix but another provider actually bills the model. The CLI's--jsonreports the display key aspricing.model_keyand the raw pricing key aspricing.model_key_raw. - Credit pools (optional):
harness_credit_poolsmaps a harness to the credit pool its sessions bill ("vibe": "mistral-vibe","hermes": "mistral-api") - use this when the harness logs do not record the billing API (Vibe logs only the model name).billing_url_poolsmaps a substring of the logged base URL to a pool ("api.mistral.ai": "mistral-api") - Hermes recordssession_model_usage.billing_base_url, so its pool comes from the data and wins over the harness mapping. The pool overrides the provider part of the display key (mistral-api:mistral-large-4vsmistral-vibe:mistral-large-4) and appears ascredit_poolin the CLI's--json; the rates themselves stay from the matched pricing entry. - Prefer editing
pricing.jsondirectly sonote/source/datestay consistent, or use the CLI for rates-only updates:# Update pricing for a model (writes to the first provider's models) agent-cost-estimator --model my-model --input-price 2.0 --update-pricing # With custom pricing file agent-cost-estimator --pricing custom.json --model my-model --input-price 2.0 --update-pricing - Verify against a real session before committing:
python -m agent_cost_estimator -d # check "prices" and "TOTAL" lines python -m pytest tests/ -v # all tests must pass - Commit: bump the version in
pyproject.toml(PATCH for price/data updates, MINOR for new features like display aliases or credit pools), record the session cost in.vibe/ai-usage-cost.md, and usechore:orbump:in the commit message for pricing-only changes.
Testing Hooks
# Test hook manually
echo '{"session_id": "<uuid>", "hook_event_name": "post_agent"}' | python ~/.vibe/hooks/post_turn.py
# Test with specific session
VIBE_SESSION_DIR=/path/to/session python ~/.vibe/hooks/post_turn.py
Running Tests
# Run all tests
python -m pytest tests/test_agent_cost_estimator.py -v
# Run specific test
python -m pytest tests/test_agent_cost_estimator.py::test_cli_default_compact_line -v
Resources
- SPEC.md: Complete project specification
- SKILL.md: LLM usage instructions
- pricing.json: Pricing configuration reference
- Wiki: hermes-wiki/wiki/entities/agent-cost-estimator/agent-cost-estimator.md
Contacts
- Repository: gitea.nolivaldeziii.com/nvaldez/agent-cost-estimator
- Wiki: hermes-wiki (see hermes-wiki repo)
- Primary Maintainer: nvaldez