deadpipe 1.0.0 → 2.0.0

package/dist/index.d.ts

@@ -1,105 +1,162 @@
 /**
- * Deadpipe - Dead simple pipeline monitoring.
+ * Deadpipe - LLM observability that answers one question:
+ * "Is this prompt behaving the same as when it was last safe?"
  *
  * @example
- * import { Deadpipe } from 'deadpipe';
+ * import { track } from 'deadpipe';
+ * import OpenAI from 'openai';
  *
- * const dp = new Deadpipe('your-api-key');
+ * const client = new OpenAI();
  *
- * // Option 1: Wrapper
- * await dp.run('my-pipeline', async () => {
- *   // your code here
+ * const { response, tracker } = await track('checkout_agent', async (t) => {
+ *   const response = await client.chat.completions.create({
+ *     model: 'gpt-4',
+ *     messages: [{ role: 'user', content: 'Process refund for order 1938' }]
+ *   });
+ *   t.record(response);
+ *   return response;
  * });
  *
- * // Option 2: Manual
- * await dp.ping('my-pipeline', { status: 'success' });
+ * @example Auto-wrapping (zero code changes):
+ * import { wrapOpenAI } from 'deadpipe';
+ * import OpenAI from 'openai';
+ *
+ * const client = wrapOpenAI(new OpenAI(), { promptId: 'checkout_agent' });
+ * // All calls automatically tracked
+ * const response = await client.chat.completions.create(...);
  */
