@hypequery/clickhouse 1.6.0 → 1.6.2

package/dist/dataset/helpers.js

@@ -0,0 +1,189 @@
+/**
+ * Dataset Helper Functions
+ *
+ * Provides declarative helper functions for defining dimensions and metrics:
+ * - dimension.string(), dimension.number(), dimension.date(), dimension.boolean()
+ * - metric.count(), metric.sum(), metric.avg(), metric.min(), metric.max(), metric.countDistinct(), metric.custom()
+ */
+import { sql } from './sql-tag.js';
+/**
+ * Create a dimension definition helper
+ */
+function createDimensionHelper(type) {
+    return (columnOrExpression, options) => {
+        return {
+            sql: columnOrExpression,
+            type,
+            description: options.description,
+            examples: options.examples,
+            join: options.join,
+        };
+    };
+}
+/**
+ * Dimension helper namespace
+ *
+ * @example
+ * ```typescript
+ * dimensions: {
+ *   region: dimension.string('region', {
+ *     description: 'Geographic region',
+ *     examples: ['US', 'EU', 'APAC']
+ *   }),
+ *   orderDate: dimension.date(sql`DATE(created_at)`, {
+ *     description: 'Order date'
+ *   }),
+ *   amount: dimension.number('amount', {
+ *     description: 'Order amount'
+ *   })
+ * }
+ * ```
+ */
+export const dimension = {
+    /**
+     * Create a string dimension
+     */
+    string: createDimensionHelper('string'),
+    /**
+     * Create a number dimension
+     */
+    number: createDimensionHelper('number'),
+    /**
+     * Create a date dimension
+     */
+    date: createDimensionHelper('date'),
+    /**
+     * Create a boolean dimension
+     */
+    boolean: createDimensionHelper('boolean'),
+};
+/**
+ * Create a metric definition helper
+ */
+function createMetricHelper(type) {
+    return (columnOrExpression, options) => {
+        return {
+            type,
+            sql: columnOrExpression,
+            description: options.description,
+            format: options.format,
+            join: options.join,
+            allowFanout: options.allowFanout,
+        };
+    };
+}
+/**
+ * Metric helper namespace
+ *
+ * @example
+ * ```typescript
+ * metrics: {
+ *   revenue: metric.sum('amount', {
+ *     description: 'Total revenue',
+ *     format: 'currency'
+ *   }),
+ *   orderCount: metric.count({
+ *     description: 'Total number of orders'
+ *   }),
+ *   avgOrderValue: metric.avg('total_amount', {
+ *     description: 'Average order value',
+ *     format: 'currency'
+ *   }),
+ *   revenuePerCustomer: metric.custom(
+ *     sql`sum(total_amount) / count(DISTINCT customer_id)`,
+ *     {
+ *       description: 'Average revenue per customer',
+ *       format: 'currency'
+ *     }
+ *   )
+ * }
+ * ```
+ */
+export const metric = {
+    /**
+     * Create a COUNT(*) metric
+     */
+    count: (options) => {
+        return {
+            type: 'count',
+            sql: sql `*`,
+            description: options.description,
+            format: options.format,
+            join: options.join,
+            allowFanout: options.allowFanout,
+        };
+    },
+    /**
+     * Create a SUM() metric
+     */
+    sum: createMetricHelper('sum'),
+    /**
+     * Create an AVG() metric
+     */
+    avg: createMetricHelper('avg'),
+    /**
+     * Create a MIN() metric
+     */
+    min: createMetricHelper('min'),
+    /**
+     * Create a MAX() metric
+     */
+    max: createMetricHelper('max'),
+    /**
+     * Create a COUNT(DISTINCT) metric
+     */
+    countDistinct: createMetricHelper('countDistinct'),
+    /**
+     * Create a custom metric with a SQL expression
+     */
+    custom: createMetricHelper('custom'),
+};
+// =============================================================================
+// VALIDATION HELPERS
+// =============================================================================
+/**
+ * Validate that a dimension definition has required metadata
+ */
+export function validateDimensionDefinition(name, definition) {
+    if (typeof definition === 'string') {
+        // Simple column reference - no validation needed
+        return;
+    }
+    if (typeof definition === 'object' && definition !== null) {
+        const def = definition;
+        if (!def.sql) {
+            throw new Error(`Dimension '${name}' is missing 'sql' property. ` +
+                `Expected a column name (string) or SQLExpression.`);
+        }
+        if (!def.type) {
+            throw new Error(`Dimension '${name}' is missing 'type' property. ` +
+                `Expected: 'string', 'number', 'date', or 'boolean'.`);
+        }
+        if (!def.description) {
+            console.warn(`⚠️  Dimension '${name}' is missing 'description'. ` +
+                `Descriptions help AI agents understand your data.`);
+        }
+    }
+}
+/**
+ * Validate that a metric definition has required metadata
+ */
+export function validateMetricDefinition(name, definition) {
+    if (typeof definition !== 'object' || definition === null) {
+        throw new Error(`Metric '${name}' must be a MetricDefinition object. ` +
+            `Use metric.sum(), metric.count(), etc. helpers.`);
+    }
+    const def = definition;
+    if (!def.type) {
+        throw new Error(`Metric '${name}' is missing 'type' property. ` +
+            `Expected: 'count', 'sum', 'avg', 'min', 'max', 'countDistinct', or 'custom'.`);
+    }
+    if (!def.sql) {
+        throw new Error(`Metric '${name}' is missing 'sql' property. ` +
+            `Expected a column name (string) or SQLExpression.`);
+    }
+    if (!def.description) {
+        console.warn(`⚠️  Metric '${name}' is missing 'description'. ` +
+            `Descriptions help AI agents understand your metrics.`);
+    }
+}

