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
@@ -29,6 +29,10 @@ function warn(msg) {
29
29
  process.stderr.write(`[risicare] WARNING: ${msg}
30
30
  `);
31
31
  }
32
+ function info(msg) {
33
+ process.stderr.write(`[risicare] INFO: ${msg}
34
+ `);
35
+ }
32
36
 
33
37
  // src/utils/text.ts
34
38
  function cutCodePoints(text, max) {
@@ -246,7 +250,111 @@ function runWithContext(overrides, fn) {
246
250
  }
247
251
 
248
252
  // src/version.ts
249
- var SDK_VERSION = "0.9.0";
253
+ var SDK_VERSION = "0.9.2";
254
+
255
+ // src/exporters/quota.ts
256
+ var QUOTA_REASON = "monthly_quota_exceeded";
257
+ var QUOTA_HEADER = "X-Risicare-Quota";
258
+ var QUOTA_HEADER_VALUE = "exceeded";
259
+ var DEFAULT_RETRY_AFTER_S = 300;
260
+ var MIN_RETRY_AFTER_S = 1;
261
+ var MAX_RETRY_AFTER_S = 3600;
262
+ var QUOTA_WARN_WINDOW_MS = 36e5;
263
+ var MAX_RESETS_AT_CHARS = 40;
264
+ function asPositiveCount(v) {
265
+ if (typeof v === "number") return Number.isFinite(v) && v > 0;
266
+ if (typeof v === "string" && /^[0-9]+$/.test(v)) return Number(v) > 0;
267
+ return false;
268
+ }
269
+ function boundedRetryAfter(value) {
270
+ let n;
271
+ if (typeof value === "number") n = value;
272
+ else if (typeof value === "string" && value.trim() !== "") n = Number(value);
273
+ else return DEFAULT_RETRY_AFTER_S;
274
+ if (!Number.isFinite(n)) return DEFAULT_RETRY_AFTER_S;
275
+ return Math.min(Math.max(n, MIN_RETRY_AFTER_S), MAX_RETRY_AFTER_S);
276
+ }
277
+ function boundedResetsAt(value) {
278
+ if (typeof value !== "string" || value.length === 0) return null;
279
+ const cut = value.slice(0, MAX_RESETS_AT_CHARS);
280
+ return /^[ -~]*$/.test(cut) ? cut : null;
281
+ }
282
+ function headerSaysExceeded(headers) {
283
+ try {
284
+ const value = headers?.get?.(QUOTA_HEADER);
285
+ return typeof value === "string" && value.trim().toLowerCase() === QUOTA_HEADER_VALUE;
286
+ } catch {
287
+ return false;
288
+ }
289
+ }
290
+ function parseJsonDiscard(payload, headers) {
291
+ const body = payload !== null && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
292
+ const stored = (asPositiveCount(body.accepted) || asPositiveCount(body.spansAccepted)) === true;
293
+ if (body.reason === QUOTA_REASON || headerSaysExceeded(headers) && !stored) {
294
+ return {
295
+ retryAfterS: boundedRetryAfter(body.retryAfterSeconds),
296
+ resetsAt: boundedResetsAt(body.resetsAt)
297
+ };
298
+ }
299
+ return null;
300
+ }
301
+ var EPISODE_END_ACCEPTS = 3;
302
+ var QuotaPause = class {
303
+ constructor(now = () => performance.now()) {
304
+ this.now = now;
305
+ }
306
+ _until = -Infinity;
307
+ _inEpisode = false;
308
+ _accepts = 0;
309
+ _lastWarn = -Infinity;
310
+ _lastInfo = -Infinity;
311
+ /**
312
+ * Spans dropped since the last WARNING: the full queue's (`addDrops`) and the batches that a
313
+ * probe lost while the WARNING was held back. The WARNING carries the number.
314
+ */
315
+ _drops = 0;
316
+ addDrops(count) {
317
+ this._drops += count;
318
+ }
319
+ paused() {
320
+ return this.now() < this._until;
321
+ }
322
+ remainingS() {
323
+ return Math.max(0, (this._until - this.now()) / 1e3);
324
+ }
325
+ enter(discard, where, dropped) {
326
+ const t = this.now();
327
+ this._until = t + discard.retryAfterS * 1e3;
328
+ this._inEpisode = true;
329
+ this._accepts = 0;
330
+ if (t - this._lastWarn >= QUOTA_WARN_WINDOW_MS) {
331
+ this._lastWarn = t;
332
+ const since = this._drops;
333
+ this._drops = 0;
334
+ warn(
335
+ `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}.` : "")
336
+ );
337
+ } else {
338
+ this._drops += dropped;
339
+ debug(`Quota discard again: ${dropped} span(s); paused for ${Math.round(discard.retryAfterS)} s`);
340
+ }
341
+ }
342
+ accepted(where) {
343
+ if (!this._inEpisode) return;
344
+ this._accepts++;
345
+ if (this._accepts < EPISODE_END_ACCEPTS) return;
346
+ this._inEpisode = false;
347
+ this._accepts = 0;
348
+ this._until = -Infinity;
349
+ const t = this.now();
350
+ if (t - this._lastInfo >= QUOTA_WARN_WINDOW_MS) {
351
+ this._lastInfo = t;
352
+ info(`Risicare: ${where} accepts spans again; the export pause for the quota has ended.`);
353
+ } else {
354
+ debug("Quota pause ended (INFO already written this hour)");
355
+ }
356
+ }
357
+ };
250
358
 
251
359
  // src/exporters/http.ts
252
360
  var CAPACITY_REFUSAL_STATUSES = /* @__PURE__ */ new Set([429, 503]);
