ai-experiments 0.1.0 → 2.0.2

package/dist/decide.js

@@ -0,0 +1,329 @@
+/**
+ * Decision making utilities
+ */
+import { track } from './tracking.js';
+/**
+ * Make a decision by evaluating and scoring multiple options
+ *
+ * Scores each option and returns the best one (highest score).
+ *
+ * @example
+ * ```ts
+ * import { decide } from 'ai-experiments'
+ *
+ * // Simple decision with sync scoring
+ * const result = await decide({
+ *   options: ['apple', 'banana', 'orange'],
+ *   score: (fruit) => {
+ *     const prices = { apple: 1.5, banana: 0.5, orange: 2.0 }
+ *     return 1 / prices[fruit] // Lower price = higher score
+ *   },
+ * })
+ * console.log(result.selected) // 'banana'
+ *
+ * // Decision with async scoring (AI-based)
+ * const result = await decide({
+ *   options: [
+ *     { prompt: 'Summarize in one sentence' },
+ *     { prompt: 'Provide a detailed summary' },
+ *     { prompt: 'Extract key points only' },
+ *   ],
+ *   score: async (option) => {
+ *     const result = await ai.generate(option)
+ *     return evaluateQuality(result)
+ *   },
+ *   context: 'Choosing best summarization approach',
+ * })
+ *
+ * // Get all options sorted by score
+ * const result = await decide({
+ *   options: ['fast', 'accurate', 'balanced'],
+ *   score: (approach) => evaluateApproach(approach),
+ *   returnAll: true,
+ * })
+ * console.log(result.allOptions)
+ * // [
+ * //   { option: 'balanced', score: 0.9 },
+ * //   { option: 'accurate', score: 0.85 },
+ * //   { option: 'fast', score: 0.7 },
+ * // ]
+ * ```
+ */
+export async function decide(options) {
+    const { options: choices, score, context, returnAll = false } = options;
+    if (choices.length === 0) {
+        throw new Error('Cannot decide with empty options');
+    }
+    // Score all options
+    const scoredOptions = await Promise.all(choices.map(async (option) => {
+        const optionScore = await score(option);
+        return { option, score: optionScore };
+    }));
+    // Sort by score (highest first)
+    const sorted = scoredOptions.sort((a, b) => b.score - a.score);
+    // Select best option
+    const best = sorted[0];
+    // Track decision
+    track({
+        type: 'decision.made',
+        timestamp: new Date(),
+        data: {
+            context,
+            optionCount: choices.length,
+            selectedScore: best.score,
+            allScores: sorted.map((s) => s.score),
+        },
+    });
+    const result = {
+        selected: best.option,
+        score: best.score,
+    };
+    if (returnAll) {
+        result.allOptions = sorted;
+    }
+    return result;
+}
+/**
+ * Weighted random selection from options
+ *
+ * Each option has a weight, and selection probability is proportional to weight.
+ *
+ * @example
+ * ```ts
+ * import { decideWeighted } from 'ai-experiments'
+ *
+ * const result = decideWeighted([
+ *   { value: 'A', weight: 0.7 },  // 70% chance
+ *   { value: 'B', weight: 0.2 },  // 20% chance
+ *   { value: 'C', weight: 0.1 },  // 10% chance
+ * ])
+ *
+ * console.log(result) // Most likely 'A', but could be B or C
+ * ```
+ */
+export function decideWeighted(options) {
+    if (options.length === 0) {
+        throw new Error('Cannot decide with empty options');
+    }
+    // Calculate total weight
+    const totalWeight = options.reduce((sum, opt) => sum + opt.weight, 0);
+    if (totalWeight <= 0) {
+        throw new Error('Total weight must be positive');
+    }
+    // Generate random value between 0 and totalWeight
+    const random = Math.random() * totalWeight;
+    // Find the option that corresponds to this random value
+    let cumulative = 0;
+    for (const option of options) {
+        cumulative += option.weight;
+        if (random <= cumulative) {
+            return option.value;
+        }
+    }
+    // Fallback (should not reach here due to floating point precision)
+    return options[options.length - 1].value;
+}
+/**
+ * Epsilon-greedy decision strategy
+ *
+ * With probability epsilon, select a random option (exploration).
+ * Otherwise, select the best option by score (exploitation).
+ *
+ * @example
+ * ```ts
+ * import { decideEpsilonGreedy } from 'ai-experiments'
+ *
+ * const result = await decideEpsilonGreedy({
+ *   options: ['model-a', 'model-b', 'model-c'],
+ *   score: async (model) => await evaluateModel(model),
+ *   epsilon: 0.1, // 10% exploration, 90% exploitation
+ * })
+ * ```
+ */
+export async function decideEpsilonGreedy(options) {
+    const { epsilon, options: choices, score, context } = options;
+    if (epsilon < 0 || epsilon > 1) {
+        throw new Error('Epsilon must be between 0 and 1');
+    }
+    // Exploration: random selection
+    if (Math.random() < epsilon) {
+        const randomIndex = Math.floor(Math.random() * choices.length);
+        const selected = choices[randomIndex];
+        const selectedScore = await score(selected);
+        track({
+            type: 'decision.made',
+            timestamp: new Date(),
+            data: {
+                context,
+                strategy: 'epsilon-greedy-explore',
+                epsilon,
+                selectedScore,
+            },
+        });
+        return {
+            selected,
+            score: selectedScore,
+        };
+    }
+    // Exploitation: best option
+    const result = await decide({ options: choices, score, context });
+    track({
+        type: 'decision.made',
+        timestamp: new Date(),
+        data: {
+            context,
+            strategy: 'epsilon-greedy-exploit',
+            epsilon,
+            selectedScore: result.score,
+        },
+    });
+    return result;
+}
+/**
+ * Thompson sampling decision strategy
+ *
+ * Bayesian approach to balancing exploration and exploitation.
+ * Each option has a Beta distribution representing our belief about its true score.
+ *
+ * @example
+ * ```ts
+ * import { decideThompsonSampling } from 'ai-experiments'
+ *
+ * // Track successes and failures for each option
+ * const priors = {
+ *   'variant-a': { alpha: 10, beta: 5 },  // 10 successes, 5 failures
+ *   'variant-b': { alpha: 8, beta: 3 },   // 8 successes, 3 failures
+ *   'variant-c': { alpha: 2, beta: 2 },   // 2 successes, 2 failures (uncertain)
+ * }
+ *
+ * const result = decideThompsonSampling(['variant-a', 'variant-b', 'variant-c'], priors)
+ * // More likely to select 'variant-b' (higher rate) but will sometimes explore 'variant-c'
+ * ```
+ */
+export function decideThompsonSampling(options, priors) {
+    if (options.length === 0) {
+        throw new Error('Cannot decide with empty options');
+    }
+    // Sample from Beta distribution for each option
+    const samples = options.map((option) => {
+        const { alpha, beta } = priors[option];
+        return {
+            option,
+            sample: sampleBeta(alpha, beta),
+        };
+    });
+    // Select option with highest sample
+    const best = samples.reduce((prev, current) => current.sample > prev.sample ? current : prev);
+    track({
+        type: 'decision.made',
+        timestamp: new Date(),
+        data: {
+            strategy: 'thompson-sampling',
+            selected: best.option,
+            sample: best.sample,
+            priors: priors[best.option],
+        },
+    });
+    return best.option;
+}
+/**
+ * Sample from Beta distribution using the ratio of two Gamma distributions
+ */
+function sampleBeta(alpha, beta) {
+    const x = sampleGamma(alpha, 1);
+    const y = sampleGamma(beta, 1);
+    return x / (x + y);
+}
+/**
+ * Sample from Gamma distribution using Marsaglia and Tsang method
+ */
+function sampleGamma(shape, scale) {
+    // Simple implementation for shape >= 1
+    if (shape < 1) {
+        // Use the property: Gamma(a) = Gamma(a+1) * U^(1/a)
+        return sampleGamma(shape + 1, scale) * Math.pow(Math.random(), 1 / shape);
+    }
+    const d = shape - 1 / 3;
+    const c = 1 / Math.sqrt(9 * d);
+    while (true) {
+        let x;
+        let v;
+        do {
+            x = randomNormal();
+            v = 1 + c * x;
+        } while (v <= 0);
+        v = v * v * v;
+        const u = Math.random();
+        if (u < 1 - 0.0331 * x * x * x * x) {
+            return d * v * scale;
+        }
+        if (Math.log(u) < 0.5 * x * x + d * (1 - v + Math.log(v))) {
+            return d * v * scale;
+        }
+    }
+}
+/**
+ * Sample from standard normal distribution using Box-Muller transform
+ */
+function randomNormal() {
+    const u1 = Math.random();
+    const u2 = Math.random();
+    return Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+}
+/**
+ * Upper Confidence Bound (UCB) decision strategy
+ *
+ * Select the option with the highest upper confidence bound.
+ * Balances exploration and exploitation using confidence intervals.
+ *
+ * @example
+ * ```ts
+ * import { decideUCB } from 'ai-experiments'
+ *
+ * const stats = {
+ *   'variant-a': { mean: 0.85, count: 100 },
+ *   'variant-b': { mean: 0.82, count: 50 },  // Less data, higher uncertainty
+ *   'variant-c': { mean: 0.78, count: 10 },  // Very uncertain
+ * }
+ *
+ * const result = decideUCB(['variant-a', 'variant-b', 'variant-c'], stats, {
+ *   explorationFactor: 2.0,
+ *   totalCount: 160,
+ * })
+ * // Might select variant-c to explore more, despite lower mean
+ * ```
+ */
+export function decideUCB(options, stats, config) {
+    const { explorationFactor, totalCount } = config;
+    if (options.length === 0) {
+        throw new Error('Cannot decide with empty options');
+    }
+    // Calculate UCB for each option
+    const ucbScores = options.map((option) => {
+        const { mean, count } = stats[option];
+        // UCB = mean + c * sqrt(ln(N) / n)
+        const explorationBonus = explorationFactor * Math.sqrt(Math.log(totalCount) / Math.max(count, 1));
+        return {
+            option,
+            ucb: mean + explorationBonus,
+            mean,
+            count,
+        };
+    });
+    // Select option with highest UCB
+    const best = ucbScores.reduce((prev, current) => (current.ucb > prev.ucb ? current : prev));
+    track({
+        type: 'decision.made',
+        timestamp: new Date(),
+        data: {
+            strategy: 'ucb',
+            selected: best.option,
+            ucb: best.ucb,
+            mean: best.mean,
+            count: best.count,
+            explorationFactor,
+        },
+    });
+    return best.option;
+}
+//# sourceMappingURL=decide.js.map

