xray-sdk 0.1.0 → 0.1.1

package/README.md

@@ -1,426 +1,573 @@
-# X-Ray SDK
+# xray-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.
+Track your pipeline executions with automatic AI reasoning that explains "WHY" decisions were made. Debug faster with step-by-step insights and visual exploration.
 
-## 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
+## 📦 Installation
 
 ```bash
-npm install xray-sdk p-queue
+npm install xray-sdk
 ```
 
-### Optional Dependencies
+---
 
-```bash
-# For database storage
-npm install @prisma/client
+## 🚀 Complete Setup Guide
 
-# For OpenAI reasoning
-npm install openai
-```
+Follow these steps to integrate X-Ray into your pipeline:
 
-## Quick Start
+### Step 1: Get Your API Key
 
-### Basic Usage (In-Memory)
+1. Visit the X-Ray Dashboard: **https://x-ray-library-sdk-git-main-devdurgesh619s-projects.vercel.app**
+2. Click **"Create Account"** to sign up
+3. Go to **"API Keys"** page: https://x-ray-library-sdk-git-main-devdurgesh619s-projects.vercel.app/api-key
+4. Click **"Generate New Key"** and copy your API key (format: `xray_xxxxx...`)
 
-```typescript
-import { XRay, MemoryStorage } from 'xray-sdk'
+### Step 2: Configure Environment Variables
 
-const storage = new MemoryStorage()
-const xray = new XRay('my-execution-1', { projectId: 'demo' }, storage)
+Create a `.env` file in your project root:
 
-// Track a step
-xray.startStep('fetch_data', { query: 'shoes' })
-const data = await fetchData('shoes')
-xray.endStep('fetch_data', { results: data.length })
+```bash
+# X-Ray Dashboard Configuration
+XRAY_API_URL="https://x-ray-library-sdk-git-main-devdurgesh619s-projects.vercel.app"
 
-// End execution
-const execution = xray.end({ success: true })
-await xray.save()
+# Your API key from Step 1
+XRAY_API_KEY="xray_your_api_key_here"
 
-console.log('Execution saved:', execution.executionId)
+# Optional: Only needed for client-side reasoning (advanced)
+OPENAI_API_KEY="sk-..."
 ```
 
-### With Database Storage (Prisma)
+### Step 3: Create HTTP Client Wrapper
+
+Create a file `src/lib/xrayClient.ts` to handle API communication:
 
 ```typescript
-import { XRay, DatabaseStorage } from '@xray/sdk'
-import { PrismaClient } from '@prisma/client'
+interface Execution {
+  executionId: string
+  startedAt: string
+  endedAt?: string
+  steps: Array<{
+    name: string
+    input?: any
+    output?: any
+    error?: string
+    durationMs?: number
+  }>
+  finalOutcome?: any
+  metadata?: Record<string, any>
+}
 
