risicare 0.9.0 → 0.9.2

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 (93) hide show
  1. package/CHANGELOG.md +1236 -0
  2. package/README.md +18 -0
  3. package/dist/frameworks/instructor.cjs +163 -6
  4. package/dist/frameworks/instructor.cjs.map +1 -1
  5. package/dist/frameworks/instructor.js +163 -6
  6. package/dist/frameworks/instructor.js.map +1 -1
  7. package/dist/frameworks/langchain.cjs +163 -6
  8. package/dist/frameworks/langchain.cjs.map +1 -1
  9. package/dist/frameworks/langchain.js +163 -6
  10. package/dist/frameworks/langchain.js.map +1 -1
  11. package/dist/frameworks/langgraph.cjs +163 -6
  12. package/dist/frameworks/langgraph.cjs.map +1 -1
  13. package/dist/frameworks/langgraph.js +163 -6
  14. package/dist/frameworks/langgraph.js.map +1 -1
  15. package/dist/frameworks/llamaindex.cjs +163 -6
  16. package/dist/frameworks/llamaindex.cjs.map +1 -1
  17. package/dist/frameworks/llamaindex.js +163 -6
  18. package/dist/frameworks/llamaindex.js.map +1 -1
  19. package/dist/index.cjs +274 -18
  20. package/dist/index.cjs.map +1 -1
  21. package/dist/index.d.cts +7 -1
  22. package/dist/index.d.ts +7 -1
  23. package/dist/index.js +274 -18
  24. package/dist/index.js.map +1 -1
  25. package/dist/providers/anthropic/index.cjs +168 -7
  26. package/dist/providers/anthropic/index.cjs.map +1 -1
  27. package/dist/providers/anthropic/index.d.cts +3 -0
  28. package/dist/providers/anthropic/index.d.ts +3 -0
  29. package/dist/providers/anthropic/index.js +168 -7
  30. package/dist/providers/anthropic/index.js.map +1 -1
  31. package/dist/providers/bedrock/index.cjs +168 -7
  32. package/dist/providers/bedrock/index.cjs.map +1 -1
  33. package/dist/providers/bedrock/index.d.cts +3 -0
  34. package/dist/providers/bedrock/index.d.ts +3 -0
  35. package/dist/providers/bedrock/index.js +168 -7
  36. package/dist/providers/bedrock/index.js.map +1 -1
  37. package/dist/providers/cerebras/index.cjs +168 -7
  38. package/dist/providers/cerebras/index.cjs.map +1 -1
  39. package/dist/providers/cerebras/index.d.cts +3 -0
  40. package/dist/providers/cerebras/index.d.ts +3 -0
  41. package/dist/providers/cerebras/index.js +168 -7
  42. package/dist/providers/cerebras/index.js.map +1 -1
  43. package/dist/providers/cohere/index.cjs +168 -7
  44. package/dist/providers/cohere/index.cjs.map +1 -1
  45. package/dist/providers/cohere/index.d.cts +3 -0
  46. package/dist/providers/cohere/index.d.ts +3 -0
  47. package/dist/providers/cohere/index.js +168 -7
  48. package/dist/providers/cohere/index.js.map +1 -1
  49. package/dist/providers/google/index.cjs +168 -7
  50. package/dist/providers/google/index.cjs.map +1 -1
  51. package/dist/providers/google/index.d.cts +3 -0
  52. package/dist/providers/google/index.d.ts +3 -0
  53. package/dist/providers/google/index.js +168 -7
  54. package/dist/providers/google/index.js.map +1 -1
  55. package/dist/providers/groq/index.cjs +168 -7
  56. package/dist/providers/groq/index.cjs.map +1 -1
  57. package/dist/providers/groq/index.d.cts +3 -0
  58. package/dist/providers/groq/index.d.ts +3 -0
  59. package/dist/providers/groq/index.js +168 -7
  60. package/dist/providers/groq/index.js.map +1 -1
  61. package/dist/providers/huggingface/index.cjs +166 -6
  62. package/dist/providers/huggingface/index.cjs.map +1 -1
  63. package/dist/providers/huggingface/index.js +166 -6
  64. package/dist/providers/huggingface/index.js.map +1 -1
  65. package/dist/providers/mistral/index.cjs +168 -7
  66. package/dist/providers/mistral/index.cjs.map +1 -1
  67. package/dist/providers/mistral/index.d.cts +3 -0
  68. package/dist/providers/mistral/index.d.ts +3 -0
  69. package/dist/providers/mistral/index.js +168 -7
  70. package/dist/providers/mistral/index.js.map +1 -1
  71. package/dist/providers/ollama/index.cjs +168 -7
  72. package/dist/providers/ollama/index.cjs.map +1 -1
  73. package/dist/providers/ollama/index.d.cts +3 -0
  74. package/dist/providers/ollama/index.d.ts +3 -0
  75. package/dist/providers/ollama/index.js +168 -7
  76. package/dist/providers/ollama/index.js.map +1 -1
  77. package/dist/providers/openai/index.cjs +168 -7
  78. package/dist/providers/openai/index.cjs.map +1 -1
  79. package/dist/providers/openai/index.d.cts +3 -0
  80. package/dist/providers/openai/index.d.ts +3 -0
  81. package/dist/providers/openai/index.js +168 -7
  82. package/dist/providers/openai/index.js.map +1 -1
  83. package/dist/providers/together/index.cjs +168 -7
  84. package/dist/providers/together/index.cjs.map +1 -1
  85. package/dist/providers/together/index.d.cts +3 -0
  86. package/dist/providers/together/index.d.ts +3 -0
  87. package/dist/providers/together/index.js +168 -7
  88. package/dist/providers/together/index.js.map +1 -1
  89. package/dist/providers/vercel-ai/index.cjs +163 -6
  90. package/dist/providers/vercel-ai/index.cjs.map +1 -1
  91. package/dist/providers/vercel-ai/index.js +163 -6
  92. package/dist/providers/vercel-ai/index.js.map +1 -1
  93. package/package.json +3 -2
