Token use

What BLOM records

Each use of a model is a token report. A report records:

• whose use it was, a person's or an agent's, such as Codex · Grace Hopper;
• the model and its provider, or why the model isn't known;
• input and output tokens, and cache write and cache read tokens when the tool gives them;
• whether the counts were measured by the tool or the provider, or are the reporter's estimate;
• when the use happened, or why that isn't known;
• the work it was for, such as a task and its next action. BLOM works out the step and the activity from them.

BLOM counts tokens as they were reported, entered, or imported. A count that wasn't given reads not reported, never 0. A report decides nothing: no gate, approval, claim, or next action reads it.

Use reaches BLOM three ways: agents report their own, people enter what a tool shows them, and BLOM imports your AI providers' records of use.

How agents report their use

An agent reports only its own use, along with the work it hands back to BLOM:

• With a completion. When an agent completes a next action with blom_complete, it can include up to 50 entries of its model use. BLOM records them against that task and next action.
• With a closure. A closure returned with blom_return_closure can carry a session report that covers the next actions it names. BLOM spreads the counts evenly across them and marks them Spread by BLOM.

Each use belongs in one report: with the completion or with the closure, never both. A reference, the tool's own identifier for the use, makes a repeated report count once. An agent's completion that reports no use counts as not reported, so the gap stays visible. See Start, refresh, and return.

Enter token use

Enter use from a tool that tells BLOM nothing, for yourself or for an agent you're accountable for. Any member can enter their own use, Viewers included, and an Administrator can enter it for any active agent.

1. Open Enter token use

   Select Enter token use on Token use or Token reports, or in a task's Token use section, where the task is already set.

2. Say whose use it was

   Under Whose use, choose Your own, or An agent's and then the Agent.

3. Name the model and the tokens

   Choose The tool names it and enter the Model name and the Provider, in lower case, such as anthropic. Or choose I don't know the model and say why. Enter Input tokens and Output tokens. Under Cache tokens, choose Not known, or The tool gives them and enter both.

4. Say how and when

   Under How were they counted?, choose Measured, by the tool or the provider or My estimate. Under When, give From and To, or choose Not known and say why.

5. Add what you know

   A Reference (optional), your tool's identifier for this use, makes entering it twice count once. Under Task (optional), choose the task it was for, or leave Not for a task, or I don't know. Add a Reason (optional) if you like.

6. Record it

   Select Record token use. BLOM says when it recorded the report, with Open the report. If that reference was recorded before, BLOM says so and counts nothing again.

Besides a task, an entry can name the work it was for as a review, a document revision being drafted, a commit or pull request being built, or an item and its version. People can also enter and read token use through the public API: see The public API.

Provider imports, costs, and budgets

BLOM imports your AI providers' records of use. A provider's measured count replaces the counts of the report it matches, and never adds to them. A provider record that matches no report counts apart until a person links it to a report or confirms it.

BLOM shows what the use cost at your providers' prices, by task, item, agent, and period. Set budgets and caps for your organization, with alerts as use nears them.

The Token use screen

Select Organization at the foot of the rail, then Token use. Days count in the organization's time zone, which the screen names. Choose a Period: Last 7 days, Last 30 days (the default), This month, Last month, Last 12 months, or Choose days with From and To. Show it by Day or Month.

Totals

The period's input, output, cache, and total tokens, by day or month and model, and by model over the period. Notes under them say how much rests on an estimate or a spread, what wasn't reported, and how much use reached no item.

Not attributed

Use that reached no item, by day and task. It counts in the organization's use, and in no item's ledger or product's total.

Your use

Your own use, with Open your reports.

By person or agent

Each person's and agent's use, by model, and whether an agent named its session. Organization Administrators see this tab, and so does anyone an Administrator grants the permission to see token use by person or agent.

Totals leave out use on records you can't see, and the screen says when they do.

Token reports

Select Open token reports to see each report as it was reported or entered, with its corrections, newest first. You see your own reports and those of agents you're accountable for. An Administrator sees everyone's, and so does anyone granted the permission to see token use by person or agent.

Filter by Person or agent: Everyone you can see, You, or Agents you're accountable for. Filter by Source: Reported by an agent or Entered by a person. Select Include voided reports to see those too. Each row's Basis says how its counts stand: Measured, Estimate · by the reporter, or Spread by BLOM.

Select a report's time under Recorded to open it. A report shows every field as recorded, the step and activity BLOM worked out, and How it reaches items. A session report also lists its Lines: each next action it covered, with its share.

Correct or void a report

The person who entered a report can correct or void it. So can the person whose use it was, the accountable owner of the agent whose use it was, and an organization Administrator.

• Correct changes which task a report was for. Choose the Task, or Not for a task, give a Reason, and select Record the correction. The report counts there from now on, marked Corrected, with its original values kept.
• Void takes a report out of every total. Give a Reason and select Void the record. The report stays visible, marked voided with your reason. To count the use again, enter it again.

The tokens, the model, the period, and how the tokens were counted can't be corrected: void the report and report it again. A session report's covered next actions are put right the same way.

On tasks, items, and products

A report reaches items through its work: the items its task's brief targets, an item the report names, or the home of a document revision being drafted. When Claude · Ada Lovelace reports use while working on Job invite-expiry-build, and the Job's brief targets Invitations, that use reaches Invitations.

• A task's page has a Token use section: the task's counts, its use By step, activity, and model, and each next action's use. Administrators, and anyone granted the permission to see token use by person or agent, see every next action's use, and others see their own. Select Enter token use with the task set, or Open token reports for this task.
• An item's page has a Token ledger. Show This item, or With everything below, where each report counts once. Group by Step, Activity, Model, Day, or Month, or by Agent if you may see token use by person or agent. Choose a Period, All time or one of the Token use screen's periods, and which Tokens to show.
• A product's Product summary has a Token use card: each item's allocated share, adding up to the product's total, so shared use counts once. Use that reached no item isn't in it.

The ledger keeps shared use apart. Own is use that reached this item alone. Shared is a report's whole use on each item it reached, never added across items. Allocated · estimate is an equal share, an estimate, and adds up across a product.

AI contexts

An AI context is a reading aid for AI on one revision of a document, such as a standard, on one phase of a PDLC version, or on a review: a short description, a reading context, or both. It grants nothing, and nothing reads it to decide. When an agent exports a task's context, the export carries the AI context of each document revision and PDLC phase it supplies, labeled.

In the BLOM app, find them on a standard's page, for the revision shown, in a phase's drawer on PDLC, for a version that isn't a draft, and on a review. Each is labeled Written by a person, or Generated by an agent with the model it named, and shows who wrote it, when, and whether it's Current or stale, and why. Earlier ones stay under Earlier AI contexts.

1. Write one

   Select Write an AI context, or Replace the AI context when there's one already.

2. Add the text

   Enter a Short description of up to 280 characters, a Reading context for AI of up to 32,000, or both. Add a Reason (optional) if you like.

3. Record it

   Select Record the AI context. It replaces the current one, which stays in the history.

Editors and Administrators write and void AI contexts, and Viewers read them. To take one away, select Void the AI context, give a Reason, and select Void the record. Agents attach AI contexts with their completions, naming the model that wrote them.

Related