@observyze/sdk 0.1.2 → 0.1.3

package/dist/index--b41_E-1.d.mts

@@ -0,0 +1,440 @@
+import { SpanType, TokenUsage, Span as Span$1, TraceStatus, Trace as Trace$1 } from '@observyze/types';
+
+/**
+ * SDK Configuration and Types
+ */
+
+/**
+ * Configuration for Observyze SDK client
+ */
+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;
+    /**
+     * Minimum confidence threshold for circuit breaker blocking (0-1).
+     * If confidence is below this threshold, high scores trigger alert-only instead of halt.
+     * @default 0.4
+     */
+    confidenceThreshold?: 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;
+    /**
+     * Fail closed when evaluation service is unreachable.
+     * If true, guardrail checks will block execution on errors (safe default).
+     * If false, guardrail checks will allow execution on errors (fail open).
+     * @default true
+     */
+    failClosed?: boolean;
+    /**
+     * Automatically redirect LLM client (OpenAI, Anthropic) base URLs to Observyze proxy gateway
+     * to ensure Redis-backed circuit breakers are enforced.
+     * @default true
+     */
+    enableProxyRedirect?: boolean;
+}
+/**
+ * Internal configuration with defaults applied
+ */
+interface ResolvedClientConfig extends Required<ClientConfig> {
+}
+/**
+ * Result of a guardrail evaluation check.
+ * score is null when evaluation could not be performed.
+ */
+interface GuardrailResult {
+    pass: boolean;
+    /** The hallucination score (0-1), or null if evaluation failed */
+    score: number | null;
+    /** Confidence in the evaluation score (0-1), null if unavailable */
+    confidence?: number | null;
+    /** The safety score (0-1), or null if evaluation failed */
+    safetyScore?: number | null;
+    /** Human-readable reason for the result */
+    reason?: string;
+    /** How the evaluation was performed */
+    evaluationSource?: 'live' | 'consensus' | 'nli_fast_path' | 'error' | 'disabled' | 'fallback';
+    /** Why a live evaluation didn't happen (only set when evaluationSource is 'error' or 'fallback') */
+    fallbackReason?: string;
+}
+
+/**
+ * Trace and Span classes for capturing AI workflow execution
+ */
+
+/**
+ * Represents an individual operation within a trace
+ */
+declare class Span {
+    private data;
+    private startTime;
+    constructor(name: string, type: SpanType, parentSpanId?: string);
+    /**
+     * Set the input data for this span
+     */
+    setInput(input: any): this;
+    /**
+     * Set the output data for this span
+     */
+    setOutput(output: any): this;
+    /**
+     * Record an error that occurred during span execution
+     */
+    setError(error: Error): this;
+    /**
+     * Set metadata for this span
+     */
+    setMetadata(key: string, value: any): this;
+    /**
+     * Set multiple metadata fields at once
+     */
+    setMetadataAll(metadata: Record<string, any>): this;
+    /**
+     * Set token usage information
+     */
+    setTokens(tokens: TokenUsage): this;
+    /**
+     * End the span and calculate duration
+     */
+    end(): void;
+    /**
+     * Get the span ID
+     */
+    get id(): string;
+    /**
+     * Get the span data for serialization
+     */
+    toJSON(): Span$1;
+}
+/**
+ * Represents a complete AI workflow execution
+ */
+declare class Trace {
+    private data;
+    private startTime;
+    private spans;
+    private ended;
+    constructor(name: string, organizationId: string, projectId?: string);
+    /**
+     * Start a new span within this trace
+     */
+    startSpan(name: string, type: SpanType, parentSpanId?: string): Span;
+    /**
+     * Add metadata to the trace
+     */
+    setMetadata(key: string, value: any): this;
+    /**
+     * Set multiple metadata fields at once
+     */
+    setMetadataAll(metadata: Record<string, any>): this;
+    /**
+     * Add tags to the trace
+     */
+    addTag(tag: string): this;
+    /**
+     * Add multiple tags at once
+     */
+    addTags(tags: string[]): this;
+    /**
+     * Set the user ID associated with this trace
+     */
+    setUserId(userId: string): this;
+    /**
+     * Set the session ID associated with this trace
+     */
+    setSessionId(sessionId: string): this;
+    /**
+     * End the trace with a final status
+     */
+    end(status?: TraceStatus): void;
+    /**
+     * Get the trace ID
+     */
+    get id(): string;
+    /**
+     * Check if the trace has ended
+     */
+    get isEnded(): boolean;
+    /**
+     * Get the trace data for serialization
+     */
+    toJSON(): Omit<Trace$1, '_id' | 'created_at' | 'updated_at'>;
+}
+
+/**
+ * Auto-Instrumentation API
+ * Provides nw.wrap() API for instrumenting LLM clients
+ */
+
+/**
+ * Supported client types for auto-instrumentation
+ */
+type SupportedClient = {
+    chat: {
+        completions: {
+            create: Function;
+        };
+    };
+} | {
+    messages: {
+        create: Function;
+    };
+};
+/**
+ * Detect the type of LLM client and apply appropriate instrumentation
+ */
+declare function wrap<T extends SupportedClient>(client: T, nwClient: ObservyzeClient): T;
+
+/**
+ * Observyze SDK Client
+ * Main entry point for instrumenting AI applications
+ */
+
+/**
+ * Main SDK client for Observyze
+ */
+declare class ObservyzeClient {
+    private config;
+    private traceBuffer;
+    private flushTimer;
+    private isShuttingDown;
+    private readonly MAX_QUEUE_SIZE;
+    private readonly RETRY_DELAYS;
+    /**
+     * 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.
+     */
+    private static parseApiError;
+    /**
+     * 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..."
+     */
+    private static formatApiError;
+    constructor(config: ClientConfig);
+    /**
+     * Start a new trace
+     */
+    startTrace(name: string, metadata?: Record<string, any>): Trace;
+    /**
+     * Buffer a completed trace for batch sending
+     */
+    private bufferTrace;
+    /**
+     * Start the auto-flush timer
+     */
+    private startFlushTimer;
+    /**
+     * Flush all buffered traces to the Ingestion Service
+     */
+    flush(): Promise<void>;
+    /**
+     * Send traces with exponential backoff retry
+     */
+    private sendWithRetry;
+    /**
+     * Shutdown the SDK and flush remaining traces
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get current buffer size
+     */
+    get bufferSize(): number;
+    /**
+     * Get SDK configuration
+     */
+    getConfig(): Readonly<ResolvedClientConfig>;
+    /**
+     * 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 extends SupportedClient>(client: T): T;
+    /**
+     * Sync local agent .history file to Observyze cloud
+     * Parses JSON/NDJSON agent history and sends to ingestion endpoint.
+     */
+    syncLocalHistory(filePath: string): Promise<void>;
+    /**
+     * 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
+     */
+    private static readonly PII_PATTERNS;
+    private static readonly SENSITIVE_KEYS;
+    private static isSensitiveKey;
+    private sanitizePII;
+    /**
+     * 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.
+     */
+    checkGuardrails(content: string | any): Promise<GuardrailResult>;
+    /**
+     * 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
+     */
+    executeWithCircuitBreaker<T>(agentExecution: () => Promise<T>, traceContext?: any): Promise<T>;
+    /**
+     * Phase 4: Bug Bounty Protocol (Automated) (Requirement 4.2)
+     * Automatically shard persistent failure cases to external security researcher endpoints (e.g. HackerOne wrapper)
+     */
+    reportBugBounty(traceId: string, securityEndpoint: string, failureContext: any): Promise<void>;
+}
+
+/**
+ * Observyze OpenTelemetry Span Exporter
+ *
+ * Implements `@opentelemetry/sdk-trace-base`'s `SpanExporter` interface
+ * so users can use the standard OTel Node.js SDK and export spans to
+ * the Observyze platform.
+ *
+ * Usage:
+ * ```typescript
+ * import { ObservyzeClient } from '@observyze/sdk'
+ * import { ObservyzeSpanExporter } from '@observyze/sdk/opentelemetry'
+ * import { NodeSDK } from '@opentelemetry/sdk-node'
+ * import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base'
+ *
+ * const nw = new ObservyzeClient({ apiKey: 'nw_...' })
+ *
+ * const sdk = new NodeSDK({
+ *   spanProcessor: new BatchSpanProcessor(
+ *     new ObservyzeSpanExporter(nw, { serviceName: 'my-app' })
+ *   )
+ * })
+ * sdk.start()
+ * ```
+ */
+
+/**
+ * Exporter configuration
+ */
+interface ObservyzeExporterConfig {
+    serviceName?: string;
+    projectId?: string;
+    defaultSpanType?: SpanType | 'llm' | 'tool' | 'agent' | 'chain' | 'retrieval';
+    headers?: Record<string, string>;
+}
+/**
+ * Observyze OpenTelemetry Span Exporter
+ */
+declare class ObservyzeSpanExporter {
+    private client;
+    private config;
+    constructor(client: ObservyzeClient, config?: ObservyzeExporterConfig);
+    /**
+     * Export spans — called by OTel SDK when spans are ready.
+     * Converts OTel spans to Observyze traces and buffers them.
+     */
+    export(spans: any[], resultCallback: (result: {
+        code: number;
+        error?: Error;
+    }) => void): Promise<void>;
+    /**
+     * Called when the exporter is shut down.
+     * Flushes any remaining buffered traces via the SDK client.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Called by the OTel SDK to force-export buffered spans.
+     */
+    forceFlush(): Promise<void>;
+}
+
+export { type ClientConfig as C, ObservyzeClient as O, type ResolvedClientConfig as R, Span as S, Trace as T, type ObservyzeExporterConfig as a, ObservyzeSpanExporter as b, type SupportedClient as c, wrap as w };