@hypequery/datasets 0.1.0 → 0.2.1

package/dist/semantic-plan.d.ts

@@ -0,0 +1,82 @@
+import type { AggregationType, FieldType, MetricFilter, MetricOrderBy, TimeGrain } from './types.js';
+export type SemanticBinaryOperator = 'add' | 'subtract' | 'multiply' | 'divide';
+export type SemanticFunctionName = 'nullIfZero' | 'coalesce' | 'round' | 'floor' | 'ceil';
+export type SemanticExpression = {
+    kind: 'ref';
+    name: string;
+} | {
+    kind: 'literal';
+    value: string | number | boolean | null;
+} | {
+    kind: 'binary';
+    operator: SemanticBinaryOperator;
+    left: SemanticExpression;
+    right: SemanticExpression;
+} | {
+    kind: 'function';
+    name: SemanticFunctionName;
+    args: SemanticExpression[];
+};
+export interface SemanticDimensionPlan {
+    name: string;
+    field: string;
+    fieldType?: FieldType;
+}
+export interface SemanticAggregationPlan {
+    name: string;
+    aggregation: AggregationType;
+    field: string;
+    filters?: MetricFilter[];
+}
+export interface SemanticGrainPlan {
+    field: string;
+    unit: TimeGrain;
+    output: 'period';
+    timezone?: string;
+    weekStart?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+}
+export type PlanNode = {
+    kind: 'aggregate';
+    source: string;
+    dimensions: SemanticDimensionPlan[];
+    aggregations: SemanticAggregationPlan[];
+    filters: MetricFilter[];
+    grain?: SemanticGrainPlan;
+    orderBy?: MetricOrderBy[];
+    limit?: number;
+    offset?: number;
+    tenant?: {
+        field: string;
+        operator: 'eq';
+        value: string;
+    } | {
+        field: string;
+        operator: 'in';
+        value: string[];
+    };
+} | {
+    kind: 'derive';
+    input: PlanNode;
+    metrics: Array<{
+        name: string;
+        expression: SemanticExpression;
+    }>;
+    orderBy?: MetricOrderBy[];
+    limit?: number;
+    offset?: number;
+};
+export interface SemanticBackendResult<T = Record<string, unknown>> {
+    data: T[];
+    meta?: {
+        timingMs?: number;
+        sql?: string;
+        tenant?: string;
+    };
+}
+export interface SemanticBackend {
+    execute<T = Record<string, unknown>>(plan: PlanNode): Promise<SemanticBackendResult<T>>;
+    explain?(plan: PlanNode): Promise<{
+        sql?: string;
+    }>;
+}
+//# sourceMappingURL=semantic-plan.d.ts.map

package/dist/semantic-plan.d.ts.map

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

package/dist/semantic-plan.js

@@ -0,0 +1 @@
+export {};

package/dist/semantic-planner.d.ts

@@ -0,0 +1,5 @@
+import type { AnyDatasetInstance, DatasetQuery, ExecutionContext, MetricQuery, MetricRef, GrainedMetricRef } from './types.js';
+import type { PlanNode } from './semantic-plan.js';
+export declare function buildDatasetPlan(ds: AnyDatasetInstance, query?: DatasetQuery, context?: ExecutionContext): PlanNode;
+export declare function buildMetricPlan(metric: MetricRef | GrainedMetricRef, query?: MetricQuery, context?: ExecutionContext): PlanNode;
+//# sourceMappingURL=semantic-planner.d.ts.map

package/dist/semantic-planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-planner.d.ts","sourceRoot":"","sources":["../src/semantic-planner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAEhB,WAAW,EACX,SAAS,EACT,gBAAgB,EACjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EACV,QAAQ,EAGT,MAAM,oBAAoB,CAAC;AAgH5B,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,kBAAkB,EACtB,KAAK,GAAE,YAAiB,EACxB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAaV;AAuFD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,GAAE,WAAgB,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAUV"}

package/dist/semantic-planner.js

