@trazum/cli 2.2.1 → 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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trazum/cli",
3
- "version": "2.2.1",
3
+ "version": "2.4.0",
4
4
  "description": "Trazum CLI: find where your LLM bill goes, price every finding per month, and enforce token budgets in CI.",
5
5
  "license": "MIT",
6
6
  "author": "David Mu\u00f1oz Rey",
@@ -41,10 +41,10 @@
41
41
  "prepublishOnly": "npm run build && npm test"
42
42
  },
43
43
  "dependencies": {
44
- "@trazum/core": "2.2.1"
44
+ "@trazum/core": "2.4.0"
45
45
  },
46
46
  "devDependencies": {
47
- "@types/node": "^26.2.0",
47
+ "@types/node": "^26.4.0",
48
48
  "typescript": "^7.0.2"
49
49
  },
50
50
  "engines": {
package/src/i18n/en.ts CHANGED
@@ -60,9 +60,14 @@ ${bold('USAGE')}
60
60
  trazum rollup <document...|dir> [--json] [--html-out <file>]
61
61
  trazum position <usage.jsonl>
62
62
  trazum receipt <usage.jsonl|dir> [--stamp] [-o <file>]
63
+ trazum bill <file|dir> [--label <name>] [--stamp] [-o <file>]
63
64
  trazum from-claude-code <file|dir> [--label <name>] [-o <file>]
64
65
  trazum from-otel <file|dir> [--label-from-service] [-o <file>]
65
66
  trazum from-litellm <file|dir> [-o <file>]
67
+ trazum from-anthropic <usage.json> [--label <name>] [--label-by-workspace <file>] [-o <file>]
68
+ trazum from-openai <usage.json> [--label <name>] [--label-by-project <file>] [-o <file>]
69
+ trazum from-openrouter <activity.json> [--label <name>] [--label-by-workspace <file>] [-o <file>]
70
+ trazum reconcile <receipt.json> --against <cost.json> [-o <file>]
66
71
  trazum from-helicone <file|dir> [-o <file>]
67
72
  trazum from-langsmith <file|dir> [-o <file>]
68
73
  trazum switch <usage.jsonl> --to <model> [--migration-usd <n>] [--cases <n>]
@@ -171,6 +176,82 @@ ${bold('OPTIONS FOR ownrate')}
171
176
  into trazum.config.json, so the model you run yourself becomes a
172
177
  first-class row in every report, priced by you and marked as such.
173
178
 
179
+ ${bold('OPTIONS FOR reconcile')}
180
+ --against <file> The provider's cost report: Anthropic's
181
+ GET /v1/organizations/cost_report or OpenAI's
182
+ GET /v1/organization/costs, told apart by shape.
183
+ -o, --out <file> Write the comparison there instead of stdout.
184
+
185
+ What Trazum computed beside what the provider billed, and never merged into
186
+ it: two price tables summed into one number is how a report becomes quietly
187
+ wrong. Fetch Anthropic's report with group_by[]=description, OpenAI's with
188
+ group_by[]=line_item, and the difference is attributed - what no token rate
189
+ covers, and for Anthropic what was batch-tier - leaving a remainder that is
190
+ the only figure worth arguing about. OpenAI's report never names batch, so
191
+ there it stays inside the remainder and the run says so. The windows must
192
+ line up or nothing is compared, and a currency with no rate is refused
193
+ rather than converted.
194
+
195
+ ${bold('OPTIONS FOR from-anthropic')}
196
+ --label <name> The project this usage belongs to. The provider
197
+ does not know your project names.
198
+ -o, --out <file> Write the usage log there instead of stdout.
199
+
200
+ Anthropic's own usage report, read as a usage log. You fetch it yourself with
201
+ your own admin credential; this reads the answer, so Trazum never holds a
202
+ provider key. Ask for group_by[]=model, because a row without one cannot be
203
+ priced, and group_by[]=service_tier, because batch is billed at a discount
204
+ and pricing it from a catalogue rate would overstate the bill. Rows at any
205
+ other tier are left out and counted, web search requests are counted and
206
+ never priced from a token rate, and has_more says the bill is one page short.
207
+
208
+ ${bold('OPTIONS FOR from-openai')}
209
+ --label <name> The project this usage belongs to. The provider
210
+ does not know your project names.
211
+ --label-by-project <file> One label per project id, as a JSON array of
212
+ {"project": "proj_…", "label": "name"}. Exact
213
+ match; --label is the fallback.
214
+ -o, --out <file> Write the usage log there instead of stdout.
215
+
216
+ OpenAI's own usage report, read as a usage log, under the same arrangement
217
+ as from-anthropic: your curl, your admin key, and this reads the answer.
218
+ Ask for group_by[]=model, because a row without one cannot be priced, and
219
+ group_by[]=batch, because a batch job is billed at a discount and pricing it
220
+ from a catalogue rate would overstate the bill. Any service tier but default
221
+ is left out and named. Audio and image tokens are never priced at a text
222
+ rate: a row carrying them is reduced to its text part and the rest is
223
+ counted where you can see it.
224
+
225
+ ${bold('OPTIONS FOR bill')}
226
+ --label <name> The project this usage belongs to, for the
227
+ shapes that take one.
228
+ --stamp Stamp the receipt with the time it was written.
229
+ -o, --out <file> Write the receipt there instead of stdout.
230
+
231
+ One door. Reads a file or a directory, tells each file's shape from its own
232
+ text - a Claude Code transcript, OTel spans, a LiteLLM, Helicone or LangSmith
233
+ export, an Anthropic, OpenAI or OpenRouter report, or a plain usage log -
234
+ converts it with the same converter the dedicated command uses, prices it,
235
+ and ends on the receipt. A file no shape claims is named, not guessed; a
236
+ file two shapes claim is named as ambiguous and left alone; a provider's
237
+ cost report is pointed at reconcile. Each file's line says how many rows
238
+ were left out, and the dedicated from-<shape> command says why.
239
+
240
+ ${bold('OPTIONS FOR from-openrouter')}
241
+ --label <name> The project this usage belongs to.
242
+ --label-by-workspace <file> One label per workspace id, as a JSON array of
243
+ {"workspace": "…", "label": "name"}. Exact
244
+ match; --label is the fallback. Needs the report
245
+ fetched with group_by=workspace.
246
+ -o, --out <file> Write the usage log there instead of stdout.
247
+
248
+ OpenRouter's activity report (GET /api/v1/activity, management key, the last
249
+ thirty days), read as a usage log keyed by the same model slugs the
250
+ OpenRouter pricing overlay uses, so hundreds of models are priceable at
251
+ once. What OpenRouter charged is printed beside Trazum's figure and never
252
+ merged into it. Reasoning tokens are counted and not added, because the
253
+ schema does not say whether the completion count already holds them.
254
+
174
255
  ${bold('OPTIONS FOR from-helicone')}