package/dist/dataset/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Dataset API Module
+ *
+ * Provides a declarative API for defining dynamic datasets with:
+ * - Type-safe dimension and metric definitions
+ * - SQL expression support via tagged templates
+ * - Helper functions for common patterns
+ * - Introspection for AI agents
+ * - Full TypeScript type inference
+ *
+ * @module @hypequery/clickhouse/dataset
+ *
+ * @example
+ * ```typescript
+ * import { sql, dimension, metric } from '@hypequery/clickhouse/dataset';
+ *
+ * const datasets = {
+ *   orders: {
+ *     name: 'orders',
+ *     description: 'Customer orders and revenue data',
+ *     table: 'orders',
+ *     dimensions: {
+ *       region: dimension.string('region', {
+ *         description: 'Geographic region',
+ *         examples: ['US', 'EU', 'APAC']
+ *       }),
+ *       date: dimension.date(sql`DATE(created_at)`, {
+ *         description: 'Order date'
+ *       })
+ *     },
+ *     metrics: {
+ *       revenue: metric.sum('amount', {
+ *         description: 'Total revenue',
+ *         format: 'currency'
+ *       }),
+ *       orderCount: metric.count({
+ *         description: 'Number of orders'
+ *       })
+ *     }
+ *   }
+ * };
+ * ```
+ */
+export { sql, isSQLExpression, toSQLString } from './sql-tag.js';
+export type { SQLExpression } from './sql-tag.js';
+export type { DimensionType, SimpleDimension, DimensionDefinition, Dimension, DimensionsMap, MetricAggregationType, MetricFormat, MetricDefinition, MetricsMap, DatasetDefinition, DatasetsMap, TenantConfig, DatasetLimits, FilterOperator, DateRangeValue, FilterValue, FilterDefinition, Filters, SortDirection, OrderByDimension, OrderByMetric, OrderBy, CacheOptions, DatasetQuery, QueryContext, QueryResultMetadata, QueryResult, InferDimensionType, InferMetricType, InferQueryRowType, InferQueryResult, IntrospectedDimension, IntrospectedMetric, IntrospectedDataset, } from './types.js';
+export { dimension, metric } from './helpers.js';
+export type { DimensionOptions, MetricOptions } from './helpers.js';
+export { validateDatasetDefinition, validateDatasets, normalizeDimension, normalizeDimensions, inferDimensionType, getDimensionSQL, getMetricSQL, getDataset, listDatasets, hasDataset, getDimensionNames, getMetricNames, hasDimension, hasMetric, getDimension, getMetric, } from './definition.js';
+export { introspectDimension, introspectMetric, getDatasetSchema, listDatasets as listDatasetSchemas, getAllDatasetSchemas, summarizeDataset, datasetsToJSON, summarizeAllDatasets, } from './introspection.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/dataset/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dataset/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAMH,OAAO,EAAE,GAAG,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACjE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAMlD,YAAY,EAEV,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,SAAS,EACT,aAAa,EAGb,qBAAqB,EACrB,YAAY,EACZ,gBAAgB,EAChB,UAAU,EAGV,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,aAAa,EAGb,cAAc,EACd,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,OAAO,EAGP,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,OAAO,EAGP,YAAY,EAGZ,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,WAAW,EAGX,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAGhB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAMpB,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAMpE,OAAO,EACL,yBAAyB,EACzB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,SAAS,GACV,MAAM,iBAAiB,CAAC;AAMzB,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,IAAI,kBAAkB,EAClC,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACd,oBAAoB,GACrB,MAAM,oBAAoB,CAAC"}

