TokenEconomy 0.3.2

Token Economy

Token economics for LLM coding agents — one tested source for model pricing (with history), run-cost computation, and token-efficiency model selection. .NET, dependency-free core.

dotnet add package TokenEconomy

Package page: TokenEconomy · GitHub releases

An agent run bills for input, output, and cache tokens at a rate that changes over time, per model. Getting that wrong is not a rounding error: a hard-coded price silently costs the wrong amount for every historic run, and a missing price that defaults to 0 reports a budget as healthy while it drains. TokenEconomy keeps the prices — with their validity dates — and answers two questions from that one source: what did this run cost? and which model buys the most for the tokens I have left? Unknown is always returned as unknown.

Docs & website: https://agent-orchestrator.dev/token-economy/ — a static site built from website/ and deployed by deploy-website.yml (see website/DEPLOY.md).

Research plan: Forecast each task as a percentage of a five-hour cap defines the proposed measurement, uncertainty, repository boundaries, and GO-blocked delivery slices. Its visual explainers are part of the static site. No forecast implementation is authorised yet.

Delegation economy: the pattern guide explains how orchestrators assign bounded work to cheaper model tiers and when to escalate. Prompts and task cards can include the standardized context block verbatim. Task-cutting guide: Dynamic workflows as a task-cutting strategy compares one Claude workflow-sized card with small dependsOn cards using Agent Studio token, review, retry, and gate evidence. It includes the current Claude-only workflow constraint, Codex integration gap, TE-8 routing hook, and a reusable AI-pattern candidate.

Prompt-enrichment analysis: Prompt enrichment before an agent run quantifies rule, embedding, classifier, and hybrid preprocessing against the Agent Studio retry baseline. It specifies the auditable enrichment-report.json contract, a Task Server integration boundary, a selection rubric, and a standalone ai-patterns handoff.

What it does

• Pricing catalog with history — per-model price entries keyed by ValidFrom; a run's cost is computed with the prices valid at the run's timestamp. Historic entries are kept, never overwritten.

• Cost API — ComputeCost(model, usage, atUtc) → deterministic breakdown + total; unknown models return an explicit unknown, never a silent zero.

• Versioned model-routing policy — one embedded, schema-backed knowledge base resolves model aliases, providers/CLIs, reasoning levels, score tiers, correctness floors, workflow exceptions, restrictions, deprecations, reissues, and evidence status. The exact synchronized Agent Studio policy is authoritative; pricing and quota cannot lower its correctness floors. See the generated knowledge view and authoritative policy.

• Token-efficiency compatibility matrix — SuggestModel(taskClass, budgetPressure, availableClis, atUtc) ranks only policy-selectable core models. Use ModelRoutingPolicy for correctness decisions and ModelRoutingKnowledgeBase.FallbacksFor(routeId) for evidence-scoped provider fallbacks. Cost class is derived from the pricing catalog, never restated.

• Agent Studio ingest — reads each card's durable task.json directly and upserts model-run metrics by task key + run. It maps model/provider, usage, price-at-run-time, final-lane outcome signal, timestamps, project, task type, CLI and thinking level; ModelRunViews provides daily per-model, CLI, and project consumption/outcome views with explicit unresolved-cost counts. The filesystem contract is intentionally used over the task-server API so reporting jobs do not require a running server.

• Provider availability snapshot — captures provider/CLI probe state, independently identified quota windows, observed usage/headroom and reset, freshness, conservative warning state, and model-price coverage at one decision instant. Imported runs supply only the separately labelled rate and exhaustion projection; they never replace observed quota. Unknown, stale, suspicious, unavailable, or unpriced inputs cannot render as healthy or as a zero cost. The snapshot is routing evidence, not model selection. See the data contract and rendered snapshot.

• Deterministic routing composition — ModelRouter.Route combines an upfront estimate, the versioned policy and knowledge base, benchmark and trust qualification, workflow capabilities, available CLIs, run-scoped quota/budget state, and an optional operator pin. It returns a selected model/thinking level or an explicit wait/override decision without allowing quota or cost to cross a correctness floor. See the routing API contract.

• Agent Studio admission loop — AgentStudioTaskAdmission.PrepareAttempt stores intake features, consumes the newest classified prior outcome, routes before each attempt against a run-scoped quota snapshot, records the complete decision, and returns either an attempt-local launch route or a closed wait/override disposition. Card configuration is retained separately and is never silently rewritten. See the host integration contract.

• Controlled A/B benchmarks — versioned repository definitions execute the same task against model/effort variants in isolated workspaces, retain raw append-only measurements, and derive deterministic comparison reports. Start with the end-to-end benchmark methodology; the protocol background records the established-suite influences.

• Upfront task complexity — card/repository signals plus measured historical neighbours produce a versioned routing score, confidence, token/reissue forecast, and audit evidence. A host-supplied mini-model rubric is optional. See the design and backtest contract.

• Document-to-text benchmark — a curated PDF/Word/spreadsheet/presentation hard-case corpus runs across every catalog model and derives evidence-linked, per-document-type capability records without turning failures into unsupported claims. See the capability-corpus methodology.

• Native media capability catalog — evidence-dated image, video, music, speech, and dictation rows for Codex, Antigravity, and Claude Code are pulled from the same embedded catalog convention as pricing. Includes the retained N=4 Codex image benchmark and explicit unknown/unverified cost factors. See the capability matrix.

• Model trust ledger — records model capability assertions separately from durable observed-run, benchmark, or audit evidence. Trust is derived from independently verifiable successful artifacts; self-reported claims never raise it, and open high-severity incidents restrict the model.

