{"_id":"@atmalviya/xray","name":"@atmalviya/xray","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@atmalviya/xray","version":"0.1.0","description":"X-Ray SDK and API for debugging multi-step, non-deterministic algorithmic systems","main":"./sdk/dist/index.js","types":"./sdk/dist/index.d.ts","exports":{".":{"import":"./sdk/dist/index.js","require":"./sdk/dist/index.js","types":"./sdk/dist/index.d.ts"}},"bin":{"xray":"cli/dist/index.js"},"scripts":{"build":"npm run build:sdk && npm run build:api && npm run build:cli","build:sdk":"cd sdk && npm run build","build:api":"cd api && npm run build","build:cli":"cd cli && npm run build","dev:api":"cd api && npm run dev","dev:cli":"cd cli && npm run dev","postinstall":"npm run build","prepublishOnly":"npm run build"},"keywords":["xray","debugging","pipeline","tracing","decision-tracking","observability"],"author":"","license":"MIT","repository":{"type":"git","url":"git+https://github.com/atmalviya/equalcollective-assignment.git"},"bugs":{"url":"https://github.com/atmalviya/equalcollective-assignment/issues"},"homepage":"https://github.com/atmalviya/equalcollective-assignment#readme","devDependencies":{"@types/node":"^20.10.0","typescript":"^5.3.3"},"engines":{"node":">=18.0.0"},"_id":"@atmalviya/xray@0.1.0","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-pcRzupZgI0pb6am8jR9TZyDgjDV1iLZzwTdNR6LxLW4Le1zCHyKex3lNVYWIiqEKzSEumbP3uQ6w+GN6/lv/8w==","shasum":"3282617c78c8e1aaad84a2f5d7d3d2df4a617c21","tarball":"https://registry.npmjs.org/@atmalviya/xray/-/xray-0.1.0.tgz","fileCount":26,"unpackedSize":69418,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDzUGGDpgOtPUyq0oyprbpNDWPobObozv6fwlA6ziOQuwIgKxpdLMD112yfxVdc0HXGe9T4NlMfHZ4rm51DZPlaDcQ="}]},"_npmUser":{"name":"atmalviya","email":"dev.atmalviya@gmail.com"},"directories":{},"maintainers":[{"name":"atmalviya","email":"dev.atmalviya@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/xray_0.1.0_1767560738600_0.7940357283461945"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-04T21:05:38.508Z","0.1.0":"2026-01-04T21:05:38.755Z","modified":"2026-01-04T21:05:38.983Z"},"maintainers":[{"name":"atmalviya","email":"dev.atmalviya@gmail.com"}],"description":"X-Ray SDK and API for debugging multi-step, non-deterministic algorithmic systems","homepage":"https://github.com/atmalviya/equalcollective-assignment#readme","keywords":["xray","debugging","pipeline","tracing","decision-tracking","observability"],"repository":{"type":"git","url":"git+https://github.com/atmalviya/equalcollective-assignment.git"},"bugs":{"url":"https://github.com/atmalviya/equalcollective-assignment/issues"},"license":"MIT","readme":"# X-Ray SDK & API\n\nA general-purpose SDK and API for debugging multi-step, non-deterministic algorithmic systems. X-Ray answers \"why did the system make this decision?\" rather than just \"what happened?\"\n\n## Overview\n\nX-Ray provides transparency into decision-making processes across multi-step pipelines. It captures:\n- **Inputs** and **outputs** at each step\n- **Candidates** considered and **filters** applied\n- **Reasoning** behind decisions (especially for LLM-based steps)\n- **Metrics** and **timing** for performance analysis\n\nUnlike traditional tracing (Jaeger, Zipkin), X-Ray focuses on **business logic decisions** rather than function calls.\n\n## Project Structure\n\n```\n.\n├── sdk/              # TypeScript SDK\n│   ├── src/\n│   └── package.json\n├── api/              # Backend API server\n│   ├── src/\n│   ├── prisma/\n│   └── package.json\n├── examples/         # Example usage\n├── ARCHITECTURE.md   # System design and rationale\n└── README.md         # This file\n```\n\n## Installation\n\n```bash\nnpm install @atmalviya/xray\n```\n\nThis installs both the SDK and CLI tools.\n\n## Quick Start\n\n> **📖 For detailed testing instructions, see [TESTING.md](./TESTING.md)**\n\n### 1. Initialize X-Ray\n\n```bash\n# Initialize X-Ray in your project\nnpx xray init\n\n# This will:\n# - Create .env file with DATABASE_URL and XRAY_PORT\n# - Set up configuration\n```\n\n### 2. Set Up Database\n\n```bash\n# Run database migrations\nnpx xray migrate\n```\n\n### 3. Start the API Server\n\n```bash\n# Start the X-Ray API server\nnpx xray start\n\n# Or specify a port\nnpx xray start --port 3000\n```\n\nThe API will run on `http://localhost:3000` (or your specified port)\n\n### 4. Use the SDK in Your Code\n\n### 3. Use the SDK in Your Code\n\n```typescript\nimport { XRayClient } from '@atmalviya/xray';\n\nconst xray = new XRayClient({\n  baseUrl: 'http://localhost:3000',\n  defaultMetadata: {\n    service: 'my-service',\n    env: 'production'\n  }\n});\n\n// Wrap your pipeline\nasync function myPipeline(input) {\n  const run = xray.startRun({\n    pipelineName: 'my_pipeline',\n    metadata: { inputId: input.id }\n  });\n\n  return run.execute(async () => {\n    const step1Result = await run.step('step1', 'llm', async (ctx) => {\n      const result = await callLLM(ctx.input);\n      ctx.record({\n        output: result,\n        reasoning: result.explanation\n      });\n      return result;\n    }, { input: { prompt: input.prompt } });\n\n    const step2Result = await run.step('step2', 'filter', async (ctx) => {\n      const filtered = filterResults(ctx.input.candidates);\n      ctx.record({\n        metrics: {\n          candidateCountBefore: ctx.input.candidates.length,\n          candidateCountAfter: filtered.length,\n          dropRate: 1 - filtered.length / ctx.input.candidates.length\n        }\n      });\n      return filtered;\n    }, { input: { candidates: step1Result } });\n\n    return step2Result;\n  });\n}\n```\n\n## Examples\n\n### Simple Examples\n\n- **`examples/test.ts`** - Basic test script\n- **`examples/minimal-example.ts`** - Minimal instrumentation (<5 minutes)\n\n### Complex Examples\n\n- **`examples/competitor-selection.ts`** - Competitor selection pipeline with 5 steps\n- **`examples/complex-pipeline.ts`** - **E-commerce recommendation system** with:\n  - 10,000+ product catalog\n  - 6 different step types (LLM, retrieval, filter, ranking, selection)\n  - Complex multi-stage filtering\n  - LLM-based relevance ranking\n  - Diversity-aware selection\n  - Detailed metrics and reasoning at each step\n\nRun the complex example:\n```bash\ncd examples\nnpm run complex\n# or\nts-node --transpile-only complex-pipeline.ts\n```\n\n## API Endpoints\n\n### Ingest\n\n- **POST /xray/events** - Accepts batched events from SDK\n  - Headers: `Authorization: Bearer <api-key>`\n  - Body: `{ events: XRayEvent[] }`\n\n### Query\n\n- **GET /xray/runs** - List runs\n  - Query params: `pipelineName`, `status`, `startDate`, `endDate`, `limit`, `offset`\n  \n- **GET /xray/runs/:runId** - Get a specific run with all steps\n\n- **GET /xray/runs/:runId/steps/:stepId** - Get full details for a step\n\n- **POST /xray/query/steps** - Advanced cross-pipeline queries\n  ```json\n  {\n    \"filters\": [\n      { \"field\": \"stepType\", \"op\": \"eq\", \"value\": \"filter\" },\n      { \"field\": \"metrics.dropRate\", \"op\": \"gt\", \"value\": 0.9 }\n    ],\n    \"include\": [\"run\", \"step\"],\n    \"limit\": 100\n  }\n  ```\n\n## Approach\n\n### Design Principles\n\n1. **Pipeline-agnostic**: Works with any multi-step process, not tied to specific domains\n2. **Fail-safe**: SDK never breaks your pipeline, even if backend is unavailable\n3. **Queryable**: Cross-pipeline queries enabled by conventions (stepType, metrics)\n4. **Performance-conscious**: Sampling and summarization to handle large candidate sets\n\n### Key Features\n\n- **Event batching**: SDK batches events and sends them asynchronously\n- **Sampling**: Configurable per-step sampling for large datasets\n- **Fail-open**: Pipeline continues normally if X-Ray backend is down\n- **JSONB storage**: Flexible metadata and metrics storage in PostgreSQL\n\n## Known Limitations\n\n1. **JSONB query limitations**: Complex nested queries on metrics require careful indexing\n2. **No UI**: API-only, no visual dashboard (see \"What Next\" in ARCHITECTURE.md)\n3. **Single language**: SDK is TypeScript/JavaScript only (Python/Java/Go planned)\n4. **No streaming**: Events are batched, not streamed in real-time\n5. **No authentication**: Authentication disabled for local development (should be added for production)\n\n## Future Improvements\n\nSee ARCHITECTURE.md \"What Next?\" section for planned enhancements:\n- Multi-language SDKs\n- Visual dashboard\n- Advanced querying and anomaly detection\n- OpenTelemetry integration\n- Performance optimizations (read replicas, materialized views)\n\n## Development\n\n### SDK Development\n\n```bash\ncd sdk\nnpm run build      # Compile TypeScript\nnpm run dev        # Watch mode\n```\n\n### API Development\n\n```bash\ncd api\nnpm run dev        # Start with hot reload\nnpm run db:studio # Open Prisma Studio for database inspection\n```\n\n## License\n\nMIT\n\n","readmeFilename":"README.md","_rev":"1-d18f757444467ccf87d25143ef0d77e4"}