package/dist/decide.js.map

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

package/dist/experiment.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Experiment execution and management
+ */
+import type { ExperimentConfig, ExperimentSummary, RunExperimentOptions, ExperimentVariant } from './types.js';
+/**
+ * Create and run an A/B experiment with multiple variants
+ *
+ * @example
+ * ```ts
+ * import { Experiment } from 'ai-experiments'
+ *
+ * const results = await Experiment({
+ *   id: 'prompt-comparison',
+ *   name: 'Prompt Engineering Test',
+ *   variants: [
+ *     {
+ *       id: 'baseline',
+ *       name: 'Baseline Prompt',
+ *       config: { prompt: 'Summarize this text.' },
+ *     },
+ *     {
+ *       id: 'detailed',
+ *       name: 'Detailed Prompt',
+ *       config: { prompt: 'Provide a comprehensive summary...' },
+ *     },
+ *   ],
+ *   execute: async (config) => {
+ *     return await ai.generate({ prompt: config.prompt })
+ *   },
+ *   metric: (result) => result.quality_score,
+ * })
+ *
+ * console.log('Best variant:', results.bestVariant)
+ * ```
+ */
+export declare function Experiment<TConfig = unknown, TResult = unknown>(config: ExperimentConfig<TConfig, TResult>, options?: RunExperimentOptions): Promise<ExperimentSummary<TResult>>;
+/**
+ * Helper to create experiment variants from a parameter grid
+ *
+ * @example
+ * ```ts
+ * const variants = createVariantsFromGrid({
+ *   temperature: [0.3, 0.7, 1.0],
+ *   model: ['sonnet', 'opus'],
+ *   maxTokens: [100, 500],
+ * })
+ * // Returns 12 variants (3 * 2 * 2 combinations)
+ * ```
+ */
+export declare function createVariantsFromGrid<T extends Record<string, unknown[]>>(grid: T): ExperimentVariant<{
+    [K in keyof T]: T[K][number];
+}>[];
+//# 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":"AAAA;;GAEG;AAGH,OAAO,KAAK,EACV,gBAAgB,EAGhB,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EAClB,MAAM,YAAY,CAAA;AAGnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,UAAU,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EACnE,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,EAC1C,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAwHrC;AA8ID;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,EACxE,IAAI,EAAE,CAAC,GACN,iBAAiB,CAAC;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;CAAE,CAAC,EAAE,CAkBvD"}

