@observyze/sdk 0.1.0

package/src/trace.ts

@@ -0,0 +1,242 @@
+/**
+ * Trace and Span classes for capturing AI workflow execution
+ */
+
+import { SpanType, TraceStatus } from './types'
+import type { Span as SpanData, Trace as TraceData, TokenUsage } from '@observyze/types'
+
+/**
+ * Generates a unique ID for traces and spans
+ */
+function generateId(): string {
+  return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`
+}
+
+/**
+ * Represents an individual operation within a trace
+ */
+export class Span {
+  private data: SpanData
+  private startTime: number
+
+  constructor(name: string, type: SpanType, parentSpanId?: string) {
+    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: any): this {
+    this.data.input = input
+    return this
+  }
+
+  /**
+   * Set the output data for this span
+   */
+  setOutput(output: any): this {
+    this.data.output = output
+    return this
+  }
+
+  /**
+   * Record an error that occurred during span execution
+   */
+  setError(error: Error): this {
+    this.data.error = {
+      message: error.message,
+      stack: error.stack,
+      code: (error as any).code
+    }
+    return this
+  }
+
+  /**
+   * Set metadata for this span
+   */
+  setMetadata(key: string, value: any): this {
+    this.data.metadata[key] = value
+    return this
+  }
+
+  /**
+   * Set multiple metadata fields at once
+   */
+  setMetadataAll(metadata: Record<string, any>): this {
+    this.data.metadata = { ...this.data.metadata, ...metadata }
+    return this
+  }
+
+  /**
+   * Set token usage information
+   */
+  setTokens(tokens: TokenUsage): this {
+    this.data.tokens = tokens
+    return this
+  }
+
+  /**
+   * End the span and calculate duration
+   */
+  end(): void {
+    const endTime = Date.now()
+    this.data.end_time = new Date(endTime)
+    this.data.duration_ms = endTime - this.startTime
+  }
+
+  /**
+   * Get the span ID
+   */
+  get id(): string {
+    return this.data.span_id
+  }
+
+  /**
+   * Get the span data for serialization
+   */
+  toJSON(): SpanData {
+    return { ...this.data }
+  }
+}
+
+/**
+ * Represents a complete AI workflow execution
+ */
+export class Trace {
+  private data: Omit<TraceData, '_id' | 'created_at' | 'updated_at'>
+  private startTime: number
+  private spans: Span[] = []
+  private ended: boolean = false
+
+  constructor(
+    name: string,
+    organizationId: string,
+    projectId?: string
+  ) {
+    this.startTime = Date.now()
+    this.data = {
+      trace_id: generateId(),
+      organization_id: organizationId,
+      project_id: projectId,
+      name,
+      status: 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: string, type: SpanType, parentSpanId?: string): Span {
+    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: string, value: any): this {
+    this.data.metadata[key] = value
+    return this
+  }
+
+  /**
+   * Set multiple metadata fields at once
+   */
+  setMetadataAll(metadata: Record<string, any>): this {
+    this.data.metadata = { ...this.data.metadata, ...metadata }
+    return this
+  }
+
+  /**
+   * Add tags to the trace
+   */
+  addTag(tag: string): this {
+    if (!this.data.tags.includes(tag)) {
+      this.data.tags.push(tag)
+    }
+    return this
+  }
+
+  /**
+   * Add multiple tags at once
+   */
+  addTags(tags: string[]): this {
+    tags.forEach(tag => this.addTag(tag))
+    return this
+  }
+
+  /**
+   * Set the user ID associated with this trace
+   */
+  setUserId(userId: string): this {
+    this.data.user_id = userId
+    return this
+  }
+
+  /**
+   * Set the session ID associated with this trace
+   */
+  setSessionId(sessionId: string): this {
+    this.data.session_id = sessionId
+    return this
+  }
+
+  /**
+   * End the trace with a final status
+   */
+  end(status: TraceStatus = TraceStatus.SUCCESS): void {
+    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(): string {
+    return this.data.trace_id
+  }
+
+  /**
+   * Check if the trace has ended
+   */
+  get isEnded(): boolean {
+    return this.ended
+  }
+
+  /**
+   * Get the trace data for serialization
+   */
+  toJSON(): Omit<TraceData, '_id' | 'created_at' | 'updated_at'> {
+    return { ...this.data }
+  }
+}

package/src/types.ts

@@ -0,0 +1,102 @@
+/**
+ * SDK Configuration and Types
+ */
+
+// Re-export types from @observyze/types for convenience
+export { SpanType, TraceStatus } from '@observyze/types'
+
+/**
+ * Configuration for Observyze SDK client
+ */
+export interface ClientConfig {
+  /**
+   * API key for authentication with Observyze Ingestion Service
+   */
+  apiKey: string
+
+  /**
+   * Endpoint URL for the Ingestion Service
+   * @default 'http://localhost:3001'
+   */
+  endpoint?: string
+
+  /**
+   * Maximum number of traces to buffer before flushing
+   * @default 100
+   */
+  batchSize?: number
+
+  /**
+   * Time in milliseconds to wait before auto-flushing buffered traces
+   * @default 5000
+   */
+  flushInterval?: number
+
+  /**
+   * Enable automatic instrumentation of popular LLM libraries
+   * @default true
+   */
+  enableAutoInstrumentation?: boolean
+
+  /**
+   * Organization ID (optional, can be extracted from API key)
+   */
+  organizationId?: string
+
+  /**
+   * Project ID for trace attribution
+   */
+  projectId?: string
+
+  /**
+   * Enable debug logging
+   * @default false
+   */
+  debug?: boolean
+
+  /**
+   * Dry run mode - don't send traces to server (useful for testing)
+   * @default false
+   */
+  dryRun?: boolean
+  
+  /**
+   * Phase 5: Automatically scrub PII from trace output before network transmission
+   * @default true
+   */
+  enablePiiRedaction?: boolean
+
+  /**
+   * Phase 4: Autonomous Circuit Breaker
+   * Hallucination score threshold (0-1) above which execution is blocked
+   * @default 0.8
+   */
+  hallucinationThreshold?: number
+
+  /**
+   * Phase 4: Autonomous Circuit Breaker
+   * Safety score threshold (0-1) above which execution is blocked
+   * @default 0.9
+   */
+  safetyThreshold?: number
+
+  /**
+   * Evaluation service URL for real-time guardrail checks
+   * In production, this should be https://api.observyze.com
+   * @default 'http://localhost:3000'
+   */
+  evalEndpoint?: string
+
+  /**
+   * Enable circuit breaker - block execution on high hallucination/safety scores
+   * @default true
+   */
+  enableCircuitBreaker?: boolean
+}
+
+/**
+ * Internal configuration with defaults applied
+ */
+export interface ResolvedClientConfig extends Required<ClientConfig> {
+  // All fields are required after defaults are applied
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "composite": false,
+    "incremental": false
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}