@@ -287,8 +395,23 @@ var HttpExporter = class {
287
395
  _calls = /* @__PURE__ */ new Map();
288
396
  /** The ack of each finished call, by its batch. Read once by `takeAck(spans)`. */
289
397
  _acks = /* @__PURE__ */ new WeakMap();
398
+ /** The requests that each finished call sent, by its batch. Read once by `takeAttempts(spans)`. */
399
+ _requests = /* @__PURE__ */ new WeakMap();
400
+ /** The batch processor dropped span(s) from a full queue in the quota pause (S-1). */
401
+ noteQuotaDrop(count = 1) {
402
+ this._quota.addDrops(count);
403
+ }
404
+ /** True while the exporter is paused for the monthly event quota (S-1). */
405
+ quotaPaused() {
406
+ return this._quota.paused();
407
+ }
290
408
  /** The spans of each finished call that could not be serialized, by its batch. */
291
409
  _unserializable = /* @__PURE__ */ new WeakMap();
410
+ /**
411
+ * S-1: the paused state after a monthly-quota discard (see `quota.ts`). A discard is not a
412
+ * failure: it does not touch the circuit breaker.
413
+ */
414
+ _quota = new QuotaPause();
292
415
  _circuitOpenUntil = 0;
293
416
  _circuitBreakerThreshold = 5;
294
417
  _circuitBreakerCooldownMs = 6e4;
@@ -325,6 +448,18 @@ var HttpExporter = class {
325
448
  get attemptsPerExport() {
326
449
  return this._maxRetries;
327
450
  }
451
+ /**
452
+ * Returns the number of HTTP requests that the `export()` call for `spans` sent, and clears
453
+ * it. This is the number that was sent, not the most that the call may send
454
+ * (`attemptsPerExport`): a 401 or 403 stops the loop after one request, and an open circuit
455
+ * breaker sends none. Returns `null` when no call is on record for `spans`. The answer is
456
+ * kept per batch, as `takeAck` keeps the ack.
457
+ */
458
+ takeAttempts(spans) {
459
+ const n = this._requests.get(spans) ?? null;
460
+ this._requests.delete(spans);
461
+ return n;
462
+ }
328
463
  /**
329
464
  * Returns the counts of the ack that the `export()` call for `spans` received, and clears
330
465
  * them. The answer is kept per batch, not on the instance: two processors that share this
@@ -369,17 +504,26 @@ var HttpExporter = class {
369
504
  misroute: null,
370
505
  noRetry: false,
371
506
  status: null,
372
- error: null
507
+ error: null,
508
+ attempts: 0
373
509
  };
374
510
  this._calls.set(spans, call);
375
511
  try {
376
512
  return await this._export(spans, call);
377
513
  } finally {
378
514
  this._calls.delete(spans);
515
+ this._requests.set(spans, this._endpointHasCredentials ? 0 : call.attempts);
379
516
  }
380
517
  }
381
518
  async _export(spans, call) {
382
519
  const cancelled = call.cancel.signal;
520
+ if (this._quota.paused()) {
521
+ debug(
522
+ `Export skipped: monthly quota pause, ${Math.round(this._quota.remainingS())} s left; ${spans.length} span(s) dropped`
523
+ );
524
+ this._acks.set(spans, { accepted: 0, rejected: 0, quotaDropped: spans.length });
525
+ return "success" /* SUCCESS */;
526
+ }
383
527
  const parts = [];
384
528
  const bad = [];
385
529
  let errorClass = "";
@@ -408,14 +552,13 @@ var HttpExporter = class {
408
552
  isHalfOpen = true;
409
553
  }
410
554
  const maxAttempts = isHalfOpen ? 1 : this._maxRetries;
411
- let attempts = 0;
412
555
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
413
556
  call.refusalAfterMs = null;
414
557
  call.misroute = null;
415
558
  call.noRetry = false;
416
559
  call.status = null;
417
560
  call.error = null;
418
- attempts++;
561
+ call.attempts++;
419
562
  const result = await this._sendRequest(payload, parts.length, call, spans);
420
563
  if (cancelled.aborted) {
421
564
  this._acks.delete(spans);
@@ -437,7 +580,7 @@ var HttpExporter = class {
437
580
  }
438
581
  if (call.refusalAfterMs !== null) {
439
582
  warn(
440
- `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.`
583
+ `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.`
441
584
  );
442
585
  return "failure" /* FAILURE */;
443
586
  }
@@ -588,6 +731,11 @@ var HttpExporter = class {
588
731
  `HTTP ${response.status} and a body that is not a Risicare ack (content-type: ${response.headers?.get?.("Content-Type") || "none"})`
589
732
  );
590
733
  }
734
+ if (ack.quota !== void 0) {
735
+ this._quota.enter(ack.quota, `The ingest endpoint ${this._safeEndpoint}`, spansSent);
736
+ } else if (ack.result === "success" /* SUCCESS */) {
737
+ this._quota.accepted(`the ingest endpoint ${this._safeEndpoint}`);
738
+ }
591
739
  if (ack.result === "success" /* SUCCESS */) this._acks.set(spans, ack.counts);
592
740
  if (ack.final) call.noRetry = true;
593
741
  return ack.result;
@@ -654,7 +802,16 @@ async function checkAck(response, spansSent, scrub) {
654
802
  try {
655
803
  payload = await response.json();
656
804
  } catch {
657
- return null;
805
+ payload = void 0;
806
+ }
807
+ const discard = parseJsonDiscard(payload, response.headers);
808
+ if (discard !== null) {
809
+ return {
810
+ result: "success" /* SUCCESS */,
811
+ counts: { accepted: 0, rejected: 0, quotaDropped: spansSent },
812
+ final: false,
813
+ quota: discard
814
+ };
658
815
  }
659
816
  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
660
817
  return null;