-const prisma = new PrismaClient()
-const storage = new DatabaseStorage(prisma)
+export class XRayClient {
+  private apiUrl: string
+  private apiKey: string
 
-const xray = new XRay('my-execution-2', { projectId: 'demo' }, storage)
+  constructor(apiUrl: string, apiKey: string) {
+    this.apiUrl = apiUrl
+    this.apiKey = apiKey
+  }
 
-// Track steps
-xray.startStep('step1', { input: 'data' })
-xray.endStep('step1', { output: 'result' })
+  async saveExecution(execution: Execution): Promise<{ executionId: string }> {
+    const response = await fetch(\`\${this.apiUrl}/api/logs\`, {
+      method: 'POST',
+      headers: {
+        'x-api-key': this.apiKey,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(execution)
+    })
 
-// Save to database
-const execution = xray.end({ success: true })
-await xray.save()
-```
+    if (!response.ok) {
+      throw new Error(\`X-Ray API Error: \${response.statusText}\`)
+    }
 
-### With AI Reasoning (OpenAI)
+    return await response.json()
+  }
+}
 
-```typescript
-import {
-  XRay,
-  DatabaseStorage,
-  ReasoningQueue,
-  createOpenAIGenerator
-} from '@xray/sdk'
-import { PrismaClient } from '@prisma/client'
-import OpenAI from 'openai'
+// Helper function to create client from environment variables
+export function createXRayClient(): XRayClient {
+  const apiUrl = process.env.XRAY_API_URL
+  const apiKey = process.env.XRAY_API_KEY
 
-const prisma = new PrismaClient()
-const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
+  if (!apiUrl || !apiKey) {
+    throw new Error('Missing XRAY_API_URL or XRAY_API_KEY in environment')
+  }
 
-// Setup storage and reasoning
-const storage = new DatabaseStorage(prisma)
-const generator = createOpenAIGenerator(openai)
-const queue = new ReasoningQueue(
-  storage,
-  generator,
-  { concurrency: 3, debug: true },
-  prisma
-)
+  return new XRayClient(apiUrl, apiKey)
+}
+```
 
-// Run pipeline
-const xray = new XRay('my-execution-3', { projectId: 'demo' }, storage)
+**💡 Tip:** See the full implementation at \`demo-app/src/lib/xrayClient.ts\` in the repository.
 
-xray.startStep('search', { query: 'laptops' })
-const results = await search('laptops')
-xray.endStep('search', { count: results.length })
+### Step 4: Track Your Pipeline with XRay
 
-xray.startStep('filter', { threshold: 4.5 })
-const filtered = results.filter(r => r.rating >= 4.5)
-xray.endStep('filter', { remaining: filtered.length })
+Wrap your pipeline logic with X-Ray tracking:
 
-// Save execution (without reasoning)
-const execution = xray.end({ success: true })
-await xray.save()
+```typescript
+import { XRay } from 'xray-sdk'
+import { createXRayClient } from './lib/xrayClient'
+
+async function myPipeline() {
+  // 1. Create XRay instance with unique execution ID
+  const executionId = \`pipeline-\${Date.now()}\`
+  const xray = new XRay(executionId, {
+    pipeline: 'my-pipeline-name',
+    domain: 'data-processing'  // Optional metadata
+  })
+
+  // 2. Track each step with startStep() and endStep()
+
+  // Step 1: Fetch data
+  xray.startStep('fetch_data', { source: 'api.example.com', limit: 100 })
+  const data = await fetchData()
+  xray.endStep('fetch_data', { records: data.length, size_kb: 45 })
+
+  // Step 2: Process data
+  xray.startStep('process_data', { records: data.length })
+  const processed = processData(data)
+  xray.endStep('process_data', {
+    processed: processed.length,
+    skipped: data.length - processed.length
+  })
+
+  // Step 3: Save results
+  xray.startStep('save_results', { records: processed.length })
+  await saveResults(processed)
+  xray.endStep('save_results', { success: true })
+
+  // 3. Complete execution
+  const execution = xray.end({
+    status: 'success',
+    total_processed: processed.length
+  })
+
+  // 4. Send to X-Ray Dashboard
+  const client = createXRayClient()
+  await client.saveExecution(execution)
+
+  // 5. View in dashboard
+  console.log(\`✅ View execution: https://x-ray-library-sdk-git-main-devdurgesh619s-projects.vercel.app/execution/\${executionId}\`)
+}
+```
 
-// Enqueue reasoning generation (async)
-await xray.enqueueReasoning(queue)
+### Step 5: View Results in Dashboard
 
-console.log('✅ Execution saved, reasoning generating in background')
-```
+1. Run your pipeline: \`npm run your-pipeline-command\`
+2. Copy the execution URL from console output
+3. Open the URL in your browser
+4. Watch AI reasoning generate automatically for each step
 
-### On-Demand Reasoning (Recommended)
+**✨ AI Reasoning explains:**
+- WHY this step produced this output
+- What metrics/thresholds drove the decision
+- What might be wrong if numbers look suspicious
 
-Instead of auto-generating reasoning, trigger it only when viewing an execution:
+Example reasoning:
+> "Only 3/10 candidates met minRating≥4.0 AND minReviews≥100; 7 failed due to low ratings/reviews"
 
-```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
-```
+## 📚 Complete Examples
 
-This approach:
-- ✅ API responds instantly (~150ms)
-- ✅ Saves LLM costs (only generate for executions users actually view)
-- ✅ Better user experience
+See the \`demo-app/\` directory for production-ready examples:
 
-## API Reference
+### Example 1: Basic Data Pipeline
 
-### XRay
+**File:** \`demo-app/src/1-basic-example.ts\`
 
 ```typescript
-class XRay {
-  constructor(executionId: string, metadata?: Record<string, any>, storage?: StorageProvider)
+import { XRay } from 'xray-sdk'
+import { createXRayClient } from './lib/xrayClient'
 
-  // V1 API (backward compatible)
-  logStep(step: { name: string, input: any, output: any, metadata?: any }): void
+const xray = new XRay(\`basic-\${Date.now()}\`, {
+  pipeline: 'data-ingestion'
+})
 
-  // V2 API (recommended)
-  startStep(name: string, input: any, metadata?: any): void
-  endStep(name: string, output: any): void
-  errorStep(name: string, error: Error): void
+// Track data ingestion
+xray.startStep('ingest', { source: 'api', limit: 1000 })
+const rawData = await fetch('https://api.example.com/data')
+xray.endStep('ingest', { records: 1000, size_mb: 2.3 })
+
+// Track validation
+xray.startStep('validate', { records: 1000 })
+const valid = rawData.filter(isValid)
+xray.endStep('validate', {
+  valid: valid.length,
+  invalid: rawData.length - valid.length
+})
 
-  end(finalOutcome: any): Execution
-  save(): Promise<void>
-  enqueueReasoning(queue: ReasoningQueue): Promise<void>
-  getExecution(): Execution
-}
+const execution = xray.end({ status: 'success' })
+await createXRayClient().saveExecution(execution)
 ```
 
-### StorageProvider
+### Example 2: E-Commerce Competitor Selection
+
+**File:** \`demo-app/src/2-ecommerce-example.ts\`
 
 ```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>
-}
-```
+import { XRay } from 'xray-sdk'
+import { createXRayClient } from './lib/xrayClient'
 
-**Implementations:**
-- `MemoryStorage` - In-memory storage (testing)
-- `DatabaseStorage` - Prisma + PostgreSQL (production)
+const xray = new XRay(\`ecommerce-\${Date.now()}\`, {
+  pipeline: 'competitor-selection',
+  domain: 'e-commerce'
+})
 
-### ReasoningQueue
+// Step 1: Generate search keywords
+xray.startStep('generate_keywords', {
+  product_title: 'Water Bottle 32oz Insulated'
+})
+const keywords = ['water bottle', 'insulated bottle', '32oz bottle']
+xray.endStep('generate_keywords', { keywords, count: 3 })
+
+// Step 2: Search for candidates
+xray.startStep('search_competitors', { keywords, limit: 50 })
+const candidates = await searchAmazon(keywords)
+xray.endStep('search_competitors', {
+  total_results: 2847,
+  candidates_fetched: 10
+})
 
-```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
-}
+// Step 3: Filter and select best competitor
+xray.startStep('filter_and_select', {
+  candidates: 10,
+  filters: { minRating: 4.0, minReviews: 100 }
+})
+const filtered = candidates.filter(c => c.rating >= 4.0 && c.reviews >= 100)
+const selected = filtered[0]
+xray.endStep('filter_and_select', {
+  passed: 3,
+  failed: 7,
+  selected: selected.title
+})
+
+const execution = xray.end({
+  competitor: selected,
+  confidence: 0.95
+})
+await createXRayClient().saveExecution(execution)
 ```
 
-### Reasoning Generators
+### Example 3: Error Handling
+
+**File:** \`demo-app/src/3-error-handling-example.ts\`
 
 ```typescript
-// OpenAI-powered reasoning
-const generator = createOpenAIGenerator(openaiClient)
+import { XRay } from 'xray-sdk'
+import { createXRayClient } from './lib/xrayClient'
 
-// Simple reasoning (no LLM)
-const generator = createSimpleGenerator()
+const xray = new XRay(\`error-demo-\${Date.now()}\`, {
+  pipeline: 'risky-pipeline'
+})
 
-// Custom reasoning
-const generator: ReasoningGenerator = async (step: Step) => {
-  return `My custom reasoning for ${step.name}`
+xray.startStep('risky_operation', { input: 'data' })
+try {
+  const result = await riskyOperation()
+  xray.endStep('risky_operation', { result })
+} catch (error) {
+  // Track errors with errorStep()
+  xray.errorStep('risky_operation', error as Error)
 }
+
+const execution = xray.end({ status: 'failed' })
+await createXRayClient().saveExecution(execution)
+
+// Dashboard will show error with AI reasoning explaining what went wrong
 ```
 
-## Configuration
+### Example 4: Movie Recommendation Pipeline
 
-### Reasoning Config
+**File:** \`demo-app/src/4-movie-example.ts\`
 
 ```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)
-}
+import { XRay } from 'xray-sdk'
+import { createXRayClient } from './lib/xrayClient'
 
-const config = createReasoningConfig({
-  concurrency: 5,
-  maxRetries: 3,
-  debug: true
+const xray = new XRay(\`movie-\${Date.now()}\`, {
+  pipeline: 'movie-recommendation',
+  domain: 'entertainment'
 })
 
-const queue = new ReasoningQueue(storage, generator, config)
+// Step 1: Extract themes from favorite movie
+xray.startStep('extract_themes', { movie: 'Inception' })
+const themes = ['time manipulation', 'mind-bending', 'layered reality']
+xray.endStep('extract_themes', { themes, count: 3 })
+
+// Step 2: Search for similar movies
+xray.startStep('search_movies', { themes, limit: 20 })
+const candidates = await searchMovies(themes)
+xray.endStep('search_movies', { total: 47, fetched: 20 })
+
+// Step 3: Filter by criteria
+xray.startStep('filter_movies', {
+  candidates: 20,
+  minRating: 7.5,
+  maxAge: 15
+})
+const filtered = candidates.filter(m => m.rating >= 7.5 && m.yearsSinceRelease <= 15)
+xray.endStep('filter_movies', { passed: 5, failed: 15 })
+
+// Step 4: Score and rank
+xray.startStep('score_and_rank', { movies: 5 })
+const scored = scoreMovies(filtered)
+const topPick = scored[0]
+xray.endStep('score_and_rank', { top_score: topPick.score })
+
+// Step 5: Get metadata
+xray.startStep('get_metadata', { movie_id: topPick.id })
+const metadata = await getMovieMetadata(topPick.id)
+xray.endStep('get_metadata', { title: metadata.title })
+
+const execution = xray.end({
+  recommendation: metadata,
+  confidence: 0.92
+})
+await createXRayClient().saveExecution(execution)
 ```
 
-## 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())
-}
+## 🎯 Core API Reference
 
-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])
-}
-```
+### XRay Class
 
-Then run:
-```bash
-npx prisma migrate dev --name add_xray
-npx prisma generate
-```
+```typescript
+import { XRay } from 'xray-sdk'
 
-## Examples
+// Create instance
+const xray = new XRay(executionId: string, metadata?: Record<string, any>)
 
-### Example 1: Simple Pipeline
+// Track steps
+xray.startStep(name: string, input?: any)
+xray.endStep(name: string, output?: any)
+xray.errorStep(name: string, error: Error)
 
-```typescript
-import { XRay, MemoryStorage } from '@xray/sdk'
+// Complete execution
+const execution = xray.end(finalOutcome?: any)
+```
 
-async function runPipeline() {
-  const storage = new MemoryStorage()
-  const xray = new XRay('exec-1', {}, storage)
+### Key Methods
 
-  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 })
+| Method | Description | Example |
+|--------|-------------|---------|
+| \`startStep(name, input?)\` | Start tracking a step | \`xray.startStep('fetch_data', { source: 'api' })\` |
+| \`endStep(name, output?)\` | End step successfully | \`xray.endStep('fetch_data', { records: 1000 })\` |
+| \`errorStep(name, error)\` | Mark step as failed | \`xray.errorStep('fetch_data', new Error('timeout'))\` |
+| \`end(finalOutcome?)\` | Complete execution | \`xray.end({ status: 'success', total: 1000 })\` |
 
-  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()
+## 🔒 Security & Reasoning Options
 
-  return execution
-}
-```
+X-Ray offers **two secure ways** to generate AI reasoning:
 
-### Example 2: With Error Handling
+### Option 1: Server-Side Reasoning (Default, Recommended)
 
-```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)
-}
-```
+**How it works:**
+1. Send execution WITHOUT reasoning to dashboard
+2. Dashboard generates reasoning using its own OpenAI key
+3. Reasoning appears automatically when you view the execution
 
-### Example 3: Custom Storage
+**Pros:**
+- ✅ No OpenAI API key needed from you
+- ✅ Zero cost for you
+- ✅ Zero setup required
 
+**Code:**
 ```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
-}
+const execution = xray.end({ status: 'success' })
+await client.saveExecution(execution)
+// Dashboard will generate reasoning automatically
 ```
 
-## Best Practices
+### Option 2: Client-Side Reasoning (Advanced)
 
-### 1. Use On-Demand Reasoning
+**How it works:**
+1. Generate reasoning locally using YOUR OpenAI key
+2. Send execution WITH reasoning to dashboard
+3. Your API key never leaves your infrastructure
 
-Don't generate reasoning on every pipeline run - only when users view executions:
+**Pros:**
+- ✅ Full control over OpenAI usage
+- ✅ Works with sensitive data (never sent to dashboard)
+- ✅ No dependency on dashboard's rate limits
 
+**Code:**
 ```typescript
-// ❌ Bad: Auto-generate reasoning (slow, expensive)
-await xray.save()
-await xray.enqueueReasoning(queue) // Blocks API response
-return { executionId }
+import { XRay, MemoryStorage, ReasoningQueue, createOpenAIGenerator } from 'xray-sdk'
+import OpenAI from 'openai'
 
-// ✅ Good: Generate on-demand (fast, cost-effective)
-await xray.save()
-return { executionId } // Returns instantly
+// 1. Track execution
+const xray = new XRay(executionId, { pipeline: 'my-pipeline' })
+xray.startStep('process', { input: 'data' })
+xray.endStep('process', { output: 'result' })
+const execution = xray.end({ status: 'success' })
 
-// Later, when viewing execution:
+// 2. Generate reasoning CLIENT-SIDE
+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
+const storage = new MemoryStorage()
+await storage.saveExecution(execution)
+
+const generator = createOpenAIGenerator(openai)
+const queue = new ReasoningQueue(storage, generator)
 await queue.processExecution(executionId)
+
+// 3. Get execution with reasoning
+const executionWithReasoning = await storage.getExecutionById(executionId)
+
+// 4. Send to dashboard
+await client.saveExecution(executionWithReasoning)
 ```
 
-### 2. Use Database Storage in Production
+**See:** \`demo-app/src/7-standalone-reasoning.ts\` for complete example
+
+---
+
+## 🏗️ Advanced Features
+
+### Custom Storage
 
 ```typescript
-// ❌ Bad: In-memory (data lost on restart)
+import { MemoryStorage, DatabaseStorage } from 'xray-sdk'
+
+// In-memory (for testing)
 const storage = new MemoryStorage()
 
-// ✅ Good: Database-backed (persistent)
-const storage = new DatabaseStorage(prisma)
+// Database (requires Prisma setup)
+const storage = new DatabaseStorage(prisma, userId)
 ```
 
-### 3. Configure Concurrency
+### Reasoning Queue Configuration
 
 ```typescript
-// Balance API costs vs speed
+import { ReasoningQueue, createOpenAIGenerator } from 'xray-sdk'
+
 const queue = new ReasoningQueue(storage, generator, {
-  concurrency: 3, // 3 parallel LLM calls
-  maxRetries: 4,  // Retry failed jobs
-  debug: true     // Enable logging
+  concurrency: 3,      // Process 3 steps in parallel
+  maxRetries: 4,       // Retry failed reasoning jobs
+  debug: true          // Enable detailed logging
 })
+
+await queue.processExecution(executionId)
 ```
 
-### 4. Handle Errors Gracefully
+### TypeScript Types
 
 ```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
+import { Execution, Step, XRay } from 'xray-sdk'
+
+const execution: Execution = {
+  executionId: 'exec-123',
+  startedAt: '2024-01-01T00:00:00Z',
+  endedAt: '2024-01-01T00:01:00Z',
+  steps: [
+    {
+      name: 'step1',
+      input: { data: 'test' },
+      output: { result: 'success' },
+      durationMs: 150
+    }
+  ],
+  finalOutcome: { status: 'success' }
 }
 ```
 
-## TypeScript
+---
 
-Full TypeScript support with type definitions:
+## 📊 Dashboard Features
 
-```typescript
-import { Execution, Step, ReasoningJob, QueueStats } from '@xray/sdk'
+The X-Ray Dashboard provides:
+
+| Feature | Description |
+|---------|-------------|
+| **Execution List** | Browse all pipeline runs with status indicators |
+| **Step-by-Step View** | Detailed breakdown showing input/output for each step |
+| **AI Reasoning** | Automatic "WHY" explanations for decisions |
+| **Real-Time Updates** | Watch reasoning generate live (polls every 2 seconds) |
+| **JSON Viewer** | Inspect raw execution data |
+| **Search & Filter** | Find executions by ID, pipeline name, or metadata |
+
+**Dashboard URL:** https://x-ray-library-sdk-git-main-devdurgesh619s-projects.vercel.app
+
+---
+
+## 🎯 Use Cases
+
+- **E-Commerce**: Competitor selection, product matching, price optimization
+- **Content Recommendation**: Movie/music recommendations, personalization engines
+- **Data Pipelines**: ETL processes, data validation, transformation workflows
+- **LLM Workflows**: Multi-step AI reasoning, autonomous agent systems
+- **Debugging**: Understand why pipeline decisions were made, identify bottlenecks
+
+---
+
+## ✅ Integration Checklist
 
-const execution: Execution = xray.getExecution()
-const stats: QueueStats = queue.getStats()
+Use this checklist to verify your integration:
+
+- [ ] Install \`xray-sdk\` package (\`npm install xray-sdk\`)
+- [ ] Create account on dashboard
+- [ ] Get API key from https://x-ray-library-sdk-git-main-devdurgesh619s-projects.vercel.app/api-key
+- [ ] Set environment variables (\`XRAY_API_URL\`, \`XRAY_API_KEY\`)
+- [ ] Create HTTP client wrapper (\`src/lib/xrayClient.ts\`)
+- [ ] Add \`XRay\` tracking to your pipeline (startStep/endStep)
+- [ ] Test with a simple pipeline execution
+- [ ] Verify execution appears in dashboard
+- [ ] Verify AI reasoning generates automatically
+- [ ] (Optional) Set up client-side reasoning for sensitive workloads
+
+---
+
+## 🚀 Quick Start Summary
+
+```bash
+# 1. Install
+npm install xray-sdk
+
+# 2. Get API key
+# Visit: https://x-ray-library-sdk-git-main-devdurgesh619s-projects.vercel.app/api-key
+
+# 3. Configure .env
+XRAY_API_URL="https://x-ray-library-sdk-git-main-devdurgesh619s-projects.vercel.app"
+XRAY_API_KEY="xray_your_key_here"
+
+# 4. Copy HTTP client
+# See: demo-app/src/lib/xrayClient.ts
+
+# 5. Track your pipeline
+# See: demo-app/src/2-ecommerce-example.ts
+
+# 6. Run and view results
+npm run your-pipeline
+# Open execution URL in browser
 ```
 
-## License
+---
+
+## 📚 Additional Resources
+
+- **Demo App**: See \`demo-app/\` directory for 5 production-ready examples
+- **Main README**: See \`../README.md\` for project overview
+- **Security Guide**: See \`../SECURITY.md\` for best practices
+- **Architecture**: See \`../XRAY_ARCHITECTURE_OVERVIEW.md\` for system design
+
+---
+
+## 📝 License
+
+ISC
 
-MIT
+---
 
-## Contributing
+## 🆘 Support
 
-Contributions welcome! Please open an issue or PR.
+- **Dashboard**: https://x-ray-library-sdk-git-main-devdurgesh619s-projects.vercel.app
+- **Get API Key**: https://x-ray-library-sdk-git-main-devdurgesh619s-projects.vercel.app/api-key
+- **Examples**: See \`demo-app/\` directory in the repository
 
-## Support
+---
 
-- GitHub Issues: https://github.com/yourusername/xray-sdk/issues
-- Documentation: https://xray-sdk.dev
+Start tracking your pipelines today with X-Ray! 🚀

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xray-sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Lightweight execution tracing for LLM pipelines with automatic reasoning generation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",