decision-xray 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Mehul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,65 @@
+# decision-xray
+
+Lightweight SDK for capturing decision-making in multi-step pipelines.
+
+## Installation
+
+```bash
+npm install decision-xray
+```
+
+## Quick Example
+
+```typescript
+import { createExecution, recordStep, createEvaluation, createFilterResult } from 'decision-xray';
+
+// Create execution
+const execution = createExecution({ name: 'Product Recommendation' });
+
+// Record a step with evaluations
+const step = recordStep({
+  executionId: execution.id,
+  name: 'Price Filter',
+  stepType: 'filter',
+  input: { candidates: 100 },
+  output: { passed: 25 },
+  reasoning: 'Filtered products over $50',
+  evaluations: [
+    createEvaluation('prod-1', 'Product A', false, {
+      filters: [
+        createFilterResult('price', false, '$75 exceeds maximum $50', 75, 50)
+      ]
+    })
+  ]
+});
+
+// You handle persistence
+await saveExecution(execution);
+await saveStep(step);
+```
+
+## API
+
+### createExecution
+Creates a new execution with unique ID and timestamp.
+
+### recordStep
+Records a decision step with inputs, outputs, reasoning, and optional evaluations.
+
+### createEvaluation
+Creates an evaluation for a single candidate (passed/failed, why).
+
+### createFilterResult
+Creates a filter result with actual vs expected values.
+
+### completeExecution
+Marks an execution as completed or failed.
+
+## Design
+
+- **No I/O**: SDK only creates objects. You handle persistence.
+- **Zero dependencies**: Works anywhere.
+- **Functional API**: Simple functions, no classes.
+- **Domain-agnostic**: Works with any decision pipeline.
+
+See full docs in code comments.

package/dist/execution.d.ts

@@ -0,0 +1,11 @@
+import { Execution, CreateExecutionInput, CompleteExecutionInput } from './types';
+/**
+ * Create a new execution. Returns an execution object with status 'running'.
+ * You're responsible for persisting it.
+ */
+export declare const createExecution: (input: CreateExecutionInput) => Execution;
+/**
+ * Mark an execution as completed or failed.
+ * Returns a new execution object with updated status and completedAt timestamp.
+ */
+export declare const completeExecution: (execution: Execution, input: CompleteExecutionInput) => Execution;

package/dist/execution.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.completeExecution = exports.createExecution = void 0;
+const generateExecutionId = () => {
+    const timestamp = Date.now();
+    const random = Math.random().toString(36).substring(2, 9);
+    return `exec_${timestamp}_${random}`;
+};
+/**
+ * Create a new execution. Returns an execution object with status 'running'.
+ * You're responsible for persisting it.
+ */
+const createExecution = (input) => {
+    return {
+        id: generateExecutionId(),
+        name: input.name,
+        description: input.description,
+        status: 'running',
+        startedAt: new Date(),
+        metadata: input.metadata
+    };
+};
+exports.createExecution = createExecution;
+/**
+ * Mark an execution as completed or failed.
+ * Returns a new execution object with updated status and completedAt timestamp.
+ */
+const completeExecution = (execution, input) => {
+    return {
+        ...execution,
+        status: input.status,
+        completedAt: new Date(),
+        metadata: {
+            ...execution.metadata,
+            ...input.metadata
+        }
+    };
+};
+exports.completeExecution = completeExecution;
+//# sourceMappingURL=execution.js.map

