@hypequery/datasets 0.2.0 → 0.2.1

package/dist/catalog.d.ts

@@ -0,0 +1,68 @@
+import type { AnyDatasetInstance, DimensionDefinition, MeasureDefinition, MetricHandle, RelationshipDefinition, SemanticFilterDefinition, DatasetLimits, TimeGrain } from './types.js';
+export interface DimensionCatalogEntry {
+    type: DimensionDefinition['fieldType'];
+    column?: string;
+    sql?: string;
+    label?: string;
+    description?: string;
+    filterable: boolean;
+    groupable: boolean;
+}
+export interface MeasureCatalogEntry {
+    aggregation: MeasureDefinition['aggregation'];
+    field: string;
+    sql?: string;
+    label?: string;
+    description?: string;
+    filterCount: number;
+}
+export interface FilterCatalogEntry {
+    field: string;
+    label?: string;
+    description?: string;
+    operators: SemanticFilterDefinition['operators'];
+    valueType?: DimensionDefinition['fieldType'];
+}
+export interface MetricCatalogEntry {
+    kind: ReturnType<MetricHandle['contract']>['kind'];
+    dataset: string;
+    valueType: 'number';
+    label?: string;
+    description?: string;
+    dimensions: string[];
+    measures?: string[];
+    filters: string[];
+    grains: string[];
+    grain?: string;
+    requires?: string[];
+}
+export interface RelationshipCatalogEntry {
+    kind: RelationshipDefinition['kind'];
+    target: string;
+    from: string;
+    to: string;
+    execution: 'metadata_only';
+}
+export interface DatasetCatalog {
+    name: string;
+    source: string;
+    tenantKey?: string;
+    timeKey?: string;
+    dimensions: Record<string, DimensionCatalogEntry>;
+    measures: Record<string, MeasureCatalogEntry>;
+    metrics: Record<string, MetricCatalogEntry>;
+    filters: Record<string, FilterCatalogEntry>;
+    relationships: Record<string, RelationshipCatalogEntry>;
+    limits?: DatasetLimits;
+    requiresTenant: boolean;
+    supportedGrains: TimeGrain[];
+    orderableFields: string[];
+    maxLimit?: number;
+}
+export type DatasetCatalogMap = Record<string, DatasetCatalog>;
+export type DatasetCatalogSource = AnyDatasetInstance & {
+    metrics?: Record<string, MetricHandle>;
+};
+export declare function getDatasetCatalog(dataset: DatasetCatalogSource): DatasetCatalog;
+export declare function getDatasetCatalogs(datasets: Record<string, DatasetCatalogSource>): DatasetCatalogMap;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

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

package/dist/catalog.js

