ai-experiments 0.1.0 → 2.0.2

package/dist/experiment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiment.js","sourceRoot":"","sources":["../src/experiment.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AASnC,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,MAA0C,EAC1C,UAAgC,EAAE;IAElC,MAAM,EACJ,QAAQ,GAAG,IAAI,EACf,cAAc,EACd,WAAW,GAAG,KAAK,EACnB,OAAO,EAAE,WAAW,EACpB,cAAc,EACd,iBAAiB,EACjB,cAAc,GACf,GAAG,OAAO,CAAA;IAEX,MAAM,mBAAmB,GAAG,IAAI,IAAI,EAAE,CAAA;IAEtC,yBAAyB;IACzB,KAAK,CAAC;QACJ,IAAI,EAAE,kBAAkB;QACxB,SAAS,EAAE,mBAAmB;QAC9B,IAAI,EAAE;YACJ,YAAY,EAAE,MAAM,CAAC,EAAE;YACvB,cAAc,EAAE,MAAM,CAAC,IAAI;YAC3B,YAAY,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM;YACpC,QAAQ;YACR,GAAG,MAAM,CAAC,QAAQ;SACnB;KACF,CAAC,CAAA;IAEF,MAAM,OAAO,GAAgC,EAAE,CAAA;IAE/C,mBAAmB;IACnB,IAAI,QAAQ,EAAE,CAAC;QACb,qDAAqD;QACrD,MAAM,cAAc,GAAG,KAAK,EAC1B,OAAmC,EACC,EAAE;YACtC,OAAO,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE;gBAC9C,cAAc;gBACd,iBAAiB;gBACjB,cAAc;aACf,CAAC,CAAA;QACJ,CAAC,CAAA;QAED,IAAI,cAAc,IAAI,cAAc,GAAG,CAAC,EAAE,CAAC;YACzC,iCAAiC;YACjC,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAA;YAC1D,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC3B,MAAM,YAAY,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAA;gBACjE,OAAO,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,CAAA;gBAE7B,oCAAoC;gBACpC,IAAI,WAAW,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;oBACxD,MAAK;gBACP,CAAC;YACH,CAAC;QACH,CAAC;aAAM,CAAC;YACN,0BAA0B;YAC1B,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAA;YACzE,OAAO,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,CAAA;QAC7B,CAAC;IACH,CAAC;SAAM,CAAC;QACN,uBAAuB;QACvB,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACtC,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE;gBAC5D,cAAc;gBACd,iBAAiB;gBACjB,cAAc;aACf,CAAC,CAAA;YACF,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;YAEpB,oCAAoC;YACpC,IAAI,WAAW,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACnC,MAAK;YACP,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,iBAAiB,GAAG,IAAI,IAAI,EAAE,CAAA;IACpC,MAAM,aAAa,GAAG,iBAAiB,CAAC,OAAO,EAAE,GAAG,mBAAmB,CAAC,OAAO,EAAE,CAAA;IAEjF,8BAA8B;IAC9B,IAAI,WAAsD,CAAA;IAC1D,MAAM,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,WAAW,KAAK,SAAS,CAAC,CAAA;IACzF,IAAI,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CACtD,CAAC,OAAO,CAAC,WAAW,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CACtF,CAAA;QACD,WAAW,GAAG;YACZ,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAY;SAC/B,CAAA;IACH,CAAC;IAED,MAAM,OAAO,GAA+B;QAC1C,YAAY,EAAE,MAAM,CAAC,EAAE;QACvB,cAAc,EAAE,MAAM,CAAC,IAAI;QAC3B,OAAO;QACP,WAAW;QACX,aAAa;QACb,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM;QACrD,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM;QACtD,SAAS,EAAE,mBAAmB;QAC9B,WAAW,EAAE,iBAAiB;KAC/B,CAAA;IAED,8BAA8B;IAC9B,KAAK,CAAC;QACJ,IAAI,EAAE,qBAAqB;QAC3B,SAAS,EAAE,iBAAiB;QAC5B,IAAI,EAAE;YACJ,YAAY,EAAE,MAAM,CAAC,EAAE;YACvB,cAAc,EAAE,MAAM,CAAC,IAAI;YAC3B,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,aAAa;YACb,WAAW,EAAE,WAAW,EAAE,SAAS;YACnC,GAAG,MAAM,CAAC,QAAQ;SACnB;KACF,CAAC,CAAA;IAEF,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,UAAU,CACvB,MAA0C,EAC1C,OAAmC,EACnC,WAAgD,EAChD,SAIC;IAED,MAAM,KAAK,GAAG,UAAU,EAAE,CAAA;IAC1B,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAA;IAE5B,MAAM,OAAO,GAAsB;QACjC,YAAY,EAAE,MAAM,CAAC,EAAE;QACvB,SAAS,EAAE,OAAO,CAAC,EAAE;QACrB,KAAK;QACL,SAAS,EAAE,SAAS;QACpB,IAAI,EAAE,WAAW;KAClB,CAAA;IAED,sBAAsB;IACtB,KAAK,CAAC;QACJ,IAAI,EAAE,eAAe;QACrB,SAAS,EAAE,SAAS;QACpB,IAAI,EAAE;YACJ,YAAY,EAAE,MAAM,CAAC,EAAE;YACvB,SAAS,EAAE,OAAO,CAAC,EAAE;YACrB,WAAW,EAAE,OAAO,CAAC,IAAI;YACzB,KAAK;SACN;KACF,CAAC,CAAA;IAEF,SAAS,CAAC,cAAc,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IAEpD,IAAI,CAAC;QACH,sBAAsB;QACtB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAC5D,MAAM,OAAO,GAAG,IAAI,IAAI,EAAE,CAAA;QAC1B,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,OAAO,EAAE,CAAA;QAExD,6BAA6B;QAC7B,IAAI,WAA+B,CAAA;QACnC,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClB,WAAW,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;YAEzC,KAAK,CAAC;gBACJ,IAAI,EAAE,iBAAiB;gBACvB,SAAS,EAAE,IAAI,IAAI,EAAE;gBACrB,IAAI,EAAE;oBACJ,YAAY,EAAE,MAAM,CAAC,EAAE;oBACvB,SAAS,EAAE,OAAO,CAAC,EAAE;oBACrB,KAAK;oBACL,WAAW;iBACZ;aACF,CAAC,CAAA;QACJ,CAAC;QAED,MAAM,gBAAgB,GAA8B;YAClD,YAAY,EAAE,MAAM,CAAC,EAAE;YACvB,SAAS,EAAE,OAAO,CAAC,EAAE;YACrB,WAAW,EAAE,OAAO,CAAC,IAAI;YACzB,KAAK;YACL,MAAM;YACN,WAAW;YACX,QAAQ;YACR,SAAS,EAAE,SAAS;YACpB,WAAW,EAAE,OAAO;YACpB,OAAO,EAAE,IAAI;SACd,CAAA;QAED,2BAA2B;QAC3B,KAAK,CAAC;YACJ,IAAI,EAAE,kBAAkB;YACxB,SAAS,EAAE,OAAO;YAClB,IAAI,EAAE;gBACJ,YAAY,EAAE,MAAM,CAAC,EAAE;gBACvB,SAAS,EAAE,OAAO,CAAC,EAAE;gBACrB,WAAW,EAAE,OAAO,CAAC,IAAI;gBACzB,KAAK;gBACL,QAAQ;gBACR,WAAW;gBACX,OAAO,EAAE,IAAI;aACd;SACF,CAAC,CAAA;QAEF,SAAS,CAAC,iBAAiB,EAAE,CAAC,gBAAgB,CAAC,CAAA;QAE/C,OAAO,gBAAgB,CAAA;IACzB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,IAAI,IAAI,EAAE,CAAA;QAC1B,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,OAAO,EAAE,CAAA;QACxD,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;QAErE,sBAAsB;QACtB,KAAK,CAAC;YACJ,IAAI,EAAE,eAAe;YACrB,SAAS,EAAE,OAAO;YAClB,IAAI,EAAE;gBACJ,YAAY,EAAE,MAAM,CAAC,EAAE;gBACvB,SAAS,EAAE,OAAO,CAAC,EAAE;gBACrB,WAAW,EAAE,OAAO,CAAC,IAAI;gBACzB,KAAK;gBACL,QAAQ;gBACR,KAAK,EAAE,GAAG,CAAC,OAAO;gBAClB,KAAK,EAAE,GAAG,CAAC,KAAK;aACjB;SACF,CAAC,CAAA;QAEF,SAAS,CAAC,cAAc,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,CAAC,CAAA;QAE3C,OAAO;YACL,YAAY,EAAE,MAAM,CAAC,EAAE;YACvB,SAAS,EAAE,OAAO,CAAC,EAAE;YACrB,WAAW,EAAE,OAAO,CAAC,IAAI;YACzB,KAAK;YACL,MAAM,EAAE,SAA+B;YACvC,QAAQ;YACR,SAAS,EAAE,SAAS;YACpB,WAAW,EAAE,OAAO;YACpB,KAAK,EAAE,GAAG;YACV,OAAO,EAAE,KAAK;SACf,CAAA;IACH,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAS,UAAU,CAAI,KAAU,EAAE,IAAY;IAC7C,MAAM,MAAM,GAAU,EAAE,CAAA;IACxB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;QAC5C,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAA;IACvC,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAO;IAEP,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAgB,CAAA;IAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;IAEvC,4BAA4B;IAC5B,MAAM,YAAY,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAA;IAE7C,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QACvC,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAC/B,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CACF,CAAA;QAErC,OAAO;YACL,EAAE,EAAE,WAAW,KAAK,EAAE;YACtB,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;YAC/D,MAAM;SACP,CAAA;IACH,CAAC,CAAC,CAAA;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,gBAAgB,CAAI,MAAa;IACxC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,EAAE,CAAC,CAAA;IACpC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,CAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAE1D,MAAM,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,GAAG,MAAM,CAAA;IAC/B,MAAM,WAAW,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAA;IAE1C,OAAO,KAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAA;AACrE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ai-experiments - AI-powered experimentation primitives for testing and evaluating models
+ *
+ * This package provides tools for A/B testing, parameter exploration, decision making,
+ * and tracking in AI applications.
+ *
+ * @packageDocumentation
+ */
+export * from './types.js';
+export { Experiment, createVariantsFromGrid } from './experiment.js';
+export { cartesian, cartesianFilter, cartesianSample, cartesianCount, cartesianWithLabels, } from './cartesian.js';
+export { decide, decideWeighted, decideEpsilonGreedy, decideThompsonSampling, decideUCB, } from './decide.js';
+export { track, flush, configureTracking, getTrackingConfig, createConsoleBackend, createMemoryBackend, createBatchBackend, createFileBackend, } from './tracking.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,cAAc,YAAY,CAAA;AAG1B,OAAO,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AAGpE,OAAO,EACL,SAAS,EACT,eAAe,EACf,eAAe,EACf,cAAc,EACd,mBAAmB,GACpB,MAAM,gBAAgB,CAAA;AAGvB,OAAO,EACL,MAAM,EACN,cAAc,EACd,mBAAmB,EACnB,sBAAsB,EACtB,SAAS,GACV,MAAM,aAAa,CAAA;AAGpB,OAAO,EACL,KAAK,EACL,KAAK,EACL,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,eAAe,CAAA"}

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * ai-experiments - AI-powered experimentation primitives for testing and evaluating models
+ *
+ * This package provides tools for A/B testing, parameter exploration, decision making,
+ * and tracking in AI applications.
+ *
+ * @packageDocumentation
+ */
+// Export core types
+export * from './types.js';
+// Export experiment functionality
+export { Experiment, createVariantsFromGrid } from './experiment.js';
+// Export cartesian product utilities
+export { cartesian, cartesianFilter, cartesianSample, cartesianCount, cartesianWithLabels, } from './cartesian.js';
+// Export decision making utilities
+export { decide, decideWeighted, decideEpsilonGreedy, decideThompsonSampling, decideUCB, } from './decide.js';
+// Export tracking utilities
+export { track, flush, configureTracking, getTrackingConfig, createConsoleBackend, createMemoryBackend, createBatchBackend, createFileBackend, } from './tracking.js';
+//# 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;;;;;;;GAOG;AAEH,oBAAoB;AACpB,cAAc,YAAY,CAAA;AAE1B,kCAAkC;AAClC,OAAO,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AAEpE,qCAAqC;AACrC,OAAO,EACL,SAAS,EACT,eAAe,EACf,eAAe,EACf,cAAc,EACd,mBAAmB,GACpB,MAAM,gBAAgB,CAAA;AAEvB,mCAAmC;AACnC,OAAO,EACL,MAAM,EACN,cAAc,EACd,mBAAmB,EACnB,sBAAsB,EACtB,SAAS,GACV,MAAM,aAAa,CAAA;AAEpB,4BAA4B;AAC5B,OAAO,EACL,KAAK,EACL,KAAK,EACL,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,eAAe,CAAA"}

