@elsium-ai/observe 0.2.3 → 0.3.0

package/dist/experiment.d.ts

@@ -0,0 +1,28 @@
+export interface ExperimentVariant {
+    name: string;
+    weight: number;
+    config: Record<string, unknown>;
+}
+export interface ExperimentResults {
+    name: string;
+    totalAssignments: number;
+    variants: Record<string, {
+        assignments: number;
+        metrics: Record<string, {
+            sum: number;
+            count: number;
+            avg: number;
+        }>;
+    }>;
+}
+export interface Experiment {
+    assign(userId?: string): ExperimentVariant;
+    record(variant: string, metrics: Record<string, number>): void;
+    results(): ExperimentResults;
+}
+export interface ExperimentConfig {
+    name: string;
+    variants: ExperimentVariant[];
+}
+export declare function createExperiment(config: ExperimentConfig): Experiment;
+//# sourceMappingURL=experiment.d.ts.map

package/dist/experiment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiment.d.ts","sourceRoot":"","sources":["../src/experiment.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B;AAED,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,gBAAgB,EAAE,MAAM,CAAA;IACxB,QAAQ,EAAE,MAAM,CACf,MAAM,EACN;QACC,WAAW,EAAE,MAAM,CAAA;QACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KACpE,CACD,CAAA;CACD;AAED,MAAM,WAAW,UAAU;IAC1B,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAAA;IAC1C,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;IAC9D,OAAO,IAAI,iBAAiB,CAAA;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,iBAAiB,EAAE,CAAA;CAC7B;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,CA0FrE"}

package/dist/index.d.ts

@@ -10,6 +10,8 @@ export { createAuditTrail, auditMiddleware } from './audit';
 export type { AuditEventType, AuditEvent, AuditStorageAdapter, AuditQueryFilter, AuditIntegrityResult, AuditTrailConfig, AuditTrail, } from './audit';
 export { createProvenanceTracker } from './provenance';
 export type { ProvenanceRecord, ProvenanceTracker } from './provenance';
+export { createExperiment } from './experiment';
+export type { Experiment, ExperimentConfig, ExperimentVariant, ExperimentResults, } from './experiment';
 export { toOTelSpan, toOTelExportRequest, toTraceparent, parseTraceparent, injectTraceContext, extractTraceContext, createOTLPExporter, } from './otel';
 export type { OTelSpan, OTelSpanKind, OTelStatusCode, OTelAttribute, OTelAttributeValue, OTelEvent, OTelResource, OTelExportRequest, TraceContext, OTLPExporterConfig, } from './otel';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AACnC,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAG1F,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACnE,YAAY,EACX,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,SAAS,EACT,aAAa,EACb,sBAAsB,EACtB,eAAe,EACf,cAAc,GACd,MAAM,eAAe,CAAA;AAGtB,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAClC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAG9F,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACzC,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAG9D,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAC3D,YAAY,EACX,cAAc,EACd,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,UAAU,GACV,MAAM,SAAS,CAAA;AAGhB,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AACtD,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAGvE,OAAO,EACN,UAAU,EACV,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,GAClB,MAAM,QAAQ,CAAA;AACf,YAAY,EACX,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,SAAS,EACT,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,GAClB,MAAM,QAAQ,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AACnC,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAG1F,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACnE,YAAY,EACX,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,SAAS,EACT,aAAa,EACb,sBAAsB,EACtB,eAAe,EACf,cAAc,GACd,MAAM,eAAe,CAAA;AAGtB,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAClC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAG9F,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACzC,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAG9D,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAC3D,YAAY,EACX,cAAc,EACd,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,UAAU,GACV,MAAM,SAAS,CAAA;AAGhB,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AACtD,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAGvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAC/C,YAAY,EACX,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,GACjB,MAAM,cAAc,CAAA;AAGrB,OAAO,EACN,UAAU,EACV,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,GAClB,MAAM,QAAQ,CAAA;AACf,YAAY,EACX,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,SAAS,EACT,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,GAClB,MAAM,QAAQ,CAAA"}

package/dist/index.js

@@ -140,6 +140,11 @@ function createLogger(options = {}) {
     }
   };
 }
