risicare 0.7.0 → 0.9.0

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 (84) hide show
  1. package/README.md +346 -68
  2. package/dist/frameworks/instructor.cjs +790 -5
  3. package/dist/frameworks/instructor.cjs.map +1 -1
  4. package/dist/frameworks/instructor.js +780 -5
  5. package/dist/frameworks/instructor.js.map +1 -1
  6. package/dist/frameworks/langchain.cjs +790 -5
  7. package/dist/frameworks/langchain.cjs.map +1 -1
  8. package/dist/frameworks/langchain.d.cts +3 -2
  9. package/dist/frameworks/langchain.d.ts +3 -2
  10. package/dist/frameworks/langchain.js +780 -5
  11. package/dist/frameworks/langchain.js.map +1 -1
  12. package/dist/frameworks/langgraph.cjs +790 -5
  13. package/dist/frameworks/langgraph.cjs.map +1 -1
  14. package/dist/frameworks/langgraph.js +780 -5
  15. package/dist/frameworks/langgraph.js.map +1 -1
  16. package/dist/frameworks/llamaindex.cjs +801 -5
  17. package/dist/frameworks/llamaindex.cjs.map +1 -1
  18. package/dist/frameworks/llamaindex.d.cts +3 -2
  19. package/dist/frameworks/llamaindex.d.ts +3 -2
  20. package/dist/frameworks/llamaindex.js +791 -5
  21. package/dist/frameworks/llamaindex.js.map +1 -1
  22. package/dist/index.cjs +1219 -212
  23. package/dist/index.cjs.map +1 -1
  24. package/dist/index.d.cts +250 -44
  25. package/dist/index.d.ts +250 -44
  26. package/dist/index.js +1219 -212
  27. package/dist/index.js.map +1 -1
  28. package/dist/providers/anthropic/index.cjs +1601 -36
  29. package/dist/providers/anthropic/index.cjs.map +1 -1
  30. package/dist/providers/anthropic/index.d.cts +3 -1
  31. package/dist/providers/anthropic/index.d.ts +3 -1
  32. package/dist/providers/anthropic/index.js +1591 -36
  33. package/dist/providers/anthropic/index.js.map +1 -1
  34. package/dist/providers/bedrock/index.cjs +850 -32
  35. package/dist/providers/bedrock/index.cjs.map +1 -1
  36. package/dist/providers/bedrock/index.js +840 -32
  37. package/dist/providers/bedrock/index.js.map +1 -1
  38. package/dist/providers/cerebras/index.cjs +1534 -30
  39. package/dist/providers/cerebras/index.cjs.map +1 -1
  40. package/dist/providers/cerebras/index.js +1524 -30
  41. package/dist/providers/cerebras/index.js.map +1 -1
  42. package/dist/providers/cohere/index.cjs +1557 -102
  43. package/dist/providers/cohere/index.cjs.map +1 -1
  44. package/dist/providers/cohere/index.js +1547 -102
  45. package/dist/providers/cohere/index.js.map +1 -1
  46. package/dist/providers/google/index.cjs +1562 -60
  47. package/dist/providers/google/index.cjs.map +1 -1
  48. package/dist/providers/google/index.js +1552 -60
  49. package/dist/providers/google/index.js.map +1 -1
  50. package/dist/providers/groq/index.cjs +1534 -30
  51. package/dist/providers/groq/index.cjs.map +1 -1
  52. package/dist/providers/groq/index.js +1524 -30
  53. package/dist/providers/groq/index.js.map +1 -1
  54. package/dist/providers/huggingface/index.cjs +1622 -25
  55. package/dist/providers/huggingface/index.cjs.map +1 -1
  56. package/dist/providers/huggingface/index.d.cts +0 -9
  57. package/dist/providers/huggingface/index.d.ts +0 -9
  58. package/dist/providers/huggingface/index.js +1612 -25
  59. package/dist/providers/huggingface/index.js.map +1 -1
  60. package/dist/providers/mistral/index.cjs +1535 -54
  61. package/dist/providers/mistral/index.cjs.map +1 -1
  62. package/dist/providers/mistral/index.js +1525 -54
  63. package/dist/providers/mistral/index.js.map +1 -1
  64. package/dist/providers/ollama/index.cjs +1559 -93
  65. package/dist/providers/ollama/index.cjs.map +1 -1
  66. package/dist/providers/ollama/index.js +1549 -93
  67. package/dist/providers/ollama/index.js.map +1 -1
  68. package/dist/providers/openai/index.cjs +1598 -61
  69. package/dist/providers/openai/index.cjs.map +1 -1
  70. package/dist/providers/openai/index.d.cts +6 -1
  71. package/dist/providers/openai/index.d.ts +6 -1
  72. package/dist/providers/openai/index.js +1588 -61
  73. package/dist/providers/openai/index.js.map +1 -1
  74. package/dist/providers/together/index.cjs +1534 -30
  75. package/dist/providers/together/index.cjs.map +1 -1
  76. package/dist/providers/together/index.js +1524 -30
  77. package/dist/providers/together/index.js.map +1 -1
  78. package/dist/providers/vercel-ai/index.cjs +1288 -17
  79. package/dist/providers/vercel-ai/index.cjs.map +1 -1
  80. package/dist/providers/vercel-ai/index.d.cts +0 -6
  81. package/dist/providers/vercel-ai/index.d.ts +0 -6
  82. package/dist/providers/vercel-ai/index.js +1278 -17
  83. package/dist/providers/vercel-ai/index.js.map +1 -1
  84. package/package.json +1 -1
