@drsamonline/catalog 0.12.10 → 0.12.12

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 (2) hide show
  1. package/package.json +1 -1
  2. package/src/index.js +86 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@drsamonline/catalog",
3
- "version": "0.12.10",
3
+ "version": "0.12.12",
4
4
  "description": "Provider catalog: schema, dedupe, ToS policy, scoring.",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/src/index.js CHANGED
@@ -73,6 +73,10 @@ export function normalizeEntry(raw) {
73
73
  capabilities: (raw.capabilities ?? ['chat']).filter((c) => CAPABILITIES.includes(c)),
74
74
  context_window: raw.context_window ?? null,
75
75
  quota: raw.quota ?? null,
76
+ // a published recurring monthly budget, in tokens, and where the number came
77
+ // from. Absent is absent: freeBudget() never invents one.
78
+ monthly_tokens: Number.isFinite(Number(raw.monthly_tokens)) && Number(raw.monthly_tokens) > 0 ? Number(raw.monthly_tokens) : null,
79
+ budget_source: raw.budget_source ?? null,
76
80
  needs_probe: raw.base_url ? Boolean(raw.needs_probe) : true,
77
81
  verified_at: raw.verified_at ?? null,
78
82
  notes: raw.notes ?? null,
@@ -203,3 +207,85 @@ export function summarise(entries, probes = {}) {
203
207
  rows,
204
208
  };
205
209
  }
210
+
211
+ /**
212
+ * Monthly free headroom, computed honestly.
213
+ *
214
+ * The number everyone wants is "how many free tokens per month do I have". The
215
+ * number that can be defended is smaller: only pools that publish a recurring
216
+ * budget, counted once per pool (two names for one upstream are one pool), and
217
+ * kept in two columns — what a probe reached, and what is only a claim.
218
+ *
219
+ * Unverified entries are never summed into the verified total. A headline that
220
+ * mixes them is a marketing number; this one is a measurement, and it says how
221
+ * much of it is missing.
222
+ *
223
+ * @param {Array<any>} entries catalogue entries, each optionally carrying
224
+ * `monthly_tokens` (a published recurring budget) and `pool_key`
225
+ * @param {Record<string, any>} [probes] keyed by pool_key, as `sui probe --write` records
226
+ * @returns {{verifiedTokens: number, unverifiedTokens: number, verified: Array<any>, unverified: Array<any>, withoutBudget: number, pools: number, note: string}}
227
+ */
228
+ export function freeBudget(entries, probes = {}) {
229
+ /** @type {Map<string, any>} */
230
+ const pools = new Map();
231
+
232
+ for (const entry of entries) {
233
+ const key = entry.pool_key ?? poolKey(entry);
234
+ const existing = pools.get(key);
235
+ const tokens = Number(entry.monthly_tokens ?? 0);
236
+ // one pool, one budget: a second name for the same upstream does not double it
237
+ if (existing) {
238
+ existing.names.push(entry.provider);
239
+ if (tokens > existing.tokens) existing.tokens = tokens;
240
+ continue;
241
+ }
242
+ pools.set(key, {
243
+ pool_key: key,
244
+ names: [entry.provider],
245
+ tokens: Number.isFinite(tokens) ? tokens : 0,
246
+ tos: entry.tos ?? 'review',
247
+ budget_source: entry.budget_source ?? null,
248
+ });
249
+ }
250
+
251
+ const verified = [];
252
+ const unverified = [];
253
+ let withoutBudget = 0;
254
+
255
+ for (const pool of pools.values()) {
256
+ if (!pool.tokens) {
257
+ withoutBudget += 1;
258
+ continue;
259
+ }
260
+ const probe = probes[pool.pool_key];
261
+ if (probe?.ok === true) verified.push(pool);
262
+ else unverified.push(pool);
263
+ }
264
+
265
+ const sum = (rows) => rows.reduce((a, r) => a + r.tokens, 0);
266
+ const verifiedTokens = sum(verified);
267
+ const unverifiedTokens = sum(unverified);
268
+
269
+ const note = verifiedTokens
270
+ ? `${verified.length} pool(s) with a published budget answered a probe.`
271
+ : 'No pool with a published budget has answered a probe here yet, so the verified total is zero. That is a measurement, not a shortfall: run `sui probe --write` on a networked machine.';
272
+
273
+ return {
274
+ verifiedTokens,
275
+ unverifiedTokens,
276
+ verified,
277
+ unverified,
278
+ withoutBudget,
279
+ pools: pools.size,
280
+ note,
281
+ };
282
+ }
283
+
284
+ /** 1_620_000 → "1.62M". A token count is read, not calculated. */
285
+ export function formatTokens(n) {
286
+ const num = Number(n ?? 0);
287
+ if (num >= 1e9) return `${(num / 1e9).toFixed(2)}B`;
288
+ if (num >= 1e6) return `${(num / 1e6).toFixed(2)}M`;
289
+ if (num >= 1e3) return `${(num / 1e3).toFixed(1)}k`;
290
+ return String(num);
291
+ }