+// ../core/src/schema.ts
+var log = createLogger();
+// ../core/src/registry.ts
+var log2 = createLogger();
+var BLOCKED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 // src/span.ts
 function createSpan(name, options = {}) {
   const id = generateId("spn");
@@ -492,7 +497,7 @@ function createCostEngine(config = {}) {
 }
 // src/tracer.ts
 import { writeFileSync } from "node:fs";
-var log = createLogger();
+var log3 = createLogger();
 function observe(config = {}) {
   const {
     output = ["console"],
@@ -515,7 +520,7 @@ function observe(config = {}) {
           try {
             writeFileSync(filename, JSON.stringify(spansToExport, null, 2));
           } catch (err2) {
-            log.error("Failed to write trace file", {
+            log3.error("Failed to write trace file", {
               error: err2 instanceof Error ? err2.message : String(err2)
             });
           }
@@ -590,7 +595,7 @@ function observe(config = {}) {
 function consoleHandler(span) {
   const duration = span.durationMs !== undefined ? `${span.durationMs}ms` : "running";
   const status = span.status === "error" ? "[ERROR]" : span.status === "ok" ? "[OK]" : "[...]";
-  log.info("span", {
+  log3.info("span", {
     trace: span.traceId,
     span: span.name,
     kind: span.kind,
@@ -920,8 +925,86 @@ function createProvenanceTracker(options) {
     }
   };
 }
+// src/experiment.ts
+import { createHash as createHash3 } from "node:crypto";
+var log4 = createLogger();
+function createExperiment(config) {
+  const { name, variants } = config;
+  if (variants.length === 0) {
+    throw new Error("Experiment must have at least one variant");
+  }
+  const totalWeight = variants.reduce((sum, v) => sum + v.weight, 0);
+  const stats = {};
+  for (const v of variants) {
+    stats[v.name] = { assignments: 0, metrics: {} };
+  }
+  function hashAssign(userId) {
+    const hash = createHash3("sha256").update(`${name}:${userId}`).digest();
+    const value = hash.readUInt32BE(0) % 1e4 / 1e4;
+    return pickVariant(value);
+  }
+  function randomAssign() {
+    const value = Math.random();
+    return pickVariant(value);
+  }
+  function pickVariant(value) {
+    let cumulative = 0;
+    for (const v of variants) {
+      cumulative += v.weight / totalWeight;
+      if (value < cumulative)
+        return v;
+    }
+    return variants[variants.length - 1];
+  }
+  return {
+    assign(userId) {
+      const variant = userId ? hashAssign(userId) : randomAssign();
+      const s = stats[variant.name];
+      if (s)
+        s.assignments++;
+      log4.debug("Experiment assignment", {
+        experiment: name,
+        variant: variant.name,
+        userId
+      });
+      return variant;
+    },
+    record(variant, metrics) {
+      const s = stats[variant];
+      if (!s)
+        return;
+      for (const [key, value] of Object.entries(metrics)) {
+        if (!s.metrics[key]) {
+          s.metrics[key] = { sum: 0, count: 0 };
+        }
+        s.metrics[key].sum += value;
+        s.metrics[key].count++;
+      }
+    },
+    results() {
+      let totalAssignments = 0;
+      const variantResults = {};
+      for (const [vName, s] of Object.entries(stats)) {
+        totalAssignments += s.assignments;
+        const metricsResult = {};
+        for (const [key, m] of Object.entries(s.metrics)) {
+          metricsResult[key] = {
+            sum: m.sum,
+            count: m.count,
+            avg: m.count > 0 ? m.sum / m.count : 0
+          };
+        }
+        variantResults[vName] = {
+          assignments: s.assignments,
+          metrics: metricsResult
+        };
+      }
+      return { name, totalAssignments, variants: variantResults };
+    }
+  };
+}
 // src/otel.ts
-var log2 = createLogger();
+var log5 = createLogger();
 var SPAN_KIND_MAP = {
   llm: 3,
   tool: 1,
@@ -1062,10 +1145,10 @@ function createOTLPExporter(config) {
         body: JSON.stringify(payload)
       });
       if (!response.ok) {
-        log2.error(`OTLP export failed: ${response.status} ${response.statusText}`);
+        log5.error(`OTLP export failed: ${response.status} ${response.statusText}`);
       }
     } catch (err2) {
-      log2.error("OTLP export error", { error: err2 instanceof Error ? err2.message : String(err2) });
+      log5.error("OTLP export error", { error: err2 instanceof Error ? err2.message : String(err2) });
     }
   }
   function startAutoFlush() {
@@ -1114,6 +1197,7 @@ export {
   createProvenanceTracker,
   createOTLPExporter,
   createMetrics,
+  createExperiment,
   createCostEngine,
   createAuditTrail,
   auditMiddleware

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@elsium-ai/observe",
-	"version": "0.2.3",
+	"version": "0.3.0",
 	"description": "Observability, tracing, and cost tracking for ElsiumAI",
 	"license": "MIT",
 	"author": "Eric Utrera <ebutrera9103@gmail.com>",
@@ -26,7 +26,7 @@
 		"dev": "bun --watch src/index.ts"
 	},
 	"dependencies": {
-		"@elsium-ai/core": "^0.2.3"
+		"@elsium-ai/core": "^0.3.0"
 	},
 	"devDependencies": {
 		"typescript": "^5.7.0"