-type Status = 'success' | 'failed';
-interface PingOptions {
-    status?: Status;
-    durationMs?: number;
-    recordsProcessed?: number;
-    appName?: string;
+declare const VERSION = "2.0.0";
+type StatusType = 'success' | 'error' | 'timeout' | 'empty' | 'schema_violation' | 'refusal';
+interface PromptTelemetry {
+    prompt_id: string;
+    model?: string;
+    provider?: string;
+    app_id?: string;
+    environment?: string;
+    version?: string;
+    request_start?: string;
+    first_token_time?: number;
+    end_time?: string;
+    total_latency?: number;
+    input_tokens?: number;
+    output_tokens?: number;
+    total_tokens?: number;
+    estimated_cost_usd?: number;
+    http_status?: number;
+    timeout?: boolean;
+    retry_count?: number;
+    provider_error_code?: string;
+    error_message?: string;
+    output_length?: number;
+    empty_output?: boolean;
+    truncated?: boolean;
+    json_parse_success?: boolean;
+    schema_validation_pass?: boolean;
+    missing_required_fields?: string;
+    output_hash?: string;
+    output_embedding?: string;
+    top_logprob_mean?: number;
+    refusal_flag?: boolean;
+    tool_call_flag?: boolean;
+    tool_calls_count?: number;
+    enum_out_of_range?: boolean;
+    numeric_out_of_bounds?: boolean;
+    hallucination_flags?: string;
+    prompt_hash?: string;
+    tool_schema_hash?: string;
+    system_prompt_hash?: string;
+    status?: StatusType;
 }
-interface DeadpipeOptions {
+interface TrackOptions {
     apiKey?: string;
     baseUrl?: string;
     timeout?: number;
+    appId?: string;
+    environment?: string;
+    version?: string;
+    provider?: 'openai' | 'anthropic' | string;
+    schema?: SchemaValidator;
+    enumFields?: Record<string, unknown[]>;
+    numericBounds?: Record<string, [number | null, number | null]>;
+    messages?: Array<{
+        role: string;
+        content: string;
+        [key: string]: unknown;
+    }>;
+    tools?: Array<Record<string, unknown>>;
+    systemPrompt?: string;
+}
+interface SchemaValidator {
+    validate: (data: unknown) => {
+        success: boolean;
+        data?: unknown;
+        errors?: string[];
+    };
+}
+interface WrapOpenAIOptions extends Omit<TrackOptions, 'messages' | 'tools' | 'systemPrompt'> {
+    promptId: string;
 }
-interface HeartbeatResponse {
-    received: boolean;
-    pipeline_id: string;
-    timestamp: string;
-    freshness: 'fresh' | 'stale' | 'critical';
-    next_expected: string;
-    created?: boolean;
-    message?: string;
+declare function estimateCost(model: string, inputTokens: number, outputTokens: number): number | null;
+declare function detectRefusal(text: string): boolean;
+declare function validateEnumBounds(data: Record<string, unknown>, enumFields?: Record<string, unknown[]>): boolean;
+declare function validateNumericBounds(data: Record<string, unknown>, numericBounds?: Record<string, [number | null, number | null]>): boolean;
+interface ExtractedResponse {
+    model: string;
+    content: string;
+    inputTokens: number | null;
+    outputTokens: number | null;
+    totalTokens: number | null;
+    finishReason: string | null;
+    toolCalls: Array<{
+        name: string;
+        arguments: string;
+    }>;
+    logprobs: unknown;
 }
-declare class Deadpipe {
+declare function extractOpenAIResponse(response: any): ExtractedResponse;
+declare function extractAnthropicResponse(response: any): ExtractedResponse;
+declare class PromptTracker {
+    private promptId;
     private apiKey;
     private baseUrl;
-    private timeout;
-    /**
-     * Create a Deadpipe client.
-     *
-     * @param apiKey - Your Deadpipe API key. Falls back to DEADPIPE_API_KEY env var.
-     * @param options - Configuration options.
-     */
-    constructor(apiKey?: string, options?: Omit<DeadpipeOptions, 'apiKey'>);
-    /**
-     * Send a heartbeat ping for a pipeline.
-     *
-     * @param pipelineId - Unique identifier for this pipeline.
-     * @param options - Ping options.
-     * @returns The heartbeat response, or null if the request failed.
-     */
-    ping(pipelineId: string, options?: PingOptions): Promise<HeartbeatResponse | null>;
-    /**
-     * Run a function with automatic heartbeat on completion.
-     *
-     * @param pipelineId - Unique identifier for this pipeline.
-     * @param fn - The function to run.
-     * @param options - Additional options.
-     * @returns The result of the function.
-     *
-     * @example
-     * const result = await dp.run('daily-etl', async () => {
-     *   const records = await processData();
-     *   return { recordsProcessed: records.length };
-     * });
-     */
-    run<T>(pipelineId: string, fn: () => T | Promise<T>, options?: {
-        appName?: string;
-    }): Promise<T>;
-    /**
-     * Create a wrapper function that auto-sends heartbeats.
-     *
-     * @param pipelineId - Unique identifier for this pipeline.
-     * @param fn - The function to wrap.
-     * @param options - Additional options.
-     * @returns A wrapped function.
-     *
-     * @example
-     * const myPipeline = dp.wrap('daily-etl', async () => {
-     *   await processData();
-     * });
-     *
-     * // Later...
-     * await myPipeline();
-     */
-    wrap<T extends (...args: unknown[]) => unknown>(pipelineId: string, fn: T, options?: {
-        appName?: string;
-    }): (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>;
+    private timeoutMs;
+    private appId;
+    private environment;
+    private versionStr;
+    private provider;
+    private schema;
+    private enumFields;
+    private numericBounds;
+    private promptHash;
+    private toolSchemaHash;
+    private systemPromptHash;
+    private startTime;
+    private firstTokenTime;
+    private endTime;
+    private telemetry;
+    private recorded;
+    private retryCount;
+    constructor(promptId: string, options?: TrackOptions);
+    start(): void;
+    markFirstToken(): void;
+    markRetry(): void;
+    record(response: any, parsedOutput?: unknown): unknown;
+    recordError(error: Error): void;
+    private send;
+    isRecorded(): boolean;
+    getTelemetry(): PromptTelemetry;
 }
-/**
- * Send a heartbeat using DEADPIPE_API_KEY from environment.
- */
-declare function ping(pipelineId: string, options?: PingOptions): Promise<HeartbeatResponse | null>;
-/**
- * Run a function with automatic heartbeat using DEADPIPE_API_KEY from environment.
- */
-declare function run<T>(pipelineId: string, fn: () => T | Promise<T>, options?: {
-    appName?: string;
-}): Promise<T>;
+declare function track<T>(promptId: string, fn: (tracker: PromptTracker) => Promise<T>, options?: TrackOptions): Promise<T>;
+type OpenAIClient = any;
+interface TrackedCompletions {
+    create: (params: any) => Promise<any>;
+}
+interface TrackedChat {
+    completions: TrackedCompletions;
+}
+interface TrackedOpenAIClient extends OpenAIClient {
+    chat: TrackedChat;
+}
+declare function wrapOpenAI(client: OpenAIClient, options: WrapOpenAIOptions): TrackedOpenAIClient;
 
-export { Deadpipe, type DeadpipeOptions, type HeartbeatResponse, type PingOptions, type Status, Deadpipe as default, ping, run };
+export { type PromptTelemetry, PromptTracker, type SchemaValidator, type StatusType, type TrackOptions, VERSION, type WrapOpenAIOptions, detectRefusal, estimateCost, extractAnthropicResponse, extractOpenAIResponse, track, validateEnumBounds, validateNumericBounds, wrapOpenAI };