netra-sdk 1.1.0 → 1.3.0

package/dist/index.d.cts

@@ -1061,6 +1061,32 @@ interface DecoratorOptions {
 }
 type SpanCallback<T> = (span: SpanWrapper) => T;
 
+/**
+ * Raw file metadata received from the backend.
+ *
+ * Contains a pre-signed download URL that the SDK uses to fetch the actual
+ * file content. Instances are produced by parsing the `attachments` array
+ * returned on each user message from the simulation API.
+ */
+interface FileData {
+    fileName: string;
+    contentType: string;
+    description?: string;
+    downloadUrl: string;
+}
+/**
+ * File after download and base64 encoding, delivered to the user task.
+ *
+ * The `data` field contains the raw file bytes encoded as a base64 ASCII
+ * string.  Consumers should decode with `Buffer.from(data, "base64")` before
+ * passing to an LLM or other downstream system.
+ */
+interface ProcessedFile {
+    fileName: string;
+    contentType: string;
+    description?: string;
+    data: string;
+}
 /**
  * Represents a single item in a simulation run.
  */
@@ -1068,6 +1094,7 @@ interface SimulationItem {
     runItemId: string;
     message: string;
     turnId: string;
+    files?: FileData[];
 }
 /**
  * Response from the conversation trigger API.
@@ -1078,6 +1105,7 @@ interface ConversationResponse {
     nextTurnId?: string;
     nextUserMessage?: string;
     nextRunItemId?: string;
+    nextFiles?: FileData[];
 }
 /**
  * Result returned from the user's task function.
@@ -1108,13 +1136,17 @@ interface SimulationResult {
 
 declare abstract class BaseTask {
     /**
+     * Process a simulation turn and return the agent's response.
+     *
      * @param message - The input message from the simulation.
-     * @param sessionId - The Session identifier.
+     * @param sessionId - The session identifier.
+     * @param files - Optional list of base64-encoded file attachments from the
+     *                dataset item.  Will be `null` when no files are attached.
      * @returns The task result containing:
      *            - message (string): The response message from the task.
      *            - sessionId (string): The session identifier.
      */
-    abstract run(message: string, sessionId?: string | null): Promise<TaskResult> | TaskResult;
+    abstract run(message: string, sessionId?: string | null, files?: ProcessedFile[] | null): Promise<TaskResult> | TaskResult;
 }
 
 /**
@@ -1182,6 +1214,28 @@ declare function span(target: AnyClass): void;
 declare function span<T extends AnyFunction>(target: T): T;
 declare function span(options?: DecoratorOptions): UnifiedDecorator;
 
+/**
+ * Shared utility functions for instrumentation.
+ * Handles setting OTel span attributes for LLM request/response tracing.
+ */
+
+/**
+ * Controls where native traces are sent.
+ *
+ * - `"netra"` -- Replace the SDK's default processors so traces go
+ *   only to Netra. If the SDK does not expose the required APIs, falls back
+ *   to additive mode (both Netra and native) and logs a warning.
+ * - `"netra-strict"` (default) -- Same replacement as `"netra"`, but if the SDK APIs
+ *   are unavailable the processor is **not** registered at all, ensuring
+ *   traces never reach native even at the cost of no tracing.
+ * - `"both"` -- The Netra processor is added alongside the native defaults;
+ *   traces go to both Netra and native.
+ *
+ * Can also be set via the `NATIVE_TRACING_MODE` environment
+ * variable using the same string values.
+ */
+type NativeTracingMode = "both" | "netra" | "netra-strict";
+
 /**
  * Custom MistralAI instrumentor for Netra SDK
  *
@@ -1296,12 +1350,15 @@ interface TracingProcessor {
     forceFlush(): Promise<void> | void;
     shutdown(timeout?: number): Promise<void> | void;
 }
+
 interface InstrumentorOptions {
     tracerProvider?: {
         getTracer(name: string, version?: string): any;
     };
     /** Override the `llm.system` attribute value (default: `"openai"`). */
     systemName?: string;
