openlayer 0.16.2 → 0.17.0

package/src/lib/integrations/tracedTool.ts

@@ -0,0 +1,175 @@
+import { tool } from '@langchain/core/tools';
+import { z } from 'zod';
+import { addFunctionCallStepToTrace } from '../tracing/tracer';
+
+/**
+ * Enhanced tool wrapper that automatically creates function call traces.
+ *
+ * This wrapper automatically creates StepType.FUNCTION_CALL steps for any tool invocation,
+ * providing detailed tracing of function calls within agent workflows.
+ *
+ * @example
+ * ```typescript
+ * import { tracedTool } from 'openlayer/lib/integrations/tracedTool';
+ *
+ * const weatherTool = tracedTool(
+ *   async ({ city }) => {
+ *     const weather = await getWeatherAPI(city);
+ *     return weather;
+ *   },
+ *   {
+ *     name: "get_weather",
+ *     description: "Get weather for a city",
+ *     schema: z.object({ city: z.string() }),
+ *     metadata: {
+ *       provider: "weather_api",
+ *       category: "external_api"
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export function tracedTool<T extends Record<string, any>>(
+  func: (input: T) => Promise<string> | string,
+  config: {
+    name: string;
+    description: string;
+    schema: z.ZodSchema<T>;
+    metadata?: Record<string, any>;
+    responseSchema?: z.ZodSchema<any>;
+  },
+) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return (tool as any)(
+    async (input: unknown) => {
+      const typedInput = input as T;
+      // Create a traced function call step (prefix will be added automatically)
+      const { step: functionStep, endStep: endFunctionStep } = addFunctionCallStepToTrace({
+        name: config.name,
+        functionName: config.name,
+        arguments: typedInput,
+        metadata: {
+          ...config.metadata,
+          toolType: 'traced_tool',
+          executionContext: 'auto_traced',
+        },
+      });
+
+      try {
+        // Execute the original function
+        const result = await func(typedInput);
+
+        // Update function step with result (timing handled automatically by step framework)
+        functionStep.log({
+          output: result,
+          metadata: {
+            ...functionStep.metadata,
+            outputLength: typeof result === 'string' ? result.length : JSON.stringify(result).length,
+            success: true,
+          },
+        });
+
+        return result;
+      } catch (error) {
+        // Log error in function step
+        functionStep.log({
+          metadata: {
+            ...functionStep.metadata,
+            error: error instanceof Error ? error.message : String(error),
+            errorType: error instanceof Error ? error.constructor.name : 'Unknown',
+            success: false,
+          },
+        });
+        throw error;
+      } finally {
+        endFunctionStep();
+      }
+    },
+    {
+      name: config.name,
+      description: config.description,
+      schema: config.schema,
+      ...(config.responseSchema && { responseSchema: config.responseSchema }),
+    },
+  );
+}
+
+/**
+ * Enhanced agent wrapper that automatically creates agent traces.
+ *
+ * This wrapper automatically creates StepType.AGENT steps for agent functions,
+ * providing clear agent boundaries in traces.
+ *
+ * @example
+ * ```typescript
+ * import { tracedAgent } from 'openlayer/lib/integrations/tracedTool';
+ *
+ * const researchAgent = tracedAgent(
+ *   async (query) => {
+ *     // Agent logic here
+ *     return result;
+ *   },
+ *   {
+ *     name: "Research Agent",
+ *     agentType: "research_specialist",
+ *     version: "1.0.0"
+ *   }
+ * );
+ * ```
+ */
+export function tracedAgent<T, R>(
+  agentFunc: (input: T) => Promise<R> | R,
+  config: {
+    name: string;
+    agentType: string;
+    version?: string;
+    metadata?: Record<string, any>;
+  },
+) {
+  return async (input: T): Promise<R> => {
+    const { startAgentStep } = await import('../tracing/tracer');
+
+    // Create an agent step (prefix will be added automatically)
+    const { step: agentStep, endStep: endAgentStep } = startAgentStep({
+      name: config.name,
+      agentType: config.agentType,
+      inputs: input,
+      metadata: {
+        ...config.metadata,
+        agentVersion: config.version || '1.0.0',
+        executionContext: 'traced_agent',
+      },
+    });
+
+    try {
+      // Execute the agent function
+      const result = await agentFunc(input);
+
+      // Update agent step with result (timing handled automatically by step framework)
+      agentStep.log({
+        output: result,
+        metadata: {
+          ...agentStep.metadata,
+          success: true,
+        },
+      });
+
+      return result;
+    } catch (error) {
+      // Log error in agent step
+      agentStep.log({
+        metadata: {
+          ...agentStep.metadata,
+          error: error instanceof Error ? error.message : String(error),
+          errorType: error instanceof Error ? error.constructor.name : 'Unknown',
+          success: false,
+        },
+      });
+      throw error;
+    } finally {
+      endAgentStep();
+    }
+  };
+}
+
+export default tracedTool;

