@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.
Files changed (70) hide show
  1. package/LICENSE +98 -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 +6306 -0
  8. package/index.js +6204 -0
  9. package/package.json +39 -4
  10. package/types/blind-features.d.ts +28 -0
  11. package/types/cache-volatility-guard.d.ts +31 -0
  12. package/types/core/account-store.d.ts +7 -0
  13. package/types/core/accounts.d.ts +134 -0
  14. package/types/core/billing-worker.d.ts +113 -0
  15. package/types/core/budget.d.ts +216 -0
  16. package/types/core/cache-simulator.d.ts +271 -0
  17. package/types/core/confidence.d.ts +36 -0
  18. package/types/core/cost.d.ts +16 -0
  19. package/types/core/evaluator.d.ts +16 -0
  20. package/types/core/gateway.d.ts +75 -0
  21. package/types/core/geo-visibility.d.ts +25 -0
  22. package/types/core/github-oauth.d.ts +41 -0
  23. package/types/core/helicone.d.ts +6 -0
  24. package/types/core/index.d.ts +36 -0
  25. package/types/core/langfuse.d.ts +7 -0
  26. package/types/core/ledger-store.d.ts +62 -0
  27. package/types/core/litellm.d.ts +15 -0
  28. package/types/core/local-tier.d.ts +82 -0
  29. package/types/core/model-prices.d.ts +25 -0
  30. package/types/core/output-diagnostics.d.ts +39 -0
  31. package/types/core/price-catalogue.d.ts +168 -0
  32. package/types/core/provider-usage.d.ts +84 -0
  33. package/types/core/quote-report.d.ts +54 -0
  34. package/types/core/replay.d.ts +2 -0
  35. package/types/core/router.d.ts +9 -0
  36. package/types/core/routing.d.ts +282 -0
  37. package/types/core/savings-ledger.d.ts +349 -0
  38. package/types/core/savings-model.d.ts +132 -0
  39. package/types/core/stripe-billing.d.ts +67 -0
  40. package/types/core/stripe-client.d.ts +117 -0
  41. package/types/core/stripe-sink.d.ts +77 -0
  42. package/types/core/theo-coverage.d.ts +49 -0
  43. package/types/core/token-reduction.d.ts +219 -0
  44. package/types/core/tool-schema.d.ts +64 -0
  45. package/types/core/traffic.d.ts +182 -0
  46. package/types/core/triage.d.ts +70 -0
  47. package/types/core/types.d.ts +149 -0
  48. package/types/core/workflow-sessions.d.ts +50 -0
  49. package/types/cta.d.ts +60 -0
  50. package/types/evaluation-capture.d.ts +11 -0
  51. package/types/exact-cache.d.ts +20 -0
  52. package/types/graders.d.ts +53 -0
  53. package/types/index.d.ts +31 -0
  54. package/types/ledger-mirror.d.ts +38 -0
  55. package/types/openai.d.ts +23 -0
  56. package/types/proxy.d.ts +104 -0
  57. package/types/reduce-request.d.ts +272 -0
  58. package/types/replay-gate.d.ts +120 -0
  59. package/types/report.d.ts +33 -0
  60. package/types/routing.d.ts +11 -0
  61. package/types/savings-ledger.d.ts +22 -0
  62. package/types/savings-snapshot.d.ts +11 -0
  63. package/types/semantic-compaction.d.ts +84 -0
  64. package/types/telemetry.d.ts +6 -0
  65. package/types/theo-agent-store.d.ts +27 -0
  66. package/types/theo-agent.d.ts +247 -0
  67. package/types/theo-gate.d.ts +75 -0
  68. package/types/theo-policy.d.ts +219 -0
  69. package/types/types.d.ts +287 -0
  70. package/types/wrap.d.ts +60 -0
