netra-sdk 1.1.0-beta.1 → 1.2.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;
 }
 
 /**
@@ -1206,13 +1238,12 @@ declare class NetraMistralAIInstrumentor {
     instrumentationDependencies(): string[];
     /**
      * Instrument MistralAI client methods (async version)
-     * Uses dynamic import() to ensure we get the same ES module instance
-     * that the application uses.
+     * Tries both ESM and CJS resolution to cover dual-package setups.
      */
     instrumentAsync(options?: InstrumentorOptions$1): Promise<NetraMistralAIInstrumentor>;
     /**
      * Instrument MistralAI client methods (sync version - for backwards compatibility)
-     * Note: This uses a cached Mistral class. Call instrumentAsync() for proper initialization.
+     * Note: This uses cached Mistral classes. Call instrumentAsync() for proper initialization.
      */
     instrument(options?: InstrumentorOptions$1): NetraMistralAIInstrumentor;
     /**
@@ -1390,6 +1421,82 @@ declare class TrialAwareOTLPExporter implements SpanExporter {
     shutdown(): Promise<void>;
 }
 
+/**
+ * Public helpers for distributed tracing context propagation.
+ *
+ * These utilities let users extract incoming W3C Trace Context from HTTP
+ * headers and run code within that context so that all child spans (LLM
+ * calls, database queries, outgoing HTTP, etc.) are linked to the upstream
+ * trace.
+ *
+ * When `@opentelemetry/instrumentation-http` + `@opentelemetry/instrumentation-express`
+ * are installed and working, incoming context extraction happens automatically.
+ * These helpers cover cases where auto-instrumentation is unavailable (e.g.
+ * ESM module loading order issues, missing peer dependencies, or non-Express
+ * frameworks).
+ */
+
+/**
+ * Run a function within a context extracted from HTTP headers.
+ *
+ * All spans created inside `fn` will be children of the trace described by the
+ * incoming `traceparent` / `tracestate` headers, enabling end-to-end
+ * distributed tracing across service boundaries.
+ *
+ * @param headers - Incoming HTTP request headers (e.g. `req.headers`).
+ * @param fn      - The function to execute within the extracted context.
+ *                  May be sync or async -- the return value is forwarded as-is.
+ * @returns The return value of `fn`.
+ *
+ * @example
+ * ```ts
+ * import { runWithExtractedContext } from "netra";
+ *
+ * app.post("/api/chat", async (req, res) => {
+ *   await runWithExtractedContext(req.headers, async () => {
+ *     const result = await myAgent(req.body.message);
+ *     res.json(result);
+ *   });
+ * });
+ * ```
+ */
+declare function runWithExtractedContext<T>(headers: Record<string, string | string[] | undefined>, fn: () => T): T;
+/**
+ * Express/Connect-compatible middleware that extracts W3C Trace Context from
+ * incoming request headers and runs all downstream handlers within the
+ * extracted context.
+ *
+ * This is the recommended way to enable distributed tracing for Express
+ * servers when `@opentelemetry/instrumentation-http` is not available or not
+ * working (e.g. due to ESM module loading order with `tsx`). It is the
+ * TypeScript equivalent of the Python SDK's `NetraFastAPIMiddleware`.
+ *
+ * **Note:** In Express 4.x, async errors thrown inside downstream handlers are
+ * not automatically caught by the Express error handler. Wrap async route
+ * handlers with your own try/catch or use Express 5 which supports async
+ * error propagation natively.
+ *
+ * @returns An Express middleware function.
+ *
+ * @example
+ * ```ts
+ * import express from "express";
+ * import { netraExpressMiddleware } from "netra-sdk";
+ *
+ * const app = express();
+ * app.use(netraExpressMiddleware());
+ *
+ * app.post("/api/chat", async (req, res) => {
+ *   // Spans created here are children of the upstream trace
+ *   const result = await myAgent(req.body.message);
+ *   res.json(result);
+ * });
+ * ```
+ */
+declare function netraExpressMiddleware(): (req: {
+    headers: Record<string, string | string[] | undefined>;
+}, res: unknown, next: () => void) => void;
+
 /**
  * Netra SDK - Main entry point
  * A comprehensive TypeScript/JavaScript SDK for AI application observability
@@ -1453,4 +1560,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, openaiAgentsInstrumentor, 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;
 }
 
 /**
@@ -1206,13 +1238,12 @@ declare class NetraMistralAIInstrumentor {
     instrumentationDependencies(): string[];
     /**
      * Instrument MistralAI client methods (async version)
-     * Uses dynamic import() to ensure we get the same ES module instance
-     * that the application uses.
+     * Tries both ESM and CJS resolution to cover dual-package setups.
      */
     instrumentAsync(options?: InstrumentorOptions$1): Promise<NetraMistralAIInstrumentor>;
     /**
      * Instrument MistralAI client methods (sync version - for backwards compatibility)
-     * Note: This uses a cached Mistral class. Call instrumentAsync() for proper initialization.
+     * Note: This uses cached Mistral classes. Call instrumentAsync() for proper initialization.
      */
     instrument(options?: InstrumentorOptions$1): NetraMistralAIInstrumentor;
     /**
@@ -1390,6 +1421,82 @@ declare class TrialAwareOTLPExporter implements SpanExporter {
     shutdown(): Promise<void>;
 }
 
+/**
+ * Public helpers for distributed tracing context propagation.
+ *
+ * These utilities let users extract incoming W3C Trace Context from HTTP
+ * headers and run code within that context so that all child spans (LLM
+ * calls, database queries, outgoing HTTP, etc.) are linked to the upstream
+ * trace.
+ *
+ * When `@opentelemetry/instrumentation-http` + `@opentelemetry/instrumentation-express`
+ * are installed and working, incoming context extraction happens automatically.
+ * These helpers cover cases where auto-instrumentation is unavailable (e.g.
+ * ESM module loading order issues, missing peer dependencies, or non-Express
+ * frameworks).
+ */
+
+/**
+ * Run a function within a context extracted from HTTP headers.
+ *
+ * All spans created inside `fn` will be children of the trace described by the
+ * incoming `traceparent` / `tracestate` headers, enabling end-to-end
+ * distributed tracing across service boundaries.
+ *
+ * @param headers - Incoming HTTP request headers (e.g. `req.headers`).
+ * @param fn      - The function to execute within the extracted context.
+ *                  May be sync or async -- the return value is forwarded as-is.
+ * @returns The return value of `fn`.
+ *
+ * @example
+ * ```ts
+ * import { runWithExtractedContext } from "netra";
+ *
+ * app.post("/api/chat", async (req, res) => {
+ *   await runWithExtractedContext(req.headers, async () => {
+ *     const result = await myAgent(req.body.message);
+ *     res.json(result);
+ *   });
+ * });
+ * ```
+ */
+declare function runWithExtractedContext<T>(headers: Record<string, string | string[] | undefined>, fn: () => T): T;
+/**
+ * Express/Connect-compatible middleware that extracts W3C Trace Context from
+ * incoming request headers and runs all downstream handlers within the
+ * extracted context.
+ *
+ * This is the recommended way to enable distributed tracing for Express
+ * servers when `@opentelemetry/instrumentation-http` is not available or not
+ * working (e.g. due to ESM module loading order with `tsx`). It is the
+ * TypeScript equivalent of the Python SDK's `NetraFastAPIMiddleware`.
+ *
+ * **Note:** In Express 4.x, async errors thrown inside downstream handlers are
+ * not automatically caught by the Express error handler. Wrap async route
+ * handlers with your own try/catch or use Express 5 which supports async
+ * error propagation natively.
+ *
+ * @returns An Express middleware function.
+ *
+ * @example
+ * ```ts
+ * import express from "express";
+ * import { netraExpressMiddleware } from "netra-sdk";
+ *
+ * const app = express();
+ * app.use(netraExpressMiddleware());
+ *
+ * app.post("/api/chat", async (req, res) => {
+ *   // Spans created here are children of the upstream trace
+ *   const result = await myAgent(req.body.message);
+ *   res.json(result);
+ * });
+ * ```
+ */
+declare function netraExpressMiddleware(): (req: {
+    headers: Record<string, string | string[] | undefined>;
+}, res: unknown, next: () => void) => void;
+
 /**
  * Netra SDK - Main entry point
  * A comprehensive TypeScript/JavaScript SDK for AI application observability
@@ -1453,4 +1560,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, openaiAgentsInstrumentor, 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 };