package/dist/dataset/index.js

@@ -0,0 +1,59 @@
+/**
+ * Dataset API Module
+ *
+ * Provides a declarative API for defining dynamic datasets with:
+ * - Type-safe dimension and metric definitions
+ * - SQL expression support via tagged templates
+ * - Helper functions for common patterns
+ * - Introspection for AI agents
+ * - Full TypeScript type inference
+ *
+ * @module @hypequery/clickhouse/dataset
+ *
+ * @example
+ * ```typescript
+ * import { sql, dimension, metric } from '@hypequery/clickhouse/dataset';
+ *
+ * const datasets = {
+ *   orders: {
+ *     name: 'orders',
+ *     description: 'Customer orders and revenue data',
+ *     table: 'orders',
+ *     dimensions: {
+ *       region: dimension.string('region', {
+ *         description: 'Geographic region',
+ *         examples: ['US', 'EU', 'APAC']
+ *       }),
+ *       date: dimension.date(sql`DATE(created_at)`, {
+ *         description: 'Order date'
+ *       })
+ *     },
+ *     metrics: {
+ *       revenue: metric.sum('amount', {
+ *         description: 'Total revenue',
+ *         format: 'currency'
+ *       }),
+ *       orderCount: metric.count({
+ *         description: 'Number of orders'
+ *       })
+ *     }
+ *   }
+ * };
+ * ```
+ */
+// =============================================================================
+// SQL TAGGED TEMPLATE
+// =============================================================================
+export { sql, isSQLExpression, toSQLString } from './sql-tag.js';
+// =============================================================================
+// HELPERS
+// =============================================================================
+export { dimension, metric } from './helpers.js';
+// =============================================================================
+// DEFINITION UTILITIES
+// =============================================================================
+export { validateDatasetDefinition, validateDatasets, normalizeDimension, normalizeDimensions, inferDimensionType, getDimensionSQL, getMetricSQL, getDataset, listDatasets, hasDataset, getDimensionNames, getMetricNames, hasDimension, hasMetric, getDimension, getMetric, } from './definition.js';
+// =============================================================================
+// INTROSPECTION
+// =============================================================================
+export { introspectDimension, introspectMetric, getDatasetSchema, listDatasets as listDatasetSchemas, getAllDatasetSchemas, summarizeDataset, datasetsToJSON, summarizeAllDatasets, } from './introspection.js';

