Files
agent-cost-estimator/AGENTS.md
T
nvaldez 94e7534a79 feat: credit-pool display (mistral-api vs mistral-vibe)
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>
2026-11-10 20:02:11 +01:00

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

  1. Read the SPEC: Review SPEC.md to understand the architecture and requirements
  2. Check existing issues: Look at open issues or requests in the repository
  3. Understand the current state: Run agent-cost-estimator --skill to see current capabilities

During Development

  1. Follow the architecture: Maintain the modular design (harness adapters, pricing providers)
  2. Add tests: All new features must have corresponding tests in tests/test_agent_cost_estimator.py
  3. Update documentation: Update SPEC.md for any architectural changes
  4. Track costs: Record AI usage in .vibe/ai-usage-cost.md

Before Committing

  1. Run all tests:
    python -m pytest tests/test_agent_cost_estimator.py -v
    
  2. 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
    
  3. Bump version ALWAYS: Update pyproject.toml version 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.1 to 0.2.2 for the next commit
  4. 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

  1. After completing work on a feature/fix, run:

    agent-cost-estimator -d
    
  2. Copy the output which shows:

    mistral:mistral-medium | session:$X.XX | turn:$Y.YY
    
  3. 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:

  1. Harness Adapters: Each AI harness (Vibe, OpenAI, etc.) has its own adapter

    • Implement HarnessAdapter interface from base.py
    • Register via entry point in pyproject.toml
    • Never hardcode harness-specific logic in core modules
  2. 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
  3. Hook System: Integration hooks are harness-specific

    • Vibe CLI hooks go in hooks/ directory
    • Each harness can have different hook mechanisms

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 @dataclass for data structures (SessionMeta, SessionUsage, etc.)
  • Error Handling: Use specific exceptions, not generic ones
  • Logging: Use logging module, not print() 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):

  1. Create adapter:

    touch agent_cost_estimator/harnesses/openai.py
    
  2. Implement interface from base.py:

    • default_home()
    • resolve_session_dir()
    • read_meta()
    • collect_usage()
  3. Register adapter in pyproject.toml:

    [project.entry-points."agent_cost_estimator.harnesses"]
    openai = "agent_cost_estimator.harnesses.openai:OpenAITHarness"
    
  4. Add tests for the new harness

  5. Update SPEC.md with the new harness documentation

  6. Add integration support (if applicable) in integrate_hooks()

Adding a New Provider

To add pricing for a new AI provider:

  1. 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": {...}
          }
        }
      }
    }
    
  2. Test the pricing lookup

  3. 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:

  1. Check the official sources online (never rely on memory or third-party blogs):
  2. 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 note which 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 section note (e.g. the zai section's "(Mistral hosted)" note) so nobody expects a second API account.
  3. 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.
  4. Update the entry fields: prices, note (what changed), source (the page you checked), and date (the day you checked, YYYY-MM-DD). Re-date unchanged entries only when you actually re-verified them.
  5. Display aliases (optional): a provider section may set provider_alias and a model entry may set model_alias. They change only what the cost tracker displays, never the lookup: the zai section sets provider_alias: "mistral" so GLM sessions display as mistral:zai-glm-5-3 even though the pricing lookup still matches zai: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 --json reports the display key as pricing.model_key and the raw pricing key as pricing.model_key_raw.
  6. Credit pools (optional): harness_credit_pools maps 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_pools maps a substring of the logged base URL to a pool ("api.mistral.ai": "mistral-api") - Hermes records session_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-4 vs mistral-vibe:mistral-large-4) and appears as credit_pool in the CLI's --json; the rates themselves stay from the matched pricing entry.
  7. Prefer editing pricing.json directly so note/source/date stay 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
    
  8. 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
    
  9. 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 use chore: or bump: 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