@@ -0,0 +1,105 @@
+import { SEMANTIC_FILTER_OPERATORS, SUPPORTED_TIME_GRAINS } from './constants.js';
+function dimensionToCatalog(dimension) {
+    return {
+        type: dimension.fieldType,
+        column: dimension.column,
+        sql: dimension.sql,
+        label: dimension.label,
+        description: dimension.description,
+        filterable: dimension.filterable !== false,
+        groupable: dimension.groupable !== false,
+    };
+}
+function measureToCatalog(measure) {
+    return {
+        aggregation: measure.aggregation,
+        field: measure.field,
+        sql: measure.sql,
+        label: measure.label,
+        description: measure.description,
+        filterCount: measure.filters?.length ?? 0,
+    };
+}
+function filterToCatalog(filter, dimensions) {
+    return {
+        field: filter.field,
+        label: filter.label,
+        description: filter.description,
+        operators: filter.operators ? [...filter.operators] : [...SEMANTIC_FILTER_OPERATORS],
+        valueType: dimensions[filter.field]?.fieldType,
+    };
+}
+function metricToCatalog(metric) {
+    const contract = metric.contract();
+    return {
+        kind: contract.kind,
+        dataset: contract.dataset,
+        valueType: contract.valueType,
+        label: contract.label,
+        description: contract.description,
+        dimensions: contract.dimensions,
+        measures: contract.measures,
+        filters: contract.filters,
+        grains: contract.grains,
+        grain: contract.grain,
+        requires: contract.requires,
+    };
+}
+function relationshipToCatalog(relationship) {
+    return {
+        kind: relationship.kind,
+        target: relationship.target().name,
+        from: relationship.from,
+        to: relationship.to,
+        execution: 'metadata_only',
+    };
+}
+export function getDatasetCatalog(dataset) {
+    const dimensionNames = Object.keys(dataset.dimensions);
+    const measureNames = Object.keys(dataset.measures);
+    const metricNames = Object.keys(dataset.metrics ?? {});
+    const supportedGrains = dataset.timeKey ? [...SUPPORTED_TIME_GRAINS] : [];
+    const maxLimit = dataset.limits?.maxResultSize;
+    return {
+        name: dataset.name,
+        source: dataset.source,
+        tenantKey: dataset.tenantKey,
+        timeKey: dataset.timeKey,
+        dimensions: Object.fromEntries(Object.entries(dataset.dimensions).map(([name, dimension]) => [
+            name,
+            dimensionToCatalog(dimension),
+        ])),
+        measures: Object.fromEntries(Object.entries(dataset.measures).map(([name, measure]) => [
+            name,
+            measureToCatalog(measure),
+        ])),
+        metrics: Object.fromEntries(Object.entries(dataset.metrics ?? {}).map(([name, metric]) => [
+            name,
+            metricToCatalog(metric),
+        ])),
+        filters: Object.fromEntries(Object.entries(dataset.filters).map(([name, filter]) => [
+            name,
+            filterToCatalog(filter, dataset.dimensions),
+        ])),
+        relationships: Object.fromEntries(Object.entries(dataset.relationships).map(([name, relationship]) => [
+            name,
+            relationshipToCatalog(relationship),
+        ])),
+        limits: dataset.limits,
+        requiresTenant: !!dataset.tenantKey,
+        supportedGrains,
+        orderableFields: [
+            ...dimensionNames,
+            ...measureNames,
+            ...metricNames,
+            ...(dataset.timeKey ? ['period'] : []),
+        ],
+        maxLimit,
+    };
+}
+export function getDatasetCatalogs(datasets) {
+    return Object.fromEntries(Object.entries(datasets).map(([name, dataset]) => [
+        name,
+        getDatasetCatalog(dataset),
+    ]));
+}

package/dist/constants.d.ts

@@ -11,6 +11,10 @@ export declare const GRAIN_FUNCTIONS: Record<TimeGrain, string>;
  * {@link GRAIN_FUNCTIONS} so the two never drift apart.
  */
 export declare const SUPPORTED_TIME_GRAINS: TimeGrain[];
+/**
+ * The filter operators accepted by semantic dataset and metric inputs.
+ */
+export declare const SEMANTIC_FILTER_OPERATORS: readonly ["eq", "neq", "gt", "gte", "lt", "lte", "in", "notIn", "between", "like"];
 /**
  * Narrowing guard for a runtime-provided grain value.
  */

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAMrD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAmC,SAAS,EAAE,CAAC;AAEjF;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAEvE"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAgB,SAAS,EAAE,MAAM,YAAY,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAMrD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAmC,SAAS,EAAE,CAAC;AAEjF;;GAEG;AACH,eAAO,MAAM,yBAAyB,oFAWkB,CAAC;AAEzD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAEvE"}

package/dist/constants.js