The trust ledger also keeps an explicit observed-run denominator, violations, and source references, so a per-model/CLI violation rate is null rather than a misleading 0% when no denominator is retained. See historical evidence and rate limits.

Future orchestrator sampling (concept only)

An orchestrator may later use the derived trust level to choose sampling frequency: unverified or provisional model/CLI pairs receive denser audit sampling, while verified pairs may be sampled less often; any open material incident restores dense sampling. This is only a measurement concept. It must not change model selection or override the routing-policy correctness floors, and a small or missing denominator must never be treated as evidence of safety.

Install

dotnet add package TokenEconomy --version 0.2.0

Dependency-free, targets net10.0. The API is pre-1.0 and may still shift — pin a version and watch releases.

Usage

using TokenEconomy;

// The seeded catalog: known Claude 4.x/5 and OpenAI gpt-5.x models.
var breakdown = ModelPriceCatalog.Default.ComputeCost(
    KnownModels.ClaudeOpus48,
    new TokenUsage(Input: 250_000, Output: 12_000, CacheRead: 40_000),
    DateTime.UtcNow);

if (breakdown.HasPrice)
    Console.WriteLine($"{breakdown.Total} {breakdown.Currency}");   // ≈ 1.57 USD
else
    Console.WriteLine(breakdown.Status);   // UnknownModel or NoPriceForDate — never a silent $0

Total is null for an unknown or unpriced model, never 0 — a missing price is always explicit. Prices carry history, so a run at an earlier timestamp is costed with the rate that was valid then.

Typed model ids

KnownModels exposes one ModelId constant for every canonical entry in the default catalog. Pricing and efficiency APIs accept these typed values directly, while ModelId converts implicitly to string for seamless use with existing callers:

var model = KnownModels.ClaudeSonnet5;
var price = ModelPriceCatalog.Default.ResolvePrice(model, DateTime.UtcNow);
var fit = ModelEfficiencyMatrix.Default.SuitabilityOf(model, TaskClass.Feature);

string providerModelId = model;
var customModel = ModelId.Of("provider-model-id");

There is deliberately no implicit conversion from string to ModelId. Dynamic or custom ids must be explicit with ModelId.Of(configurationValue). The existing string overloads remain unchanged for external input and preserve case-insensitive, dot/dash-insensitive, and alias lookup.

The constants are generated from the catalog and checked in. Maintainers can regenerate them with:

dotnet run --project tools/KnownModelsGenerator -- src/TokenEconomy/KnownModels.g.cs

The test suite renders the file in memory and compares its bytes with the checked-in output, so a catalog change without regeneration fails CI.

Selecting the correctness route

using TokenEconomy;

var decision = ModelRoutingPolicy.Default.RecommendCore(new()
{
    Scorecard = new()
    {
        CorrectnessRisk = 24,
        ExpectedScope = 14,
        ContextDemand = 14,
        TaskTypeAndUncertainty = 6,
        EmpiricalConfidence = 6,
        QuotaAndCostHeadroom = 0,
    },
    CorrectnessTriggers = ["persistentStateMigration"],
});

Console.WriteLine($"{decision.Route.ModelId} @ {decision.Route.ThinkingLevel}");
// gpt-5.6-sol @ medium — the score and migration floor both require Sol/medium.

The evaluator accepts no price catalog, cost class, or quota snapshot. Quota and cost headroom contribute only the policy's declared 0-5 intake points; hard floors are applied afterward. Provider availability may select an explicitly equivalent fallback, wait, or require an operator override, but never silently spend correctness margin.

The machine source is src/TokenEconomy/catalog/model-routing-policy.json and is validated against its JSON schema, every price-catalog model, the media catalog's CLI scopes, trust-evidence unknowns, the authoritative Markdown hash, and the deterministic generated public view. Unknown models or levels, unsupported combinations, restrictions, deprecations, and provisional evidence are returned explicitly by ModelRoutingKnowledgeBase.Resolve.

Status

The pricing catalog + cost API were extracted from CodingAgentRunner.Pricing (v0.5.0) into this standalone package (0.1.0); 0.2.0 adds the token-efficiency matrix + SuggestModel. TokenEconomy 0.2.0 is published on nuget.org; release operations and the one-time setup fallback are documented in docs/PUBLISHING.md, with the verified TE-1 operator handoff retained in results/TE-1-nuget-first-publish.md.

Repository layout

website/ is a real part of this repository, not a mirror. It is the public documentation surface at https://agent-orchestrator.dev/token-economy/ — plain static HTML with a checked data step: scripts/generate-website-data.py regenerates website/data/*.json from the committed evidence, and CI rejects stale data, so the published charts and benchmark tables cannot drift from the library. Preview it locally on http://localhost:4340 with:

python -m http.server 4340 --directory website

See website/README.md for the content rules and website/DEPLOY.md for deployment.

Contributing

See CONTRIBUTING.md for build and test steps and the project's invariants. Issues and pull requests are welcome. Report security issues through the private process in SECURITY.md.

Agent Orchestrator ecosystem

TokenEconomy is the token-economics layer of the Agent Orchestrator family. It answers what a run costs and which model to spend the next tokens on; Agent Studio is the orchestrator that turns tasks into agent runs and is the source of the run metrics imported here; the Runner is the process and protocol layer that actually launches the coding-agent CLIs and reports the token usage this library prices; and Agent Chat is the conversation UI for those runs. See the other projects on the Agent Orchestrator website and in the agent-orc GitHub organization.

License

Apache-2.0 © 2026 Robert Mischke. See NOTICE.