@@ -0,0 +1,155 @@
+import { getMetricGrain, getMetricRef, } from './utils/metric-handle.js';
+import { validateDatasetQuery } from './dataset-query.js';
+import { isSupportedTimeGrain } from './constants.js';
+import { getRuntimeTenantPredicate } from './utils/tenant-runtime.js';
+function resolveField(ds, field) {
+    const dimension = ds.dimensions[field];
+    if (dimension?.sql) {
+        throw new Error(`Semantic backend plans do not support SQL-backed dimension "${field}". ` +
+            'Use a backend-specific query builder for raw SQL expressions.');
+    }
+    return dimension?.column ?? field;
+}
+function dimensionsForQuery(ds, dimensions = []) {
+    return dimensions.map((name) => ({
+        name,
+        field: resolveField(ds, name),
+        fieldType: ds.dimensions[name]?.fieldType,
+    }));
+}
+function normalizeFilters(ds, filters = []) {
+    return filters.map((filter) => {
+        const resolvedField = ds.filters[filter.field]?.field ?? filter.field;
+        return {
+            ...filter,
+            field: resolveField(ds, resolvedField),
+        };
+    });
+}
+function aggregationForMeasure(ds, name) {
+    const measure = ds.measures[name];
+    if (!measure) {
+        throw new Error(`Unknown measure "${name}" on dataset "${ds.name}".`);
+    }
+    if (measure.sql) {
+        throw new Error(`Semantic backend plans do not support SQL-backed measure "${name}". ` +
+            'Use a backend-specific query builder for raw SQL expressions.');
+    }
+    return {
+        name,
+        aggregation: measure.aggregation,
+        field: resolveField(ds, measure.field),
+        filters: normalizeFilters(ds, measure.filters),
+    };
+}
+function tenantForContext(ds, context) {
+    const tenantPredicate = getRuntimeTenantPredicate(context);
+    if (!tenantPredicate || !ds.tenantKey) {
+        return undefined;
+    }
+    return { field: ds.tenantKey, ...tenantPredicate };
+}
+function grainForQuery(ds, unit) {
+    if (!unit) {
+        return undefined;
+    }
+    if (!ds.timeKey) {
+        throw new Error(`Cannot use grain "${unit}" because dataset "${ds.name}" has no timeKey.`);
+    }
+    if (!isSupportedTimeGrain(unit)) {
+        throw new Error(`Unsupported time grain "${unit}".`);
+    }
+    return {
+        field: ds.timeKey,
+        unit,
+        output: 'period',
+    };
+}
+function aggregatePlan(ds, query, aggregations, context) {
+    return {
+        kind: 'aggregate',
+        source: ds.source,
+        dimensions: dimensionsForQuery(ds, query.dimensions),
+        aggregations,
+        filters: normalizeFilters(ds, query.filters),
+        grain: grainForQuery(ds, query.by),
+        orderBy: query.orderBy,
+        limit: query.limit,
+        offset: query.offset,
+        tenant: tenantForContext(ds, context),
+    };
+}
+export function buildDatasetPlan(ds, query = {}, context) {
+    const validation = validateDatasetQuery(ds, query, context);
+    if (!validation.valid) {
+        throw new Error(`Invalid dataset query: ${validation.errors.join('; ')}`);
+    }
+    const measures = query.measures ?? Object.keys(ds.measures);
+    return aggregatePlan(ds, query, measures.map((name) => aggregationForMeasure(ds, name)), context);
+}
+function buildBaseMetricPlan(metric, query, context) {
+    const spec = metric.spec;
+    if (spec.__type !== 'aggregation_spec') {
+        throw new Error(`Metric "${metric.name}" is not a base metric.`);
+    }
+    if (spec.sql) {
+        throw new Error(`Semantic backend plans do not support SQL-backed metric "${metric.name}". ` +
+            'Use a backend-specific query builder for raw SQL expressions.');
+    }
+    return aggregatePlan(metric.dataset, {
+        ...query,
+        by: query.by,
+        measures: [],
+    }, [{
+            name: metric.name,
+            aggregation: spec.aggregation,
+            field: resolveField(metric.dataset, spec.field),
+            filters: normalizeFilters(metric.dataset, spec.filters),
+        }], context);
+}
+function buildDerivedMetricPlan(metric, query, context) {
+    const spec = metric.spec;
+    if (spec.__type !== 'derived_metric_spec') {
+        throw new Error(`Metric "${metric.name}" is not a derived metric.`);
+    }
+    const inputAggregations = Object.entries(spec.uses).map(([alias, baseMetric]) => {
+        const baseSpec = baseMetric.spec;
+        if (baseSpec.__type !== 'aggregation_spec') {
+            throw new Error(`Derived metric "${metric.name}" references non-base metric "${alias}".`);
+        }
+        if (baseSpec.sql) {
+            throw new Error(`Semantic backend plans do not support SQL-backed metric "${alias}" used by derived metric "${metric.name}". ` +
+                'Use a backend-specific query builder for raw SQL expressions.');
+        }
+        return {
+            name: alias,
+            aggregation: baseSpec.aggregation,
+            field: resolveField(metric.dataset, baseSpec.field),
+            filters: baseSpec.filters,
+        };
+    });
+    const inputs = Object.fromEntries(Object.keys(spec.uses).map((alias) => [alias, alias]));
+    const expression = spec.formula(inputs).expression;
+    return {
+        kind: 'derive',
+        input: aggregatePlan(metric.dataset, {
+            ...query,
+            orderBy: undefined,
+            limit: undefined,
+            offset: undefined,
+        }, inputAggregations, context),
+        metrics: [{ name: metric.name, expression }],
+        orderBy: query.orderBy,
+        limit: query.limit,
+        offset: query.offset,
+    };
+}
+export function buildMetricPlan(metric, query = {}, context) {
+    const ref = getMetricRef(metric);
+    const grain = getMetricGrain(metric, query);
+    const plannedQuery = { ...query, by: grain };
+    if (ref.spec.__type === 'derived_metric_spec') {
+        return buildDerivedMetricPlan(ref, plannedQuery, context);
+    }
+    return buildBaseMetricPlan(ref, plannedQuery, context);
+}

