@harrym1707/sdk 0.0.0-stage → 0.2.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.
- package/LICENSE +98 -0
- package/README.md +48 -2
- package/bin/mesh-demo.mjs +105 -0
- package/bin/mesh-proxy.mjs +39 -0
- package/bin/mesh-quote.mjs +45 -0
- package/bin/mesh-report.mjs +47 -0
- package/index.cjs +6306 -0
- package/index.js +6204 -0
- package/package.json +39 -4
- package/types/blind-features.d.ts +28 -0
- package/types/cache-volatility-guard.d.ts +31 -0
- package/types/core/account-store.d.ts +7 -0
- package/types/core/accounts.d.ts +134 -0
- package/types/core/billing-worker.d.ts +113 -0
- package/types/core/budget.d.ts +216 -0
- package/types/core/cache-simulator.d.ts +271 -0
- package/types/core/confidence.d.ts +36 -0
- package/types/core/cost.d.ts +16 -0
- package/types/core/evaluator.d.ts +16 -0
- package/types/core/gateway.d.ts +75 -0
- package/types/core/geo-visibility.d.ts +25 -0
- package/types/core/github-oauth.d.ts +41 -0
- package/types/core/helicone.d.ts +6 -0
- package/types/core/index.d.ts +36 -0
- package/types/core/langfuse.d.ts +7 -0
- package/types/core/ledger-store.d.ts +62 -0
- package/types/core/litellm.d.ts +15 -0
- package/types/core/local-tier.d.ts +82 -0
- package/types/core/model-prices.d.ts +25 -0
- package/types/core/output-diagnostics.d.ts +39 -0
- package/types/core/price-catalogue.d.ts +168 -0
- package/types/core/provider-usage.d.ts +84 -0
- package/types/core/quote-report.d.ts +54 -0
- package/types/core/replay.d.ts +2 -0
- package/types/core/router.d.ts +9 -0
- package/types/core/routing.d.ts +282 -0
- package/types/core/savings-ledger.d.ts +349 -0
- package/types/core/savings-model.d.ts +132 -0
- package/types/core/stripe-billing.d.ts +67 -0
- package/types/core/stripe-client.d.ts +117 -0
- package/types/core/stripe-sink.d.ts +77 -0
- package/types/core/theo-coverage.d.ts +49 -0
- package/types/core/token-reduction.d.ts +219 -0
- package/types/core/tool-schema.d.ts +64 -0
- package/types/core/traffic.d.ts +182 -0
- package/types/core/triage.d.ts +70 -0
- package/types/core/types.d.ts +149 -0
- package/types/core/workflow-sessions.d.ts +50 -0
- package/types/cta.d.ts +60 -0
- package/types/evaluation-capture.d.ts +11 -0
- package/types/exact-cache.d.ts +20 -0
- package/types/graders.d.ts +53 -0
- package/types/index.d.ts +31 -0
- package/types/ledger-mirror.d.ts +38 -0
- package/types/openai.d.ts +23 -0
- package/types/proxy.d.ts +104 -0
- package/types/reduce-request.d.ts +272 -0
- package/types/replay-gate.d.ts +120 -0
- package/types/report.d.ts +33 -0
- package/types/routing.d.ts +11 -0
- package/types/savings-ledger.d.ts +22 -0
- package/types/savings-snapshot.d.ts +11 -0
- package/types/semantic-compaction.d.ts +84 -0
- package/types/telemetry.d.ts +6 -0
- package/types/theo-agent-store.d.ts +27 -0
- package/types/theo-agent.d.ts +247 -0
- package/types/theo-gate.d.ts +75 -0
- package/types/theo-policy.d.ts +219 -0
- package/types/types.d.ts +287 -0
- package/types/wrap.d.ts +60 -0
|
@@ -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,16 @@
|
|
|
1
|
+
import type { EvaluationInput, Evaluator, QualityPolicy, QualityResult } from "./types.js";
|
|
2
|
+
/**
|
|
3
|
+
* Apply a quality policy to a measured result, returning the result with
|
|
4
|
+
* `passed` narrowed to whether every requirement is met.
|
|
5
|
+
*
|
|
6
|
+
* The error-rate and latency ceilings are fail-closed: a ceiling the result
|
|
7
|
+
* does not actually measure cannot be certified as met, so an unmeasured
|
|
8
|
+
* `maxErrorRate` or `maxLatencyMs` fails the gate rather than silently passing.
|
|
9
|
+
* This closes the "never silently reduce quality" hole where a candidate gated
|
|
10
|
+
* on error rate or latency would otherwise clear a gate it never proved.
|
|
11
|
+
*/
|
|
12
|
+
export declare function applyQualityPolicy(result: QualityResult, policy: QualityPolicy): QualityResult;
|
|
13
|
+
export declare class ExactMatchEvaluator implements Evaluator {
|
|
14
|
+
name: string;
|
|
15
|
+
evaluate(input: EvaluationInput): Promise<QualityResult>;
|
|
16
|
+
}
|
|
@@ -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,41 @@
|
|
|
1
|
+
import type { GithubIdentity } from "./accounts.js";
|
|
2
|
+
/**
|
|
3
|
+
* GitHub OAuth — the one identity step in signup. First login auto-creates the
|
|
4
|
+
* account (no approval), so this module only needs to (a) build the authorize
|
|
5
|
+
* URL, (b) issue and verify a stateless CSRF `state`, and (c) exchange the
|
|
6
|
+
* returned code for a stable GitHub identity.
|
|
7
|
+
*
|
|
8
|
+
* The `state` is an HMAC-signed `nonce.timestamp` rather than server-side
|
|
9
|
+
* session storage, so the API stays stateless and horizontally scalable. The
|
|
10
|
+
* fetch calls are injectable so the whole exchange is unit-testable with no
|
|
11
|
+
* network.
|
|
12
|
+
*
|
|
13
|
+
* Only identity is read: numeric GitHub id (stable across renames), login, and
|
|
14
|
+
* a verified primary email when the user has shared one. The short-lived access
|
|
15
|
+
* token is used for those two reads and then discarded — never stored.
|
|
16
|
+
*/
|
|
17
|
+
export type GithubOAuthConfig = {
|
|
18
|
+
clientId: string;
|
|
19
|
+
clientSecret: string;
|
|
20
|
+
/** Where GitHub redirects back with the code; must match the OAuth app setting. */
|
|
21
|
+
redirectUri: string;
|
|
22
|
+
/** Secret for signing the stateless `state` token. */
|
|
23
|
+
stateSecret: string;
|
|
24
|
+
/** Scopes requested. Default: read:user user:email (identity + email only). */
|
|
25
|
+
scope?: string;
|
|
26
|
+
};
|
|
27
|
+
/** Mint a signed, time-stamped CSRF state token. */
|
|
28
|
+
export declare function createOAuthState(secret: string, now?: number): string;
|
|
29
|
+
/** Verify a state token's signature and freshness (constant-time on the signature). */
|
|
30
|
+
export declare function verifyOAuthState(secret: string, state: string, now?: number, maxAgeMs?: number): boolean;
|
|
31
|
+
/** Build the GitHub authorize URL a browser is redirected to. Pure. */
|
|
32
|
+
export declare function buildAuthorizeUrl(config: GithubOAuthConfig, state: string): string;
|
|
33
|
+
export type OAuthFetch = typeof fetch;
|
|
34
|
+
/**
|
|
35
|
+
* Exchange an authorization code for a GitHub identity: swap code → access
|
|
36
|
+
* token, then read the user and their verified primary email. The token never
|
|
37
|
+
* leaves this function.
|
|
38
|
+
*/
|
|
39
|
+
export declare function exchangeCodeForIdentity(config: GithubOAuthConfig, code: string, deps?: {
|
|
40
|
+
fetch?: OAuthFetch;
|
|
41
|
+
}): Promise<GithubIdentity>;
|
|
@@ -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,36 @@
|
|
|
1
|
+
export * from "./types.js";
|
|
2
|
+
export * from "./router.js";
|
|
3
|
+
export * from "./routing.js";
|
|
4
|
+
export * from "./evaluator.js";
|
|
5
|
+
export * from "./cost.js";
|
|
6
|
+
export * from "./confidence.js";
|
|
7
|
+
export * from "./cache-simulator.js";
|
|
8
|
+
export * from "./price-catalogue.js";
|
|
9
|
+
export * from "./token-reduction.js";
|
|
10
|
+
export * from "./tool-schema.js";
|
|
11
|
+
export * from "./savings-model.js";
|
|
12
|
+
export * from "./theo-coverage.js";
|
|
13
|
+
export * from "./savings-ledger.js";
|
|
14
|
+
export * from "./workflow-sessions.js";
|
|
15
|
+
export * from "./quote-report.js";
|
|
16
|
+
export * from "./traffic.js";
|
|
17
|
+
export * from "./triage.js";
|
|
18
|
+
export * from "./gateway.js";
|
|
19
|
+
export * from "./litellm.js";
|
|
20
|
+
export * from "./helicone.js";
|
|
21
|
+
export * from "./langfuse.js";
|
|
22
|
+
export * from "./model-prices.js";
|
|
23
|
+
export * from "./replay.js";
|
|
24
|
+
export * from "./provider-usage.js";
|
|
25
|
+
export * from "./stripe-sink.js";
|
|
26
|
+
export * from "./geo-visibility.js";
|
|
27
|
+
export * from "./output-diagnostics.js";
|
|
28
|
+
export * from "./stripe-billing.js";
|
|
29
|
+
export * from "./budget.js";
|
|
30
|
+
export * from "./security/index.js";
|
|
31
|
+
export * from "./accounts.js";
|
|
32
|
+
export * from "./account-store.js";
|
|
33
|
+
export * from "./ledger-store.js";
|
|
34
|
+
export * from "./github-oauth.js";
|
|
35
|
+
export * from "./stripe-client.js";
|
|
36
|
+
export * from "./billing-worker.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,62 @@
|
|
|
1
|
+
import { type LedgerRecord } from "./savings-ledger.js";
|
|
2
|
+
/**
|
|
3
|
+
* Server-side ledger storage with chain-verification-on-ingest.
|
|
4
|
+
*
|
|
5
|
+
* The proxy/SDK mirrors each hash-chained record it writes locally to the Mesh
|
|
6
|
+
* API; this is where the API stores it, per account, in an append-only JSONL
|
|
7
|
+
* spool. The one rule that makes "recompute it yourself" a guarantee rather
|
|
8
|
+
* than a promise: a record is stored ONLY if it is self-consistent AND
|
|
9
|
+
* continues the account's existing chain. A perturbed, forked, or gapped batch
|
|
10
|
+
* is a hard reject — it is never partially stored and never silently repaired.
|
|
11
|
+
*
|
|
12
|
+
* The mirror is fire-and-forget with retry, so the same records arrive more
|
|
13
|
+
* than once. Ingestion is therefore idempotent: records at or below the stored
|
|
14
|
+
* tail are recognised as replays and skipped (with a fork check against the
|
|
15
|
+
* tail), and only the genuine continuation is appended.
|
|
16
|
+
*/
|
|
17
|
+
/** The last stored record's position, all the store needs to extend the chain. */
|
|
18
|
+
export type LedgerTail = {
|
|
19
|
+
seq: number;
|
|
20
|
+
eventHash: string;
|
|
21
|
+
};
|
|
22
|
+
export type IngestVerification = {
|
|
23
|
+
ok: true;
|
|
24
|
+
/** Records beyond the current tail that should be appended, in order. */
|
|
25
|
+
newRecords: LedgerRecord[];
|
|
26
|
+
/** Leading records recognised as already-stored replays. */
|
|
27
|
+
skipped: number;
|
|
28
|
+
/** The tail after appending newRecords. */
|
|
29
|
+
tail: LedgerTail;
|
|
30
|
+
} | {
|
|
31
|
+
ok: false;
|
|
32
|
+
reason: string;
|
|
33
|
+
seq: number;
|
|
34
|
+
};
|
|
35
|
+
/**
|
|
36
|
+
* Verify that `records` form a valid continuation of `tail` (undefined = empty
|
|
37
|
+
* chain, starting at genesis). Pure: no I/O, so the whole accept/replay/reject
|
|
38
|
+
* decision is unit-testable. Allows a leading overlap of already-stored
|
|
39
|
+
* sequences (idempotent retries) and rejects any gap, fork, or tampered hash.
|
|
40
|
+
*/
|
|
41
|
+
export declare function verifyIngestBatch(tail: LedgerTail | undefined, records: readonly LedgerRecord[]): IngestVerification;
|
|
42
|
+
export type LedgerIngestResult = {
|
|
43
|
+
ok: true;
|
|
44
|
+
stored: number;
|
|
45
|
+
skipped: number;
|
|
46
|
+
tailSeq: number;
|
|
47
|
+
} | {
|
|
48
|
+
ok: false;
|
|
49
|
+
reason: string;
|
|
50
|
+
seq: number;
|
|
51
|
+
};
|
|
52
|
+
export interface LedgerStore {
|
|
53
|
+
append(accountId: string, records: readonly LedgerRecord[]): LedgerIngestResult;
|
|
54
|
+
readRecords(accountId: string): LedgerRecord[];
|
|
55
|
+
tail(accountId: string): LedgerTail | undefined;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* File-backed ledger store: one append-only JSONL spool per account under
|
|
59
|
+
* `<dir>/<accountId>.jsonl`. Tails are cached in memory and lazily resumed from
|
|
60
|
+
* the spool, so a server restart picks the chain up where it left off.
|
|
61
|
+
*/
|
|
62
|
+
export declare function openFileLedgerStore(dir: string): LedgerStore;
|
|
@@ -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;
|