@brizz/sdk 0.1.7 → 0.1.9

package/README.md

@@ -259,8 +259,60 @@ API keys, crypto addresses, IPs, and more.
 
 Group related operations under a session context:
 
+### Session Context Manager (Recommended)
+
+The `startSession` function creates a session span and provides a `Session` object:
+
+```typescript
+import { startSession } from '@brizz/sdk';
+
+// Basic usage - all LLM calls within the callback are automatically linked
+const result = await startSession('session-123', async (session) => {
+  // Add custom properties (optional)
+  session.updateProperties({ userId: 'user-456', model: 'gpt-4' });
+
+  const response = await openai.chat.completions.create({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: userQuery }],
+  });
+
+  return response;
+});
+```
+
+**Session Methods:**
+- `session.updateProperties({ key: value })` - Add custom properties to the session span
+- `session.setInput(text)` - (Optional) Manually track input text
+- `session.setOutput(text)` - (Optional) Manually track output text
+
+**When to use manual input/output tracking:**
+
+In most cases, Brizz automatically captures inputs and outputs from your LLM calls. Use `setInput`/`setOutput` for special scenarios:
+
+- **Multi-agent flows**: Track only user-facing input/output, not intermediate agent communications
+- **Structured data extraction**: Track a specific field from complex JSON requests
+- **Post-processing**: Track transformed responses before returning to the user
+
+```typescript
+await startSession('session-456', async (session) => {
+  // Extract just the query from a structured request
+  const requestData = { query: "What's the weather?", context: {...} };
+  session.setInput(requestData.query);
+
+  const response = await openai.chat.completions.create({...});
+
+  // Extract answer from structured response
+  const responseJson = JSON.parse(response.choices[0].message.content);
+  session.setOutput(responseJson.answer);
+
+  return responseJson;
+});
+```
+
 ### Function Wrapper Pattern
 
+For simpler cases where you just need to tag traces with a session ID:
+
 ```typescript
 import { withSessionId, emitEvent } from '@brizz/sdk';
 

package/dist/index.cjs

@@ -33,6 +33,7 @@ __export(src_exports, {
   Brizz: () => Brizz,
   DEFAULT_PII_PATTERNS: () => DEFAULT_PII_PATTERNS,
   LogLevel: () => LogLevel,
+  Session: () => Session,
   SeverityNumber: () => import_api_logs2.SeverityNumber,
   callWithProperties: () => callWithProperties,
   callWithSessionId: () => callWithSessionId,
@@ -48,6 +49,7 @@ __export(src_exports, {
   maskAttributes: () => maskAttributes,
   maskValue: () => maskValue,
   setLogLevel: () => setLogLevel,
+  startSession: () => startSession,
   withProperties: () => withProperties,
   withSessionId: () => withSessionId
 });
@@ -480,7 +482,7 @@ var import_sdk_logs2 = require("@opentelemetry/sdk-logs");
 
 // src/internal/version.ts
 function getSDKVersion() {
-  return "0.1.7";
+  return "0.1.9";
 }
 
 // src/internal/log/processors/log-processor.ts
@@ -1115,6 +1117,9 @@ var BRIZZ = "brizz";
 var PROPERTIES = "properties";
 var SESSION_ID = "session.id";
 var PROPERTIES_CONTEXT_KEY = (0, import_api2.createContextKey)(PROPERTIES);
+var SESSION_INPUT = "brizz.session.input";
+var SESSION_OUTPUT = "brizz.session.output";
+var SESSION_SPAN_NAME = "brizz.start_session";
 
 // src/internal/log/processors/log-processor.ts
 var DEFAULT_LOG_MASKING_RULES = [
@@ -1695,6 +1700,79 @@ function withSessionId(sessionId, fn, thisArg) {
 function callWithSessionId(sessionId, fn, thisArg, ...args) {
   return callWithProperties({ [SESSION_ID]: sessionId }, fn, thisArg, ...args);
 }
+var Session = class {
+  sessionId;
+  span;
+  inputs = [];
+  outputs = [];
+  constructor(sessionId, span) {
+    this.sessionId = sessionId;
+    this.span = span;
+  }
+  /**
+   * (Optional) Append text to session input tracking.
+   * Use when you need to track specific input data that differs from what's sent to the LLM.
+   * Multiple calls accumulate in an array.
+   *
+   * @param text - Text to append to session input
+   */
+  setInput(text) {
+    this.inputs.push(text);
+    this.span.setAttribute(SESSION_INPUT, JSON.stringify(this.inputs));
+  }
+  /**
+   * (Optional) Append text to session output tracking.
+   * Use when you need to track specific output data that differs from what's received from the LLM.
+   * Multiple calls accumulate in an array.
+   *
+   * @param text - Text to append to session output
+   */
+  setOutput(text) {
+    this.outputs.push(text);
+    this.span.setAttribute(SESSION_OUTPUT, JSON.stringify(this.outputs));
+  }
+  /**
+   * Update custom properties on the session span.
+   * Properties are prefixed with 'brizz.'.
+   *
+   * @param properties - Key-value properties to set on the session
+   */
+  updateProperties(properties) {
+    for (const [key, value] of Object.entries(properties)) {
+      this.span.setAttribute(`${BRIZZ}.${key}`, value);
+    }
+  }
+};
+function startSession(sessionId, callback) {
+  const tracer = import_api5.trace.getTracer("@brizz/sdk");
+  return tracer.startActiveSpan(SESSION_SPAN_NAME, (span) => {
+    span.setAttribute(`${BRIZZ}.${SESSION_ID}`, sessionId);
+    const session = new Session(sessionId, span);
+    return callWithProperties({ [SESSION_ID]: sessionId }, () => {
+      try {
+        const result = callback(session);
+        if (result && typeof result.then === "function") {
+          return result.then((value) => {
+            span.end();
+            return value;
+          }).catch((error) => {
+            span.recordException(error);
+            span.setStatus({ code: import_api5.SpanStatusCode.ERROR });
+            span.end();
+            throw error;
+          });
+        }
+        span.end();
+        return result;
+      } catch (error) {
+        span.recordException(error);
+        span.setStatus({ code: import_api5.SpanStatusCode.ERROR });
+        span.end();
+        throw error;
+      }
+    });
+  });
+}
 
 // src/internal/sdk.ts
 var _Brizz = class __Brizz {
@@ -1945,6 +2023,7 @@ var init_exports = {};
   Brizz,
   DEFAULT_PII_PATTERNS,
   LogLevel,
+  Session,
   SeverityNumber,
   callWithProperties,
   callWithSessionId,
@@ -1960,6 +2039,7 @@ var init_exports = {};
   maskAttributes,
   maskValue,
   setLogLevel,
+  startSession,
   withProperties,
   withSessionId
 });