@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,132 @@
|
|
|
1
|
+
import { type TokenPrice } from "./cost.js";
|
|
2
|
+
/**
|
|
3
|
+
* Composable cost-reduction model.
|
|
4
|
+
*
|
|
5
|
+
* A single lever looks unimpressive. Model routing on LLMRouterBench's MMLU-Pro
|
|
6
|
+
* returned 9.73% and bought it with quality. The levers below are different in
|
|
7
|
+
* two ways: most of them do not touch the answer, and they attack disjoint parts
|
|
8
|
+
* of a request, so they compose rather than compete.
|
|
9
|
+
*
|
|
10
|
+
* A request is modelled as segments, because each lever only reaches some of
|
|
11
|
+
* them. Tool-schema minification cannot help a RAG prompt with no tools, and
|
|
12
|
+
* prefix caching cannot help the one segment that changes every request. Summing
|
|
13
|
+
* headline percentages across levers double-counts; applying them to the
|
|
14
|
+
* segments they actually target does not.
|
|
15
|
+
*
|
|
16
|
+
* Order matters and is fixed: reducers shrink segments first, then caching prices
|
|
17
|
+
* whatever stable tokens remain. Minifying a tool catalogue and then caching it
|
|
18
|
+
* must charge the cache rate on the minified size, not the original.
|
|
19
|
+
*
|
|
20
|
+
* Every lever carries the published evidence for its reduction factor. Those
|
|
21
|
+
* factors come from their authors' benchmarks, not from MESH measuring them on
|
|
22
|
+
* your traffic, so a projection from this model is a hypothesis to verify by
|
|
23
|
+
* replay, never a realised saving. Realised savings come from provider-reported
|
|
24
|
+
* usage priced through the catalogue.
|
|
25
|
+
*/
|
|
26
|
+
export type WorkloadSegment = "toolSchemas" | "systemPrompt" | "retrievedContext" | "history" | "userTurn" | "output";
|
|
27
|
+
export declare const INPUT_SEGMENTS: readonly WorkloadSegment[];
|
|
28
|
+
/**
|
|
29
|
+
* How confident a saving is before it is measured on the customer's own traffic.
|
|
30
|
+
*
|
|
31
|
+
* - `deterministic`: the request is provably equivalent, or the provider bills
|
|
32
|
+
* the same tokens at a lower rate. Nothing about the answer can change.
|
|
33
|
+
* - `needs-verification`: the prompt or the output budget changes, so quality
|
|
34
|
+
* has to be shown to hold by replay before the lever is enabled.
|
|
35
|
+
*/
|
|
36
|
+
export type LeverRisk = "deterministic" | "needs-verification";
|
|
37
|
+
export type LeverEvidence = {
|
|
38
|
+
/** Where the reduction factor comes from. */
|
|
39
|
+
source: string;
|
|
40
|
+
/** What that source measured, in its own terms. */
|
|
41
|
+
claim: string;
|
|
42
|
+
};
|
|
43
|
+
export type Lever = {
|
|
44
|
+
id: string;
|
|
45
|
+
description: string;
|
|
46
|
+
risk: LeverRisk;
|
|
47
|
+
/** Segments this lever can reach; it has no effect on any other. */
|
|
48
|
+
targets: readonly WorkloadSegment[];
|
|
49
|
+
/** Share of targeted tokens removed, between 0 and 1. */
|
|
50
|
+
reduction: number;
|
|
51
|
+
/**
|
|
52
|
+
* How this lever changes the number of calls a task takes. 1 leaves it
|
|
53
|
+
* unchanged, 1.5 adds half a round trip per existing one, 0.3 removes most of
|
|
54
|
+
* them. Above 1 can make a lever net negative however much it trims per
|
|
55
|
+
* prompt, which is the whole reason this field exists: a published bench found
|
|
56
|
+
* progressive disclosure modelled at ~77% delivering ~13%, because the router
|
|
57
|
+
* it adds costs one extra round trip per novel tool call.
|
|
58
|
+
*/
|
|
59
|
+
roundTripMultiplier?: number;
|
|
60
|
+
evidence: LeverEvidence;
|
|
61
|
+
};
|
|
62
|
+
export type WorkloadProfile = {
|
|
63
|
+
name: string;
|
|
64
|
+
/** Requests the projection covers; caching needs more than one to pay off. */
|
|
65
|
+
requests: number;
|
|
66
|
+
/** Mean tokens per request in each segment. */
|
|
67
|
+
segments: Record<WorkloadSegment, number>;
|
|
68
|
+
/**
|
|
69
|
+
* Segments byte-identical across requests, so a provider's prefix cache can
|
|
70
|
+
* serve them. Order is the prompt order: caching stops at the first segment
|
|
71
|
+
* that changes, so anything listed after a volatile segment cannot cache.
|
|
72
|
+
*/
|
|
73
|
+
stableSegments: readonly WorkloadSegment[];
|
|
74
|
+
};
|
|
75
|
+
export type LeverContribution = {
|
|
76
|
+
lever: string;
|
|
77
|
+
risk: LeverRisk;
|
|
78
|
+
tokensRemoved: number;
|
|
79
|
+
costRemovedUsd: number;
|
|
80
|
+
/** Share of the baseline bill this lever alone removes, given the levers before it. */
|
|
81
|
+
sharePercent: number;
|
|
82
|
+
evidence: LeverEvidence;
|
|
83
|
+
};
|
|
84
|
+
export type SavingsProjection = {
|
|
85
|
+
workload: string;
|
|
86
|
+
requests: number;
|
|
87
|
+
baselineCostUsd: number;
|
|
88
|
+
projectedCostUsd: number;
|
|
89
|
+
savingUsd: number;
|
|
90
|
+
savingPercent: number;
|
|
91
|
+
/** The share achievable without any possibility of changing an answer. */
|
|
92
|
+
deterministicSavingPercent: number;
|
|
93
|
+
/** The additional share that requires a replay check before rollout. */
|
|
94
|
+
needsVerificationSavingPercent: number;
|
|
95
|
+
contributions: LeverContribution[];
|
|
96
|
+
inputTokensBefore: number;
|
|
97
|
+
inputTokensAfter: number;
|
|
98
|
+
outputTokensBefore: number;
|
|
99
|
+
outputTokensAfter: number;
|
|
100
|
+
cachedInputTokens: number;
|
|
101
|
+
/** Calls per task before any lever. */
|
|
102
|
+
roundTripsBefore: number;
|
|
103
|
+
/** Calls per task after every lever's effect on call count. */
|
|
104
|
+
roundTripsAfter: number;
|
|
105
|
+
warnings: string[];
|
|
106
|
+
};
|
|
107
|
+
/**
|
|
108
|
+
* Published levers, with the evidence for each factor.
|
|
109
|
+
*
|
|
110
|
+
* Factors are deliberately set at or below the conservative end of what each
|
|
111
|
+
* source reports. A model that projects a vendor's best-case number is the thing
|
|
112
|
+
* this project exists to argue against.
|
|
113
|
+
*/
|
|
114
|
+
export declare const PUBLISHED_LEVERS: Record<string, Lever>;
|
|
115
|
+
/**
|
|
116
|
+
* Project the cost of a workload after a set of levers.
|
|
117
|
+
*
|
|
118
|
+
* Caching is applied last and only to stable segments that remain contiguous
|
|
119
|
+
* from the start of the prompt, because providers match on an exact prefix: the
|
|
120
|
+
* first segment that varies ends the cacheable region regardless of what follows.
|
|
121
|
+
*/
|
|
122
|
+
export declare function projectSavings(profile: WorkloadProfile, levers: Lever[], price: TokenPrice, options?: {
|
|
123
|
+
minimumCacheableTokens?: number;
|
|
124
|
+
}): SavingsProjection;
|
|
125
|
+
/**
|
|
126
|
+
* Workload shapes the levers behave very differently on. The headline number a
|
|
127
|
+
* customer sees depends far more on which of these they are than on anything
|
|
128
|
+
* MESH does, which is why one global percentage would be misleading.
|
|
129
|
+
*/
|
|
130
|
+
export declare const WORKLOAD_ARCHETYPES: Record<string, WorkloadProfile>;
|
|
131
|
+
/** Levers applicable to a profile, in the order they should be applied. */
|
|
132
|
+
export declare function leversFor(profile: WorkloadProfile): Lever[];
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import type { Invoice } from "./savings-ledger.js";
|
|
2
|
+
/**
|
|
3
|
+
* Turning a recomputed MESH invoice into a Stripe charge — the honest way.
|
|
4
|
+
*
|
|
5
|
+
* This module is PURE: it converts an `Invoice` (the output of
|
|
6
|
+
* `recomputeInvoice`, itself a pure function over the customer's own
|
|
7
|
+
* hash-chained ledger) into a `StripeInvoicePlan` — the exact set of Stripe API
|
|
8
|
+
* calls that would bill it. No network here; the executor (mesh-bill script)
|
|
9
|
+
* runs the plan. Keeping it pure means the billing arithmetic is unit-tested
|
|
10
|
+
* without touching Stripe, and the plan can be shown to a human before anything
|
|
11
|
+
* is created.
|
|
12
|
+
*
|
|
13
|
+
* The invariants that matter for a verified-savings vendor:
|
|
14
|
+
* - A broken/unverified ledger NEVER bills. verdict carries DO_NOT_BILL.
|
|
15
|
+
* - A non-positive net period bills nothing (do_not_charge), and a carried
|
|
16
|
+
* deficit is surfaced, never hidden.
|
|
17
|
+
* - The amount is 1% (or the contracted feePercent) of NET verified savings,
|
|
18
|
+
* taken straight from the invoice — this module does not recompute savings,
|
|
19
|
+
* it only formats the already-verified number for Stripe.
|
|
20
|
+
* - The line-item description traces to the recomputable statement, so the
|
|
21
|
+
* customer can check the charge against their own ledger.
|
|
22
|
+
* - Every create call carries an idempotency key keyed on customer+period, so
|
|
23
|
+
* re-running a month cannot double-bill.
|
|
24
|
+
*/
|
|
25
|
+
export type StripeBillingOptions = {
|
|
26
|
+
/** Stripe customer id (cus_…) the fee is billed to. */
|
|
27
|
+
stripeCustomerId: string;
|
|
28
|
+
/** Currency for the invoice. MESH fees are USD-denominated. */
|
|
29
|
+
currency?: string;
|
|
30
|
+
/**
|
|
31
|
+
* Whether to finalize+send the invoice or leave it as a reviewable DRAFT.
|
|
32
|
+
* Default "draft": nothing is ever charged without a human finalizing it.
|
|
33
|
+
*/
|
|
34
|
+
mode?: "draft" | "finalize";
|
|
35
|
+
/** Label for the customer's statement, e.g. the spool set or app id. */
|
|
36
|
+
customerLabel?: string;
|
|
37
|
+
};
|
|
38
|
+
export type StripeInvoicePlan = {
|
|
39
|
+
action: "bill";
|
|
40
|
+
/** cus_… the invoice item + invoice attach to. */
|
|
41
|
+
customerId: string;
|
|
42
|
+
/** Integer minor units (cents) — Stripe never takes floats. */
|
|
43
|
+
amountCents: number;
|
|
44
|
+
currency: string;
|
|
45
|
+
/** Human-readable, traces to the recomputable statement. */
|
|
46
|
+
description: string;
|
|
47
|
+
/** Keyed on customer+period so a re-run cannot double-bill. */
|
|
48
|
+
idempotencyKey: string;
|
|
49
|
+
finalize: boolean;
|
|
50
|
+
/** Carried into the explanatory metadata on the Stripe objects. */
|
|
51
|
+
metadata: Record<string, string>;
|
|
52
|
+
} | {
|
|
53
|
+
action: "do_not_bill";
|
|
54
|
+
/** Why nothing is billed: do_not_charge, deficit carried, or chain broken. */
|
|
55
|
+
reason: string;
|
|
56
|
+
/** True only when the ledger failed verification — the hard stop. */
|
|
57
|
+
chainUnverified: boolean;
|
|
58
|
+
};
|
|
59
|
+
/**
|
|
60
|
+
* Build the Stripe plan for one recomputed invoice.
|
|
61
|
+
*
|
|
62
|
+
* `chainVerified` is passed in (not read from the invoice) because chain
|
|
63
|
+
* verification is the ledger layer's job: the caller verifies the spool and
|
|
64
|
+
* tells us. An unverified chain is a hard DO_NOT_BILL — a statement over an
|
|
65
|
+
* unverifiable ledger is not an invoice.
|
|
66
|
+
*/
|
|
67
|
+
export declare function buildStripeInvoicePlan(invoice: Invoice, chainVerified: boolean, options: StripeBillingOptions): StripeInvoicePlan;
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A dependency-free Stripe REST client — the one place MESH talks to Stripe.
|
|
3
|
+
*
|
|
4
|
+
* Promoted from the form-encoded `stripePost` in scripts/mesh-bill so the
|
|
5
|
+
* automated billing worker and the self-serve payment endpoints share one
|
|
6
|
+
* hardened client instead of re-rolling fetch calls. Everything is
|
|
7
|
+
* form-encoded, idempotency-keyed, and zero-dependency, matching the repo.
|
|
8
|
+
*
|
|
9
|
+
* SAFETY: the client refuses a live secret key (sk_live_…) unless `allowLive`
|
|
10
|
+
* is passed explicitly. The automated signup/metering/billing paths NEVER pass
|
|
11
|
+
* it, so no amount of configuration can make the unattended system charge real
|
|
12
|
+
* money — live billing stays the deliberate, human-gated mesh-bill --live path.
|
|
13
|
+
*/
|
|
14
|
+
export type StripeMode = "test" | "live";
|
|
15
|
+
/** Nested form values (objects/arrays) flattened to Stripe's bracket notation. */
|
|
16
|
+
export type StripeForm = Record<string, string | number | boolean | undefined>;
|
|
17
|
+
export type StripeCustomer = {
|
|
18
|
+
id: string;
|
|
19
|
+
};
|
|
20
|
+
export type StripeCheckoutSession = {
|
|
21
|
+
id: string;
|
|
22
|
+
url: string | null;
|
|
23
|
+
status?: string;
|
|
24
|
+
};
|
|
25
|
+
export type StripeSetupIntent = {
|
|
26
|
+
id: string;
|
|
27
|
+
status: string;
|
|
28
|
+
client_secret: string | null;
|
|
29
|
+
payment_method: string | null;
|
|
30
|
+
};
|
|
31
|
+
export type StripeInvoiceItem = {
|
|
32
|
+
id: string;
|
|
33
|
+
};
|
|
34
|
+
export type StripeInvoice = {
|
|
35
|
+
id: string;
|
|
36
|
+
status: string;
|
|
37
|
+
amount_due?: number;
|
|
38
|
+
hosted_invoice_url?: string | null;
|
|
39
|
+
payment_intent?: string | null;
|
|
40
|
+
};
|
|
41
|
+
export type StripeRefund = {
|
|
42
|
+
id: string;
|
|
43
|
+
status: string;
|
|
44
|
+
};
|
|
45
|
+
/**
|
|
46
|
+
* The operations the billing worker depends on. Narrow on purpose so the
|
|
47
|
+
* worker can be unit-tested with a fake, and so the payment-choice branching is
|
|
48
|
+
* exercised without a Stripe account.
|
|
49
|
+
*/
|
|
50
|
+
export interface BillingStripe {
|
|
51
|
+
readonly mode: StripeMode;
|
|
52
|
+
createInvoice(params: {
|
|
53
|
+
customerId: string;
|
|
54
|
+
currency: string;
|
|
55
|
+
collectionMethod: "charge_automatically" | "send_invoice";
|
|
56
|
+
description?: string;
|
|
57
|
+
daysUntilDue?: number;
|
|
58
|
+
defaultPaymentMethod?: string;
|
|
59
|
+
autoAdvance?: boolean;
|
|
60
|
+
metadata?: Record<string, string>;
|
|
61
|
+
idempotencyKey?: string;
|
|
62
|
+
}): Promise<StripeInvoice>;
|
|
63
|
+
createInvoiceItem(params: {
|
|
64
|
+
customerId: string;
|
|
65
|
+
invoiceId: string;
|
|
66
|
+
amountCents: number;
|
|
67
|
+
currency: string;
|
|
68
|
+
description: string;
|
|
69
|
+
metadata?: Record<string, string>;
|
|
70
|
+
idempotencyKey?: string;
|
|
71
|
+
}): Promise<StripeInvoiceItem>;
|
|
72
|
+
finalizeInvoice(invoiceId: string, idempotencyKey?: string): Promise<StripeInvoice>;
|
|
73
|
+
payInvoice(invoiceId: string, idempotencyKey?: string): Promise<StripeInvoice>;
|
|
74
|
+
}
|
|
75
|
+
/** The fuller surface the payment-setup and admin endpoints use. */
|
|
76
|
+
export interface StripeClient extends BillingStripe {
|
|
77
|
+
createCustomer(params: {
|
|
78
|
+
email?: string;
|
|
79
|
+
metadata?: Record<string, string>;
|
|
80
|
+
idempotencyKey?: string;
|
|
81
|
+
}): Promise<StripeCustomer>;
|
|
82
|
+
createMandateCheckoutSession(params: {
|
|
83
|
+
customerId: string;
|
|
84
|
+
paymentMethodTypes: string[];
|
|
85
|
+
successUrl: string;
|
|
86
|
+
cancelUrl: string;
|
|
87
|
+
currency: string;
|
|
88
|
+
idempotencyKey?: string;
|
|
89
|
+
}): Promise<StripeCheckoutSession>;
|
|
90
|
+
getCheckoutSession(sessionId: string): Promise<StripeCheckoutSession & {
|
|
91
|
+
setup_intent: string | null;
|
|
92
|
+
customer: string | null;
|
|
93
|
+
}>;
|
|
94
|
+
getSetupIntent(setupIntentId: string): Promise<StripeSetupIntent>;
|
|
95
|
+
setDefaultPaymentMethod(customerId: string, paymentMethodId: string): Promise<void>;
|
|
96
|
+
createRefund(params: {
|
|
97
|
+
paymentIntentId: string;
|
|
98
|
+
amountCents?: number;
|
|
99
|
+
idempotencyKey?: string;
|
|
100
|
+
}): Promise<StripeRefund>;
|
|
101
|
+
getInvoice(invoiceId: string): Promise<StripeInvoice>;
|
|
102
|
+
}
|
|
103
|
+
export declare class StripeApiError extends Error {
|
|
104
|
+
readonly status: number;
|
|
105
|
+
readonly type?: string | undefined;
|
|
106
|
+
readonly code?: string | undefined;
|
|
107
|
+
constructor(message: string, status: number, type?: string | undefined, code?: string | undefined);
|
|
108
|
+
}
|
|
109
|
+
/**
|
|
110
|
+
* Create the real Stripe client. `allowLive` defaults to false: a live key is
|
|
111
|
+
* refused unless the caller opts in deliberately (only the human-gated
|
|
112
|
+
* mesh-bill path ever does).
|
|
113
|
+
*/
|
|
114
|
+
export declare function createStripeClient(secretKey: string, options?: {
|
|
115
|
+
allowLive?: boolean;
|
|
116
|
+
fetch?: typeof fetch;
|
|
117
|
+
}): StripeClient;
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
import { type BillableEvent, type InvoiceOptions } from "./savings-ledger.js";
|
|
2
|
+
/**
|
|
3
|
+
* The LOCAL Stripe meter sink: a pure projection from ledger events to Stripe
|
|
4
|
+
* Billing Meters event rows, written to a local JSONL file. No network calls,
|
|
5
|
+
* no API keys, no Stripe account - this is the file a billing integration
|
|
6
|
+
* would transmit, produced where the customer can read it first.
|
|
7
|
+
*
|
|
8
|
+
* Honesty properties, inherited rather than re-promised:
|
|
9
|
+
* - The projection selects and bills events through the SAME shared pipeline
|
|
10
|
+
* as recomputeInvoice (selectBillableEvents + leverUnbilledReason): deduped
|
|
11
|
+
* by requestId, failed tasks voided in full, unmeasured levers never
|
|
12
|
+
* counted, lossy levers only with approved gate verdicts, negatives netted.
|
|
13
|
+
* - Idempotent by construction: a doubled spool deduplicates to the same
|
|
14
|
+
* events, the same hourly windows, the same identifiers and the same values,
|
|
15
|
+
* so re-projection emits ZERO duplicate meter events - the output file is
|
|
16
|
+
* byte-identical. The identifier doubles as the Stripe-side idempotency key.
|
|
17
|
+
* - The canonical billing artifact remains the invoice. The projection's total
|
|
18
|
+
* equals the invoice's net verified savings over the same options (same
|
|
19
|
+
* floats, grouped hourly instead of by lever), and `totalCents` is exposed
|
|
20
|
+
* so the reconciliation is a one-line check.
|
|
21
|
+
*/
|
|
22
|
+
export type StripeMeterEventRow = {
|
|
23
|
+
/** Stripe Billing Meter event name; one meter per deployment. */
|
|
24
|
+
event_name: string;
|
|
25
|
+
/**
|
|
26
|
+
* Deterministic idempotency identifier: sha256 of applicationId + window
|
|
27
|
+
* start. Stripe rejects duplicate identifiers within the dedupe horizon,
|
|
28
|
+
* which is exactly the re-transmission guard a replayed spool needs.
|
|
29
|
+
*/
|
|
30
|
+
identifier: string;
|
|
31
|
+
/** Hour-window start, ISO UTC. */
|
|
32
|
+
timestamp: string;
|
|
33
|
+
payload: {
|
|
34
|
+
/**
|
|
35
|
+
* Customer mapping for the Stripe meter. Defaults to the applicationId
|
|
36
|
+
* verbatim; a real integration passes customerIdOf to map onto cus_ ids.
|
|
37
|
+
*/
|
|
38
|
+
stripe_customer_id: string;
|
|
39
|
+
/** Net verified savings for the window, USD as a decimal string (6 dp). */
|
|
40
|
+
value: string;
|
|
41
|
+
};
|
|
42
|
+
};
|
|
43
|
+
export type StripeMeterProjectionOptions = Pick<InvoiceOptions, "period" | "gateVerdictOverrides" | "failedTaskIds"> & {
|
|
44
|
+
/** Meter event name. Default "mesh_net_verified_savings_usd". */
|
|
45
|
+
eventName?: string;
|
|
46
|
+
/** Map an applicationId to the Stripe customer id. Default: identity. */
|
|
47
|
+
customerIdOf?: (applicationId: string) => string;
|
|
48
|
+
};
|
|
49
|
+
export type StripeMeterProjection = {
|
|
50
|
+
rows: StripeMeterEventRow[];
|
|
51
|
+
/** Deduplicated events considered (inside the period, if one was given). */
|
|
52
|
+
eventsConsidered: number;
|
|
53
|
+
/** Events that contributed at least one billable lever to a row. */
|
|
54
|
+
eventsBilled: number;
|
|
55
|
+
duplicatesIgnored: number;
|
|
56
|
+
/** Events whose timestamp could not be bucketed into an hour window. */
|
|
57
|
+
eventsSkippedBadTimestamp: number;
|
|
58
|
+
/** Sum across rows, for reconciliation against the invoice. */
|
|
59
|
+
totalUsd: number;
|
|
60
|
+
totalCents: number;
|
|
61
|
+
};
|
|
62
|
+
/** Deterministic row identifier: hash(applicationId + window start). */
|
|
63
|
+
export declare function stripeMeterIdentifier(applicationId: string, windowStart: string): string;
|
|
64
|
+
/**
|
|
65
|
+
* Project ledger events onto hourly pre-aggregated Stripe meter rows. Pure:
|
|
66
|
+
* same events and options in, byte-identical rows out, however many times the
|
|
67
|
+
* spool was replayed or shuffled.
|
|
68
|
+
*/
|
|
69
|
+
export declare function projectLedgerEventsToStripeMeterRows(events: readonly BillableEvent[], options?: StripeMeterProjectionOptions): StripeMeterProjection;
|
|
70
|
+
/**
|
|
71
|
+
* Write the projection to a local JSONL file, one meter row per line. A full
|
|
72
|
+
* deterministic rewrite, never an append: re-projecting the same spool writes
|
|
73
|
+
* the identical bytes, which is what makes a doubled spool emit zero duplicate
|
|
74
|
+
* meter events. Local only - nothing here (or anywhere in this module) opens a
|
|
75
|
+
* network connection or reads a key.
|
|
76
|
+
*/
|
|
77
|
+
export declare function writeStripeMeterSink(path: string, rows: readonly StripeMeterEventRow[]): void;
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import { type TokenPrice } from "./cost.js";
|
|
2
|
+
import { type LeverRisk, type WorkloadProfile } from "./savings-model.js";
|
|
3
|
+
export type LeverCoverage = {
|
|
4
|
+
leverId: string;
|
|
5
|
+
description: string;
|
|
6
|
+
risk: LeverRisk;
|
|
7
|
+
/** The lever targets at least one segment this workload actually has. */
|
|
8
|
+
applicable: boolean;
|
|
9
|
+
/** Theo applies it to this workload today (it is in leversFor). */
|
|
10
|
+
applied: boolean;
|
|
11
|
+
/**
|
|
12
|
+
* Projected saving from this lever alone on this workload, in USD and as a
|
|
13
|
+
* share of the baseline. For an applied lever this is its marginal saving in
|
|
14
|
+
* Theo's real stack; for an unapplied one it is the standalone projection. Both
|
|
15
|
+
* are hypotheses from the lever's published evidence — never a realised saving.
|
|
16
|
+
*/
|
|
17
|
+
projectedSavingUsd: number;
|
|
18
|
+
projectedSavingPercent: number;
|
|
19
|
+
/** Why an applicable lever is not applied. Absent when applied, or not applicable. */
|
|
20
|
+
reason?: string;
|
|
21
|
+
};
|
|
22
|
+
export type CoverageReport = {
|
|
23
|
+
workload: string;
|
|
24
|
+
baselineCostUsd: number;
|
|
25
|
+
/** Theo's actual stacked projection on this workload (what leversFor delivers). */
|
|
26
|
+
realizedSavingUsd: number;
|
|
27
|
+
realizedSavingPercent: number;
|
|
28
|
+
/** The part of the realized saving that cannot change an answer — live immediately. */
|
|
29
|
+
realizedDeterministicPercent: number;
|
|
30
|
+
/** The part that needs a replay proof within the quality ceiling before it is enabled. */
|
|
31
|
+
realizedNeedsVerificationPercent: number;
|
|
32
|
+
/** Catalogue levers that can touch this workload (N). */
|
|
33
|
+
applicableLevers: number;
|
|
34
|
+
/** Of those, how many Theo applies (M). */
|
|
35
|
+
appliedLevers: number;
|
|
36
|
+
/** M / N as a percentage — the headline coverage figure. */
|
|
37
|
+
leverCoveragePercent: number;
|
|
38
|
+
/** Every catalogue lever, applied or not, sorted by projected headroom descending. */
|
|
39
|
+
levers: LeverCoverage[];
|
|
40
|
+
/** Applicable levers Theo does not apply, each with a reason. Sorted by headroom. */
|
|
41
|
+
gaps: LeverCoverage[];
|
|
42
|
+
};
|
|
43
|
+
/**
|
|
44
|
+
* Measure how much of the lever catalogue Theo reaches on one workload profile.
|
|
45
|
+
*
|
|
46
|
+
* Deterministic: the same profile, price and catalogue always produce the same
|
|
47
|
+
* report, so it is safe to diff across builds and to assert on in tests.
|
|
48
|
+
*/
|
|
49
|
+
export declare function coverageForProfile(profile: WorkloadProfile, price: TokenPrice): CoverageReport;
|
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
import { type TokenPrice } from "./cost.js";
|
|
2
|
+
/**
|
|
3
|
+
* Token reduction: spend fewer tokens on the SAME model, rather than moving work
|
|
4
|
+
* to a weaker one. Model substitution trades quality for cost and needs a quality
|
|
5
|
+
* gate to be safe. Most of the levers here do not: removing a duplicated context
|
|
6
|
+
* block, or letting a provider's prefix cache serve a prompt you already paid
|
|
7
|
+
* for, changes the bill and not the answer.
|
|
8
|
+
*
|
|
9
|
+
* The economics that make this the primary lever rather than a secondary one,
|
|
10
|
+
* using rates captured in model-prices.ts:
|
|
11
|
+
* - Output tokens cost 5x input (Claude Sonnet 5.5) to 8x (gpt-5), so trimming
|
|
12
|
+
* an over-long answer is worth several times trimming the prompt.
|
|
13
|
+
* - Cached input costs 1/20th of fresh input (Sonnet 5.5: $2.00 -> $0.10), so a
|
|
14
|
+
* stable prefix served from cache is close to free.
|
|
15
|
+
*
|
|
16
|
+
* Token counting here is an ESTIMATE used to decide what to cut and to project a
|
|
17
|
+
* saving. It is never the basis of a realised-saving claim: those come from the
|
|
18
|
+
* provider's own reported usage, priced through the catalogue. A deployment
|
|
19
|
+
* should pass the tokenizer matching its model via `countTokens`, because a
|
|
20
|
+
* tokenizer pinned inside MESH would drift from the provider's own counting.
|
|
21
|
+
*/
|
|
22
|
+
export type TokenCounter = (text: string) => number;
|
|
23
|
+
/**
|
|
24
|
+
* Tokenizer-free estimate. Byte-pair encoders average roughly 4 characters per
|
|
25
|
+
* token on English prose and nearer 3 on code, punctuation and JSON, so this
|
|
26
|
+
* counts word-like runs and separators separately instead of dividing the whole
|
|
27
|
+
* string by one constant. Expect roughly +/-15% against a real tokenizer; good
|
|
28
|
+
* enough to rank candidate reductions, not good enough to bill on.
|
|
29
|
+
*/
|
|
30
|
+
export declare const approximateTokenCount: TokenCounter;
|
|
31
|
+
export type ReductionRisk = "lossless" | "low" | "moderate";
|
|
32
|
+
export type ReductionOutcome = {
|
|
33
|
+
reducer: string;
|
|
34
|
+
version: string;
|
|
35
|
+
risk: ReductionRisk;
|
|
36
|
+
text: string;
|
|
37
|
+
tokensBefore: number;
|
|
38
|
+
tokensAfter: number;
|
|
39
|
+
tokensSaved: number;
|
|
40
|
+
/** What the reducer removed, for review before anything is enabled. */
|
|
41
|
+
notes: string[];
|
|
42
|
+
};
|
|
43
|
+
export type Reducer = {
|
|
44
|
+
id: string;
|
|
45
|
+
version: string;
|
|
46
|
+
risk: ReductionRisk;
|
|
47
|
+
reduce: (text: string) => {
|
|
48
|
+
text: string;
|
|
49
|
+
notes: string[];
|
|
50
|
+
};
|
|
51
|
+
};
|
|
52
|
+
/**
|
|
53
|
+
* Removes exact duplicate blocks. Retrieval pipelines routinely send the same
|
|
54
|
+
* passage two or three times (overlapping chunks, a document that matched several
|
|
55
|
+
* queries, a system prompt echoed into the first user turn). Dropping later exact
|
|
56
|
+
* copies is lossless: the model already has the text.
|
|
57
|
+
*
|
|
58
|
+
* Only blocks at or above `minimumBlockTokens` are considered, so ordinary
|
|
59
|
+
* repeated phrasing is left alone.
|
|
60
|
+
*
|
|
61
|
+
* Duplicates are caught at two granularities: whole blocks separated by a
|
|
62
|
+
* blank line (as before), and, inside a block that survives that check,
|
|
63
|
+
* individual lines separated by a single newline. A RAG prompt that joins
|
|
64
|
+
* several retrieved excerpts with `picks.join("\n")` never produces a
|
|
65
|
+
* duplicated top-level block — the whole joined block is unique per request
|
|
66
|
+
* because the question text differs — but an excerpt pulled twice is still an
|
|
67
|
+
* exact duplicate line inside it, and dropping it is exactly as lossless as
|
|
68
|
+
* dropping a duplicate paragraph.
|
|
69
|
+
*/
|
|
70
|
+
export declare function dedupeRepeatedBlocks(minimumBlockTokens?: number, countTokens?: TokenCounter): Reducer;
|
|
71
|
+
/**
|
|
72
|
+
* Collapses redundant whitespace outside fenced and inline code, where layout is
|
|
73
|
+
* meaningful. Individually small; free, and it compounds across every request.
|
|
74
|
+
*/
|
|
75
|
+
export declare function collapseWhitespace(): Reducer;
|
|
76
|
+
/**
|
|
77
|
+
* Minifies pretty-printed JSON inside fenced ```json blocks. Agent tool results
|
|
78
|
+
* are frequently indented JSON, and JSON whitespace carries no meaning the model
|
|
79
|
+
* depends on, so re-serializing compactly removes indentation while preserving
|
|
80
|
+
* every key and value. Only blocks that parse as JSON are touched; anything else
|
|
81
|
+
* is left byte-identical. Values are preserved; numeric *formatting* is
|
|
82
|
+
* normalized (e.g. 1.0 -> 1), which is why this is a reduction of the serialized
|
|
83
|
+
* form, not a byte-identity transform — it is applied where the JSON's values,
|
|
84
|
+
* not its layout, are what the model needs.
|
|
85
|
+
*/
|
|
86
|
+
export declare function minifyJsonBlocks(countTokens?: TokenCounter): Reducer;
|
|
87
|
+
/** Run reducers in order, reporting what each one saved. */
|
|
88
|
+
export declare function applyReducers(text: string, reducers: Reducer[], countTokens?: TokenCounter): {
|
|
89
|
+
text: string;
|
|
90
|
+
outcomes: ReductionOutcome[];
|
|
91
|
+
tokensBefore: number;
|
|
92
|
+
tokensAfter: number;
|
|
93
|
+
};
|
|
94
|
+
export type PrefixBreaker = {
|
|
95
|
+
/** What kind of per-request value is sitting inside the would-be stable prefix. */
|
|
96
|
+
kind: "timestamp" | "date" | "uuid" | "long-number" | "unknown";
|
|
97
|
+
example: string;
|
|
98
|
+
occurrences: number;
|
|
99
|
+
};
|
|
100
|
+
export type CachingProjection = {
|
|
101
|
+
status: "priced";
|
|
102
|
+
baselineCostUsd: number;
|
|
103
|
+
cachedCostUsd: number;
|
|
104
|
+
savingUsd: number;
|
|
105
|
+
savingPercent: number;
|
|
106
|
+
recoverableSavingUsd: number;
|
|
107
|
+
} | {
|
|
108
|
+
status: "unpriced";
|
|
109
|
+
reason: string;
|
|
110
|
+
};
|
|
111
|
+
export type CachingAnalysis = {
|
|
112
|
+
requests: number;
|
|
113
|
+
meanInputTokens: number;
|
|
114
|
+
/** Tokens identical across every sampled request, from the start of the prompt. */
|
|
115
|
+
sharedPrefixTokens: number;
|
|
116
|
+
/** Share of a request's input that the provider could serve from cache today. */
|
|
117
|
+
cacheablePrefixShare: number;
|
|
118
|
+
/**
|
|
119
|
+
* Shared prefix that would exist if the per-request values listed in
|
|
120
|
+
* `prefixBreakers` were moved out of the prefix. The gap between this and
|
|
121
|
+
* `sharedPrefixTokens` is the cost of a timestamp in a system prompt.
|
|
122
|
+
*/
|
|
123
|
+
recoverablePrefixTokens: number;
|
|
124
|
+
prefixBreakers: PrefixBreaker[];
|
|
125
|
+
projection: CachingProjection;
|
|
126
|
+
};
|
|
127
|
+
export declare function commonPrefixLength(left: string, right: string): number;
|
|
128
|
+
/**
|
|
129
|
+
* Removes a repeated LEADING block from texts after the first, when that
|
|
130
|
+
* block is an exact match for the start of the first text in the group.
|
|
131
|
+
*
|
|
132
|
+
* This is the shape a continuous-learning / continuous-memory agent
|
|
133
|
+
* produces: the application glues the same memory or persistent-instruction
|
|
134
|
+
* block to the front of every turn, with only a short turn-specific
|
|
135
|
+
* remainder varying underneath it. `dedupeRepeatedBlocks` never catches
|
|
136
|
+
* this, because it only ever sees one text at a time and the memory block
|
|
137
|
+
* is not a standalone paragraph inside any single text - it is the shared
|
|
138
|
+
* PREFIX of several texts that each continue differently.
|
|
139
|
+
*
|
|
140
|
+
* LOSSY, not lossless, unlike `dedupeRepeatedBlocks`: a same-text duplicate
|
|
141
|
+
* sits right next to its twin, so the model reads both in the same breath.
|
|
142
|
+
* The duplicate removed here can be many turns upstream of the current one,
|
|
143
|
+
* which is a real behaviour change - a model that attends less to context
|
|
144
|
+
* far back in a long history may act differently with the block restated
|
|
145
|
+
* fresh every turn versus present once near the start. Callers must run
|
|
146
|
+
* this behind a replay-gate pass on their own traffic before billing it;
|
|
147
|
+
* it is never enabled by default.
|
|
148
|
+
*
|
|
149
|
+
* The cut point is always snapped to the last newline at or before the raw
|
|
150
|
+
* common-prefix length (never cut THROUGH a line), unless the match is a
|
|
151
|
+
* complete containment of one text inside the other, which needs no
|
|
152
|
+
* snapping because there is no partially-matched line to protect. This
|
|
153
|
+
* means a false positive - two texts that happen to start with the same
|
|
154
|
+
* few words before diverging mid-line, e.g. two turns both opening "Turn "
|
|
155
|
+
* - can only ever leave that differing line untouched, never truncate into it.
|
|
156
|
+
*/
|
|
157
|
+
export declare function dedupeRepeatedLeadingBlock(texts: readonly string[], minimumBlockTokens?: number, countTokens?: TokenCounter): {
|
|
158
|
+
texts: string[];
|
|
159
|
+
notes: string[];
|
|
160
|
+
};
|
|
161
|
+
/**
|
|
162
|
+
* How much of a workload's prompt a provider's prefix cache could serve, and what
|
|
163
|
+
* is stopping it.
|
|
164
|
+
*
|
|
165
|
+
* Providers cache on an exact prefix match, so a single value that changes per
|
|
166
|
+
* request invalidates everything after it. A current-date line at the top of a
|
|
167
|
+
* system prompt can therefore cost the entire prompt's cache discount, which is
|
|
168
|
+
* the difference between paying full input rate and one twentieth of it. That
|
|
169
|
+
* failure is invisible in a cost dashboard: spend simply stays high.
|
|
170
|
+
*
|
|
171
|
+
* `requests` should be a representative sample of real prompts for one workload.
|
|
172
|
+
*/
|
|
173
|
+
export declare function analysePromptCaching(requests: string[], options?: {
|
|
174
|
+
price?: TokenPrice;
|
|
175
|
+
countTokens?: TokenCounter;
|
|
176
|
+
/** Minimum prefix a provider will cache at all; OpenAI's floor is 1024 tokens. */
|
|
177
|
+
minimumCacheableTokens?: number;
|
|
178
|
+
}): CachingAnalysis;
|
|
179
|
+
export type OutputCapAdvice = {
|
|
180
|
+
observations: number;
|
|
181
|
+
/** Cap that would have truncated none of the observed responses. */
|
|
182
|
+
maxObserved: number;
|
|
183
|
+
recommendedCap: number;
|
|
184
|
+
/** Share of observed responses the recommended cap would have truncated. */
|
|
185
|
+
truncationRate: number;
|
|
186
|
+
meanOutputTokens: number;
|
|
187
|
+
/**
|
|
188
|
+
* Saving only materialises on responses that would have run past the cap, so
|
|
189
|
+
* this is deliberately conservative: it counts the tokens above the cap and
|
|
190
|
+
* nothing else.
|
|
191
|
+
*/
|
|
192
|
+
projectedTokensSaved: number;
|
|
193
|
+
projectedSavingUsd?: number;
|
|
194
|
+
};
|
|
195
|
+
/**
|
|
196
|
+
* Recommend `max_output_tokens` from observed response lengths.
|
|
197
|
+
*
|
|
198
|
+
* Output is the expensive half of the bill (5x input on Sonnet 5.5, 8x on gpt-5),
|
|
199
|
+
* and an uncapped request lets a model ramble at that rate. A cap set at a high
|
|
200
|
+
* quantile of what a workload actually produces removes the tail without touching
|
|
201
|
+
* the responses that were already the right length.
|
|
202
|
+
*
|
|
203
|
+
* This caps length; it does not make answers shorter at equal quality. Any
|
|
204
|
+
* response that would have exceeded the cap gets truncated, so `truncationRate`
|
|
205
|
+
* is the number to judge it on, and a cap belongs behind a replay check before
|
|
206
|
+
* rollout.
|
|
207
|
+
*/
|
|
208
|
+
export declare function recommendOutputCap(observedOutputTokens: number[], options?: {
|
|
209
|
+
quantile?: number;
|
|
210
|
+
price?: TokenPrice;
|
|
211
|
+
headroom?: number;
|
|
212
|
+
}): OutputCapAdvice;
|
|
213
|
+
export type ReductionSaving = {
|
|
214
|
+
inputTokensSaved: number;
|
|
215
|
+
outputTokensSaved: number;
|
|
216
|
+
savingUsd?: number;
|
|
217
|
+
};
|
|
218
|
+
/** Price a projected reduction. Returns tokens only when no price is supplied. */
|
|
219
|
+
export declare function priceReduction(inputTokensSaved: number, outputTokensSaved: number, price?: TokenPrice): ReductionSaving;
|