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
@@ -65,6 +65,10 @@ function warn(msg) {
65
65
  process.stderr.write(`[risicare] WARNING: ${msg}
66
66
  `);
67
67
  }
68
+ function info(msg) {
69
+ process.stderr.write(`[risicare] INFO: ${msg}
70
+ `);
71
+ }
68
72
 
69
73
  // src/utils/text.ts
70
74
  function cutCodePoints(text, max) {
@@ -282,7 +286,111 @@ function runWithContext(overrides, fn) {
282
286
  }
283
287
 
284
288
  // src/version.ts
285
- var SDK_VERSION = "0.9.0";
289
+ var SDK_VERSION = "0.9.2";
290
+
291
+ // src/exporters/quota.ts
292
+ var QUOTA_REASON = "monthly_quota_exceeded";
293
+ var QUOTA_HEADER = "X-Risicare-Quota";
294
+ var QUOTA_HEADER_VALUE = "exceeded";
295
+ var DEFAULT_RETRY_AFTER_S = 300;
296
+ var MIN_RETRY_AFTER_S = 1;
297
+ var MAX_RETRY_AFTER_S = 3600;
298
+ var QUOTA_WARN_WINDOW_MS = 36e5;
299
+ var MAX_RESETS_AT_CHARS = 40;
300
+ function asPositiveCount(v) {
301
+ if (typeof v === "number") return Number.isFinite(v) && v > 0;
302
+ if (typeof v === "string" && /^[0-9]+$/.test(v)) return Number(v) > 0;
303
+ return false;
304
+ }
305
+ function boundedRetryAfter(value) {
306
+ let n;
307
+ if (typeof value === "number") n = value;
308
+ else if (typeof value === "string" && value.trim() !== "") n = Number(value);
309
+ else return DEFAULT_RETRY_AFTER_S;
310
+ if (!Number.isFinite(n)) return DEFAULT_RETRY_AFTER_S;
311
+ return Math.min(Math.max(n, MIN_RETRY_AFTER_S), MAX_RETRY_AFTER_S);
312
+ }
313
+ function boundedResetsAt(value) {
314
+ if (typeof value !== "string" || value.length === 0) return null;
315
+ const cut = value.slice(0, MAX_RESETS_AT_CHARS);
316
+ return /^[ -~]*$/.test(cut) ? cut : null;
317
+ }
318
+ function headerSaysExceeded(headers) {
319
+ try {
320
+ const value = headers?.get?.(QUOTA_HEADER);
321
+ return typeof value === "string" && value.trim().toLowerCase() === QUOTA_HEADER_VALUE;
322
+ } catch {
323
+ return false;
324
+ }
325
+ }
326
+ function parseJsonDiscard(payload, headers) {
327
+ const body = payload !== null && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
328
+ const stored = (asPositiveCount(body.accepted) || asPositiveCount(body.spansAccepted)) === true;
329
+ if (body.reason === QUOTA_REASON || headerSaysExceeded(headers) && !stored) {
330
+ return {
331
+ retryAfterS: boundedRetryAfter(body.retryAfterSeconds),
332
+ resetsAt: boundedResetsAt(body.resetsAt)
333
+ };
334
+ }
335
+ return null;
336
+ }
337
+ var EPISODE_END_ACCEPTS = 3;
338
+ var QuotaPause = class {
339
+ constructor(now = () => performance.now()) {
340
+ this.now = now;
341
+ }
342
+ _until = -Infinity;
343
+ _inEpisode = false;
344
+ _accepts = 0;
345
+ _lastWarn = -Infinity;
346
+ _lastInfo = -Infinity;
347
+ /**
348
+ * Spans dropped since the last WARNING: the full queue's (`addDrops`) and the batches that a
349
+ * probe lost while the WARNING was held back. The WARNING carries the number.
350
+ */
351
+ _drops = 0;
352
+ addDrops(count) {
353
+ this._drops += count;
354
+ }
355
+ paused() {
356
+ return this.now() < this._until;
357
+ }
358
+ remainingS() {
359
+ return Math.max(0, (this._until - this.now()) / 1e3);
360
+ }
361
+ enter(discard, where, dropped) {
362
+ const t = this.now();
363
+ this._until = t + discard.retryAfterS * 1e3;
364
+ this._inEpisode = true;
365
+ this._accepts = 0;
366
+ if (t - this._lastWarn >= QUOTA_WARN_WINDOW_MS) {
367
+ this._lastWarn = t;
368
+ const since = this._drops;
369
+ this._drops = 0;
370
+ warn(
371
+ `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}.` : "")
372
+ );
373
+ } else {
374
+ this._drops += dropped;
375
+ debug(`Quota discard again: ${dropped} span(s); paused for ${Math.round(discard.retryAfterS)} s`);
376
+ }
377
+ }
378
+ accepted(where) {
379
+ if (!this._inEpisode) return;
380
+ this._accepts++;
381
+ if (this._accepts < EPISODE_END_ACCEPTS) return;
382
+ this._inEpisode = false;
383
+ this._accepts = 0;
384
+ this._until = -Infinity;
385
+ const t = this.now();
386
+ if (t - this._lastInfo >= QUOTA_WARN_WINDOW_MS) {
387
+ this._lastInfo = t;
388
+ info(`Risicare: ${where} accepts spans again; the export pause for the quota has ended.`);
389
+ } else {
390
+ debug("Quota pause ended (INFO already written this hour)");
391
+ }
392
+ }
393
+ };
286
394
 
287
395
  // src/exporters/http.ts
288
396
  var CAPACITY_REFUSAL_STATUSES = /* @__PURE__ */ new Set([429, 503]);
