ai-experiments 2.3.0 → 2.4.0

package/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> ai-experiments@2.3.0 build /Users/nathanclevenger/projects/primitives.org.ai/packages/ai-experiments
+> tsc
+

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # ai-experiments
 
+## 2.4.0
+
+### Patch Changes
+
+- Updated dependencies [4d58f5f]
+  - ai-functions@2.4.0
+  - ai-database@2.4.0
+
 ## 2.3.0
 
 ### Patch Changes

package/dist/cartesian.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Cartesian product utilities for parameter exploration
+ */
+import type { CartesianParams, CartesianResult } from './types.js';
+/**
+ * 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 declare function cartesian<T extends CartesianParams>(params: T): CartesianResult<T>;
+/**
+ * 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 declare function cartesianFilter<T extends CartesianParams>(params: T, filter: (combo: {
+    [K in keyof T]: T[K][number];
+}) => boolean): CartesianResult<T>;
+/**
+ * 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 declare function cartesianSample<T extends CartesianParams>(params: T, sampleSize: number, options?: {
+    /** Random seed for reproducibility */
+    seed?: number;
+    /** Whether to sample without replacement (default: true) */
+    unique?: boolean;
+}): CartesianResult<T>;
+/**
+ * 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 declare function cartesianCount<T extends CartesianParams>(params: T): number;
+/**
+ * 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 declare function cartesianWithLabels<T extends CartesianParams>(params: T): Array<{
+    values: {
+        [K in keyof T]: T[K][number];
+    };
+    labels: {
+        [K in keyof T]: number;
+    };
+}>;
+//# sourceMappingURL=cartesian.d.ts.map

package/dist/cartesian.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cartesian.d.ts","sourceRoot":"","sources":["../src/cartesian.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,eAAe,EAAE,MAAM,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CA0BlF;AA4BD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,eAAe,EACvD,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,CAAC,KAAK,EAAE;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;CAAE,KAAK,OAAO,GAC3D,eAAe,CAAC,CAAC,CAAC,CAGpB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,eAAe,EACvD,MAAM,EAAE,CAAC,EACT,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IACP,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4DAA4D;IAC5D,MAAM,CAAC,EAAE,OAAO,CAAA;CACZ,GACL,eAAe,CAAC,CAAC,CAAC,CAqBpB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,eAAe,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,CAS3E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,eAAe,EAC3D,MAAM,EAAE,CAAC,GACR,KAAK,CAAC;IACP,MAAM,EAAE;SAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;KAAE,CAAA;IACxC,MAAM,EAAE;SAAG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM;KAAE,CAAA;CACnC,CAAC,CA0BD"}

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/clickhouse-storage.d.ts

@@ -0,0 +1,227 @@
+/**
+ * ClickHouse storage backend for AI experiments.
+ *
+ * Migrated (per [ADR-0003](../../../docs/adr/0003-storage-strategy-pg-clickhouse-default.md))
+ * from the standalone embedded `chdb` adapter to the canonical
+ * `ClickHouseProvider` from `ai-database`. Experiment runs are recorded as
+ * SVO Actions on the canonical `actions` table:
+ *
+ * - `verb` — event type (e.g. `variant.complete`)
+ * - `subject` — `experimentId`
+ * - `object` — `variantId`
+ * - `roles` — `{ runId }` (other named roles can be carried here)
+ * - `data` — JSON payload (`experimentName`, `variantName`, `dimensions`,
+ *    `runId`, `success`, `durationMs`, `result`, `metricName`,
+ *    `metricValue`, `errorMessage`, `errorStack`, `metadata`)
+ * - `status` — `'completed'` for successful runs, `'failed'` otherwise
+ *
+ * Writes go through {@link ClickHouseProvider.recordAction} (and
+ * {@link ClickHouseProvider.commitBatch} when bulk-storing). Aggregations
+ * use {@link ClickHouseProvider.analyticsQuery} against the `actions` table
+ * with `JSONExtract*` against the `data` column. This is the **option (c)
+ * hybrid** approach from the migration plan: SVO surface for writes, raw
+ * analytical SQL for the experiment-specific aggregations the SVO surface
+ * doesn't expose directly (cartesian grids, time-series rollups,
+ * best-variant selection by metric).
+ *
+ * Deployment shift: the previous `chdb` adapter used embedded ClickHouse
+ * (file-system path). This adapter is HTTP-based — callers wire up a
+ * ClickHouse server (self-hosted or ClickHouse Cloud) via
+ * {@link createClickHouseHttpFetcher}. Tests use a fake fetcher.
+ *
+ * @packageDocumentation
+ */
+import { type ClickHouseHttpFetcher, type ClickHouseProvider } from 'ai-database';
+import type { TrackingBackend, TrackingEvent, ExperimentResult } from './types.js';
+/** Options for {@link ClickHouseExperimentStorage}. */
+export interface ClickHouseExperimentStorageOptions {
+    /** HTTP fetcher (typically constructed via `createClickHouseHttpFetcher`). */
+    fetcher: ClickHouseHttpFetcher;
+    /**
+     * ClickHouse database. Must already exist (or call
+     * {@link bootstrapExperimentsSchema}).
+     *
+     * @default 'aidb'
+     */
+    database?: string;
+    /**
+     * Namespace partition for experiment events.
+     *
+     * @default 'experiments'
+     */
+    namespace?: string;
+    /**
+     * Whether to bootstrap the canonical schema (`things`/`actions`/`verbs`)
+     * before the first write.
+     *
+     * @default false
+     */
+    autoBootstrap?: boolean;
+}
+/**
+ * Backwards-compat alias for the prior `ChdbStorageOptions`. The
+ * `dataPath` and `autoInit` fields are retained as no-ops to ease the
+ * upgrade — they are ignored in favor of HTTP fetcher options.
+ */
+export interface ChdbStorageOptions extends Partial<ClickHouseExperimentStorageOptions> {
+    /** @deprecated Embedded chdb is no longer used; supply `fetcher`. */
+    dataPath?: string;
+    /** @deprecated Replaced by `autoBootstrap`. */
+    autoInit?: boolean;
+}
+/**
+ * ClickHouse-backed experiment storage built on the canonical
+ * {@link ClickHouseProvider} adapter. Implements
+ * {@link TrackingBackend}.
+ *
+ * @example
+ * ```ts
+ * import { configureTracking } from 'ai-experiments'
+ * import { createClickHouseExperimentStorage } from 'ai-experiments/storage'
+ * import { createClickHouseHttpFetcher } from 'ai-database'
+ *
+ * const fetcher = createClickHouseHttpFetcher({
+ *   url: process.env.CLICKHOUSE_URL!,
+ *   username: process.env.CLICKHOUSE_USER,
+ *   password: process.env.CLICKHOUSE_PASSWORD,
+ *   database: 'aidb',
+ * })
+ * const storage = createClickHouseExperimentStorage({ fetcher })
+ *
+ * configureTracking({ backend: storage })
+ *
+ * // Later: analyse results
+ * const best = await storage.getBestVariant('my-experiment')
+ * ```
+ */
+export declare class ClickHouseExperimentStorage implements TrackingBackend {
+    private readonly provider;
+    private readonly fetcher;
+    private readonly database;
+    private readonly namespace;
+    private readonly autoBootstrap;
+    private bootstrapped;
+    private readonly nextEventId;
+    constructor(options: ClickHouseExperimentStorageOptions);
+    /** Underlying canonical CH provider (escape hatch for advanced callers). */
+    getProvider(): ClickHouseProvider;
+    private ensureBootstrap;
+    track(event: TrackingEvent): Promise<void>;
+    flush(): Promise<void>;
+    storeResult(result: ExperimentResult): Promise<void>;
+    /**
+     * Bulk-store results via {@link ClickHouseProvider.commitBatch}. One
+     * HTTP POST per call carries the entire batch as `JSONEachRow`.
+     */
+    storeResults(results: ExperimentResult[]): Promise<void>;
+    /** Quote a SQL string literal — same shape as the canonical adapter. */
+    private quote;
+    /**
+     * Get all experiments seen in the actions table (variant.complete events).
+     */
+    getExperiments(): Promise<Array<{
+        experimentId: string;
+        experimentName: string;
+        variantCount: number;
+        runCount: number;
+        firstRun: string;
+        lastRun: string;
+    }>>;
+    getVariantStats(experimentId: string): Promise<Array<{
+        variantId: string;
+        variantName: string;
+        runCount: number;
+        successCount: number;
+        successRate: number;
+        avgDuration: number;
+        avgMetric: number;
+        minMetric: number;
+        maxMetric: number;
+    }>>;
+    getBestVariant(experimentId: string, options?: {
+        metric?: 'avgMetric' | 'successRate' | 'avgDuration';
+        minimumRuns?: number;
+    }): Promise<{
+        variantId: string;
+        variantName: string;
+        metricValue: number;
+        runCount: number;
+    } | null>;
+    getCartesianAnalysis(experimentId: string, dimension: string): Promise<Array<{
+        dimensionValue: string;
+        runCount: number;
+        avgMetric: number;
+        successRate: number;
+    }>>;
+    getCartesianGrid(experimentId: string, dimensions: string[]): Promise<Array<{
+        dimensions: Record<string, string>;
+        runCount: number;
+        avgMetric: number;
+        successRate: number;
+    }>>;
+    getTimeSeries(experimentId: string, options?: {
+        interval?: 'hour' | 'day' | 'week';
+        variantId?: string;
+    }): Promise<Array<{
+        period: string;
+        runCount: number;
+        avgMetric: number;
+        successRate: number;
+    }>>;
+    getEvents(experimentId: string, options?: {
+        eventType?: string;
+        variantId?: string;
+        limit?: number;
+    }): Promise<TrackingEvent[]>;
+    /**
+     * Raw analytical SQL pass-through. Routes to
+     * {@link ClickHouseProvider.analyticsQuery}.
+     */
+    query(sql: string): Promise<Array<Record<string, unknown>>>;
+    /** No-op (kept for backwards compat with the chdb-era API). */
+    close(): void;
+}
+/**
+ * Bootstrap the canonical CH schema (`things`, `actions`, `verbs`).
+ * Convenience wrapper around the canonical
+ * {@link bootstrapClickHouseSchema}.
+ */
+export declare function bootstrapExperimentsSchema(fetcher: ClickHouseHttpFetcher, options?: {
+    database?: string;
+}): Promise<void>;
+/**
+ * Create a ClickHouse-backed experiment storage backend.
+ *
+ * @example
+ * ```ts
+ * import { configureTracking } from 'ai-experiments'
+ * import { createClickHouseExperimentStorage } from 'ai-experiments/storage'
+ * import { createClickHouseHttpFetcher } from 'ai-database'
+ *
+ * const fetcher = createClickHouseHttpFetcher({
+ *   url: process.env.CLICKHOUSE_URL!,
+ *   username: process.env.CLICKHOUSE_USER,
+ *   password: process.env.CLICKHOUSE_PASSWORD,
+ *   database: 'aidb',
+ * })
+ * const storage = createClickHouseExperimentStorage({ fetcher })
+ *
+ * configureTracking({ backend: storage })
+ *
+ * const best = await storage.getBestVariant('my-experiment')
+ * ```
+ */
+export declare function createClickHouseExperimentStorage(options: ClickHouseExperimentStorageOptions): ClickHouseExperimentStorage;
+/**
+ * @deprecated Renamed to {@link ClickHouseExperimentStorage}. The class
+ * now wraps the canonical `ClickHouseProvider` from `ai-database` instead
+ * of embedded chdb. The old `dataPath` constructor option is ignored —
+ * supply a `fetcher` instead.
+ */
+export declare const ChdbStorage: typeof ClickHouseExperimentStorage;
+export type ChdbStorage = ClickHouseExperimentStorage;
+/**
+ * @deprecated Renamed to {@link createClickHouseExperimentStorage}.
+ */
+export declare function createChdbBackend(options: ClickHouseExperimentStorageOptions): ClickHouseExperimentStorage;
+//# sourceMappingURL=clickhouse-storage.d.ts.map

package/dist/clickhouse-storage.d.ts.map

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