package/dist/tracking.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Event tracking for experiments
+ */
+import type { TrackingEvent, TrackingBackend, TrackingOptions } from './types.js';
+/**
+ * Configure tracking
+ *
+ * @example
+ * ```ts
+ * import { configureTracking } from 'ai-experiments'
+ *
+ * // Use console backend (default)
+ * configureTracking({
+ *   enabled: true,
+ *   metadata: { projectId: 'my-project' },
+ * })
+ *
+ * // Use custom backend
+ * configureTracking({
+ *   backend: {
+ *     track: async (event) => {
+ *       await fetch('/api/analytics', {
+ *         method: 'POST',
+ *         body: JSON.stringify(event),
+ *       })
+ *     },
+ *   },
+ * })
+ *
+ * // Disable tracking
+ * configureTracking({ enabled: false })
+ * ```
+ */
+export declare function configureTracking(options: TrackingOptions): void;
+/**
+ * Track an event
+ *
+ * @example
+ * ```ts
+ * import { track } from 'ai-experiments'
+ *
+ * track({
+ *   type: 'experiment.start',
+ *   timestamp: new Date(),
+ *   data: {
+ *     experimentId: 'my-experiment',
+ *     variantCount: 3,
+ *   },
+ * })
+ * ```
+ */
+export declare function track(event: TrackingEvent): void;
+/**
+ * Flush pending events
+ *
+ * Call this before the process exits to ensure all events are sent.
+ *
+ * @example
+ * ```ts
+ * import { flush } from 'ai-experiments'
+ *
+ * process.on('SIGINT', async () => {
+ *   await flush()
+ *   process.exit(0)
+ * })
+ * ```
+ */
+export declare function flush(): Promise<void>;
+/**
+ * Create a console-based tracking backend
+ *
+ * Logs events to console.log in a human-readable format.
+ */
+export declare function createConsoleBackend(options?: {
+    /** Whether to include full event data (default: false) */
+    verbose?: boolean;
+}): TrackingBackend;
+/**
+ * Create an in-memory tracking backend that stores events
+ *
+ * Useful for testing or collecting events for batch processing.
+ *
+ * @example
+ * ```ts
+ * import { createMemoryBackend } from 'ai-experiments'
+ *
+ * const backend = createMemoryBackend()
+ * configureTracking({ backend })
+ *
+ * // Run experiments...
+ *
+ * // Get all events
+ * const events = backend.getEvents()
+ * console.log(`Tracked ${events.length} events`)
+ *
+ * // Clear events
+ * backend.clear()
+ * ```
+ */
+export declare function createMemoryBackend(): TrackingBackend & {
+    getEvents: () => TrackingEvent[];
+    clear: () => void;
+};
+/**
+ * Create a batching tracking backend
+ *
+ * Batches events and sends them in groups to reduce network overhead.
+ *
+ * @example
+ * ```ts
+ * import { createBatchBackend } from 'ai-experiments'
+ *
+ * const backend = createBatchBackend({
+ *   batchSize: 10,
+ *   flushInterval: 5000, // 5 seconds
+ *   send: async (events) => {
+ *     await fetch('/api/analytics/batch', {
+ *       method: 'POST',
+ *       body: JSON.stringify({ events }),
+ *     })
+ *   },
+ * })
+ *
+ * configureTracking({ backend })
+ * ```
+ */
+export declare function createBatchBackend(options: {
+    /** Maximum batch size before auto-flush */
+    batchSize: number;
+    /** Interval in ms to auto-flush (default: no auto-flush) */
+    flushInterval?: number;
+    /** Function to send batched events */
+    send: (events: TrackingEvent[]) => Promise<void>;
+}): TrackingBackend;
+/**
+ * Create a file-based tracking backend
+ *
+ * Writes events to a file (JSONL format).
+ *
+ * @example
+ * ```ts
+ * import { createFileBackend } from 'ai-experiments'
+ *
+ * const backend = createFileBackend({
+ *   path: './experiments.jsonl',
+ * })
+ *
+ * configureTracking({ backend })
+ * ```
+ */
+export declare function createFileBackend(options: {
+    /** Path to the file */
+    path: string;
+}): TrackingBackend;
+/**
+ * Get current tracking configuration
+ */
+export declare function getTrackingConfig(): Readonly<Required<TrackingOptions>>;
+//# sourceMappingURL=tracking.d.ts.map

