@harrym1707/sdk 0.0.0-stage → 0.1.1

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.
Files changed (58) hide show
  1. package/LICENSE +96 -0
  2. package/README.md +48 -2
  3. package/bin/mesh-demo.mjs +105 -0
  4. package/bin/mesh-proxy.mjs +39 -0
  5. package/bin/mesh-quote.mjs +45 -0
  6. package/bin/mesh-report.mjs +47 -0
  7. package/index.cjs +4923 -0
  8. package/index.js +4850 -0
  9. package/package.json +39 -4
  10. package/types/blind-features.d.ts +28 -0
  11. package/types/cache-ttl-advisor.d.ts +31 -0
  12. package/types/cache-volatility-guard.d.ts +17 -0
  13. package/types/core/cache-simulator.d.ts +271 -0
  14. package/types/core/confidence.d.ts +36 -0
  15. package/types/core/cost.d.ts +16 -0
  16. package/types/core/evaluator.d.ts +6 -0
  17. package/types/core/gateway.d.ts +75 -0
  18. package/types/core/geo-visibility.d.ts +25 -0
  19. package/types/core/helicone.d.ts +6 -0
  20. package/types/core/index.d.ts +26 -0
  21. package/types/core/langfuse.d.ts +7 -0
  22. package/types/core/litellm.d.ts +15 -0
  23. package/types/core/local-tier.d.ts +82 -0
  24. package/types/core/model-prices.d.ts +25 -0
  25. package/types/core/output-diagnostics.d.ts +39 -0
  26. package/types/core/price-catalogue.d.ts +168 -0
  27. package/types/core/provider-usage.d.ts +84 -0
  28. package/types/core/quote-report.d.ts +54 -0
  29. package/types/core/replay-runner.d.ts +11 -0
  30. package/types/core/replay.d.ts +2 -0
  31. package/types/core/router.d.ts +9 -0
  32. package/types/core/routing-simulation.d.ts +24 -0
  33. package/types/core/savings-ledger.d.ts +349 -0
  34. package/types/core/savings-model.d.ts +132 -0
  35. package/types/core/stripe-billing.d.ts +67 -0
  36. package/types/core/stripe-sink.d.ts +77 -0
  37. package/types/core/theo-coverage.d.ts +49 -0
  38. package/types/core/token-reduction.d.ts +208 -0
  39. package/types/core/tool-schema.d.ts +64 -0
  40. package/types/core/traffic.d.ts +182 -0
  41. package/types/core/triage.d.ts +70 -0
  42. package/types/core/types.d.ts +138 -0
  43. package/types/evaluation-capture.d.ts +11 -0
  44. package/types/exact-cache.d.ts +20 -0
  45. package/types/graders.d.ts +53 -0
  46. package/types/index.d.ts +26 -0
  47. package/types/openai.d.ts +23 -0
  48. package/types/proxy.d.ts +63 -0
  49. package/types/reduce-request.d.ts +247 -0
  50. package/types/replay-gate.d.ts +120 -0
  51. package/types/report.d.ts +33 -0
  52. package/types/routing.d.ts +11 -0
  53. package/types/savings-ledger.d.ts +12 -0
  54. package/types/semantic-compaction.d.ts +84 -0
  55. package/types/telemetry.d.ts +6 -0
  56. package/types/theo-policy.d.ts +119 -0
  57. package/types/types.d.ts +263 -0
  58. package/types/wrap.d.ts +52 -0
