Know what an AI task really costs, and what its result is worth.
Verovo connects buyer logs, supplier charges, financial records and business outcomes. Review charges and delivery, allocate direct and shared costs to tasks, and calculate cost per verified success and ROI when the evidence supports it.
For teams buying or operating AI services, the output is a reproducible economic record: task costs, allocation rules, verified results and explicit evidence gaps. The local economics command runs on an explicit case, and intake assembles that case from a local billing-period bundle; automated optimization and insurance remain future work. Feature status and build/integrate decisions.
Website · 中文 · Product definition · Buyer task guide
This repository grew out of an audit: ~110 AI usage/cost tools were fed a synthetic fixture whose expected total can be computed by hand, and the tools' own parsers were run against it. 65+ evidence-backed findings; most tools were clean, and the ones that were not failed in five specific classes (per-block re-summation, re-emitted events, cache-pricing semantics, price-table drift, resume/fork loss).
- The report: The Token-Accounting Bug Report
- Three single-page cases with every number sourced and dated: launch case cards
- What the audit taught about its own method: one assertion was corrected by real data, and that rule now applies to every finding (codeburn #1264)
Merge counts are reported as of the date they were taken and are never kept as a single hand-edited number: 14 merged at report publication (2026-09-09), 23 merged or accepted per the claims index (2026-10-11). A GitHub search for the author's merged PRs counts the whole account, not audit fixes, so it is not a substitute for either figure.
| Workflow | Question | Useful next step |
|---|---|---|
| Charge review | Do the charges match the applicable rules and records? | Reconcile, pay, request evidence or ask the supplier to review a difference |
| Task economics | What does each task cost, including shared expenses? | Compare cost per verified success and evidence-backed business value |
| Delivery review | Does the work meet the buyer’s stated requirements? | Accept, request remediation, adjust scope or decide on renewal |
Run either workflow independently or combine them. Correct charges do not establish successful delivery; poor delivery does not automatically establish incorrect billing. Missing evidence remains UNPROVABLE.
Our users are business and engineering owners accountable for AI spending or results, with finance and procurement as collaborators. AI support is an initial application scenario. Coding agents, automation platforms, tools/APIs and model services belong to the wider scope; coverage is verified task by task.
git clone https://github.com/roy-tong/Verovo.git
cd Verovo
python3 healthcheck/verovo economics --case examples/task-economics.json --json economics.json --markdown economics.mdThe synthetic case has two tasks, USD 43.50 in total costs and one verified success. A duplicate financial row is flagged and excluded. The verified USD 100 value yields ROI 1.2989. These are demonstration inputs, not customer results. Use your own explicit records and review coverage before making a financial decision.
The review command is part of the v0.13.0 release.
Python 3.9+, standard library only:
git clone https://github.com/roy-tong/verovo.git
cd verovo
python3 healthcheck/verovo review --sample --html buyer-review.html --json buyer-review.jsonThe synthetic example returns charges: PASS, delivery: FAIL, and one missing
delivery observation as UNPROVABLE. Open buyer-review.html to inspect both lanes,
criteria, rule references, observed values and evidence hashes. Every report carries
three conclusion levels, kept separate: Level 1 rule consistency (what the run
establishes), Level 2 evidence credibility (rule applicability, source truth, coverage —
reported as not established when absent), Level 3 the buyer business decision (outside
the tool). The six operating stages — Intake → Source Check → Rule Resolution →
Reconciliation → Delivery Assessment → Buyer Decision — map each step to a command in
docs/review-method/buyer-review-stages.md.
View the synthetic report.
Agent hosts can call the same review read-only via MCP (verovo-mcp: verovo_review,
verovo_review_template, verovo_recount, verovo_invoice_intake, verovo_period_intake;
no write or submit actions exposed).
To review your own task, copy the task and observation examples
and follow the input guide. Checks compare supplied criteria
with values in local JSON files. A person must confirm rule applicability and source
truth; the tool does not infer contract terms or judge arbitrary AI output quality.
Install the current CLI release:
python3 -m pip install "verovo==0.13.0"
verovo recount --sampleThe verovo project is published on PyPI. The Provider SDK
(@verovo/mcp) has its own release number and is not tied to the CLI version.
prepare maps supported exports; recount applies a selected vendor rule set;
dispute organizes supported differences; recovery records supplier responses
and realized corrections separately. A rule-priced finding is not recovered money.
Recount examples · Periodic reconciliation
| Capability | Current boundary |
|---|---|
| Buyer review (main preview) | Explicit charge/delivery criteria, local JSON evidence, separate results and offline HTML/JSON; no universal contract parser |
| Supported billing recounts | Selected export formats and versioned rules; applicability must be reviewed |
| Buyer Ledger | Local tool-bill processing and 26 catalog entries; cataloged does not mean connected or validated on real customer bills |
| Developer diagnostics | Local coding-agent log checks, measurement conformance and regression fixtures |
| Task economics (main preview) | Local task/run/usage/cost/outcome case → direct and allocated cost, cost per verified success, ROI when verified value exists; unallocated and unverified items stay explicit. Cost drivers and scenario-based proposals build on the same case |
| Human buyer review | Scope and fees discussed for a concrete task; commercial acceptance and repeat purchase remain under validation |
verovo economics --case case.json --json out.json --markdown out.md connects
business tasks, agent runs, financialized usage, invoices/cost items and verified
outcomes. Costs are never added across currencies; duplicate financial rows are
reported rather than summed; missing task/run links and shared costs without an
allocation rule stay unallocated; unverified outcomes do not enter the
cost-per-verified-success denominator. See the
case schema and
design boundary. The command is local and makes no
network calls.
To avoid hand-writing the case, assemble it from a period bundle:
python3 healthcheck/verovo intake --bundle examples/period-bundle --out ./period-out
python3 healthcheck/verovo economics --case ./period-out/case.json --markdown economics.mdThe bundle manifest names local traces, usage rows, bills, outcomes and optional
invoices. Intake reconciles a bill with financialized usage by charge_id, keeps
unallocated costs, currency mismatches and unverified outcomes as named open
items, and refuses to fabricate a precise ROI when the period is incomplete. See
period intake.
Once the case exists, look at where the money goes and what could change:
python3 healthcheck/verovo drivers --case ./period-out/case.json
python3 healthcheck/verovo optimize --case ./period-out/case.json --scenario scenarios.jsondrivers separates recorded from attributable cost and keeps not-recorded /
not-separable buckets visible. optimize applies explicit assumptions
(scale_cost, drop) to a copy of the case, re-runs the same economics and
attaches a verification plan to every proposal; nothing is auto-applied and no
saving is claimed. See cost drivers and scenarios.
Buyer Ledger · Coverage limits · Developer CLI · Conformance
Describe a billing, acceptance or renewal task: name the service, account or task, decision date, available record types and owner. You can request delivery review without first finding a billing discrepancy.
Free measurement lane / 免费测量通道: bring 20–100 sanitized rows to issue #6 or the website form — 免费：带 20–100 行脱敏数据提交到 issue #6 或官网表单。
Providers reviewing upstream spend are buyers in that transaction. Provider-side work for downstream billing is an extension triggered by a concrete customer dispute, revenue discrepancy or procurement requirement. It does not redefine the buyer focus.
The existing free measurement runs retain their separate sample-based scope. No fixed enterprise price or recovery promise is published. Scope and any fee are agreed before commissioned work.
Local CLI commands do not upload data. Optional GitHub-hosted workflows upload to GitHub and require a private repository; do not put private bills in public issues. Synthetic fixtures and test results establish engineering behavior, not customer adoption, economic recovery or paid demand.
Launch case cards — every number sourced and dated: tokendash #37 (one message billed as three), claude-hud #758 (1-hour cache writes at the 5-minute rate), VibeMirror-coder-001 (an independent re-measurement through the free lane). Index and walkthrough images: docs/launch.
CI · Claims and reproductions · Roadmap · Contributing · Agent instructions
The standard, SDK, rules and reusable checks support these workflows and remain open source. MIT license.
Verovo provides an optional, local invoice2data adapter for supplier PDF/image/text invoice files. Extraction is not booked to the economics ledger, and it never infers taxes, credits, refunds, foreign exchange or task allocation.
pip install invoice2data
python3 healthcheck/verovo invoice-intake --file ./invoice.pdf --json ./invoice-draft.jsonA vendor-specific template may be needed. The result includes a source SHA-256 and explicit `review_status: unreviewed` and `cost_ledger_status: not_imported` fields. Review the original invoice and contractual rules before assigning costs. Core Verovo remains standard-library-only. See feature status.