@@ -16,6 +16,21 @@ export const GRAIN_FUNCTIONS = {
  * {@link GRAIN_FUNCTIONS} so the two never drift apart.
  */
 export const SUPPORTED_TIME_GRAINS = Object.keys(GRAIN_FUNCTIONS);
+/**
+ * The filter operators accepted by semantic dataset and metric inputs.
+ */
+export const SEMANTIC_FILTER_OPERATORS = [
+    'eq',
+    'neq',
+    'gt',
+    'gte',
+    'lt',
+    'lte',
+    'in',
+    'notIn',
+    'between',
+    'like',
+];
 /**
  * Narrowing guard for a runtime-provided grain value.
  */

package/dist/index.d.ts

@@ -6,6 +6,10 @@ export { sum, count, countDistinct, avg, min, max } from './aggregations.js';
 export { divide, multiply, subtract, add, nullIfZero, coalesce, round, floor, ceil, } from './formulas.js';
 export { eq, neq, gt, gte, lt, lte, inList, notInList, between, like, asc, desc, filter, order, } from './query-helpers.js';
 export { createDatasetRegistry } from './registry.js';
+export { getDatasetCatalog, getDatasetCatalogs } from './catalog.js';
+export type { DatasetCatalog, DatasetCatalogMap, DimensionCatalogEntry, MeasureCatalogEntry, MetricCatalogEntry, FilterCatalogEntry, RelationshipCatalogEntry, } from './catalog.js';
+export { generateDatasetTools, toOpenAITools, toAISDKTools, toMcpTools, } from './tools.js';
+export type { AISDKToolDefinition, DatasetToolAnalytics, DatasetToolMode, GenerateDatasetToolsOptions, JsonSchema, McpToolDefinition, OpenAIToolDefinition, SemanticToolDefinition, } from './tools.js';
 export { createDatasetClient } from './executor.js';
 export type { DatasetClient, CreateDatasetClientOptions } from './executor.js';
 export { createInMemoryBackend } from './in-memory-backend.js';
@@ -15,6 +19,6 @@ export type { ValidationResult } from './validation.js';
 export { validateFilterValue, matchesFieldType } from './validation.js';
 export type { QueryBuilderLike, QueryBuilderFactoryLike } from './query-builder-protocol.js';
 export { validateSQLIdentifier, isSafeSQLIdentifier, quoteSQLIdentifier } from './sql-utils.js';
-export { GRAIN_FUNCTIONS } from './constants.js';
+export { GRAIN_FUNCTIONS, SEMANTIC_FILTER_OPERATORS, SUPPORTED_TIME_GRAINS } from './constants.js';
 export type { FieldType, DimensionType, DimensionOptions, DimensionDefinition, MeasureOptions, MeasureDefinition, InferDimensionType, RelationshipKind, RelationshipDefinition, AggregationType, MeasureAggregation, AggregationSpec, FormulaExpr, DerivedMetricSpec, TimeGrain, MetricRef, BaseMetricRef, DerivedMetricRef, GrainedMetricRef, MetricContract, MetricFilter, MetricOrderBy, MetricQuery, DatasetQuery, MetricResultMeta, MetricResult, DatasetQueryResult, MetricHandle, ExecutionContext, SemanticExecutionRuntime, SemanticTenantRuntime, SemanticFilterDefinition, SemanticFiltersDefinition, DatasetConfig, DatasetLimits, DatasetInstance, AnyDatasetInstance, BaseMetricConfig, DerivedMetricConfig, DatasetRegistryInstance, DatasetFieldNames, DatasetDimensionNames, DatasetMeasureNames, DatasetOrderableNames, DatasetQueryFor, DatasetRow, DatasetQueryResultFor, MetricQueryFor, MetricRow, MetricResultFor, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAGhE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAG7E,OAAO,EACL,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAC/B,UAAU,EAAE,QAAQ,EACpB,KAAK,EAAE,KAAK,EAAE,IAAI,GACnB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EACzB,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAChC,GAAG,EAAE,IAAI,EACT,MAAM,EAAE,KAAK,GACd,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAGtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,YAAY,EAAE,aAAa,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC5E,YAAY,EACV,QAAQ,EACR,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,uBAAuB,EACvB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAG5B,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGxE,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAG7F,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAGhG,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGjD,YAAY,EACV,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,wBAAwB,EACxB,qBAAqB,EACrB,wBAAwB,EACxB,yBAAyB,EACzB,aAAa,EACb,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,UAAU,EACV,qBAAqB,EACrB,cAAc,EACd,SAAS,EACT,eAAe,GAChB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -14,6 +14,10 @@ export { divide, multiply, subtract, add, nullIfZero, coalesce, round, floor, ce
 export { eq, neq, gt, gte, lt, lte, inList, notInList, between, like, asc, desc, filter, order, } from './query-helpers.js';
 // Registry
 export { createDatasetRegistry } from './registry.js';
+// Catalog
+export { getDatasetCatalog, getDatasetCatalogs } from './catalog.js';
+// Agent/tool metadata
+export { generateDatasetTools, toOpenAITools, toAISDKTools, toMcpTools, } from './tools.js';
 // Dataset client
 export { createDatasetClient } from './executor.js';
 export { createInMemoryBackend } from './in-memory-backend.js';
@@ -21,4 +25,4 @@ export { validateFilterValue, matchesFieldType } from './validation.js';
 // SQL utilities
 export { validateSQLIdentifier, isSafeSQLIdentifier, quoteSQLIdentifier } from './sql-utils.js';
 // Constants
-export { GRAIN_FUNCTIONS } from './constants.js';
+export { GRAIN_FUNCTIONS, SEMANTIC_FILTER_OPERATORS, SUPPORTED_TIME_GRAINS } from './constants.js';

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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/datasets",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Semantic layer for defining datasets, metrics, and semantic queries",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",