@trazum/cli 2.3.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1 +1 @@
1
- {"version":3,"file":"en.d.ts","sourceRoot":"","sources":["../../src/i18n/en.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAqB9C;;;;;;GAMG;AACH,eAAO,MAAM,EAAE,EAAE,WAupGhB,CAAC"}
1
+ {"version":3,"file":"en.d.ts","sourceRoot":"","sources":["../../src/i18n/en.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAqB9C;;;;;;GAMG;AACH,eAAO,MAAM,EAAE,EAAE,WAw4GhB,CAAC"}
package/dist/i18n/en.js CHANGED
@@ -51,9 +51,14 @@ ${bold('USAGE')}
51
51
  trazum rollup <document...|dir> [--json] [--html-out <file>]
52
52
  trazum position <usage.jsonl>
53
53
  trazum receipt <usage.jsonl|dir> [--stamp] [-o <file>]
54
+ trazum bill <file|dir> [--label <name>] [--stamp] [-o <file>]
54
55
  trazum from-claude-code <file|dir> [--label <name>] [-o <file>]
55
56
  trazum from-otel <file|dir> [--label-from-service] [-o <file>]
56
57
  trazum from-litellm <file|dir> [-o <file>]
58
+ trazum from-anthropic <usage.json> [--label <name>] [--label-by-workspace <file>] [-o <file>]
59
+ trazum from-openai <usage.json> [--label <name>] [--label-by-project <file>] [-o <file>]
60
+ trazum from-openrouter <activity.json> [--label <name>] [--label-by-workspace <file>] [-o <file>]
61
+ trazum reconcile <receipt.json> --against <cost.json> [-o <file>]
57
62
  trazum from-helicone <file|dir> [-o <file>]
58
63
  trazum from-langsmith <file|dir> [-o <file>]
59
64
  trazum switch <usage.jsonl> --to <model> [--migration-usd <n>] [--cases <n>]
@@ -162,6 +167,82 @@ ${bold('OPTIONS FOR ownrate')}
162
167
  into trazum.config.json, so the model you run yourself becomes a
163
168
  first-class row in every report, priced by you and marked as such.
164
169
 
170
+ ${bold('OPTIONS FOR reconcile')}
171
+ --against <file> The provider's cost report: Anthropic's
172
+ GET /v1/organizations/cost_report or OpenAI's
173
+ GET /v1/organization/costs, told apart by shape.
174
+ -o, --out <file> Write the comparison there instead of stdout.
175
+
176
+ What Trazum computed beside what the provider billed, and never merged into
177
+ it: two price tables summed into one number is how a report becomes quietly
178
+ wrong. Fetch Anthropic's report with group_by[]=description, OpenAI's with
179
+ group_by[]=line_item, and the difference is attributed - what no token rate
180
+ covers, and for Anthropic what was batch-tier - leaving a remainder that is
181
+ the only figure worth arguing about. OpenAI's report never names batch, so
182
+ there it stays inside the remainder and the run says so. The windows must
183
+ line up or nothing is compared, and a currency with no rate is refused
184
+ rather than converted.
185
+
186
+ ${bold('OPTIONS FOR from-anthropic')}
187
+ --label <name> The project this usage belongs to. The provider
188
+ does not know your project names.
189
+ -o, --out <file> Write the usage log there instead of stdout.
190
+
191
+ Anthropic's own usage report, read as a usage log. You fetch it yourself with
192
+ your own admin credential; this reads the answer, so Trazum never holds a
193
+ provider key. Ask for group_by[]=model, because a row without one cannot be
194
+ priced, and group_by[]=service_tier, because batch is billed at a discount
195
+ and pricing it from a catalogue rate would overstate the bill. Rows at any
196
+ other tier are left out and counted, web search requests are counted and
197
+ never priced from a token rate, and has_more says the bill is one page short.
198
+
199
+ ${bold('OPTIONS FOR from-openai')}
200
+ --label <name> The project this usage belongs to. The provider
201
+ does not know your project names.
202
+ --label-by-project <file> One label per project id, as a JSON array of
203
+ {"project": "proj_…", "label": "name"}. Exact
204
+ match; --label is the fallback.
205
+ -o, --out <file> Write the usage log there instead of stdout.
206
+
207
+ OpenAI's own usage report, read as a usage log, under the same arrangement
208
+ as from-anthropic: your curl, your admin key, and this reads the answer.
209
+ Ask for group_by[]=model, because a row without one cannot be priced, and
210
+ group_by[]=batch, because a batch job is billed at a discount and pricing it
211
+ from a catalogue rate would overstate the bill. Any service tier but default
212
+ is left out and named. Audio and image tokens are never priced at a text
213
+ rate: a row carrying them is reduced to its text part and the rest is
214
+ counted where you can see it.
215
+
216
+ ${bold('OPTIONS FOR bill')}
217
+ --label <name> The project this usage belongs to, for the
218
+ shapes that take one.
219
+ --stamp Stamp the receipt with the time it was written.
220
+ -o, --out <file> Write the receipt there instead of stdout.
221
+
222
+ One door. Reads a file or a directory, tells each file's shape from its own
223
+ text - a Claude Code transcript, OTel spans, a LiteLLM, Helicone or LangSmith
224
+ export, an Anthropic, OpenAI or OpenRouter report, or a plain usage log -
225
+ converts it with the same converter the dedicated command uses, prices it,
226
+ and ends on the receipt. A file no shape claims is named, not guessed; a
227
+ file two shapes claim is named as ambiguous and left alone; a provider's
228
+ cost report is pointed at reconcile. Each file's line says how many rows
229
+ were left out, and the dedicated from-<shape> command says why.
230
+
231
+ ${bold('OPTIONS FOR from-openrouter')}
232
+ --label <name> The project this usage belongs to.
233
+ --label-by-workspace <file> One label per workspace id, as a JSON array of
234
+ {"workspace": "…", "label": "name"}. Exact
235
+ match; --label is the fallback. Needs the report
236
+ fetched with group_by=workspace.
237
+ -o, --out <file> Write the usage log there instead of stdout.
238
+
239
+ OpenRouter's activity report (GET /api/v1/activity, management key, the last
240
+ thirty days), read as a usage log keyed by the same model slugs the
241
+ OpenRouter pricing overlay uses, so hundreds of models are priceable at
242
+ once. What OpenRouter charged is printed beside Trazum's figure and never
243
+ merged into it. Reasoning tokens are counted and not added, because the
244
+ schema does not say whether the completion count already holds them.
245
+
165
246
  ${bold('OPTIONS FOR from-helicone')}
166
247
  -o, --out <file> Write the usage log there instead of stdout.
167
248
 
@@ -1581,6 +1662,96 @@ ${bold('EXAMPLES')}
1581
1662
  unparseable: (count) => `${count} line(s) did not parse as JSON.`,
1582
1663
  written: (file) => `Wrote ${file}.`,
1583
1664
  },