package/dist/execution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.js","sourceRoot":"","sources":["../src/execution.ts"],"names":[],"mappings":";;;AAOA,MAAM,mBAAmB,GAAG,GAAgB,EAAE;IAC5C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1D,OAAO,QAAQ,SAAS,IAAI,MAAM,EAAE,CAAC;AACvC,CAAC,CAAC;AAEF;;;GAGG;AACI,MAAM,eAAe,GAAG,CAAC,KAA2B,EAAa,EAAE;IACxE,OAAO;QACL,EAAE,EAAE,mBAAmB,EAAE;QACzB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,MAAM,EAAE,SAAS;QACjB,SAAS,EAAE,IAAI,IAAI,EAAE;QACrB,QAAQ,EAAE,KAAK,CAAC,QAAQ;KACzB,CAAC;AACJ,CAAC,CAAC;AATW,QAAA,eAAe,mBAS1B;AAEF;;;GAGG;AACI,MAAM,iBAAiB,GAAG,CAC/B,SAAoB,EACpB,KAA6B,EAClB,EAAE;IACb,OAAO;QACL,GAAG,SAAS;QACZ,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,WAAW,EAAE,IAAI,IAAI,EAAE;QACvB,QAAQ,EAAE;YACR,GAAG,SAAS,CAAC,QAAQ;YACrB,GAAG,KAAK,CAAC,QAAQ;SAClB;KACF,CAAC;AACJ,CAAC,CAAC;AAbW,QAAA,iBAAiB,qBAa5B"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { ExecutionId, StepId, Execution, ExecutionStatus, Step, Evaluation, FilterResult, CreateExecutionInput, RecordStepInput, CompleteExecutionInput } from './types';
+export { createExecution, completeExecution } from './execution';
+export { recordStep, createEvaluation, createFilterResult } from './step';

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFilterResult = exports.createEvaluation = exports.recordStep = exports.completeExecution = exports.createExecution = void 0;
+var execution_1 = require("./execution");
+Object.defineProperty(exports, "createExecution", { enumerable: true, get: function () { return execution_1.createExecution; } });
+Object.defineProperty(exports, "completeExecution", { enumerable: true, get: function () { return execution_1.completeExecution; } });
+var step_1 = require("./step");
+Object.defineProperty(exports, "recordStep", { enumerable: true, get: function () { return step_1.recordStep; } });
+Object.defineProperty(exports, "createEvaluation", { enumerable: true, get: function () { return step_1.createEvaluation; } });
+Object.defineProperty(exports, "createFilterResult", { enumerable: true, get: function () { return step_1.createFilterResult; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAaA,yCAGqB;AAFnB,4GAAA,eAAe,OAAA;AACf,8GAAA,iBAAiB,OAAA;AAGnB,+BAIgB;AAHd,kGAAA,UAAU,OAAA;AACV,wGAAA,gBAAgB,OAAA;AAChB,0GAAA,kBAAkB,OAAA"}

package/dist/step.d.ts

@@ -0,0 +1,21 @@
+import { Step, RecordStepInput, Evaluation, FilterResult } from './types';
+/**
+ * Record a decision step with inputs, outpts, reasoning, and optional evaluations.
+ * Returns a step object that you should persist.
+ */
+export declare const recordStep: (input: RecordStepInput) => Step;
+/**
+ * Create an evaluation for a candidate item.
+ * Use this to track pass/fail decisions with optional filters and scoring.
+ */
+export declare const createEvaluation: (itemId: string, itemLabel: string, passed: boolean, options?: {
+    score?: number;
+    filters?: FilterResult[];
+    reason?: string;
+    metadata?: Record<string, unknown>;
+}) => Evaluation;
+/**
+ * Create a filter result showing why a candidate passed or failed a specific filter.
+ * Include actual and expected values for better debugging.
+ */
+export declare const createFilterResult: (filterName: string, passed: boolean, detail: string, actualValue?: unknown, expectedValue?: unknown) => FilterResult;

package/dist/step.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFilterResult = exports.createEvaluation = exports.recordStep = void 0;
+const generateStepId = () => {
+    const timestamp = Date.now();
+    const random = Math.random().toString(36).substring(2, 9);
+    return `step_${timestamp}_${random}`;
+};
+/**
+ * Record a decision step with inputs, outpts, reasoning, and optional evaluations.
+ * Returns a step object that you should persist.
+ */
+const recordStep = (input) => {
+    return {
+        id: generateStepId(),
+        executionId: input.executionId,
+        name: input.name,
+        stepType: input.stepType,
+        timestamp: new Date(),
+        durationMs: input.durationMs,
+        input: input.input,
+        output: input.output,
+        reasoning: input.reasoning,
+        evaluations: input.evaluations,
+        metadata: input.metadata
+    };
+};
+exports.recordStep = recordStep;
+/**
+ * Create an evaluation for a candidate item.
+ * Use this to track pass/fail decisions with optional filters and scoring.
+ */
+const createEvaluation = (itemId, itemLabel, passed, options) => {
+    return {
+        itemId,
+        itemLabel,
+        passed,
+        score: options?.score,
+        filters: options?.filters,
+        reason: options?.reason,
+        metadata: options?.metadata
+    };
+};
+exports.createEvaluation = createEvaluation;
+/**
+ * Create a filter result showing why a candidate passed or failed a specific filter.
+ * Include actual and expected values for better debugging.
+ */
+const createFilterResult = (filterName, passed, detail, actualValue, expectedValue) => {
+    return {
+        filterName,
+        passed,
+        detail,
+        actualValue,
+        expectedValue
+    };
+};
+exports.createFilterResult = createFilterResult;
+//# sourceMappingURL=step.js.map

package/dist/step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.js","sourceRoot":"","sources":["../src/step.ts"],"names":[],"mappings":";;;AAEA,MAAM,cAAc,GAAG,GAAW,EAAE;IAClC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1D,OAAO,QAAQ,SAAS,IAAI,MAAM,EAAE,CAAC;AACvC,CAAC,CAAC;AAEF;;;GAGG;AACI,MAAM,UAAU,GAAG,CAAC,KAAsB,EAAQ,EAAE;IACzD,OAAO;QACL,EAAE,EAAE,cAAc,EAAE;QACpB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,SAAS,EAAE,IAAI,IAAI,EAAE;QACrB,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,QAAQ,EAAE,KAAK,CAAC,QAAQ;KACzB,CAAC;AACJ,CAAC,CAAC;AAdW,QAAA,UAAU,cAcrB;AAEF;;;GAGG;AACI,MAAM,gBAAgB,GAAG,CAC9B,MAAc,EACd,SAAiB,EACjB,MAAe,EACf,OAKC,EACW,EAAE;IACd,OAAO;QACL,MAAM;QACN,SAAS;QACT,MAAM;QACN,KAAK,EAAE,OAAO,EAAE,KAAK;QACrB,OAAO,EAAE,OAAO,EAAE,OAAO;QACzB,MAAM,EAAE,OAAO,EAAE,MAAM;QACvB,QAAQ,EAAE,OAAO,EAAE,QAAQ;KAC5B,CAAC;AACJ,CAAC,CAAC;AApBW,QAAA,gBAAgB,oBAoB3B;AAEF;;;GAGG;AACI,MAAM,kBAAkB,GAAG,CAChC,UAAkB,EAClB,MAAe,EACf,MAAc,EACd,WAAqB,EACrB,aAAuB,EACT,EAAE;IAChB,OAAO;QACL,UAAU;QACV,MAAM;QACN,MAAM;QACN,WAAW;QACX,aAAa;KACd,CAAC;AACJ,CAAC,CAAC;AAdW,QAAA,kBAAkB,sBAc7B"}

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+export type ExecutionId = string;
+export type StepId = string;
+export interface Execution {
+    id: ExecutionId;
+    name: string;
+    description?: string;
+    status: ExecutionStatus;
+    startedAt: Date;
+    completedAt?: Date;
+    metadata?: Record<string, unknown>;
+}
+export type ExecutionStatus = 'running' | 'completed' | 'failed';
+export interface Step {
+    id: StepId;
+    executionId: ExecutionId;
+    name: string;
+    stepType: string;
+    timestamp: Date;
+    durationMs?: number;
+    input: Record<string, unknown>;
+    output: Record<string, unknown>;
+    reasoning: string;
+    metadata?: Record<string, unknown>;
+    evaluations?: Evaluation[];
+}
+export interface Evaluation {
+    itemId: string;
+    itemLabel: string;
+    passed: boolean;
+    score?: number;
+    filters?: FilterResult[];
+    reason?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface FilterResult {
+    filterName: string;
+    passed: boolean;
+    detail: string;
+    actualValue?: unknown;
+    expectedValue?: unknown;
+}
+export interface CreateExecutionInput {
+    name: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface RecordStepInput {
+    executionId: ExecutionId;
+    name: string;
+    stepType: string;
+    input: Record<string, unknown>;
+    output: Record<string, unknown>;
+    reasoning: string;
+    durationMs?: number;
+    evaluations?: Evaluation[];
+    metadata?: Record<string, unknown>;
+}
+export interface CompleteExecutionInput {
+    status: 'completed' | 'failed';
+    metadata?: Record<string, unknown>;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "decision-xray",
+  "version": "0.1.0",
+  "description": "Lightweight SDK for capturing decision-making in multi-step algorithmic systems",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "debugging",
+    "decision-tracking",
+    "pipeline",
+    "observability",
+    "tracing",
+    "xray"
+  ],
+  "author": "Mehul",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mehulkchaudhari/decision-xray.git",
+    "directory": "decision-xray"
+  },
+  "homepage": "https://github.com/mehulkchaudhari/decision-xray#readme",
+  "bugs": {
+    "url": "https://github.com/mehulkchaudhari/decision-xray/issues"
+  },
+  "devDependencies": {
+    "typescript": "^5.2.2"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}
+