@@ -66,6 +66,10 @@ function warn(msg) {
66
66
  process.stderr.write(`[risicare] WARNING: ${msg}
67
67
  `);
68
68
  }
69
+ function info(msg) {
70
+ process.stderr.write(`[risicare] INFO: ${msg}
71
+ `);
72
+ }
69
73
 
70
74
  // src/utils/text.ts
71
75
  function cutCodePoints(text, max) {
@@ -278,7 +282,111 @@ function getContext() {
278
282
  }
279
283
 
280
284
  // src/version.ts
281
- var SDK_VERSION = "0.9.0";
285
+ var SDK_VERSION = "0.9.2";
286
+
287
+ // src/exporters/quota.ts
288
+ var QUOTA_REASON = "monthly_quota_exceeded";
289
+ var QUOTA_HEADER = "X-Risicare-Quota";
290
+ var QUOTA_HEADER_VALUE = "exceeded";
291
+ var DEFAULT_RETRY_AFTER_S = 300;
292
+ var MIN_RETRY_AFTER_S = 1;
293
+ var MAX_RETRY_AFTER_S = 3600;
294
+ var QUOTA_WARN_WINDOW_MS = 36e5;
295
+ var MAX_RESETS_AT_CHARS = 40;
296
+ function asPositiveCount(v) {
297
+ if (typeof v === "number") return Number.isFinite(v) && v > 0;
298
+ if (typeof v === "string" && /^[0-9]+$/.test(v)) return Number(v) > 0;
299
+ return false;
300
+ }
301
+ function boundedRetryAfter(value) {
302
+ let n;
303
+ if (typeof value === "number") n = value;
304
+ else if (typeof value === "string" && value.trim() !== "") n = Number(value);
305
+ else return DEFAULT_RETRY_AFTER_S;
306
+ if (!Number.isFinite(n)) return DEFAULT_RETRY_AFTER_S;
307
+ return Math.min(Math.max(n, MIN_RETRY_AFTER_S), MAX_RETRY_AFTER_S);
308
+ }
309
+ function boundedResetsAt(value) {
310
+ if (typeof value !== "string" || value.length === 0) return null;
311
+ const cut = value.slice(0, MAX_RESETS_AT_CHARS);
312
+ return /^[ -~]*$/.test(cut) ? cut : null;
313
+ }
314
+ function headerSaysExceeded(headers) {
315
+ try {
316
+ const value = headers?.get?.(QUOTA_HEADER);
317
+ return typeof value === "string" && value.trim().toLowerCase() === QUOTA_HEADER_VALUE;
318
+ } catch {
319
+ return false;
320
+ }
321
+ }
322
+ function parseJsonDiscard(payload, headers) {
323
+ const body = payload !== null && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
324
+ const stored = (asPositiveCount(body.accepted) || asPositiveCount(body.spansAccepted)) === true;
325
+ if (body.reason === QUOTA_REASON || headerSaysExceeded(headers) && !stored) {
326
+ return {
327
+ retryAfterS: boundedRetryAfter(body.retryAfterSeconds),
328
+ resetsAt: boundedResetsAt(body.resetsAt)
329
+ };
330
+ }
331
+ return null;
332
+ }
333
+ var EPISODE_END_ACCEPTS = 3;
334
+ var QuotaPause = class {
335
+ constructor(now = () => performance.now()) {
336
+ this.now = now;
337
+ }
338
+ _until = -Infinity;
339
+ _inEpisode = false;
340
+ _accepts = 0;
341
+ _lastWarn = -Infinity;
342
+ _lastInfo = -Infinity;
343
+ /**
344
+ * Spans dropped since the last WARNING: the full queue's (`addDrops`) and the batches that a
345
+ * probe lost while the WARNING was held back. The WARNING carries the number.
346
+ */
347
+ _drops = 0;
348
+ addDrops(count) {
349
+ this._drops += count;
350
+ }
351
+ paused() {
352
+ return this.now() < this._until;
353
+ }
354
+ remainingS() {
355
+ return Math.max(0, (this._until - this.now()) / 1e3);
356
+ }
357
+ enter(discard, where, dropped) {
358
+ const t = this.now();
359
+ this._until = t + discard.retryAfterS * 1e3;
360
+ this._inEpisode = true;
361
+ this._accepts = 0;
362
+ if (t - this._lastWarn >= QUOTA_WARN_WINDOW_MS) {
363
+ this._lastWarn = t;
364
+ const since = this._drops;
365
+ this._drops = 0;
366
+ warn(
367
+ `Risicare: the monthly event quota is used up (monthly_quota_exceeded). ${where} discarded ${dropped} span(s) and will discard new ones until the quota resets (resetsAt=${discard.resetsAt ?? "unknown"}) or the plan changes. The SDK pauses export and sends one batch again in ${Math.round(discard.retryAfterS)} s. Spans that end in the meantime wait in the queue. When it is full the oldest spans are dropped (the most recent are kept) and counted as quota_exceeded in droppedSpansByReason; a batch that is discarded again is dropped and counted the same way. This is not an error and the SDK does not retry the batch. At most one such WARNING an hour.` + (since > 0 ? ` Spans dropped for the quota since the last WARNING: ${since}.` : "")
368
+ );
369
+ } else {
370
+ this._drops += dropped;
371
+ debug(`Quota discard again: ${dropped} span(s); paused for ${Math.round(discard.retryAfterS)} s`);
372
+ }
373
+ }
374
+ accepted(where) {
375
+ if (!this._inEpisode) return;
376
+ this._accepts++;
377
+ if (this._accepts < EPISODE_END_ACCEPTS) return;
378
+ this._inEpisode = false;
379
+ this._accepts = 0;
380
+ this._until = -Infinity;
381
+ const t = this.now();
382
+ if (t - this._lastInfo >= QUOTA_WARN_WINDOW_MS) {
383
+ this._lastInfo = t;
384
+ info(`Risicare: ${where} accepts spans again; the export pause for the quota has ended.`);
385
+ } else {
386
+ debug("Quota pause ended (INFO already written this hour)");
387
+ }
388
+ }
389
+ };
282
390
 
283
391
  // src/exporters/http.ts
284
392
  var CAPACITY_REFUSAL_STATUSES = /* @__PURE__ */ new Set([429, 503]);
@@ -319,8 +427,23 @@ var HttpExporter = class {
319
427
  _calls = /* @__PURE__ */ new Map();
320
428
  /** The ack of each finished call, by its batch. Read once by `takeAck(spans)`. */
321
429
  _acks = /* @__PURE__ */ new WeakMap();
430
+ /** The requests that each finished call sent, by its batch. Read once by `takeAttempts(spans)`. */
431
+ _requests = /* @__PURE__ */ new WeakMap();
432
+ /** The batch processor dropped span(s) from a full queue in the quota pause (S-1). */
433
+ noteQuotaDrop(count = 1) {
434
+ this._quota.addDrops(count);
435
+ }
436
+ /** True while the exporter is paused for the monthly event quota (S-1). */
437
+ quotaPaused() {
438
+ return this._quota.paused();
439
+ }
322
440
  /** The spans of each finished call that could not be serialized, by its batch. */
323
441
  _unserializable = /* @__PURE__ */ new WeakMap();
442
+ /**
443
+ * S-1: the paused state after a monthly-quota discard (see `quota.ts`). A discard is not a
444
+ * failure: it does not touch the circuit breaker.
445
+ */
446
+ _quota = new QuotaPause();
324
447
  _circuitOpenUntil = 0;
325
448
  _circuitBreakerThreshold = 5;
326
449
  _circuitBreakerCooldownMs = 6e4;
@@ -357,6 +480,18 @@ var HttpExporter = class {
357
480
  get attemptsPerExport() {
358
481
  return this._maxRetries;
359
482
  }
483
+ /**
484
+ * Returns the number of HTTP requests that the `export()` call for `spans` sent, and clears
485
+ * it. This is the number that was sent, not the most that the call may send
486
+ * (`attemptsPerExport`): a 401 or 403 stops the loop after one request, and an open circuit
487
+ * breaker sends none. Returns `null` when no call is on record for `spans`. The answer is
488
+ * kept per batch, as `takeAck` keeps the ack.
489
+ */
490
+ takeAttempts(spans) {
491
+ const n = this._requests.get(spans) ?? null;
492
+ this._requests.delete(spans);
493
+ return n;
494
+ }
360
495
  /**
361
496
  * Returns the counts of the ack that the `export()` call for `spans` received, and clears
362
497
  * them. The answer is kept per batch, not on the instance: two processors that share this
@@ -401,17 +536,26 @@ var HttpExporter = class {
401
536
  misroute: null,
402
537
  noRetry: false,
403
538
  status: null,
404
- error: null
539
+ error: null,
540
+ attempts: 0
405
541
  };
406
542
  this._calls.set(spans, call);
407
543
  try {
408
544
  return await this._export(spans, call);
409
545
  } finally {
410
546
  this._calls.delete(spans);
547
+ this._requests.set(spans, this._endpointHasCredentials ? 0 : call.attempts);
411
548
  }
412
549
  }
413
550
  async _export(spans, call) {
414
551
  const cancelled = call.cancel.signal;
552
+ if (this._quota.paused()) {
553
+ debug(
554
+ `Export skipped: monthly quota pause, ${Math.round(this._quota.remainingS())} s left; ${spans.length} span(s) dropped`
555
+ );
556
+ this._acks.set(spans, { accepted: 0, rejected: 0, quotaDropped: spans.length });
557
+ return "success" /* SUCCESS */;
558
+ }
415
559
  const parts = [];
416
560
  const bad = [];
417
561
  let errorClass = "";
@@ -440,14 +584,13 @@ var HttpExporter = class {
440
584
  isHalfOpen = true;
441
585
  }
442
586
  const maxAttempts = isHalfOpen ? 1 : this._maxRetries;
443
- let attempts = 0;
444
587
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
445
588
  call.refusalAfterMs = null;
446
589
  call.misroute = null;
447
590
  call.noRetry = false;
448
591
  call.status = null;
449
592
  call.error = null;
450
- attempts++;
593
+ call.attempts++;
451
594
  const result = await this._sendRequest(payload, parts.length, call, spans);
452
595
  if (cancelled.aborted) {
453
596
  this._acks.delete(spans);
@@ -469,7 +612,7 @@ var HttpExporter = class {
469
612
  }
470
613
  if (call.refusalAfterMs !== null) {
471
614
  warn(
472
- `Risicare: the ingest endpoint refused this batch for capacity (HTTP 429/503) after ${attempts} attempt(s). This is a healthy server shedding load, not an outage. This export of the batch failed; the circuit breaker does not count it. Reduce batch size or export rate if it persists.`
615
+ `Risicare: the ingest endpoint refused this batch for capacity (HTTP 429/503) after ${call.attempts} attempt(s). This is a healthy server shedding load, not an outage. This export of the batch failed; the circuit breaker does not count it. Reduce batch size or export rate if it persists.`
473
616
  );
474
617
  return "failure" /* FAILURE */;
475
618
  }
@@ -620,6 +763,11 @@ var HttpExporter = class {
620
763
  `HTTP ${response.status} and a body that is not a Risicare ack (content-type: ${response.headers?.get?.("Content-Type") || "none"})`
621
764
  );
622
765
  }
766
+ if (ack.quota !== void 0) {
767
+ this._quota.enter(ack.quota, `The ingest endpoint ${this._safeEndpoint}`, spansSent);
768
+ } else if (ack.result === "success" /* SUCCESS */) {
769
+ this._quota.accepted(`the ingest endpoint ${this._safeEndpoint}`);
770
+ }
623
771
  if (ack.result === "success" /* SUCCESS */) this._acks.set(spans, ack.counts);
624
772
  if (ack.final) call.noRetry = true;
625
773
  return ack.result;
@@ -686,7 +834,16 @@ async function checkAck(response, spansSent, scrub) {
686
834
  try {
687
835
  payload = await response.json();
688
836
  } catch {
689
- return null;
837
+ payload = void 0;
838
+ }
839
+ const discard = parseJsonDiscard(payload, response.headers);
840
+ if (discard !== null) {
841
+ return {
842
+ result: "success" /* SUCCESS */,
843
+ counts: { accepted: 0, rejected: 0, quotaDropped: spansSent },
844
+ final: false,
845
+ quota: discard
846
+ };
690
847
  }
691
848
  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
692
849
  return null;
@@ -1210,9 +1367,11 @@ function createSendProxy(originalSend) {
1210
1367
  );
1211
1368
  };
1212
1369
  }
1370
+ var PATCHED = /* @__PURE__ */ new WeakSet();
1213
1371
  function patchBedrock(client) {
1214
1372
  assertClient("patchBedrock", client);
1215
- return new Proxy(client, {
1373
+ if (PATCHED.has(client)) return client;
1374
+ const proxy = new Proxy(client, {
1216
1375
  get(target, prop, receiver) {
1217
1376
  const value = Reflect.get(target, prop, receiver);
1218
1377
  if (prop === "send" && typeof value === "function") {
@@ -1221,6 +1380,8 @@ function patchBedrock(client) {
1221
1380
  return value;
1222
1381
  }
1223
1382
  });
1383
+ PATCHED.add(proxy);
1384
+ return proxy;
1224
1385
  }
1225
1386
  // Annotate the CommonJS export names for ESM import in node:
1226
1387
  0 && (module.exports = {