package/dist/tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking.d.ts","sourceRoot":"","sources":["../src/tracking.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAWjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAMhE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAsBhD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAI3C;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE;IAC7C,0DAA0D;IAC1D,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,GAAG,eAAe,CAgBlB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,IAAI,eAAe,GAAG;IACvD,SAAS,EAAE,MAAM,aAAa,EAAE,CAAA;IAChC,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB,CAYA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAC1C,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAA;IACjB,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,sCAAsC;IACtC,IAAI,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACjD,GAAG,eAAe,CAkDlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IACzC,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAA;CACb,GAAG,eAAe,CAwClB;AAaD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,QAAQ,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CAEvE"}

package/dist/tracking.js

@@ -0,0 +1,310 @@
+/**
+ * Event tracking for experiments
+ */
+/**
+ * Default tracking configuration
+ */
+let trackingConfig = {
+    backend: createConsoleBackend(),
+    enabled: true,
+    metadata: {},
+};
+/**
+ * Configure tracking
+ *
+ * @example
+ * ```ts
+ * import { configureTracking } from 'ai-experiments'
+ *
+ * // Use console backend (default)
+ * configureTracking({
+ *   enabled: true,
+ *   metadata: { projectId: 'my-project' },
+ * })
+ *
+ * // Use custom backend
+ * configureTracking({
+ *   backend: {
+ *     track: async (event) => {
+ *       await fetch('/api/analytics', {
+ *         method: 'POST',
+ *         body: JSON.stringify(event),
+ *       })
+ *     },
+ *   },
+ * })
+ *
+ * // Disable tracking
+ * configureTracking({ enabled: false })
+ * ```
+ */
+export function configureTracking(options) {
+    trackingConfig = {
+        backend: options.backend ?? trackingConfig.backend,
+        enabled: options.enabled ?? trackingConfig.enabled,
+        metadata: options.metadata ?? trackingConfig.metadata,
+    };
+}
+/**
+ * Track an event
+ *
+ * @example
+ * ```ts
+ * import { track } from 'ai-experiments'
+ *
+ * track({
+ *   type: 'experiment.start',
+ *   timestamp: new Date(),
+ *   data: {
+ *     experimentId: 'my-experiment',
+ *     variantCount: 3,
+ *   },
+ * })
+ * ```
+ */
+export function track(event) {
+    if (!trackingConfig.enabled) {
+        return;
+    }
+    // Merge global metadata
+    const enrichedEvent = {
+        ...event,
+        data: {
+            ...event.data,
+            ...trackingConfig.metadata,
+        },
+    };
+    // Track via backend (handle both sync and async)
+    const result = trackingConfig.backend.track(enrichedEvent);
+    if (result instanceof Promise) {
+        // Don't await - fire and forget
+        result.catch((error) => {
+            console.error('Error tracking event:', error);
+        });
+    }
+}
+/**
+ * Flush pending events
+ *
+ * Call this before the process exits to ensure all events are sent.
+ *
+ * @example
+ * ```ts
+ * import { flush } from 'ai-experiments'
+ *
+ * process.on('SIGINT', async () => {
+ *   await flush()
+ *   process.exit(0)
+ * })
+ * ```
+ */
+export async function flush() {
+    if (trackingConfig.backend.flush) {
+        await trackingConfig.backend.flush();
+    }
+}
+/**
+ * Create a console-based tracking backend
+ *
+ * Logs events to console.log in a human-readable format.
+ */
+export function createConsoleBackend(options) {
+    const { verbose = false } = options ?? {};
+    return {
+        track: (event) => {
+            const timestamp = event.timestamp.toISOString();
+            if (verbose) {
+                console.log(`[${timestamp}] ${event.type}`, event.data);
+            }
+            else {
+                // Condensed format
+                const key = extractKey(event);
+                console.log(`[${timestamp}] ${event.type} ${key}`);
+            }
+        },
+    };
+}
+/**
+ * Create an in-memory tracking backend that stores events
+ *
+ * Useful for testing or collecting events for batch processing.
+ *
+ * @example
+ * ```ts
+ * import { createMemoryBackend } from 'ai-experiments'
+ *
+ * const backend = createMemoryBackend()
+ * configureTracking({ backend })
+ *
+ * // Run experiments...
+ *
+ * // Get all events
+ * const events = backend.getEvents()
+ * console.log(`Tracked ${events.length} events`)
+ *
+ * // Clear events
+ * backend.clear()
+ * ```
+ */
+export function createMemoryBackend() {
+    const events = [];
+    return {
+        track: (event) => {
+            events.push(event);
+        },
+        getEvents: () => [...events],
+        clear: () => {
+            events.length = 0;
+        },
+    };
+}
+/**
+ * Create a batching tracking backend
+ *
+ * Batches events and sends them in groups to reduce network overhead.
+ *
+ * @example
+ * ```ts
+ * import { createBatchBackend } from 'ai-experiments'
+ *
+ * const backend = createBatchBackend({
+ *   batchSize: 10,
+ *   flushInterval: 5000, // 5 seconds
+ *   send: async (events) => {
+ *     await fetch('/api/analytics/batch', {
+ *       method: 'POST',
+ *       body: JSON.stringify({ events }),
+ *     })
+ *   },
+ * })
+ *
+ * configureTracking({ backend })
+ * ```
+ */
+export function createBatchBackend(options) {
+    const { batchSize, flushInterval, send } = options;
+    const batch = [];
+    let flushTimer = null;
+    const flush = async () => {
+        if (batch.length === 0)
+            return;
+        const eventsToSend = [...batch];
+        batch.length = 0;
+        try {
+            await send(eventsToSend);
+        }
+        catch (error) {
+            console.error('Error sending batch:', error);
+            // Re-add failed events to batch (simple retry strategy)
+            batch.unshift(...eventsToSend);
+        }
+    };
+    const scheduleFlush = () => {
+        if (flushTimer) {
+            clearTimeout(flushTimer);
+        }
+        if (flushInterval) {
+            flushTimer = setTimeout(() => {
+                flush().catch(console.error);
+            }, flushInterval);
+        }
+    };
+    return {
+        track: (event) => {
+            batch.push(event);
+            // Auto-flush if batch is full
+            if (batch.length >= batchSize) {
+                flush().catch(console.error);
+            }
+            else {
+                scheduleFlush();
+            }
+        },
+        flush: async () => {
+            if (flushTimer) {
+                clearTimeout(flushTimer);
+                flushTimer = null;
+            }
+            await flush();
+        },
+    };
+}
+/**
+ * Create a file-based tracking backend
+ *
+ * Writes events to a file (JSONL format).
+ *
+ * @example
+ * ```ts
+ * import { createFileBackend } from 'ai-experiments'
+ *
+ * const backend = createFileBackend({
+ *   path: './experiments.jsonl',
+ * })
+ *
+ * configureTracking({ backend })
+ * ```
+ */
+export function createFileBackend(options) {
+    // Note: This requires Node.js fs module
+    // Import dynamically to avoid breaking in non-Node environments
+    let fs = null;
+    let writeStream = null;
+    const ensureStream = async () => {
+        if (!writeStream) {
+            try {
+                fs = await import('fs');
+                writeStream = fs.createWriteStream(options.path, { flags: 'a' });
+            }
+            catch (error) {
+                console.error('Failed to create file stream:', error);
+                throw error;
+            }
+        }
+        return writeStream;
+    };
+    return {
+        track: async (event) => {
+            try {
+                const stream = await ensureStream();
+                const line = JSON.stringify(event) + '\n';
+                stream.write(line);
+            }
+            catch (error) {
+                console.error('Failed to write event to file:', error);
+            }
+        },
+        flush: async () => {
+            if (writeStream) {
+                return new Promise((resolve, reject) => {
+                    writeStream.end((error) => {
+                        if (error)
+                            reject(error);
+                        else
+                            resolve();
+                    });
+                });
+            }
+        },
+    };
+}
+/**
+ * Extract a key identifier from event data for logging
+ */
+function extractKey(event) {
+    const data = event.data;
+    if ('experimentId' in data)
+        return `exp=${data.experimentId}`;
+    if ('variantId' in data)
+        return `variant=${data.variantId}`;
+    if ('runId' in data)
+        return `run=${data.runId}`;
+    return '';
+}
+/**
+ * Get current tracking configuration
+ */
+export function getTrackingConfig() {
+    return { ...trackingConfig };
+}
+//# sourceMappingURL=tracking.js.map

package/dist/tracking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking.js","sourceRoot":"","sources":["../src/tracking.ts"],"names":[],"mappings":"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"}