xray-sdk 0.1.0

package/dist/reasoning/generator.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOpenAIGenerator = createOpenAIGenerator;
+exports.createSimpleGenerator = createSimpleGenerator;
+/**
+ * Default reasoning generator using OpenAI
+ * Users can provide their own OpenAI client instance
+ */
+function createOpenAIGenerator(openaiClient) {
+    return async (step) => {
+        console.log(`[XRay LLM] 🚀 Generating reasoning for step: ${step.name}`);
+        // Try numeric reasoning first (free, fast)
+        const numericReasoning = generateNumericReasoning(step);
+        if (numericReasoning) {
+            console.log(`[XRay LLM] ✓ Using numeric reasoning: "${numericReasoning}"`);
+            return numericReasoning;
+        }
+        // Handle errors
+        if (step.error) {
+            return `❌ ${step.name} failed: ${step.error}`;
+        }
+        try {
+            const prompt = `You are an AI pipeline observability expert. Generate a concise 1-2 sentence explanation for this step.
+
+Input: ${JSON.stringify(step.input ?? {})}
+
+Output: ${JSON.stringify(step.output ?? {})}
+
+Rules:
+- Be specific and mention counts, thresholds, or key decisions
+- Use neutral, technical language
+- Do NOT restate raw data verbatim
+- ONLY return the reasoning text, no JSON formatting
+
+Reasoning:`;
+            console.log(`[XRay LLM] 📤 Sending request to OpenAI API...`);
+            const completion = await openaiClient.chat.completions.create({
+                model: "gpt-4o-mini",
+                messages: [{ role: "user", content: prompt }],
+                max_tokens: 150,
+                temperature: 0.1,
+            });
+            console.log(`[XRay LLM] ✓ Received response from OpenAI API`);
+            const rawResponse = completion.choices[0]?.message?.content?.trim() || "Step processed";
+            console.log(`[XRay LLM] 📝 Raw response (${rawResponse.length} chars): "${rawResponse}"`);
+            // Clean up the response
+            let reasoning = rawResponse
+                .replace(/^Reasoning:\s*/i, '')
+                .replace(/```json\s*/g, '')
+                .replace(/```\s*/g, '')
+                .trim();
+            // If response looks like truncated JSON, return fallback
+            if (reasoning.startsWith('{') && !reasoning.endsWith('}')) {
+                console.log(`[XRay LLM] ⚠️  Detected truncated JSON response, using fallback`);
+                const fallback = generateNumericReasoning(step) || `Processed ${step.name}`;
+                console.log(`[XRay LLM] ✓ Using fallback: "${fallback}"`);
+                return fallback;
+            }
+            console.log(`[XRay LLM] ✅ Final reasoning (${reasoning.length} chars): "${reasoning}"`);
+            return reasoning;
+        }
+        catch (error) {
+            console.error(`[XRay LLM] ❌ OpenAI API failed for step ${step.name}:`, error.message);
+            const fallback = generateNumericReasoning(step) || `✅ ${step.name} processed`;
+            console.log(`[XRay LLM] ✓ Using fallback: "${fallback}"`);
+            return fallback;
+        }
+    };
+}
+/**
+ * Simple reasoning generator (no LLM)
+ * Returns numeric summaries based on step data
+ */
+function createSimpleGenerator() {
+    return async (step) => {
+        if (step.error) {
+            return `❌ ${step.name} failed: ${step.error}`;
+        }
+        const numericReasoning = generateNumericReasoning(step);
+        if (numericReasoning) {
+            return numericReasoning;
+        }
+        return `✅ ${step.name} processed (${step.durationMs ?? 0}ms)`;
+    };
+}
+function generateNumericReasoning(step) {
+    const input = step.input ?? {};
+    const output = step.output ?? {};
+    // Ranking/Selection steps
+    if (output.ranked_candidates && output.selection) {
+        const count = output.ranked_candidates?.length ?? 0;
+        const selectionTitle = output.selection?.title ?? output.selection?.asin ?? 'top choice';
+        return `Ranked ${count} candidate(s) and selected "${selectionTitle}" as top choice`;
+    }
+    // Filter pass/fail
+    const total = output.total_evaluated ?? output.total_evaluated ?? output.evaluated?.length;
+    const passed = output.passed ?? output.accepted ?? output.remaining?.length;
+    if (total && passed !== undefined) {
+        return `📊 ${passed}/${total} passed`;
+    }
+    // Search results
+    const found = output.total_results ?? output.total_found ?? output.total;
+    const returned = output.candidates_fetched ?? output.candidates?.length;
+    if (found && returned) {
+        return `🔍 ${found}→${returned} results`;
+    }
+    // Size change (only if different)
+    const inputCount = getArrayLength(input);
+    const outputCount = getArrayLength(output);
+    if (inputCount && outputCount && inputCount !== outputCount) {
+        return `🔄 ${inputCount}→${outputCount} items`;
+    }
+    return null;
+}
+function getArrayLength(obj) {
+    if (Array.isArray(obj))
+        return obj.length;
+    return obj?.candidates?.length ?? obj?.items?.length ?? obj?.remaining?.length ?? obj?.ranked_candidates?.length ?? null;
+}

