@brizz/sdk 0.1.14 → 0.1.16

package/README.md

@@ -288,6 +288,7 @@ const result = await startSession(
 - `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
+- `session.setTitle(text)` - Set a session title (typically used with `mode: 'title'`)
 
 **When to use manual input/output tracking:**
 
@@ -313,6 +314,58 @@ await startSession('session-456', async (session) => {
 });
 ```
 
+### Session Title Generation
+
+If you use an LLM call to generate session titles, wrap it so those spans don't appear as part of the conversation:
+
+```typescript
+import { startSession, startSessionTitle } from '@brizz/sdk';
+
+await startSession('session-123', async (session) => {
+  const response = await openai.chat.completions.create({...});
+
+  // Title generation — excluded from conversation view
+  await startSessionTitle(async (title) => {
+    const t = await openai.chat.completions.create({
+      model: 'gpt-4',
+      messages: [{ role: 'user', content: 'Summarize this chat in 3 words' }],
+    });
+    title.setTitle(t.choices[0].message.content);
+  });
+});
+
+// Or use mode: 'title' on startSession directly
+await startSession('session-123', async (session) => {
+  const t = await openai.chat.completions.create({...});
+  session.setTitle(t.choices[0].message.content);
+}, undefined, { mode: 'title' });
+
+// Or use startSessionTitle outside a session (pass sessionId explicitly)
+await startSessionTitle(async (title) => {
+  title.setTitle('My Title');
+}, { sessionId: 'session-123' });
+```
+
+### Accessing the Active Session
+
+Use `getActiveSession()` to retrieve the current session from anywhere within a `startSession` scope — no need to pass the session object through your call stack:
+
+```typescript
+import { startSession, getActiveSession } from '@brizz/sdk';
+
+function deepHelper() {
+  const session = getActiveSession();
+  session?.updateProperties({ step: 'helper' });
+}
+
+await startSession('session-123', async () => {
+  deepHelper(); // accesses session without it being passed as a parameter
+});
+
+// Outside a session, returns undefined
+getActiveSession(); // undefined
+```
+
 ### Function Wrapper Pattern
 
 For simpler cases where you just need to tag traces with a session ID:

package/dist/index.cjs

@@ -34,11 +34,13 @@ __export(src_exports, {
   DEFAULT_PII_PATTERNS: () => DEFAULT_PII_PATTERNS,
   LogLevel: () => LogLevel,
   Session: () => Session,
+  SessionTitle: () => SessionTitle,
   SeverityNumber: () => import_api_logs2.SeverityNumber,
   callWithProperties: () => callWithProperties,
   callWithSessionId: () => callWithSessionId,
   detectRuntime: () => detectRuntime,
   emitEvent: () => emitEvent,
+  getActiveSession: () => getActiveSession,
   getLogLevel: () => getLogLevel,
   getMetricsExporter: () => getMetricsExporter,
   getMetricsReader: () => getMetricsReader,
@@ -50,6 +52,7 @@ __export(src_exports, {
   maskValue: () => maskValue,
   setLogLevel: () => setLogLevel,
   startSession: () => startSession,
+  startSessionTitle: () => startSessionTitle,
   withProperties: () => withProperties,
   withSessionId: () => withSessionId
 });
@@ -493,7 +496,7 @@ var import_sdk_logs2 = require("@opentelemetry/sdk-logs");
 
 // src/internal/version.ts
 function getSDKVersion() {
-  return "0.1.14";
+  return "0.1.16";
 }
 
 // src/internal/log/processors/log-processor.ts
@@ -1130,9 +1133,13 @@ var BRIZZ = "brizz";
 var PROPERTIES = "properties";
 var SESSION_ID = "session.id";
 var PROPERTIES_CONTEXT_KEY = (0, import_api2.createContextKey)(PROPERTIES);
+var SESSION_OBJECT_CONTEXT_KEY = (0, import_api2.createContextKey)("brizz.session.object");
 var SESSION_INPUT = "brizz.session.input";
 var SESSION_OUTPUT = "brizz.session.output";
 var SESSION_SPAN_NAME = "brizz.start_session";
+var SESSION_TITLE_SPAN_NAME = "brizz.session_title";
+var SESSION_TITLE_GENERATION = "session.title_generation";
+var SESSION_TITLE = "brizz.session.title";
 
 // src/internal/log/processors/log-processor.ts
 var DEFAULT_LOG_MASKING_RULES = [
@@ -1762,7 +1769,7 @@ var Session = class {
    * 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
+   * @param text - Text to append to session input, or null to append null
    */
   setInput(text) {
     this.inputs.push(text);
@@ -1773,12 +1780,20 @@ var Session = class {
    * 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
+   * @param text - Text to append to session output, or null to append null
    */
   setOutput(text) {
     this.outputs.push(text);
     this.span.setAttribute(SESSION_OUTPUT, JSON.stringify(this.outputs));
   }
+  /**
+   * Set the session title on the span.
+   *
+   * @param title - The generated title string
+   */
+  setTitle(title) {
+    this.span.setAttribute(SESSION_TITLE, title);
+  }
   /**
    * Update custom properties on the session span.
    * Properties are prefixed with 'brizz.'.
@@ -1791,9 +1806,28 @@ var Session = class {
     }
   }
 };
-function startSession(sessionId, callback, extraProperties) {
+var SessionTitle = class {
+  span;
+  constructor(span) {
+    this.span = span;
+  }
+  /**
+   * Set the generated title on the wrapper span.
+   *
+   * @param title - The generated title string
+   */
+  setTitle(title) {
+    this.span.setAttribute(SESSION_TITLE, title);
+  }
+};
+function getActiveSession() {
+  return import_api5.context.active().getValue(SESSION_OBJECT_CONTEXT_KEY);
+}
+function startSession(sessionId, callback, extraProperties, options) {
+  const isTitle = options?.mode === "title";
+  const spanName = isTitle ? SESSION_TITLE_SPAN_NAME : SESSION_SPAN_NAME;
   const tracer = import_api5.trace.getTracer("@brizz/sdk");
-  return tracer.startActiveSpan(SESSION_SPAN_NAME, (span) => {
+  return tracer.startActiveSpan(spanName, (span) => {
     span.setAttribute(`${BRIZZ}.${SESSION_ID}`, sessionId);
     if (extraProperties) {
       for (const [key, value] of Object.entries(extraProperties)) {
@@ -1802,14 +1836,57 @@ function startSession(sessionId, callback, extraProperties) {
     }
     const session = new Session(sessionId, span);
     const contextProperties = { [SESSION_ID]: sessionId };
+    if (isTitle) {
+      contextProperties[SESSION_TITLE_GENERATION] = "true";
+    }
     if (extraProperties) {
       for (const [key, value] of Object.entries(extraProperties)) {
         contextProperties[key] = String(value);
       }
     }
     return callWithProperties(contextProperties, () => {
+      const sessionCtx = import_api5.context.active().setValue(SESSION_OBJECT_CONTEXT_KEY, session);
+      return import_api5.context.with(sessionCtx, () => {
+        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;
+        }
+      });
+    });
+  });
+}
+function startSessionTitle(callback, options) {
+  const resolvedSessionId = options?.sessionId ?? getActiveSession()?.sessionId;
+  const tracer = import_api5.trace.getTracer("@brizz/sdk");
+  return tracer.startActiveSpan(SESSION_TITLE_SPAN_NAME, (span) => {
+    if (resolvedSessionId) {
+      span.setAttribute(`${BRIZZ}.${SESSION_ID}`, resolvedSessionId);
+    }
+    const sessionTitle = new SessionTitle(span);
+    const properties = { [SESSION_TITLE_GENERATION]: "true" };
+    if (resolvedSessionId) {
+      properties[SESSION_ID] = resolvedSessionId;
+    }
+    return callWithProperties(properties, () => {
       try {
-        const result = callback(session);
+        const result = callback(sessionTitle);
         if (result && typeof result.then === "function") {
           return result.then((value) => {
             span.end();
@@ -2083,11 +2160,13 @@ var init_exports = {};
   DEFAULT_PII_PATTERNS,
   LogLevel,
   Session,
+  SessionTitle,
   SeverityNumber,
   callWithProperties,
   callWithSessionId,
   detectRuntime,
   emitEvent,
+  getActiveSession,
   getLogLevel,
   getMetricsExporter,
   getMetricsReader,
@@ -2099,6 +2178,7 @@ var init_exports = {};
   maskValue,
   setLogLevel,
   startSession,
+  startSessionTitle,
   withProperties,
   withSessionId
 });