+    /** Controls where traces are sent. See {@link NativeTracingMode}. */
+    nativeTracing?: NativeTracingMode;
 }
 
 declare class NetraAgentsTracingProcessor implements TracingProcessor {
@@ -1528,4 +1585,4 @@ declare class Netra {
     static withBlockedSpansLocal: typeof withBlockedSpansLocal;
 }
 
-export { type ActionModel, Aggregation, BaseTask, type CategoricalDataPoint, ChartType, Config, type ConversationResponse, type ConversationResult, ConversationType, type CreateDatasetParams, type CreateRunResult, DEFAULT_INSTRUMENTS, DEFAULT_INSTRUMENTS_FOR_ROOT, Dashboard, type DashboardData, type Dataset, type DatasetEntry, type DatasetItem, type Dimension, DimensionField, type DimensionValue, EntryStatus, Evaluation, type EvaluationScore, type EvaluatorFunction, type Filter, type FilterConfig, FilterField, FilterType, FilteringSpanExporter, type GetPromptParams, GroupBy, InstrumentationSpanProcessor, type ListSpansParams, type ListTracesParams, Measure, type Metrics, Netra, NetraAgentsTracingProcessor, NetraInstruments, NetraOpenAIAgentsInstrumentor, type NumberResponse, Operator, type PromptResponse, Prompts, type QueryDataParams, type QueryResponse, type Run, RunEntryContext, RunStatus, Scope, ScrubbingSpanProcessor, SessionSpanProcessor, type SessionUsageData, Simulation, type SimulationItem, type SimulationOptions, type SimulationResult, SpanIOProcessor, type SpanOptions, SpanType, type SpansPage, type TaskFunction, type TaskResult, type TenantUsageData, type TestSuiteResult, type TimeRange, type TimeSeriesDataPoint, type TimeSeriesResponse, type TimeSeriesWithDimension, type TraceSpan, type TraceSummary, type TracesPage, TrialAwareOTLPExporter, Usage, type UsageModel, agent, Netra as default, metadataField, mistralAIInstrumentor, netraExpressMiddleware, openaiAgentsInstrumentor, runWithExtractedContext, span, task, workflow };
+export { type ActionModel, Aggregation, BaseTask, type CategoricalDataPoint, ChartType, Config, type ConversationResponse, type ConversationResult, ConversationType, type CreateDatasetParams, type CreateRunResult, DEFAULT_INSTRUMENTS, DEFAULT_INSTRUMENTS_FOR_ROOT, Dashboard, type DashboardData, type Dataset, type DatasetEntry, type DatasetItem, type Dimension, DimensionField, type DimensionValue, EntryStatus, Evaluation, type EvaluationScore, type EvaluatorFunction, type Filter, type FilterConfig, FilterField, FilterType, FilteringSpanExporter, type GetPromptParams, GroupBy, InstrumentationSpanProcessor, type ListSpansParams, type ListTracesParams, Measure, type Metrics, Netra, NetraAgentsTracingProcessor, NetraInstruments, NetraOpenAIAgentsInstrumentor, type NumberResponse, Operator, type ProcessedFile, type PromptResponse, Prompts, type QueryDataParams, type QueryResponse, type Run, RunEntryContext, RunStatus, Scope, ScrubbingSpanProcessor, SessionSpanProcessor, type SessionUsageData, Simulation, type SimulationItem, type SimulationOptions, type SimulationResult, SpanIOProcessor, type SpanOptions, SpanType, type SpansPage, type TaskFunction, type TaskResult, type TenantUsageData, type TestSuiteResult, type TimeRange, type TimeSeriesDataPoint, type TimeSeriesResponse, type TimeSeriesWithDimension, type TraceSpan, type TraceSummary, type TracesPage, TrialAwareOTLPExporter, Usage, type UsageModel, agent, Netra as default, metadataField, mistralAIInstrumentor, netraExpressMiddleware, openaiAgentsInstrumentor, runWithExtractedContext, span, task, workflow };

package/dist/index.d.ts

@@ -1061,6 +1061,32 @@ interface DecoratorOptions {
 }
 type SpanCallback<T> = (span: SpanWrapper) => T;
 
+/**
+ * Raw file metadata received from the backend.
+ *
+ * Contains a pre-signed download URL that the SDK uses to fetch the actual
+ * file content. Instances are produced by parsing the `attachments` array
+ * returned on each user message from the simulation API.
+ */
+interface FileData {
+    fileName: string;
+    contentType: string;
+    description?: string;
+    downloadUrl: string;
+}
+/**
+ * File after download and base64 encoding, delivered to the user task.
+ *
+ * The `data` field contains the raw file bytes encoded as a base64 ASCII
+ * string.  Consumers should decode with `Buffer.from(data, "base64")` before
+ * passing to an LLM or other downstream system.
+ */
+interface ProcessedFile {
+    fileName: string;
+    contentType: string;
+    description?: string;
+    data: string;
+}
 /**
  * Represents a single item in a simulation run.
  */
@@ -1068,6 +1094,7 @@ interface SimulationItem {
     runItemId: string;
     message: string;
     turnId: string;
+    files?: FileData[];
 }
 /**
  * Response from the conversation trigger API.
@@ -1078,6 +1105,7 @@ interface ConversationResponse {
     nextTurnId?: string;
     nextUserMessage?: string;
     nextRunItemId?: string;
+    nextFiles?: FileData[];
 }
 /**
  * Result returned from the user's task function.
@@ -1108,13 +1136,17 @@ interface SimulationResult {
 
 declare abstract class BaseTask {
     /**
+     * Process a simulation turn and return the agent's response.
+     *
      * @param message - The input message from the simulation.
-     * @param sessionId - The Session identifier.
+     * @param sessionId - The session identifier.
+     * @param files - Optional list of base64-encoded file attachments from the
+     *                dataset item.  Will be `null` when no files are attached.
      * @returns The task result containing:
      *            - message (string): The response message from the task.
      *            - sessionId (string): The session identifier.
      */
-    abstract run(message: string, sessionId?: string | null): Promise<TaskResult> | TaskResult;
+    abstract run(message: string, sessionId?: string | null, files?: ProcessedFile[] | null): Promise<TaskResult> | TaskResult;
 }
 
 /**
@@ -1182,6 +1214,28 @@ declare function span(target: AnyClass): void;
 declare function span<T extends AnyFunction>(target: T): T;
 declare function span(options?: DecoratorOptions): UnifiedDecorator;
 
+/**
+ * Shared utility functions for instrumentation.
+ * Handles setting OTel span attributes for LLM request/response tracing.
+ */
+
+/**
+ * Controls where native traces are sent.
+ *
+ * - `"netra"` -- Replace the SDK's default processors so traces go
+ *   only to Netra. If the SDK does not expose the required APIs, falls back
+ *   to additive mode (both Netra and native) and logs a warning.
+ * - `"netra-strict"` (default) -- Same replacement as `"netra"`, but if the SDK APIs
+ *   are unavailable the processor is **not** registered at all, ensuring
+ *   traces never reach native even at the cost of no tracing.
+ * - `"both"` -- The Netra processor is added alongside the native defaults;
+ *   traces go to both Netra and native.
+ *
+ * Can also be set via the `NATIVE_TRACING_MODE` environment
+ * variable using the same string values.
+ */
+type NativeTracingMode = "both" | "netra" | "netra-strict";
+
 /**
  * Custom MistralAI instrumentor for Netra SDK
  *
@@ -1296,12 +1350,15 @@ interface TracingProcessor {
     forceFlush(): Promise<void> | void;
     shutdown(timeout?: number): Promise<void> | void;
 }
+
 interface InstrumentorOptions {
     tracerProvider?: {
         getTracer(name: string, version?: string): any;
     };
     /** Override the `llm.system` attribute value (default: `"openai"`). */
     systemName?: string;
