ai-experiments 0.1.0 → 2.0.1

package/dist/cartesian.js

@@ -0,0 +1,216 @@
+/**
+ * Cartesian product utilities for parameter exploration
+ */
+/**
+ * Generate cartesian product of parameter sets
+ *
+ * Takes an object where each key maps to an array of possible values,
+ * and returns all possible combinations as an array of objects.
+ *
+ * @example
+ * ```ts
+ * import { cartesian } from 'ai-experiments'
+ *
+ * const combinations = cartesian({
+ *   model: ['sonnet', 'opus', 'gpt-4o'],
+ *   temperature: [0.3, 0.7, 1.0],
+ *   maxTokens: [100, 500, 1000],
+ * })
+ *
+ * // Returns 27 combinations (3 * 3 * 3):
+ * // [
+ * //   { model: 'sonnet', temperature: 0.3, maxTokens: 100 },
+ * //   { model: 'sonnet', temperature: 0.3, maxTokens: 500 },
+ * //   { model: 'sonnet', temperature: 0.3, maxTokens: 1000 },
+ * //   { model: 'sonnet', temperature: 0.7, maxTokens: 100 },
+ * //   ...
+ * // ]
+ *
+ * // Use with experiments:
+ * const variants = combinations.map((config, i) => ({
+ *   id: `variant-${i}`,
+ *   name: `${config.model} T=${config.temperature} max=${config.maxTokens}`,
+ *   config,
+ * }))
+ * ```
+ */
+export function cartesian(params) {
+    const keys = Object.keys(params);
+    const values = keys.map((k) => params[k]);
+    // Handle empty input
+    if (keys.length === 0) {
+        return [];
+    }
+    // Handle single parameter
+    if (keys.length === 1) {
+        const key = keys[0];
+        return values[0].map((val) => ({ [key]: val }));
+    }
+    // Generate all combinations using recursive helper
+    const combinations = cartesianProduct(values);
+    // Map back to objects
+    return combinations.map((combo) => {
+        const obj = {};
+        keys.forEach((key, i) => {
+            obj[key] = combo[i];
+        });
+        return obj;
+    });
+}
+/**
+ * Recursive cartesian product implementation
+ */
+function cartesianProduct(arrays) {
+    if (arrays.length === 0)
+        return [[]];
+    const [first, ...rest] = arrays;
+    // Base case: single array
+    if (rest.length === 0) {
+        return first.map((x) => [x]);
+    }
+    // Recursive case
+    const restProduct = cartesianProduct(rest);
+    const result = [];
+    for (const x of first) {
+        for (const restCombo of restProduct) {
+            result.push([x, ...restCombo]);
+        }
+    }
+    return result;
+}
+/**
+ * Generate a grid of parameter combinations with filtering
+ *
+ * Similar to cartesian(), but allows filtering out invalid combinations.
+ *
+ * @example
+ * ```ts
+ * import { cartesianFilter } from 'ai-experiments'
+ *
+ * const combinations = cartesianFilter(
+ *   {
+ *     model: ['sonnet', 'opus'],
+ *     temperature: [0.3, 0.7, 1.0],
+ *     maxTokens: [100, 500],
+ *   },
+ *   // Filter out combinations where opus uses high temperature
+ *   (combo) => !(combo.model === 'opus' && combo.temperature > 0.7)
+ * )
+ * ```
+ */
+export function cartesianFilter(params, filter) {
+    const allCombinations = cartesian(params);
+    return allCombinations.filter(filter);
+}
+/**
+ * Generate a random sample from the cartesian product
+ *
+ * Useful when the full cartesian product is too large to test all combinations.
+ *
+ * @example
+ * ```ts
+ * import { cartesianSample } from 'ai-experiments'
+ *
+ * // Full product would be 1000 combinations (10 * 10 * 10)
+ * // Sample just 20 random combinations
+ * const sample = cartesianSample(
+ *   {
+ *     param1: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+ *     param2: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+ *     param3: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+ *   },
+ *   20
+ * )
+ * ```
+ */
+export function cartesianSample(params, sampleSize, options = {}) {
+    const { unique = true } = options;
+    // Generate all combinations first
+    const allCombinations = cartesian(params);
+    // If sample size is larger than available combinations, return all
+    if (sampleSize >= allCombinations.length) {
+        return allCombinations;
+    }
+    // Shuffle and take first n items
+    const shuffled = [...allCombinations];
+    // Simple Fisher-Yates shuffle
+    for (let i = shuffled.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+    }
+    return shuffled.slice(0, sampleSize);
+}
+/**
+ * Count the total number of combinations without generating them
+ *
+ * Useful for checking if cartesian product is feasible before generating.
+ *
+ * @example
+ * ```ts
+ * import { cartesianCount } from 'ai-experiments'
+ *
+ * const count = cartesianCount({
+ *   model: ['sonnet', 'opus', 'gpt-4o'],
+ *   temperature: [0.3, 0.5, 0.7, 0.9],
+ *   maxTokens: [100, 500, 1000, 2000],
+ * })
+ * // Returns 48 (3 * 4 * 4)
+ *
+ * if (count > 100) {
+ *   console.log('Too many combinations, use cartesianSample instead')
+ * }
+ * ```
+ */
+export function cartesianCount(params) {
+    const keys = Object.keys(params);
+    if (keys.length === 0)
+        return 0;
+    return keys.reduce((total, key) => {
+        const arr = params[key];
+        return total * (arr?.length ?? 0);
+    }, 1);
+}
+/**
+ * Generate cartesian product with labels for each dimension
+ *
+ * Returns combinations with additional metadata about which dimension each value came from.
+ *
+ * @example
+ * ```ts
+ * import { cartesianWithLabels } from 'ai-experiments'
+ *
+ * const labeled = cartesianWithLabels({
+ *   model: ['sonnet', 'opus'],
+ *   temperature: [0.3, 0.7],
+ * })
+ * // [
+ * //   { values: { model: 'sonnet', temperature: 0.3 }, labels: { model: 0, temperature: 0 } },
+ * //   { values: { model: 'sonnet', temperature: 0.7 }, labels: { model: 0, temperature: 1 } },
+ * //   { values: { model: 'opus', temperature: 0.3 }, labels: { model: 1, temperature: 0 } },
+ * //   { values: { model: 'opus', temperature: 0.7 }, labels: { model: 1, temperature: 1 } },
+ * // ]
+ * ```
+ */
+export function cartesianWithLabels(params) {
+    const keys = Object.keys(params);
+    const values = keys.map((k) => params[k]);
+    if (keys.length === 0) {
+        return [];
+    }
+    const combinations = cartesianProduct(values);
+    return combinations.map((combo) => {
+        const valuesObj = {};
+        const labelsObj = {};
+        keys.forEach((key, i) => {
+            const value = combo[i];
+            valuesObj[key] = value;
+            const arr = params[key];
+            labelsObj[key] = arr ? arr.indexOf(value) : -1;
+        });
+        return {
+            values: valuesObj,
+            labels: labelsObj,
+        };
+    });
+}
+//# sourceMappingURL=cartesian.js.map

package/dist/cartesian.js.map

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

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,EAC5B,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CA2C5B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,OAAO,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GAC3C,CAAC,CA0BH;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,CA6C5B;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,CA+BH;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"}