package/dist/reasoning/queue.d.ts

@@ -0,0 +1,57 @@
+import PQueue from 'p-queue';
+import { ReasoningConfig } from './config';
+import { ReasoningGenerator } from './generator';
+import { ReasoningJob, QueueStats, StorageProvider } from '../types';
+export declare class ReasoningQueue {
+    private jobs;
+    private queue;
+    private config;
+    private storage;
+    private generator;
+    private prisma?;
+    constructor(storage: StorageProvider, generator: ReasoningGenerator, config?: Partial<ReasoningConfig>, prismaClient?: any);
+    /**
+     * Load pending jobs from database (for recovery after restart)
+     */
+    private loadPendingJobs;
+    /**
+     * Enqueue a single step for reasoning generation
+     */
+    enqueue(executionId: string, stepName: string): Promise<string>;
+    /**
+     * Enqueue all steps from an execution that don't have reasoning
+     */
+    enqueueExecution(executionId: string): Promise<string[]>;
+    /**
+     * Process a single job with retry logic
+     */
+    private processJob;
+    /**
+     * Handle job error with retry logic
+     */
+    private handleJobError;
+    /**
+     * Check if error is retryable
+     */
+    private isRetryableError;
+    /**
+     * Process all steps in an execution
+     */
+    processExecution(executionId: string): Promise<void>;
+    /**
+     * Get queue statistics
+     */
+    getStats(): QueueStats;
+    /**
+     * Get job by ID
+     */
+    getJob(jobId: string): ReasoningJob | undefined;
+    /**
+     * Clear all jobs
+     */
+    clear(): void;
+    /**
+     * Get underlying p-queue
+     */
+    get pqueue(): PQueue;
+}

package/dist/reasoning/queue.js

