@observyze/sdk 0.1.0 → 0.1.3

package/dist/index.js

@@ -0,0 +1,1282 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ObservyzeClient: () => ObservyzeClient,
+  ObservyzeSpanExporter: () => ObservyzeSpanExporter,
+  Span: () => Span,
+  SpanType: () => import_types.SpanType,
+  Trace: () => Trace,
+  TraceStatus: () => import_types.TraceStatus,
+  wrap: () => wrap,
+  wrapAnthropic: () => wrapAnthropic,
+  wrapOpenAI: () => wrapOpenAI
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_debug3 = __toESM(require("debug"));
+
+// src/types.ts
+var import_types = require("@observyze/types");
+
+// src/trace.ts
+var import_crypto = require("crypto");
+function generateId() {
+  return `${Date.now()}-${(0, import_crypto.randomUUID)().substring(0, 8)}`;
+}
+var Span = class {
+  data;
+  startTime;
+  constructor(name, type, parentSpanId) {
+    this.startTime = Date.now();
+    this.data = {
+      span_id: generateId(),
+      parent_span_id: parentSpanId,
+      name,
+      type,
+      start_time: new Date(this.startTime),
+      end_time: new Date(this.startTime),
+      // Will be updated on end()
+      duration_ms: 0,
+      input: null,
+      output: null,
+      metadata: {}
+    };
+  }
+  /**
+   * Set the input data for this span
+   */
+  setInput(input) {
+    this.data.input = input;
+    return this;
+  }
+  /**
+   * Set the output data for this span
+   */
+  setOutput(output) {
+    this.data.output = output;
+    return this;
+  }
+  /**
+   * Record an error that occurred during span execution
+   */
+  setError(error) {
+    this.data.error = {
+      message: error.message,
+      stack: error.stack,
+      code: error.code
+    };
+    return this;
+  }
+  /**
+   * Set metadata for this span
+   */
+  setMetadata(key, value) {
+    this.data.metadata[key] = value;
+    return this;
+  }
+  /**
+   * Set multiple metadata fields at once
+   */
+  setMetadataAll(metadata) {
+    this.data.metadata = { ...this.data.metadata, ...metadata };
+    return this;
+  }
+  /**
+   * Set token usage information
+   */
+  setTokens(tokens) {
+    this.data.tokens = tokens;
+    return this;
+  }
+  /**
+   * End the span and calculate duration
+   */
+  end() {
+    const endTime = Date.now();
+    this.data.end_time = new Date(endTime);
+    this.data.duration_ms = endTime - this.startTime;
+  }
+  /**
+   * Get the span ID
+   */
+  get id() {
+    return this.data.span_id;
+  }
+  /**
+   * Get the span data for serialization
+   */
+  toJSON() {
+    return { ...this.data };
+  }
+};
+var Trace = class {
+  data;
+  startTime;
+  spans = [];
+  ended = false;
+  constructor(name, organizationId, projectId) {
+    this.startTime = Date.now();
+    this.data = {
+      trace_id: generateId(),
+      organization_id: organizationId,
+      project_id: projectId,
+      name,
+      status: import_types.TraceStatus.RUNNING,
+      start_time: new Date(this.startTime),
+      end_time: new Date(this.startTime),
+      // Will be updated on end()
+      duration_ms: 0,
+      metadata: {},
+      spans: [],
+      tags: []
+    };
+  }
+  /**
+   * Start a new span within this trace
+   */
+  startSpan(name, type, parentSpanId) {
+    if (this.ended) {
+      throw new Error("Cannot start span on an ended trace");
+    }
+    const span = new Span(name, type, parentSpanId);
+    this.spans.push(span);
+    return span;
+  }
+  /**
+   * Add metadata to the trace
+   */
+  setMetadata(key, value) {
+    this.data.metadata[key] = value;
+    return this;
+  }
+  /**
+   * Set multiple metadata fields at once
+   */
+  setMetadataAll(metadata) {
+    this.data.metadata = { ...this.data.metadata, ...metadata };
+    return this;
+  }
+  /**
+   * Add tags to the trace
+   */
+  addTag(tag) {
+    if (!this.data.tags.includes(tag)) {
+      this.data.tags.push(tag);
+    }
+    return this;
+  }
+  /**
+   * Add multiple tags at once
+   */
+  addTags(tags) {
+    tags.forEach((tag) => this.addTag(tag));
+    return this;
+  }
+  /**
+   * Set the user ID associated with this trace
+   */
+  setUserId(userId) {
+    this.data.user_id = userId;
+    return this;
+  }
+  /**
+   * Set the session ID associated with this trace
+   */
+  setSessionId(sessionId) {
+    this.data.session_id = sessionId;
+    return this;
+  }
+  /**
+   * End the trace with a final status
+   */
+  end(status = import_types.TraceStatus.SUCCESS) {
+    if (this.ended) {
+      return;
+    }
+    const endTime = Date.now();
+    this.data.end_time = new Date(endTime);
+    this.data.duration_ms = endTime - this.startTime;
+    this.data.status = status;
+    this.data.spans = this.spans.map((span) => span.toJSON());
+    this.ended = true;
+  }
+  /**
+   * Get the trace ID
+   */
+  get id() {
+    return this.data.trace_id;
+  }
+  /**
+   * Check if the trace has ended
+   */
+  get isEnded() {
+    return this.ended;
+  }
+  /**
+   * Get the trace data for serialization
+   */
+  toJSON() {
+    return { ...this.data };
+  }
+};
+
+// src/instrumentation/openai.ts
+var import_debug = __toESM(require("debug"));
+var log = (0, import_debug.default)("observyze:sdk");
+function wrapOpenAI(client, nwClient) {
+  const anyClient = client;
+  if (nwClient.getConfig().enableProxyRedirect && anyClient.baseURL && anyClient.apiKey) {
+    const isAlreadyRedirected = anyClient.baseURL.includes("/api/v1/proxy/openai");
+    if (!isAlreadyRedirected) {
+      const originalApiKey = anyClient.apiKey;
+      anyClient.baseURL = `${nwClient.getConfig().endpoint}/api/v1/proxy/openai/v1`;
+      anyClient.apiKey = nwClient.getConfig().apiKey;
+      anyClient.defaultHeaders = {
+        ...anyClient.defaultHeaders,
+        "x-provider-key": originalApiKey
+      };
+      if (nwClient.getConfig().debug) {
+        log("[Observyze SDK] Transparently redirected OpenAI client to proxy gateway:", anyClient.baseURL);
+      }
+    }
+  }
+  const originalCreate = client.chat.completions.create.bind(client.chat.completions);
+  client.chat.completions.create = async function(params, options) {
+    const isProxyRedirected = nwClient.getConfig().enableProxyRedirect && anyClient.baseURL?.includes("/api/v1/proxy/openai");
+    if (isProxyRedirected) {
+      return originalCreate(params, options);
+    }
+    const trace = nwClient.startTrace(`openai.chat.completions.create`, {
+      provider: "openai",
+      model: params.model
+    });
+    const span = trace.startSpan("chat.completions.create", import_types.SpanType.LLM);
+    span.setMetadata("model", params.model);
+    span.setMetadata("provider", "openai");
+    if (params.temperature !== void 0) span.setMetadata("temperature", params.temperature);
+    if (params.max_tokens !== void 0) span.setMetadata("max_tokens", params.max_tokens);
+    span.setInput({
+      model: params.model,
+      messages: params.messages,
+      temperature: params.temperature,
+      max_tokens: params.max_tokens
+    });
+    const startTime = Date.now();
+    try {
+      const response = await originalCreate(params, options);
+      if (params.stream) {
+        return wrapOpenAIStream(response, span, trace, startTime);
+      }
+      const completionResponse = response;
+      const latency = Date.now() - startTime;
+      span.setOutput({
+        id: completionResponse.id,
+        model: completionResponse.model,
+        choices: completionResponse.choices
+      });
+      if (completionResponse.usage) {
+        span.setTokens({
+          input: completionResponse.usage.prompt_tokens,
+          output: completionResponse.usage.completion_tokens,
+          total: completionResponse.usage.total_tokens
+        });
+      }
+      span.setMetadata("latency_ms", latency);
+      span.end();
+      trace.end();
+      return response;
+    } catch (error) {
+      const latency = Date.now() - startTime;
+      span.setMetadata("latency_ms", latency);
+      span.setError(error);
+      span.end();
+      trace.end();
+      throw error;
+    }
+  };
+  return client;
+}
+function wrapOpenAIStream(stream, span, trace, startTime) {
+  const bufferedChunks = [];
+  let streamId = "";
+  let streamModel = "";
+  return {
+    [Symbol.asyncIterator]: async function* () {
+      try {
+        for await (const chunk of stream) {
+          if (chunk.id) streamId = chunk.id;
+          if (chunk.model) streamModel = chunk.model;
+          const delta = chunk.choices[0]?.delta;
+          if (delta?.content) {
+            bufferedChunks.push(delta.content);
+          }
+          yield chunk;
+        }
+        const latency = Date.now() - startTime;
+        const completeOutput = bufferedChunks.join("");
+        span.setOutput({
+          id: streamId,
+          model: streamModel,
+          content: completeOutput
+        });
+        span.setMetadata("latency_ms", latency);
+        span.setMetadata("streaming", true);
+        span.end();
+        trace.end();
+      } catch (error) {
+        const latency = Date.now() - startTime;
+        span.setMetadata("latency_ms", latency);
+        span.setError(error);
+        span.end();
+        trace.end();
+        throw error;
+      }
+    }
+  };
+}
+
+// src/instrumentation/anthropic.ts
+var import_debug2 = __toESM(require("debug"));
+var log2 = (0, import_debug2.default)("observyze:sdk");
+function wrapAnthropic(client, nwClient) {
+  const anyClient = client;
+  if (nwClient.getConfig().enableProxyRedirect && anyClient.baseURL && anyClient.apiKey) {
+    const isAlreadyRedirected = anyClient.baseURL.includes("/api/v1/proxy/anthropic");
+    if (!isAlreadyRedirected) {
+      const originalApiKey = anyClient.apiKey;
+      anyClient.baseURL = `${nwClient.getConfig().endpoint}/api/v1/proxy/anthropic/v1`;
+      anyClient.apiKey = nwClient.getConfig().apiKey;
+      anyClient.defaultHeaders = {
+        ...anyClient.defaultHeaders,
+        "x-provider-key": originalApiKey
+      };
+      if (nwClient.getConfig().debug) {
+        log2("[Observyze SDK] Transparently redirected Anthropic client to proxy gateway:", anyClient.baseURL);
+      }
+    }
+  }
+  const originalCreate = client.messages.create.bind(client.messages);
+  client.messages.create = async function(params, options) {
+    const isProxyRedirected = nwClient.getConfig().enableProxyRedirect && anyClient.baseURL?.includes("/api/v1/proxy/anthropic");
+    if (isProxyRedirected) {
+      return originalCreate(params, options);
+    }
+    const trace = nwClient.startTrace(`anthropic.messages.create`, {
+      provider: "anthropic",
+      model: params.model
+    });
+    const span = trace.startSpan("messages.create", import_types.SpanType.LLM);
+    span.setMetadata("model", params.model);
+    span.setMetadata("provider", "anthropic");
+    if (params.temperature !== void 0) span.setMetadata("temperature", params.temperature);
+    if (params.max_tokens !== void 0) span.setMetadata("max_tokens", params.max_tokens);
+    if (params.system !== void 0) span.setMetadata("system", params.system);
+    span.setInput({
+      model: params.model,
+      messages: params.messages,
+      max_tokens: params.max_tokens,
+      temperature: params.temperature,
+      system: params.system
+    });
+    const startTime = Date.now();
+    try {
+      const response = await originalCreate(params, options);
+      if (params.stream) {
+        return wrapAnthropicStream(response, span, trace, startTime);
+      }
+      const messageResponse = response;
+      const latency = Date.now() - startTime;
+      span.setOutput({
+        id: messageResponse.id,
+        model: messageResponse.model,
+        role: messageResponse.role,
+        content: messageResponse.content,
+        stop_reason: messageResponse.stop_reason
+      });
+      if (messageResponse.usage) {
+        span.setTokens({
+          input: messageResponse.usage.input_tokens,
+          output: messageResponse.usage.output_tokens,
+          total: messageResponse.usage.input_tokens + messageResponse.usage.output_tokens
+        });
+      }
+      span.setMetadata("latency_ms", latency);
+      span.end();
+      trace.end();
+      return response;
+    } catch (error) {
+      const latency = Date.now() - startTime;
+      span.setMetadata("latency_ms", latency);
+      span.setError(error);
+      span.end();
+      trace.end();
+      throw error;
+    }
+  };
+  return client;
+}
+function wrapAnthropicStream(stream, span, trace, startTime) {
+  const bufferedChunks = [];
+  let messageId = "";
+  let messageModel = "";
+  let stopReason = null;
+  let inputTokens = 0;
+  let outputTokens = 0;
+  return {
+    [Symbol.asyncIterator]: async function* () {
+      try {
+        for await (const event of stream) {
+          if (event.type === "message_start" && event.message) {
+            messageId = event.message.id;
+            messageModel = event.message.model;
+            if (event.message.usage) {
+              inputTokens = event.message.usage.input_tokens;
+            }
+          }
+          if (event.type === "content_block_delta" && event.delta?.text) {
+            bufferedChunks.push(event.delta.text);
+          }
+          if (event.type === "message_delta" && event.delta) {
+            if (event.delta.stop_reason) {
+              stopReason = event.delta.stop_reason;
+            }
+            if (event.usage?.output_tokens) {
+              outputTokens = event.usage.output_tokens;
+            }
+          }
+          yield event;
+        }
+        const latency = Date.now() - startTime;
+        const completeOutput = bufferedChunks.join("");
+        span.setOutput({
+          id: messageId,
+          model: messageModel,
+          content: completeOutput,
+          stop_reason: stopReason
+        });
+        if (inputTokens > 0 || outputTokens > 0) {
+          span.setTokens({
+            input: inputTokens,
+            output: outputTokens,
+            total: inputTokens + outputTokens
+          });
+        }
+        span.setMetadata("latency_ms", latency);
+        span.setMetadata("streaming", true);
+        span.end();
+        trace.end();
+      } catch (error) {
+        const latency = Date.now() - startTime;
+        span.setMetadata("latency_ms", latency);
+        span.setError(error);
+        span.end();
+        trace.end();
+        throw error;
+      }
+    }
+  };
+}
+
+// src/instrumentation/index.ts
+function wrap(client, nwClient) {
+  if ("chat" in client && client.chat && "completions" in client.chat) {
+    return wrapOpenAI(client, nwClient);
+  }
+  if ("messages" in client && client.messages && "create" in client.messages) {
+    return wrapAnthropic(client, nwClient);
+  }
+  throw new Error(
+    "Observyze SDK: Unsupported client type. Supported clients: OpenAI, Anthropic"
+  );
+}
+
+// src/client.ts
+var import_fs = __toESM(require("fs"));
+var import_path = __toESM(require("path"));
+var log3 = (0, import_debug3.default)("observyze:sdk");
+var DEFAULT_CONFIG = {
+  endpoint: "http://localhost:3001",
+  batchSize: 100,
+  flushInterval: 5e3,
+  enableAutoInstrumentation: true,
+  debug: false,
+  dryRun: false,
+  enablePiiRedaction: true,
+  hallucinationThreshold: 0.8,
+  safetyThreshold: 0.9,
+  confidenceThreshold: 0.4,
+  evalEndpoint: process.env.EVAL_ENDPOINT || (process.env.NODE_ENV === "production" ? "https://api.observyze.com" : "http://localhost:3001"),
+  enableCircuitBreaker: true,
+  failClosed: true,
+  enableProxyRedirect: true
+};
+var ObservyzeClient = class _ObservyzeClient {
+  config;
+  traceBuffer = [];
+  flushTimer = null;
+  isShuttingDown = false;
+  MAX_QUEUE_SIZE = 1e3;
+  RETRY_DELAYS = [1e3, 2e3, 4e3, 8e3, 16e3, 3e4];
+  /**
+   * Parse a JSON API error response and extract trace_id, error code, and message.
+   * The api-gateway error handler includes these fields in every error response.
+   */
+  static parseApiError(_response, body) {
+    try {
+      const parsed = JSON.parse(body);
+      const error = parsed.error || parsed;
+      return {
+        traceId: error.trace_id || "unknown",
+        code: error.code || "UNKNOWN_ERROR",
+        message: error.message || body.slice(0, 200)
+      };
+    } catch {
+      return {
+        traceId: "unknown",
+        code: "UNKNOWN_ERROR",
+        message: body.slice(0, 200)
+      };
+    }
+  }
+  /**
+   * Format an API error into a user-friendly message with trace_id for correlation.
+   * Example output:
+   *   "Observyze API error (401 [ref: err_a1b2c3d4]): MISSING_PROVIDER_KEY — No API key configured..."
+   */
+  static formatApiError(response, body) {
+    const { traceId, code, message } = _ObservyzeClient.parseApiError(response, body);
+    const prefix = traceId !== "unknown" ? ` [ref: ${traceId}]` : "";
+    return `Observyze API error (${response.status}${prefix}): ${code} \u2014 ${message}`;
+  }
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("Observyze SDK: apiKey is required");
+    }
+    this.config = {
+      ...DEFAULT_CONFIG,
+      ...config,
+      organizationId: config.organizationId || "",
+      projectId: config.projectId || ""
+    };
+    this.startFlushTimer();
+    if (this.config.debug) {
+      log3("[Observyze SDK] Initialized with config:", {
+        endpoint: this.config.endpoint,
+        batchSize: this.config.batchSize,
+        flushInterval: this.config.flushInterval,
+        dryRun: this.config.dryRun
+      });
+    }
+  }
+  /**
+   * Start a new trace
+   */
+  startTrace(name, metadata) {
+    const trace = new Trace(
+      name,
+      this.config.organizationId,
+      this.config.projectId
+    );
+    if (metadata) {
+      trace.setMetadataAll(metadata);
+    }
+    const originalEnd = trace.end.bind(trace);
+    trace.end = (status = import_types.TraceStatus.SUCCESS) => {
+      originalEnd(status);
+      this.bufferTrace(trace);
+    };
+    return trace;
+  }
+  /**
+   * Buffer a completed trace for batch sending
+   */
+  bufferTrace(trace) {
+    if (!trace.isEnded) {
+      if (this.config.debug) {
+        log3.extend("warn")("[Observyze SDK] Attempted to buffer a trace that has not ended");
+      }
+      return;
+    }
+    if (this.traceBuffer.length >= this.MAX_QUEUE_SIZE) {
+      if (this.config.debug) {
+        log3.extend("warn")(`[Observyze SDK] Queue at max capacity (${this.MAX_QUEUE_SIZE}), dropping oldest trace`);
+      }
+      this.traceBuffer.shift();
+    }
+    this.traceBuffer.push(trace);
+    if (this.config.debug) {
+      log3(`[Observyze SDK] Buffered trace ${trace.id} (${this.traceBuffer.length}/${this.config.batchSize})`);
+    }
+    if (this.traceBuffer.length >= this.config.batchSize) {
+      this.flush().catch((err) => {
+        log3.extend("error")("[Observyze SDK] Error flushing buffer:", err);
+      });
+    }
+  }
+  /**
+   * Start the auto-flush timer
+   */
+  startFlushTimer() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+    }
+    this.flushTimer = setInterval(() => {
+      if (this.traceBuffer.length > 0) {
+        this.flush().catch((err) => {
+          log3.extend("error")("[Observyze SDK] Error in auto-flush:", err);
+        });
+      }
+    }, this.config.flushInterval);
+    if (this.flushTimer.unref) {
+      this.flushTimer.unref();
+    }
+  }
+  /**
+   * Flush all buffered traces to the Ingestion Service
+   */
+  async flush() {
+    if (this.traceBuffer.length === 0) {
+      return;
+    }
+    const tracesToSend = this.traceBuffer.splice(0, this.config.batchSize);
+    if (this.config.debug) {
+      log3(`[Observyze SDK] Flushing ${tracesToSend.length} traces`);
+    }
+    if (this.config.dryRun) {
+      if (this.config.debug) {
+        log3("[Observyze SDK] Dry-run mode: traces not sent");
+      }
+      return;
+    }
+    try {
+      await this.sendWithRetry(tracesToSend);
+    } catch (error) {
+      const remainingSpace = this.MAX_QUEUE_SIZE - this.traceBuffer.length;
+      if (remainingSpace > 0) {
+        this.traceBuffer.unshift(...tracesToSend.slice(0, remainingSpace));
+        if (this.config.debug) {
+          log3(`[Observyze SDK] Re-queued ${Math.min(tracesToSend.length, remainingSpace)} traces after failure`);
+        }
+      } else {
+        if (this.config.debug) {
+          log3.extend("warn")(`[Observyze SDK] Queue full, dropped ${tracesToSend.length} traces`);
+        }
+      }
+      if (this.config.debug) {
+        log3.extend("error")("[Observyze SDK] Failed to send traces after retries:", error);
+      }
+      throw error;
+    }
+  }
+  /**
+   * Send traces with exponential backoff retry
+   */
+  async sendWithRetry(traces) {
+    let lastError = null;
+    for (let attempt = 0; attempt < this.RETRY_DELAYS.length + 1; attempt++) {
+      try {
+        const response = await fetch(`${this.config.endpoint}/api/v1/ingest/batch`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${this.config.apiKey}`
+          },
+          body: JSON.stringify({
+            traces: traces.map((trace) => {
+              const json = trace.toJSON();
+              if (this.config.enablePiiRedaction) {
+                json.spans = this.sanitizePII(json.spans);
+              }
+              return json;
+            })
+          })
+        });
+        if (!response.ok) {
+          const errorBody = await response.text();
+          const formatted = _ObservyzeClient.formatApiError(response, errorBody);
+          throw new Error(`[Observyze SDK] Trace ingestion failed. ${formatted}`);
+        }
+        if (this.config.debug) {
+          log3(`[Observyze SDK] Successfully sent ${traces.length} traces${attempt > 0 ? ` (after ${attempt} retries)` : ""}`);
+        }
+        return;
+      } catch (error) {
+        lastError = error;
+        if (attempt >= this.RETRY_DELAYS.length) {
+          break;
+        }
+        const delay = this.RETRY_DELAYS[attempt];
+        if (this.config.debug) {
+          log3.extend("warn")(`[Observyze SDK] Attempt ${attempt + 1} failed, retrying in ${delay}ms...`, error);
+        }
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+    throw lastError || new Error("Failed to send traces after all retries");
+  }
+  /**
+   * Shutdown the SDK and flush remaining traces
+   */
+  async shutdown() {
+    if (this.isShuttingDown) {
+      return;
+    }
+    this.isShuttingDown = true;
+    if (this.config.debug) {
+      log3("[Observyze SDK] Shutting down...");
+    }
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    try {
+      await this.flush();
+    } catch (error) {
+      log3.extend("error")("[Observyze SDK] Error during shutdown flush:", error);
+    }
+    if (this.config.debug) {
+      log3("[Observyze SDK] Shutdown complete");
+    }
+  }
+  /**
+   * Get current buffer size
+   */
+  get bufferSize() {
+    return this.traceBuffer.length;
+  }
+  /**
+   * Get SDK configuration
+   */
+  getConfig() {
+    return { ...this.config };
+  }
+  /**
+   * Wrap an LLM client (OpenAI, Anthropic) to enable auto-instrumentation
+   * 
+   * @example
+   * ```typescript
+   * import OpenAI from 'openai'
+   * import { ObservyzeClient } from '@observyze/sdk'
+   * 
+   * const nw = new ObservyzeClient({ apiKey: 'your-api-key' })
+   * const openai = new OpenAI({ apiKey: 'openai-key' })
+   * 
+   * // Wrap the client to enable auto-instrumentation
+   * nw.wrap(openai)
+   * 
+   * // All calls are now automatically traced
+   * const response = await openai.chat.completions.create({
+   *   model: 'gpt-4',
+   *   messages: [{ role: 'user', content: 'Hello!' }]
+   * })
+   * ```
+   */
+  wrap(client) {
+    return wrap(client, this);
+  }
+  /**
+   * Sync local agent .history file to Observyze cloud
+   * Parses JSON/NDJSON agent history and sends to ingestion endpoint.
+   */
+  async syncLocalHistory(filePath) {
+    try {
+      if (typeof process === "undefined" || !process.versions?.node) {
+        throw new Error("syncLocalHistory is only available in Node.js environments");
+      }
+      const fullPath = import_path.default.resolve(process.cwd(), filePath);
+      if (!import_fs.default.existsSync(fullPath)) {
+        throw new Error(`History file not found: ${fullPath}`);
+      }
+      const content = import_fs.default.readFileSync(fullPath, "utf-8");
+      let items = [];
+      try {
+        items = JSON.parse(content);
+      } catch (e) {
+        items = content.split("\n").filter((l) => l.trim()).map((l) => JSON.parse(l));
+      }
+      if (!Array.isArray(items)) {
+        items = [items];
+      }
+      if (this.config.debug) {
+        log3(`[Observyze SDK] Syncing ${items.length} traces from ${filePath}`);
+      }
+      for (let i = 0; i < items.length; i += this.config.batchSize) {
+        const batch = items.slice(i, i + this.config.batchSize);
+        const response = await fetch(`${this.config.endpoint}/api/v1/ingest/batch`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${this.config.apiKey}`
+          },
+          body: JSON.stringify({ traces: batch })
+        });
+        if (!response.ok) {
+          const errorBody = await response.text();
+          const formatted = _ObservyzeClient.formatApiError(response, errorBody);
+          throw new Error(`[Observyze SDK] Local history sync failed. ${formatted}`);
+        }
+        if (this.config.debug) {
+          log3(`[Observyze SDK] Synced batch of ${batch.length} traces from local history`);
+        }
+      }
+    } catch (err) {
+      log3.extend("error")("[Observyze SDK] Failed to sync local history:", err);
+      throw err;
+    }
+  }
+  /**
+   * Industry-grade PII Redaction (Compliance & RBAC)
+   *
+   * Recursively scrubs PII from trace data before transmission to the cloud.
+   * Coverage: emails, JWTs, bearer tokens, AWS/API keys, SSNs, credit cards,
+   * phone numbers (US + E.164), IPv4/IPv6, passport numbers, ZIP codes, plus
+   * key-based redaction for sensitive JSON fields (password, token, api_key, etc.).
+   *
+   * Design:
+   *  - Pure function, never mutates the original object
+   *  - Depth-limited to 16 levels to prevent stack overflow on deep agent outputs
+   *  - Key-aware: sensitive key names are fully redacted regardless of value format
+   */
+  static PII_PATTERNS = [
+    { pattern: /\b[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}\b/gi, label: "[EMAIL_REDACTED]" },
+    { pattern: /\beyJ[A-Za-z0-9_\-]+\.eyJ[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+\b/g, label: "[JWT_REDACTED]" },
+    { pattern: /\b(Bearer|Token|Basic)\s+[A-Za-z0-9\-.~+\/]+=*\b/gi, label: "[AUTH_TOKEN_REDACTED]" },
+    { pattern: /\b(AKIA|ASIA|AROA|ANPA|ANVA|AIDA)[A-Z0-9]{16}\b/g, label: "[AWS_KEY_REDACTED]" },
+    { pattern: /\b(sk-[A-Za-z0-9\-]{20,}|pk-[A-Za-z0-9\-]{20,}|ob_[A-Za-z0-9]{20,}|ghp_[A-Za-z0-9]{36,}|gho_[A-Za-z0-9]{36,})\b/g, label: "[API_KEY_REDACTED]" },
+    { pattern: /\b\d{3}-\d{2}-\d{4}\b/g, label: "[SSN_REDACTED]" },
+    { pattern: /\b(?:\d[ \-]?){13,18}\d\b/g, label: "[CC_REDACTED]" },
+    { pattern: /(?:\+1[\s.\-]?)?\(?\d{3}\)?[\s.\-]?\d{3}[\s.\-]?\d{4}\b/g, label: "[PHONE_REDACTED]" },
+    { pattern: /\+\d{1,3}[\s.\-]?\(?\d{1,4}\)?[\s.\-]?\d{1,4}[\s.\-]?\d{1,9}/g, label: "[PHONE_REDACTED]" },
+    { pattern: /\b(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\b/g, label: "[IP_REDACTED]" },
+    { pattern: /\b(?:[0-9a-fA-F]{1,4}:){2,7}[0-9a-fA-F]{1,4}\b/g, label: "[IP_REDACTED]" }
+  ];
+  static SENSITIVE_KEYS = /* @__PURE__ */ new Set([
+    "password",
+    "passwd",
+    "secret",
+    "token",
+    "apikey",
+    "api_key",
+    "accesstoken",
+    "access_token",
+    "refreshtoken",
+    "refresh_token",
+    "authorization",
+    "auth",
+    "credential",
+    "credentials",
+    "private_key",
+    "privatekey",
+    "client_secret",
+    "clientsecret",
+    "ssn",
+    "social_security",
+    "dob",
+    "date_of_birth",
+    "dateofbirth",
+    "passport",
+    "passport_number",
+    "credit_card",
+    "creditcard",
+    "card_number",
+    "cardnumber",
+    "cvv",
+    "cvc",
+    "pin",
+    "bank_account",
+    "routing_number"
+  ]);
+  static isSensitiveKey(key) {
+    const normalized = key.toLowerCase().replace(/-/g, "_");
+    if (_ObservyzeClient.SENSITIVE_KEYS.has(normalized)) return true;
+    const segments = normalized.split("_");
+    for (const segment of segments) {
+      if (_ObservyzeClient.SENSITIVE_KEYS.has(segment)) return true;
+    }
+    return false;
+  }
+  sanitizePII(data, depth = 0) {
+    if (depth > 16) return "[MAX_DEPTH_EXCEEDED]";
+    if (data === null || data === void 0) return data;
+    if (typeof data === "string") {
+      let result = data;
+      for (const { pattern, label } of _ObservyzeClient.PII_PATTERNS) {
+        pattern.lastIndex = 0;
+        result = result.replace(pattern, label);
+      }
+      return result;
+    }
+    if (typeof data === "number" || typeof data === "boolean") return data;
+    if (Array.isArray(data)) return data.map((item) => this.sanitizePII(item, depth + 1));
+    if (typeof data === "object") {
+      const sanitized = {};
+      for (const [k, v] of Object.entries(data)) {
+        sanitized[k] = _ObservyzeClient.isSensitiveKey(k) ? "[REDACTED]" : this.sanitizePII(v, depth + 1);
+      }
+      return sanitized;
+    }
+    return data;
+  }
+  /**
+   * Phase 4: Autonomous Circuit Breakers (Requirement 4.1)
+   * Evaluate a trace or text for hallucination in real-time.
+   * If hallucination score > hallucinationThreshold, the SDK blocks execution.
+   * 
+   * Returns GuardrailResult with score: null when evaluation couldn't be performed.
+   * In failClosed mode, null scores result in blocked execution.
+   * In failOpen mode, null scores allow execution through.
+   */
+  async checkGuardrails(content) {
+    if (!this.config.enableCircuitBreaker) {
+      return { pass: true, score: 0, safetyScore: 0, evaluationSource: "disabled" };
+    }
+    try {
+      if (this.config.debug) {
+        log3(`[Observyze Guardrail] Analyzing payload for hallucination anomalies...`);
+      }
+      const evalEndpoint = this.config.evalEndpoint;
+      const payload = typeof content === "string" ? { text: content, organization_id: this.config.organizationId } : { trace: content, organization_id: this.config.organizationId };
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 5e3);
+      let evalResult = null;
+      try {
+        const response = await fetch(`${evalEndpoint}/api/v1/evaluate/hallucination`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${this.config.apiKey}`
+          },
+          body: JSON.stringify(payload),
+          signal: controller.signal
+        });
+        clearTimeout(timeout);
+        if (response.ok) {
+          evalResult = await response.json();
+        } else {
+          const errorBody = await response.text();
+          const { traceId, code, message } = _ObservyzeClient.parseApiError(response, errorBody);
+          if (this.config.debug) {
+            log3.extend("warn")(`[Observyze Guardrail] Eval returned ${response.status} [${code}] (ref: ${traceId}): ${message}`);
+          }
+        }
+      } catch (fetchError) {
+        clearTimeout(timeout);
+        if (fetchError.name === "AbortError") {
+          if (this.config.debug) {
+            log3.extend("warn")("[Observyze Guardrail] Evaluation timed out after 5s");
+          }
+        } else if (this.config.debug) {
+          log3.extend("warn")("[Observyze Guardrail] Evaluation request failed:", fetchError.message);
+        }
+      }
+      let hallucinationScore = 0;
+      let safetyScore = 0;
+      let evaluationSource = "live";
+      let confidence = null;
+      if (evalResult) {
+        hallucinationScore = evalResult.score ?? evalResult.hallucination_score ?? null;
+        safetyScore = evalResult.safety_score ?? 0;
+        evaluationSource = evalResult.evaluation_source ?? "live";
+        confidence = evalResult.confidence ?? null;
+        if (hallucinationScore === null) {
+          if (this.config.failClosed) {
+            if (this.config.debug) {
+              log3.extend("warn")("[Observyze Guardrail] Eval returned null score \u2014 failing closed (blocking)");
+            }
+            return {
+              pass: false,
+              score: null,
+              confidence: null,
+              safetyScore: null,
+              evaluationSource: "error",
+              fallbackReason: evalResult.message || "Evaluation failed to produce a score",
+              reason: "Evaluation service failed to produce a score. Fail-closed: execution blocked."
+            };
+          }
+          if (this.config.debug) {
+            log3("[Observyze Guardrail] Eval returned null score \u2014 allowing (fail-open)");
+          }
+          return {
+            pass: true,
+            score: null,
+            confidence: null,
+            safetyScore: null,
+            evaluationSource: "error",
+            fallbackReason: evalResult.message || "Evaluation failed to produce a score"
+          };
+        }
+      } else if (this.config.failClosed) {
+        if (this.config.debug) {
+          log3.extend("warn")("[Observyze Guardrail] Eval unavailable \u2014 failing closed (blocking)");
+        }
+        return {
+          pass: false,
+          score: null,
+          confidence: null,
+          safetyScore: null,
+          evaluationSource: "error",
+          fallbackReason: "Evaluation service unreachable",
+          reason: "Evaluation service unreachable. Fail-closed: execution blocked."
+        };
+      } else {
+        if (this.config.debug) {
+          log3("[Observyze Guardrail] Eval unavailable \u2014 allowing (fail-open)");
+        }
+        return {
+          pass: true,
+          score: null,
+          confidence: null,
+          safetyScore: null,
+          evaluationSource: "error",
+          fallbackReason: "Evaluation service unreachable"
+        };
+      }
+      const hallThreshold = this.config.hallucinationThreshold;
+      const safeThreshold = this.config.safetyThreshold;
+      const confThreshold = this.config.confidenceThreshold;
+      if (confidence !== null && confidence < confThreshold) {
+        if (hallucinationScore >= hallThreshold) {
+          if (this.config.debug) {
+            log3.extend("warn")(`[Observyze Guardrail] High score (${hallucinationScore.toFixed(2)}) but low confidence (${confidence.toFixed(2)}). Alerting only.`);
+          }
+          return {
+            pass: true,
+            score: hallucinationScore,
+            confidence,
+            safetyScore,
+            evaluationSource,
+            reason: `Score ${hallucinationScore.toFixed(2)} but confidence ${confidence.toFixed(2)} is low. Execution allowed with alert.`
+          };
+        }
+      }
+      if (hallucinationScore >= hallThreshold) {
+        if (this.config.debug) {
+          log3.extend("warn")(`[Observyze Guardrail] Hallucination circuit breached! Score: ${hallucinationScore.toFixed(2)} >= ${hallThreshold}`);
+        }
+        return {
+          pass: false,
+          score: hallucinationScore,
+          confidence,
+          safetyScore,
+          evaluationSource,
+          reason: `Hallucination score ${hallucinationScore.toFixed(2)} exceeds threshold ${hallThreshold}. Execution blocked for human review.`
+        };
+      }
+      if (safetyScore !== null && safetyScore >= safeThreshold) {
+        if (this.config.debug) {
+          log3.extend("warn")(`[Observyze Guardrail] Safety circuit breached! Score: ${safetyScore.toFixed(2)} >= ${safeThreshold}`);
+        }
+        return {
+          pass: false,
+          score: hallucinationScore,
+          confidence,
+          safetyScore,
+          evaluationSource,
+          reason: `Safety score ${safetyScore.toFixed(2)} exceeds threshold ${safeThreshold}. Execution blocked for safety review.`
+        };
+      }
+      return { pass: true, score: hallucinationScore, confidence, safetyScore, evaluationSource };
+    } catch (err) {
+      log3.extend("error")("[Observyze Guardrail] Failed to evaluate:", err);
+      if (this.config.failClosed) {
+        return { pass: false, score: null, confidence: null, safetyScore: null, evaluationSource: "error", fallbackReason: "Guardrail exception", reason: "Guardrail error \u2014 fail-closed: execution blocked." };
+      }
+      return { pass: true, score: null, confidence: null, safetyScore: null, evaluationSource: "error", fallbackReason: "Guardrail exception" };
+    }
+  }
+  /**
+   * Phase 4: Autonomous Circuit Breakers
+   * Execute an agent action wrapped with the Circuit Breaker.
+   * Pauses execution if hallucination score >= hallucinationThreshold and requests human review.
+   * @throws Error when execution is blocked by circuit breaker
+   */
+  async executeWithCircuitBreaker(agentExecution, traceContext) {
+    if (!this.config.enableCircuitBreaker) {
+      return await agentExecution();
+    }
+    const guardResult = await this.checkGuardrails(traceContext || "execution context");
+    if (!guardResult.pass) {
+      const error = new Error(`[Observyze] Execution Blocked by Autonomous Circuit Breaker. Hallucination: ${guardResult.score?.toFixed(2) ?? "N/A"}, Safety: ${(guardResult.safetyScore ?? 0)?.toFixed(2) ?? "N/A"}. Reason: ${guardResult.reason}. Human approval required before agent can continue.`);
+      if (this.config.debug) {
+        log3.extend("error")("[Observyze CircuitBreaker] Execution blocked:", error.message);
+      }
+      throw error;
+    }
+    if (this.config.debug) {
+      log3(`[Observyze CircuitBreaker] Execution allowed. Hallucination: ${guardResult.score?.toFixed(2) ?? "N/A"}, Safety: ${(guardResult.safetyScore ?? 0)?.toFixed(2) ?? "N/A"}`);
+    }
+    return await agentExecution();
+  }
+  /**
+   * Phase 4: Bug Bounty Protocol (Automated) (Requirement 4.2)
+   * Automatically shard persistent failure cases to external security researcher endpoints (e.g. HackerOne wrapper)
+   */
+  async reportBugBounty(traceId, securityEndpoint, failureContext) {
+    try {
+      if (this.config.debug) {
+        log3(`[Observyze SDK] Sharding persistent failure case ${traceId} to Bug Bounty Protocol endpoint...`);
+      }
+      await fetch(securityEndpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          alert: "persistent_failure_sharded",
+          trace_id: traceId,
+          context: failureContext,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        })
+      });
+      if (this.config.debug) {
+        log3(`[Observyze SDK] Bug Bounty payload successfully transmitted.`);
+      }
+    } catch (err) {
+      log3.extend("error")("[Observyze Bug Bounty] Failed to shard failure case:", err);
+    }
+  }
+};
+
+// src/opentelemetry/exporter.ts
+var ObservyzeSpanExporter = class {
+  client;
+  config;
+  constructor(client, config) {
+    this.client = client;
+    this.config = {
+      serviceName: config?.serviceName || "unknown-service",
+      projectId: config?.projectId || "",
+      defaultSpanType: config?.defaultSpanType || "llm",
+      headers: config?.headers || {}
+    };
+  }
+  /**
+   * Export spans — called by OTel SDK when spans are ready.
+   * Converts OTel spans to Observyze traces and buffers them.
+   */
+  async export(spans, resultCallback) {
+    if (!spans || spans.length === 0) {
+      resultCallback({ code: 0 });
+      return;
+    }
+    try {
+      const organizationId = this.client.config?.organizationId || "";
+      const projectId = this.config.projectId || this.client.config?.projectId || "";
+      for (const span of spans) {
+        const spanContext = span.spanContext();
+        const traceId = spanContext?.traceId || span.spanId();
+        const trace = new Trace(
+          span.name || "otel-span",
+          organizationId,
+          projectId
+        );
+        trace.setMetadata("source", "opentelemetry");
+        trace.setMetadata("otel.trace_id", traceId);
+        trace.setMetadata("otel.span_id", spanContext?.spanId || "");
+        trace.setMetadata("service.name", this.config.serviceName);
+        trace.setMetadataAll(span.attributes || {});
+        if (span.resource?.attributes) {
+          trace.setMetadataAll(span.resource.attributes);
+        }
+        const input = span.attributes?.["gen_ai.prompt.0.content"] || span.attributes?.["gen_ai.completion.0.content"] || span.attributes?.["llm.input"] || void 0;
+        const output = span.attributes?.["gen_ai.completion.0.content"] || span.attributes?.["llm.output"] || void 0;
+        const model = span.attributes?.["gen_ai.request.model"] || span.attributes?.["llm.model"] || void 0;
+        const provider = span.attributes?.["gen_ai.request.provider"] || span.attributes?.["llm.provider"] || void 0;
+        const inputTokens = typeof span.attributes?.["gen_ai.usage.input_tokens"] === "number" ? span.attributes["gen_ai.usage.input_tokens"] : void 0;
+        const outputTokens = typeof span.attributes?.["gen_ai.usage.output_tokens"] === "number" ? span.attributes["gen_ai.usage.output_tokens"] : void 0;
+        trace.setMetadata("provider", provider || "unknown");
+        trace.setMetadata("model", model || "unknown");
+        const nsDuration = span.duration;
+        const durationMs = nsDuration ? Math.round(nsDuration / 1e6) : 0;
+        trace.setMetadata("latency_ms", durationMs);
+        trace.setMetadata("otel.duration_ns", nsDuration);
+        const oSpan = trace.startSpan(span.name || "otel-operation", this.config.defaultSpanType);
+        if (input) oSpan.setInput(input);
+        if (output) oSpan.setOutput(output);
+        if (inputTokens || outputTokens) {
+          oSpan.setTokens({
+            input: inputTokens || 0,
+            output: outputTokens || 0,
+            total: (inputTokens || 0) + (outputTokens || 0)
+          });
+        }
+        if (model) oSpan.setMetadata("model", model);
+        if (provider) oSpan.setMetadata("provider", provider);
+        if (span.attributes) oSpan.setMetadataAll(span.attributes);
+        const status = span.status;
+        const statusCode = status?.code;
+        if (statusCode === 2) {
+          oSpan.setError(new Error(status?.message || "OTel span error"));
+          trace.end(import_types.TraceStatus.ERROR);
+        } else {
+          trace.end(import_types.TraceStatus.SUCCESS);
+        }
+      }
+      resultCallback({ code: 0 });
+    } catch (error) {
+      resultCallback({
+        code: 1,
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    }
+  }
+  /**
+   * Called when the exporter is shut down.
+   * Flushes any remaining buffered traces via the SDK client.
+   */
+  async shutdown() {
+    try {
+      await this.client.flush();
+    } catch {
+    }
+  }
+  /**
+   * Called by the OTel SDK to force-export buffered spans.
+   */
+  async forceFlush() {
+    try {
+      await this.client.flush();
+    } catch {
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ObservyzeClient,
+  ObservyzeSpanExporter,
+  Span,
+  SpanType,
+  Trace,
+  TraceStatus,
+  wrap,
+  wrapAnthropic,
+  wrapOpenAI
+});