@observyze/sdk 0.1.3 → 0.1.5

package/dist/index-ClE8H5jj.d.mts

@@ -0,0 +1,646 @@
+/**
+ * SDK Configuration and Types
+ */
+/**
+ * Type of span operation
+ */
+declare enum SpanType {
+    LLM = "llm",
+    TOOL = "tool",
+    AGENT = "agent",
+    CHAIN = "chain",
+    RETRIEVAL = "retrieval",
+    EMBEDDING = "embedding",
+    CUSTOM = "custom"
+}
+/**
+ * Status of trace execution
+ */
+declare enum TraceStatus {
+    SUCCESS = "success",
+    ERROR = "error",
+    TIMEOUT = "timeout",
+    RUNNING = "running"
+}
+/**
+ * Error information for a span
+ */
+interface SpanError {
+    message: string;
+    stack?: string;
+    code?: string;
+}
+/**
+ * Token usage information
+ */
+interface TokenUsage {
+    input: number;
+    output: number;
+    total: number;
+    computed_pixels?: number;
+    audio_seconds?: number;
+}
+/**
+ * Individual operation within a trace
+ */
+interface Span$1 {
+    span_id: string;
+    parent_span_id?: string;
+    name: string;
+    type: SpanType;
+    start_time: Date;
+    end_time: Date;
+    duration_ms: number;
+    input: any;
+    output: any;
+    error?: SpanError;
+    metadata: {
+        model?: string;
+        provider?: string;
+        temperature?: number;
+        max_tokens?: number;
+        [key: string]: any;
+    };
+    tokens?: TokenUsage;
+}
+/**
+ * Complete record of an AI workflow execution
+ */
+interface Trace$1 {
+    trace_id: string;
+    organization_id: string;
+    project_id?: string;
+    name: string;
+    provider?: string;
+    model?: string;
+    status: TraceStatus;
+    start_time: Date;
+    end_time: Date;
+    duration_ms: number;
+    metadata: Record<string, any>;
+    spans: Span$1[];
+    tags: string[];
+    user_id?: string;
+    session_id?: string;
+    cost?: number;
+    cost_breakdown?: {
+        tokens: number;
+        pixels: number;
+        audio: number;
+    };
+    created_at: Date;
+    updated_at: Date;
+}
+/**
+ * Configuration for Observyze SDK client
+ */
+interface ClientConfig {
+    /**
+     * API key for authentication with Observyze
+     */
+    apiKey: string;
+    /**
+     * Endpoint URL for the Observyze API
+     * @default 'https://api.observyze.com'
+     */
+    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;
+    /**
+     * Timeout for each ingestion HTTP attempt in milliseconds.
+     * @default 10000
+     */
+    requestTimeoutMs?: number;
+    /**
+     * 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;
+    /**
+     * Automatically scrub PII from trace output before network transmission
+     * @default true
+     */
+    enablePiiRedaction?: boolean;
+    /**
+     * Capture prompt/completion content and arbitrary user metadata in traces.
+     * Set to false for metadata-only telemetry: names, inputs, outputs, errors,
+     * user/session identifiers, and tags are omitted locally before a trace
+     * can enter the dispatch buffer.
+     * @default true
+     */
+    captureContent?: boolean;
+    /**
+     * Hallucination threshold for checkGuardrails() calls.
+     * @default 0.8
+     */
+    hallucinationThreshold?: number;
+    /**
+     * Safety threshold for checkGuardrails() calls.
+     * @default 0.9
+     */
+    safetyThreshold?: number;
+    /**
+     * Minimum confidence threshold for guardrail blocking (0-1).
+     * When confidence is below this value, high scores trigger an alert-only
+     * response instead of halting execution.
+     * @default 0.4
+     */
+    confidenceThreshold?: number;
+    /**
+     * Evaluation service URL for guardrail checks.
+     * Defaults to the same value as `endpoint`.
+     */
+    evalEndpoint?: string;
+    /**
+     * Enable explicit guardrail methods (checkGuardrails, executeWithCircuitBreaker).
+     * @default true
+     */
+    enableCircuitBreaker?: boolean;
+    /**
+     * Fail closed when the evaluation service is unreachable.
+     * true = block execution on errors (safe default).
+     * false = allow execution on errors.
+     * @default true
+     */
+    failClosed?: boolean;
+    /**
+     * Automatically redirect OpenAI/Anthropic base URLs through the Observyze
+     * proxy gateway to enforce Redis-backed circuit breakers.
+     * @default true
+     */
+    enableProxyRedirect?: boolean;
+}
+/**
+ * Internal configuration with all defaults applied
+ */
+type ResolvedClientConfig = Required<ClientConfig>;
+/**
+ * Result of a connection test.
+ * Verifies the SDK can reach Observyze and send a real trace end-to-end.
+ */
+interface TestConnectionResult {
+    /** Whether the test trace was accepted by Observyze */
+    ok: boolean;
+    /** The trace ID of the sent test trace (present when ok === true) */
+    traceId?: string;
+    /** HTTP status returned by the API (present when the request failed) */
+    status?: number;
+    /** Human-readable message with the outcome or the exact failure reason */
+    message: string;
+}
+/**
+ * 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 */
+    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;
+    private readonly captureContent;
+    constructor(name: string, type: SpanType, parentSpanId?: string, captureContent?: boolean);
+    /**
+     * 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;
+    private readonly captureContent;
+    constructor(name: string, organizationId: string, projectId?: string, captureContent?: boolean);
+    /**
+     * 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'>;
+}
+
+interface LangChainRunnableLike {
+    invoke: (input: unknown, config?: unknown) => Promise<unknown>;
+    stream?: (input: unknown, config?: unknown) => Promise<AsyncIterable<unknown>> | AsyncIterable<unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Instruments a LangChain-compatible Runnable boundary without taking a hard
+ * dependency on LangChain. It captures invoke() and stream(); provider-specific
+ * inner spans still require wrapping the underlying provider client.
+ */
+declare function wrapLangChain<T extends LangChainRunnableLike>(runnable: T, nwClient: ObservyzeClient): T;
+
+type Callable$2 = (...args: any[]) => any;
+type GeminiMethodSurface = ({
+    generateContent: Callable$2;
+    generateContentStream?: Callable$2;
+} | {
+    generateContent?: Callable$2;
+    generateContentStream: Callable$2;
+}) & Record<string, unknown>;
+type GeminiClientLike = GeminiMethodSurface | ({
+    models: GeminiMethodSurface;
+} & Record<string, unknown>);
+/** Supports both @google/generative-ai model objects and @google/genai clients. */
+declare function wrapGemini<T extends GeminiClientLike>(client: T, nwClient: ObservyzeClient): T;
+
+type Callable$1 = (...args: any[]) => any;
+type VercelAILike = ({
+    generateText: Callable$1;
+    streamText?: Callable$1;
+} | {
+    generateText?: Callable$1;
+    streamText: Callable$1;
+}) & Record<string, unknown>;
+/**
+ * Wraps the Vercel AI SDK function surface. A new object is returned because
+ * ESM namespace imports are immutable and cannot be monkey-patched safely.
+ */
+declare function wrapVercelAI<T extends VercelAILike>(sdk: T, nwClient: ObservyzeClient): T;
+
+type Callable = (...args: any[]) => any;
+type LlamaIndexEngineLike = ({
+    query: Callable;
+    chat?: Callable;
+} | {
+    query?: Callable;
+    chat: Callable;
+}) & Record<string, unknown>;
+/** Instruments LlamaIndex QueryEngine and ChatEngine method boundaries. */
+declare function wrapLlamaIndex<T extends LlamaIndexEngineLike>(engine: T, nwClient: ObservyzeClient): T;
+
+/**
+ * Auto-Instrumentation API
+ * Provides nw.wrap() API for instrumenting LLM clients
+ */
+
+type ClientMethod = (...args: any[]) => any;
+/**
+ * Supported client types for auto-instrumentation
+ */
+type SupportedClient = {
+    chat: {
+        completions: {
+            create: ClientMethod;
+        };
+    };
+} | {
+    messages: {
+        create: ClientMethod;
+    };
+} | GeminiClientLike | VercelAILike | LlamaIndexEngineLike | LangChainRunnableLike;
+/**
+ * Detect the type of LLM client and apply appropriate instrumentation
+ */
+declare function wrap<T extends SupportedClient>(client: T, nwClient: ObservyzeClient): T;
+
+interface ExecutionBudgetOptions {
+    /** Maximum provider/tool operations allowed in this run. */
+    maxCalls: number;
+    /** Maximum cumulative tokens. Omit when token usage is not available. */
+    maxTokens?: number;
+    /** Wall-clock deadline for the complete run in milliseconds. */
+    timeoutMs: number;
+}
+interface ExecutionBudgetStats {
+    callsUsed: number;
+    tokensUsed: number;
+    elapsedMs: number;
+    remainingCalls: number;
+    remainingTokens: number | null;
+    remainingMs: number;
+    aborted: boolean;
+}
+declare class ExecutionBudgetExceededError extends Error {
+    readonly dimension: 'calls' | 'tokens' | 'time';
+    readonly code = "OBSERVYZE_EXECUTION_BUDGET_EXCEEDED";
+    constructor(dimension: 'calls' | 'tokens' | 'time', message: string);
+}
+/**
+ * Active, process-local agent execution budget. Use one instance for one
+ * agent/session run and execute every provider/tool action through run().
+ * The callback receives an AbortSignal and must pass it to the underlying SDK
+ * for transport-level cancellation; run() still rejects at the deadline if a
+ * third-party SDK ignores the signal.
+ *
+ * @example
+ * ```typescript
+ * const budget = new ExecutionBudget({ maxCalls: 20, maxTokens: 50_000, timeoutMs: 30_000 })
+ *
+ * const result = await budget.run(async (signal) => {
+ *   return openai.chat.completions.create({ ... }, { signal })
+ * })
+ * ```
+ */
+declare class ExecutionBudget {
+    private readonly options;
+    private readonly startedAt;
+    private readonly controller;
+    private callsUsed;
+    private tokensUsed;
+    constructor(options: ExecutionBudgetOptions);
+    get signal(): AbortSignal;
+    get stats(): ExecutionBudgetStats;
+    abort(reason?: string): void;
+    consumeTokens(tokens: number): void;
+    run<T>(operation: (signal: AbortSignal) => Promise<T>, reservedTokens?: number): Promise<T>;
+    private assertTime;
+}
+
+/**
+ * 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;
+    private static readBoundedResponse;
+    private static retryAfterMs;
+    private static parseApiError;
+    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 Observyze
+     */
+    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 a supported LLM client or framework boundary to enable auto-instrumentation.
+     *
+     * Supports: OpenAI, Anthropic, Google Gemini, Vercel AI SDK, LangChain, LlamaIndex.
+     *
+     * @example
+     * ```typescript
+     * import OpenAI from 'openai'
+     * import { ObservyzeClient } from '@observyze/sdk'
+     *
+     * const nw = new ObservyzeClient({ apiKey: 'your-api-key' })
+     * const openai = nw.wrap(new OpenAI({ apiKey: 'openai-key' }))
+     *
+     * // All calls are now automatically traced
+     * const response = await openai.chat.completions.create({
+     *   model: 'gpt-4o',
+     *   messages: [{ role: 'user', content: 'Hello!' }]
+     * })
+     * ```
+     */
+    wrap<T extends SupportedClient>(client: T): T;
+    /** Create an active call/token/time budget for one agent execution. */
+    createExecutionBudget(options: ExecutionBudgetOptions): ExecutionBudget;
+    /**
+     * Verify that the SDK can reach Observyze and send traces end-to-end.
+     *
+     * @example
+     * ```typescript
+     * const nw = new ObservyzeClient({ apiKey: process.env.OBSERVYZE_API_KEY })
+     * const result = await nw.testConnection()
+     * // { ok: true, traceId: '...', message: 'Connection successful...' }
+     * ```
+     */
+    testConnection(): Promise<TestConnectionResult>;
+    /**
+     * Sync a local agent .history file to Observyze cloud.
+     * Parses JSON/NDJSON agent history and sends to the ingestion endpoint.
+     */
+    syncLocalHistory(filePath: string): Promise<void>;
+    /**
+     * Industry-grade PII redaction.
+     * Recursively scrubs PII from trace data before transmission.
+     */
+    private sanitizePII;
+    /**
+     * Explicitly evaluate content before an application action.
+     * Requires an active Observyze subscription with guardrails enabled.
+     *
+     * Returns GuardrailResult with score: null when evaluation couldn't be performed.
+     * In failClosed mode (default), null scores block execution.
+     *
+     * @example
+     * ```typescript
+     * const result = await nw.checkGuardrails(llmOutput)
+     * if (!result.pass) {
+     *   throw new Error('Guardrail blocked: ' + result.reason)
+     * }
+     * ```
+     */
+    checkGuardrails(content: string | any): Promise<GuardrailResult>;
+    /**
+     * Execute an application action only after an explicit pre-execution
+     * guardrail check passes.
+     * @throws Error when execution is blocked by circuit breaker
+     */
+    executeWithCircuitBreaker<T>(agentExecution: () => Promise<T>, traceContext?: any): Promise<T>;
+}
+
+/**
+ * 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, ExecutionBudget as E, type GeminiClientLike as G, type LangChainRunnableLike as L, ObservyzeClient as O, type ResolvedClientConfig as R, Span as S, type TestConnectionResult as T, type VercelAILike as V, ExecutionBudgetExceededError as a, type ExecutionBudgetOptions as b, type ExecutionBudgetStats as c, type GuardrailResult as d, type LlamaIndexEngineLike as e, type ObservyzeExporterConfig as f, ObservyzeSpanExporter as g, type Span$1 as h, type SpanError as i, SpanType as j, type SupportedClient as k, type TokenUsage as l, Trace as m, type Trace$1 as n, TraceStatus as o, wrapGemini as p, wrapLangChain as q, wrapLlamaIndex as r, wrapVercelAI as s, wrap as w };