package/dist/dataset/introspection.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Dataset Introspection API
+ *
+ * Provides introspection capabilities for datasets, enabling AI agents
+ * and other tools to understand the structure and metadata of datasets.
+ *
+ * Key functions:
+ * - getDatasetSchema(): Get full schema for a dataset
+ * - listDatasets(): List all available datasets
+ * - introspectDimension(): Get metadata for a specific dimension
+ * - introspectMetric(): Get metadata for a specific metric
+ */
+import type { DatasetDefinition, DatasetsMap, IntrospectedDataset, IntrospectedDimension, IntrospectedMetric } from './types.js';
+/**
+ * Introspect a dimension definition to extract metadata
+ *
+ * @param dimension - Dimension definition (any format)
+ * @returns Introspected dimension metadata
+ */
+export declare function introspectDimension(dimension: DatasetDefinition['dimensions'][string]): IntrospectedDimension;
+/**
+ * Introspect a metric definition to extract metadata
+ *
+ * @param metric - Metric definition
+ * @returns Introspected metric metadata
+ */
+export declare function introspectMetric(metric: DatasetDefinition['metrics'][string]): IntrospectedMetric;
+/**
+ * Get the complete schema for a dataset (for AI agents)
+ *
+ * @param datasets - Map of all dataset definitions
+ * @param datasetName - Name of the dataset to introspect
+ * @returns Introspected dataset schema
+ * @throws Error if dataset not found
+ *
+ * @example
+ * ```typescript
+ * const schema = getDatasetSchema(datasets, 'orders');
+ * console.log(schema.dimensions.region.description);
+ * console.log(schema.metrics.revenue.format);
+ * ```
+ */
+export declare function getDatasetSchema(datasets: DatasetsMap, datasetName: string): IntrospectedDataset;
+/**
+ * List all available datasets
+ *
+ * @param datasets - Map of all dataset definitions
+ * @returns Array of dataset names
+ *
+ * @example
+ * ```typescript
+ * const allDatasets = listDatasets(datasets);
+ * // ['orders', 'customers', 'products']
+ * ```
+ */
+export declare function listDatasets(datasets: DatasetsMap): string[];
+/**
+ * Get introspected schemas for all datasets
+ *
+ * @param datasets - Map of all dataset definitions
+ * @returns Map of dataset names to introspected schemas
+ *
+ * @example
+ * ```typescript
+ * const allSchemas = getAllDatasetSchemas(datasets);
+ * for (const [name, schema] of Object.entries(allSchemas)) {
+ *   console.log(`Dataset: ${name}`);
+ *   console.log(`Description: ${schema.description}`);
+ * }
+ * ```
+ */
+export declare function getAllDatasetSchemas(datasets: DatasetsMap): Record<string, IntrospectedDataset>;
+/**
+ * Generate a human-readable summary of a dataset (for LLMs)
+ *
+ * @param datasets - Map of all dataset definitions
+ * @param datasetName - Name of the dataset to summarize
+ * @returns Markdown-formatted summary
+ *
+ * @example
+ * ```typescript
+ * const summary = summarizeDataset(datasets, 'orders');
+ * console.log(summary);
+ * // # Dataset: orders
+ * // Customer orders and revenue data
+ * //
+ * // ## Dimensions
+ * // - region (string): Geographic region
+ * //   Examples: US, EU, APAC
+ * // ...
+ * ```
+ */
+export declare function summarizeDataset(datasets: DatasetsMap, datasetName: string): string;
+/**
+ * Generate a JSON representation of all datasets (for AI context)
+ *
+ * @param datasets - Map of all dataset definitions
+ * @returns JSON string with all dataset schemas
+ *
+ * @example
+ * ```typescript
+ * const json = datasetsToJSON(datasets);
+ * // Send to LLM as context for query generation
+ * ```
+ */
+export declare function datasetsToJSON(datasets: DatasetsMap): string;
+/**
+ * Get a concise summary of all datasets (for LLM context)
+ *
+ * @param datasets - Map of all dataset definitions
+ * @returns Array of dataset summaries
+ *
+ * @example
+ * ```typescript
+ * const summaries = summarizeAllDatasets(datasets);
+ * // [
+ * //   {
+ * //     name: 'orders',
+ * //     description: 'Customer orders and revenue data',
+ * //     dimensionCount: 5,
+ * //     metricCount: 4
+ * //   },
+ * //   ...
+ * // ]
+ * ```
+ */
+export declare function summarizeAllDatasets(datasets: DatasetsMap): Array<{
+    name: string;
+    description: string;
+    dimensionCount: number;
+    metricCount: number;
+}>;
+//# sourceMappingURL=introspection.d.ts.map

