@observyze/sdk 0.1.4 → 0.1.5

package/dist/{index-IZdiaORv.d.mts → index-ClE8H5jj.d.mts}

@@ -1,20 +1,107 @@
-import { SpanType, TokenUsage, Span as Span$1, TraceStatus, Trace as Trace$1 } from '@observyze/types';
-
 /**
  * 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 Ingestion Service
+     * API key for authentication with Observyze
      */
     apiKey: string;
     /**
-     * Endpoint URL for the Ingestion Service
-     * @default 'http://localhost:3001'
+     * Endpoint URL for the Observyze API
+     * @default 'https://api.observyze.com'
      */
     endpoint?: string;
     /**
@@ -28,10 +115,10 @@ interface ClientConfig {
      */
     flushInterval?: number;
     /**
-     * Enable automatic instrumentation of popular LLM libraries
-     * @default true
+     * Timeout for each ingestion HTTP attempt in milliseconds.
+     * @default 10000
      */
-    enableAutoInstrumentation?: boolean;
+    requestTimeoutMs?: number;
     /**
      * Organization ID (optional, can be extracted from API key)
      */
@@ -46,63 +133,68 @@ interface ClientConfig {
      */
     debug?: boolean;
     /**
-     * Dry run mode - don't send traces to server (useful for testing)
+     * 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
+     * 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
+     * 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;
     /**
-     * Phase 4: Autonomous Circuit Breaker
-     * Safety score threshold (0-1) above which execution is blocked
+     * Safety threshold for checkGuardrails() calls.
      * @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.
+     * 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 real-time guardrail checks
-     * In production, this should be https://api.observyze.com
-     * @default 'http://localhost:3000'
+     * Evaluation service URL for guardrail checks.
+     * Defaults to the same value as `endpoint`.
      */
     evalEndpoint?: string;
     /**
-     * Enable circuit breaker - block execution on high hallucination/safety scores
+     * Enable explicit guardrail methods (checkGuardrails, executeWithCircuitBreaker).
      * @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).
+     * 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 LLM client (OpenAI, Anthropic) base URLs to Observyze proxy gateway
-     * to ensure Redis-backed circuit breakers are enforced.
+     * Automatically redirect OpenAI/Anthropic base URLs through the Observyze
+     * proxy gateway to enforce Redis-backed circuit breakers.
      * @default true
      */
     enableProxyRedirect?: boolean;
 }
 /**
- * Internal configuration with defaults applied
+ * Internal configuration with all defaults applied
  */
-interface ResolvedClientConfig extends Required<ClientConfig> {
-}
+type ResolvedClientConfig = Required<ClientConfig>;
 /**
  * Result of a connection test.
  * Verifies the SDK can reach Observyze and send a real trace end-to-end.
@@ -133,7 +225,7 @@ interface GuardrailResult {
     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') */
+    /** Why a live evaluation didn't happen */
     fallbackReason?: string;
 }
 
@@ -147,7 +239,8 @@ interface GuardrailResult {
 declare class Span {
     private data;
     private startTime;
-    constructor(name: string, type: SpanType, parentSpanId?: string);
+    private readonly captureContent;
+    constructor(name: string, type: SpanType, parentSpanId?: string, captureContent?: boolean);
     /**
      * Set the input data for this span
      */
@@ -193,7 +286,8 @@ declare class Trace {
     private startTime;
     private spans;
     private ended;
-    constructor(name: string, organizationId: string, projectId?: string);
+    private readonly captureContent;
+    constructor(name: string, organizationId: string, projectId?: string, captureContent?: boolean);
     /**
      * Start a new span within this trace
      */
@@ -240,30 +334,135 @@ declare class Trace {
     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: Function;
+            create: ClientMethod;
         };
     };
 } | {
     messages: {
-        create: Function;
+        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
@@ -279,16 +478,9 @@ declare class ObservyzeClient {
     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 readBoundedResponse;
+    private static retryAfterMs;
     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);
     /**
@@ -304,7 +496,7 @@ declare class ObservyzeClient {
      */
     private startFlushTimer;
     /**
-     * Flush all buffered traces to the Ingestion Service
+     * Flush all buffered traces to Observyze
      */
     flush(): Promise<void>;
     /**
@@ -324,7 +516,9 @@ declare class ObservyzeClient {
      */
     getConfig(): Readonly<ResolvedClientConfig>;
     /**
-     * Wrap an LLM client (OpenAI, Anthropic) to enable auto-instrumentation
+     * Wrap a supported LLM client or framework boundary to enable auto-instrumentation.
+     *
+     * Supports: OpenAI, Anthropic, Google Gemini, Vercel AI SDK, LangChain, LlamaIndex.
      *
      * @example
      * ```typescript
@@ -332,86 +526,61 @@ declare class ObservyzeClient {
      * 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)
+     * const openai = nw.wrap(new OpenAI({ apiKey: 'openai-key' }))
      *
      * // All calls are now automatically traced
      * const response = await openai.chat.completions.create({
-     *   model: 'gpt-4',
+     *   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.
      *
-     * This is the definitive "is my integration working?" test for SDK users.
-     * It sends a real test trace through the EXACT same pipeline used by
-     * `flush()` / the wrapped LLM clients (same endpoint, apiKey, retry logic),
-     * so a successful call proves the whole chain works from your code:
-     *   - apiKey is valid and authorized
-     *   - endpoint is reachable from your environment
-     *   - organization / project resolution works
-     *   - the ingest pipeline accepts and stores traces
-     *
      * @example
      * ```typescript
      * const nw = new ObservyzeClient({ apiKey: process.env.OBSERVYZE_API_KEY })
      * const result = await nw.testConnection()
-     * // { ok: true, traceId: 'nw_xxx', message: 'Connection successful...' }
+     * // { ok: true, traceId: '...', message: 'Connection successful...' }
      * ```
-     *
-     * The returned traceId can be searched in the Observyze dashboard (Traces →
-     * search the trace name "Observyze Connection Test") to confirm it landed.
      */
     testConnection(): Promise<TestConnectionResult>;
     /**
-     * Sync local agent .history file to Observyze cloud
-     * Parses JSON/NDJSON agent history and sends to ingestion endpoint.
+     * 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 (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;
+     * Industry-grade PII redaction.
+     * Recursively scrubs PII from trace data before transmission.
+     */
     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.
+     * 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, null scores result in blocked execution.
-     * In failOpen mode, null scores allow execution through.
+     * 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>;
     /**
-     * Phase 4: Autonomous Circuit Breakers
-     * Execute an agent action wrapped with the Circuit Breaker.
-     * Pauses execution if hallucination score >= hallucinationThreshold and requests human review.
+     * 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>;
-    /**
-     * 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>;
 }
 
 /**
@@ -474,4 +643,4 @@ declare class ObservyzeSpanExporter {
     forceFlush(): Promise<void>;
 }
 
-export { type ClientConfig as C, ObservyzeClient as O, type ResolvedClientConfig as R, Span as S, type TestConnectionResult as T, type ObservyzeExporterConfig as a, ObservyzeSpanExporter as b, type SupportedClient as c, Trace as d, wrap as w };
+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 };