package/src/lib/tracing/index.d.ts

@@ -1 +1,11 @@
 export * as tracer from './tracer';
+export {
+  addChatCompletionStepToTrace,
+  addChainStepToTrace,
+  addAgentStepToTrace,
+  addToolStepToTrace,
+  addRetrieverStepToTrace,
+  addFunctionCallStepToTrace,
+  startAgentStep,
+  addHandoffStepToTrace,
+} from './tracer';

package/src/lib/tracing/steps.ts

@@ -1,5 +1,25 @@
+/**
+ * Module with the different Step classes and helper functions that can be used in a trace.
+ *
+ * This is the consolidated module for all step-related functionality in the Openlayer SDK,
+ * similar to the Python SDK's steps.py module.
+ */
+
 import { v4 as uuidv4 } from 'uuid';
-import { StepType } from './enums';
+
+// ============================= ENUMS ============================= //
+
+export enum StepType {
+  USER_CALL = 'user_call',
+  CHAT_COMPLETION = 'chat_completion',
+  CHAIN = 'chain',
+  AGENT = 'agent',
+  TOOL = 'tool',
+  RETRIEVER = 'retriever',
+  FUNCTION_CALL = 'function_call',
+}
+
+// ============================= INTERFACES ============================= //
 
 export interface StepData {
   name: string;
@@ -25,6 +45,15 @@ export interface ChatCompletionStepData extends StepData {
   modelParameters: Record<string, any> | null;
 }
 
+// ============================= STEP CLASSES ============================= //
+
+/**
+ * Step, defined as a single function call being traced.
+ *
+ * This is the base class for all the different types of steps that can be
+ * used in a trace. Steps can also contain nested steps, which represent
+ * function calls made within the parent step.
+ */
 export class Step {
   name: string;
   id: string;
@@ -38,21 +67,33 @@ export class Step {
   latency: number | null = null;
   steps: Step[] = [];
 
-  constructor(name: string, inputs: any = null, output: any = null, metadata: Record<string, any> = {}, startTime?: number | null, endTime?: number | null) {
+  constructor(
+    name: string,
+    inputs: any = null,
+    output: any = null,
+    metadata: Record<string, any> = {},
+    startTime?: number | null,
+    endTime?: number | null,
+  ) {
     this.name = name;
     this.id = uuidv4();
     this.inputs = inputs;
     this.output = output;
     this.metadata = metadata;
-
     this.startTime = startTime ?? Date.now();
     this.endTime = endTime ?? null;
   }
 
+  /**
+   * Adds a nested step to the current step.
+   */
   addNestedStep(nestedStep: Step): void {
     this.steps.push(nestedStep);
   }
 
+  /**
+   * Logs step data.
+   */
   log(data: Partial<Record<keyof this, any>>): void {
     Object.keys(data).forEach((key) => {
       if (key in this) {
@@ -62,6 +103,9 @@ export class Step {
     });
   }
 
+  /**
+   * Dictionary representation of the Step.
+   */
   toJSON(): StepData {
     return {
       name: this.name,
@@ -79,13 +123,26 @@ export class Step {
   }
 }
 
+/**
+ * User call step represents a generic user call in the trace.
+ */
 export class UserCallStep extends Step {
-  constructor(name: string, inputs: any = null, output: any = null, metadata: Record<string, any> = {}, startTime?: number | null, endTime?: number | null) {
+  constructor(
+    name: string,
+    inputs: any = null,
+    output: any = null,
+    metadata: Record<string, any> = {},
+    startTime?: number | null,
+    endTime?: number | null,
+  ) {
     super(name, inputs, output, metadata, startTime, endTime);
     this.stepType = StepType.USER_CALL;
   }
 }
 
+/**
+ * Chat completion step represents an LLM chat completion in the trace.
+ */
 export class ChatCompletionStep extends Step {
   provider: string | null = null;
   promptTokens: number | null = null;
@@ -95,7 +152,14 @@ export class ChatCompletionStep extends Step {
   model: string | null = null;
   modelParameters: Record<string, any> | null = null;
 
-    constructor(name: string, inputs: any = null, output: any = null, metadata: Record<string, any> = {}, startTime?: number | null, endTime?: number | null) {
+  constructor(
+    name: string,
+    inputs: any = null,
+    output: any = null,
+    metadata: Record<string, any> = {},
+    startTime?: number | null,
+    endTime?: number | null,
+  ) {
     super(name, inputs, output, metadata, startTime, endTime);
     this.stepType = StepType.CHAT_COMPLETION;
   }
@@ -114,3 +178,152 @@ export class ChatCompletionStep extends Step {
     };
   }
 }
+
+/**
+ * Chain step represents sequential operations or workflow chains in AI applications.
+ */
+export class ChainStep extends Step {
+  constructor(name: string, inputs: any = null, output: any = null, metadata: Record<string, any> = {}) {
+    super(name, inputs, output, metadata);
+    this.stepType = StepType.CHAIN;
+  }
+}
+
+/**
+ * Agent step tracks AI agent actions and decision-making processes.
+ */
+export class AgentStep extends Step {
+  tool: string | null = null;
+  action: any = null;
+
+  constructor(name: string, inputs: any = null, output: any = null, metadata: Record<string, any> = {}) {
+    super(name, inputs, output, metadata);
+    this.stepType = StepType.AGENT;
+  }
+}
+
+/**
+ * Tool step tracks individual tool executions within AI workflows.
+ */
+export class ToolStep extends Step {
+  constructor(name: string, inputs: any = null, output: any = null, metadata: Record<string, any> = {}) {
+    super(name, inputs, output, metadata);
+    this.stepType = StepType.TOOL;
+  }
+}
+
+/**
+ * Retriever step tracks document retrieval and search operations.
+ */
+export class RetrieverStep extends Step {
+  documents: any[] = [];
+
+  constructor(name: string, inputs: any = null, output: any = null, metadata: Record<string, any> = {}) {
+    super(name, inputs, output, metadata);
+    this.stepType = StepType.RETRIEVER;
+  }
+}
+
+/**
+ * Function call step tracks specific function calls with detailed execution metadata.
+ */
+export class FunctionCallStep extends Step {
+  functionName: string | null = null;
+  arguments: Record<string, any> | null = null;
+  result: any = null;
+  executionTime: number | null = null;
+
+  constructor(name: string, inputs: any = null, output: any = null, metadata: Record<string, any> = {}) {
+    super(name, inputs, output, metadata);
+    this.stepType = StepType.FUNCTION_CALL;
+  }
+}
+
+// ============================= FACTORY FUNCTION ============================= //
+
+/**
+ * Factory function to create a step based on the step type.
+ */
+export function stepFactory(
+  stepType: StepType,
+  name: string,
+  inputs: any = null,
+  output: any = null,
+  metadata: Record<string, any> = {},
+  startTime?: number | null,
+  endTime?: number | null,
+): Step {
+  if (!Object.values(StepType).includes(stepType)) {
+    throw new Error(`Step type ${stepType} not recognized.`);
+  }
+
+  switch (stepType) {
+    case StepType.USER_CALL:
+      return new UserCallStep(name, inputs, output, metadata, startTime, endTime);
+    case StepType.CHAT_COMPLETION:
+      return new ChatCompletionStep(name, inputs, output, metadata, startTime, endTime);
+    case StepType.CHAIN:
+      return new ChainStep(name, inputs, output, metadata);
+    case StepType.AGENT:
+      return new AgentStep(name, inputs, output, metadata);
+    case StepType.TOOL:
+      return new ToolStep(name, inputs, output, metadata);
+    case StepType.RETRIEVER:
+      return new RetrieverStep(name, inputs, output, metadata);
+    case StepType.FUNCTION_CALL:
+      return new FunctionCallStep(name, inputs, output, metadata);
+    default:
+      throw new Error(`Step type ${stepType} not recognized.`);
+  }
+}
+
+// ============================= HELPER FUNCTION INTERFACES ============================= //
+
+/**
+ * Interface for step creation parameters used by helper functions
+ */
+export interface StepCreationParams {
+  name: string;
+  inputs?: any;
+  output?: any;
+  metadata?: Record<string, any>;
+}
+
+export interface ChatCompletionStepParams extends StepCreationParams {
+  latency: number;
+  tokens?: number | null;
+  promptTokens?: number | null;
+  completionTokens?: number | null;
+  model?: string | null;
+  modelParameters?: Record<string, any> | null;
+  rawOutput?: string | null;
+  provider?: string;
+  startTime?: number | null;
+  endTime?: number | null;
+}
+
+export interface AgentStepParams extends StepCreationParams {
+  tool?: string;
+  action?: any;
+}
+
+export interface RetrieverStepParams extends StepCreationParams {
+  documents?: any[];
+}
+
+export interface FunctionCallStepParams extends StepCreationParams {
+  functionName: string;
+  arguments: Record<string, any>;
+}
+
+export interface EnhancedAgentStepParams extends StepCreationParams {
+  agentType: string;
+}
+
+export interface HandoffStepParams {
+  name: string;
+  fromComponent: string;
+  toComponent: string;
+  handoffData: any;
+  metadata?: Record<string, any>;
+}

package/src/lib/tracing/tracer.ts

@@ -1,9 +1,16 @@
 // tracing/tracer.ts
 
-import Openlayer from '../../index';
-import { StepType } from './enums';
-import { ChatCompletionStep, Step, UserCallStep } from './steps';
 import { Trace } from './traces';
+import {
+  Step,
+  ChatCompletionStep,
+  AgentStep,
+  RetrieverStep,
+  FunctionCallStep,
+  StepType,
+  stepFactory,
+} from './steps';
+import Openlayer from '../../index';
 
 let currentTrace: Trace | null = null;
 
@@ -36,12 +43,7 @@ function createStep(
   openlayerInferencePipelineId?: string,
 ): [Step, () => void] {
   metadata = metadata || {};
-  let newStep: Step;
-  if (stepType === StepType.CHAT_COMPLETION) {
-    newStep = new ChatCompletionStep(name, inputs, output, metadata, startTime, endTime);
-  } else {
-    newStep = new UserCallStep(name, inputs, output, metadata, startTime, endTime);
-  }
+  const newStep = stepFactory(stepType, name, inputs, output, metadata, startTime, endTime);
 
   const inferencePipelineId = openlayerInferencePipelineId || process.env['OPENLAYER_INFERENCE_PIPELINE_ID'];
 
@@ -63,7 +65,19 @@ function createStep(
   stepStack.push(newStep);
 
   const endStep = () => {
+    // Calculate latency for this step before removing from stack
+    newStep.endTime = Date.now();
+    // Only calculate latency if it hasn't been manually set
+    if (newStep.latency === null) {
+      if (newStep.startTime && newStep.endTime) {
+        newStep.latency = newStep.endTime - newStep.startTime;
+      } else {
+        newStep.latency = 0; // Fallback to 0 if timestamps are missing
+      }
+    }
+
     stepStack.pop(); // Remove the current step from the stack
+    console.debug(`Ending step ${newStep.name}`);
 
     if (isRootStep) {
       console.debug('Ending the trace...');
@@ -225,6 +239,136 @@ export function addChatCompletionStepToTrace(
   endStep();
 }
 
+export function addChainStepToTrace(params: {
+  name: string;
+  inputs: any;
+  output?: any;
+  metadata?: Record<string, any>;
+}) {
+  // Add "Handoffs: " prefix for chain steps (representing workflow transitions)
+  const stepName = `Handoffs: ${params.name}`;
+  const [step, endStep] = createStep(stepName, StepType.CHAIN, params.inputs, params.output, params.metadata);
+  return { step, endStep };
+}
+
+export function addAgentStepToTrace(params: {
+  name: string;
+  inputs: any;
+  output?: any;
+  metadata?: Record<string, any>;
+  tool?: string;
+  action?: any;
+}) {
+  // Add "Agent: " prefix for agent steps
+  const stepName = `Agent: ${params.name}`;
+  const [step, endStep] = createStep(stepName, StepType.AGENT, params.inputs, params.output, params.metadata);
+  if (step instanceof AgentStep) {
+    step.tool = params.tool || null;
+    step.action = params.action || null;
+  }
+  return { step, endStep };
+}
+
+export function addToolStepToTrace(params: {
+  name: string;
+  inputs: any;
+  output?: any;
+  metadata?: Record<string, any>;
+}) {
+  const [step, endStep] = createStep(
+    params.name,
+    StepType.TOOL,
+    params.inputs,
+    params.output,
+    params.metadata,
+  );
+  return { step, endStep };
+}
+
+export function addRetrieverStepToTrace(params: {
+  name: string;
+  inputs: any;
+  output?: any;
+  metadata?: Record<string, any>;
+  documents?: any[];
+}) {
+  const [step, endStep] = createStep(
+    params.name,
+    StepType.RETRIEVER,
+    params.inputs,
+    params.output,
+    params.metadata,
+  );
+  if (step instanceof RetrieverStep) {
+    step.documents = params.documents || [];
+  }
+  return { step, endStep };
+}
+
+export function addFunctionCallStepToTrace(params: {
+  name: string;
+  functionName: string;
+  arguments: Record<string, any>;
+  output?: any;
+  metadata?: Record<string, any>;
+}) {
+  // Add "Tool Call: " prefix for better dashboard visibility
+  const stepName = `Tool Call: ${params.name}`;
+  const [step, endStep] = createStep(
+    stepName,
+    StepType.FUNCTION_CALL,
+    params.arguments,
+    params.output,
+    params.metadata,
+  );
+  if (step instanceof FunctionCallStep) {
+    step.functionName = params.functionName;
+    step.arguments = params.arguments;
+    step.result = params.output;
+  }
+  return { step, endStep };
+}
+
+// Enhanced agent step creator with nested LLM tracking
+export function startAgentStep(params: {
+  name: string;
+  agentType: string;
+  inputs: any;
+  metadata?: Record<string, any>;
+}) {
+  // Add "Agent: " prefix for better dashboard visibility
+  const stepName = `Agent: ${params.name}`;
+  const [step, endStep] = createStep(stepName, StepType.AGENT, params.inputs, undefined, {
+    ...params.metadata,
+    agentType: params.agentType,
+  });
+
+  if (step instanceof AgentStep) {
+    step.action = params.inputs;
+  }
+
+  return { step, endStep };
+}
+
+// Explicit handoff function for agent-to-agent or component-to-component transitions
+export function addHandoffStepToTrace(params: {
+  name: string;
+  fromComponent: string;
+  toComponent: string;
+  handoffData: any;
+  metadata?: Record<string, any>;
+}) {
+  const stepName = `Handoffs: ${params.fromComponent} → ${params.toComponent}`;
+  const [step, endStep] = createStep(stepName, StepType.CHAIN, params.handoffData, undefined, {
+    ...params.metadata,
+    handoffType: 'component_transition',
+    fromComponent: params.fromComponent,
+    toComponent: params.toComponent,
+    timestamp: new Date().toISOString(),
+  });
+  return { step, endStep };
+}
+
 export function postProcessTrace(traceObj: Trace): { traceData: any; inputVariableNames: string[] } {
   const rootStep = traceObj.steps[0];
 

package/src/resources/inference-pipelines/data.ts

@@ -118,11 +118,21 @@ export namespace DataStreamParams {
      */
     questionColumnName?: string;
 
+    /**
+     * Name of the column with the session id.
+     */
+    sessionIdColumnName?: string | null;
+
     /**
      * Name of the column with the timestamps. Timestamps must be in UNIX sec format.
      * If not provided, the upload timestamp is used.
      */
     timestampColumnName?: string;
+
+    /**
+     * Name of the column with the user id.
+     */
+    userIdColumnName?: string | null;
   }
 
   export namespace LlmData {

package/src/uploads.ts

@@ -156,8 +156,9 @@ async function getBytes(value: ToFileInput): Promise<Array<BlobPart>> {
     }
   } else {
     throw new Error(
-      `Unexpected data type: ${typeof value}; constructor: ${value?.constructor
-        ?.name}; props: ${propsForError(value)}`,
+      `Unexpected data type: ${typeof value}; constructor: ${
+        value?.constructor?.name
+      }; props: ${propsForError(value)}`,
     );
   }
 

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.16.2'; // x-release-please-version
+export const VERSION = '0.17.0'; // x-release-please-version

package/uploads.d.ts

@@ -69,7 +69,7 @@ export declare const isMultipartBody: (body: any) => body is MultipartBody;
  * Returns a multipart/form-data request if any part of the given request body contains a File / Blob value.
  * Otherwise returns the request as is.
  */
-export declare const maybeMultipartFormRequestOptions: <T = Record<string, unknown>>(opts: RequestOptions<T>) => Promise<RequestOptions<MultipartBody | T>>;
-export declare const multipartFormRequestOptions: <T = Record<string, unknown>>(opts: RequestOptions<T>) => Promise<RequestOptions<MultipartBody | T>>;
+export declare const maybeMultipartFormRequestOptions: <T = Record<string, unknown>>(opts: RequestOptions<T>) => Promise<RequestOptions<T | MultipartBody>>;
+export declare const multipartFormRequestOptions: <T = Record<string, unknown>>(opts: RequestOptions<T>) => Promise<RequestOptions<T | MultipartBody>>;
 export declare const createForm: <T = Record<string, unknown>>(body: T | undefined) => Promise<FormData>;
 //# sourceMappingURL=uploads.d.ts.map