@@ -323,8 +431,23 @@ var HttpExporter = class {
323
431
  _calls = /* @__PURE__ */ new Map();
324
432
  /** The ack of each finished call, by its batch. Read once by `takeAck(spans)`. */
325
433
  _acks = /* @__PURE__ */ new WeakMap();
434
+ /** The requests that each finished call sent, by its batch. Read once by `takeAttempts(spans)`. */
435
+ _requests = /* @__PURE__ */ new WeakMap();
436
+ /** The batch processor dropped span(s) from a full queue in the quota pause (S-1). */
437
+ noteQuotaDrop(count = 1) {
438
+ this._quota.addDrops(count);
439
+ }
440
+ /** True while the exporter is paused for the monthly event quota (S-1). */
441
+ quotaPaused() {
442
+ return this._quota.paused();
443
+ }
326
444
  /** The spans of each finished call that could not be serialized, by its batch. */
327
445
  _unserializable = /* @__PURE__ */ new WeakMap();
446
+ /**
447
+ * S-1: the paused state after a monthly-quota discard (see `quota.ts`). A discard is not a
448
+ * failure: it does not touch the circuit breaker.
449
+ */
450
+ _quota = new QuotaPause();
328
451
  _circuitOpenUntil = 0;
329
452
  _circuitBreakerThreshold = 5;
330
453
  _circuitBreakerCooldownMs = 6e4;
@@ -361,6 +484,18 @@ var HttpExporter = class {
361
484
  get attemptsPerExport() {
362
485
  return this._maxRetries;
363
486
  }
487
+ /**
488
+ * Returns the number of HTTP requests that the `export()` call for `spans` sent, and clears
489
+ * it. This is the number that was sent, not the most that the call may send
490
+ * (`attemptsPerExport`): a 401 or 403 stops the loop after one request, and an open circuit
491
+ * breaker sends none. Returns `null` when no call is on record for `spans`. The answer is
492
+ * kept per batch, as `takeAck` keeps the ack.
493
+ */
494
+ takeAttempts(spans) {
495
+ const n = this._requests.get(spans) ?? null;
496
+ this._requests.delete(spans);
497
+ return n;
498
+ }
364
499
  /**
365
500
  * Returns the counts of the ack that the `export()` call for `spans` received, and clears
366
501
  * them. The answer is kept per batch, not on the instance: two processors that share this
@@ -405,17 +540,26 @@ var HttpExporter = class {
405
540
  misroute: null,
406
541
  noRetry: false,
407
542
  status: null,
408
- error: null
543
+ error: null,
544
+ attempts: 0
409
545
  };
410
546
  this._calls.set(spans, call);
411
547
  try {
412
548
  return await this._export(spans, call);
413
549
  } finally {
414
550
  this._calls.delete(spans);
551
+ this._requests.set(spans, this._endpointHasCredentials ? 0 : call.attempts);
415
552
  }
416
553
  }
417
554
  async _export(spans, call) {
418
555
  const cancelled = call.cancel.signal;
556
+ if (this._quota.paused()) {
557
+ debug(
558
+ `Export skipped: monthly quota pause, ${Math.round(this._quota.remainingS())} s left; ${spans.length} span(s) dropped`
559
+ );
560
+ this._acks.set(spans, { accepted: 0, rejected: 0, quotaDropped: spans.length });
561
+ return "success" /* SUCCESS */;
562
+ }
419
563
  const parts = [];
420
564
  const bad = [];
421
565
  let errorClass = "";
@@ -444,14 +588,13 @@ var HttpExporter = class {
444
588
  isHalfOpen = true;
445
589
  }
446
590
  const maxAttempts = isHalfOpen ? 1 : this._maxRetries;
447
- let attempts = 0;
448
591
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
449
592
  call.refusalAfterMs = null;
450
593
  call.misroute = null;
451
594
  call.noRetry = false;
452
595
  call.status = null;
453
596
  call.error = null;
454
- attempts++;
597
+ call.attempts++;
455
598
  const result = await this._sendRequest(payload, parts.length, call, spans);
456
599
  if (cancelled.aborted) {
457
600
  this._acks.delete(spans);
@@ -473,7 +616,7 @@ var HttpExporter = class {
473
616
  }
474
617
  if (call.refusalAfterMs !== null) {
475
618
  warn(
476
- `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.`
619
+ `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.`
477
620
  );
478
621
  return "failure" /* FAILURE */;
479
622
  }
@@ -624,6 +767,11 @@ var HttpExporter = class {
624
767
  `HTTP ${response.status} and a body that is not a Risicare ack (content-type: ${response.headers?.get?.("Content-Type") || "none"})`
625
768
  );
626
769
  }
770
+ if (ack.quota !== void 0) {
771
+ this._quota.enter(ack.quota, `The ingest endpoint ${this._safeEndpoint}`, spansSent);
772
+ } else if (ack.result === "success" /* SUCCESS */) {
773
+ this._quota.accepted(`the ingest endpoint ${this._safeEndpoint}`);
774
+ }
627
775
  if (ack.result === "success" /* SUCCESS */) this._acks.set(spans, ack.counts);
628
776
  if (ack.final) call.noRetry = true;
629
777
  return ack.result;
@@ -690,7 +838,16 @@ async function checkAck(response, spansSent, scrub) {
690
838
  try {
691
839
  payload = await response.json();
692
840
  } catch {
693
- return null;
841
+ payload = void 0;
842
+ }
843
+ const discard = parseJsonDiscard(payload, response.headers);
844
+ if (discard !== null) {
845
+ return {
846
+ result: "success" /* SUCCESS */,
847
+ counts: { accepted: 0, rejected: 0, quotaDropped: spansSent },
848
+ final: false,
849
+ quota: discard
850
+ };
694
851
  }
695
852
  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
696
853
  return null;