@observyze/sdk 0.1.0

package/src/client.ts

@@ -0,0 +1,578 @@
+/**
+ * Observyze SDK Client
+ * Main entry point for instrumenting AI applications
+ */
+
+import { Trace } from './trace'
+import { TraceStatus } from './types'
+import type { ClientConfig, ResolvedClientConfig } from './types'
+
+/**
+ * Default configuration values
+ */
+const DEFAULT_CONFIG: Partial<ClientConfig> = {
+  endpoint: 'http://localhost:3001',
+  batchSize: 100,
+  flushInterval: 5000,
+  enableAutoInstrumentation: true,
+  debug: false,
+  dryRun: false,
+  enablePiiRedaction: true,
+  hallucinationThreshold: 0.8,
+  safetyThreshold: 0.9,
+  evalEndpoint: process.env.EVAL_ENDPOINT || (process.env.NODE_ENV === 'production' ? 'https://api.observyze.com' : 'http://localhost:3000'),
+  enableCircuitBreaker: true
+}
+
+/**
+ * Main SDK client for Observyze
+ */
+export class ObservyzeClient {
+  private config: ResolvedClientConfig
+  private traceBuffer: Trace[] = []
+  private flushTimer: NodeJS.Timeout | null = null
+  private isShuttingDown: boolean = false
+  private readonly MAX_QUEUE_SIZE = 1000
+  private readonly RETRY_DELAYS = [1000, 2000, 4000, 8000, 16000, 30000] // ms: 1s → 2s → 4s → 8s → 16s → 30s
+
+  constructor(config: ClientConfig) {
+    // Validate required fields
+    if (!config.apiKey) {
+      throw new Error('Observyze SDK: apiKey is required')
+    }
+
+    // Apply defaults
+    this.config = {
+      ...DEFAULT_CONFIG,
+      ...config,
+      organizationId: config.organizationId || '',
+      projectId: config.projectId || ''
+    } as ResolvedClientConfig
+
+    // Start flush timer
+    this.startFlushTimer()
+
+    // Log initialization
+    if (this.config.debug) {
+      console.log('[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: string, metadata?: Record<string, any>): Trace {
+    const trace = new Trace(
+      name,
+      this.config.organizationId,
+      this.config.projectId
+    )
+
+    if (metadata) {
+      trace.setMetadataAll(metadata)
+    }
+
+    // Auto-end and buffer trace when it's ended
+    const originalEnd = trace.end.bind(trace)
+    trace.end = (status: TraceStatus = TraceStatus.SUCCESS) => {
+      originalEnd(status)
+      this.bufferTrace(trace)
+    }
+
+    return trace
+  }
+
+  /**
+   * Buffer a completed trace for batch sending
+   */
+  private bufferTrace(trace: Trace): void {
+    if (!trace.isEnded) {
+      if (this.config.debug) {
+        console.warn('[Observyze SDK] Attempted to buffer a trace that has not ended')
+      }
+      return
+    }
+
+    // Check if queue is at max capacity
+    if (this.traceBuffer.length >= this.MAX_QUEUE_SIZE) {
+      if (this.config.debug) {
+        console.warn(`[Observyze SDK] Queue at max capacity (${this.MAX_QUEUE_SIZE}), dropping oldest trace`)
+      }
+      // Drop oldest trace to make room
+      this.traceBuffer.shift()
+    }
+
+    this.traceBuffer.push(trace)
+
+    if (this.config.debug) {
+      console.log(`[Observyze SDK] Buffered trace ${trace.id} (${this.traceBuffer.length}/${this.config.batchSize})`)
+    }
+
+    // Flush if buffer is full
+    if (this.traceBuffer.length >= this.config.batchSize) {
+      this.flush().catch(err => {
+        console.error('[Observyze SDK] Error flushing buffer:', err)
+      })
+    }
+  }
+
+  /**
+   * Start the auto-flush timer
+   */
+  private startFlushTimer(): void {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer)
+    }
+
+    this.flushTimer = setInterval(() => {
+      if (this.traceBuffer.length > 0) {
+        this.flush().catch(err => {
+          console.error('[Observyze SDK] Error in auto-flush:', err)
+        })
+      }
+    }, this.config.flushInterval)
+
+    // Don't keep the process alive just for the timer
+    if (this.flushTimer.unref) {
+      this.flushTimer.unref()
+    }
+  }
+
+  /**
+   * Flush all buffered traces to the Ingestion Service
+   */
+  async flush(): Promise<void> {
+    if (this.traceBuffer.length === 0) {
+      return
+    }
+
+    const tracesToSend = this.traceBuffer.splice(0, this.config.batchSize)
+
+    if (this.config.debug) {
+      console.log(`[Observyze SDK] Flushing ${tracesToSend.length} traces`)
+    }
+
+    // In dry-run mode, just log and return
+    if (this.config.dryRun) {
+      if (this.config.debug) {
+        console.log('[Observyze SDK] Dry-run mode: traces not sent')
+      }
+      return
+    }
+
+    try {
+      await this.sendWithRetry(tracesToSend)
+    } catch (error) {
+      // On final failure, put traces back in buffer (up to max queue size)
+      const remainingSpace = this.MAX_QUEUE_SIZE - this.traceBuffer.length
+      if (remainingSpace > 0) {
+        this.traceBuffer.unshift(...tracesToSend.slice(0, remainingSpace))
+        if (this.config.debug) {
+          console.log(`[Observyze SDK] Re-queued ${Math.min(tracesToSend.length, remainingSpace)} traces after failure`)
+        }
+      } else {
+        if (this.config.debug) {
+          console.warn(`[Observyze SDK] Queue full, dropped ${tracesToSend.length} traces`)
+        }
+      }
+
+      if (this.config.debug) {
+        console.error('[Observyze SDK] Failed to send traces after retries:', error)
+      }
+
+      throw error
+    }
+  }
+
+  /**
+   * Send traces with exponential backoff retry
+   */
+  private async sendWithRetry(traces: Trace[]): Promise<void> {
+    let lastError: Error | null = 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()
+          throw new Error(`Ingestion failed: ${response.status} ${errorBody}`)
+        }
+
+        if (this.config.debug) {
+          console.log(`[Observyze SDK] Successfully sent ${traces.length} traces${attempt > 0 ? ` (after ${attempt} retries)` : ''}`)
+        }
+
+        return // Success
+      } catch (error) {
+        lastError = error as Error
+
+        // If this is the last attempt, break and throw
+        if (attempt >= this.RETRY_DELAYS.length) {
+          break
+        }
+
+        // Calculate delay with exponential backoff
+        const delay = this.RETRY_DELAYS[attempt]
+
+        if (this.config.debug) {
+          console.warn(`[Observyze SDK] Attempt ${attempt + 1} failed, retrying in ${delay}ms...`, error)
+        }
+
+        // Wait before retrying
+        await new Promise(resolve => setTimeout(resolve, delay))
+      }
+    }
+
+    // All retries exhausted
+    throw lastError || new Error('Failed to send traces after all retries')
+  }
+
+  /**
+   * Shutdown the SDK and flush remaining traces
+   */
+  async shutdown(): Promise<void> {
+    if (this.isShuttingDown) {
+      return
+    }
+
+    this.isShuttingDown = true
+
+    if (this.config.debug) {
+      console.log('[Observyze SDK] Shutting down...')
+    }
+
+    // Stop the flush timer
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer)
+      this.flushTimer = null
+    }
+
+    // Flush remaining traces
+    try {
+      await this.flush()
+    } catch (error) {
+      console.error('[Observyze SDK] Error during shutdown flush:', error)
+    }
+
+    if (this.config.debug) {
+      console.log('[Observyze SDK] Shutdown complete')
+    }
+  }
+
+  /**
+   * Get current buffer size
+   */
+  get bufferSize(): number {
+    return this.traceBuffer.length
+  }
+
+  /**
+   * Get SDK configuration
+   */
+  getConfig(): Readonly<ResolvedClientConfig> {
+    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<T>(client: T): T {
+    const { wrap: wrapClient } = require('./instrumentation')
+    return wrapClient(client, this)
+  }
+
+  /**
+   * Sync local agent .history file to Observyze cloud
+   * Parses JSON/NDJSON agent history and sends to ingestion endpoint.
+   */
+  async syncLocalHistory(filePath: string): Promise<void> {
+    try {
+      if (typeof process === 'undefined' || !process.versions?.node) {
+        throw new Error('syncLocalHistory is only available in Node.js environments')
+      }
+      
+      const fs = require('fs')
+      const path = require('path')
+      const fullPath = path.resolve(process.cwd(), filePath)
+      
+      if (!fs.existsSync(fullPath)) {
+         throw new Error(`History file not found: ${fullPath}`)
+      }
+      
+      const content = fs.readFileSync(fullPath, 'utf-8')
+      let items: any[] = []
+      
+      // Handle NDJSON or plain JSON array
+      try {
+        items = JSON.parse(content)
+      } catch (e) {
+        items = content.split('\n').filter((l: string) => l.trim()).map((l: string) => JSON.parse(l))
+      }
+      
+      if (!Array.isArray(items)) {
+         items = [items]
+      }
+      
+      if (this.config.debug) {
+        console.log(`[Observyze SDK] Syncing ${items.length} traces from ${filePath}`)
+      }
+      
+      // Send directly via api utilizing standard format
+      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()
+            throw new Error(`Batch sync failed: ${response.status} ${errorBody}`)
+         }
+         
+         if (this.config.debug) {
+            console.log(`[Observyze SDK] Synced batch of ${batch.length} traces from local history`)
+         }
+      }
+    } catch (err) {
+      console.error('[Observyze SDK] Failed to sync local history:', err)
+      throw err
+    }
+  }
+
+  /**
+   * Phase 5: PII Redaction (Compliance & RBAC)
+   * Recursively sanitize strings to mask common PII before transmitting to the cloud.
+   */
+  private sanitizePII(data: any): any {
+     if (data === null || data === undefined) return data;
+     
+     if (typeof data === 'string') {
+        return data
+           .replace(/\b[\w\.-]+@[\w\.-]+\.\w{2,4}\b/gi, '[EMAIL_REDACTED]') // Emails
+           .replace(/\b\d{3}-\d{2}-\d{4}\b/g, '[SSN_REDACTED]') // SSN
+           .replace(/\b(?:\d[ -]*?){13,16}\b/g, '[CC_REDACTED]'); // Credit Cards
+     }
+     if (Array.isArray(data)) {
+        return data.map(item => this.sanitizePII(item));
+     }
+     if (typeof data === 'object') {
+        const sanitized: any = {};
+        for (const [k, v] of Object.entries(data)) {
+           sanitized[k] = this.sanitizePII(v);
+        }
+        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.
+   */
+  async checkGuardrails(content: string | any): Promise<{ pass: boolean, score: number, reason?: string, safetyScore?: number }> {
+    if (!this.config.enableCircuitBreaker) {
+      return { pass: true, score: 0 }
+    }
+
+    try {
+      if (this.config.debug) {
+        console.log(`[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(), 5000)
+
+      let evalResult: any = 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 if (response.status === 404) {
+          if (this.config.debug) {
+            console.log('[Observyze Guardrail] Eval endpoint not found, using fallback')
+          }
+        }
+      } catch (fetchError: any) {
+        clearTimeout(timeout)
+        if (fetchError.name === 'AbortError') {
+          if (this.config.debug) {
+            console.warn('[Observyze Guardrail] Evaluation timed out after 5s')
+          }
+        } else if (this.config.debug) {
+          console.warn('[Observyze Guardrail] Evaluation request failed:', fetchError.message)
+        }
+      }
+
+      let hallucinationScore = 0
+      let safetyScore = 0
+
+      if (evalResult) {
+        hallucinationScore = evalResult.score ?? evalResult.hallucination_score ?? 0
+        safetyScore = evalResult.safety_score ?? 0
+      } else {
+        if (this.config.debug) {
+          console.log('[Observyze Guardrail] No eval result, using conservative threshold')
+        }
+        hallucinationScore = 0.5
+      }
+
+      const hallThreshold = this.config.hallucinationThreshold
+      const safeThreshold = this.config.safetyThreshold
+
+      if (hallucinationScore >= hallThreshold) {
+        if (this.config.debug) {
+          console.warn(`[Observyze Guardrail] Hallucination circuit breached! Score: ${hallucinationScore.toFixed(2)} >= ${hallThreshold}`)
+        }
+        return { 
+          pass: false, 
+          score: hallucinationScore, 
+          safetyScore,
+          reason: `Hallucination score ${hallucinationScore.toFixed(2)} exceeds threshold ${hallThreshold}. Execution blocked for human review.`
+        }
+      }
+
+      if (safetyScore >= safeThreshold) {
+        if (this.config.debug) {
+          console.warn(`[Observyze Guardrail] Safety circuit breached! Score: ${safetyScore.toFixed(2)} >= ${safeThreshold}`)
+        }
+        return { 
+          pass: false, 
+          score: hallucinationScore,
+          safetyScore,
+          reason: `Safety score ${safetyScore.toFixed(2)} exceeds threshold ${safeThreshold}. Execution blocked for safety review.`
+        }
+      }
+
+      return { pass: true, score: hallucinationScore, safetyScore }
+
+    } catch (err) {
+      console.error('[Observyze Guardrail] Failed to evaluate:', err)
+      return { pass: true, score: 0 }
+    }
+  }
+
+  /**
+   * 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<T>(agentExecution: () => Promise<T>, traceContext?: any): Promise<T> {
+    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)}, Safety: ${(guardResult.safetyScore ?? 0).toFixed(2)}. ` +
+        `Reason: ${guardResult.reason}. Human approval required before agent can continue.`)
+      
+      if (this.config.debug) {
+        console.error('[Observyze CircuitBreaker] Execution blocked:', error.message)
+      }
+      
+      throw error
+    }
+
+    if (this.config.debug) {
+      console.log(`[Observyze CircuitBreaker] Execution allowed. Hallucination: ${guardResult.score.toFixed(2)}, Safety: ${(guardResult.safetyScore ?? 0).toFixed(2)}`)
+    }
+
+    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: string, securityEndpoint: string, failureContext: any): Promise<void> {
+    try {
+      if (this.config.debug) {
+         console.log(`[Observyze SDK] Sharding persistent failure case ${traceId} to Bug Bounty Protocol endpoint...`);
+      }
+      
+      // Dispatch failure case context to security webhook
+      await fetch(securityEndpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          alert: 'persistent_failure_sharded',
+          trace_id: traceId,
+          context: failureContext,
+          timestamp: new Date().toISOString()
+        })
+      });
+      
+      if (this.config.debug) {
+         console.log(`[Observyze SDK] Bug Bounty payload successfully transmitted.`);
+      }
+    } catch (err) {
+      console.error('[Observyze Bug Bounty] Failed to shard failure case:', err);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Observyze Node.js SDK
+ * AI Observability & Governance Platform
+ */
+
+export { ObservyzeClient } from './client'
+export { Trace, Span } from './trace'
+export { SpanType, TraceStatus } from './types'
+export type { ClientConfig, ResolvedClientConfig } from './types'
+
+// Export instrumentation utilities
+export { wrap, wrapOpenAI, wrapAnthropic } from './instrumentation'
+export type { SupportedClient } from './instrumentation'
+
+// Re-export types from @observyze/types for convenience
+export type {
+  Span as SpanData,
+  Trace as TraceData,
+  SpanError,
+  TokenUsage
+} from '@observyze/types'