package/dist/experiment.js

@@ -0,0 +1,292 @@
+/**
+ * Experiment execution and management
+ */
+import { randomUUID } from 'crypto';
+import { track } from './tracking.js';
+/**
+ * Create and run an A/B experiment with multiple variants
+ *
+ * @example
+ * ```ts
+ * import { Experiment } from 'ai-experiments'
+ *
+ * const results = await Experiment({
+ *   id: 'prompt-comparison',
+ *   name: 'Prompt Engineering Test',
+ *   variants: [
+ *     {
+ *       id: 'baseline',
+ *       name: 'Baseline Prompt',
+ *       config: { prompt: 'Summarize this text.' },
+ *     },
+ *     {
+ *       id: 'detailed',
+ *       name: 'Detailed Prompt',
+ *       config: { prompt: 'Provide a comprehensive summary...' },
+ *     },
+ *   ],
+ *   execute: async (config) => {
+ *     return await ai.generate({ prompt: config.prompt })
+ *   },
+ *   metric: (result) => result.quality_score,
+ * })
+ *
+ * console.log('Best variant:', results.bestVariant)
+ * ```
+ */
+export async function Experiment(config, options = {}) {
+    const { parallel = true, maxConcurrency, stopOnError = false, context: contextData, onVariantStart, onVariantComplete, onVariantError, } = options;
+    const experimentStartTime = new Date();
+    // Track experiment start
+    track({
+        type: 'experiment.start',
+        timestamp: experimentStartTime,
+        data: {
+            experimentId: config.id,
+            experimentName: config.name,
+            variantCount: config.variants.length,
+            parallel,
+            ...config.metadata,
+        },
+    });
+    const results = [];
+    // Execute variants
+    if (parallel) {
+        // Parallel execution with optional concurrency limit
+        const executeVariant = async (variant) => {
+            return runVariant(config, variant, contextData, {
+                onVariantStart,
+                onVariantComplete,
+                onVariantError,
+            });
+        };
+        if (maxConcurrency && maxConcurrency > 0) {
+            // Execute with concurrency limit
+            const chunks = chunkArray(config.variants, maxConcurrency);
+            for (const chunk of chunks) {
+                const chunkResults = await Promise.all(chunk.map(executeVariant));
+                results.push(...chunkResults);
+                // Stop on first error if configured
+                if (stopOnError && chunkResults.some((r) => !r.success)) {
+                    break;
+                }
+            }
+        }
+        else {
+            // Execute all in parallel
+            const allResults = await Promise.all(config.variants.map(executeVariant));
+            results.push(...allResults);
+        }
+    }
+    else {
+        // Sequential execution
+        for (const variant of config.variants) {
+            const result = await runVariant(config, variant, contextData, {
+                onVariantStart,
+                onVariantComplete,
+                onVariantError,
+            });
+            results.push(result);
+            // Stop on first error if configured
+            if (stopOnError && !result.success) {
+                break;
+            }
+        }
+    }
+    const experimentEndTime = new Date();
+    const totalDuration = experimentEndTime.getTime() - experimentStartTime.getTime();
+    // Find best variant by metric
+    let bestVariant;
+    const successfulResults = results.filter((r) => r.success && r.metricValue !== undefined);
+    if (successfulResults.length > 0) {
+        const best = successfulResults.reduce((prev, current) => (current.metricValue ?? -Infinity) > (prev.metricValue ?? -Infinity) ? current : prev);
+        bestVariant = {
+            variantId: best.variantId,
+            variantName: best.variantName,
+            metricValue: best.metricValue,
+        };
+    }
+    const summary = {
+        experimentId: config.id,
+        experimentName: config.name,
+        results,
+        bestVariant,
+        totalDuration,
+        successCount: results.filter((r) => r.success).length,
+        failureCount: results.filter((r) => !r.success).length,
+        startedAt: experimentStartTime,
+        completedAt: experimentEndTime,
+    };
+    // Track experiment completion
+    track({
+        type: 'experiment.complete',
+        timestamp: experimentEndTime,
+        data: {
+            experimentId: config.id,
+            experimentName: config.name,
+            successCount: summary.successCount,
+            failureCount: summary.failureCount,
+            totalDuration,
+            bestVariant: bestVariant?.variantId,
+            ...config.metadata,
+        },
+    });
+    return summary;
+}
+/**
+ * Run a single variant
+ */
+async function runVariant(config, variant, contextData, callbacks) {
+    const runId = randomUUID();
+    const startTime = new Date();
+    const context = {
+        experimentId: config.id,
+        variantId: variant.id,
+        runId,
+        startedAt: startTime,
+        data: contextData,
+    };
+    // Track variant start
+    track({
+        type: 'variant.start',
+        timestamp: startTime,
+        data: {
+            experimentId: config.id,
+            variantId: variant.id,
+            variantName: variant.name,
+            runId,
+        },
+    });
+    callbacks.onVariantStart?.(variant.id, variant.name);
+    try {
+        // Execute the variant
+        const result = await config.execute(variant.config, context);
+        const endTime = new Date();
+        const duration = endTime.getTime() - startTime.getTime();
+        // Compute metric if provided
+        let metricValue;
+        if (config.metric) {
+            metricValue = await config.metric(result);
+            track({
+                type: 'metric.computed',
+                timestamp: new Date(),
+                data: {
+                    experimentId: config.id,
+                    variantId: variant.id,
+                    runId,
+                    metricValue,
+                },
+            });
+        }
+        const experimentResult = {
+            experimentId: config.id,
+            variantId: variant.id,
+            variantName: variant.name,
+            runId,
+            result,
+            metricValue,
+            duration,
+            startedAt: startTime,
+            completedAt: endTime,
+            success: true,
+        };
+        // Track variant completion
+        track({
+            type: 'variant.complete',
+            timestamp: endTime,
+            data: {
+                experimentId: config.id,
+                variantId: variant.id,
+                variantName: variant.name,
+                runId,
+                duration,
+                metricValue,
+                success: true,
+            },
+        });
+        callbacks.onVariantComplete?.(experimentResult);
+        return experimentResult;
+    }
+    catch (error) {
+        const endTime = new Date();
+        const duration = endTime.getTime() - startTime.getTime();
+        const err = error instanceof Error ? error : new Error(String(error));
+        // Track variant error
+        track({
+            type: 'variant.error',
+            timestamp: endTime,
+            data: {
+                experimentId: config.id,
+                variantId: variant.id,
+                variantName: variant.name,
+                runId,
+                duration,
+                error: err.message,
+                stack: err.stack,
+            },
+        });
+        callbacks.onVariantError?.(variant.id, err);
+        return {
+            experimentId: config.id,
+            variantId: variant.id,
+            variantName: variant.name,
+            runId,
+            result: undefined,
+            duration,
+            startedAt: startTime,
+            completedAt: endTime,
+            error: err,
+            success: false,
+        };
+    }
+}
+/**
+ * Split array into chunks
+ */
+function chunkArray(array, size) {
+    const chunks = [];
+    for (let i = 0; i < array.length; i += size) {
+        chunks.push(array.slice(i, i + size));
+    }
+    return chunks;
+}
+/**
+ * Helper to create experiment variants from a parameter grid
+ *
+ * @example
+ * ```ts
+ * const variants = createVariantsFromGrid({
+ *   temperature: [0.3, 0.7, 1.0],
+ *   model: ['sonnet', 'opus'],
+ *   maxTokens: [100, 500],
+ * })
+ * // Returns 12 variants (3 * 2 * 2 combinations)
+ * ```
+ */
+export function createVariantsFromGrid(grid) {
+    const keys = Object.keys(grid);
+    const values = keys.map((k) => grid[k]);
+    // Generate all combinations
+    const combinations = cartesianProduct(values);
+    return combinations.map((combo, index) => {
+        const config = Object.fromEntries(keys.map((key, i) => [key, combo[i]]));
+        return {
+            id: `variant-${index}`,
+            name: keys.map((k, i) => `${String(k)}=${combo[i]}`).join(', '),
+            config,
+        };
+    });
+}
+/**
+ * Cartesian product helper
+ */
+function cartesianProduct(arrays) {
+    if (arrays.length === 0)
+        return [[]];
+    if (arrays.length === 1)
+        return arrays[0].map((x) => [x]);
+    const [first, ...rest] = arrays;
+    const restProduct = cartesianProduct(rest);
+    return first.flatMap((x) => restProduct.map((arr) => [x, ...arr]));
+}
+//# sourceMappingURL=experiment.js.map