package/dist/sql-utils.d.ts

@@ -19,7 +19,7 @@ export declare function isSafeSQLIdentifier(identifier: string): boolean;
 export declare function validateSQLIdentifier(identifier: string, context: string): void;
 /**
  * Quotes a SQL identifier for safe use in queries.
- * Uses double quotes which is standard SQL.
+ * Uses backticks, which is how ClickHouse quotes identifiers.
  *
  * @param identifier - The identifier to quote
  * @returns Quoted identifier

package/dist/sql-utils.js

@@ -26,13 +26,13 @@ export function validateSQLIdentifier(identifier, context) {
 }
 /**
  * Quotes a SQL identifier for safe use in queries.
- * Uses double quotes which is standard SQL.
+ * Uses backticks, which is how ClickHouse quotes identifiers.
  *
  * @param identifier - The identifier to quote
  * @returns Quoted identifier
  */
 export function quoteSQLIdentifier(identifier) {
-    // Escape any existing double quotes by doubling them
-    const escaped = identifier.replace(/"/g, '""');
-    return `"${escaped}"`;
+    // Escape any existing backticks by doubling them
+    const escaped = identifier.replace(/`/g, '``');
+    return `\`${escaped}\``;
 }

package/dist/tools.d.ts

@@ -0,0 +1,53 @@
+import type { AnyDatasetInstance, DatasetQuery, ExecutionContext, MetricHandle, MetricQuery } from './types.js';
+import { getDatasetCatalog, type DatasetCatalogSource } from './catalog.js';
+export type JsonSchema = {
+    type?: string;
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    items?: JsonSchema;
+    required?: string[];
+    enum?: string[];
+    minimum?: number;
+    maximum?: number;
+    additionalProperties?: boolean;
+};
+export interface SemanticToolDefinition<TInput = Record<string, unknown>, TResult = unknown> {
+    name: string;
+    description: string;
+    parameters: JsonSchema;
+    execute(input: TInput, context?: ExecutionContext): Promise<TResult>;
+}
+export type DatasetToolMode = 'catalog' | 'per-dataset' | 'per-metric';
+export interface DatasetToolAnalytics {
+    execute(target: AnyDatasetInstance | MetricHandle, query?: DatasetQuery | MetricQuery, context?: ExecutionContext): Promise<unknown>;
+}
+export interface GenerateDatasetToolsOptions {
+    datasets: Record<string, DatasetCatalogSource>;
+    analytics: DatasetToolAnalytics;
+    mode?: DatasetToolMode;
+    includeSql?: boolean;
+}
+export interface OpenAIToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: JsonSchema;
+    };
+}
+export interface AISDKToolDefinition {
+    description: string;
+    parameters: JsonSchema;
+    execute(input: Record<string, unknown>): Promise<unknown>;
+}
+export interface McpToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+}
+export declare function generateDatasetTools(options: GenerateDatasetToolsOptions): SemanticToolDefinition[];
+export declare function toOpenAITools(tools: SemanticToolDefinition[]): OpenAIToolDefinition[];
+export declare function toAISDKTools(tools: SemanticToolDefinition[]): Record<string, AISDKToolDefinition>;
+export declare function toMcpTools(tools: SemanticToolDefinition[]): McpToolDefinition[];
+export { getDatasetCatalog };
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,WAAW,EAGZ,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EAIjB,KAAK,oBAAoB,EAC1B,MAAM,cAAc,CAAC;AAGtB,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,CAAC;AAEF,MAAM,WAAW,sBAAsB,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtE;AAED,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,aAAa,GAAG,YAAY,CAAC;AAEvE,MAAM,WAAW,oBAAoB;IACnC,OAAO,CACL,MAAM,EAAE,kBAAkB,GAAG,YAAY,EACzC,KAAK,CAAC,EAAE,YAAY,GAAG,WAAW,EAClC,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAC/C,SAAS,EAAE,oBAAoB,CAAC;IAChC,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,UAAU,CAAC;KACxB,CAAC;CACH;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,UAAU,CAAC;CACzB;AA8VD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,sBAAsB,EAAE,CAenG;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,sBAAsB,EAAE,GAAG,oBAAoB,EAAE,CASrF;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,sBAAsB,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAWjG;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,sBAAsB,EAAE,GAAG,iBAAiB,EAAE,CAM/E;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/tools.js

