netra-sdk 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,1243 @@
+import { Span, Context, TracerProvider } from '@opentelemetry/api';
+import { SpanProcessor, ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';
+import { ExportResultCode, ExportResult } from '@opentelemetry/core';
+
+/**
+ * Configuration management for Netra SDK
+ */
+interface NetraConfig {
+    appName?: string;
+    headers?: string | Record<string, string>;
+    disableBatch?: boolean;
+    traceContent?: boolean;
+    debugMode?: boolean;
+    enableRootSpan?: boolean;
+    resourceAttributes?: Record<string, any>;
+    environment?: string;
+    enableScrubbing?: boolean;
+    blockedSpans?: string[];
+    instruments?: Set<NetraInstruments>;
+    blockInstruments?: Set<NetraInstruments>;
+}
+declare enum NetraInstruments {
+    OPENAI = "openai",
+    GOOGLE_GENERATIVE_AI = "google_genai",
+    MISTRAL = "mistral",
+    GROQ = "groq",
+    VERTEX_AI = "vertexai",
+    TOGETHER = "together",
+    ANTHROPIC = "anthropic",
+    LANGCHAIN = "langchain",
+    LANGGRAPH = "langgraph",
+    LLAMA_INDEX = "llama_index",
+    PINECONE = "pinecone",
+    QDRANT = "qdrant",
+    CHROMADB = "chromadb",
+    HTTP = "http",
+    HTTPS = "https",
+    FETCH = "fetch",
+    PRISMA = "prisma",
+    TYPEORM = "typeorm",
+    MONGODB = "mongodb",
+    POSTGRES = "postgres",
+    MYSQL = "mysql",
+    REDIS = "redis",
+    EXPRESS = "express",
+    FASTIFY = "fastify",
+    NESTJS = "nestjs",
+    KAFKA = "kafka",
+    RABBITMQ = "rabbitmq"
+}
+declare class Config {
+    static readonly SDK_NAME = "netra";
+    static readonly LIBRARY_NAME = "netra";
+    static readonly LIBRARY_VERSION = "1.0.0";
+    static readonly TRIAL_BLOCK_DURATION_SECONDS = 900;
+    static readonly ATTRIBUTE_MAX_LEN: number;
+    static readonly CONVERSATION_MAX_LEN: number;
+    appName: string;
+    otlpEndpoint?: string;
+    apiKey?: string;
+    headers: Record<string, string>;
+    disableBatch: boolean;
+    traceContent: boolean;
+    debugMode: boolean;
+    enableRootSpan: boolean;
+    enableScrubbing: boolean;
+    environment: string;
+    resourceAttributes: Record<string, any>;
+    blockedSpans?: string[];
+    constructor(config?: NetraConfig);
+    private _getAppName;
+    private _getOtlpEndpoint;
+    private _parseHeaders;
+    private _parseEnvHeaders;
+    private _validateApiKey;
+    private _setupAuthentication;
+    private _getBoolConfig;
+    private _getResourceAttributes;
+    private _setTraceContentEnv;
+    /**
+     * Format the OTLP endpoint URL by appending /v1/traces if not already present
+     */
+    formatOtlpEndpoint(): any;
+    /**
+     * Set Traceloop environment variables based on Netra config.
+     * This ensures the Traceloop SDK picks up our configuration.
+     */
+    setTraceloopEnv(): void;
+}
+
+/**
+ * Dashboard API Models
+ */
+declare enum Scope {
+    SPANS = "Spans",
+    TRACES = "Traces"
+}
+declare enum ChartType {
+    LINE_TIME_SERIES = "Line Time Series",
+    BAR_TIME_SERIES = "Bar Time Series",
+    HORIZONTAL_BAR = "Horizontal Bar",
+    VERTICAL_BAR = "Vertical Bar",
+    PIE = "Pie",
+    NUMBER = "Number"
+}
+declare enum Measure {
+    LATENCY = "Latency",
+    ERROR_RATE = "Error Rate",
+    PII_COUNT = "PII Count",
+    REQUEST_COUNT = "Request Count",
+    TOTAL_COST = "Total Cost",
+    VIOLATIONS = "Violations",
+    TOTAL_TOKENS = "Total Tokens"
+}
+declare enum Aggregation {
+    AVERAGE = "Average",
+    P50 = "p50",
+    P90 = "p90",
+    P95 = "p95",
+    P99 = "p99",
+    MEDIAN = "Median (p50)",
+    PERCENTAGE = "Percentage",
+    TOTAL_COUNT = "Total Count"
+}
+declare enum GroupBy {
+    DAY = "day",
+    HOUR = "hour",
+    MINUTE = "minute"
+}
+declare enum DimensionField {
+    ENVIRONMENT = "environment",
+    SERVICE = "service",
+    MODEL_NAME = "model_name"
+}
+declare enum Operator {
+    EQUALS = "equals",
+    NOT_EQUALS = "not_equals",
+    CONTAINS = "contains",
+    NOT_CONTAINS = "not_contains",
+    STARTS_WITH = "starts_with",
+    ENDS_WITH = "ends_with",
+    GREATER_THAN = "greater_than",
+    LESS_THAN = "less_than",
+    GREATER_EQUAL_TO = "greater_equal_to",
+    LESS_EQUAL_TO = "less_equal_to",
+    ANY_OF = "any_of",
+    NONE_OF = "none_of"
+}
+declare enum FilterType {
+    STRING = "string",
+    NUMBER = "number",
+    BOOLEAN = "boolean",
+    ARRAY_OPTIONS = "arrayOptions",
+    OBJECT = "object"
+}
+declare enum FilterField {
+    TOTAL_COST = "total_cost",
+    SERVICE = "service",
+    TENANT_ID = "tenant_id",
+    USER_ID = "user_id",
+    SESSION_ID = "session_id",
+    ENVIRONMENT = "environment",
+    LATENCY = "latency",
+    MODEL_NAME = "model_name",
+    MODELS = "models",
+    METADATA = "metadata"
+}
+declare enum SessionFilterField {
+    TENANT_ID = "tenant_id"
+}
+declare enum SessionOperator {
+    ANY_OF = "any_of"
+}
+declare enum SessionFilterType {
+    ARRAY = "arrayOptions"
+}
+declare enum SortField {
+    SESSION_ID = "session_id",
+    START_TIME = "start_time",
+    TOTAL_REQUESTS = "totalRequests",
+    TOTAL_COST = "totalCost"
+}
+declare enum SortOrder {
+    ASC = "asc",
+    DESC = "desc"
+}
+/**
+ * Create a metadata filter field
+ * @param key The metadata key to filter on
+ * @returns The formatted metadata field string
+ * @example
+ * metadataField("customer_tier") // returns "metadata['customer_tier']"
+ */
+declare function metadataField(key: string): string;
+interface Filter {
+    field: FilterField | string;
+    operator: Operator;
+    type: FilterType;
+    value: any;
+    key?: string;
+}
+interface Metrics {
+    measure: Measure;
+    aggregation: Aggregation;
+}
+interface Dimension {
+    field: DimensionField;
+}
+interface FilterConfig {
+    startTime: string;
+    endTime: string;
+    groupBy: GroupBy;
+    filters?: Filter[];
+}
+interface TimeRange {
+    startTime: string;
+    endTime: string;
+}
+interface TimeSeriesDataPoint {
+    date: string;
+    value: number;
+}
+interface DimensionValue {
+    dimension: string;
+    value: number;
+}
+interface TimeSeriesWithDimension {
+    date: string;
+    values: DimensionValue[];
+}
+interface TimeSeriesResponse {
+    timeSeries: TimeSeriesWithDimension[];
+    dimensions: string[];
+}
+interface CategoricalDataPoint {
+    dimension: string;
+    value: number;
+}
+interface NumberResponse {
+    value: number;
+}
+type DashboardData = TimeSeriesDataPoint[] | TimeSeriesResponse | CategoricalDataPoint[] | NumberResponse | Record<string, any>;
+interface QueryResponse {
+    timeRange: TimeRange;
+    data: DashboardData;
+}
+interface QueryDataParams {
+    scope: Scope;
+    chartType: ChartType;
+    metrics: Metrics;
+    filter: FilterConfig;
+    dimension?: Dimension;
+}
+interface SessionFilter {
+    field: SessionFilterField;
+    operator: SessionOperator;
+    type: SessionFilterType;
+    value: string[];
+}
+interface SessionStatsResult {
+    data: SessionStatsData[];
+    hasNextPage: boolean;
+    nextCursor?: string;
+}
+interface SessionFilterConfig {
+    startTime: string;
+    endTime: string;
+    filters?: SessionFilter[];
+}
+interface SessionStatsData {
+    session_id: string;
+    session_start_time: string;
+    totalRequests: number;
+    totalCost: number;
+    session_duration: string;
+    cursor: string;
+}
+
+/**
+ * Public Dashboard API
+ * Exposed as Netra.dashboard
+ */
+
+declare class Dashboard {
+    private config;
+    private client;
+    constructor(config: Config);
+    /**
+     * Execute a dynamic query for dashboards to retrieve metrics and time-series data
+     * @param params Query parameters
+     * @returns Query response containing timeRange and data, or null on error
+     */
+    queryData(params: QueryDataParams): Promise<QueryResponse | null>;
+    getSessionStats(startTime: string, endTime: string, limit?: number, filters?: SessionFilter[], cursor?: string, sortField?: SortField, sortOrder?: SortOrder): Promise<SessionStatsResult | null>;
+    iterSessionStats(startTime: string, endTime: string, filters?: SessionFilter[], sortField?: SortField, sortOrder?: SortOrder): AsyncGenerator<SessionStatsData, void, unknown>;
+    getSessionSummary(filter: SessionFilterConfig): Promise<any | null>;
+    private isValidScope;
+    private isValidChartType;
+    private isValidMetrics;
+    private isValidFilterConfig;
+    private isValidDimension;
+    private isSessionFilterConfig;
+}
+
+/**
+ * Evaluation API Models
+ */
+interface DatasetEntry {
+    id: string;
+    input: string;
+    datasetId: string;
+    expectedOutput?: any;
+}
+interface DatasetItem {
+    input: any;
+    expectedOutput?: any;
+    metadata?: Record<string, any>;
+    tags?: string[];
+}
+interface DatasetRecord {
+    id: string;
+    input: any;
+    datasetId: string;
+    expectedOutput?: any;
+}
+interface Dataset {
+    items: DatasetItem[] | DatasetRecord[];
+}
+interface Run {
+    id: string;
+    datasetId: string;
+    name?: string;
+    testEntries: DatasetItem[];
+}
+interface EvaluationScore {
+    metricType: string;
+    score: number;
+}
+declare enum EntryStatus {
+    AGENT_TRIGGERED = "agent_triggered",
+    AGENT_COMPLETED = "agent_completed",
+    FAILED = "failed"
+}
+declare enum RunStatus {
+    COMPLETED = "completed"
+}
+interface CreateDatasetParams {
+    name: string;
+    tags?: string[];
+}
+interface TestSuiteResult {
+    success: boolean;
+    runId?: string;
+    error?: string;
+    results?: Array<{
+        id: string;
+        input: string;
+        output: any;
+        status: string;
+        error?: string;
+    }>;
+}
+declare enum ScoreType {
+    BOOLEAN = "boolean",
+    NUMERICAL = "numerical",
+    CATEGORICAL = "categorical"
+}
+interface EvaluatorConfig {
+    name: string;
+    label: string;
+    scoreType: ScoreType;
+}
+interface AddDatasetItemResponse {
+    datasetId: string;
+    projectId: string;
+    organizationId: string;
+    source: string;
+    input: any;
+    expectedOutput?: any;
+    isActive: boolean;
+    tags?: string[];
+    createdBy: string;
+    updatedBy: string;
+    updatedAt: string;
+    sourceId?: string;
+    metadata?: Record<string, any>;
+    id: string;
+    createdAt?: string;
+    deletedAt?: string;
+}
+interface CreateDatasetResponse {
+    projectId: string;
+    organizationId: string;
+    name: string;
+    tags?: string[];
+    createdBy: string;
+    updatedBy: string;
+    updatedAt: string;
+    id: string;
+    createdAt: string;
+    deletedAt?: string | null;
+}
+interface GetDatasetItemsResponse {
+    items: DatasetRecord[];
+}
+type EvaluatorFunction = (params: {
+    input: string;
+    output: any;
+    expectedOutput?: any;
+}) => EvaluationScore | EvaluationScore[] | Promise<EvaluationScore | EvaluationScore[]>;
+type TaskFunction = (input: any) => any | Promise<any>;
+
+/**
+ * Public Evaluation API
+ * Exposed as Netra.evaluation
+ */
+
+/**
+ * Public entry-point exposed as Netra.evaluation
+ */
+declare class Evaluation {
+    private config;
+    private client;
+    constructor(config: Config);
+    /**
+     * Create an empty dataset and return its id on success, else null
+     * @param name The name of the dataset
+     * @param tags Optional list of tags to associate with the dataset
+     * @returns A backend JSON response containing dataset info (id, name, tags, etc.) on success
+     */
+    createDataset(name: string, tags?: string[]): Promise<CreateDatasetResponse | null>;
+    /**
+     * Add a single item to an existing dataset
+     * @param datasetId The id of the dataset to which the item will be added
+     * @param item The dataset item to add
+     * @returns A backend JSON response containing dataset item info (id, input, expectedOutput, etc.) on success
+     */
+    addDatasetItem(datasetId: string, item: DatasetEntry): Promise<AddDatasetItemResponse | null>;
+    /**
+     * Get a dataset by ID
+     * @param datasetId The id of the dataset to retrieve
+     * @returns A backend JSON response containing dataset info (id, input, expectedOutput etc.) on success
+     */
+    getDataset(datasetId: string): Promise<GetDatasetItemsResponse | null>;
+    /**
+     * Create a new run for the given dataset and evaluators
+     * @param name The name of the run
+     * @param datasetId The id of the dataset to which the run will be associated
+     * @param evaluatorsConfig Optional list of evaluators to be used for the run
+     * @returns runId: The id of the created run
+     */
+    createRun(name: string, datasetId?: string, evaluatorsConfig?: EvaluatorConfig[]): Promise<string | null>;
+    /**
+     * Netra evaluation function to initiate a test suite
+     * @param name The name of the run
+     * @param data The dataset to be used for the test suite
+     * @param task The task to be executed for each item in the dataset
+     * @param evaluators Optional list of evaluators to be used for the test suite
+     * @param maxConcurrency The maximum number of concurrent tasks to be executed
+     * @returns A dictionary containing the run id and the results of the test suite
+     */
+    runTestSuite(name: string, data: Dataset, task: TaskFunction, evaluators?: any[], maxConcurrency?: number): Promise<Record<string, any> | null>;
+    /**
+     * Async implementation of runTestSuite
+     * @param name The name of the run
+     * @param data The dataset to be used for the test suite
+     * @param task The task to be executed for each item in the dataset
+     * @param evaluators Optional list of evaluators to be used for the test suite
+     * @param maxConcurrency The maximum number of concurrent tasks to be executed
+     * @returns items: The results of the test suite
+     */
+    private runTestSuiteAsync;
+    /**
+     * Create an ItemContext from a dataset item
+     * @param idx The index of the item
+     * @param item The dataset item
+     * @returns ItemContext: The created ItemContext
+     */
+    private createItemContext;
+    /**
+     * Type guard for DatasetRecord
+     */
+    private isDatasetRecord;
+    /**
+     * Execute the full pipeline for a single item
+     * @param runId The run ID
+     * @param runName The name of the run
+     * @param ctx The item context
+     * @param task The task function to execute
+     * @param evaluators Optional list of evaluators
+     * @param results List to append results to
+     * @param bgEvalTasks List to append background evaluation tasks to
+     */
+    private executeItemPipeline;
+    /**
+     * Post agent_triggered status and return testRunItemId
+     * @param runId The run ID
+     * @param ctx The item context
+     * @returns str: The testRunItemId
+     */
+    private postTriggeredStatus;
+    /**
+     * Post completed/failed status with task output
+     * @param runId The run ID
+     * @param ctx The item context
+     */
+    private postCompletedStatus;
+    /**
+     * Run all evaluators for a single item after span ingestion
+     * @param runId The run ID
+     * @param ctx The item context
+     * @param evaluators List of evaluators
+     */
+    private runEvaluatorsForItem;
+}
+
+/**
+ * Base HTTP client for Netra API calls
+ */
+
+interface HttpResponse<T = any> {
+    data: T;
+    status: number;
+    ok: boolean;
+}
+declare class NetraHttpClient {
+    private baseUrl;
+    private headers;
+    private timeout;
+    private initialized;
+    constructor(config: Config, timeoutEnvVar: string, defaultTimeout: number);
+    private resolveBaseUrl;
+    private buildHeaders;
+    private getTimeout;
+    isInitialized(): boolean;
+    get<T = any>(path: string, params?: Record<string, string | number | undefined>): Promise<HttpResponse<T>>;
+    post<T = any>(path: string, body?: Record<string, any>): Promise<HttpResponse<T>>;
+    /**
+     * Extract data from nested response format
+     * Netra API typically returns { data: { data: actualData } }
+     */
+    extractData<T>(response: HttpResponse<any>, defaultValue: T): T;
+}
+
+/**
+ * Internal HTTP client for Evaluation APIs
+ */
+
+declare class EvaluationHttpClient extends NetraHttpClient {
+    constructor(config: Config);
+    /**
+     * Fetch dataset items for a dataset id
+     */
+    getDataset(datasetId: string): Promise<any[]>;
+    /**
+     * Create a run for a dataset
+     */
+    createRun(name: string, datasetId?: string, evaluatorsConfig?: Record<string, any>[]): Promise<any>;
+    /**
+     * Create an empty dataset and return backend data
+     */
+    createDataset(name: string, tags?: string[]): Promise<any>;
+    /**
+     * Add a single item to an existing dataset
+     */
+    addDatasetItem(datasetId: string, itemPayload: Record<string, any>): Promise<any>;
+    /**
+     * Submit a new run item to the backend
+     */
+    postRunItem(runId: string, payload: Record<string, any>): Promise<any>;
+    /**
+     * Submit local evaluations result
+     */
+    submitLocalEvaluations(runId: string, testRunItemId: string, evaluatorResults: Array<Record<string, any>>): Promise<any>;
+    /**
+     * Submit the run status
+     */
+    postRunStatus(runId: string, status: string): Promise<any>;
+    /**
+     * Check if a span exists in the backend
+     */
+    getSpanById(spanId: string): Promise<any>;
+    /**
+     * Wait until a span is available in the backend
+     * Polls the GET /spans/:id endpoint to verify span availability before running evaluators
+     */
+    waitForSpanIngestion(spanId?: string, timeoutSeconds?: number, pollIntervalSeconds?: number, initialDelaySeconds?: number): Promise<boolean>;
+}
+
+/**
+ * Run Entry Context for Evaluation
+ * Provides context management for evaluation run entries
+ */
+
+declare class RunEntryContext {
+    private client;
+    private config;
+    readonly evaluationRun: Run;
+    readonly entry: DatasetEntry;
+    traceId?: string;
+    private span?;
+    private startTime?;
+    constructor(client: EvaluationHttpClient, config: Config, run: Run, entry: DatasetEntry);
+    /**
+     * Get the run associated with this context
+     * Alias for evaluationRun for backwards compatibility
+     */
+    get run(): Run;
+    /**
+     * Start the run entry context
+     * Creates a span and posts agent_triggered status
+     */
+    start(): Promise<void>;
+    /**
+     * End the run entry context
+     * @param success Whether the entry completed successfully
+     * @param scores Optional scores to record
+     */
+    end(success?: boolean, scores?: EvaluationScore[]): Promise<void>;
+    /**
+     * Get the current span
+     */
+    getSpan(): Span | undefined;
+    /**
+     * Execute a function within this context
+     * Automatically handles start/end and error handling
+     */
+    execute<T>(fn: (ctx: RunEntryContext) => Promise<T>, scores?: EvaluationScore[]): Promise<T>;
+}
+
+/**
+ * Usage API Models
+ */
+interface SessionUsageData {
+    sessionId: string;
+    tokenCount: number;
+    requestCount: number;
+    totalCost: number;
+}
+interface TenantUsageData {
+    tenantId: string;
+    organisationId: string;
+    tokenCount: number;
+    requestCount: number;
+    sessionCount: number;
+    totalCost: number;
+}
+interface TraceSummary {
+    id: string;
+    name: string;
+    kind: string;
+    latencyMs: number;
+    startTime: string;
+    endTime: string;
+    cursor: string;
+    organisationId: string;
+    projectId: string;
+    sessionId?: string;
+    tenantId?: string;
+    userId?: string;
+    environment?: string;
+    models?: string[];
+    promptTokens?: number;
+    completionTokens?: number;
+    cachedTokens?: number;
+    totalTokens?: number;
+    promptTokensCost?: number;
+    completionTokensCost?: number;
+    cachedTokensCost?: number;
+    totalCost?: number;
+    hasPii?: boolean;
+    piiEntities?: any[];
+    hasViolation?: boolean;
+    violations?: any[];
+    hasError?: boolean;
+    service?: string;
+}
+interface TracesPage {
+    traces: TraceSummary[];
+    hasNextPage: boolean;
+    nextCursor?: string;
+}
+interface TraceSpan {
+    id: string;
+    traceId: string;
+    name: string;
+    kind: string;
+    parentSpanId?: string;
+    latencyMs?: number;
+    startTimeMs?: string;
+    endTimeMs?: string;
+    organisationId: string;
+    projectId: string;
+    sessionId?: string;
+    tenantId?: string;
+    userId?: string;
+    environment?: string;
+    modelName?: string;
+    promptTokens?: number;
+    completionTokens?: number;
+    cachedTokens?: number;
+    totalTokens?: number;
+    promptTokensCost?: number;
+    completionTokensCost?: number;
+    cachedTokensCost?: number;
+    totalCost?: number;
+    hasPii?: boolean;
+    piiEntities?: any[];
+    piiActions?: Record<string, any>;
+    hasViolation?: boolean;
+    violations?: any[];
+    violationActions?: Record<string, any>;
+    status?: string;
+    attributes?: string;
+    events?: string;
+    links?: string;
+    resources?: string;
+    metadata?: Record<string, any>;
+    hasError?: boolean;
+    createdAt: string;
+    cursor: string;
+}
+interface SpansPage {
+    spans: TraceSpan[];
+    hasNextPage: boolean;
+    nextCursor?: string;
+}
+interface ListTracesParams {
+    startTime: string;
+    endTime: string;
+    traceId?: string;
+    sessionId?: string;
+    userId?: string;
+    tenantId?: string;
+    limit?: number;
+    cursor?: string;
+    direction?: "up" | "down";
+    sortField?: string;
+    sortOrder?: "asc" | "desc";
+}
+interface ListSpansParams {
+    traceId: string;
+    cursor?: string;
+    direction?: "up" | "down";
+    limit?: number;
+    spanName?: string;
+}
+
+/**
+ * Public Usage API
+ * Exposed as Netra.usage
+ */
+
+declare class Usage {
+    private config;
+    private client;
+    constructor(config: Config);
+    /**
+     * Get session usage data
+     * @param sessionId Session identifier
+     * @param startTime Start time for the usage data (in ISO 8601 UTC format)
+     * @param endTime End time for the usage data (in ISO 8601 UTC format)
+     * @returns Session usage data or null on error
+     */
+    getSessionUsage(sessionId: string, startTime: string, endTime: string): Promise<SessionUsageData | null>;
+    /**
+     * Get tenant usage data
+     * @param tenantId Tenant identifier
+     * @param startTime Start time for the usage data (in ISO 8601 UTC format)
+     * @param endTime End time for the usage data (in ISO 8601 UTC format)
+     * @returns Tenant usage data or null on error
+     */
+    getTenantUsage(tenantId: string, startTime: string, endTime: string): Promise<TenantUsageData | null>;
+    /**
+     * List all traces
+     * @param params List traces parameters
+     * @returns Traces page or null on error
+     */
+    listTraces(params: ListTracesParams): Promise<TracesPage | null>;
+    /**
+     * List all spans for a given trace
+     * @param params List spans parameters
+     * @returns Spans page or null on error
+     */
+    listSpansByTraceId(params: ListSpansParams): Promise<SpansPage | null>;
+    /**
+     * Iterate over traces using cursor-based pagination
+     * @param params List traces parameters
+     * @returns Async generator yielding TraceSummary items
+     */
+    iterTraces(params: ListTracesParams): AsyncGenerator<TraceSummary, void, unknown>;
+    /**
+     * Iterate over spans for a given trace using cursor-based pagination
+     * @param params List spans parameters
+     * @returns Async generator yielding TraceSpan items
+     */
+    iterSpansByTraceId(params: ListSpansParams): AsyncGenerator<TraceSpan, void, unknown>;
+    private mapToTraceSummary;
+    private mapToTraceSpan;
+}
+
+/**
+ * Session Manager for tracking user sessions and context
+ *
+ * Uses AsyncLocalStorage for entity stacks (workflow, task, agent)
+ * and OpenTelemetry's baggage API for session context (session_id, user_id, tenant_id).
+ * This provides proper concurrency support for multi-request environments.
+ */
+
+declare enum ConversationType {
+    INPUT = "input",
+    OUTPUT = "output"
+}
+
+/**
+ * Type definitions for Netra SDK
+ */
+declare enum SpanType {
+    SPAN = "SPAN",
+    GENERATION = "GENERATION",
+    TOOL = "TOOL",
+    EMBEDDING = "EMBEDDING",
+    AGENT = "AGENT"
+}
+interface UsageModel {
+    model: string;
+    usage_type: string;
+    units_used?: number;
+    cost_in_usd?: number;
+}
+interface ActionModel {
+    start_time: string;
+    action: string;
+    action_type: string;
+    success: boolean;
+    affected_records?: Array<{
+        record_id: string;
+        record_type: string;
+    }>;
+    metadata?: Record<string, string>;
+}
+interface DecoratorOptions {
+    name?: string;
+    asType?: SpanType;
+}
+
+/**
+ * Span Wrapper for custom span tracking
+ */
+
+declare class SpanWrapper {
+    private name;
+    private attributes;
+    private moduleName;
+    private startTime?;
+    private endTime?;
+    private status;
+    private errorMessage?;
+    private span?;
+    private activeContext?;
+    private tracer?;
+    constructor(name: string, attributes?: Record<string, string>, moduleName?: string, asType?: SpanType, tracer?: any);
+    start(): this;
+    end(): this;
+    setAttribute(key: string, value: string): this;
+    /**
+     * Run a function with this span set as the active span in the OTel context.
+     * Useful for nesting spans.
+     */
+    withActive<T>(fn: () => T): T;
+    /**
+     * Async version of withActive(). Keeps the context active across async work.
+     */
+    withActiveAsync<T>(fn: () => Promise<T>): Promise<T>;
+    setPrompt(prompt: string): this;
+    setNegativePrompt(negativePrompt: string): this;
+    setUsage(usage: UsageModel[]): this;
+    setAction(action: ActionModel[]): this;
+    setModel(model: string): this;
+    setLlmSystem(system: string): this;
+    setError(errorMessage: string): this;
+    setSuccess(): this;
+    addEvent(name: string, attributes?: Record<string, string>): this;
+    getCurrentSpan(): Span | undefined;
+}
+
+declare function withBlockedSpansLocal<T>(patterns: readonly string[], fn: () => Promise<T> | T): Promise<T>;
+
+/**
+ * Decorators for easy instrumentation
+ */
+
+type AnyFunction = (...args: any[]) => any;
+declare function workflow<T extends AnyFunction>(target: T, options?: DecoratorOptions): T;
+declare function workflow<T extends AnyFunction>(options?: DecoratorOptions): (target: T) => T;
+declare function agent<T extends AnyFunction>(target: T, options?: DecoratorOptions): T;
+declare function agent<T extends AnyFunction>(options?: DecoratorOptions): (target: T) => T;
+declare function task<T extends AnyFunction>(target: T, options?: DecoratorOptions): T;
+declare function task<T extends AnyFunction>(options?: DecoratorOptions): (target: T) => T;
+declare function span<T extends AnyFunction>(target: T, options?: DecoratorOptions): T;
+declare function span<T extends AnyFunction>(options?: DecoratorOptions): (target: T) => T;
+
+/**
+ * Session Span Processor
+ *
+ * OpenTelemetry span processor that automatically adds session attributes to spans.
+ * This includes session_id, user_id, tenant_id from OpenTelemetry baggage, and entity context
+ * (workflow, task, agent names) from SessionManager.
+ *
+ * Uses OpenTelemetry's baggage API for automatic context propagation across async boundaries.
+ */
+
+declare class SessionSpanProcessor implements SpanProcessor {
+    /**
+     * Called when a span starts. Adds session and entity context attributes.
+     */
+    onStart(span: Span, parentContext: Context): void;
+    /**
+     * Called when a span ends. No-op for this processor.
+     */
+    onEnd(span: ReadableSpan): void;
+    /**
+     * Shuts down the processor.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Forces a flush of any pending spans.
+     */
+    forceFlush(): Promise<void>;
+}
+
+/**
+ * Instrumentation Span Processor
+ *
+ * OpenTelemetry span processor that:
+ * 1. Records the raw instrumentation scope name for each span
+ * 2. Truncates attribute values to prevent oversized payloads
+ */
+
+declare class InstrumentationSpanProcessor implements SpanProcessor {
+    private maxAttributeLength;
+    constructor(maxAttributeLength?: number);
+    /**
+     * Detect the raw instrumentation name from the span's instrumentation scope.
+     */
+    private detectRawInstrumentationName;
+    /**
+     * Truncate a value to the maximum allowed length.
+     * Handles strings, bytes, and recursively handles lists and objects.
+     */
+    private truncateValue;
+    /**
+     * Called when a span starts. Wraps setAttribute to truncate values
+     * and records the instrumentation name.
+     */
+    onStart(span: Span, parentContext: Context): void;
+    /**
+     * Called when a span ends. No-op for this processor.
+     */
+    onEnd(span: ReadableSpan): void;
+    /**
+     * Shuts down the processor.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Forces a flush of any pending spans.
+     */
+    forceFlush(): Promise<void>;
+}
+
+/**
+ * Scrubbing Span Processor
+ *
+ * OpenTelemetry span processor that scrubs sensitive data from span attributes.
+ * This includes API keys, emails, phone numbers, SSNs, credit cards, passwords,
+ * bearer tokens, and other sensitive information.
+ */
+
+declare class ScrubbingSpanProcessor implements SpanProcessor {
+    /**
+     * Check if a key is considered sensitive.
+     */
+    private isSensitiveKey;
+    /**
+     * Scrub sensitive patterns from a string value.
+     */
+    private scrubStringValue;
+    /**
+     * Recursively scrub sensitive data from a dictionary value.
+     */
+    private scrubDictValue;
+    /**
+     * Recursively scrub sensitive data from a list value.
+     */
+    private scrubListValue;
+    /**
+     * Scrub sensitive data from a key-value pair.
+     */
+    private scrubKeyValue;
+    /**
+     * Called when a span starts. No-op for this processor.
+     */
+    onStart(span: Span, parentContext: Context): void;
+    /**
+     * Called when a span ends. Scrubs sensitive data from span attributes.
+     */
+    onEnd(span: ReadableSpan): void;
+    /**
+     * Shuts down the processor.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Forces a flush of any pending spans.
+     */
+    forceFlush(): Promise<void>;
+}
+
+/**
+ * Custom MistralAI instrumentor for Netra SDK
+ *
+ * Note: '@mistralai/mistralai' is a peer dependency. The SDK dynamically imports it
+ * to ensure we patch the same module instance the application uses.
+ */
+
+interface InstrumentorOptions {
+    tracerProvider?: TracerProvider;
+}
+/**
+ * Custom MistralAI instrumentor for Netra SDK
+ */
+declare class NetraMistralAIInstrumentor {
+    private tracer;
+    private tracerProvider?;
+    private resourceCtors;
+    constructor();
+    /**
+     * Returns the list of instrumentation dependencies
+     */
+    instrumentationDependencies(): string[];
+    /**
+     * Instrument MistralAI client methods (async version)
+     * Uses dynamic import() to ensure we get the same ES module instance
+     * that the application uses.
+     */
+    instrumentAsync(options?: InstrumentorOptions): Promise<NetraMistralAIInstrumentor>;
+    /**
+     * Instrument MistralAI client methods (sync version - for backwards compatibility)
+     * Note: This uses a cached Mistral class. Call instrumentAsync() for proper initialization.
+     */
+    instrument(options?: InstrumentorOptions): NetraMistralAIInstrumentor;
+    /**
+     * Uninstrument MistralAI client methods
+     */
+    uninstrument(): void;
+    /**
+     * Check if MistralAI is currently instrumented
+     */
+    isInstrumented(): boolean;
+    /**
+     * Resolve public resource constructors from the exported Mistral client.
+     * This avoids relying on internal "@mistralai/mistralai/sdk/*" paths.
+     *
+     * We create a temporary client instance purely for discovery; it should not
+     * make network calls.
+     */
+    private _ensureResourceCtors;
+    private _getCtor;
+    private _instrumentChat;
+    private _instrumentEmbeddings;
+    private _instrumentFIM;
+    private _instrumentAgents;
+    private _uninstrumentChat;
+    private _uninstrumentEmbeddings;
+    private _uninstrumentFIM;
+    private _uninstrumentAgents;
+}
+declare const mistralAIInstrumentor: NetraMistralAIInstrumentor;
+
+declare class FilteringSpanExporter implements SpanExporter {
+    private readonly exporter;
+    private exact;
+    private prefixes;
+    private suffixes;
+    private rememberedBlockedParentMap;
+    constructor(exporter: SpanExporter, patterns: string[]);
+    export(spans: ReadableSpan[], resultCallback: (result: {
+        code: ExportResultCode;
+    }) => void): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+    private isBlocked;
+    private matchesLocalPatterns;
+    private hasLocalBlockFlag;
+    private reparentBlockedChildren;
+}
+
+interface ExporterConfig {
+    url: string;
+    headers?: Record<string, string>;
+}
+declare class TrialAwareOTLPExporter implements SpanExporter {
+    private _url;
+    private _headers;
+    private _isShutdown;
+    constructor(config: ExporterConfig);
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    private checkErrorBody;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+/**
+ * Netra SDK - Main entry point
+ * A comprehensive TypeScript/JavaScript SDK for AI application observability
+ * Built on top of OpenTelemetry and Traceloop
+ */
+
+declare class Netra {
+    private static _initialized;
+    private static _config;
+    private static _tracer;
+    /**
+     * Usage API client for usage and traces
+     * Available after calling Netra.init()
+     */
+    static usage: Usage;
+    /**
+     * Evaluation API client for datasets, runs, and test suites
+     * Available after calling Netra.init()
+     */
+    static evaluation: Evaluation;
+    /**
+     * Dashboard API client for querying metrics and time-series data
+     * Available after calling Netra.init()
+     */
+    static dashboard: Dashboard;
+    /**
+     * Check if Netra has been initialized
+     */
+    static isInitialized(): boolean;
+    /**
+     * Initialize the Netra SDK
+     * Note: Custom instrumentations (OpenAI, Groq, MistralAI) are initialized
+     * asynchronously. Use initAsync() or await Netra.ready() to ensure
+     * instrumentations are complete before using instrumented modules.
+     */
+    static init(config?: NetraConfig): void;
+    /**
+     * Initialize the Netra SDK and wait for all instrumentations to be ready.
+     * This is the recommended way to initialize Netra when using ES modules,
+     * as it ensures all async instrumentations (OpenAI, Groq, MistralAI) are
+     * complete before the application starts using the instrumented modules.
+     *
+     * @example
+     * await Netra.initAsync({ appName: 'my-app', instruments: new Set([NetraInstruments.OPENAI]) });
+     * // Now OpenAI is fully instrumented
+     * const openai = new OpenAI();
+     */
+    static initAsync(config?: NetraConfig): Promise<void>;
+    /**
+     * Returns a promise that resolves when all async instrumentations are ready.
+     * Can be called after init() to wait for instrumentations.
+     *
+     * @example
+     * Netra.init({ appName: 'my-app' });
+     * await Netra.ready();
+     * // Now all instrumentations are complete
+     */
+    static ready(): Promise<void>;
+    /**
+     * Optional cleanup to end the root span and uninstrument all.
+     * Now async to ensure spans are flushed.
+     */
+    static shutdown(): Promise<void>;
+    /**
+     * Run a function with the root span as the active parent context.
+     * All spans created within this function will be children of the root span.
+     *
+     * @param fn The function to run within the root span context
+     * @returns The result of the function
+     */
+    static runWithRootSpan<T>(fn: () => T): T;
+    /**
+     * Run an async function with the root span as the active parent context.
+     * All spans created within this function will be children of the root span.
+     *
+     * @param fn The async function to run within the root span context
+     * @returns A promise that resolves with the result of the function
+     */
+    static runWithRootSpanAsync<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Run a function within an isolated entity context.
+     * This ensures that entity stacks (workflow, task, agent, span) are isolated
+     * per request in concurrent environments.
+     *
+     * Note: Session context (session_id, user_id, tenant_id) is automatically
+     * isolated via OpenTelemetry's baggage API and AsyncLocalStorage.
+     * This method is primarily needed if you're using workflow/task/agent decorators
+     * or span wrappers in concurrent environments.
+     *
+     * @param fn The function to run with isolated entity context
+     * @returns The result of the function
+     *
+     */
+    static runWithContext<T>(fn: () => T): T;
+    /**
+     * Set session_id context attributes for all spans.
+     * Uses OpenTelemetry baggage API for automatic context propagation.
+     *
+     * Context automatically propagates across async boundaries in concurrent environments
+     * thanks to AsyncLocalStorage in @opentelemetry/sdk-node.
+     */
+    static setSessionId(sessionId: string): void;
+    /**
+     * Set user_id context attributes for all spans.
+     * Uses OpenTelemetry baggage API for automatic context propagation.
+     */
+    static setUserId(userId: string): void;
+    /**
+     * Set tenant_id context attributes for all spans.
+     * Uses OpenTelemetry baggage API for automatic context propagation.
+     */
+    static setTenantId(tenantId: string): void;
+    /**
+     * Set a custom attribute on the current active span
+     */
+    static setCustomAttributes(key: string, value: any): void;
+    /**
+     * Set custom event in the current active span
+     */
+    static setCustomEvent(eventName: string, attributes: Record<string, any>): void;
+    /**
+     * Append a conversation entry to the current active span
+     */
+    static addConversation(conversationType: ConversationType, role: string, content: string | Record<string, any>): void;
+    /**
+     * Start a new span
+     */
+    static startSpan(name: string, attributes?: Record<string, string>, moduleName?: string, asType?: SpanType): SpanWrapper;
+    static withBlockedSpansLocal: typeof withBlockedSpansLocal;
+}
+
+export { type ActionModel, Aggregation, type CategoricalDataPoint, ChartType, Config, ConversationType, type CreateDatasetParams, 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, GroupBy, InstrumentationSpanProcessor, type ListSpansParams, type ListTracesParams, Measure, type Metrics, Netra, NetraInstruments, type NumberResponse, Operator, type QueryDataParams, type QueryResponse, type Run, RunEntryContext, RunStatus, Scope, ScrubbingSpanProcessor, SessionSpanProcessor, type SessionUsageData, SpanType, type SpansPage, type TaskFunction, 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, span, task, workflow };