ai-experiments 2.3.0 → 2.4.0

package/dist/decide.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Decision making utilities
+ */
+import type { DecideOptions, DecisionResult } from './types.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 declare function decide<T>(options: DecideOptions<T>): Promise<DecisionResult<T>>;
+/**
+ * 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 declare function decideWeighted<T>(options: Array<{
+    value: T;
+    weight: number;
+}>): T;
+/**
+ * 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 declare function decideEpsilonGreedy<T>(options: DecideOptions<T> & {
+    epsilon: number;
+}): Promise<DecisionResult<T>>;
+/**
+ * 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 declare function decideThompsonSampling<T extends string>(options: T[], priors: Record<T, {
+    alpha: number;
+    beta: number;
+}>): T;
+/**
+ * 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 declare function decideUCB<T extends string>(options: T[], stats: Record<T, {
+    mean: number;
+    count: number;
+}>, config: {
+    /** Exploration factor (typically 1-2) */
+    explorationFactor: number;
+    /** Total number of trials across all options */
+    totalCount: number;
+}): T;
+//# sourceMappingURL=decide.d.ts.map

package/dist/decide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decide.d.ts","sourceRoot":"","sources":["../src/decide.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAG/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAsB,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CA2CrF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,CAAC,CA0BjF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAC9C,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAiD5B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,MAAM,EACrD,OAAO,EAAE,CAAC,EAAE,EACZ,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GACjD,CAAC,CA6BH;AAuDD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,EACxC,OAAO,EAAE,CAAC,EAAE,EACZ,KAAK,EAAE,MAAM,CAAC,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,EACjD,MAAM,EAAE;IACN,yCAAyC;IACzC,iBAAiB,EAAE,MAAM,CAAA;IACzB,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAA;CACnB,GACA,CAAC,CAwCH"}

package/dist/decide.js

@@ -0,0 +1,333 @@
+/**
+ * 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 !== undefined && { 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"}