@@ -0,0 +1,322 @@
+import { getDatasetCatalog, getDatasetCatalogs, } from './catalog.js';
+import { SEMANTIC_FILTER_OPERATORS } from './constants.js';
+function enumSchema(values, description) {
+    const unique = Array.from(new Set(values));
+    return {
+        type: 'string',
+        ...(unique.length > 0 ? { enum: unique } : {}),
+        ...(description ? { description } : {}),
+    };
+}
+function toolNamePart(name) {
+    const normalized = name.replace(/[^A-Za-z0-9_-]/g, '_');
+    return /^[A-Za-z_]/.test(normalized) ? normalized : `_${normalized}`;
+}
+function arrayEnumSchema(values, description) {
+    return {
+        type: 'array',
+        items: enumSchema(values),
+        ...(description ? { description } : {}),
+    };
+}
+function limitSchema(catalogs) {
+    const finiteLimits = catalogs
+        .map(catalog => catalog.maxLimit)
+        .filter((limit) => typeof limit === 'number');
+    return {
+        type: 'integer',
+        minimum: 0,
+        ...(finiteLimits.length > 0 ? { maximum: Math.max(...finiteLimits) } : {}),
+    };
+}
+function querySchema(catalogs, includeDataset) {
+    const datasetNames = catalogs.map(catalog => catalog.name);
+    const dimensionNames = Array.from(new Set(catalogs.flatMap(catalog => Object.keys(catalog.dimensions))));
+    const measureNames = Array.from(new Set(catalogs.flatMap(catalog => Object.keys(catalog.measures))));
+    const filterNames = Array.from(new Set(catalogs.flatMap(catalog => Object.keys(catalog.filters))));
+    const grainNames = Array.from(new Set(catalogs.flatMap(catalog => catalog.supportedGrains)));
+    const orderFields = Array.from(new Set(catalogs.flatMap(catalog => catalog.orderableFields)));
+    const properties = {
+        dimensions: arrayEnumSchema(dimensionNames, 'Dimensions to group by.'),
+        measures: arrayEnumSchema(measureNames, 'Measures to aggregate.'),
+        filters: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    field: enumSchema(filterNames),
+                    operator: enumSchema([...SEMANTIC_FILTER_OPERATORS]),
+                    value: {},
+                },
+                required: ['field', 'operator', 'value'],
+                additionalProperties: false,
+            },
+        },
+        orderBy: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    field: enumSchema(orderFields),
+                    direction: enumSchema(['asc', 'desc']),
+                },
+                required: ['field', 'direction'],
+                additionalProperties: false,
+            },
+        },
+        by: enumSchema(grainNames, 'Optional time grain.'),
+        limit: limitSchema(catalogs),
+        offset: {
+            type: 'integer',
+            minimum: 0,
+        },
+    };
+    if (includeDataset) {
+        properties.dataset = enumSchema(datasetNames);
+    }
+    return {
+        type: 'object',
+        properties,
+        required: includeDataset ? ['dataset'] : [],
+        additionalProperties: false,
+    };
+}
+function assertStringArray(input, name) {
+    if (input == null)
+        return [];
+    if (!Array.isArray(input) || input.some(value => typeof value !== 'string')) {
+        throw new Error(`Invalid ${name}: expected an array of strings.`);
+    }
+    return input;
+}
+function assertFilters(input) {
+    if (input == null)
+        return [];
+    if (!Array.isArray(input)) {
+        throw new Error('Invalid filters: expected an array.');
+    }
+    return input.map((filter, index) => {
+        if (!filter || typeof filter !== 'object') {
+            throw new Error(`Invalid filters[${index}]: expected an object.`);
+        }
+        const candidate = filter;
+        if (typeof candidate.field !== 'string') {
+            throw new Error(`Invalid filters[${index}].field: expected a string.`);
+        }
+        if (!SEMANTIC_FILTER_OPERATORS.includes(candidate.operator)) {
+            throw new Error(`Invalid filters[${index}].operator: expected a supported operator.`);
+        }
+        return {
+            field: candidate.field,
+            operator: candidate.operator,
+            value: candidate.value,
+        };
+    });
+}
+function assertOrderBy(input) {
+    if (input == null)
+        return [];
+    if (!Array.isArray(input)) {
+        throw new Error('Invalid orderBy: expected an array.');
+    }
+    return input.map((order, index) => {
+        if (!order || typeof order !== 'object') {
+            throw new Error(`Invalid orderBy[${index}]: expected an object.`);
+        }
+        const candidate = order;
+        if (typeof candidate.field !== 'string') {
+            throw new Error(`Invalid orderBy[${index}].field: expected a string.`);
+        }
+        if (candidate.direction !== 'asc' && candidate.direction !== 'desc') {
+            throw new Error(`Invalid orderBy[${index}].direction: expected "asc" or "desc".`);
+        }
+        return {
+            field: candidate.field,
+            direction: candidate.direction,
+        };
+    });
+}
+function assertNonNegativeInteger(input, name) {
+    if (input == null)
+        return undefined;
+    if (!Number.isInteger(input) || input < 0) {
+        throw new Error(`Invalid ${name}: expected a non-negative integer.`);
+    }
+    return input;
+}
+function assertAllowedValues(values, allowed, label) {
+    const invalid = values.filter(value => !allowed.includes(value));
+    if (invalid.length > 0) {
+        throw new Error(`Invalid ${label}: ${invalid.join(', ')}. Available: ${allowed.join(', ') || '(none)'}.`);
+    }
+}
+function normalizeDatasetQuery(input, catalog, options = {}) {
+    const dimensions = assertStringArray(input.dimensions, 'dimensions');
+    const measures = assertStringArray(input.measures, 'measures');
+    const filters = assertFilters(input.filters);
+    const orderBy = assertOrderBy(input.orderBy);
+    const limit = assertNonNegativeInteger(input.limit, 'limit');
+    const offset = assertNonNegativeInteger(input.offset, 'offset');
+    let by;
+    assertAllowedValues(dimensions, Object.keys(catalog.dimensions), 'dimensions');
+    assertAllowedValues(measures, Object.keys(catalog.measures), 'measures');
+    assertAllowedValues(filters.map(filter => filter.field), Object.keys(catalog.filters), 'filter fields');
+    assertAllowedValues(orderBy.map(order => order.field), options.orderableFields ?? catalog.orderableFields, 'orderBy fields');
+    for (const filter of filters) {
+        const allowedOperators = catalog.filters[filter.field]?.operators ?? [];
+        if (!allowedOperators.includes(filter.operator)) {
+            throw new Error(`Invalid filter operator for "${filter.field}": ${filter.operator}. Allowed: ${allowedOperators.join(', ')}.`);
+        }
+    }
+    if (typeof input.by === 'string') {
+        assertAllowedValues([input.by], catalog.supportedGrains, 'time grain');
+        by = input.by;
+    }
+    else if (input.by != null) {
+        throw new Error('Invalid by: expected a time grain string.');
+    }
+    if (limit != null && catalog.maxLimit != null && limit > catalog.maxLimit) {
+        throw new Error(`Invalid limit: ${limit}. Max: ${catalog.maxLimit}.`);
+    }
+    return {
+        ...(dimensions.length > 0 ? { dimensions } : {}),
+        ...(measures.length > 0 ? { measures } : {}),
+        ...(filters.length > 0 ? { filters } : {}),
+        ...(orderBy.length > 0 ? { orderBy } : {}),
+        ...(by ? { by } : {}),
+        ...(limit != null ? { limit } : {}),
+        ...(offset != null ? { offset } : {}),
+    };
+}
+function redactSql(result, includeSql) {
+    if (includeSql || !result || typeof result !== 'object') {
+        return result;
+    }
+    const resultObject = result;
+    if (!resultObject.meta || typeof resultObject.meta !== 'object' || !('sql' in resultObject.meta)) {
+        return result;
+    }
+    const { sql: _sql, ...meta } = resultObject.meta;
+    return {
+        ...resultObject,
+        meta,
+    };
+}
+function buildCatalogTool(datasets, catalogs, analytics, includeSql) {
+    const catalogList = Object.values(catalogs);
+    return {
+        name: 'query_dataset',
+        description: 'Query governed analytics datasets by selecting dimensions, measures, filters, and time grains.',
+        parameters: querySchema(catalogList, true),
+        async execute(input, context) {
+            if (typeof input.dataset !== 'string' || !datasets[input.dataset]) {
+                throw new Error(`Invalid dataset: ${String(input.dataset)}. Available: ${Object.keys(datasets).join(', ')}.`);
+            }
+            const catalog = catalogs[input.dataset];
+            const query = normalizeDatasetQuery(input, catalog);
+            const result = await analytics.execute(datasets[input.dataset], query, context);
+            return redactSql(result, includeSql);
+        },
+    };
+}
+function buildDatasetTools(datasets, catalogs, analytics, includeSql) {
+    return Object.entries(datasets).map(([datasetName, dataset]) => {
+        const catalog = catalogs[datasetName];
+        return {
+            name: `query_${toolNamePart(datasetName)}`,
+            description: `Query the ${datasetName} analytics dataset.`,
+            parameters: querySchema([catalog], false),
+            async execute(input, context) {
+                const query = normalizeDatasetQuery(input, catalog);
+                const result = await analytics.execute(dataset, query, context);
+                return redactSql(result, includeSql);
+            },
+        };
+    });
+}
+function metricQuerySchema(catalog, metricName) {
+    const schema = querySchema([catalog], false);
+    const properties = schema.properties ?? {};
+    delete properties.measures;
+    properties.orderBy = {
+        type: 'array',
+        items: {
+            type: 'object',
+            properties: {
+                field: enumSchema([...Object.keys(catalog.dimensions), metricName, ...(catalog.timeKey ? ['period'] : [])]),
+                direction: enumSchema(['asc', 'desc']),
+            },
+            required: ['field', 'direction'],
+            additionalProperties: false,
+        },
+    };
+    return {
+        ...schema,
+        properties,
+    };
+}
+function buildMetricTools(datasets, catalogs, analytics, includeSql) {
+    const tools = [];
+    for (const [datasetName, dataset] of Object.entries(datasets)) {
+        const catalog = catalogs[datasetName];
+        for (const [metricName, metric] of Object.entries(dataset.metrics ?? {})) {
+            tools.push({
+                name: `query_${toolNamePart(metricName)}`,
+                description: `Query the ${metricName} metric from the ${datasetName} dataset.`,
+                parameters: metricQuerySchema(catalog, metricName),
+                async execute(input, context) {
+                    const orderableFields = [
+                        ...Object.keys(catalog.dimensions),
+                        metricName,
+                        ...(catalog.timeKey ? ['period'] : []),
+                    ];
+                    const query = normalizeDatasetQuery({ ...input, measures: [] }, catalog, { orderableFields });
+                    const result = await analytics.execute(metric, query, context);
+                    return redactSql(result, includeSql);
+                },
+            });
+        }
+    }
+    return tools;
+}
+export function generateDatasetTools(options) {
+    const mode = options.mode ?? 'catalog';
+    const catalogs = getDatasetCatalogs(options.datasets);
+    if (mode === 'catalog') {
+        return [
+            buildCatalogTool(options.datasets, catalogs, options.analytics, options.includeSql ?? false),
+        ];
+    }
+    if (mode === 'per-dataset') {
+        return buildDatasetTools(options.datasets, catalogs, options.analytics, options.includeSql ?? false);
+    }
+    return buildMetricTools(options.datasets, catalogs, options.analytics, options.includeSql ?? false);
+}
+export function toOpenAITools(tools) {
+    return tools.map(tool => ({
+        type: 'function',
+        function: {
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.parameters,
+        },
+    }));
+}
+export function toAISDKTools(tools) {
+    return Object.fromEntries(tools.map(tool => [
+        tool.name,
+        {
+            description: tool.description,
+            parameters: tool.parameters,
+            execute: input => tool.execute(input),
+        },
+    ]));
+}
+export function toMcpTools(tools) {
+    return tools.map(tool => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.parameters,
+    }));
+}
+export { getDatasetCatalog };