package/dist/dataset/introspection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspection.d.ts","sourceRoot":"","sources":["../../src/dataset/introspection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACX,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAapB;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,GACjD,qBAAqB,CASvB;AAMD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,GAC3C,kBAAkB,CAQpB;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,WAAW,EACrB,WAAW,EAAE,MAAM,GAClB,mBAAmB,CAwBrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,EAAE,CAE5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,WAAW,GACpB,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAQrC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,WAAW,EACrB,WAAW,EAAE,MAAM,GAClB,MAAM,CA0DR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,CAG5D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,WAAW,GACpB,KAAK,CAAC;IACP,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC,CAUD"}

package/dist/dataset/introspection.js

@@ -0,0 +1,239 @@
+/**
+ * Dataset Introspection API
+ *
+ * Provides introspection capabilities for datasets, enabling AI agents
+ * and other tools to understand the structure and metadata of datasets.
+ *
+ * Key functions:
+ * - getDatasetSchema(): Get full schema for a dataset
+ * - listDatasets(): List all available datasets
+ * - introspectDimension(): Get metadata for a specific dimension
+ * - introspectMetric(): Get metadata for a specific metric
+ */
+import { getDataset, listDatasets as listDatasetNames, normalizeDimension, getDimensionSQL, getMetricSQL, } from './definition.js';
+// =============================================================================
+// DIMENSION INTROSPECTION
+// =============================================================================
+/**
+ * Introspect a dimension definition to extract metadata
+ *
+ * @param dimension - Dimension definition (any format)
+ * @returns Introspected dimension metadata
+ */
+export function introspectDimension(dimension) {
+    const normalized = normalizeDimension(dimension);
+    return {
+        type: normalized.type,
+        description: normalized.description || undefined,
+        examples: normalized.examples,
+        sql: getDimensionSQL(dimension),
+    };
+}
+// =============================================================================
+// METRIC INTROSPECTION
+// =============================================================================
+/**
+ * Introspect a metric definition to extract metadata
+ *
+ * @param metric - Metric definition
+ * @returns Introspected metric metadata
+ */
+export function introspectMetric(metric) {
+    return {
+        type: 'number',
+        aggregationType: metric.type,
+        description: metric.description,
+        format: metric.format,
+        sql: getMetricSQL(metric),
+    };
+}
+// =============================================================================
+// DATASET INTROSPECTION
+// =============================================================================
+/**
+ * Get the complete schema for a dataset (for AI agents)
+ *
+ * @param datasets - Map of all dataset definitions
+ * @param datasetName - Name of the dataset to introspect
+ * @returns Introspected dataset schema
+ * @throws Error if dataset not found
+ *
+ * @example
+ * ```typescript
+ * const schema = getDatasetSchema(datasets, 'orders');
+ * console.log(schema.dimensions.region.description);
+ * console.log(schema.metrics.revenue.format);
+ * ```
+ */
+export function getDatasetSchema(datasets, datasetName) {
+    const dataset = getDataset(datasets, datasetName);
+    // Introspect all dimensions
+    const dimensions = {};
+    for (const [name, dimension] of Object.entries(dataset.dimensions)) {
+        dimensions[name] = introspectDimension(dimension);
+    }
+    // Introspect all metrics
+    const metrics = {};
+    for (const [name, metric] of Object.entries(dataset.metrics)) {
+        metrics[name] = introspectMetric(metric);
+    }
+    return {
+        name: dataset.name,
+        description: dataset.description,
+        table: dataset.table,
+        dimensions,
+        metrics,
+        tenantRequired: dataset.tenant?.required,
+        limits: dataset.limits,
+    };
+}
+/**
+ * List all available datasets
+ *
+ * @param datasets - Map of all dataset definitions
+ * @returns Array of dataset names
+ *
+ * @example
+ * ```typescript
+ * const allDatasets = listDatasets(datasets);
+ * // ['orders', 'customers', 'products']
+ * ```
+ */
+export function listDatasets(datasets) {
+    return listDatasetNames(datasets);
+}
+/**
+ * Get introspected schemas for all datasets
+ *
+ * @param datasets - Map of all dataset definitions
+ * @returns Map of dataset names to introspected schemas
+ *
+ * @example
+ * ```typescript
+ * const allSchemas = getAllDatasetSchemas(datasets);
+ * for (const [name, schema] of Object.entries(allSchemas)) {
+ *   console.log(`Dataset: ${name}`);
+ *   console.log(`Description: ${schema.description}`);
+ * }
+ * ```
+ */
+export function getAllDatasetSchemas(datasets) {
+    const schemas = {};
+    for (const name of listDatasetNames(datasets)) {
+        schemas[name] = getDatasetSchema(datasets, name);
+    }
+    return schemas;
+}
+/**
+ * Generate a human-readable summary of a dataset (for LLMs)
+ *
+ * @param datasets - Map of all dataset definitions
+ * @param datasetName - Name of the dataset to summarize
+ * @returns Markdown-formatted summary
+ *
+ * @example
+ * ```typescript
+ * const summary = summarizeDataset(datasets, 'orders');
+ * console.log(summary);
+ * // # Dataset: orders
+ * // Customer orders and revenue data
+ * //
+ * // ## Dimensions
+ * // - region (string): Geographic region
+ * //   Examples: US, EU, APAC
+ * // ...
+ * ```
+ */
+export function summarizeDataset(datasets, datasetName) {
+    const schema = getDatasetSchema(datasets, datasetName);
+    const lines = [];
+    // Header
+    lines.push(`# Dataset: ${schema.name}`);
+    lines.push(schema.description);
+    lines.push('');
+    // Dimensions
+    lines.push('## Dimensions');
+    for (const [name, dimension] of Object.entries(schema.dimensions)) {
+        lines.push(`- ${name} (${dimension.type})${dimension.description ? `: ${dimension.description}` : ''}`);
+        if (dimension.examples && dimension.examples.length > 0) {
+            lines.push(`  Examples: ${dimension.examples.join(', ')}`);
+        }
+    }
+    lines.push('');
+    // Metrics
+    lines.push('## Metrics');
+    for (const [name, metric] of Object.entries(schema.metrics)) {
+        lines.push(`- ${name} (${metric.aggregationType})${metric.description ? `: ${metric.description}` : ''}`);
+        if (metric.format) {
+            lines.push(`  Format: ${metric.format}`);
+        }
+    }
+    lines.push('');
+    // Constraints
+    if (schema.tenantRequired || schema.limits) {
+        lines.push('## Constraints');
+        if (schema.tenantRequired) {
+            lines.push('- Multi-tenancy: Required');
+        }
+        if (schema.limits) {
+            if (schema.limits.maxDimensions) {
+                lines.push(`- Max dimensions: ${schema.limits.maxDimensions}`);
+            }
+            if (schema.limits.maxMetrics) {
+                lines.push(`- Max metrics: ${schema.limits.maxMetrics}`);
+            }
+            if (schema.limits.maxFilters) {
+                lines.push(`- Max filters: ${schema.limits.maxFilters}`);
+            }
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/**
+ * Generate a JSON representation of all datasets (for AI context)
+ *
+ * @param datasets - Map of all dataset definitions
+ * @returns JSON string with all dataset schemas
+ *
+ * @example
+ * ```typescript
+ * const json = datasetsToJSON(datasets);
+ * // Send to LLM as context for query generation
+ * ```
+ */
+export function datasetsToJSON(datasets) {
+    const schemas = getAllDatasetSchemas(datasets);
+    return JSON.stringify(schemas, null, 2);
+}
+/**
+ * Get a concise summary of all datasets (for LLM context)
+ *
+ * @param datasets - Map of all dataset definitions
+ * @returns Array of dataset summaries
+ *
+ * @example
+ * ```typescript
+ * const summaries = summarizeAllDatasets(datasets);
+ * // [
+ * //   {
+ * //     name: 'orders',
+ * //     description: 'Customer orders and revenue data',
+ * //     dimensionCount: 5,
+ * //     metricCount: 4
+ * //   },
+ * //   ...
+ * // ]
+ * ```
+ */
+export function summarizeAllDatasets(datasets) {
+    return listDatasetNames(datasets).map((name) => {
+        const schema = getDatasetSchema(datasets, name);
+        return {
+            name: schema.name,
+            description: schema.description,
+            dimensionCount: Object.keys(schema.dimensions).length,
+            metricCount: Object.keys(schema.metrics).length,
+        };
+    });
+}