package/README.md CHANGED
@@ -7,7 +7,9 @@ AI agent observability and error diagnosis for Node.js and TypeScript.
7
7
  [![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue.svg)](https://www.npmjs.com/package/risicare)
8
8
  [![License: Proprietary](https://img.shields.io/badge/license-proprietary-red.svg)](LICENSE)
9
9
 
10
- Monitor your AI agents in production. Trace every LLM call, detect errors automatically, and get AI-generated fix suggestions — with 3 lines of setup.
10
+ Monitor your AI agents in production. Patch your LLM client, wrap your agent,
11
+ and the SDK sends a span for each traced call to Risicare. Risicare then
12
+ diagnoses the errors and suggests fixes.
11
13
 
12
14
  ## Quickstart
13
15
 
@@ -20,11 +22,8 @@ import { init, agent, shutdown } from 'risicare';
20
22
  import { patchOpenAI } from 'risicare/openai';
21
23
  import OpenAI from 'openai';
22
24
 
23
- // 1. Initialize
24
- init({
25
- apiKey: 'rsk-...',
26
- endpoint: 'https://ingest.risicare.ai',
27
- });
25
+ // 1. Initialize (for the hosted service, set no endpoint)
26
+ init({ apiKey: 'rsk-...' });
28
27
 
29
28
  // 2. Patch your LLM client
30
29
  const openai = patchOpenAI(new OpenAI());
@@ -38,18 +37,73 @@ const myAgent = agent({ name: 'research-agent' }, async (query: string) => {
38
37
  return response.choices[0].message.content;
39
38
  });
40
39
 
41
- // Run it — traces appear in your dashboard within seconds
40
+ // Run it
42
41
  const result = await myAgent('What is quantum computing?');
43
42
  await shutdown();
44
43
  ```
45
44
 
46
- **That's it.** Your agent's LLM calls, latency, token usage, and costs now appear in the [Risicare dashboard](https://app.risicare.ai).
45
+ The SDK sends one span for the agent function and one span for the LLM call,
46
+ in the same trace. The LLM span has the model, the latency, the token counts
47
+ and the cost. You see them in the [Risicare dashboard](https://app.risicare.ai).
48
+
49
+ ## Two hosts
50
+
51
+ The SDK sends data to two hosts:
52
+
53
+ - **Spans** go to `endpoint`. The default is `https://ingest.risicare.ai`.
54
+ - **Scores and fix reads** go to `apiEndpoint`. The default is `https://api.risicare.ai`.
55
+
56
+ For the hosted service, set neither. For your own deployment, set `endpoint`
57
+ (or `RISICARE_ENDPOINT`). Scores and fix reads go to the first of these that
58
+ is set:
59
+
60
+ 1. the `apiEndpoint` option;
61
+ 2. the `endpoint` option, unless it is the default ingest host;
62
+ 3. the `RISICARE_API_ENDPOINT` environment variable;
63
+ 4. the `RISICARE_ENDPOINT` environment variable, if you gave no `endpoint`
64
+ option and it is not the default ingest host;
65
+ 5. the default, `https://api.risicare.ai`.
66
+
67
+ The SDK ignores the default ingest host (`https://ingest.risicare.ai`) when it
68
+ selects the api host, and goes to the next step. So your key does not go to a
69
+ host that you did not name. Only that exact value is ignored (letter case, a
70
+ `:443` port and slashes at the end do not matter). A different form, for
71
+ example `http://ingest.risicare.ai` or `https://ingest.risicare.ai/v1`, is a
72
+ host that you named, and the SDK uses it. A value that is empty, or that has
73
+ ASCII whitespace only, is "not set". `RISICARE_ENDPOINT=https://my-host` alone sends spans, scores and fix
74
+ reads to `https://my-host`.
75
+
76
+ ## Configuration
77
+
78
+ `RISICARE_TRACING` is trimmed and compared without case:
79
+
80
+ | Value | Result |
81
+ |-------|--------|
82
+ | `true`, `1`, `yes`, `on` | tracing on |
83
+ | `false`, `0`, `no`, `off` | tracing off |
84
+ | unset, empty, or whitespace only | the default applies |
85
+ | any other value | tracing off, with one WARNING that names the value |
86
+
87
+ The `enabled` option has priority over the variable. With no API key, tracing
88
+ is off, whatever `enabled` or `RISICARE_TRACING` says (see "A note on running
89
+ without an API key").
90
+
91
+ ## Imports
92
+
93
+ The package has no default export. Use named imports or a namespace import.
94
+ `Span` and `Tracer` are types only: import them with `import type`.
95
+
96
+ ```typescript
97
+ import { init, agent } from 'risicare';
98
+ import * as risicare from 'risicare';
99
+ import type { Span, Tracer } from 'risicare';
100
+ ```
47
101
 
48
102
  ## Prompt content is NOT captured by default
49
103
 
50
- **Since 0.5.1, `traceContent` defaults to `false`.** Your prompts and completions
104
+ **`traceContent` defaults to `false`** (since 0.5.2, the first published version with this default). Your prompts and completions
51
105
  stay in your process. Everything else — model, token counts, latency, cost,
52
- message roles, errors, and any attributes you set — is captured as normal, so the
106
+ errors, and any attributes you set — is captured as normal, so the
53
107
  dashboard, cost tracking and error diagnosis all work unchanged.
54
108
 
55
109
  To send prompt and completion text as well, opt in:
@@ -59,6 +113,25 @@ init({ apiKey: 'rsk-...', traceContent: true });
59
113
  // or set RISICARE_TRACE_CONTENT=true
60
114
  ```
61
115
 
116
+ **Which providers capture text.** With `traceContent: true`:
117
+
118
+ - `patchOpenAI` and `patchAnthropic` capture the prompt and the completion text.
119
+ They write the first 10 messages to `gen_ai.prompt.N.role` and
120
+ `gen_ai.prompt.N.content`. They write the completion to
121
+ `gen_ai.completion.content`. `patchAnthropic` also writes a string `system`
122
+ prompt to `gen_ai.system_prompt`. The SDK cuts each text at 10,000 characters
123
+ (Unicode code points). It cuts the system prompt at 5,000. `patchOpenAI` also
124
+ captures text for a client of an OpenAI-compatible host.
125
+ - For a streamed call, they capture the prompt only, not the completion.
126
+ - `patchGoogleAI`, `patchMistral`, `patchGroq`, `patchCohere`, `patchTogether`,
127
+ `patchOllama`, `patchHuggingFace`, `patchCerebras`, `patchBedrock` and
128
+ `patchVercelAI` capture no prompt or completion text.
129
+
130
+ **Error text is not covered by this switch.** The error message from a
131
+ provider can contain your prompt text. For example, a 400 error can repeat
132
+ part of the prompt. The SDK sends error messages also when `traceContent` is
133
+ off, because error diagnosis uses them.
134
+
62
135
  **Upgrading from 0.5.0 or earlier?** This is a behaviour change: content that
63
136
  used to be sent is no longer sent unless you opt in. In those versions the flag
64
137
  also did not work for content you set by hand — `traceContent: false` did not
@@ -73,9 +146,9 @@ Since 0.7.0, the gate also covers the OpenTelemetry GenAI, OpenInference and
73
146
  CrewAI content keys, for example `input.value`, `output.value`,
74
147
  `gen_ai.input.messages` and `gen_ai.output.messages`.
75
148
 
76
- If you want content captured but redacted first, use the `mask` hook — it is
77
- independent of this switch and runs on every content-bearing field before
78
- export:
149
+ If you want content captured but redacted first, use the `mask` hook. It runs
150
+ on every content-bearing field of every span before export, for every
151
+ exporter:
79
152
 
80
153
  ```typescript
81
154
  init({ apiKey: 'rsk-...', traceContent: true, mask: (key, value) => value });
@@ -87,31 +160,91 @@ init({ apiKey: 'rsk-...', traceContent: true, mask: (key, value) => value });
87
160
  - **12 LLM providers** — OpenAI, Anthropic, Google, Mistral, Groq, Cohere, Together, Ollama, HuggingFace, Cerebras, Bedrock, Vercel AI
88
161
  - **4 framework integrations** — LangChain, LangGraph, Instructor, LlamaIndex
89
162
  - **Error Diagnosis (beta)** — LLM-powered root cause analysis with fix suggestions; auto-apply not yet wired (see "Error Diagnosis" section below)
90
- - **Evaluation scores** — Rate agent quality with `score()` and 13 built-in scorers
91
- - **Streaming support** — `tracedStream()` for async iterator tracing
92
- - **Context propagation** — Automatic across `async/await`, `Promise`, `setTimeout`, `EventEmitter`
163
+ - **Evaluation scores** — Rate agent quality with `score()`
164
+ - **Streaming** — `tracedStream()` traces an async iterator (see "Streaming" below)
165
+ - **Context propagation** — Automatic across `async/await`, `Promise` and `setTimeout`. An `EventEmitter` listener runs in the context of the `emit()` call
93
166
  - **Zero runtime dependencies** — No bloat in your node_modules
94
167
  - **Dual CJS/ESM** — Works with `require()` and `import`
95
168
  - **Full TypeScript** — Strict types and IntelliSense out of the box
96
- - **Non-blocking** — Async batch export with circuit breaker and retry
97
- - **Zero overhead when disabled** — Frozen NOOP_SPAN singleton, no allocations
169
+ - **Background export** — Async batch export with circuit breaker and retry
170
+ - **Low cost when disabled** — a frozen no-op span
98
171
 
99
172
  ## LLM Providers
100
173
 
101
174
  ```typescript
175
+ import OpenAI from 'openai';
102
176
  import { patchOpenAI } from 'risicare/openai';
103
177
  import { patchAnthropic } from 'risicare/anthropic';
104
- import { patchGoogle } from 'risicare/google';
178
+ import { patchGoogleAI } from 'risicare/google';
105
179
  // ... and 9 more
106
180
 
107
181
  const openai = patchOpenAI(new OpenAI());
108
- // Every call is now traced — model, tokens, latency, cost
182
+ // chat.completions.create and embeddings.create are now traced
109
183
  ```
110
184
 
111
185
  All 12 providers:
112
186
 
113
187
  `openai` · `anthropic` · `google` · `mistral` · `groq` · `cohere` · `together` · `ollama` · `huggingface` · `cerebras` · `bedrock` · `vercel-ai`
114
188
 
189
+ `patchOpenAI` also traces an OpenAI-compatible host (`baseURL`). It sets the
190
+ provider name (`gen_ai.system`) from the host for DeepSeek, Together, Groq, xAI,
191
+ Fireworks, Baseten, Novita and BytePlus (`api.byteplus.com` and
192
+ `ark.cn-beijing.byteplus.com`). Any other host is named `openai`.
193
+
194
+ ### Streaming
195
+
196
+ The caller gets the provider's own promise and stream objects. The SDK counts
197
+ only the chunks that the caller reads. It does not read ahead. The span of a
198
+ stream ends once, when the stream ends, with `stream.end_reason`:
199
+
200
+ | `stream.end_reason` | When | Status |
201
+ |---|---|---|
202
+ | `done` | The caller read the stream to its end. | ok |
203
+ | `return` | The caller stopped early (`break`, `return()`). | ok |
204
+ | `abort` | An abort stopped the stream: `controller.abort()` or the request `signal` (OpenAI, Anthropic, Groq, Together, Cerebras), the request `abortSignal` (Cohere), Ollama `abort()`, `cancel()`, or an `AbortError` that reached the caller. See the Google and Mistral limits. The span also gets `risicare.cancelled` = `true` and `risicare.cancel_type` = `AbortError`. | error |
205
+ | `error` | An error reached the caller. The span records it. | error |
206
+ | `handoff` | The caller took the data another way: `tee()`, `getReader()`, `toReadableStream()`, `pipeTo()`, `pipeThrough()` or `asResponse()`. | ok |
207
+ | `garbage` | Nothing holds the promise, the stream or an iterator, and no `next()` waits. The JavaScript engine decides when this is seen; it can be never. | ok |
208
+ | `shutdown` | `shutdown()` ends every stream span that is still open, and exports it. | ok |
209
+
210
+ The span has `stream.chunk_count`: the number of chunks that the caller read.
211
+ It has the token counts that the chunks gave: the usage chunk (OpenAI needs
212
+ `stream_options: { include_usage: true }`; also Groq, Together, Cerebras,
213
+ Hugging Face), `message_start` and `message_delta` (Anthropic), the last
214
+ `usageMetadata` (Google), the chunk `usage` (Mistral), the last chunk with
215
+ `done` (Ollama), `message-end` (Cohere). A count that the stream did not give
216
+ stays empty. The span does not capture the streamed completion text.
217
+
218
+ Call `shutdown()` before the process stops. A span that is still open is lost
219
+ if the process stops without it.
220
+
221
+ Limits:
222
+
223
+ - Cohere: `stream.controller.abort()` does not stop a Cohere stream, so it is
224
+ not an abort. The request option `abortSignal` stops it, and is an abort.
225
+ - Google, the request `signal`: the Google SDK changes the abort into a
226
+ `GoogleGenerativeAIError`. A read after the abort ends the span as `error`,
227
+ not `abort`. An abort with no read after it ends as `garbage` or
228
+ `shutdown`, status ok.
229
+ - Mistral, the request `signal` (`fetchOptions.signal`): a read after the
230
+ abort gets an `AbortError`, and the span ends as `abort`. The SDK cannot see
231
+ this signal, so an abort with no read after it ends as `garbage` or
232
+ `shutdown`, status ok.
233
+ - Google `result.response`: the Google SDK gives the aggregated response also
234
+ when nobody reads `result.stream`. If the caller never takes `result.stream`,
235
+ the span ends as `done` when `result.response` settles, with the tokens of
236
+ the aggregated response and `stream.chunk_count` = 0 (`error` if it
237
+ rejects). If the caller takes `result.stream`, the stream decides the end.
238
+ A stream that the caller takes after the span ended is not counted.
239
+ - `handoff`: the SDK does not see the chunks after the handoff, so the chunk
240
+ and token counts cover only the chunks read before it.
241
+ - Bedrock (`ConverseStreamCommand`): the SDK does not read the stream. The
242
+ span ends when `send()` returns. It has no token counts.
243
+ - Vercel AI (`tracedStreamText`): the span ends through the `streamText`
244
+ callbacks: `onFinish` (`done`, with the usage), `onAbort` (`abort`) or an
245
+ error chunk (`error`). With no callback, it ends as `garbage` or at
246
+ `shutdown()`.
247
+
115
248
  ## Framework Integrations
116
249
 
117
250
  ```typescript
@@ -130,13 +263,24 @@ const client = patchInstructor(instructor);
130
263
 
131
264
  // LlamaIndex
132
265
  import { RisicareLlamaIndexHandler } from 'risicare/llamaindex';
266
+ const liHandler = new RisicareLlamaIndexHandler();
267
+ for (const name of RisicareLlamaIndexHandler.EVENT_NAMES) {
268
+ Settings.callbackManager.on(name, (e) => liHandler.onEvent(e)); // Settings from 'llamaindex'
269
+ }
133
270
  ```
134
271
 
272
+ The LangChain and LlamaIndex handlers give one LLM span for each model call.
273
+ Use one handler: two handler instances on one call (for example one in the model
274
+ constructor and one in `invoke`) give two LLM spans. LangChain's `ChatOpenAI` and LlamaIndex's `OpenAI` make their own OpenAI client.
275
+ `patchOpenAI` changes only the client that you give to it, so it does not add a
276
+ second span to these calls. You need `withSuppression()` only when the same call
277
+ also goes through a client that you patched.
278
+
135
279
  ## Core API
136
280
 
137
281
  ```typescript
138
282
  import {
139
- init, shutdown, // Lifecycle
283
+ init, flush, shutdown, // Lifecycle
140
284
  agent, session, // Identity & grouping
141
285
  traceThink, traceDecide, traceAct, // Decision phases
142
286
  reportError, score, // Diagnosis & evaluation
@@ -144,48 +288,150 @@ import {
144
288
  } from 'risicare';
145
289
 
146
290
  init({ apiKey, endpoint }) // Initialize SDK
147
- agent({ name }, fn) // Wrap function with agent identity
148
- session({ sessionId, userId }, fn) // Group traces into user sessions
149
- // These are WRAPPER FACTORIES: they return a function you then call.
150
- await traceThink('analyze', async () => {...})() // note the trailing ()
151
- await traceDecide('choose', async () => {...})()
152
- await traceAct('execute', async () => {...})()
291
+ // agent(), session() and the trace* functions are WRAPPER FACTORIES:
292
+ // they return a function that you then call. Note the trailing ().
293
+ await agent({ name }, fn)() // Run fn with agent identity
294
+ await session({ sessionId, userId }, fn)() // Run fn in a user session
295
+ await traceThink('analyze', fn)()
296
+ await traceDecide('choose', fn)()
297
+ await traceAct('execute', fn)()
153
298
  reportError(error) // Report caught errors for diagnosis
154
299
  score(traceId, 'quality', 0.92) // Record evaluation score [0.0-1.0]
155
300
  tracedStream(asyncIterable, 'stream') // Trace async iterators
156
- await shutdown() // Flush pending spans and close
301
+ await flush(5000) // Wait for delivery; false when a span or a score was lost
302
+ await shutdown(5000) // Deliver what it can in the time, then stop
157
303
  ```
158
304
 
305
+ ## Delivery: flush, shutdown and metrics
306
+
307
+ - `await flush(timeoutMs?)` waits for the queued spans and the pending scores
308
+ (default 5000 ms). It returns `true` only when the gateway acknowledged every
309
+ span and every score that the SDK accepted since the previous `flush()`
310
+ returned (or since `init()`), and nothing is queued or in flight. When the SDK
311
+ has no evidence of delivery, `flush()` is not `true`.
312
+ - A loss of any kind makes exactly one `flush()` return `false`: the next one
313
+ that ends. A loss is a drop for any reason (`shutdown_residue` included), a
314
+ rejection, a failed score, and a score that `score()` refuses at the call. It
315
+ also raises a counter with a named reason: `droppedSpansByReason`,
316
+ `rejectedSpans` or `failedScores`. A `flush()` that returns `false` at its
317
+ deadline, while none of these counters went up since the previous `flush()`,
318
+ means that spans are still in flight: they are not lost. `flush()` only waits.
319
+ It does not stop a request that is already sent. With more than one exporter,
320
+ a batch counts as delivered when the first exporter that succeeds takes it:
321
+ `flush()` can then return `true` while another exporter refused the batch.
322
+ - `flush()` returns `false` when the SDK is not active: before `init()`, with
323
+ tracing off at `init()` (`enabled: false`, `RISICARE_TRACING=false`), and with
324
+ no API key. `isEnabled()` is `false` in the same cases, and after `shutdown()`
325
+ or the SDK's own drain at SIGTERM or SIGINT.
326
+ - A `flush()` that comes while a `shutdown()` runs (your own call, or the SDK's
327
+ drain at SIGTERM or SIGINT) waits for that shutdown, inside its own deadline,
328
+ and then reports the real outcome of what the SDK accepted, with the same
329
+ loss rule. So does a `flush()` after `shutdown()`. It never answers from the
330
+ state of an empty queue.
331
+ - A span that ends while a `shutdown()` runs (your own call, or the SDK's drain
332
+ at SIGTERM or SIGINT) joins that drain, and is exported before the drain ends.
333
+ A span that ends after the drain has stopped taking spans (nothing was left
334
+ to export, a round failed, or its time ended) is counted at once as
335
+ `shutdown_residue`, with one WARNING for the first one, and one `flush()`
336
+ returns `false`. It is never dropped without a count.
337
+ - At SIGTERM and SIGINT the SDK drains what it holds. In both orders of
338
+ registration `flush()` reports the real outcome, and your listener runs once
339
+ and decides the exit. When your application has its own listener for the
340
+ signal when the signal arrives, the SDK does not raise the signal again and
341
+ does not end the process. When it has none at that moment, and had none when
342
+ it called `init()`, the SDK raises the signal again after its drain, so that
343
+ the default action ends the process. A listener that you add during the
344
+ drain runs on that second signal.
345
+ - The order of registration does change one thing: which spans your listener
346
+ makes are delivered. Node calls the listeners in the order of registration. A
347
+ listener that you register BEFORE `init()` runs before the SDK's: the spans
348
+ that it ends before it first waits are in the queue when the SDK drains, and
349
+ are delivered. A listener that you register AFTER `init()` runs after the
350
+ SDK's drain started. A span that it ends can miss the drain, when the drain
351
+ has stopped taking spans (nothing was left to export, a round failed, or its
352
+ time ended). That span is counted as `shutdown_residue`, and one `flush()`
353
+ returns `false`. A span that ends after the drain ended is counted in the same
354
+ way, in both orders. If your listener must make spans that are delivered,
355
+ register it before `init()`, or end the spans before the signal.
356
+ - A new `init()` (after `shutdown()`) starts a new count: "since `init()`" in the
357
+ rules above. A loss that was not reported is not carried over. Report the old
358
+ client's loss with `flush()` or `getMetrics()` before you call `init()` again.
359
+ - `await shutdown(timeoutMs?)` is the call that ends a process in a fixed time
360
+ (default 5000 ms). At the deadline it stops the export in flight. It counts
361
+ the spans that it did not deliver as `shutdown_residue`, with one WARNING.
362
+ - A timeout that is not a finite number means 5000 ms.
363
+ - `getMetrics()` gives `exportedSpans` (spans that the backend accepted),
364
+ `rejectedSpans`, `droppedSpans`, `droppedSpansByReason` (`queue_full`,
365
+ `transport_refused`, `shutdown_residue`, `unacknowledged`), `failedExports`,
366
+ `failedScores`, the queue numbers and `sdkState`. `unacknowledged` counts
367
+ spans that were sent, or that could not be serialized, and that the
368
+ backend's answer did not account for. `failedExports` counts the export
369
+ calls that failed as a whole. A later round can still deliver those spans, so
370
+ it is not a loss counter: the loss counters are `droppedSpansByReason`,
371
+ `rejectedSpans` and `failedScores`.
372
+ - `score()` stops its request after 2000 ms and does not follow a redirect. A
373
+ status of 300 or more, an error or a timeout adds 1 to `failedScores`. The
374
+ first failure writes one WARNING at once. Failures in the next 10 seconds
375
+ are counted, and the next WARNING gives their number. A score that `score()`
376
+ refuses at the call (a value that is not a number or is outside 0 to 1, an
377
+ empty trace id or name) writes one WARNING, is not sent, and also adds 1 to
378
+ `failedScores`. When the SDK is not active (before `init()`, after `shutdown()`
379
+ or the SDK's own drain, tracing off, no key), nothing is counted.
380
+ At most 50 score requests run at one time. Up to 1,000 scores wait for a free
381
+ slot, with no timer: the 2000 ms bound starts when the request starts. A score
382
+ that comes when 1,000 already wait fails at once and is counted. When the bound
383
+ of `flush()` or `shutdown()` ends, the scores that still wait fail and are not
384
+ sent.
385
+
159
386
  ## Error Diagnosis
160
387
 
161
- > **Beta status (2026-05):** detect → diagnose → suggest is shipped and runs against
162
- > Together.AI Llama-3.3-70B with a circuit-breaker / template-only fallback. Suggested
163
- > fixes land in your dashboard as `status=draft` for human review. Automatic
164
- > deployment, A/B rollout, and learning-from-outcomes (stages 4–6 in our docs) are
165
- > in development and not yet wired in production. Treat this as **AI-assisted
166
- > error diagnosis** today; auto-apply will follow.
388
+ > **Beta.** The Risicare service detects an error, diagnoses it and suggests a
389
+ > fix. The diagnosis runs on the service, with Together.AI Llama-3.3-70B.
390
+ > Suggested fixes land in your dashboard as `status=draft` for human review.
391
+ > Automatic deployment, A/B rollout and learning from outcomes are not
392
+ > available. Treat this as **AI-assisted error diagnosis**.
167
393
 
168
- When your agent fails, Risicare:
394
+ When your agent fails:
169
395
 
170
- 1. **Classifies** the error (154 codes across TOOL, MEMORY, REASONING, OUTPUT, etc.)
171
- 2. **Diagnoses** the root cause using AI analysis
172
- 3. **Generates** a fix suggestion you can review in the dashboard and apply manually
396
+ 1. The SDK records the error on the span and gives it an error code
397
+ (`error.code`). The taxonomy has 154 codes in 10 modules (TOOL, MEMORY,
398
+ REASONING, OUTPUT and others). The SDK's own rules give 18 of them. An
399
+ error that no rule matches gets a 19th, `TOOL.EXECUTION.CRASHED`.
400
+ 2. The Risicare service diagnoses the root cause.
401
+ 3. The service writes a fix suggestion that you can review in the dashboard
402
+ and apply manually.
173
403
 
174
404
  ```typescript
175
405
  try {
176
406
  await myAgent(input);
177
407
  } catch (error) {
178
- reportError(error); // Triggers diagnosis pipeline; fix lands as draft for review
408
+ reportError(error); // Records the error for diagnosis; the fix lands as a draft for review
179
409
  }
180
410
  ```
181
411
 
182
412
  ## Fix application is off by default
183
413
 
184
- **Since 0.7.0, FixRuntime starts only when you opt in.** FixRuntime reads the
185
- active fixes for your project from Risicare and applies them to your LLM calls.
186
- A fix can change a prompt, a parameter, a tool, the retry or fallback behaviour,
187
- a guard, or the model routing. Through 0.6.0, FixRuntime started automatically
188
- when you set an API key.
414
+ **Since 0.7.0, FixRuntime starts only when you opt in.** During the beta, the
415
+ Risicare service does not give fixes to customer projects, so FixRuntime has no
416
+ effect for them. Through 0.6.0, FixRuntime started automatically when you set an
417
+ API key.
418
+
419
+ When FixRuntime is on, it reads the active fixes for your project from Risicare.
420
+ The fix interceptor enforces guard fixes on these paths only: `interceptCall` and
421
+ `interceptResponse` on the runtime, and the input guards of the patched OpenAI
422
+ chat call. The guards do not run when a framework integration suppresses provider
423
+ instrumentation. A failed input guard throws `GuardRejectedError` before the LLM
424
+ call. The input guards check messages that have text content: a string, or the
425
+ `text` parts of a list. A guard pattern that is not usable (not a string, empty,
426
+ longer than 500 characters, or JavaScript cannot use it) rejects the call. The
427
+ provider path does not apply prompt, parameter or fallback fixes.
428
+
429
+ Each SDK uses its own regular-expression engine. These constructs can give a
430
+ different result in JavaScript and Python: `$` before a final newline, Unicode
431
+ case folding, `\d` and `\w` on non-ASCII text, and a `]` first in a class.
432
+ JavaScript rejects a pattern that contains `\N{...}` or `\U........`. A pattern
433
+ has no time bound: a pattern with nested repeats can take a very long time on a
434
+ long input.
189
435
 
190
436
  When FixRuntime is off, the SDK does not request `/fixes/active`, and it does
191
437
  not change your LLM calls. Tracing, error reporting and scores are not affected.
@@ -226,44 +472,76 @@ const myAgent = agent({ name: 'planner', role: 'coordinator' }, async (input) =>
226
472
 
227
473
  ## Sessions
228
474
 
229
- Group traces from the same user conversation:
475
+ Group traces from the same user conversation. `withSession` runs the callback
476
+ now and returns its result:
230
477
 
231
478
  ```typescript
232
- const result = await session(
479
+ import { withSession } from 'risicare';
480
+
481
+ const result = await withSession(
233
482
  { sessionId: 'sess-abc123', userId: 'user-456' },
234
483
  () => myAgent(userMessage)
235
484
  );
236
485
  ```
237
486
 
487
+ `session()` does not run the callback. It returns a wrapped function, which you
488
+ call later, for example once for each request.
489
+
238
490
  ## Known limitation — span loss during a backend outage
239
491
 
240
- The SDK does **not** currently survive a sustained outage of the Risicare
241
- backend, and the loss is silent to your application (it is warned about, but
242
- nothing throws and `flush()` will not fail your request path).
492
+ The SDK does **not** keep spans through a long outage of the Risicare backend.
493
+ Nothing throws in your application. The SDK writes a WARNING, `flush()`
494
+ returns `false`, and `getMetrics()` counts the lost spans in
495
+ `droppedSpansByReason.transport_refused`.
243
496
 
244
497
  The HTTP exporter opens a circuit breaker after **5 consecutive failed export
245
- calls** and holds it open for **60 seconds**, returning failure immediately
246
- without touching the network. Queued spans get 3 re-queue attempts, which against
247
- an open breaker resolve in microseconds — so they are dropped — and for the
248
- remainder of the cooldown the SDK will not retry even after your backend is
249
- healthy again.
250
-
251
- Measured, for a 1,000-span cohort emitted during the outage: **4 s → all
252
- delivered; 5 s → half; 6 s and beyond → none.** The thresholds are counted in
253
- **failed calls, not seconds** — where the 5th consecutive failure falls in
254
- wall-clock time depends on your span rate and on how fast your endpoint fails.
255
-
256
- Nothing is lost on a clean `shutdown()`, and short blips that stay under the
257
- 5-failure threshold are fully survivable. Tracked as `F-SDKBLIP-001`.
498
+ calls** and holds it open for **60 seconds**. While it is open, an export
499
+ returns failure at once and does not use the network. A batch that fails is
500
+ put back in the queue at most 3 times. Against an open breaker these 3
501
+ attempts fail at once, so the spans are dropped. For the rest of the cooldown
502
+ the SDK does not send, also when your backend is healthy again.
503
+
504
+ The thresholds count **failed calls, not seconds**. When the 5th consecutive
505
+ failure occurs depends on your span rate and on how fast your endpoint fails.
506
+ A short failure that stays under 5 consecutive failed calls does not open the
507
+ breaker. Tracked as `F-SDKBLIP-001`.
508
+
509
+ One export call sends a batch at most 3 times. A 401 or 403 answer is sent
510
+ once in each export call: the endpoint refused the API key, and the same key
511
+ gets the same answer. At the first failed export of an outage (at most once in
512
+ 5 minutes), the SDK writes the WARNING "spans are NOT reaching ...". It gives
513
+ the HTTP status of the last answer, or the error code when there was no answer.
514
+ For a 401 or 403 it tells you to check the API key. When the kind of failure
515
+ changes in one outage (for example a 401, then no answer), the SDK writes one more
516
+ WARNING. An endpoint URL with credentials (a user name or a password before the
517
+ host) is not supported: `fetch` does not send a request to it.
518
+
519
+ The SDK removes its API key from each text that it logs: in any case of letters,
520
+ and also when the key is percent-encoded. An endpoint is logged without its user
521
+ name, password and query. A secret that you put in another place of a URL (for
522
+ example in its path) is logged as you gave it.
258
523
 
259
524
  ## A note on running without an API key
260
525
 
261
- If tracing is enabled but no API key is configured, the SDK emits a one-time
262
- `console.warn` and **drops** the spans. It deliberately does **not** print span
263
- payloads to your console: the SDK performs no redaction of its own, so printing
264
- would put prompts, completions and anything else in your attributes onto your
265
- stderr. If you want console output for local development, pass `debug: true`
266
- explicitly.
526
+ With no API key (an empty one, or one of only whitespace, counts as none) the SDK
527
+ sends nothing to Risicare, whatever `RISICARE_TRACING`, `enabled` or `enable()`
528
+ says. Tracing is off:
529
+ `isEnabled()` is `false`, `flush()` returns `false`, and the metrics show
530
+ nothing exported. The SDK says so once, at `init()`, in one WARNING on stderr:
531
+ there is no API key, nothing is sent, `flush()` returns `false`, and how to set
532
+ the key. There is no WARNING when you turned tracing off on purpose
533
+ (`enabled: false`, `RISICARE_TRACING=false`).
534
+
535
+ The SDK also prints no span without a key, with `debug: true` too. It performs no
536
+ redaction of its own, so printing would put prompts, completions and anything
537
+ else in your attributes onto your stderr. (The Python SDK prints spans with
538
+ `debug=True` and no key. They are display only: never counted, never sent.)
539
+
540
+ The SDK trims the key. An `apiKey` option that is empty, or only whitespace, counts
541
+ as "not given": the SDK then uses `RISICARE_API_KEY`.
542
+
543
+ Not active means not true: `flush()` also returns `false` before `init()` and
544
+ with tracing off at `init()`.
267
545
 
268
546
  ## Requirements
269
547