1665
+ reconcile: {
1666
+ noReceipt: () => 'reconcile needs a receipt and a cost report: trazum reconcile receipt.json --against cost.json',
1667
+ noReport: () => 'reconcile needs --against <cost report>: the JSON from Anthropic\'s GET /v1/organizations/cost_report or OpenAI\'s GET /v1/organization/costs.',
1668
+ receiptUnreadable: (file) => `${file}: not readable as JSON.`,
1669
+ notAReceipt: (file) => `${file}: not a receipt. It needs total.usd and span.fromMs/toMs, which "trazum receipt" writes.`,
1670
+ reportUnreadable: (file) => `${file}: not found.`,
1671
+ notAReport: (file) => `${file}: not the JSON a cost report endpoint returns, Anthropic's or OpenAI's. Pass the response body whole.`,
1672
+ summary: (computed, billed, difference) => `Trazum computed $${computed.toFixed(2)}; the provider billed $${billed.toFixed(2)}. Difference: $${difference.toFixed(2)}.`,
1673
+ notTokens: (usd) => `$${usd.toFixed(2)} of that is billed for something no token rate covers: web search, code execution, session usage. Trazum prices tokens and never claimed to cover these.`,
1674
+ batch: (usd) => `$${usd.toFixed(2)} of it is batch-tier, which from-anthropic leaves out rather than price at a catalogue rate.`,
1675
+ remainder: (usd) => `$${usd.toFixed(2)} is left over, and it is the only figure here worth arguing about: the same standard-tier tokens priced two ways, or usage your log never saw. A negative one means Trazum priced more than you were charged, which is a stale rate in the direction that costs you money.`,
1676
+ notAttributable: () => 'The difference cannot be attributed: this report was not grouped by description, so no row says whether it was tokens, a web search or a batch. Add group_by[]=description.',
1677
+ notAttributableByLineItem: () => 'The difference cannot be attributed: this report was not grouped by line item, so no row says what the money was for. Add group_by[]=line_item.',
1678
+ batchNotSeparable: () => 'This report never says whether a line was a batch job, so a batch discount, if any, is inside that remainder rather than taken out of it.',
1679
+ unknownUnit: (usd) => `$${usd.toFixed(2)} of the remainder is on line items whose unit is null: the report says no single unit applies, so it is neither counted as tokens nor as not. It is named here so the remainder does not stand on a unit nobody stated.`,
1680
+ windowNotCovered: (fromComputed, toComputed, fromBilled, toBilled) => `These are not the same window. The receipt covers ${fromComputed} to ${toComputed}; the report covers ${fromBilled} to ${toBilled}. A receipt set against a bill for other days is a wrong number under a right title, so nothing was compared.`,
1681
+ noBilledWindow: () => 'The cost report has no time buckets, so there is no window to compare against.',
1682
+ otherCurrency: (list) => `The report carries ${list} beside USD. Summing two currencies into one total needs a rate, and inventing one is the thing this product exists not to do. Nothing was compared.`,
1683
+ truncated: () => 'The report says has_more: true, so the billed figure is one page short and the difference is understated by whatever you did not fetch.',
1684
+ unreadableAmount: (count) => `${count} row(s) carried an amount that is not a number. They are counted, never read as zero: a zero would quietly shrink the bill.`,
1685
+ written: (file) => `Wrote ${file}.`,
1686
+ },
1687
+ fromAnthropic: {
1688
+ noPath: () => 'from-anthropic needs the usage report your own curl produced: trazum from-anthropic usage.json --label billing',
1689
+ notFound: (path) => `${path}: not found`,
1690
+ summary: (buckets, rows) => `${buckets} time bucket(s), ${rows} usage row(s) read.`,
1691
+ unnamedModel: (count) => `${count} row(s) named no model and are not in the output: the report was not grouped by model, so nothing on the row says what answered. Add group_by[]=model to the request.`,
1692
+ nonStandardTier: (count) => `${count} row(s) were billed at a tier a catalogue rate is not the rate for (batch, priority, flex) and are not in the output. Pricing them from the standard rate would overstate the bill and look right doing it.`,
1693
+ tierUnknown: () => 'The report never named a service tier, so a batch row and a standard row are indistinguishable here. Everything was read as standard. Add group_by[]=service_tier if any of this usage is batched.',
1694
+ webSearch: (count) => `${count} web search request(s) are in this report and in no line of the output: server tools are billed per request, not per token, so no token rate reaches them.`,
1695
+ truncated: () => 'The report says has_more: true. This is one page of several and a bill built from it is understated. Follow next_page until has_more is false, and convert each page.',
1696
+ unparseable: () => 'That is not the JSON GET /v1/organizations/usage_report/messages returns. Pass the response body whole, not a field of it.',
1697
+ labelledByWorkspace: (count) => `${count} row(s) took their label from the workspace mapping.`,
1698
+ unruledWorkspace: (count) => `${count} row(s) carried a workspace no rule names. They keep --label if you gave one and are unattributed if you did not: a workspace nobody wrote a rule for is better unattributed than attributed to a neighbour.`,
1699
+ workspaceNotGrouped: () => 'A workspace mapping was given and no row carried a workspace id, so the split you asked for was not made. Either the report was not grouped by workspace or this organisation uses only the default one, and nothing here can tell those apart. Add group_by[]=workspace_id.',
1700
+ rulesUnreadable: (file) => `${file}: not readable as a workspace mapping. It is a JSON array of {"workspace": "wrkspc_…" | null, "label": "name"}.`,
1701
+ ruleBad: (file, at) => `${file}: entry ${at} is not a rule. Each needs a "label" and a "workspace", which may be null for the default workspace but may not be missing: a missing field is a typo and null is a decision.`,
1702
+ rulesEmpty: (file) => `${file}: no rules in it. You passed --label-by-workspace to narrow something, and an empty file would silently narrow nothing.`,
1703
+ written: (file) => `Wrote ${file}.`,
1704
+ },
1705
+ fromOpenai: {
1706
+ noPath: () => 'from-openai needs the usage report your own curl produced: trazum from-openai usage.json --label billing',
1707
+ notFound: (path) => `${path}: not found`,
1708
+ summary: (buckets, rows, requests) => `${buckets} time bucket(s), ${rows} usage row(s) read, covering ${requests} request(s).`,
1709
+ unnamedModel: (count) => `${count} row(s) named no model and are not in the output: the report was not grouped by model, so nothing on the row says what answered. Add group_by[]=model to the request.`,
1710
+ batch: (count) => `${count} row(s) were batch jobs and are not in the output: batch is billed at a discount, and pricing it from a catalogue rate would overstate the bill and look right doing it.`,
1711
+ batchUnknown: () => 'The report never said whether anything was batch, so a batch row and a standard row are indistinguishable here. Everything was read as standard. Add group_by[]=batch if any of this usage is batched.',
1712
+ nonDefaultTier: (count, tiers) => `${count} row(s) were at a service tier a catalogue rate is not the rate for (${tiers}) and are not in the output. The schema does not list the tiers, so they are named rather than guessed at.`,
1713
+ tierUnknown: () => 'The report never named a service tier. Everything was read as the default tier. Add group_by[]=service_tier if any of this usage runs on another.',
1714
+ mixed: (rows, tokens, cacheWrites) => `${rows} row(s) carried audio or image tokens, which a text rate is not the rate for. Each was reduced to its text part; ${tokens} audio and image token(s) are in no line of the output${cacheWrites > 0 ? `, and ${cacheWrites} cache-write token(s) on those rows were left out too, because the report gives them no modality` : ''}.`,
1715
+ unsplit: (count) => `${count} row(s) carried audio or image tokens and no text split to reduce them by, and are not in the output. Pricing them at a text rate would be a guess.`,
1716
+ truncated: () => 'The report says has_more: true. This is one page of several and a bill built from it is understated. Follow next_page until has_more is false, and convert each page.',
1717
+ unparseable: () => 'That is not the JSON GET /v1/organization/usage/completions returns. Pass the response body whole, not a field of it.',
1718
+ labelledByProject: (count) => `${count} row(s) took their label from the project mapping.`,
1719
+ unruledProject: (count) => `${count} row(s) carried a project no rule names. They keep --label if you gave one and are unattributed if you did not: a project nobody wrote a rule for is better unattributed than attributed to a neighbour.`,
1720
+ projectNotGrouped: () => 'A project mapping was given and no row carried a project id, so the split you asked for was not made. Add group_by[]=project_id.',
1721
+ rulesUnreadable: (file) => `${file}: not readable as a project mapping. It is a JSON array of {"project": "proj_…", "label": "name"}.`,
1722
+ ruleBad: (file, at) => `${file}: entry ${at} is not a rule. Each needs a "project" id and a "label", both non-empty strings.`,
1723
+ rulesEmpty: (file) => `${file}: no rules in it. You passed --label-by-project to narrow something, and an empty file would silently narrow nothing.`,
1724
+ written: (file) => `Wrote ${file}.`,
1725
+ },
1726
+ bill: {
1727
+ noPath: () => 'bill needs a file or a directory to read: trazum bill ~/.claude/projects',
1728
+ notFound: (path) => `${path}: not found`,
1729
+ noFiles: (path) => `${path}: no .json, .jsonl or .ndjson files under it.`,
1730
+ file: (path, shape, records, leftOut) => `${path}: ${shape}${records === null ? ', read as it is' : `, ${records} record(s)`}${leftOut > 0 ? `, ${leftOut} row(s) left out. Run trazum from-${shape} on it for the reasons.` : '.'}`,
1731
+ unknown: (path) => `${path}: no shape this tool reads claims it, so it was not guessed at and is not in the bill.`,
1732
+ ambiguous: (path, shapes) => `${path}: claimed by more than one shape (${shapes}), so it was not converted. Run the dedicated from-<shape> command on it and say which.`,
1733
+ costReport: (path) => `${path}: a provider's cost report, which is a bill rather than usage. Set it beside a receipt with trazum reconcile.`,
1734
+ nothingRead: () => 'Nothing here was a usage source this tool reads, so there is nothing to bill.',
1735
+ sources: (read, seen) => `${read} of ${seen} file(s) read as usage.`,
1736
+ written: (file) => `Wrote ${file}.`,
1737
+ },
1738
+ fromOpenrouter: {
1739
+ noPath: () => 'from-openrouter needs the activity report your own curl produced: trazum from-openrouter activity.json --label billing',
1740
+ notFound: (path) => `${path}: not found`,
1741
+ summary: (rows, days, requests) => `${rows} activity row(s) read over ${days} day(s), covering ${requests} request(s).`,
1742
+ reportedUsage: (usd, byokUsd) => `OpenRouter says it charged $${usd.toFixed(4)}${byokUsd > 0 ? ` plus $${byokUsd.toFixed(4)} billed upstream on your own keys` : ''}. That figure is OpenRouter's, printed beside Trazum's and never merged into it: two price tables summed into one number is how a report becomes quietly wrong.`,
1743
+ reasoning: (tokens) => `${tokens} reasoning token(s) are in this report and were not added to any record: the schema does not say whether completion_tokens already includes them, and adding them if it does would charge reasoning twice.`,
1744
+ unnamedModel: (count) => `${count} row(s) named no model and are not in the output: nothing on the row says what answered.`,
1745
+ undated: (count) => `${count} row(s) carried a date that is not a YYYY-MM-DD day and are not in the output.`,
1746
+ unparseable: () => 'That is not the JSON GET /api/v1/activity returns. Pass the response body whole, not a field of it.',
1747
+ labelledByWorkspace: (count) => `${count} row(s) took their label from the workspace mapping.`,
1748
+ unruledWorkspace: (count) => `${count} row(s) carried a workspace no rule names. They keep --label if you gave one and are unattributed if you did not.`,
1749
+ workspaceNotGrouped: () => 'A workspace mapping was given and no row carried a workspace id, so the split you asked for was not made. Fetch the report with group_by=workspace.',
1750
+ rulesUnreadable: (file) => `${file}: not readable as a workspace mapping. It is a JSON array of {"workspace": "…", "label": "name"}.`,
1751
+ ruleBad: (file, at) => `${file}: entry ${at} is not a rule. Each needs a "workspace" id and a "label", both non-empty strings.`,
1752
+ rulesEmpty: (file) => `${file}: no rules in it. You passed --label-by-workspace to narrow something, and an empty file would silently narrow nothing.`,
1753
+ written: (file) => `Wrote ${file}.`,
1754
+ },
1584
1755
  fromHelicone: {
1585
1756
  noPath: () => 'from-helicone needs a request export or a directory: trazum from-helicone requests.json',
1586
1757
  notFound: (path) => `${path}: not found`,
@@ -1633,6 +1804,10 @@ ${bold('EXAMPLES')}
1633
1804
  written: (file) => `Wrote ${file}.`,
1634
1805
  stateNeedsFile: () => '--state reads one transcript, not a folder: the state ties an offset in the transcript to a length of the output, and several transcripts appending to one output have no single such length. Point it at the .jsonl file.',
1635
1806
  stateNeedsOut: () => '--state needs --out: there is nothing to resume against when the records go to stdout.',
1807
+ cwdRulesUnreadable: (file) => `${file}: --label-by-cwd wants a JSON file holding a list, like [{"prefix": "/work/api", "label": "api"}].`,
1808
+ cwdRuleBad: (file, at) => `${file}: entry ${at} needs a non-empty "prefix" and "label", both strings. Nothing is guessed from a path here, so an entry that is not a rule is refused rather than skipped.`,
1809
+ cwdRulesEmpty: (file) => `${file}: no rules in it, so every line would fall back to --label or to nothing. Write a rule or drop the flag.`,
1810
+ labelledByCwd: (rules) => `Labelled by working directory, ${rules} rule(s). The directory decides which of your labels applies and never reaches the output.`,
1636
1811
  resumed: (skipped, offset) => skipped === 0
1637
1812
  ? `Read the transcript in full and recorded a resume point at byte ${offset}.`
1638
1813
  : `Resumed at byte ${skipped}, so ${skipped} byte(s) were not re-read. Next resume point: byte ${offset}.`,