xray-sdk 0.1.0

package/README.md

@@ -0,0 +1,426 @@
+# X-Ray SDK
+
+**AI-powered observability for multi-step pipelines**
+
+X-Ray is a lightweight SDK that automatically tracks pipeline executions and generates human-readable reasoning for each step using LLMs.
+
+## Features
+
+✨ **Automatic Step Tracking** - Track pipeline execution with simple `startStep()` / `endStep()` calls
+🤖 **AI-Powered Reasoning** - Generate natural language explanations for each step using OpenAI
+💾 **Flexible Storage** - In-memory or database-backed (Prisma + PostgreSQL)
+⚡ **Async Processing** - Non-blocking reasoning generation with retry logic
+🔄 **On-Demand Generation** - Only generate reasoning when you need it (cost savings)
+📊 **Job Queue** - Built-in queue for managing concurrent LLM calls
+
+## Installation
+
+```bash
+npm install xray-sdk p-queue
+```
+
+### Optional Dependencies
+
+```bash
+# For database storage
+npm install @prisma/client
+
+# For OpenAI reasoning
+npm install openai
+```
+
+## Quick Start
+
+### Basic Usage (In-Memory)
+
+```typescript
+import { XRay, MemoryStorage } from 'xray-sdk'
+
+const storage = new MemoryStorage()
+const xray = new XRay('my-execution-1', { projectId: 'demo' }, storage)
+
+// Track a step
+xray.startStep('fetch_data', { query: 'shoes' })
+const data = await fetchData('shoes')
+xray.endStep('fetch_data', { results: data.length })
+
+// End execution
+const execution = xray.end({ success: true })
+await xray.save()
+
+console.log('Execution saved:', execution.executionId)
+```
+
+### With Database Storage (Prisma)
+
+```typescript
+import { XRay, DatabaseStorage } from '@xray/sdk'
+import { PrismaClient } from '@prisma/client'
+
+const prisma = new PrismaClient()
+const storage = new DatabaseStorage(prisma)
+
+const xray = new XRay('my-execution-2', { projectId: 'demo' }, storage)
+
+// Track steps
+xray.startStep('step1', { input: 'data' })
+xray.endStep('step1', { output: 'result' })
+
+// Save to database
+const execution = xray.end({ success: true })
+await xray.save()
+```
+
+### With AI Reasoning (OpenAI)
+
+```typescript
+import {
+  XRay,
+  DatabaseStorage,
+  ReasoningQueue,
+  createOpenAIGenerator
+} from '@xray/sdk'
+import { PrismaClient } from '@prisma/client'
+import OpenAI from 'openai'
+
+const prisma = new PrismaClient()
+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
+
+// Setup storage and reasoning
+const storage = new DatabaseStorage(prisma)
+const generator = createOpenAIGenerator(openai)
+const queue = new ReasoningQueue(
+  storage,
+  generator,
+  { concurrency: 3, debug: true },
+  prisma
+)
+
+// Run pipeline
+const xray = new XRay('my-execution-3', { projectId: 'demo' }, storage)
+
+xray.startStep('search', { query: 'laptops' })
+const results = await search('laptops')
+xray.endStep('search', { count: results.length })
+
+xray.startStep('filter', { threshold: 4.5 })
+const filtered = results.filter(r => r.rating >= 4.5)
+xray.endStep('filter', { remaining: filtered.length })
+
+// Save execution (without reasoning)
+const execution = xray.end({ success: true })
+await xray.save()
+
+// Enqueue reasoning generation (async)
+await xray.enqueueReasoning(queue)
+
+console.log('✅ Execution saved, reasoning generating in background')
+```
+
+### On-Demand Reasoning (Recommended)
+
+Instead of auto-generating reasoning, trigger it only when viewing an execution:
+
+```typescript
+// Pipeline API - just save execution
+const execution = xray.end({ success: true })
+await xray.save()
+return { executionId: execution.executionId } // Returns instantly
+
+// Later, when user views execution detail page
+await queue.processExecution(executionId) // Generate reasoning now
+```
+
+This approach:
+- ✅ API responds instantly (~150ms)
+- ✅ Saves LLM costs (only generate for executions users actually view)
+- ✅ Better user experience
+
+## API Reference
+
+### XRay
+
+```typescript
+class XRay {
+  constructor(executionId: string, metadata?: Record<string, any>, storage?: StorageProvider)
+
+  // V1 API (backward compatible)
+  logStep(step: { name: string, input: any, output: any, metadata?: any }): void
+
+  // V2 API (recommended)
+  startStep(name: string, input: any, metadata?: any): void
+  endStep(name: string, output: any): void
+  errorStep(name: string, error: Error): void
+
+  end(finalOutcome: any): Execution
+  save(): Promise<void>
+  enqueueReasoning(queue: ReasoningQueue): Promise<void>
+  getExecution(): Execution
+}
+```
+
+### StorageProvider
+
+```typescript
+interface StorageProvider {
+  saveExecution(execution: Execution): Promise<void>
+  getExecutionById(executionId: string): Promise<Execution | undefined>
+  getAllExecutions(): Promise<Execution[]>
+  updateStepReasoning(executionId: string, stepName: string, reasoning: string): Promise<void>
+}
+```
+
+**Implementations:**
+- `MemoryStorage` - In-memory storage (testing)
+- `DatabaseStorage` - Prisma + PostgreSQL (production)
+
+### ReasoningQueue
+
+```typescript
+class ReasoningQueue {
+  constructor(
+    storage: StorageProvider,
+    generator: ReasoningGenerator,
+    config?: Partial<ReasoningConfig>,
+    prismaClient?: any
+  )
+
+  enqueue(executionId: string, stepName: string): Promise<string>
+  enqueueExecution(executionId: string): Promise<string[]>
+  processExecution(executionId: string): Promise<void>
+  getStats(): QueueStats
+  getJob(jobId: string): ReasoningJob | undefined
+}
+```
+
+### Reasoning Generators
+
+```typescript
+// OpenAI-powered reasoning
+const generator = createOpenAIGenerator(openaiClient)
+
+// Simple reasoning (no LLM)
+const generator = createSimpleGenerator()
+
+// Custom reasoning
+const generator: ReasoningGenerator = async (step: Step) => {
+  return `My custom reasoning for ${step.name}`
+}
+```
+
+## Configuration
+
+### Reasoning Config
+
+```typescript
+interface ReasoningConfig {
+  concurrency: number      // Parallel LLM calls (default: 3)
+  maxRetries: number       // Max retries per job (default: 4)
+  retryDelays: number[]    // Backoff delays in ms (default: [1000, 2000, 4000, 8000])
+  debug: boolean           // Enable logging (default: false)
+}
+
+const config = createReasoningConfig({
+  concurrency: 5,
+  maxRetries: 3,
+  debug: true
+})
+
+const queue = new ReasoningQueue(storage, generator, config)
+```
+
+## Prisma Schema
+
+If using `DatabaseStorage`, add this to your Prisma schema:
+
+```prisma
+model Execution {
+  id            String      @id @default(cuid())
+  executionId   String      @unique
+  projectId     String      @default("default")
+  metadata      Json?
+  finalOutcome  Json?
+  startedAt     DateTime    @default(now())
+  completedAt   DateTime?
+  steps         Step[]
+  reasoningJobs ReasoningJob[]
+}
+
+model Step {
+  id            String      @id @default(cuid())
+  executionId   String
+  execution     Execution   @relation(fields: [executionId], references: [id], onDelete: Cascade)
+  name          String
+  input         Json?
+  output        Json?
+  error         String?
+  durationMs    Int?
+  reasoning     String?
+  createdAt     DateTime    @default(now())
+}
+
+model ReasoningJob {
+  id            String      @id @default(cuid())
+  executionId   String
+  execution     Execution   @relation(fields: [executionId], references: [id], onDelete: Cascade)
+  stepName      String
+  status        String
+  reasoning     String?
+  error         String?
+  attempts      Int         @default(0)
+  createdAt     DateTime    @default(now())
+  completedAt   DateTime?
+
+  @@unique([executionId, stepName])
+}
+```
+
+Then run:
+```bash
+npx prisma migrate dev --name add_xray
+npx prisma generate
+```
+
+## Examples
+
+### Example 1: Simple Pipeline
+
+```typescript
+import { XRay, MemoryStorage } from '@xray/sdk'
+
+async function runPipeline() {
+  const storage = new MemoryStorage()
+  const xray = new XRay('exec-1', {}, storage)
+
+  xray.startStep('fetch', { url: 'https://api.example.com' })
+  const data = await fetch('https://api.example.com').then(r => r.json())
+  xray.endStep('fetch', { count: data.length })
+
+  xray.startStep('process', { data })
+  const processed = data.map(d => d.value * 2)
+  xray.endStep('process', { result: processed })
+
+  const execution = xray.end({ total: processed.length })
+  await xray.save()
+
+  return execution
+}
+```
+
+### Example 2: With Error Handling
+
+```typescript
+xray.startStep('risky_operation', { input: 'data' })
+try {
+  const result = await riskyOperation()
+  xray.endStep('risky_operation', { result })
+} catch (error) {
+  xray.errorStep('risky_operation', error as Error)
+}
+```
+
+### Example 3: Custom Storage
+
+```typescript
+import { StorageProvider, Execution } from '@xray/sdk'
+
+class S3Storage implements StorageProvider {
+  async saveExecution(execution: Execution): Promise<void> {
+    // Upload to S3
+    await s3.putObject({
+      Bucket: 'my-bucket',
+      Key: `executions/${execution.executionId}.json`,
+      Body: JSON.stringify(execution)
+    })
+  }
+
+  async getExecutionById(id: string): Promise<Execution | undefined> {
+    // Download from S3
+    const obj = await s3.getObject({
+      Bucket: 'my-bucket',
+      Key: `executions/${id}.json`
+    })
+    return JSON.parse(obj.Body.toString())
+  }
+
+  // ... implement other methods
+}
+```
+
+## Best Practices
+
+### 1. Use On-Demand Reasoning
+
+Don't generate reasoning on every pipeline run - only when users view executions:
+
+```typescript
+// ❌ Bad: Auto-generate reasoning (slow, expensive)
+await xray.save()
+await xray.enqueueReasoning(queue) // Blocks API response
+return { executionId }
+
+// ✅ Good: Generate on-demand (fast, cost-effective)
+await xray.save()
+return { executionId } // Returns instantly
+
+// Later, when viewing execution:
+await queue.processExecution(executionId)
+```
+
+### 2. Use Database Storage in Production
+
+```typescript
+// ❌ Bad: In-memory (data lost on restart)
+const storage = new MemoryStorage()
+
+// ✅ Good: Database-backed (persistent)
+const storage = new DatabaseStorage(prisma)
+```
+
+### 3. Configure Concurrency
+
+```typescript
+// Balance API costs vs speed
+const queue = new ReasoningQueue(storage, generator, {
+  concurrency: 3, // 3 parallel LLM calls
+  maxRetries: 4,  // Retry failed jobs
+  debug: true     // Enable logging
+})
+```
+
+### 4. Handle Errors Gracefully
+
+```typescript
+xray.startStep('step', { input })
+try {
+  const result = await operation()
+  xray.endStep('step', { result })
+} catch (error) {
+  xray.errorStep('step', error as Error)
+  // Continue pipeline or throw
+}
+```
+
+## TypeScript
+
+Full TypeScript support with type definitions:
+
+```typescript
+import { Execution, Step, ReasoningJob, QueueStats } from '@xray/sdk'
+
+const execution: Execution = xray.getExecution()
+const stats: QueueStats = queue.getStats()
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR.
+
+## Support
+
+- GitHub Issues: https://github.com/yourusername/xray-sdk/issues
+- Documentation: https://xray-sdk.dev

package/dist/XRay.d.ts

@@ -0,0 +1,30 @@
+import { Execution, StorageProvider } from "./types";
+import { ReasoningQueue } from "./reasoning/queue";
+export declare class XRay {
+    private execution;
+    private activeSteps;
+    private pendingReasoningSteps;
+    private storage?;
+    constructor(executionId: string, metadata?: Record<string, any>, storage?: StorageProvider);
+    /** ✅ BACKWARD-COMPATIBLE (v1) – no auto reasoning */
+    logStep(step: {
+        name: string;
+        input: any;
+        output: any;
+        metadata?: Record<string, any>;
+    }): void;
+    /** Start a step (v2) */
+    startStep(name: string, input: any, metadata?: Record<string, any>): void;
+    /** Finish a step (v3) – stores without reasoning (populated asynchronously) */
+    endStep(name: string, output: any): void;
+    /** Capture error inside a step (v2) – stores without reasoning (populated asynchronously) */
+    errorStep(name: string, error: Error): void;
+    /** End execution - returns execution without enqueueing reasoning */
+    end(finalOutcome: any): Execution;
+    /** Save execution to storage (if configured) */
+    save(): Promise<void>;
+    /** Enqueue reasoning jobs - call AFTER saveExecution() */
+    enqueueReasoning(queue: ReasoningQueue): Promise<void>;
+    /** Get the current execution */
+    getExecution(): Execution;
+}

package/dist/XRay.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XRay = void 0;
+class XRay {
+    constructor(executionId, metadata, storage) {
+        this.activeSteps = new Map();
+        this.pendingReasoningSteps = [];
+        this.execution = {
+            executionId,
+            startedAt: new Date().toISOString(),
+            steps: [],
+            metadata
+        };
+        this.storage = storage;
+    }
+    /** ✅ BACKWARD-COMPATIBLE (v1) – no auto reasoning */
+    logStep(step) {
+        this.execution.steps.push({
+            name: step.name,
+            input: step.input,
+            output: step.output,
+            timestamp: new Date().toISOString(),
+            metadata: step.metadata
+            // reasoning can be added manually via metadata.reasoning if needed
+        });
+    }
+    /** Start a step (v2) */
+    startStep(name, input, metadata) {
+        const step = {
+            name,
+            input,
+            timestamp: new Date().toISOString(),
+            startedAt: new Date().toISOString(),
+            metadata
+        };
+        this.activeSteps.set(name, step);
+    }
+    /** Finish a step (v3) – stores without reasoning (populated asynchronously) */
+    endStep(name, output) {
+        const step = this.activeSteps.get(name);
+        if (!step)
+            return;
+        step.output = output;
+        step.endedAt = new Date().toISOString();
+        step.durationMs =
+            new Date(step.endedAt).getTime() -
+                new Date(step.startedAt).getTime();
+        // Store without reasoning (will be populated asynchronously)
+        step.reasoning = undefined;
+        this.execution.steps.push(step);
+        this.activeSteps.delete(name);
+        // Track step for later processing
+        this.pendingReasoningSteps.push(step.name);
+    }
+    /** Capture error inside a step (v2) – stores without reasoning (populated asynchronously) */
+    errorStep(name, error) {
+        const step = this.activeSteps.get(name);
+        if (!step)
+            return;
+        step.error = error.message;
+        step.endedAt = new Date().toISOString();
+        step.durationMs =
+            new Date(step.endedAt).getTime() -
+                new Date(step.startedAt).getTime();
+        // Store without reasoning (will be populated asynchronously)
+        step.reasoning = undefined;
+        this.execution.steps.push(step);
+        this.activeSteps.delete(name);
+        // Track step for later processing
+        this.pendingReasoningSteps.push(step.name);
+    }
+    /** End execution - returns execution without enqueueing reasoning */
+    end(finalOutcome) {
+        this.execution.endedAt = new Date().toISOString();
+        this.execution.finalOutcome = finalOutcome;
+        return this.execution;
+    }
+    /** Save execution to storage (if configured) */
+    async save() {
+        if (this.storage) {
+            await this.storage.saveExecution(this.execution);
+        }
+    }
+    /** Enqueue reasoning jobs - call AFTER saveExecution() */
+    async enqueueReasoning(queue) {
+        for (const stepName of this.pendingReasoningSteps) {
+            await queue.enqueue(this.execution.executionId, stepName);
+        }
+    }
+    /** Get the current execution */
+    getExecution() {
+        return this.execution;
+    }
+}
+exports.XRay = XRay;

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { XRay } from './XRay';
+export { DatabaseStorage } from './storage/DatabaseStorage';
+export { MemoryStorage } from './storage/MemoryStorage';
+export { ReasoningQueue } from './reasoning/queue';
+export { createOpenAIGenerator, createSimpleGenerator } from './reasoning/generator';
+export { createReasoningConfig, DEFAULT_REASONING_CONFIG } from './reasoning/config';
+export type { Execution, Step, ReasoningJob, QueueStats, XRayConfig, ReasoningConfig, StorageProvider } from './types';
+export type { ReasoningGenerator } from './reasoning/generator';

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+// Main entry point for X-Ray SDK
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_REASONING_CONFIG = exports.createReasoningConfig = exports.createSimpleGenerator = exports.createOpenAIGenerator = exports.ReasoningQueue = exports.MemoryStorage = exports.DatabaseStorage = exports.XRay = void 0;
+// Core classes
+var XRay_1 = require("./XRay");
+Object.defineProperty(exports, "XRay", { enumerable: true, get: function () { return XRay_1.XRay; } });
+// Storage implementations
+var DatabaseStorage_1 = require("./storage/DatabaseStorage");
+Object.defineProperty(exports, "DatabaseStorage", { enumerable: true, get: function () { return DatabaseStorage_1.DatabaseStorage; } });
+var MemoryStorage_1 = require("./storage/MemoryStorage");
+Object.defineProperty(exports, "MemoryStorage", { enumerable: true, get: function () { return MemoryStorage_1.MemoryStorage; } });
+// Reasoning
+var queue_1 = require("./reasoning/queue");
+Object.defineProperty(exports, "ReasoningQueue", { enumerable: true, get: function () { return queue_1.ReasoningQueue; } });
+var generator_1 = require("./reasoning/generator");
+Object.defineProperty(exports, "createOpenAIGenerator", { enumerable: true, get: function () { return generator_1.createOpenAIGenerator; } });
+Object.defineProperty(exports, "createSimpleGenerator", { enumerable: true, get: function () { return generator_1.createSimpleGenerator; } });
+var config_1 = require("./reasoning/config");
+Object.defineProperty(exports, "createReasoningConfig", { enumerable: true, get: function () { return config_1.createReasoningConfig; } });
+Object.defineProperty(exports, "DEFAULT_REASONING_CONFIG", { enumerable: true, get: function () { return config_1.DEFAULT_REASONING_CONFIG; } });

package/dist/reasoning/config.d.ts

@@ -0,0 +1,8 @@
+export interface ReasoningConfig {
+    concurrency: number;
+    maxRetries: number;
+    retryDelays: number[];
+    debug: boolean;
+}
+export declare const DEFAULT_REASONING_CONFIG: ReasoningConfig;
+export declare function createReasoningConfig(overrides?: Partial<ReasoningConfig>): ReasoningConfig;

package/dist/reasoning/config.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_REASONING_CONFIG = void 0;
+exports.createReasoningConfig = createReasoningConfig;
+exports.DEFAULT_REASONING_CONFIG = {
+    concurrency: 3,
+    maxRetries: 4,
+    retryDelays: [1000, 2000, 4000, 8000], // 1s, 2s, 4s, 8s
+    debug: false
+};
+function createReasoningConfig(overrides) {
+    return {
+        ...exports.DEFAULT_REASONING_CONFIG,
+        ...overrides
+    };
+}

package/dist/reasoning/generator.d.ts

@@ -0,0 +1,12 @@
+import { Step } from "../types";
+export type ReasoningGenerator = (step: Step) => Promise<string>;
+/**
+ * Default reasoning generator using OpenAI
+ * Users can provide their own OpenAI client instance
+ */
+export declare function createOpenAIGenerator(openaiClient: any): ReasoningGenerator;
+/**
+ * Simple reasoning generator (no LLM)
+ * Returns numeric summaries based on step data
+ */
+export declare function createSimpleGenerator(): ReasoningGenerator;