+    /** Controls where traces are sent. See {@link NativeTracingMode}. */
+    nativeTracing?: NativeTracingMode;
 }
 
 declare class NetraAgentsTracingProcessor implements TracingProcessor {
@@ -1528,4 +1585,4 @@ declare class Netra {
     static withBlockedSpansLocal: typeof withBlockedSpansLocal;
 }
 
-export { type ActionModel, Aggregation, BaseTask, type CategoricalDataPoint, ChartType, Config, type ConversationResponse, type ConversationResult, ConversationType, type CreateDatasetParams, type CreateRunResult, DEFAULT_INSTRUMENTS, DEFAULT_INSTRUMENTS_FOR_ROOT, Dashboard, type DashboardData, type Dataset, type DatasetEntry, type DatasetItem, type Dimension, DimensionField, type DimensionValue, EntryStatus, Evaluation, type EvaluationScore, type EvaluatorFunction, type Filter, type FilterConfig, FilterField, FilterType, FilteringSpanExporter, type GetPromptParams, GroupBy, InstrumentationSpanProcessor, type ListSpansParams, type ListTracesParams, Measure, type Metrics, Netra, NetraAgentsTracingProcessor, NetraInstruments, NetraOpenAIAgentsInstrumentor, type NumberResponse, Operator, type PromptResponse, Prompts, type QueryDataParams, type QueryResponse, type Run, RunEntryContext, RunStatus, Scope, ScrubbingSpanProcessor, SessionSpanProcessor, type SessionUsageData, Simulation, type SimulationItem, type SimulationOptions, type SimulationResult, SpanIOProcessor, type SpanOptions, SpanType, type SpansPage, type TaskFunction, type TaskResult, type TenantUsageData, type TestSuiteResult, type TimeRange, type TimeSeriesDataPoint, type TimeSeriesResponse, type TimeSeriesWithDimension, type TraceSpan, type TraceSummary, type TracesPage, TrialAwareOTLPExporter, Usage, type UsageModel, agent, Netra as default, metadataField, mistralAIInstrumentor, netraExpressMiddleware, openaiAgentsInstrumentor, runWithExtractedContext, span, task, workflow };
+export { type ActionModel, Aggregation, BaseTask, type CategoricalDataPoint, ChartType, Config, type ConversationResponse, type ConversationResult, ConversationType, type CreateDatasetParams, type CreateRunResult, DEFAULT_INSTRUMENTS, DEFAULT_INSTRUMENTS_FOR_ROOT, Dashboard, type DashboardData, type Dataset, type DatasetEntry, type DatasetItem, type Dimension, DimensionField, type DimensionValue, EntryStatus, Evaluation, type EvaluationScore, type EvaluatorFunction, type Filter, type FilterConfig, FilterField, FilterType, FilteringSpanExporter, type GetPromptParams, GroupBy, InstrumentationSpanProcessor, type ListSpansParams, type ListTracesParams, Measure, type Metrics, Netra, NetraAgentsTracingProcessor, NetraInstruments, NetraOpenAIAgentsInstrumentor, type NumberResponse, Operator, type ProcessedFile, type PromptResponse, Prompts, type QueryDataParams, type QueryResponse, type Run, RunEntryContext, RunStatus, Scope, ScrubbingSpanProcessor, SessionSpanProcessor, type SessionUsageData, Simulation, type SimulationItem, type SimulationOptions, type SimulationResult, SpanIOProcessor, type SpanOptions, SpanType, type SpansPage, type TaskFunction, type TaskResult, type TenantUsageData, type TestSuiteResult, type TimeRange, type TimeSeriesDataPoint, type TimeSeriesResponse, type TimeSeriesWithDimension, type TraceSpan, type TraceSummary, type TracesPage, TrialAwareOTLPExporter, Usage, type UsageModel, agent, Netra as default, metadataField, mistralAIInstrumentor, netraExpressMiddleware, openaiAgentsInstrumentor, runWithExtractedContext, span, task, workflow };