package/package.json CHANGED
@@ -1,6 +1,41 @@
1
1
  {
2
2
  "name": "@harrym1707/sdk",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "Cut LLM API costs on Claude and OpenAI: one-URL proxy or one-line SDK wrapper that reduces each request losslessly and meters VERIFIED savings into an append-only, customer-recomputable ledger. Pay only a share of verified savings.",
5
+ "license": "BUSL-1.1",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/Harrym1707/Mesh.git",
9
+ "directory": "packages/sdk-js/pkg"
10
+ },
11
+ "bugs": "https://github.com/Harrym1707/Mesh/issues",
12
+ "homepage": "https://www.mesh-technology.com",
13
+ "type": "module",
14
+ "main": "./index.cjs",
15
+ "module": "./index.js",
16
+ "types": "./types/index.d.ts",
17
+ "exports": {
18
+ ".": {
19
+ "types": "./types/index.d.ts",
20
+ "import": "./index.js",
21
+ "require": "./index.cjs"
22
+ }
23
+ },
24
+ "bin": {
25
+ "mesh-quote": "bin/mesh-quote.mjs",
26
+ "mesh-proxy": "bin/mesh-proxy.mjs",
27
+ "mesh-demo": "bin/mesh-demo.mjs",
28
+ "mesh-report": "bin/mesh-report.mjs"
29
+ },
30
+ "files": [
31
+ "index.js",
32
+ "index.cjs",
33
+ "bin",
34
+ "types",
35
+ "README.md",
36
+ "LICENSE"
37
+ ],
38
+ "engines": {
39
+ "node": ">=18"
40
+ }
41
+ }
@@ -0,0 +1,28 @@
1
+ export type BlindFeatures = {
2
+ schemaVersion: 1;
3
+ provider: "openai" | "anthropic" | "unknown";
4
+ /** The model id — a routing/pricing key, not user content. */
5
+ model: string;
6
+ messageCount: number;
7
+ toolCount: number;
8
+ /** Approximate token counts by message role. No text, only sizes. */
9
+ roleTokensApprox: Record<string, number>;
10
+ inputTokensApprox: number;
11
+ toolSchemaTokensApprox: number;
12
+ /** Keyed, irreversible hashes of each content block — for dedup/reuse learning. */
13
+ blockHashes: string[];
14
+ /** Fraction of content blocks that repeat verbatim within this request. */
15
+ duplicateBlockFraction: number;
16
+ /** Keyed hash of the cacheable prefix (tools + system) — a cross-turn reuse signal. */
17
+ stablePrefixHash: string;
18
+ };
19
+ /**
20
+ * Reduce a request to irreversible features under a per-deployment HMAC key.
21
+ *
22
+ * The key never leaves the gateway; nothing returned here can be turned back into
23
+ * the prompt, and the key makes even a guess-and-check attack on a short block
24
+ * infeasible. Pure and allocation-light so it can run in the hot path.
25
+ */
26
+ export declare function extractBlindFeatures(request: unknown, options: {
27
+ hmacKey: string;
28
+ }): BlindFeatures;
@@ -0,0 +1,31 @@
1
+ export type CacheTtlRecommendation = {
2
+ ttl: "5m" | "1h";
3
+ /** Why this TTL was chosen, for the stamp's change record. */
4
+ reason: string;
5
+ };
6
+ export type CacheTtlAdvisorOptions = {
7
+ /** LRU bound on tracked conversations. Default 1000. */
8
+ maxConversations?: number;
9
+ /** Gaps needed before the advisor will move off the 5m default. Default 3. */
10
+ minObservations?: number;
11
+ /** Recommend 1h once the realized gap p90 exceeds this many seconds. Default 300 (5m). */
12
+ upgradeGapP90Seconds?: number;
13
+ /** Most recent gaps retained per conversation for the p90. Default 20. */
14
+ windowGaps?: number;
15
+ };
16
+ export declare class CacheTtlAdvisor {
17
+ /** Insertion-ordered; re-inserted on touch, so the first key is the LRU. */
18
+ private readonly conversations;
19
+ private readonly maxConversations;
20
+ private readonly minObservations;
21
+ private readonly upgradeGapP90Seconds;
22
+ private readonly windowGaps;
23
+ constructor(options?: CacheTtlAdvisorOptions);
24
+ /**
25
+ * Record this request's arrival and recommend a TTL for its conversation.
26
+ * Call once per request. `nowSeconds` is injectable for tests; at runtime it
27
+ * defaults to the wall clock.
28
+ */
29
+ recommend(request: unknown, nowSeconds?: number): CacheTtlRecommendation;
30
+ private evict;
31
+ }
@@ -0,0 +1,17 @@
1
+ export type CacheStampDecision = {
2
+ stamp: boolean;
3
+ /** Present when stamp is false: why this conversation is not being stamped. */
4
+ reason?: string;
5
+ };
6
+ export declare class CachePrefixVolatilityGuard {
7
+ private readonly maxConversations;
8
+ /** Insertion-ordered; re-inserted on touch, so the first key is the LRU. */
9
+ private readonly conversations;
10
+ constructor(maxConversations?: number);
11
+ /**
12
+ * Record this request and decide whether its conversation has earned a
13
+ * cache stamp. Call once per request, with the raw (unreduced) request.
14
+ */
15
+ observe(request: unknown): CacheStampDecision;
16
+ private evict;
17
+ }
@@ -0,0 +1,271 @@
1
+ import { type TokenPrice } from "./cost.js";
2
+ import type { BillableEvent } from "./savings-ledger.js";
3
+ import { type TokenCounter } from "./token-reduction.js";
4
+ /**
5
+ * Provider prompt-cache simulator.
6
+ *
7
+ * Prefix caching is the largest lever MESH has, and on a fixture it was worth 29
8
+ * of 32 points. A claim that large cannot rest on a stub that simply says "the
9
+ * prefix was cached". This models the published rules, including the ones that
10
+ * make caching fail:
11
+ *
12
+ * - a minimum cacheable prefix (1,024 tokens on both providers; 2,048 on
13
+ * Claude Haiku), below which nothing caches at all
14
+ * - longest EXACT prefix matching, so one changed character early in the
15
+ * prompt discards everything after it
16
+ * - hit granularity (OpenAI grants hits in 128-token increments)
17
+ * - a time to live measured from last use, so traffic spread thinly over time
18
+ * never accumulates a hit rate
19
+ * - a write premium where the provider charges one (Anthropic bills a cache
20
+ * write at 1.25x base for the 5-minute TTL, 2x for the hour)
21
+ *
22
+ * The TTL is the honest part. A simulation that assumes every repeat hits will
23
+ * overstate caching badly for low-traffic workloads: with a 5-minute TTL and
24
+ * requests ten minutes apart, the cache never pays for itself and the write
25
+ * premium makes it worse than doing nothing. That outcome is reachable here.
26
+ *
27
+ * Sources: OpenAI's prompt-caching guide (automatic above 1,024 tokens, 128-token
28
+ * increments, longest exact prefix, 5-10 minutes of inactivity up to an hour) and
29
+ * Anthropic's (explicit breakpoints, 5-minute default TTL or 1 hour, writes at
30
+ * 1.25x or 2x base, reads at 0.1x).
31
+ */
32
+ export type CachePolicy = {
33
+ name: string;
34
+ /** Nothing below this caches at all. */
35
+ minimumCacheableTokens: number;
36
+ /** Hits are granted in whole multiples of this many tokens. */
37
+ incrementTokens: number;
38
+ /** Entry is dropped after this long without being used. */
39
+ ttlSeconds: number;
40
+ /** Charge for writing a prefix, as a multiple of the base input rate. */
41
+ writeMultiplier: number;
42
+ /** Charge for reading a cached prefix, as a multiple of the base input rate. */
43
+ readMultiplier: number;
44
+ };
45
+ /** Automatic, no write premium, hits in 128-token steps. */
46
+ export declare const OPENAI_CACHE: CachePolicy;
47
+ /** Explicit breakpoints, 5-minute TTL, writes at 1.25x base. */
48
+ export declare const ANTHROPIC_CACHE_5M: CachePolicy;
49
+ /**
50
+ * Anthropic with NO cache_control placed: the cache is opt-in, so nothing
51
+ * caches and every token bills at the full input rate. This is the measured
52
+ * reality of unstamped Claude traffic (the first live export recorded a
53
+ * five-turn agent with zero cache reads and zero writes), and therefore the
54
+ * honest baseline for valuing a MESH-placed stamp.
55
+ */
56
+ export declare const ANTHROPIC_NO_CACHE: CachePolicy;
57
+ /** The hour-long TTL, which doubles the write charge. */
58
+ export declare const ANTHROPIC_CACHE_1H: CachePolicy;
59
+ export type SimulatedRequest = {
60
+ /** Seconds since the run began. Drives TTL expiry. */
61
+ atSeconds: number;
62
+ /** The exact prompt text the provider would see, in order. */
63
+ prompt: string;
64
+ /** Output tokens the model produced, for costing. */
65
+ outputTokens: number;
66
+ };
67
+ export type SimulatedCall = {
68
+ atSeconds: number;
69
+ totalInputTokens: number;
70
+ cachedInputTokens: number;
71
+ writtenInputTokens: number;
72
+ freshInputTokens: number;
73
+ outputTokens: number;
74
+ costUsd: number;
75
+ /** Why nothing was cached, when nothing was. */
76
+ missReason?: "below-minimum" | "no-matching-prefix" | "expired" | "first-request";
77
+ };
78
+ export type SimulationResult = {
79
+ policy: string;
80
+ calls: SimulatedCall[];
81
+ totalCostUsd: number;
82
+ /** What the same traffic would cost with caching unavailable. */
83
+ uncachedCostUsd: number;
84
+ savingUsd: number;
85
+ savingPercent: number;
86
+ totalInputTokens: number;
87
+ cachedInputTokens: number;
88
+ /** Share of input tokens served from cache. */
89
+ hitRate: number;
90
+ expiries: number;
91
+ missReasons: Record<string, number>;
92
+ };
93
+ /**
94
+ * Run a request stream against a cache policy and price it.
95
+ *
96
+ * Deliberately pessimistic where the published behaviour is a range: the
97
+ * shorter documented TTL is used, and a prefix must clear the minimum AFTER
98
+ * being rounded down to the policy's increment.
99
+ */
100
+ export declare function simulateCache(requests: SimulatedRequest[], policy: CachePolicy, price: TokenPrice, options?: {
101
+ countTokens?: TokenCounter;
102
+ }): SimulationResult;
103
+ /**
104
+ * Context compaction, priced.
105
+ *
106
+ * An agent loop re-sends its whole transcript every turn, so the API bill grows
107
+ * with the square of the session. Harnesses fight that by COMPACTING: at some
108
+ * turn they throw the transcript away and replace it with a short summary, so
109
+ * the prefix shrinks and growth restarts from a smaller base.
110
+ *
111
+ * The move is not free, and the cost that hides from a naive token count is the
112
+ * one caching imposes. Prefix caching already defeats most of the quadratic tax
113
+ * on its own: once a transcript is cached, every later turn READS it at 0.1x and
114
+ * writes only the new tail. Compaction discards that cached prefix — the summary
115
+ * does not match the bytes it replaced, so the longest-exact-prefix match
116
+ * collapses to the stable system block, and everything after it is re-written at
117
+ * the full (or write-premium) rate. That rewrite, plus the one-off summarisation
118
+ * call that reads the transcript to produce the summary, is the price of
119
+ * compaction. It only pays back if the session runs long enough afterwards for
120
+ * the smaller prefix to save more than the rewrite cost.
121
+ *
122
+ * The counter-intuitive, and therefore worth-proving, result this models: under
123
+ * a WARM cache and fast turns, compaction can be a net LOSS, because the thing
124
+ * it shrinks was already being read at a tenth of its price. It wins when the
125
+ * cache is cold — slow human-in-the-loop turns that expire the TTL, or traffic
126
+ * with no cache_control placed at all — where the transcript really is re-sent
127
+ * at full price every turn. Both regimes are reachable here by choice of policy
128
+ * and turn spacing.
129
+ */
130
+ export type AgentSessionSpec = {
131
+ /** The stable system + tool block that leads every turn. Cached, never rewritten. */
132
+ systemPromptTokens: number;
133
+ /** How many model calls the session makes. */
134
+ turns: number;
135
+ /** New transcript appended before each turn (user message + tool results). */
136
+ userTurnTokens: number;
137
+ /** Model output each turn, which becomes input on the next turn. */
138
+ assistantTurnTokens: number;
139
+ /** Seconds between turns. Long gaps expire the cache TTL and change the verdict. */
140
+ secondsPerTurn: number;
141
+ };
142
+ export type CompactionSpec = {
143
+ /** The turn (1-based) whose prompt is the first to carry the summary. */
144
+ atTurn: number;
145
+ /** Size of the summary that replaces the discarded transcript. */
146
+ summaryTokens: number;
147
+ /**
148
+ * Charge the one-off call that reads the transcript to write the summary.
149
+ * Defaults to true; set false to isolate the cache-invalidation cost alone.
150
+ */
151
+ chargeSummarizationCall?: boolean;
152
+ };
153
+ export type CompactionEconomics = {
154
+ compactionTurn: number;
155
+ summaryTokens: number;
156
+ /** The session run straight through, no compaction. */
157
+ baseline: SimulationResult;
158
+ /** The same session with the transcript compacted at `compactionTurn`. */
159
+ withCompaction: SimulationResult;
160
+ /**
161
+ * The cache penalty of the compaction event, isolated from its size effect:
162
+ * the compaction turn's actual cost minus what that same prompt would have
163
+ * cost if every token had been served from cache. Always >= 0 — it is the
164
+ * price of the prefix collapsing to the system block on that one turn.
165
+ */
166
+ cacheInvalidationCostUsd: number;
167
+ /** Cost of the one-off call that reads the transcript to write the summary (0 if not charged). */
168
+ summarizationCostUsd: number;
169
+ /** baseline total minus compacted total. Positive means compaction paid off. */
170
+ netSavingUsd: number;
171
+ savingPercent: number;
172
+ worthwhile: boolean;
173
+ /**
174
+ * Turns after the compaction point before compaction turns net-positive, or
175
+ * null if it never does within the session's length.
176
+ */
177
+ breakEvenTurns: number | null;
178
+ };
179
+ /**
180
+ * Build a turn-by-turn agent session as a request stream, with the transcript
181
+ * growing by one segment each turn. With a `compaction`, turns from `atTurn`
182
+ * on lead with a summary in place of the discarded transcript, and (unless
183
+ * disabled) a summarisation call is inserted just before that turn.
184
+ */
185
+ export declare function buildAgentSession(spec: AgentSessionSpec, compaction?: CompactionSpec, options?: {
186
+ countTokens?: TokenCounter;
187
+ }): SimulatedRequest[];
188
+ /**
189
+ * Price a compaction decision: run the session with and without it under the
190
+ * same cache policy, and decompose the difference into the cache-invalidation
191
+ * cost, the summarisation cost, the net saving and the break-even horizon.
192
+ */
193
+ export declare function estimateCompactionEconomics(spec: AgentSessionSpec, compaction: CompactionSpec, policy: CachePolicy, price: TokenPrice, options?: {
194
+ countTokens?: TokenCounter;
195
+ }): CompactionEconomics;
196
+ /**
197
+ * Compaction economics computed from the ledger instead of a synthetic session.
198
+ *
199
+ * The ledger keeps no prompt text — only provider-verbatim token counts — so
200
+ * the string prefix model above cannot run on it. It does not need to: the
201
+ * ledger already records what the cache DID (cachedInputTokens per turn), so the
202
+ * realized per-turn input rate is known, and compaction can be priced as the
203
+ * removal of context from later turns valued at that realized rate.
204
+ *
205
+ * What compaction removes is a fixed block. Replacing the history accumulated by
206
+ * the compaction point with a shorter summary drops the same
207
+ * `context_before - preserved_prefix - summary` tokens from EVERY later turn's
208
+ * input. Those removed tokens are exactly the stable, repeated prefix — the part
209
+ * the provider was most likely serving from cache — so on a turn where the
210
+ * ledger shows cache reads they are valued at the cached rate, not the full
211
+ * one. That is a deliberate under-claim on cache-heavy traffic (the ledger's own
212
+ * convention): compaction is credited only with what the removed tokens actually
213
+ * cost, which on a warm cache is a tenth of their face value. The one-off
214
+ * summarisation call is charged at the FULL input rate, against compaction, so
215
+ * the net never flatters the lever.
216
+ */
217
+ /** One turn of a task, projected from a recorded ledger event to just what pricing needs. */
218
+ export type LedgerTurn = {
219
+ taskId?: string;
220
+ turnIndex: number;
221
+ /** For ordering turns that share a turnIndex; optional. */
222
+ timestampMs?: number;
223
+ inputTokens: number;
224
+ outputTokens: number;
225
+ cachedInputTokens: number;
226
+ };
227
+ export type LedgerCompactionSpec = {
228
+ /** The turn (1-based, within the task) that first carries the summary. */
229
+ atTurn: number;
230
+ /** Size of the summary that replaces the discarded history. */
231
+ summaryTokens: number;
232
+ /**
233
+ * The always-present prefix (system + tools) compaction keeps verbatim.
234
+ * Defaults to the smallest input seen in the task — a safe lower bound that,
235
+ * if anything, under-states what is removed and so under-claims the saving.
236
+ */
237
+ preservedPrefixTokens?: number;
238
+ };
239
+ export type LedgerCompactionEstimate = {
240
+ taskId?: string;
241
+ turns: number;
242
+ compactionTurn: number;
243
+ summaryTokens: number;
244
+ preservedPrefixTokens: number;
245
+ /** Tokens dropped from every post-compaction turn's input. */
246
+ removedTokensPerTurn: number;
247
+ postCompactionTurns: number;
248
+ /** Full task cost as recorded (sum of each turn priced at its realized usage). */
249
+ recordedCostUsd: number;
250
+ /** One-off cost of producing the summary, charged at the full input rate. */
251
+ summarizationCostUsd: number;
252
+ /** Realized value of the context compaction removes, summed over later turns. */
253
+ grossSavingUsd: number;
254
+ netSavingUsd: number;
255
+ savingPercent: number;
256
+ worthwhile: boolean;
257
+ /** Turns after the compaction point before the one-off cost is repaid, or null. */
258
+ breakEvenTurns: number | null;
259
+ };
260
+ /**
261
+ * Project recorded ledger events into per-task turn streams: keep the succeeded
262
+ * events that carry usage, group them by taskId, and order each group by turn.
263
+ * Events with no taskId are each treated as their own single-turn task.
264
+ */
265
+ export declare function ledgerTurnsByTask(events: readonly BillableEvent[]): Map<string, LedgerTurn[]>;
266
+ /**
267
+ * Price a compaction decision from a single task's recorded turns. `price` is
268
+ * the resolved catalogue rate for the task's model (look it up with
269
+ * `priceUsage` / `lookupPrice` and pass `.price`).
270
+ */
271
+ export declare function estimateCompactionFromLedger(turns: readonly LedgerTurn[], compaction: LedgerCompactionSpec, price: TokenPrice): LedgerCompactionEstimate;
@@ -0,0 +1,36 @@
1
+ /**
2
+ * Confidence bounds for savings claims.
3
+ *
4
+ * Homed in core because every part of MESH that asserts "quality held" needs the
5
+ * same bound: the offline benchmark, and the replay gate that decides whether a
6
+ * lossy reduction may be switched on for real traffic. One implementation, so
7
+ * the statistics behind an invoice cannot drift from the statistics behind a
8
+ * benchmark.
9
+ */
10
+ export declare function mean(values: number[]): number;
11
+ /** Deterministic PRNG, so a bound is reproducible from its seed. */
12
+ export declare function seededRandom(seed: string): () => number;
13
+ /**
14
+ * Lower confidence bound on a mean, resampling whole groups.
15
+ *
16
+ * Groups matter: several records can come from one prompt or one task, and
17
+ * treating them as independent understates the spread and overstates the bound.
18
+ */
19
+ export declare function groupBootstrapLowerBound(deltas: number[], groups: string[], samples: number, seed: string, alpha?: number): number;
20
+ /**
21
+ * Simultaneous lower bounds across every candidate configuration.
22
+ *
23
+ * Scoring many candidates on one sample and keeping the best biases that winner
24
+ * upward: a per-candidate bound holds for a configuration chosen in advance, not
25
+ * for the maximum over a search. Measured on MMLU-Pro, the uncorrected bound let
26
+ * configurations through that then lost up to 3.26 pp on held-out data while
27
+ * reporting a safe bound.
28
+ *
29
+ * Groups are resampled once per draw and every candidate scored on that same
30
+ * resample, so candidates stay correlated as they are in truth. Each deviation
31
+ * is then divided by that candidate's own bootstrap standard error before the
32
+ * maximum is taken. Studentising is not optional: an unscaled maximum lets
33
+ * whichever candidate is noisiest set the band for the most precise one, which
34
+ * was tried first and was wrong.
35
+ */
36
+ export declare function simultaneousGroupBootstrapLowerBounds(deltasByConfiguration: number[][], groups: string[], samples: number, seed: string, alpha?: number): number[];
@@ -0,0 +1,16 @@
1
+ export type TokenPrice = {
2
+ inputPerMillion: number;
3
+ cachedInputPerMillion?: number;
4
+ /** Cache writes at the default (5m) TTL; Anthropic bills 1.25x base input. */
5
+ cacheWriteInputPerMillion?: number;
6
+ /** Cache writes at the 1h TTL; Anthropic bills 2x base input. */
7
+ cacheWrite1hInputPerMillion?: number;
8
+ outputPerMillion: number;
9
+ };
10
+ export declare function estimateTokenCost(inputTokens: number, outputTokens: number, price: TokenPrice, cacheUsage?: {
11
+ cachedInputTokens?: number;
12
+ /** TOTAL cache writes, inclusive of any 1h share below. */
13
+ cacheWriteInputTokens?: number;
14
+ /** The share of the writes above that carried the 1h TTL. */
15
+ cacheWrite1hInputTokens?: number;
16
+ }): number;
@@ -0,0 +1,6 @@
1
+ import type { EvaluationInput, Evaluator, QualityPolicy, QualityResult } from "./types.js";
2
+ export declare function applyQualityPolicy(result: QualityResult, policy: QualityPolicy): QualityResult;
3
+ export declare class ExactMatchEvaluator implements Evaluator {
4
+ name: string;
5
+ evaluate(input: EvaluationInput): Promise<QualityResult>;
6
+ }
@@ -0,0 +1,75 @@
1
+ import { type PriceCatalogue } from "./price-catalogue.js";
2
+ import type { IngestIssue, TrafficMeasurement, TrafficRecord } from "./traffic.js";
3
+ import type { StreamSignals } from "./triage.js";
4
+ /**
5
+ * The shared gateway layer every adapter feeds.
6
+ *
7
+ * LiteLLM, Helicone and Langfuse log different schemas, but the triage engine
8
+ * needs one shape: a traffic record plus the three things only a gateway or
9
+ * tracer knows (what it thinks the row cost, who the request was for, and
10
+ * whether its own cache answered). Each adapter is ~150 lines of field
11
+ * mapping; everything downstream - reconciliation, signals, classification,
12
+ * quoting - is written once here and in triage.ts, so a finding fixed for one
13
+ * connector is fixed for all of them.
14
+ */
15
+ export type GatewayRecord = {
16
+ record: TrafficRecord;
17
+ /** The tool's own cost figure for the row, as logged. */
18
+ reportedSpendUsd?: number;
19
+ /** The downstream customer the request was made for. */
20
+ endUser?: string;
21
+ teamId?: string;
22
+ };
23
+ export type GatewayParseResult = {
24
+ /** Rows that reached a provider; the analysable baseline. */
25
+ accepted: GatewayRecord[];
26
+ /**
27
+ * Rows the tool's own response cache answered. Not baseline: no provider
28
+ * call happened, and counting the would-have-been cost would claim a saving
29
+ * the customer's own stack already delivers.
30
+ */
31
+ cacheHits: GatewayRecord[];
32
+ issues: IngestIssue[];
33
+ };
34
+ export type SpendReconciliation = {
35
+ /** Rows where both a reported spend and a catalogue price existed. */
36
+ comparedRows: number;
37
+ reportedSpendUsd: number;
38
+ catalogueCostUsd: number;
39
+ /** Positive when the tool reports more spend than published rates support. */
40
+ driftPercent: number;
41
+ /** Rows whose reported spend deviates more than the tolerance. */
42
+ flagged: Array<{
43
+ id: string;
44
+ model: string;
45
+ reportedUsd: number;
46
+ catalogueUsd: number;
47
+ driftPercent: number;
48
+ }>;
49
+ /** Rows whose model the catalogue cannot price; excluded, never zeroed. */
50
+ unpricedRows: number;
51
+ /** What the tool's own response cache already saves, at catalogue rates. */
52
+ cacheHitRows: number;
53
+ cacheHitSavedUsd: number;
54
+ };
55
+ /**
56
+ * Reconcile a tool's reported spend against the dated price catalogue.
57
+ *
58
+ * A persistent drift means one of the two price sources is stale, and either
59
+ * way the customer's dashboards are wrong by that much. Rows already arriving
60
+ * provider-cached are priced at the cached rate, so a correct gateway figure
61
+ * is not flagged merely because caching made the true cost lower.
62
+ */
63
+ export declare function reconcileGatewaySpend(parsed: GatewayParseResult, catalogue: PriceCatalogue, options?: {
64
+ tolerancePercent?: number;
65
+ }): SpendReconciliation;
66
+ /**
67
+ * Derive segment-classification signals for one traffic stream.
68
+ *
69
+ * The measurement supplies what usage alone can show; the gateway extras add
70
+ * the dimensions only it knows: who each request was for, and how often its
71
+ * own response cache already answers.
72
+ */
73
+ export declare function signalsFromGateway(stream: GatewayRecord[], cacheHits: GatewayRecord[], measurement: TrafficMeasurement): StreamSignals;
74
+ /** Group parsed gateway rows into streams by the workload the tool tagged. */
75
+ export declare function groupByStream(entries: GatewayRecord[]): Map<string, GatewayRecord[]>;
@@ -0,0 +1,25 @@
1
+ export type GeoObservation = {
2
+ engine: string;
3
+ promptId: string;
4
+ timestamp: string;
5
+ mentioned: boolean;
6
+ cited?: boolean;
7
+ linked?: boolean;
8
+ correctDescription?: boolean;
9
+ categoryAssociated?: boolean;
10
+ competitorMentions?: string[];
11
+ citedDomains?: string[];
12
+ };
13
+ export type GeoVisibilityMetrics = {
14
+ observations: number;
15
+ mentions: number;
16
+ mentionRate: number;
17
+ citations: number;
18
+ citationRate: number;
19
+ links: number;
20
+ linkRate: number;
21
+ correctDescriptionRate: number | null;
22
+ categoryAssociationRate: number | null;
23
+ };
24
+ export declare function calculateGeoVisibilityMetrics(observations: GeoObservation[]): GeoVisibilityMetrics;
25
+ export declare function calculateGeoVisibilityByEngine(observations: GeoObservation[]): Record<string, GeoVisibilityMetrics>;
@@ -0,0 +1,6 @@
1
+ import type { GatewayParseResult } from "./gateway.js";
2
+ /**
3
+ * Parse Helicone request rows from /v1/request/query output or a CSV-to-JSON
4
+ * export. Rows that cannot be read are reported, never dropped silently.
5
+ */
6
+ export declare function parseHeliconeRequests(rows: unknown[], fallbackDate: string): GatewayParseResult;
@@ -0,0 +1,26 @@
1
+ export * from "./types.js";
2
+ export * from "./router.js";
3
+ export * from "./evaluator.js";
4
+ export * from "./cost.js";
5
+ export * from "./confidence.js";
6
+ export * from "./cache-simulator.js";
7
+ export * from "./price-catalogue.js";
8
+ export * from "./token-reduction.js";
9
+ export * from "./tool-schema.js";
10
+ export * from "./savings-model.js";
11
+ export * from "./theo-coverage.js";
12
+ export * from "./savings-ledger.js";
13
+ export * from "./quote-report.js";
14
+ export * from "./traffic.js";
15
+ export * from "./triage.js";
16
+ export * from "./gateway.js";
17
+ export * from "./litellm.js";
18
+ export * from "./helicone.js";
19
+ export * from "./langfuse.js";
20
+ export * from "./model-prices.js";
21
+ export * from "./replay.js";
22
+ export * from "./provider-usage.js";
23
+ export * from "./stripe-sink.js";
24
+ export * from "./geo-visibility.js";
25
+ export * from "./output-diagnostics.js";
26
+ export * from "./stripe-billing.js";
@@ -0,0 +1,7 @@
1
+ import type { GatewayParseResult } from "./gateway.js";
2
+ /**
3
+ * Parse Langfuse generation rows from the public API or an export. Rows that
4
+ * are not generations (spans, events) are skipped silently; rows that are
5
+ * generations but unreadable are reported.
6
+ */
7
+ export declare function parseLangfuseGenerations(rows: unknown[], fallbackDate: string): GatewayParseResult;
@@ -0,0 +1,15 @@
1
+ import { reconcileGatewaySpend, signalsFromGateway, type GatewayParseResult, type GatewayRecord } from "./gateway.js";
2
+ export type LiteLLMRecord = GatewayRecord;
3
+ export type LiteLLMParseResult = GatewayParseResult;
4
+ /**
5
+ * Parse LiteLLM spend-log rows, from /spend/logs output, a database export, or
6
+ * a StandardLoggingPayload stream. Rows that cannot be read are reported, never
7
+ * dropped silently.
8
+ */
9
+ export declare function parseLiteLLMSpendLogs(rows: unknown[], fallbackDate: string): LiteLLMParseResult;
10
+ /**
11
+ * Reconciliation and signal derivation are shared across every connector; see
12
+ * gateway.ts. Re-exported under the LiteLLM names existing callers use.
13
+ */
14
+ export declare const reconcileLiteLLMSpend: typeof reconcileGatewaySpend;
15
+ export declare const signalsFromLiteLLM: typeof signalsFromGateway;