@@ -0,0 +1,82 @@
1
+ /**
2
+ * Local-tier router — PROTOTYPE (preview lever, off by default).
3
+ *
4
+ * The orchestration idea: run the requests a small open-weight model handles
5
+ * well (e.g. PrismML's Bonsai, served on a local OpenAI-compatible endpoint at
6
+ * http://127.0.0.1:8080/v1) on THAT model instead of the expensive cloud model,
7
+ * and keep only the hard requests on the cloud. Inference on a model you host is
8
+ * free at the margin, so the saving is the whole cloud cost that request would
9
+ * have incurred — valued here against the same price catalogue that prices every
10
+ * other MESH saving.
11
+ *
12
+ * This is a LOSSY lever: it changes which model answers, so it CAN change the
13
+ * answer. It is therefore off by default and, in production, must be gated by
14
+ * the replay-gate (a replay of the customer's own traffic proving the local
15
+ * model's answers held) before it is ever switched on for real traffic — exactly
16
+ * how MESH treats every other answer-affecting move. Billing uses the cloud cost
17
+ * avoided NET of the customer's own compute, never as if the local model were
18
+ * free of consequence.
19
+ *
20
+ * This module is the pure decision + economics. Wiring the chosen route into the
21
+ * proxy's forwarding path (send a "local" request to policy.endpoint with the
22
+ * caller's own key, translate the model field) is the next step and is kept out
23
+ * of the audited proxy until the gate is in place.
24
+ */
25
+ import { type PriceCatalogue, type TokenUsage } from "./price-catalogue.js";
26
+ /** What the router needs to know about a request to decide its route. */
27
+ export type LocalTierRequest = {
28
+ /** The cloud provider the request was aimed at, e.g. "anthropic" / "openai". */
29
+ provider: string;
30
+ /** The cloud model id it would otherwise run on — the baseline for savings. */
31
+ model: string;
32
+ /** Measured prompt size. Big contexts stay on the cloud model. */
33
+ inputTokens: number;
34
+ /** Tool / function definitions present. Tool-use requests stay on the cloud model by default. */
35
+ hasTools: boolean;
36
+ };
37
+ export type LocalTierPolicy = {
38
+ /** Off by default: this is an answer-changing lever, gated by replay in production. */
39
+ enabled: boolean;
40
+ /** Local OpenAI-compatible server, e.g. http://127.0.0.1:8080/v1 (PrismML Bonsai). */
41
+ endpoint: string;
42
+ /** The open-weight model the endpoint serves. */
43
+ localModel: string;
44
+ /** Cloud model ids eligible to be stood in for (usually the expensive ones). Empty = none. */
45
+ baselineModels: string[];
46
+ /** Only small requests route local; larger prompts stay on the cloud model. */
47
+ maxInputTokens: number;
48
+ /** Keep tool-use requests on the cloud model unless explicitly allowed. */
49
+ allowTools: boolean;
50
+ };
51
+ export type RouteDecision = {
52
+ route: "local";
53
+ endpoint: string;
54
+ model: string;
55
+ baseline: {
56
+ provider: string;
57
+ model: string;
58
+ };
59
+ reason: string;
60
+ } | {
61
+ route: "cloud";
62
+ reason: string;
63
+ };
64
+ export declare function defaultLocalTierPolicy(overrides?: Partial<LocalTierPolicy>): LocalTierPolicy;
65
+ /**
66
+ * Decide whether a request should run on the local open-weight model or stay on
67
+ * the cloud model. Conservative by construction: only small, tool-free requests
68
+ * aimed at an eligible baseline route local; everything else stays cloud, with a
69
+ * reason recorded either way.
70
+ */
71
+ export declare function decideRoute(req: LocalTierRequest, policy: LocalTierPolicy): RouteDecision;
72
+ /**
73
+ * The cloud cost a locally-run request avoided: the full catalogue-priced cost
74
+ * of that request at its baseline cloud model. Returns null when the baseline is
75
+ * unpriced (then the saving is recorded, never billed — as everywhere in MESH).
76
+ * This is the GROSS cloud spend avoided; the customer's own compute is netted off
77
+ * before any fee.
78
+ */
79
+ export declare function cloudCostAvoidedUsd(baseline: {
80
+ provider: string;
81
+ model: string;
82
+ }, usage: TokenUsage, catalogue: PriceCatalogue, at: string): number | null;
@@ -0,0 +1,25 @@
1
+ import { type PriceCatalogue } from "./price-catalogue.js";
2
+ /** Published list rates as observed on the capture date. */
3
+ export declare const publishedModelPrices: PriceCatalogue;
4
+ /**
5
+ * Anthropic's documented minimum cacheable prompt length, by model class:
6
+ * 1,024 tokens for Opus- and Sonnet-class models, 2,048 tokens for
7
+ * Haiku-class models (https://docs.claude.com/en/docs/build-with-claude/
8
+ * prompt-caching, captured 2026-10-08, same capture date as `ANTHROPIC`
9
+ * above). Below this minimum the provider processes the request without
10
+ * caching at all — not an error, a silent no-op — so a breakpoint placed on
11
+ * a shorter prefix can never be read back and would make MESH claim a
12
+ * saving that cannot happen.
13
+ *
14
+ * Matched on the raw model id by substring rather than through
15
+ * `resolveModelId`, because the minimum only depends on which model
16
+ * CLASS was called (Haiku vs. everything else), not on resolving the exact
17
+ * dated build to a catalogued price entry — a model id the price catalogue
18
+ * cannot resolve (an older or unlisted Claude build) still has a real
19
+ * minimum, and guessing wrong in the lenient direction (1,024 for an
20
+ * unrecognised id) risks stamping a Haiku-class model's too-short prefix.
21
+ * An id that is not recognisably Claude at all should never reach this
22
+ * function; callers only call it after confirming an Anthropic-shaped
23
+ * request.
24
+ */
25
+ export declare function anthropicCacheableMinimumTokens(modelId: string): number;
@@ -0,0 +1,39 @@
1
+ import { type TokenCounter } from "./token-reduction.js";
2
+ /**
3
+ * Output-side diagnostics: METERING, not mutation.
4
+ *
5
+ * Ground truth from real agent trajectories (docs/rnd/knowledge/
6
+ * 2026-10-26-output-token-ground-truth.md): ~24% of agent output tokens are
7
+ * lines already present verbatim in the request context (re-printed files,
8
+ * echoed tool results), output is ~29% of a well-cached agent's bill, and
9
+ * the waste concentrates in a minority of large completions. Chat traffic
10
+ * shows the same shape on later turns (p90 re-emission 61% on turn-2+
11
+ * responses in WildChat).
12
+ *
13
+ * MESH will not mutate model output — that is the deepest lossy territory
14
+ * there is — but it CAN measure the waste per request and put the number in
15
+ * front of the customer: the ledger records how many of a completion's
16
+ * tokens were re-emissions of its own context, and the statement shows what
17
+ * a diff-shaped integration would reclaim. Metering first; any mutation
18
+ * lever earns its way through a replay gate later, sized by these numbers.
19
+ *
20
+ * Method mirrors the trajectory study so the numbers are comparable:
21
+ * line-level, whitespace-normalized, leading line-number prefixes stripped,
22
+ * lines under 8 significant characters ignored. Deterministic, content never
23
+ * stored — only token counts leave this function.
24
+ */
25
+ export type OutputReEmission = {
26
+ /** Tokens of the completion text that were inspected (all of it). */
27
+ inspectedOutputTokens: number;
28
+ /** Tokens on lines already present verbatim in the request context. */
29
+ reEmittedOutputTokens: number;
30
+ /** Of the re-emitted tokens, those on lines that look like code. */
31
+ reEmittedCodeTokens: number;
32
+ };
33
+ /** Every string value in a request body, newline-joined, for line extraction. */
34
+ export declare function collectRequestText(value: unknown, depth?: number): string;
35
+ /**
36
+ * Measure what fraction of a completion is verbatim re-emission of lines the
37
+ * request already contained. Pure and deterministic.
38
+ */
39
+ export declare function measureOutputReEmission(requestText: string, outputText: string, countTokens?: TokenCounter): OutputReEmission;
@@ -0,0 +1,168 @@
1
+ import { type TokenPrice } from "./cost.js";
2
+ /**
3
+ * Where a rate came from, so a cost figure in a report can be traced back to a
4
+ * published price rather than taken on trust.
5
+ */
6
+ export type PriceProvenance = {
7
+ /** Published source the rate was read from. */
8
+ source: string;
9
+ /** ISO date (YYYY-MM-DD) the rate was read. */
10
+ capturedOn: string;
11
+ note?: string;
12
+ };
13
+ /**
14
+ * One rate band. Providers tier some models by prompt size, so a single model can
15
+ * carry several bands; exactly one band is unbounded.
16
+ */
17
+ export type PriceTier = TokenPrice & {
18
+ /** Applies when input tokens are at most this value; omit for the unbounded band. */
19
+ maxInputTokens?: number;
20
+ };
21
+ /** A provider's published rate for one model over one date range. */
22
+ export type ModelPriceEntry = {
23
+ provider: string;
24
+ model: string;
25
+ /** Billing mode; distinct modes price independently over the same dates. */
26
+ mode: "standard" | "batch" | "flex";
27
+ /** Inclusive ISO date this rate took effect. */
28
+ effectiveFrom: string;
29
+ /** Exclusive ISO date this rate stopped applying; omit while current. */
30
+ effectiveTo?: string;
31
+ tiers: PriceTier[];
32
+ provenance: PriceProvenance;
33
+ };
34
+ /**
35
+ * A customer's contracted rate, layered over published prices. Either a flat
36
+ * discount on the published rate or a full replacement set of bands.
37
+ */
38
+ export type NegotiatedRate = {
39
+ provider: string;
40
+ model: string;
41
+ mode?: ModelPriceEntry["mode"];
42
+ effectiveFrom: string;
43
+ effectiveTo?: string;
44
+ /** Percentage off every published rate, 0-100. Mutually exclusive with `tiers`. */
45
+ discountPercent?: number;
46
+ /** Replacement bands. Mutually exclusive with `discountPercent`. */
47
+ tiers?: PriceTier[];
48
+ provenance: PriceProvenance;
49
+ };
50
+ export type PriceCatalogue = {
51
+ entries: ModelPriceEntry[];
52
+ negotiated: NegotiatedRate[];
53
+ /** API-identifier to catalogue-key mappings; see resolveModelId. */
54
+ aliases?: ModelAlias[];
55
+ };
56
+ export type PriceLookup = {
57
+ status: "priced";
58
+ price: TokenPrice;
59
+ entry: ModelPriceEntry;
60
+ negotiated?: NegotiatedRate;
61
+ } | {
62
+ status: "unpriced";
63
+ reason: string;
64
+ };
65
+ export type UsagePricing = {
66
+ status: "priced";
67
+ costUsd: number;
68
+ price: TokenPrice;
69
+ entry: ModelPriceEntry;
70
+ negotiated?: NegotiatedRate;
71
+ } | {
72
+ status: "unpriced";
73
+ reason: string;
74
+ };
75
+ export type TokenUsage = {
76
+ inputTokens: number;
77
+ outputTokens: number;
78
+ cachedInputTokens?: number;
79
+ /** TOTAL cache writes, inclusive of any 1h share below. */
80
+ cacheWriteInputTokens?: number;
81
+ /** The share of the writes above that carried the 1h TTL (bills a premium). */
82
+ cacheWrite1hInputTokens?: number;
83
+ };
84
+ export type PriceQuery = {
85
+ provider: string;
86
+ model: string;
87
+ mode?: ModelPriceEntry["mode"];
88
+ /** ISO date the request was billed on. */
89
+ at: string;
90
+ };
91
+ /**
92
+ * Validate a catalogue. Overlapping date ranges for one provider/model/mode are
93
+ * rejected rather than resolved, because silently picking one of two candidate
94
+ * rates would make a cost figure unreproducible.
95
+ */
96
+ export declare function validatePriceCatalogue(catalogue: PriceCatalogue): PriceCatalogue;
97
+ /**
98
+ * Resolve the rate that applied to one model on one date. Returns an explicit
99
+ * `unpriced` result rather than a zero, so a missing price can never be mistaken
100
+ * for free inference.
101
+ */
102
+ export declare function lookupPrice(catalogue: PriceCatalogue, query: PriceQuery, inputTokens?: number): PriceLookup;
103
+ /**
104
+ * Cost of one recorded request. Token counts come from the provider's own usage
105
+ * fields; the rate comes from the catalogue, never from the traffic itself.
106
+ */
107
+ export declare function priceUsage(catalogue: PriceCatalogue, query: PriceQuery, usage: TokenUsage): UsagePricing;
108
+ export type RepriceComparison = {
109
+ baseline: UsagePricing;
110
+ candidate: UsagePricing;
111
+ /** Set only when both sides priced; positive means the candidate is cheaper. */
112
+ savingsUsd?: number;
113
+ savingsPercent?: number;
114
+ };
115
+ /**
116
+ * Re-price recorded usage against a different model, provider, or billing mode.
117
+ * Both sides must price before a saving is reported: a comparison against an
118
+ * unpriced model is not a comparison.
119
+ */
120
+ export declare function repriceUsage(catalogue: PriceCatalogue, baseline: PriceQuery, candidate: PriceQuery, usage: TokenUsage): RepriceComparison;
121
+ /** Parse an externally supplied catalogue, for example a customer's contracted rates. */
122
+ export declare function parsePriceCatalogue(value: unknown): PriceCatalogue;
123
+ /** Combine catalogues, for example published rates plus a customer's contract. */
124
+ export declare function mergePriceCatalogues(...catalogues: PriceCatalogue[]): PriceCatalogue;
125
+ /**
126
+ * Deterministic JSON: object keys sorted recursively, `undefined` members
127
+ * omitted. Two structurally equal values always serialise to identical bytes,
128
+ * which is what makes content hashes over catalogues and ledger events stable.
129
+ */
130
+ export declare function canonicalJson(value: unknown): string;
131
+ /**
132
+ * Content hash of a catalogue. Pinned onto every ledger event at write time, so
133
+ * an invoice names the exact rates it was computed against and a later
134
+ * catalogue update can never silently re-price history.
135
+ */
136
+ export declare function catalogueVersion(catalogue: PriceCatalogue): string;
137
+ /** Maps an API model identifier onto a catalogue key. */
138
+ export type ModelAlias = {
139
+ provider: string;
140
+ /** Exact API model id, or a prefix ending in "*". */
141
+ id: string;
142
+ /** Catalogue model key this resolves to. */
143
+ model: string;
144
+ };
145
+ export type ModelResolution = {
146
+ status: "resolved";
147
+ model: string;
148
+ via: "exact" | "alias" | "normalised";
149
+ } | {
150
+ status: "unresolved";
151
+ reason: string;
152
+ candidates: string[];
153
+ };
154
+ /**
155
+ * Resolve the model id a log carries onto a catalogue key.
156
+ *
157
+ * Catalogue keys are the names providers publish on their pricing pages
158
+ * ("Sonnet 5.5"); logs carry API identifiers ("claude-sonnet-5-5-20260514").
159
+ * Without this every real row prices as unpriced.
160
+ *
161
+ * Resolution never guesses. Exact matches win, then explicit aliases, then a
162
+ * normalised comparison that strips punctuation, case and a trailing release
163
+ * date. Where normalisation admits more than one catalogue key the longest
164
+ * match wins, so "sonnet 5.5" beats "sonnet 5" on `claude-sonnet-5-5`; where two
165
+ * keys tie, the result is unresolved and names the candidates, because pricing
166
+ * traffic against a coin flip is a billing error rather than a convenience.
167
+ */
168
+ export declare function resolveModelId(catalogue: PriceCatalogue, provider: string, rawModelId: string): ModelResolution;
@@ -0,0 +1,84 @@
1
+ /**
2
+ * The single shared provider-usage normaliser.
3
+ *
4
+ * Hoisted from the replay gate (packages/sdk-js/src/replay-gate.ts replayUsage)
5
+ * so every MESH component - the request-path SDK wrapper, the replay gate, and
6
+ * the ledger - reads provider usage through ONE parser. The old arrangement had
7
+ * three divergent parsers: the SDK wrapper's tokenUsage returned undefined on
8
+ * both the Chat Completions shape (prompt_tokens) and the Anthropic shape
9
+ * (cache reads/writes OUTSIDE input_tokens), which silently dropped usage - and
10
+ * therefore billing evidence - on every non-Responses surface.
11
+ *
12
+ * The two provider conventions, both normalised to a TOTAL-INCLUSIVE figure:
13
+ *
14
+ * OpenAI (Responses and Chat Completions) reports cached tokens INSIDE
15
+ * input_tokens/prompt_tokens. `prompt_tokens_details.cache_write_tokens` is
16
+ * informational: OpenAI publishes no cache-write rate, so writes are
17
+ * normalised to zero and never priced ($0, informational).
18
+ *
19
+ * Anthropic reports cache reads and writes ALONGSIDE input_tokens:
20
+ * total input = input_tokens + cache_read_input_tokens + cache writes.
21
+ * Cache writes may carry a TTL split in `usage.cache_creation`
22
+ * ({ephemeral_5m_input_tokens, ephemeral_1h_input_tokens}); when both the
23
+ * split and the flat cache_creation_input_tokens are present they must sum
24
+ * exactly, or the usage is INVALID rather than silently repaired - a billing
25
+ * record built on inconsistent provider usage is a dispute, not an estimate.
26
+ *
27
+ * Response-side execution-tier evidence is normalised here too: OpenAI reports
28
+ * a top-level `service_tier` on the response; Anthropic reports
29
+ * `usage.service_tier` ("standard" | "priority" | "batch"). Billing reads the
30
+ * tier the provider ANSWERED with, never the one the request asked for.
31
+ * "priority" maps to standard pricing (MESH claims no saving on it) and
32
+ * "batch" maps to the batch execution mode.
33
+ */
34
+ export type NormalizedProviderUsage = {
35
+ /** Total input billed, inclusive of cache reads and cache writes. */
36
+ inputTokens: number;
37
+ /** Input billed at the full rate: total minus cached minus written. */
38
+ uncachedInputTokens: number;
39
+ /** Input served from the provider's cache, billed at the cached rate. */
40
+ cachedInputTokens: number;
41
+ /** Total input written into the provider's cache (Anthropic bills a premium). */
42
+ cacheWriteInputTokens: number;
43
+ /**
44
+ * TTL split of the cache writes, present ONLY when the provider reported it
45
+ * (Anthropic usage.cache_creation). Absent means the split is unknown, which
46
+ * downstream pricing must treat conservatively, never as "all 5m".
47
+ */
48
+ cacheWrite5mInputTokens?: number;
49
+ cacheWrite1hInputTokens?: number;
50
+ outputTokens: number;
51
+ };
52
+ export type ProviderUsageResult =
53
+ /** Usage read and internally consistent. */
54
+ {
55
+ status: "ok";
56
+ usage: NormalizedProviderUsage;
57
+ }
58
+ /** Usage present but unreadable or inconsistent; the reason is auditable. */
59
+ | {
60
+ status: "invalid";
61
+ reason: string;
62
+ }
63
+ /** The response carries no usage object at all. */
64
+ | {
65
+ status: "missing";
66
+ };
67
+ /** Normalise one provider response's usage, or say exactly why it cannot be. */
68
+ export declare function normalizeProviderUsage(response: unknown): ProviderUsageResult;
69
+ /** Convenience view of normalizeProviderUsage: the usage, or undefined. */
70
+ export declare function providerUsage(response: unknown): NormalizedProviderUsage | undefined;
71
+ export type ResponseExecutionMode = "standard" | "flex" | "batch";
72
+ /**
73
+ * The service tier the provider ANSWERED with: OpenAI's top-level
74
+ * response.service_tier, else Anthropic's usage.service_tier. Returns the
75
+ * provider's own string untouched; map it with executionModeFromServiceTier.
76
+ */
77
+ export declare function responseServiceTier(response: unknown): string | undefined;
78
+ /**
79
+ * Map response-side tier evidence onto a billing execution mode. "flex" and
80
+ * "batch" are the only modes with their own catalogue rates; Anthropic's
81
+ * "priority" (and every unknown value) maps to STANDARD pricing, so MESH never
82
+ * claims a tier saving it cannot price.
83
+ */
84
+ export declare function executionModeFromServiceTier(serviceTier: string | undefined): ResponseExecutionMode;
@@ -0,0 +1,54 @@
1
+ import { type GatewayParseResult, type SpendReconciliation } from "./gateway.js";
2
+ import { type PriceCatalogue } from "./price-catalogue.js";
3
+ import { type SegmentQuote } from "./triage.js";
4
+ /**
5
+ * The pre-contract quote, built from a design partner's OWN gateway export.
6
+ *
7
+ * One file of their real traffic in; one shareable report out: which customer
8
+ * shape each stream is, what MESH is honestly worth on it, what their own
9
+ * gateway already saves them (credited, never billed), and -- when nothing is
10
+ * worth charging for -- the explicit "do not pay us" answer. Every band in the
11
+ * report cites the measurement it is an analogue of; nothing here invents a
12
+ * number the triage pipeline did not already defend.
13
+ *
14
+ * This module only composes the existing adapters and triage; the quoting
15
+ * logic itself lives in triage.ts and is exercised by the gate suites.
16
+ */
17
+ export type QuoteExportFormat = "litellm" | "helicone" | "langfuse";
18
+ export type QuoteStreamReport = {
19
+ stream: string;
20
+ requests: number;
21
+ /** Catalogue-priced baseline for the stream's provider calls. */
22
+ baselineUsd: number;
23
+ quote: SegmentQuote;
24
+ };
25
+ export type QuoteReport = {
26
+ schemaVersion: 1;
27
+ format: QuoteExportFormat;
28
+ /** Billing date the rates were resolved on. */
29
+ at: string;
30
+ /** Content hash of the price catalogue used, so the quote is reproducible. */
31
+ catalogueVersion: string;
32
+ /** Deterministic fingerprint of the accepted rows the quote was built from. */
33
+ trafficFingerprint: string;
34
+ rows: {
35
+ accepted: number;
36
+ gatewayCacheHits: number;
37
+ unreadable: number;
38
+ };
39
+ /** Largest baseline first. */
40
+ streams: QuoteStreamReport[];
41
+ reconciliation: SpendReconciliation;
42
+ /** True when every stream triages to "not worth charging for". */
43
+ doNotPayUs: boolean;
44
+ };
45
+ /** Parse a gateway export with the right adapter. Unreadable rows are reported, never dropped silently. */
46
+ export declare function parseGatewayExport(rows: unknown[], format: QuoteExportFormat, fallbackDate: string): GatewayParseResult;
47
+ /** Build the quote report from raw export rows. Pure and deterministic. */
48
+ export declare function buildQuoteReport(rows: unknown[], options: {
49
+ format: QuoteExportFormat;
50
+ at: string;
51
+ catalogue: PriceCatalogue;
52
+ }): QuoteReport;
53
+ /** Render the report for a human: bands, caveats, credits and verdicts. */
54
+ export declare function renderQuoteReport(report: QuoteReport): string;
@@ -0,0 +1,2 @@
1
+ import type { ReplayPolicy, ReplayRecord, ReplayReport } from "./types.js";
2
+ export declare function evaluateReplay(records: ReplayRecord[], policy: ReplayPolicy): ReplayReport;
@@ -0,0 +1,9 @@
1
+ import type { RoutingDecision, RoutingPolicy } from "./types.js";
2
+ export type RouterContext = {
3
+ taskClass?: string;
4
+ requestHash?: string;
5
+ random?: () => number;
6
+ };
7
+ export declare class SafeRouter {
8
+ decide(policy: RoutingPolicy | undefined, ctx: RouterContext): RoutingDecision;
9
+ }