175
256
  -o, --out <file> Write the usage log there instead of stdout.
176
257
 
@@ -1796,6 +1877,162 @@ ${bold('EXAMPLES')}
1796
1877
  written: (file) => `Wrote ${file}.`,
1797
1878
  },
1798
1879
 
1880
+ reconcile: {
1881
+ noReceipt: () =>
1882
+ 'reconcile needs a receipt and a cost report: trazum reconcile receipt.json --against cost.json',
1883
+ noReport: () =>
1884
+ 'reconcile needs --against <cost report>: the JSON from Anthropic\'s GET /v1/organizations/cost_report or OpenAI\'s GET /v1/organization/costs.',
1885
+ receiptUnreadable: (file) => `${file}: not readable as JSON.`,
1886
+ notAReceipt: (file) =>
1887
+ `${file}: not a receipt. It needs total.usd and span.fromMs/toMs, which "trazum receipt" writes.`,
1888
+ reportUnreadable: (file) => `${file}: not found.`,
1889
+ notAReport: (file) =>
1890
+ `${file}: not the JSON a cost report endpoint returns, Anthropic's or OpenAI's. Pass the response body whole.`,
1891
+ summary: (computed, billed, difference) =>
1892
+ `Trazum computed $${computed.toFixed(2)}; the provider billed $${billed.toFixed(2)}. Difference: $${difference.toFixed(2)}.`,
1893
+ notTokens: (usd) =>
1894
+ `$${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.`,
1895
+ batch: (usd) =>
1896
+ `$${usd.toFixed(2)} of it is batch-tier, which from-anthropic leaves out rather than price at a catalogue rate.`,
1897
+ remainder: (usd) =>
1898
+ `$${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.`,
1899
+ notAttributable: () =>
1900
+ '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.',
1901
+ notAttributableByLineItem: () =>
1902
+ '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.',
1903
+ batchNotSeparable: () =>
1904
+ '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.',
1905
+ unknownUnit: (usd) =>
1906
+ `$${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.`,
1907
+ windowNotCovered: (fromComputed, toComputed, fromBilled, toBilled) =>
1908
+ `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.`,
1909
+ noBilledWindow: () => 'The cost report has no time buckets, so there is no window to compare against.',
1910
+ otherCurrency: (list) =>
1911
+ `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.`,
1912
+ truncated: () =>
1913
+ '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.',
1914
+ unreadableAmount: (count) =>
1915
+ `${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.`,
1916
+ written: (file) => `Wrote ${file}.`,
1917
+ },
1918
+
1919
+ fromAnthropic: {
1920
+ noPath: () =>
1921
+ 'from-anthropic needs the usage report your own curl produced: trazum from-anthropic usage.json --label billing',
1922
+ notFound: (path) => `${path}: not found`,
1923
+ summary: (buckets, rows) => `${buckets} time bucket(s), ${rows} usage row(s) read.`,
1924
+ unnamedModel: (count) =>
1925
+ `${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.`,
1926
+ nonStandardTier: (count) =>
1927
+ `${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.`,
1928
+ tierUnknown: () =>
1929
+ '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.',
1930
+ webSearch: (count) =>
1931
+ `${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.`,
1932
+ truncated: () =>
1933
+ '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.',
1934
+ unparseable: () =>
1935
+ 'That is not the JSON GET /v1/organizations/usage_report/messages returns. Pass the response body whole, not a field of it.',
1936
+ labelledByWorkspace: (count) =>
1937
+ `${count} row(s) took their label from the workspace mapping.`,
1938
+ unruledWorkspace: (count) =>
1939
+ `${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.`,
1940
+ workspaceNotGrouped: () =>
1941
+ '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.',
1942
+ rulesUnreadable: (file) =>
1943
+ `${file}: not readable as a workspace mapping. It is a JSON array of {"workspace": "wrkspc_…" | null, "label": "name"}.`,
1944
+ ruleBad: (file, at) =>
1945
+ `${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.`,
1946
+ rulesEmpty: (file) =>
1947
+ `${file}: no rules in it. You passed --label-by-workspace to narrow something, and an empty file would silently narrow nothing.`,
1948
+ written: (file) => `Wrote ${file}.`,
1949
+ },
1950
+
1951
+ fromOpenai: {
1952
+ noPath: () =>
1953
+ 'from-openai needs the usage report your own curl produced: trazum from-openai usage.json --label billing',
1954
+ notFound: (path) => `${path}: not found`,
1955
+ summary: (buckets, rows, requests) =>
1956
+ `${buckets} time bucket(s), ${rows} usage row(s) read, covering ${requests} request(s).`,
1957
+ unnamedModel: (count) =>
1958
+ `${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.`,
1959
+ batch: (count) =>
1960
+ `${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.`,
1961
+ batchUnknown: () =>
1962
+ '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.',
1963
+ nonDefaultTier: (count, tiers) =>
1964
+ `${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.`,
1965
+ tierUnknown: () =>
1966
+ '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.',
1967
+ mixed: (rows, tokens, cacheWrites) =>
1968
+ `${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` : ''}.`,
1969
+ unsplit: (count) =>
1970
+ `${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.`,
1971
+ truncated: () =>
1972
+ '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.',
1973
+ unparseable: () =>
1974
+ 'That is not the JSON GET /v1/organization/usage/completions returns. Pass the response body whole, not a field of it.',
1975
+ labelledByProject: (count) => `${count} row(s) took their label from the project mapping.`,
1976
+ unruledProject: (count) =>
1977
+ `${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.`,
1978
+ projectNotGrouped: () =>
1979
+ '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.',
1980
+ rulesUnreadable: (file) =>
1981
+ `${file}: not readable as a project mapping. It is a JSON array of {"project": "proj_…", "label": "name"}.`,
1982
+ ruleBad: (file, at) =>
1983
+ `${file}: entry ${at} is not a rule. Each needs a "project" id and a "label", both non-empty strings.`,
1984
+ rulesEmpty: (file) =>
1985
+ `${file}: no rules in it. You passed --label-by-project to narrow something, and an empty file would silently narrow nothing.`,
1986
+ written: (file) => `Wrote ${file}.`,
1987
+ },
1988
+
1989
+ bill: {
1990
+ noPath: () => 'bill needs a file or a directory to read: trazum bill ~/.claude/projects',
1991
+ notFound: (path) => `${path}: not found`,
1992
+ noFiles: (path) => `${path}: no .json, .jsonl or .ndjson files under it.`,
1993
+ file: (path, shape, records, leftOut) =>
1994
+ `${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.` : '.'}`,
1995
+ unknown: (path) =>
1996
+ `${path}: no shape this tool reads claims it, so it was not guessed at and is not in the bill.`,
1997
+ ambiguous: (path, shapes) =>
1998
+ `${path}: claimed by more than one shape (${shapes}), so it was not converted. Run the dedicated from-<shape> command on it and say which.`,
1999
+ costReport: (path) =>
2000
+ `${path}: a provider's cost report, which is a bill rather than usage. Set it beside a receipt with trazum reconcile.`,
2001
+ nothingRead: () => 'Nothing here was a usage source this tool reads, so there is nothing to bill.',
2002
+ sources: (read, seen) => `${read} of ${seen} file(s) read as usage.`,
2003
+ written: (file) => `Wrote ${file}.`,
2004
+ },
2005
+
2006
+ fromOpenrouter: {
2007
+ noPath: () =>
2008
+ 'from-openrouter needs the activity report your own curl produced: trazum from-openrouter activity.json --label billing',
2009
+ notFound: (path) => `${path}: not found`,
2010
+ summary: (rows, days, requests) =>
2011
+ `${rows} activity row(s) read over ${days} day(s), covering ${requests} request(s).`,
2012
+ reportedUsage: (usd, byokUsd) =>
2013
+ `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.`,
2014
+ reasoning: (tokens) =>
2015
+ `${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.`,
2016
+ unnamedModel: (count) =>
2017
+ `${count} row(s) named no model and are not in the output: nothing on the row says what answered.`,
2018
+ undated: (count) =>
2019
+ `${count} row(s) carried a date that is not a YYYY-MM-DD day and are not in the output.`,
2020
+ unparseable: () =>
2021
+ 'That is not the JSON GET /api/v1/activity returns. Pass the response body whole, not a field of it.',
2022
+ labelledByWorkspace: (count) => `${count} row(s) took their label from the workspace mapping.`,
2023
+ unruledWorkspace: (count) =>
2024
+ `${count} row(s) carried a workspace no rule names. They keep --label if you gave one and are unattributed if you did not.`,
2025
+ workspaceNotGrouped: () =>
2026
+ '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.',
2027
+ rulesUnreadable: (file) =>
2028
+ `${file}: not readable as a workspace mapping. It is a JSON array of {"workspace": "…", "label": "name"}.`,
2029
+ ruleBad: (file, at) =>
2030
+ `${file}: entry ${at} is not a rule. Each needs a "workspace" id and a "label", both non-empty strings.`,
2031
+ rulesEmpty: (file) =>
2032
+ `${file}: no rules in it. You passed --label-by-workspace to narrow something, and an empty file would silently narrow nothing.`,
2033
+ written: (file) => `Wrote ${file}.`,
2034
+ },
2035
+
1799
2036
  fromHelicone: {
1800
2037
  noPath: () =>
1801
2038
  'from-helicone needs a request export or a directory: trazum from-helicone requests.json',
@@ -1871,6 +2108,10 @@ ${bold('EXAMPLES')}
1871
2108
  stateNeedsFile: () =>
1872
2109
  '--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.',
1873
2110
  stateNeedsOut: () => '--state needs --out: there is nothing to resume against when the records go to stdout.',
2111
+ cwdRulesUnreadable: (file) => `${file}: --label-by-cwd wants a JSON file holding a list, like [{"prefix": "/work/api", "label": "api"}].`,
2112
+ 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.`,
2113
+ 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.`,
2114
+ labelledByCwd: (rules) => `Labelled by working directory, ${rules} rule(s). The directory decides which of your labels applies and never reaches the output.`,
1874
2115
  resumed: (skipped, offset) =>
1875
2116
  skipped === 0
1876
2117
  ? `Read the transcript in full and recorded a resume point at byte ${offset}.`
package/src/i18n/es.ts CHANGED
@@ -47,9 +47,14 @@ ${bold('USO')}
47
47
  trazum rollup <documento...|dir> [--json] [--html-out <fichero>]
48
48
  trazum position <uso.jsonl>
49
49
  trazum receipt <uso.jsonl|dir> [--stamp] [-o <fichero>]
50
+ trazum bill <fichero|dir> [--label <nombre>] [--stamp] [-o <fichero>]
50
51
  trazum from-claude-code <fichero|dir> [--label <nombre>] [-o <fichero>]
51
52
  trazum from-otel <fichero|dir> [--label-from-service] [-o <fichero>]
52
53
  trazum from-litellm <fichero|dir> [-o <fichero>]
54
+ trazum from-anthropic <usage.json> [--label <name>] [--label-by-workspace <file>] [-o <file>]
55
+ trazum from-openai <usage.json> [--label <name>] [--label-by-project <file>] [-o <file>]
56
+ trazum from-openrouter <activity.json> [--label <name>] [--label-by-workspace <file>] [-o <file>]
57
+ trazum reconcile <receipt.json> --against <cost.json> [-o <file>]
53
58
  trazum from-helicone <fichero|dir> [-o <fichero>]
54
59
  trazum from-langsmith <fichero|dir> [-o <fichero>]
55
60
  trazum switch <uso.jsonl> --to <modelo> [--migration-usd <n>] [--cases <n>]
@@ -197,6 +202,85 @@ ${bold('OPCIONES DE ownrate')}
197
202
  en trazum.config.json, de modo que el modelo que tú mismo sirves sea una
198
203
  fila de primera en cada informe, tasado por ti y marcado como tal.
199
204
 
205
+ ${bold('OPCIONES DE reconcile')}
206
+ --against <archivo> El informe de costes del proveedor: el
207
+ GET /v1/organizations/cost_report de Anthropic o
208
+ el GET /v1/organization/costs de OpenAI, que se
209
+ distinguen por su forma.
210
+ -o, --out <archivo> Escribe la comparacion ahi en vez de en stdout.
211
+
212
+ Lo que Trazum calculo junto a lo que el proveedor facturo, nunca sumado:
213
+ dos tablas de precios en una sola cifra es como un informe se vuelve
214
+ silenciosamente falso. Descarga el de Anthropic con group_by[]=description
215
+ y el de OpenAI con group_by[]=line_item, y la diferencia queda atribuida -
216
+ lo que ninguna tarifa por token cubre, y en Anthropic lo que fue batch -
217
+ dejando un resto que es la unica cifra que merece discusion. El informe de
218
+ OpenAI nunca nombra batch, asi que ahi se queda dentro del resto y la
219
+ ejecucion lo dice. Las ventanas deben coincidir o no se compara nada, y una
220
+ moneda sin tipo de cambio se rechaza en vez de convertirse.
221
+
222
+ ${bold('OPCIONES DE from-anthropic')}
223
+ --label <nombre> El proyecto al que pertenece este uso. El
224
+ proveedor no conoce tus nombres de proyecto.
225
+ -o, --out <archivo> Escribe el log de uso ahi en vez de en stdout.
226
+
227
+ El informe de uso de Anthropic, leido como log. Lo descargas tu con tu propia
228
+ credencial de admin; esto lee la respuesta, asi que Trazum nunca sostiene una
229
+ clave de proveedor. Pide group_by[]=model, porque una fila sin modelo no se
230
+ puede cobrar, y group_by[]=service_tier, porque batch se factura con
231
+ descuento y cobrarlo a tarifa de catalogo inflaria la factura. Las filas de
232
+ cualquier otro tramo se quedan fuera y se cuentan, las busquedas web se
233
+ cuentan y nunca se cobran por token, y has_more avisa de que falta pagina.
234
+
235
+ ${bold('OPCIONES DE from-openai')}
236
+ --label <nombre> El proyecto al que pertenece este uso. El
237
+ proveedor no conoce tus nombres de proyecto.
238
+ --label-by-project <archivo> Una etiqueta por id de proyecto, como array JSON
239
+ de {"project": "proj_…", "label": "nombre"}.
240
+ Coincidencia exacta; --label es el respaldo.
241
+ -o, --out <archivo> Escribe el log de uso ahi en vez de en stdout.
242
+
243
+ El informe de uso de OpenAI, leido como log, con el mismo arreglo que
244
+ from-anthropic: tu curl, tu clave de admin, y esto lee la respuesta. Pide
245
+ group_by[]=model, porque una fila sin modelo no se puede cobrar, y
246
+ group_by[]=batch, porque un trabajo por lotes se factura con descuento y
247
+ cobrarlo a tarifa de catalogo inflaria la factura. Cualquier tramo de
248
+ servicio que no sea default se queda fuera y se nombra. Los tokens de audio
249
+ e imagen nunca se cobran a tarifa de texto: una fila que los trae se reduce
250
+ a su parte de texto y el resto se cuenta donde puedas verlo.
251
+
252
+ ${bold('OPCIONES DE bill')}
253
+ --label <nombre> El proyecto al que pertenece este uso, para las
254
+ formas que lo admiten.
255
+ --stamp Sella el recibo con la hora en que se escribio.
256
+ -o, --out <archivo> Escribe el recibo ahi en vez de en stdout.
257
+
258
+ Una sola puerta. Lee un archivo o un directorio, reconoce la forma de cada
259
+ archivo por su propio texto - una transcripcion de Claude Code, spans OTel,
260
+ un export de LiteLLM, Helicone o LangSmith, un informe de Anthropic, OpenAI
261
+ u OpenRouter, o un log de uso plano - lo convierte con el mismo conversor
262
+ que usa el comando dedicado, lo cobra y termina en el recibo. Un archivo
263
+ que ninguna forma reclama se nombra, no se adivina; uno que reclaman dos se
264
+ nombra como ambiguo y se deja en paz; un informe de costes de proveedor se
265
+ remite a reconcile. La linea de cada archivo dice cuantas filas quedaron
266
+ fuera, y el comando from-<forma> dedicado dice por que.
267
+
268
+ ${bold('OPCIONES DE from-openrouter')}
269
+ --label <nombre> El proyecto al que pertenece este uso.
270
+ --label-by-workspace <archivo> Una etiqueta por id de workspace, como array
271
+ JSON de {"workspace": "…", "label": "nombre"}.
272
+ Coincidencia exacta; --label es el respaldo.
273
+ Requiere el informe pedido con group_by=workspace.
274
+ -o, --out <archivo> Escribe el log de uso ahi en vez de en stdout.
275
+
276
+ El informe de actividad de OpenRouter (GET /api/v1/activity, clave de
277
+ gestion, los ultimos treinta dias), leido como log de uso con los mismos
278
+ slugs de modelo que usa el overlay de precios de OpenRouter, asi que cientos
279
+ de modelos se pueden cobrar de golpe. Lo que OpenRouter cobro se imprime
280
+ junto a la cifra de Trazum y nunca se suma a ella. Los tokens de razonamiento
281
+ se cuentan y no se anaden, porque el esquema no dice si el recuento de
282
+ completado ya los incluye.
283
+
200
284
  ${bold('OPCIONES DE from-helicone')}
201
285
  -o, --out <fichero> Escribe el log de uso ahí en vez de en stdout.
202
286
 
@@ -1820,6 +1904,162 @@ ${bold('EJEMPLOS')}
1820
1904
  written: (file) => `Escrito ${file}.`,
1821
1905
  },
1822
1906
 
1907
+ reconcile: {
1908
+ noReceipt: () =>
1909
+ 'reconcile necesita un recibo y un informe de costes: trazum reconcile receipt.json --against cost.json',
1910
+ noReport: () =>
1911
+ 'reconcile necesita --against <informe de costes>: el JSON del GET /v1/organizations/cost_report de Anthropic o del GET /v1/organization/costs de OpenAI.',
1912
+ receiptUnreadable: (file) => `${file}: no se puede leer como JSON.`,
1913
+ notAReceipt: (file) =>
1914
+ `${file}: no es un recibo. Necesita total.usd y span.fromMs/toMs, que es lo que escribe «trazum receipt».`,
1915
+ reportUnreadable: (file) => `${file}: no encontrado.`,
1916
+ notAReport: (file) =>
1917
+ `${file}: no es el JSON que devuelve un endpoint de costes, ni el de Anthropic ni el de OpenAI. Pasa el cuerpo de la respuesta entero.`,
1918
+ summary: (computed, billed, difference) =>
1919
+ `Trazum calculo $${computed.toFixed(2)}; el proveedor facturo $${billed.toFixed(2)}. Diferencia: $${difference.toFixed(2)}.`,
1920
+ notTokens: (usd) =>
1921
+ `$${usd.toFixed(2)} de eso se factura por algo que ninguna tarifa por token cubre: busqueda web, ejecucion de codigo, uso de sesion. Trazum cobra tokens y nunca dijo cubrir esto.`,
1922
+ batch: (usd) =>
1923
+ `$${usd.toFixed(2)} es del tramo batch, que from-anthropic deja fuera en vez de cobrarlo a tarifa de catalogo.`,
1924
+ remainder: (usd) =>
1925
+ `Quedan $${usd.toFixed(2)}, y es la unica cifra aqui que merece discusion: los mismos tokens estandar cobrados de dos maneras, o uso que tu log nunca vio. Si es negativa, Trazum cobro mas de lo que te facturaron, que es una tarifa desactualizada en la direccion que te cuesta dinero.`,
1926
+ notAttributable: () =>
1927
+ 'La diferencia no se puede atribuir: este informe no se agrupo por descripcion, asi que ninguna fila dice si fue tokens, una busqueda web o un batch. Anade group_by[]=description.',
1928
+ notAttributableByLineItem: () =>
1929
+ 'La diferencia no se puede atribuir: este informe no se agrupo por line item, asi que ninguna fila dice a que fue el dinero. Anade group_by[]=line_item.',
1930
+ batchNotSeparable: () =>
1931
+ 'Este informe nunca dice si una linea fue un trabajo por lotes, asi que el descuento de batch, si lo hay, esta dentro de ese resto y no fuera de el.',
1932
+ unknownUnit: (usd) =>
1933
+ `$${usd.toFixed(2)} del resto esta en line items cuya unidad es null: el informe dice que ninguna unidad aplica, asi que ni se cuenta como tokens ni como lo contrario. Se nombra aqui para que el resto no descanse sobre una unidad que nadie declaro.`,
1934
+ windowNotCovered: (fromComputed, toComputed, fromBilled, toBilled) =>
1935
+ `No son la misma ventana. El recibo cubre de ${fromComputed} a ${toComputed}; el informe cubre de ${fromBilled} a ${toBilled}. Un recibo comparado con una factura de otros dias es una cifra equivocada bajo un titulo correcto, asi que no se comparo nada.`,
1936
+ noBilledWindow: () => 'El informe de costes no tiene intervalos, asi que no hay ventana contra la que comparar.',
1937
+ otherCurrency: (list) =>
1938
+ `El informe trae ${list} ademas de USD. Sumar dos monedas en un total necesita un tipo de cambio, e inventarlo es justo lo que este producto existe para no hacer. No se comparo nada.`,
1939
+ truncated: () =>
1940
+ 'El informe dice has_more: true, asi que la cifra facturada se queda una pagina corta y la diferencia sale menor de lo que es.',
1941
+ unreadableAmount: (count) =>
1942
+ `${count} fila(s) traian un importe que no es un numero. Se cuentan, nunca se leen como cero: un cero encogeria la factura en silencio.`,
1943
+ written: (file) => `Escrito ${file}.`,
1944
+ },
1945
+
1946
+ fromAnthropic: {
1947
+ noPath: () =>
1948
+ 'from-anthropic necesita el informe de uso que produjo tu propio curl: trazum from-anthropic usage.json --label facturacion',
1949
+ notFound: (path) => `${path}: no encontrado`,
1950
+ summary: (buckets, rows) => `${buckets} intervalo(s), ${rows} fila(s) de uso leida(s).`,
1951
+ unnamedModel: (count) =>
1952
+ `${count} fila(s) no nombraron modelo y no estan en la salida: el informe no se agrupo por modelo, asi que nada en la fila dice que respondio. Anade group_by[]=model a la peticion.`,
1953
+ nonStandardTier: (count) =>
1954
+ `${count} fila(s) se facturaron en un tramo para el que una tarifa de catalogo no es la tarifa (batch, priority, flex) y no estan en la salida. Cobrarlas a la tarifa estandar inflaria la factura y pareceria correcto.`,
1955
+ tierUnknown: () =>
1956
+ 'El informe no nombro ningun tramo de servicio, asi que una fila batch y una estandar son indistinguibles aqui. Todo se leyo como estandar. Anade group_by[]=service_tier si parte de este uso va por lotes.',
1957
+ webSearch: (count) =>
1958
+ `${count} peticion(es) de busqueda web estan en el informe y en ninguna linea de la salida: las herramientas de servidor se facturan por peticion, no por token, asi que ninguna tarifa por token llega a ellas.`,
1959
+ truncated: () =>
1960
+ 'El informe dice has_more: true. Esto es una pagina de varias y una factura hecha con ella se queda corta. Sigue next_page hasta que has_more sea false, y convierte cada pagina.',
1961
+ unparseable: () =>
1962
+ 'Eso no es el JSON que devuelve GET /v1/organizations/usage_report/messages. Pasa el cuerpo de la respuesta entero, no un campo suyo.',
1963
+ labelledByWorkspace: (count) =>
1964
+ `${count} fila(s) tomaron su etiqueta del mapeo de workspaces.`,
1965
+ unruledWorkspace: (count) =>
1966
+ `${count} fila(s) traian un workspace que ninguna regla nombra. Conservan --label si lo diste y quedan sin atribuir si no: un workspace para el que nadie escribio una regla esta mejor sin atribuir que atribuido al vecino.`,
1967
+ workspaceNotGrouped: () =>
1968
+ 'Diste un mapeo de workspaces y ninguna fila traia id de workspace, asi que el reparto que pediste no se hizo. O el informe no se agrupo por workspace o esta organizacion solo usa el de por defecto, y nada aqui puede distinguirlo. Anade group_by[]=workspace_id.',
1969
+ rulesUnreadable: (file) =>
1970
+ `${file}: no se puede leer como mapeo de workspaces. Es un array JSON de {"workspace": "wrkspc_…" | null, "label": "nombre"}.`,
1971
+ ruleBad: (file, at) =>
1972
+ `${file}: la entrada ${at} no es una regla. Cada una necesita "label" y "workspace", que puede ser null para el workspace por defecto pero no puede faltar: un campo que falta es una errata y null es una decision.`,
1973
+ rulesEmpty: (file) =>
1974
+ `${file}: no hay reglas dentro. Pasaste --label-by-workspace para repartir algo, y un archivo vacio repartiria nada en silencio.`,
1975
+ written: (file) => `Escrito ${file}.`,
1976
+ },
1977
+
1978
+ fromOpenai: {
1979
+ noPath: () =>
1980
+ 'from-openai necesita el informe de uso que produjo tu propio curl: trazum from-openai usage.json --label facturacion',
1981
+ notFound: (path) => `${path}: no encontrado`,
1982
+ summary: (buckets, rows, requests) =>
1983
+ `${buckets} intervalo(s), ${rows} fila(s) de uso leida(s), que cubren ${requests} peticion(es).`,
1984
+ unnamedModel: (count) =>
1985
+ `${count} fila(s) no nombraron modelo y no estan en la salida: el informe no se agrupo por modelo, asi que nada en la fila dice que respondio. Anade group_by[]=model a la peticion.`,
1986
+ batch: (count) =>
1987
+ `${count} fila(s) eran trabajos por lotes y no estan en la salida: batch se factura con descuento, y cobrarlo a tarifa de catalogo inflaria la factura y pareceria correcto.`,
1988
+ batchUnknown: () =>
1989
+ 'El informe nunca dijo si algo fue batch, asi que una fila por lotes y una estandar son indistinguibles aqui. Todo se leyo como estandar. Anade group_by[]=batch si parte de este uso va por lotes.',
1990
+ nonDefaultTier: (count, tiers) =>
1991
+ `${count} fila(s) estaban en un tramo de servicio para el que una tarifa de catalogo no es la tarifa (${tiers}) y no estan en la salida. El esquema no lista los tramos, asi que se nombran en vez de adivinarse.`,
1992
+ tierUnknown: () =>
1993
+ 'El informe no nombro ningun tramo de servicio. Todo se leyo como el tramo por defecto. Anade group_by[]=service_tier si parte de este uso corre en otro.',
1994
+ mixed: (rows, tokens, cacheWrites) =>
1995
+ `${rows} fila(s) traian tokens de audio o imagen, para los que una tarifa de texto no es la tarifa. Cada una se redujo a su parte de texto; ${tokens} token(s) de audio e imagen no estan en ninguna linea de la salida${cacheWrites > 0 ? `, y ${cacheWrites} token(s) de escritura de cache de esas filas se quedaron fuera tambien, porque el informe no les da modalidad` : ''}.`,
1996
+ unsplit: (count) =>
1997
+ `${count} fila(s) traian tokens de audio o imagen y ningun desglose de texto por el que reducirlas, y no estan en la salida. Cobrarlas a tarifa de texto seria adivinar.`,
1998
+ truncated: () =>
1999
+ 'El informe dice has_more: true. Esto es una pagina de varias y una factura hecha con ella se queda corta. Sigue next_page hasta que has_more sea false, y convierte cada pagina.',
2000
+ unparseable: () =>
2001
+ 'Eso no es el JSON que devuelve GET /v1/organization/usage/completions. Pasa el cuerpo de la respuesta entero, no un campo suyo.',
2002
+ labelledByProject: (count) => `${count} fila(s) tomaron su etiqueta del mapeo de proyectos.`,
2003
+ unruledProject: (count) =>
2004
+ `${count} fila(s) traian un proyecto que ninguna regla nombra. Conservan --label si lo diste y quedan sin atribuir si no: un proyecto para el que nadie escribio una regla esta mejor sin atribuir que atribuido al vecino.`,
2005
+ projectNotGrouped: () =>
2006
+ 'Diste un mapeo de proyectos y ninguna fila traia id de proyecto, asi que el reparto que pediste no se hizo. Anade group_by[]=project_id.',
2007
+ rulesUnreadable: (file) =>
2008
+ `${file}: no se puede leer como mapeo de proyectos. Es un array JSON de {"project": "proj_…", "label": "nombre"}.`,
2009
+ ruleBad: (file, at) =>
2010
+ `${file}: la entrada ${at} no es una regla. Cada una necesita un id en "project" y una "label", ambos cadenas no vacias.`,
2011
+ rulesEmpty: (file) =>
2012
+ `${file}: no hay reglas dentro. Pasaste --label-by-project para repartir algo, y un archivo vacio repartiria nada en silencio.`,
2013
+ written: (file) => `Escrito ${file}.`,
2014
+ },
2015
+
2016
+ bill: {
2017
+ noPath: () => 'bill necesita un archivo o un directorio que leer: trazum bill ~/.claude/projects',
2018
+ notFound: (path) => `${path}: no encontrado`,
2019
+ noFiles: (path) => `${path}: no hay archivos .json, .jsonl ni .ndjson dentro.`,
2020
+ file: (path, shape, records, leftOut) =>
2021
+ `${path}: ${shape}${records === null ? ', leido tal cual' : `, ${records} registro(s)`}${leftOut > 0 ? `, ${leftOut} fila(s) fuera. Ejecuta trazum from-${shape} sobre el para ver por que.` : '.'}`,
2022
+ unknown: (path) =>
2023
+ `${path}: ninguna forma que esta herramienta lee lo reclama, asi que no se adivino y no esta en la factura.`,
2024
+ ambiguous: (path, shapes) =>
2025
+ `${path}: lo reclama mas de una forma (${shapes}), asi que no se convirtio. Ejecuta el comando from-<forma> dedicado y di cual.`,
2026
+ costReport: (path) =>
2027
+ `${path}: un informe de costes de proveedor, que es una factura y no uso. Ponlo junto a un recibo con trazum reconcile.`,
2028
+ nothingRead: () => 'Nada de esto era una fuente de uso que esta herramienta lea, asi que no hay nada que facturar.',
2029
+ sources: (read, seen) => `${read} de ${seen} archivo(s) leido(s) como uso.`,
2030
+ written: (file) => `Escrito ${file}.`,
2031
+ },
2032
+
2033
+ fromOpenrouter: {
2034
+ noPath: () =>
2035
+ 'from-openrouter necesita el informe de actividad que produjo tu propio curl: trazum from-openrouter activity.json --label facturacion',
2036
+ notFound: (path) => `${path}: no encontrado`,
2037
+ summary: (rows, days, requests) =>
2038
+ `${rows} fila(s) de actividad leida(s) en ${days} dia(s), que cubren ${requests} peticion(es).`,
2039
+ reportedUsage: (usd, byokUsd) =>
2040
+ `OpenRouter dice que cobro $${usd.toFixed(4)}${byokUsd > 0 ? ` mas $${byokUsd.toFixed(4)} facturados aguas arriba con tus propias claves` : ''}. Esa cifra es de OpenRouter, impresa junto a la de Trazum y nunca sumada a ella: dos tablas de precios en una sola cifra es como un informe se vuelve silenciosamente falso.`,
2041
+ reasoning: (tokens) =>
2042
+ `${tokens} token(s) de razonamiento estan en este informe y no se anadieron a ningun registro: el esquema no dice si completion_tokens ya los incluye, y anadirlos si es asi cobraria el razonamiento dos veces.`,
2043
+ unnamedModel: (count) =>
2044
+ `${count} fila(s) no nombraron modelo y no estan en la salida: nada en la fila dice que respondio.`,
2045
+ undated: (count) =>
2046
+ `${count} fila(s) traian una fecha que no es un dia YYYY-MM-DD y no estan en la salida.`,
2047
+ unparseable: () =>
2048
+ 'Eso no es el JSON que devuelve GET /api/v1/activity. Pasa el cuerpo de la respuesta entero, no un campo suyo.',
2049
+ labelledByWorkspace: (count) => `${count} fila(s) tomaron su etiqueta del mapeo de workspaces.`,
2050
+ unruledWorkspace: (count) =>
2051
+ `${count} fila(s) traian un workspace que ninguna regla nombra. Conservan --label si lo diste y quedan sin atribuir si no.`,
2052
+ workspaceNotGrouped: () =>
2053
+ 'Diste un mapeo de workspaces y ninguna fila traia id de workspace, asi que el reparto que pediste no se hizo. Pide el informe con group_by=workspace.',
2054
+ rulesUnreadable: (file) =>
2055
+ `${file}: no se puede leer como mapeo de workspaces. Es un array JSON de {"workspace": "…", "label": "nombre"}.`,
2056
+ ruleBad: (file, at) =>
2057
+ `${file}: la entrada ${at} no es una regla. Cada una necesita un id en "workspace" y una "label", ambos cadenas no vacias.`,
2058
+ rulesEmpty: (file) =>
2059
+ `${file}: no hay reglas dentro. Pasaste --label-by-workspace para repartir algo, y un archivo vacio repartiria nada en silencio.`,
2060
+ written: (file) => `Escrito ${file}.`,
2061
+ },
2062
+
1823
2063
  fromHelicone: {
1824
2064
  noPath: () =>
1825
2065
  'from-helicone necesita un export de peticiones o un directorio: trazum from-helicone requests.json',
@@ -1895,6 +2135,10 @@ ${bold('EJEMPLOS')}
1895
2135
  stateNeedsFile: () =>
1896
2136
  '--state lee un transcript, no una carpeta: el estado ata un desplazamiento del transcript a una longitud del fichero de salida, y varios transcripts escribiendo en una sola salida no tienen una longitud así. Apúntalo al fichero .jsonl.',
1897
2137
  stateNeedsOut: () => '--state necesita --out: sin fichero de salida no hay nada contra lo que reanudar.',
2138
+ cwdRulesUnreadable: (file) => `${file}: --label-by-cwd espera un JSON con una lista, del estilo [{"prefix": "/trabajo/api", "label": "api"}].`,
2139
+ cwdRuleBad: (file, at) => `${file}: la entrada ${at} necesita "prefix" y "label", ambos cadenas y no vacíos. Aquí no se adivina nada a partir de una ruta, así que una entrada que no es una regla se rechaza en vez de saltarse.`,
2140
+ cwdRulesEmpty: (file) => `${file}: no tiene reglas, así que cada línea acabaría en --label o sin etiqueta. Escribe una regla o quita la opción.`,
2141
+ labelledByCwd: (rules) => `Etiquetado por directorio de trabajo, ${rules} regla(s). El directorio decide cuál de tus etiquetas se aplica y nunca llega a la salida.`,
1898
2142
  resumed: (skipped, offset) =>
1899
2143
  skipped === 0
1900
2144
  ? `Transcript leído entero; punto de reanudación anotado en el byte ${offset}.`