@@ -0,0 +1,309 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReasoningQueue = void 0;
+// Database-backed queue for asynchronous reasoning generation
+const p_queue_1 = __importDefault(require("p-queue"));
+const config_1 = require("./config");
+const crypto_1 = require("crypto");
+class ReasoningQueue {
+    constructor(storage, generator, config = {}, prismaClient) {
+        this.config = { ...config_1.DEFAULT_REASONING_CONFIG, ...config };
+        this.storage = storage;
+        this.generator = generator;
+        this.prisma = prismaClient;
+        this.jobs = new Map();
+        this.queue = new p_queue_1.default({ concurrency: this.config.concurrency });
+        if (this.config.debug) {
+            console.log('[XRay Queue] Reasoning queue initialized', {
+                concurrency: this.config.concurrency,
+                maxRetries: this.config.maxRetries
+            });
+        }
+        // Load pending jobs from database if available
+        if (this.prisma) {
+            this.loadPendingJobs().catch(error => {
+                console.error('[XRay Queue] Failed to load pending jobs from database:', error);
+            });
+        }
+    }
+    /**
+     * Load pending jobs from database (for recovery after restart)
+     */
+    async loadPendingJobs() {
+        if (!this.prisma)
+            return;
+        try {
+            const pendingJobs = await this.prisma.reasoningJob.findMany({
+                where: {
+                    status: { in: ['pending', 'processing'] }
+                }
+            });
+            if (pendingJobs.length > 0) {
+                console.log(`[XRay Queue] Found ${pendingJobs.length} pending jobs in database, re-enqueuing...`);
+                for (const dbJob of pendingJobs) {
+                    const job = {
+                        id: dbJob.id,
+                        executionId: dbJob.executionId,
+                        stepName: dbJob.stepName,
+                        attempt: dbJob.attempts,
+                        status: 'pending',
+                        createdAt: dbJob.createdAt.toISOString()
+                    };
+                    this.jobs.set(job.id, job);
+                    this.queue.add(() => this.processJob(job.id));
+                }
+                console.log(`[XRay Queue] Re-enqueued ${pendingJobs.length} jobs from database`);
+            }
+        }
+        catch (error) {
+            console.error('[XRay Queue] Failed to load pending jobs from database:', error);
+        }
+    }
+    /**
+     * Enqueue a single step for reasoning generation
+     */
+    async enqueue(executionId, stepName) {
+        const jobId = (0, crypto_1.randomUUID)();
+        const job = {
+            id: jobId,
+            executionId,
+            stepName,
+            attempt: 1,
+            status: 'pending',
+            createdAt: new Date().toISOString()
+        };
+        this.jobs.set(jobId, job);
+        // Persist job to database if Prisma client is available
+        if (this.prisma) {
+            try {
+                const execution = await this.prisma.execution.findUnique({
+                    where: { executionId },
+                    select: { id: true }
+                });
+                if (execution) {
+                    await this.prisma.reasoningJob.create({
+                        data: {
+                            id: jobId,
+                            executionId: execution.id,
+                            stepName,
+                            status: 'pending',
+                            attempts: 1
+                        }
+                    });
+                }
+            }
+            catch (error) {
+                console.error(`[XRay Queue] Failed to persist job to database:`, error);
+            }
+        }
+        // Add to queue
+        this.queue.add(() => this.processJob(jobId));
+        if (this.config.debug) {
+            console.log(`[XRay Queue] Job enqueued: ${executionId}/${stepName}`);
+        }
+        return jobId;
+    }
+    /**
+     * Enqueue all steps from an execution that don't have reasoning
+     */
+    async enqueueExecution(executionId) {
+        const execution = await this.storage.getExecutionById(executionId);
+        if (!execution) {
+            throw new Error(`Execution ${executionId} not found`);
+        }
+        const jobIds = [];
+        for (const step of execution.steps) {
+            if (!step.reasoning) {
+                const jobId = await this.enqueue(executionId, step.name);
+                jobIds.push(jobId);
+            }
+        }
+        return jobIds;
+    }
+    /**
+     * Process a single job with retry logic
+     */
+    async processJob(jobId) {
+        const job = this.jobs.get(jobId);
+        if (!job) {
+            console.error(`[XRay Queue] Job ${jobId} not found`);
+            return;
+        }
+        job.status = 'processing';
+        job.startedAt = new Date().toISOString();
+        // Update job status in database
+        if (this.prisma) {
+            try {
+                await this.prisma.reasoningJob.update({
+                    where: { id: jobId },
+                    data: { status: 'processing' }
+                });
+            }
+            catch (error) {
+                console.error(`[XRay Queue] Failed to update job status in database:`, error);
+            }
+        }
+        if (this.config.debug) {
+            console.log(`[XRay Queue] Processing job ${jobId} (attempt ${job.attempt}/${this.config.maxRetries})`);
+        }
+        try {
+            // Load execution
+            const execution = await this.storage.getExecutionById(job.executionId);
+            if (!execution) {
+                throw new Error(`Execution ${job.executionId} not found`);
+            }
+            // Find the step
+            const step = execution.steps.find(s => s.name === job.stepName);
+            if (!step) {
+                throw new Error(`Step ${job.stepName} not found in execution ${job.executionId}`);
+            }
+            // Skip if reasoning already exists
+            if (step.reasoning) {
+                console.log(`[XRay Queue] Reasoning already exists for ${job.stepName}, skipping`);
+                job.status = 'completed';
+                job.completedAt = new Date().toISOString();
+                return;
+            }
+            // Generate reasoning
+            const reasoning = await this.generator(step);
+            // Update storage
+            await this.storage.updateStepReasoning(job.executionId, job.stepName, reasoning);
+            // Mark job as completed
+            job.status = 'completed';
+            job.completedAt = new Date().toISOString();
+            // Update job in database
+            if (this.prisma) {
+                try {
+                    await this.prisma.reasoningJob.update({
+                        where: { id: jobId },
+                        data: {
+                            status: 'completed',
+                            reasoning,
+                            completedAt: new Date()
+                        }
+                    });
+                }
+                catch (error) {
+                    console.error(`[XRay Queue] Failed to update completed job in database:`, error);
+                }
+            }
+            if (this.config.debug) {
+                console.log(`[XRay Queue] ✅ Generated reasoning for ${job.executionId}/${job.stepName}`);
+            }
+        }
+        catch (error) {
+            console.error(`[XRay Queue] ❌ Error processing job ${jobId}:`, error.message);
+            await this.handleJobError(job, error);
+        }
+    }
+    /**
+     * Handle job error with retry logic
+     */
+    async handleJobError(job, error) {
+        const errorMessage = error.message || String(error);
+        job.error = errorMessage;
+        const isRetryable = this.isRetryableError(error);
+        if (isRetryable && job.attempt < this.config.maxRetries) {
+            // Schedule retry with exponential backoff
+            const delay = this.config.retryDelays[job.attempt - 1] || 8000;
+            job.attempt++;
+            job.status = 'pending';
+            job.nextRetryAt = new Date(Date.now() + delay).toISOString();
+            console.warn(`[XRay Queue] Retry ${job.attempt}/${this.config.maxRetries} for ${job.stepName} in ${delay}ms`);
+            setTimeout(() => {
+                this.queue.add(() => this.processJob(job.id));
+            }, delay);
+        }
+        else {
+            // Max retries reached
+            job.status = 'failed';
+            job.completedAt = new Date().toISOString();
+            if (this.prisma) {
+                try {
+                    await this.prisma.reasoningJob.update({
+                        where: { id: job.id },
+                        data: {
+                            status: 'failed',
+                            error: errorMessage,
+                            attempts: job.attempt,
+                            completedAt: new Date()
+                        }
+                    });
+                }
+                catch (dbError) {
+                    console.error(`[XRay Queue] Failed to update failed job in database:`, dbError);
+                }
+            }
+            console.error(`[XRay Queue] ✗ Failed to generate reasoning for ${job.executionId}/${job.stepName} after ${job.attempt} attempts`);
+        }
+    }
+    /**
+     * Check if error is retryable
+     */
+    isRetryableError(error) {
+        const errorMessage = error.message || String(error);
+        const errorCode = error.code;
+        const retryablePatterns = [
+            'ECONNRESET',
+            'ETIMEDOUT',
+            'ENOTFOUND',
+            'rate_limit_exceeded',
+            'service_unavailable',
+            'timeout',
+            '429',
+            '503',
+            '502',
+        ];
+        return retryablePatterns.some(pattern => errorMessage.includes(pattern) || errorCode === pattern);
+    }
+    /**
+     * Process all steps in an execution
+     */
+    async processExecution(executionId) {
+        const jobIds = await this.enqueueExecution(executionId);
+        if (jobIds.length === 0) {
+            if (this.config.debug) {
+                console.log(`[XRay Queue] No pending reasoning for execution ${executionId}`);
+            }
+            return;
+        }
+        console.log(`[XRay Queue] Processing ${jobIds.length} steps for execution ${executionId}`);
+        await this.queue.onIdle();
+        console.log(`[XRay Queue] ✓ Completed processing for execution ${executionId}`);
+    }
+    /**
+     * Get queue statistics
+     */
+    getStats() {
+        const jobs = Array.from(this.jobs.values());
+        return {
+            pending: jobs.filter(j => j.status === 'pending').length,
+            processing: jobs.filter(j => j.status === 'processing').length,
+            completed: jobs.filter(j => j.status === 'completed').length,
+            failed: jobs.filter(j => j.status === 'failed').length,
+            totalJobs: jobs.length
+        };
+    }
+    /**
+     * Get job by ID
+     */
+    getJob(jobId) {
+        return this.jobs.get(jobId);
+    }
+    /**
+     * Clear all jobs
+     */
+    clear() {
+        this.jobs.clear();
+    }
+    /**
+     * Get underlying p-queue
+     */
+    get pqueue() {
+        return this.queue;
+    }
+}
+exports.ReasoningQueue = ReasoningQueue;

