risicare 0.6.0 → 0.8.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 (85) hide show
  1. package/LICENSE +26 -0
  2. package/README.md +308 -61
  3. package/dist/frameworks/instructor.cjs +790 -5
  4. package/dist/frameworks/instructor.cjs.map +1 -1
  5. package/dist/frameworks/instructor.js +780 -5
  6. package/dist/frameworks/instructor.js.map +1 -1
  7. package/dist/frameworks/langchain.cjs +790 -5
  8. package/dist/frameworks/langchain.cjs.map +1 -1
  9. package/dist/frameworks/langchain.d.cts +3 -2
  10. package/dist/frameworks/langchain.d.ts +3 -2
  11. package/dist/frameworks/langchain.js +780 -5
  12. package/dist/frameworks/langchain.js.map +1 -1
  13. package/dist/frameworks/langgraph.cjs +790 -5
  14. package/dist/frameworks/langgraph.cjs.map +1 -1
  15. package/dist/frameworks/langgraph.js +780 -5
  16. package/dist/frameworks/langgraph.js.map +1 -1
  17. package/dist/frameworks/llamaindex.cjs +801 -5
  18. package/dist/frameworks/llamaindex.cjs.map +1 -1
  19. package/dist/frameworks/llamaindex.d.cts +3 -2
  20. package/dist/frameworks/llamaindex.d.ts +3 -2
  21. package/dist/frameworks/llamaindex.js +791 -5
  22. package/dist/frameworks/llamaindex.js.map +1 -1
  23. package/dist/index.cjs +1259 -175
  24. package/dist/index.cjs.map +1 -1
  25. package/dist/index.d.cts +245 -39
  26. package/dist/index.d.ts +245 -39
  27. package/dist/index.js +1259 -175
  28. package/dist/index.js.map +1 -1
  29. package/dist/providers/anthropic/index.cjs +1601 -36
  30. package/dist/providers/anthropic/index.cjs.map +1 -1
  31. package/dist/providers/anthropic/index.d.cts +3 -1
  32. package/dist/providers/anthropic/index.d.ts +3 -1
  33. package/dist/providers/anthropic/index.js +1591 -36
  34. package/dist/providers/anthropic/index.js.map +1 -1
  35. package/dist/providers/bedrock/index.cjs +850 -32
  36. package/dist/providers/bedrock/index.cjs.map +1 -1
  37. package/dist/providers/bedrock/index.js +840 -32
  38. package/dist/providers/bedrock/index.js.map +1 -1
  39. package/dist/providers/cerebras/index.cjs +1534 -30
  40. package/dist/providers/cerebras/index.cjs.map +1 -1
  41. package/dist/providers/cerebras/index.js +1524 -30
  42. package/dist/providers/cerebras/index.js.map +1 -1
  43. package/dist/providers/cohere/index.cjs +1557 -102
  44. package/dist/providers/cohere/index.cjs.map +1 -1
  45. package/dist/providers/cohere/index.js +1547 -102
  46. package/dist/providers/cohere/index.js.map +1 -1
  47. package/dist/providers/google/index.cjs +1562 -60
  48. package/dist/providers/google/index.cjs.map +1 -1
  49. package/dist/providers/google/index.js +1552 -60
  50. package/dist/providers/google/index.js.map +1 -1
  51. package/dist/providers/groq/index.cjs +1534 -30
  52. package/dist/providers/groq/index.cjs.map +1 -1
  53. package/dist/providers/groq/index.js +1524 -30
  54. package/dist/providers/groq/index.js.map +1 -1
  55. package/dist/providers/huggingface/index.cjs +1622 -25
  56. package/dist/providers/huggingface/index.cjs.map +1 -1
  57. package/dist/providers/huggingface/index.d.cts +0 -9
  58. package/dist/providers/huggingface/index.d.ts +0 -9
  59. package/dist/providers/huggingface/index.js +1612 -25
  60. package/dist/providers/huggingface/index.js.map +1 -1
  61. package/dist/providers/mistral/index.cjs +1535 -54
  62. package/dist/providers/mistral/index.cjs.map +1 -1
  63. package/dist/providers/mistral/index.js +1525 -54
  64. package/dist/providers/mistral/index.js.map +1 -1
  65. package/dist/providers/ollama/index.cjs +1559 -93
  66. package/dist/providers/ollama/index.cjs.map +1 -1
  67. package/dist/providers/ollama/index.js +1549 -93
  68. package/dist/providers/ollama/index.js.map +1 -1
  69. package/dist/providers/openai/index.cjs +1598 -61
  70. package/dist/providers/openai/index.cjs.map +1 -1
  71. package/dist/providers/openai/index.d.cts +6 -1
  72. package/dist/providers/openai/index.d.ts +6 -1
  73. package/dist/providers/openai/index.js +1588 -61
  74. package/dist/providers/openai/index.js.map +1 -1
  75. package/dist/providers/together/index.cjs +1534 -30
  76. package/dist/providers/together/index.cjs.map +1 -1
  77. package/dist/providers/together/index.js +1524 -30
  78. package/dist/providers/together/index.js.map +1 -1
  79. package/dist/providers/vercel-ai/index.cjs +1288 -17
  80. package/dist/providers/vercel-ai/index.cjs.map +1 -1
  81. package/dist/providers/vercel-ai/index.d.cts +0 -6
  82. package/dist/providers/vercel-ai/index.d.ts +0 -6
  83. package/dist/providers/vercel-ai/index.js +1278 -17
  84. package/dist/providers/vercel-ai/index.js.map +1 -1
  85. package/package.json +5 -12
