@brizz/sdk 0.1.29 → 0.1.32

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.
package/README.md CHANGED
@@ -18,6 +18,7 @@ libraries including OpenAI, Anthropic, Vercel AI SDK, and more.
18
18
  - [Supported Libraries](#supported-libraries)
19
19
  - [PII Masking](#pii-masking)
20
20
  - [Session Tracking](#session-tracking)
21
+ - [Mute Messages](#mute-messages)
21
22
  - [Custom Events & Logging](#custom-events--logging)
22
23
  - [Environment Variables](#environment-variables)
23
24
  - [Disable Span Export](#disable-span-export)
@@ -190,12 +191,30 @@ The SDK automatically instruments:
190
191
  - **LangChain** - `langchain` and `@langchain/*` packages
191
192
  - **LlamaIndex** - `llamaindex` package
192
193
  - **AWS Bedrock** - `@aws-sdk/client-bedrock-runtime`
193
- - **Google Vertex AI** - `@google-cloud/vertexai`
194
194
  - **Vector Databases** - Pinecone, Qdrant, ChromaDB
195
- - **HTTP/Fetch** - Automatic network request tracing
195
+
196
+ ### Optional Instrumentations
197
+
198
+ A few instrumentations ship as **optional peer dependencies** so they're only
199
+ pulled in when you need them. Install the matching package(s) to enable them:
200
+
201
+ | To trace | Install |
202
+ | --- | --- |
203
+ | **Vercel AI SDK v7+** (`ai@7`) — required for span capture | `npm install @ai-sdk/otel` |
204
+ | **Google Vertex AI** (`@google-cloud/vertexai`) | `npm install @traceloop/instrumentation-vertexai` |
205
+ | **MCP** (Model Context Protocol) | `npm install @arizeai/openinference-instrumentation-mcp @modelcontextprotocol/sdk` |
206
+
207
+ If a package isn't installed, the SDK keeps working and simply skips that
208
+ instrumentation. On the automatic path the skip is a quiet `debug` log; when you
209
+ opt in explicitly via `instrumentModules`, a missing package is logged at `error`
210
+ so the misconfiguration is visible.
196
211
 
197
212
  ### Vercel AI SDK Integration
198
213
 
214
+ On `ai@7` and newer, also install `@ai-sdk/otel` — v7 moved AI SDK span collection
215
+ into that package, so without it your `generateText` / `streamText` calls produce no
216
+ spans. It isn't needed on `ai@6`.
217
+
199
218
  For Vercel AI SDK instrumentation, you need to enable telemetry in your function calls:
200
219
 
201
220
  ```typescript
@@ -224,6 +243,47 @@ This enables automatic tracing of:
224
243
  - Tool calls and executions
225
244
  - Streaming data
226
245
 
246
+ ### Vercel eve
247
+
248
+ [Vercel `eve`](https://eve.dev) agents emit standard OpenTelemetry GenAI spans, so Brizz ingests
249
+ their traces, message content, and cost as soon as you point eve's exporter at your Brizz endpoint.
250
+ `@brizz/sdk/eve` gives you a one-line `registerOTel` config that reads `BRIZZ_DSN` — it wires the
251
+ exporter and the session grouping that makes each agent run render as a single conversation:
252
+
253
+ ```typescript
254
+ // agent/instrumentation.ts
255
+ import { defineInstrumentation } from 'eve/instrumentation';
256
+ import { registerOTel } from '@vercel/otel';
257
+ import { createEveOtelConfig } from '@brizz/sdk/eve';
258
+
259
+ export default defineInstrumentation({
260
+ setup: ({ agentName }) => registerOTel(createEveOtelConfig({ serviceName: agentName })),
261
+ });
262
+ ```
263
+
264
+ Then set your DSN in the environment — a single pasted credential:
265
+
266
+ ```bash
267
+ BRIZZ_DSN=https://<bearer>@<gateway-host>/<service-name>
268
+ ```
269
+
270
+ `createEveOtelConfig` derives the bearer and endpoint from the DSN and ignores its service segment —
271
+ eve's `agentName` stays the service name. Prefer to compose it yourself? The pieces are exported too:
272
+
273
+ ```typescript
274
+ import { createEveTraceExporter, createEveSessionProcessor } from '@brizz/sdk/eve';
275
+
276
+ registerOTel({
277
+ serviceName: agentName,
278
+ traceExporter: createEveTraceExporter(),
279
+ // 'auto' keeps the default exporter processor.
280
+ spanProcessors: [createEveSessionProcessor(), 'auto'],
281
+ });
282
+ ```
283
+
284
+ `@brizz/sdk/eve` is a standalone, side-effect-free export: it does not initialize the full SDK, so
285
+ it won't duplicate the spans eve already emits.
286
+
227
287
  ## PII Masking
228
288
 
229
289
  Optional masking for span attributes.
@@ -494,6 +554,23 @@ const sessionedProcess = withSessionId(
494
554
  **Note:** The arrow function approach (Option 1) is recommended as it's more explicit, avoids lint
495
555
  warnings, and is less prone to `this` binding issues.
496
556
 
557
+ ## Mute Messages
558
+
559
+ Keep internal or unrelated LLM calls — summarization, title generation, classification, guardrail checks — out of the captured conversation. The call still runs and its telemetry (latency, tokens, cost) is recorded; only the user and/or assistant content is left out.
560
+
561
+ ```typescript
562
+ import { callWithMute, withMute } from '@brizz/sdk';
563
+
564
+ // Hide both sides of an internal call
565
+ await callWithMute({}, () => agent.run('Summarize this conversation for internal logging.'));
566
+
567
+ // Keep the assistant reply, drop the prompt
568
+ await callWithMute({ output: false }, () => agent.run('…a long internal prompt…'));
569
+
570
+ // Pre-wrap a function to reuse the same muting
571
+ const muteTitle = withMute({}, agent.run, agent);
572
+ ```
573
+
497
574
  ## Deployment Environment
498
575
 
499
576
  Optionally specify the deployment environment for better filtering and organization:
@@ -0,0 +1,10 @@
1
+ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
2
+ get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
3
+ }) : x)(function(x) {
4
+ if (typeof require !== "undefined") return require.apply(this, arguments);
5
+ throw Error('Dynamic require of "' + x + '" is not supported');
6
+ });
7
+
8
+ export {
9
+ __require
10
+ };
@@ -0,0 +1,8 @@
1
+ // src/internal/version.ts
2
+ function getSDKVersion() {
3
+ return "0.1.32";
4
+ }
5
+
6
+ export {
7
+ getSDKVersion
8
+ };
@@ -0,0 +1,36 @@
1
+ // src/internal/dsn.ts
2
+ var PLACEHOLDER_SERVICE = "<service-name>";
3
+ var SERVICE_NAME_HEADER = "X-Brizz-Service-Name";
4
+ function parseDSN(dsn, options = {}) {
5
+ let parsed;
6
+ try {
7
+ parsed = new globalThis.URL(dsn);
8
+ } catch {
9
+ return null;
10
+ }
11
+ if (parsed.protocol !== "http:" && parsed.protocol !== "https:" || !parsed.username || !parsed.host) {
12
+ return null;
13
+ }
14
+ const scheme = parsed.protocol === "https:" ? "https" : "http";
15
+ let service;
16
+ try {
17
+ service = decodeURIComponent(parsed.pathname.replace(/^\//, ""));
18
+ } catch {
19
+ return null;
20
+ }
21
+ if (!options.allowPlaceholderService && (service === "" || service === PLACEHOLDER_SERVICE)) {
22
+ return null;
23
+ }
24
+ return {
25
+ scheme,
26
+ host: parsed.host,
27
+ bearer: decodeURIComponent(parsed.username),
28
+ service,
29
+ baseUrl: `${scheme}://${parsed.host}`
30
+ };
31
+ }
32
+
33
+ export {
34
+ SERVICE_NAME_HEADER,
35
+ parseDSN
36
+ };
@@ -0,0 +1,130 @@
1
+ "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
2
+
3
+ var _chunkOZCOXBB7cjs = require('./chunk-OZCOXBB7.cjs');
4
+
5
+ // src/internal/instrumentation/vercel-ai/interrupt.ts
6
+ var _api = require('@opentelemetry/api');
7
+ var INNER_OPERATION_IDS = /* @__PURE__ */ new Set([
8
+ "ai.generateText.doGenerate",
9
+ "ai.streamText.doStream"
10
+ ]);
11
+ function isInnerLLMSpan(span) {
12
+ if (INNER_OPERATION_IDS.has(span.name)) {
13
+ return true;
14
+ }
15
+ const opId = span.attributes["ai.operationId"];
16
+ return typeof opId === "string" && INNER_OPERATION_IDS.has(opId);
17
+ }
18
+ var MAX_PENDING_ENTRIES = 1024;
19
+ var pendingByParentSpanId = /* @__PURE__ */ new Map();
20
+ var needsApprovalToolNames = /* @__PURE__ */ new Set();
21
+ var versionState = { sawActiveSpan: false };
22
+ function setPending(parentSpanId, value) {
23
+ pendingByParentSpanId.set(parentSpanId, value);
24
+ while (pendingByParentSpanId.size > MAX_PENDING_ENTRIES) {
25
+ const oldest = pendingByParentSpanId.keys().next().value;
26
+ if (oldest === void 0) {
27
+ break;
28
+ }
29
+ pendingByParentSpanId.delete(oldest);
30
+ }
31
+ }
32
+ function extractInterruptTools(tools) {
33
+ if (!tools || typeof tools !== "object") {
34
+ return [];
35
+ }
36
+ return Object.entries(tools).filter(
37
+ ([, t]) => !!t && typeof t === "object" && t.needsApproval
38
+ ).map(([name]) => name);
39
+ }
40
+ function parsePromptToolNames(raw) {
41
+ if (!Array.isArray(raw)) {
42
+ return null;
43
+ }
44
+ const names = [];
45
+ for (const element of raw) {
46
+ if (typeof element !== "string") {
47
+ continue;
48
+ }
49
+ try {
50
+ const parsed = JSON.parse(element);
51
+ if (parsed && typeof parsed.name === "string") {
52
+ names.push(parsed.name);
53
+ }
54
+ } catch (e) {
55
+ }
56
+ }
57
+ return names.length > 0 ? names : null;
58
+ }
59
+ function createInterruptIntegration() {
60
+ const onStart = (event) => {
61
+ for (const name of extractInterruptTools(event.tools)) {
62
+ needsApprovalToolNames.add(name);
63
+ }
64
+ };
65
+ const onStepStart = (event) => {
66
+ const span = _api.trace.getActiveSpan();
67
+ if (span) {
68
+ versionState.sawActiveSpan = true;
69
+ }
70
+ const names = extractInterruptTools(event.tools);
71
+ if (names.length === 0) {
72
+ return;
73
+ }
74
+ for (const name of names) {
75
+ needsApprovalToolNames.add(name);
76
+ }
77
+ if (!span) {
78
+ return;
79
+ }
80
+ const value = JSON.stringify(names);
81
+ span.setAttribute(_chunkOZCOXBB7cjs.INTERRUPT_TOOLS, value);
82
+ setPending(span.spanContext().spanId, value);
83
+ };
84
+ return {
85
+ onStart,
86
+ onStepStart
87
+ };
88
+ }
89
+ var InterruptPropagator = class {
90
+ onStart(span, _parentContext) {
91
+ if (!isInnerLLMSpan(span)) {
92
+ return;
93
+ }
94
+ const parentSpanId = _optionalChain([span, 'access', _ => _.parentSpanContext, 'optionalAccess', _2 => _2.spanId]);
95
+ const stashed = parentSpanId && pendingByParentSpanId.get(parentSpanId);
96
+ if (stashed) {
97
+ span.setAttribute(_chunkOZCOXBB7cjs.INTERRUPT_TOOLS, stashed);
98
+ pendingByParentSpanId.delete(parentSpanId);
99
+ return;
100
+ }
101
+ if (versionState.sawActiveSpan || needsApprovalToolNames.size === 0) {
102
+ return;
103
+ }
104
+ const scoped = parsePromptToolNames(span.attributes["ai.prompt.tools"]);
105
+ const names = scoped === null ? [...needsApprovalToolNames] : scoped.filter((n) => needsApprovalToolNames.has(n));
106
+ if (names.length > 0) {
107
+ span.setAttribute(_chunkOZCOXBB7cjs.INTERRUPT_TOOLS, JSON.stringify(names));
108
+ }
109
+ }
110
+ onEnd() {
111
+ }
112
+ async shutdown() {
113
+ }
114
+ async forceFlush() {
115
+ }
116
+ };
117
+ function _resetInterruptState() {
118
+ if (process.env["NODE_ENV"] !== "test") {
119
+ return;
120
+ }
121
+ pendingByParentSpanId.clear();
122
+ needsApprovalToolNames.clear();
123
+ versionState.sawActiveSpan = false;
124
+ }
125
+
126
+
127
+
128
+
129
+
130
+ exports.createInterruptIntegration = createInterruptIntegration; exports.InterruptPropagator = InterruptPropagator; exports._resetInterruptState = _resetInterruptState;