package/dist/storage/DatabaseStorage.d.ts

@@ -0,0 +1,21 @@
+import { Execution, StorageProvider } from "../types";
+export declare class DatabaseStorage implements StorageProvider {
+    private prisma;
+    constructor(prismaClient: any);
+    /**
+     * Save a complete execution to the database
+     */
+    saveExecution(execution: Execution): Promise<void>;
+    /**
+     * Get a single execution by ID
+     */
+    getExecutionById(id: string): Promise<Execution | undefined>;
+    /**
+     * Get all executions
+     */
+    getAllExecutions(): Promise<Execution[]>;
+    /**
+     * Update a single step's reasoning
+     */
+    updateStepReasoning(executionId: string, stepName: string, reasoning: string): Promise<void>;
+}

package/dist/storage/DatabaseStorage.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatabaseStorage = void 0;
+class DatabaseStorage {
+    constructor(prismaClient) {
+        this.prisma = prismaClient;
+    }
+    /**
+     * Save a complete execution to the database
+     */
+    async saveExecution(execution) {
+        if (!execution || !execution.executionId || execution.steps.length === 0) {
+            console.warn("Skipping invalid execution:", execution?.executionId);
+            return;
+        }
+        try {
+            const existing = await this.prisma.execution.findUnique({
+                where: { executionId: execution.executionId },
+            });
+            if (existing) {
+                await this.prisma.execution.update({
+                    where: { executionId: execution.executionId },
+                    data: {
+                        metadata: execution.metadata || {},
+                        finalOutcome: execution.finalOutcome || {},
+                        completedAt: new Date(),
+                        steps: {
+                            deleteMany: {},
+                            create: execution.steps.map(step => ({
+                                name: step.name,
+                                input: step.input || {},
+                                output: step.output || {},
+                                error: step.error,
+                                durationMs: step.durationMs,
+                                reasoning: step.reasoning,
+                            })),
+                        },
+                    },
+                });
+                console.log(`[XRay Storage] ✅ Updated execution ${execution.executionId}`);
+            }
+            else {
+                await this.prisma.execution.create({
+                    data: {
+                        executionId: execution.executionId,
+                        projectId: execution.metadata?.projectId || "default",
+                        metadata: execution.metadata || {},
+                        finalOutcome: execution.finalOutcome || {},
+                        steps: {
+                            create: execution.steps.map(step => ({
+                                name: step.name,
+                                input: step.input || {},
+                                output: step.output || {},
+                                error: step.error,
+                                durationMs: step.durationMs,
+                                reasoning: step.reasoning,
+                            })),
+                        },
+                    },
+                });
+                console.log(`[XRay Storage] ✅ Created execution ${execution.executionId}`);
+            }
+        }
+        catch (error) {
+            console.error(`[XRay Storage] ❌ Failed to save execution ${execution.executionId}:`, error);
+            throw error;
+        }
+    }
+    /**
+     * Get a single execution by ID
+     */
+    async getExecutionById(id) {
+        try {
+            const exec = await this.prisma.execution.findUnique({
+                where: { executionId: id },
+                include: {
+                    steps: {
+                        orderBy: {
+                            createdAt: 'asc',
+                        },
+                    },
+                },
+            });
+            if (!exec) {
+                return undefined;
+            }
+            return {
+                executionId: exec.executionId,
+                startedAt: exec.startedAt.toISOString(),
+                endedAt: exec.completedAt?.toISOString(),
+                metadata: exec.metadata,
+                finalOutcome: exec.finalOutcome,
+                steps: exec.steps.map((step) => ({
+                    name: step.name,
+                    input: step.input,
+                    output: step.output,
+                    error: step.error || undefined,
+                    durationMs: step.durationMs || undefined,
+                    reasoning: step.reasoning || undefined,
+                    timestamp: step.createdAt.toISOString(),
+                })),
+            };
+        }
+        catch (error) {
+            console.error(`[XRay Storage] ❌ Failed to get execution ${id}:`, error);
+            return undefined;
+        }
+    }
+    /**
+     * Get all executions
+     */
+    async getAllExecutions() {
+        try {
+            const executions = await this.prisma.execution.findMany({
+                include: {
+                    steps: {
+                        orderBy: {
+                            createdAt: 'asc',
+                        },
+                    },
+                },
+                orderBy: {
+                    startedAt: 'desc',
+                },
+                take: 100,
+            });
+            return executions.map((exec) => ({
+                executionId: exec.executionId,
+                startedAt: exec.startedAt.toISOString(),
+                endedAt: exec.completedAt?.toISOString(),
+                metadata: exec.metadata,
+                finalOutcome: exec.finalOutcome,
+                steps: exec.steps.map((step) => ({
+                    name: step.name,
+                    input: step.input,
+                    output: step.output,
+                    error: step.error || undefined,
+                    durationMs: step.durationMs || undefined,
+                    reasoning: step.reasoning || undefined,
+                    timestamp: step.createdAt.toISOString(),
+                })),
+            }));
+        }
+        catch (error) {
+            console.error("[XRay Storage] ❌ Failed to load executions:", error);
+            return [];
+        }
+    }
+    /**
+     * Update a single step's reasoning
+     */
+    async updateStepReasoning(executionId, stepName, reasoning) {
+        try {
+            const execution = await this.prisma.execution.findUnique({
+                where: { executionId },
+                include: { steps: true },
+            });
+            if (!execution) {
+                throw new Error(`Execution ${executionId} not found`);
+            }
+            const step = execution.steps.find((s) => s.name === stepName);
+            if (!step) {
+                throw new Error(`Step ${stepName} not found in execution ${executionId}`);
+            }
+            await this.prisma.step.update({
+                where: { id: step.id },
+                data: { reasoning },
+            });
+            console.log(`[XRay Storage] ✅ Updated reasoning for ${executionId}/${stepName}`);
+        }
+        catch (error) {
+            console.error(`[XRay Storage] ❌ Failed to update reasoning for ${executionId}/${stepName}:`, error);
+            throw error;
+        }
+    }
+}
+exports.DatabaseStorage = DatabaseStorage;

package/dist/storage/MemoryStorage.d.ts

@@ -0,0 +1,9 @@
+import { Execution, StorageProvider } from "../types";
+export declare class MemoryStorage implements StorageProvider {
+    private executions;
+    saveExecution(execution: Execution): Promise<void>;
+    getExecutionById(executionId: string): Promise<Execution | undefined>;
+    getAllExecutions(): Promise<Execution[]>;
+    updateStepReasoning(executionId: string, stepName: string, reasoning: string): Promise<void>;
+    clear(): void;
+}