package/LICENSE ADDED
@@ -0,0 +1,26 @@
1
+ Copyright (c) 2026 Conscience Labs Pvt. Ltd. All rights reserved.
2
+ Contact: info@consciencelabs.ai
3
+
4
+ COMMERCIAL END USER LICENSE AGREEMENT (EULA)
5
+
6
+ This software ("SDK") is the proprietary property of Conscience Labs Pvt. Ltd.
7
+ Your use of this SDK is strictly governed by the commercial subscription agreement
8
+ and terms of service entered into between your organization and Conscience Labs Pvt. Ltd.
9
+
10
+ LICENSE GRANT & RESTRICTIONS:
11
+ 1. Subject to an active, paid subscription, you are granted a limited, non-exclusive,
12
+ non-transferable license to integrate this SDK into your applications solely to
13
+ utilize the AI Observability services hosted by Conscience Labs Pvt. Ltd.
14
+ 2. You shall not modify, adapt, alter, translate, or create derivative works from this SDK.
15
+ 3. You shall not reverse engineer, decompile, disassemble, or otherwise attempt to
16
+ derive the source code of this SDK.
17
+ 4. You shall not distribute, sublicense, lease, rent, or loan this SDK to any third
18
+ party as a standalone tool or product.
19
+
20
+ WARRANTY DISCLAIMER:
21
+ THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR
22
+ IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
23
+ FITNESS FOR A PARTICULAR PURPOSE.
24
+
25
+ For licensing inquiries, custom enterprise terms, or support, please contact:
26
+ info@consciencelabs.ai
package/README.md CHANGED
@@ -5,9 +5,11 @@ AI agent observability and error diagnosis for Node.js and TypeScript.
5
5
  [![npm version](https://img.shields.io/npm/v/risicare.svg)](https://www.npmjs.com/package/risicare)
6
6
  [![npm downloads](https://img.shields.io/npm/dm/risicare.svg)](https://www.npmjs.com/package/risicare)
7
7
  [![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue.svg)](https://www.npmjs.com/package/risicare)
8
- [![License: MIT](https://img.shields.io/npm/l/risicare.svg)](https://opensource.org/licenses/MIT)
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://app.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,72 @@ 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 and no
88
+ explicit setting, tracing is off (see "A note on running without an API key").
89
+
90
+ ## Imports
91
+
92
+ The package has no default export. Use named imports or a namespace import.
93
+ `Span` and `Tracer` are types only: import them with `import type`.
94
+
95
+ ```typescript
96
+ import { init, agent } from 'risicare';
97
+ import * as risicare from 'risicare';
98
+ import type { Span, Tracer } from 'risicare';
99
+ ```
47
100
 
48
101
  ## Prompt content is NOT captured by default
49
102
 
50
- **Since 0.5.1, `traceContent` defaults to `false`.** Your prompts and completions
103
+ **`traceContent` defaults to `false`** (since 0.5.2, the first published version with this default). Your prompts and completions
51
104
  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
105
+ errors, and any attributes you set — is captured as normal, so the
53
106
  dashboard, cost tracking and error diagnosis all work unchanged.
54
107
 
55
108
  To send prompt and completion text as well, opt in:
@@ -59,6 +112,25 @@ init({ apiKey: 'rsk-...', traceContent: true });
59
112
  // or set RISICARE_TRACE_CONTENT=true
60
113
  ```
61
114
 
115
+ **Which providers capture text.** With `traceContent: true`:
116
+
117
+ - `patchOpenAI` and `patchAnthropic` capture the prompt and the completion text.
118
+ They write the first 10 messages to `gen_ai.prompt.N.role` and
119
+ `gen_ai.prompt.N.content`. They write the completion to
120
+ `gen_ai.completion.content`. `patchAnthropic` also writes a string `system`
121
+ prompt to `gen_ai.system_prompt`. The SDK cuts each text at 10,000 characters
122
+ (Unicode code points). It cuts the system prompt at 5,000. `patchOpenAI` also
123
+ captures text for a client of an OpenAI-compatible host.
124
+ - For a streamed call, they capture the prompt only, not the completion.
125
+ - `patchGoogleAI`, `patchMistral`, `patchGroq`, `patchCohere`, `patchTogether`,
126
+ `patchOllama`, `patchHuggingFace`, `patchCerebras`, `patchBedrock` and
127
+ `patchVercelAI` capture no prompt or completion text.
128
+
129
+ **Error text is not covered by this switch.** The error message from a
130
+ provider can contain your prompt text. For example, a 400 error can repeat
131
+ part of the prompt. The SDK sends error messages also when `traceContent` is
132
+ off, because error diagnosis uses them.
133
+
62
134
  **Upgrading from 0.5.0 or earlier?** This is a behaviour change: content that
63
135
  used to be sent is no longer sent unless you opt in. In those versions the flag
64
136
  also did not work for content you set by hand — `traceContent: false` did not
@@ -69,9 +141,13 @@ When capture is off, content-bearing attributes are **replaced** with
69
141
  `<risicare:content-omitted>` rather than removed, so "no prompt was sent" stays
70
142
  distinguishable from "capture is off".
71
143
 
72
- If you want content captured but redacted first, use the `mask` hook — it is
73
- independent of this switch and runs on every content-bearing field before
74
- export:
144
+ Since 0.7.0, the gate also covers the OpenTelemetry GenAI, OpenInference and
145
+ CrewAI content keys, for example `input.value`, `output.value`,
146
+ `gen_ai.input.messages` and `gen_ai.output.messages`.
147
+
148
+ If you want content captured but redacted first, use the `mask` hook. It runs
149
+ on every content-bearing field of every span before export, for every
150
+ exporter:
75
151
 
76
152
  ```typescript
77
153
  init({ apiKey: 'rsk-...', traceContent: true, mask: (key, value) => value });
@@ -83,31 +159,91 @@ init({ apiKey: 'rsk-...', traceContent: true, mask: (key, value) => value });
83
159
  - **12 LLM providers** — OpenAI, Anthropic, Google, Mistral, Groq, Cohere, Together, Ollama, HuggingFace, Cerebras, Bedrock, Vercel AI
84
160
  - **4 framework integrations** — LangChain, LangGraph, Instructor, LlamaIndex
85
161
  - **Error Diagnosis (beta)** — LLM-powered root cause analysis with fix suggestions; auto-apply not yet wired (see "Error Diagnosis" section below)
86
- - **Evaluation scores** — Rate agent quality with `score()` and 13 built-in scorers
87
- - **Streaming support** — `tracedStream()` for async iterator tracing
88
- - **Context propagation** — Automatic across `async/await`, `Promise`, `setTimeout`, `EventEmitter`
162
+ - **Evaluation scores** — Rate agent quality with `score()`
163
+ - **Streaming** — `tracedStream()` traces an async iterator (see "Streaming" below)
164
+ - **Context propagation** — Automatic across `async/await`, `Promise` and `setTimeout`. An `EventEmitter` listener runs in the context of the `emit()` call
89
165
  - **Zero runtime dependencies** — No bloat in your node_modules
90
166
  - **Dual CJS/ESM** — Works with `require()` and `import`
91
167
  - **Full TypeScript** — Strict types and IntelliSense out of the box
92
- - **Non-blocking** — Async batch export with circuit breaker and retry
93
- - **Zero overhead when disabled** — Frozen NOOP_SPAN singleton, no allocations
168
+ - **Background export** — Async batch export with circuit breaker and retry
169
+ - **Low cost when disabled** — a frozen no-op span
94
170
 
95
171
  ## LLM Providers
96
172
 
97
173
  ```typescript
174
+ import OpenAI from 'openai';
98
175
  import { patchOpenAI } from 'risicare/openai';
99
176
  import { patchAnthropic } from 'risicare/anthropic';
100
- import { patchGoogle } from 'risicare/google';
177
+ import { patchGoogleAI } from 'risicare/google';
101
178
  // ... and 9 more
102
179
 
103
180
  const openai = patchOpenAI(new OpenAI());
104
- // Every call is now traced — model, tokens, latency, cost
181
+ // chat.completions.create and embeddings.create are now traced
105
182
  ```
106
183
 
107
184
  All 12 providers:
108
185
 
109
186
  `openai` · `anthropic` · `google` · `mistral` · `groq` · `cohere` · `together` · `ollama` · `huggingface` · `cerebras` · `bedrock` · `vercel-ai`
110
187
 
188
+ `patchOpenAI` also traces an OpenAI-compatible host (`baseURL`). It sets the
189
+ provider name (`gen_ai.system`) from the host for DeepSeek, Together, Groq, xAI,
190
+ Fireworks, Baseten, Novita and BytePlus (`api.byteplus.com` and
191
+ `ark.cn-beijing.byteplus.com`). Any other host is named `openai`.
192
+
193
+ ### Streaming
194
+
195
+ The caller gets the provider's own promise and stream objects. The SDK counts
196
+ only the chunks that the caller reads. It does not read ahead. The span of a
197
+ stream ends once, when the stream ends, with `stream.end_reason`:
198
+
199
+ | `stream.end_reason` | When | Status |
200
+ |---|---|---|
201
+ | `done` | The caller read the stream to its end. | ok |
202
+ | `return` | The caller stopped early (`break`, `return()`). | ok |
203
+ | `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 |
204
+ | `error` | An error reached the caller. The span records it. | error |
205
+ | `handoff` | The caller took the data another way: `tee()`, `getReader()`, `toReadableStream()`, `pipeTo()`, `pipeThrough()` or `asResponse()`. | ok |
206
+ | `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 |
207
+ | `shutdown` | `shutdown()` ends every stream span that is still open, and exports it. | ok |
208
+
209
+ The span has `stream.chunk_count`: the number of chunks that the caller read.
210
+ It has the token counts that the chunks gave: the usage chunk (OpenAI needs
211
+ `stream_options: { include_usage: true }`; also Groq, Together, Cerebras,
212
+ Hugging Face), `message_start` and `message_delta` (Anthropic), the last
213
+ `usageMetadata` (Google), the chunk `usage` (Mistral), the last chunk with
214
+ `done` (Ollama), `message-end` (Cohere). A count that the stream did not give
215
+ stays empty. The span does not capture the streamed completion text.
216
+
217
+ Call `shutdown()` before the process stops. A span that is still open is lost
218
+ if the process stops without it.
219
+
220
+ Limits:
221
+
222
+ - Cohere: `stream.controller.abort()` does not stop a Cohere stream, so it is
223
+ not an abort. The request option `abortSignal` stops it, and is an abort.
224
+ - Google, the request `signal`: the Google SDK changes the abort into a
225
+ `GoogleGenerativeAIError`. A read after the abort ends the span as `error`,
226
+ not `abort`. An abort with no read after it ends as `garbage` or
227
+ `shutdown`, status ok.
228
+ - Mistral, the request `signal` (`fetchOptions.signal`): a read after the
229
+ abort gets an `AbortError`, and the span ends as `abort`. The SDK cannot see
230
+ this signal, so an abort with no read after it ends as `garbage` or
231
+ `shutdown`, status ok.
232
+ - Google `result.response`: the Google SDK gives the aggregated response also
233
+ when nobody reads `result.stream`. If the caller never takes `result.stream`,
234
+ the span ends as `done` when `result.response` settles, with the tokens of
235
+ the aggregated response and `stream.chunk_count` = 0 (`error` if it
236
+ rejects). If the caller takes `result.stream`, the stream decides the end.
237
+ A stream that the caller takes after the span ended is not counted.
238
+ - `handoff`: the SDK does not see the chunks after the handoff, so the chunk
239
+ and token counts cover only the chunks read before it.
240
+ - Bedrock (`ConverseStreamCommand`): the SDK does not read the stream. The
241
+ span ends when `send()` returns. It has no token counts.
242
+ - Vercel AI (`tracedStreamText`): the span ends through the `streamText`
243
+ callbacks: `onFinish` (`done`, with the usage), `onAbort` (`abort`) or an
244
+ error chunk (`error`). With no callback, it ends as `garbage` or at
245
+ `shutdown()`.
246
+
111
247
  ## Framework Integrations
112
248
 
113
249
  ```typescript
@@ -126,13 +262,24 @@ const client = patchInstructor(instructor);
126
262
 
127
263
  // LlamaIndex
128
264
  import { RisicareLlamaIndexHandler } from 'risicare/llamaindex';
265
+ const liHandler = new RisicareLlamaIndexHandler();
266
+ for (const name of RisicareLlamaIndexHandler.EVENT_NAMES) {
267
+ Settings.callbackManager.on(name, (e) => liHandler.onEvent(e)); // Settings from 'llamaindex'
268
+ }
129
269
  ```
130
270
 
271
+ The LangChain and LlamaIndex handlers give one LLM span for each model call.
272
+ Use one handler: two handler instances on one call (for example one in the model
273
+ constructor and one in `invoke`) give two LLM spans. LangChain's `ChatOpenAI` and LlamaIndex's `OpenAI` make their own OpenAI client.
274
+ `patchOpenAI` changes only the client that you give to it, so it does not add a
275
+ second span to these calls. You need `withSuppression()` only when the same call
276
+ also goes through a client that you patched.
277
+
131
278
  ## Core API
132
279
 
133
280
  ```typescript
134
281
  import {
135
- init, shutdown, // Lifecycle
282
+ init, flush, shutdown, // Lifecycle
136
283
  agent, session, // Identity & grouping
137
284
  traceThink, traceDecide, traceAct, // Decision phases
138
285
  reportError, score, // Diagnosis & evaluation
@@ -140,41 +287,114 @@ import {
140
287
  } from 'risicare';
141
288
 
142
289
  init({ apiKey, endpoint }) // Initialize SDK
143
- agent({ name }, fn) // Wrap function with agent identity
144
- session({ sessionId, userId }, fn) // Group traces into user sessions
145
- // These are WRAPPER FACTORIES: they return a function you then call.
146
- await traceThink('analyze', async () => {...})() // note the trailing ()
147
- await traceDecide('choose', async () => {...})()
148
- await traceAct('execute', async () => {...})()
290
+ // agent(), session() and the trace* functions are WRAPPER FACTORIES:
291
+ // they return a function that you then call. Note the trailing ().
292
+ await agent({ name }, fn)() // Run fn with agent identity
293
+ await session({ sessionId, userId }, fn)() // Run fn in a user session
294
+ await traceThink('analyze', fn)()
295
+ await traceDecide('choose', fn)()
296
+ await traceAct('execute', fn)()
149
297
  reportError(error) // Report caught errors for diagnosis
150
298
  score(traceId, 'quality', 0.92) // Record evaluation score [0.0-1.0]
151
299
  tracedStream(asyncIterable, 'stream') // Trace async iterators
152
- await shutdown() // Flush pending spans and close
300
+ await flush(5000) // Wait for delivery; false when a span or a score was lost
301
+ await shutdown(5000) // Deliver what it can in the time, then stop
153
302
  ```
154
303
 
304
+ ## Delivery: flush, shutdown and metrics
305
+
306
+ - `await flush(timeoutMs?)` waits for the queued spans and the pending scores
307
+ (default 5000 ms). It returns `true` only when nothing is queued, no batch is
308
+ in flight, and no span was dropped or rejected and no score failed since the
309
+ previous `flush()` returned (or since `init()`, for the first call). A loss
310
+ makes the next `flush()` return `false` one time, also when it occurred while
311
+ no flush ran. It returns `false` at its deadline. `flush()` only waits. It
312
+ does not stop a request that is already sent. With more than one exporter,
313
+ a batch counts as delivered when the first exporter that succeeds takes it:
314
+ `flush()` can then return `true` while another exporter refused the batch.
315
+ - `await shutdown(timeoutMs?)` is the call that ends a process in a fixed time
316
+ (default 5000 ms). At the deadline it stops the export in flight. It counts
317
+ the spans that it did not deliver as `shutdown_residue`, with one WARNING.
318
+ - A timeout that is not a finite number means 5000 ms.
319
+ - `getMetrics()` gives `exportedSpans` (spans that the backend accepted),
320
+ `rejectedSpans`, `droppedSpans`, `droppedSpansByReason` (`queue_full`,
321
+ `transport_refused`, `shutdown_residue`, `unacknowledged`), `failedExports`,
322
+ `failedScores`, the queue numbers and `sdkState`. `unacknowledged` counts
323
+ spans that were sent, or that could not be serialized, and that the
324
+ backend's answer did not account for.
325
+ - `score()` stops its request after 2000 ms and does not follow a redirect. A
326
+ status of 300 or more, an error or a timeout adds 1 to `failedScores`. The
327
+ first failure writes one WARNING at once. Failures in the next 10 seconds
328
+ are counted, and the next WARNING gives their number.
329
+ At most 50 score requests run at one time. Up to 1,000 scores wait for a free
330
+ slot, with no timer: the 2000 ms bound starts when the request starts. A score
331
+ that comes when 1,000 already wait fails at once and is counted. When the bound
332
+ of `flush()` or `shutdown()` ends, the scores that still wait fail and are not
333
+ sent.
334
+
155
335
  ## Error Diagnosis
156
336
 
157
- > **Beta status (2026-05):** detect → diagnose → suggest is shipped and runs against
158
- > Together.AI Llama-3.3-70B with a circuit-breaker / template-only fallback. Suggested
159
- > fixes land in your dashboard as `status=draft` for human review. Automatic
160
- > deployment, A/B rollout, and learning-from-outcomes (stages 4–6 in our docs) are
161
- > in development and not yet wired in production. Treat this as **AI-assisted
162
- > error diagnosis** today; auto-apply will follow.
337
+ > **Beta.** The Risicare service detects an error, diagnoses it and suggests a
338
+ > fix. The diagnosis runs on the service, with Together.AI Llama-3.3-70B.
339
+ > Suggested fixes land in your dashboard as `status=draft` for human review.
340
+ > Automatic deployment, A/B rollout and learning from outcomes are not
341
+ > available. Treat this as **AI-assisted error diagnosis**.
163
342
 
164
- When your agent fails, Risicare:
343
+ When your agent fails:
165
344
 
166
- 1. **Classifies** the error (154 codes across TOOL, MEMORY, REASONING, OUTPUT, etc.)
167
- 2. **Diagnoses** the root cause using AI analysis
168
- 3. **Generates** a fix suggestion you can review in the dashboard and apply manually
345
+ 1. The SDK records the error on the span and gives it an error code
346
+ (`error.code`). The taxonomy has 154 codes in 10 modules (TOOL, MEMORY,
347
+ REASONING, OUTPUT and others). The SDK's own rules give 18 of them. An
348
+ error that no rule matches gets a 19th, `TOOL.EXECUTION.CRASHED`.
349
+ 2. The Risicare service diagnoses the root cause.
350
+ 3. The service writes a fix suggestion that you can review in the dashboard
351
+ and apply manually.
169
352
 
170
353
  ```typescript
171
354
  try {
172
355
  await myAgent(input);
173
356
  } catch (error) {
174
- reportError(error); // Triggers diagnosis pipeline; fix lands as draft for review
357
+ reportError(error); // Records the error for diagnosis; the fix lands as a draft for review
175
358
  }
176
359
  ```
177
360
 
361
+ ## Fix application is off by default
362
+
363
+ **Since 0.7.0, FixRuntime starts only when you opt in.** During the beta, the
364
+ Risicare service does not give fixes to customer projects, so FixRuntime has no
365
+ effect for them. Through 0.6.0, FixRuntime started automatically when you set an
366
+ API key.
367
+
368
+ When FixRuntime is on, it reads the active fixes for your project from Risicare.
369
+ The fix interceptor enforces guard fixes on these paths only: `interceptCall` and
370
+ `interceptResponse` on the runtime, and the input guards of the patched OpenAI
371
+ chat call. The guards do not run when a framework integration suppresses provider
372
+ instrumentation. A failed input guard throws `GuardRejectedError` before the LLM
373
+ call. The input guards check messages that have text content: a string, or the
374
+ `text` parts of a list. A guard pattern that is not usable (not a string, empty,
375
+ longer than 500 characters, or JavaScript cannot use it) rejects the call. The
376
+ provider path does not apply prompt, parameter or fallback fixes.
377
+
378
+ Each SDK uses its own regular-expression engine. These constructs can give a
379
+ different result in JavaScript and Python: `$` before a final newline, Unicode
380
+ case folding, `\d` and `\w` on non-ASCII text, and a `]` first in a class.
381
+ JavaScript rejects a pattern that contains `\N{...}` or `\U........`. A pattern
382
+ has no time bound: a pattern with nested repeats can take a very long time on a
383
+ long input.
384
+
385
+ When FixRuntime is off, the SDK does not request `/fixes/active`, and it does
386
+ not change your LLM calls. Tracing, error reporting and scores are not affected.
387
+
388
+ To opt in:
389
+
390
+ ```typescript
391
+ init({ apiKey: 'rsk-...', fixRuntime: true });
392
+ // or set RISICARE_FIX_RUNTIME=true
393
+ ```
394
+
395
+ When FixRuntime is on, the SDK requests the active fixes during `init()` and
396
+ then every 60 seconds. The `fixRuntime` option has priority over the environment variable.
397
+
178
398
  ## Decision Phases
179
399
 
180
400
  Structure your traces to see how your agent thinks, decides, and acts:
@@ -201,39 +421,63 @@ const myAgent = agent({ name: 'planner', role: 'coordinator' }, async (input) =>
201
421
 
202
422
  ## Sessions
203
423
 
204
- Group traces from the same user conversation:
424
+ Group traces from the same user conversation. `withSession` runs the callback
425
+ now and returns its result:
205
426
 
206
427
  ```typescript
207
- const result = await session(
428
+ import { withSession } from 'risicare';
429
+
430
+ const result = await withSession(
208
431
  { sessionId: 'sess-abc123', userId: 'user-456' },
209
432
  () => myAgent(userMessage)
210
433
  );
211
434
  ```
212
435
 
436
+ `session()` does not run the callback. It returns a wrapped function, which you
437
+ call later, for example once for each request.
438
+
213
439
  ## Known limitation — span loss during a backend outage
214
440
 
215
- The SDK does **not** currently survive a sustained outage of the Risicare
216
- backend, and the loss is silent to your application (it is warned about, but
217
- nothing throws and `flush()` will not fail your request path).
441
+ The SDK does **not** keep spans through a long outage of the Risicare backend.
442
+ Nothing throws in your application. The SDK writes a WARNING, `flush()`
443
+ returns `false`, and `getMetrics()` counts the lost spans in
444
+ `droppedSpansByReason.transport_refused`.
218
445
 
219
446
  The HTTP exporter opens a circuit breaker after **5 consecutive failed export
220
- calls** and holds it open for **60 seconds**, returning failure immediately
221
- without touching the network. Queued spans get 3 re-queue attempts, which against
222
- an open breaker resolve in microseconds — so they are dropped — and for the
223
- remainder of the cooldown the SDK will not retry even after your backend is
224
- healthy again.
225
-
226
- Measured, for a 1,000-span cohort emitted during the outage: **4 s → all
227
- delivered; 5 s → half; 6 s and beyond → none.** The thresholds are counted in
228
- **failed calls, not seconds** — where the 5th consecutive failure falls in
229
- wall-clock time depends on your span rate and on how fast your endpoint fails.
230
-
231
- Nothing is lost on a clean `shutdown()`, and short blips that stay under the
232
- 5-failure threshold are fully survivable. Tracked as `F-SDKBLIP-001`.
447
+ calls** and holds it open for **60 seconds**. While it is open, an export
448
+ returns failure at once and does not use the network. A batch that fails is
449
+ put back in the queue at most 3 times. Against an open breaker these 3
450
+ attempts fail at once, so the spans are dropped. For the rest of the cooldown
451
+ the SDK does not send, also when your backend is healthy again.
452
+
453
+ The thresholds count **failed calls, not seconds**. When the 5th consecutive
454
+ failure occurs depends on your span rate and on how fast your endpoint fails.
455
+ A short failure that stays under 5 consecutive failed calls does not open the
456
+ breaker. Tracked as `F-SDKBLIP-001`.
457
+
458
+ One export call sends a batch at most 3 times. A 401 or 403 answer is sent
459
+ once in each export call: the endpoint refused the API key, and the same key
460
+ gets the same answer. At the first failed export of an outage (at most once in
461
+ 5 minutes), the SDK writes the WARNING "spans are NOT reaching ...". It gives
462
+ the HTTP status of the last answer, or the error code when there was no answer.
463
+ For a 401 or 403 it tells you to check the API key. When the kind of failure
464
+ changes in one outage (for example a 401, then no answer), the SDK writes one more
465
+ WARNING. An endpoint URL with credentials (a user name or a password before the
466
+ host) is not supported: `fetch` does not send a request to it.
467
+
468
+ The SDK removes its API key from each text that it logs: in any case of letters,
469
+ and also when the key is percent-encoded. An endpoint is logged without its user
470
+ name, password and query. A secret that you put in another place of a URL (for
471
+ example in its path) is logged as you gave it.
233
472
 
234
473
  ## A note on running without an API key
235
474
 
236
- If tracing is enabled but no API key is configured, the SDK emits a one-time
475
+ If you give no API key, or an empty one, tracing is off. This applies when
476
+ you do not set tracing explicitly. The SDK then writes one WARNING to stderr.
477
+ The SDK sends no span.
478
+
479
+ If tracing is enabled explicitly (`enabled: true` or `RISICARE_TRACING=true`)
480
+ but no API key is configured, the SDK emits a one-time
237
481
  `console.warn` and **drops** the spans. It deliberately does **not** print span
238
482
  payloads to your console: the SDK performs no redaction of its own, so printing
239
483
  would put prompts, completions and anything else in your attributes onto your
@@ -257,7 +501,6 @@ explicitly.
257
501
 
258
502
  ## Support
259
503
 
260
- - **Bug reports**: [github.com/Conscience-AI-Labs/risicare-ops/issues](https://github.com/Conscience-AI-Labs/risicare-ops/issues)
261
504
  - **Email**: support@risicare.ai
262
505
  - **Docs**: [risicare.ai/docs](https://risicare.ai/docs)
263
506
 
@@ -266,4 +509,8 @@ SDK or platform issue — fast feedback shapes GA.
266
509
 
267
510
  ## License
268
511
 
269
- [MIT](LICENSE)
512
+ **Proprietary. You need a commercial licence.** See [LICENSE](LICENSE).
513
+
514
+ Conscience Labs Pvt. Ltd. owns this SDK. You need an active, paid
515
+ subscription to use it. You may not change it, make derivative works from
516
+ it, reverse engineer it, or redistribute it. Contact <info@consciencelabs.ai>.