drizzle-cube 0.5.7 → 0.6.0

package/dist/server/server/ai/discovery-helpers.d.ts

@@ -0,0 +1,29 @@
+import { CubeMetadata } from '../types/metadata';
+/** A measure or dimension as carried in cube metadata. */
+type Field = CubeMetadata['measures'][number] | CubeMetadata['dimensions'][number];
+/** Scoring callbacks shared with discovery.ts (avoids a circular import). */
+export interface ScoreFns {
+    fuzzyMatchScore: (query: string, target: string) => number;
+    matchAgainstArray: (query: string, targets: string[]) => number;
+}
+/**
+ * Score a single field (measure or dimension) against a keyword.
+ * Returns the best score across name, title, description and synonyms.
+ */
+export declare function scoreField(keyword: string, field: Field, fns: ScoreFns): number;
+/**
+ * Accumulate field scores for a keyword into a running totals map.
+ * Adds to `totalScore` (returned) and records the per-field best score when the
+ * field clears the relevance threshold, mutating `scores` and `matchedOn`.
+ */
+export declare function accumulateFieldScores(keyword: string, fields: Field[], fns: ScoreFns, scores: Map<string, number>, matchedOn: {
+    hit: boolean;
+}): number;
+/** Return the top-N field names from a score map, highest score first. */
+export declare function topScoredFields(scores: Map<string, number>, limit: number): string[];
+/**
+ * Score a single field as a best-match candidate (used by findBestFieldMatch).
+ * Returns the best score across name, title and synonyms (no description match).
+ */
+export declare function scoreFieldForBestMatch(fieldName: string, field: Field, fns: ScoreFns): number;
+export {};

package/dist/server/server/ai/discovery.d.ts

@@ -0,0 +1,66 @@
+import { CubeMetadata } from '../types/metadata';
+import { QUERY_SCHEMAS } from './schemas';
+/**
+ * Discovery result for a cube
+ */
+export interface CubeDiscoveryResult {
+    cube: string;
+    title: string;
+    description?: string;
+    relevanceScore: number;
+    matchedOn: ('name' | 'title' | 'description' | 'exampleQuestions' | 'measures' | 'dimensions')[];
+    suggestedMeasures: string[];
+    suggestedDimensions: string[];
+    capabilities: {
+        query: true;
+        funnel: boolean;
+        flow: boolean;
+        retention: boolean;
+    };
+    analysisConfig?: {
+        candidateBindingKeys: Array<{
+            dimension: string;
+            description?: string;
+        }>;
+        candidateTimeDimensions: Array<{
+            dimension: string;
+            description?: string;
+        }>;
+        candidateEventDimensions: Array<{
+            dimension: string;
+            description?: string;
+        }>;
+    };
+    hints?: string[];
+    querySchemas?: typeof QUERY_SCHEMAS;
+}
+/**
+ * Discovery request options
+ */
+export interface DiscoveryOptions {
+    /** Topic or intent to search for */
+    topic?: string;
+    /** Natural language intent */
+    intent?: string;
+    /** Maximum number of results */
+    limit?: number;
+    /** Minimum relevance score (0-1) */
+    minScore?: number;
+}
+/**
+ * Calculate Levenshtein distance between two strings
+ */
+export declare function levenshteinDistance(a: string, b: string): number;
+/**
+ * Discover relevant cubes based on topic or intent
+ */
+export declare function discoverCubes(metadata: CubeMetadata[], options?: DiscoveryOptions): CubeDiscoveryResult[];
+/**
+ * Find the best matching field across all cubes
+ */
+export declare function findBestFieldMatch(metadata: CubeMetadata[], fieldName: string, fieldType?: 'measure' | 'dimension'): {
+    field: string;
+    cube: string;
+    score: number;
+    type: 'measure' | 'dimension';
+} | null;

package/dist/server/server/ai/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * AI-Ready Data Layer Utilities
+ * Schema-aware intelligence for AI agents - no server-side LLM required
+ */
+export { discoverCubes, findBestFieldMatch, type CubeDiscoveryResult, type DiscoveryOptions } from './discovery';
+export { suggestQuery, type QuerySuggestion } from './suggestion';
+export { validateQuery, type ValidationResult, type ValidationError, type ValidationWarning } from './validation';
+export { QUERY_SCHEMAS, type QuerySchemas } from './schemas';
+export { QUERY_PARAMS_SCHEMA, QUERY_LANGUAGE_REFERENCE } from './query-schema';
+export { MCP_PROMPTS, MCP_GUIDE_PROMPT, QUERY_LANGUAGE_PROMPT, QUERY_RULES_PROMPT, QUERY_BUILDING_PROMPT, DATE_FILTERING_PROMPT, DEFAULT_MCP_INSTRUCTIONS, getDefaultMCPPrompts, getDefaultMcpInstructions, type MCPPrompt } from './mcp-prompts';

package/dist/server/server/ai/mcp-prompts.d.ts

@@ -0,0 +1,83 @@
+/**
+ * MCP Prompts for AI Agents
+ *
+ * These prompts provide guidance for AI agents using the Drizzle Cube MCP server.
+ * They help prevent common query mistakes and ensure correct query construction.
+ *
+ * Structure: 3 focused prompts (down from 4 redundant ones):
+ * - MCP_GUIDE_PROMPT: Workflow (discover -> validate -> load) + cross-cube joins
+ * - QUERY_LANGUAGE_PROMPT: TS DSL reference (single source of truth from query-schema.ts)
+ * - DATE_FILTERING_PROMPT: Decision tree for the #1 mistake
+ *
+ * QUERY_RULES_PROMPT and QUERY_BUILDING_PROMPT are kept as backward-compatible aliases.
+ */
+export interface MCPPrompt {
+    name: string;
+    description: string;
+    messages: Array<{
+        role: 'user' | 'assistant';
+        content: {
+            type: 'text';
+            text: string;
+        };
+    }>;
+}
+/**
+ * Main workflow guide for using drizzle-cube MCP tools
+ */
+export declare const MCP_GUIDE_PROMPT: MCPPrompt;
+/**
+ * Query language reference — imports the TypeScript DSL from query-schema.ts
+ * Replaces both QUERY_RULES_PROMPT and QUERY_BUILDING_PROMPT
+ */
+export declare const QUERY_LANGUAGE_PROMPT: MCPPrompt;
+/**
+ * Critical guide specifically for date filtering vs time grouping — the #1 mistake
+ */
+export declare const DATE_FILTERING_PROMPT: MCPPrompt;
+/**
+ * Backward-compatible alias — now references the unified query language prompt
+ */
+export declare const QUERY_RULES_PROMPT: MCPPrompt;
+/**
+ * Backward-compatible alias — now references the unified query language prompt
+ */
+export declare const QUERY_BUILDING_PROMPT: MCPPrompt;
+/**
+ * All MCP prompts for the Drizzle Cube server
+ */
+export declare const MCP_PROMPTS: MCPPrompt[];
+/**
+ * Get all default MCP prompts
+ */
+export declare function getDefaultMCPPrompts(): MCPPrompt[];
+/**
+ * Default instructions returned in the MCP `initialize` result.
+ *
+ * Per the MCP spec (InitializeResult.instructions), this string is the only
+ * server-authored guidance that clients are expected to surface to the model
+ * (e.g. by adding it to the system prompt). `prompts/*` and `resources/*` are
+ * pull-based and are usually invoked by the *user* (slash commands) — not by
+ * the model — so we cannot rely on them for correctness.
+ *
+ * The instructions therefore:
+ *  1. Mandate the discover → (validate) → load workflow.
+ *  2. Tell the model that the `discover` tool response itself contains the
+ *     full query language reference (`queryLanguageReference`) and the date
+ *     filtering decision tree (`dateFilteringGuide`). The model MUST read
+ *     those fields before constructing any query — they are the source of
+ *     truth for syntax, operators, and analysis modes.
+ *  3. Inline the single most-violated rule (aggregated totals vs time
+ *     series) so that even a model that ignores the discover payload still
+ *     sees it once in its system prompt.
+ *
+ * Keep this body short (< ~2 KB) — long instructions get truncated or
+ * deprioritised by some clients.
+ */
+export declare const DEFAULT_MCP_INSTRUCTIONS: string;
+/**
+ * Get the default MCP instructions string returned in the `initialize` result.
+ * Exposed as a function (not just a const) so consumers can wrap or extend it
+ * via the `instructions` resolver in `MCPOptions`.
+ */
+export declare function getDefaultMcpInstructions(): string;

package/dist/server/server/ai/query-schema.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Unified Query Schema — Single Source of Truth
+ *
+ * This module defines the canonical query parameter schema used by BOTH:
+ * - MCP `load` tool (mcp-transport.ts)
+ * - Agent `execute_query` tool (agent/tools.ts)
+ *
+ * It also exports a TypeScript DSL reference string used in prompts.
+ */
+/**
+ * JSON Schema for query parameters shared across MCP and Agent tools.
+ * Covers regular queries (measures/dimensions/filters/timeDimensions/order/limit/offset/ungrouped)
+ * and analysis modes (funnel/flow/retention).
+ */
+export declare const QUERY_PARAMS_SCHEMA: {
+    readonly measures: {
+        readonly type: "array";
+        readonly items: {
+            readonly type: "string";
+            readonly pattern: "^[A-Z][a-zA-Z0-9]*\\.[a-zA-Z][a-zA-Z0-9]*$";
+        };
+        readonly description: "Aggregation measures — EXACTLY \"CubeName.measureName\" (two parts, one dot). Copy field names verbatim from discover results. WRONG: \"Sales.Sales.count\" (double-prefixed). RIGHT: \"Sales.count\".";
+    };
+    readonly dimensions: {
+        readonly type: "array";
+        readonly items: {
+            readonly type: "string";
+            readonly pattern: "^[A-Z][a-zA-Z0-9]*\\.[a-zA-Z][a-zA-Z0-9]*$";
+        };
+        readonly description: "Grouping dimensions — EXACTLY \"CubeName.dimensionName\" (two parts, one dot). Copy from discover results. Can include dimensions from RELATED cubes via joins. WRONG: \"Teams.Teams.name\". RIGHT: \"Teams.name\".";
+    };
+    readonly filters: {
+        readonly type: "array";
+        readonly items: {
+            readonly type: "object";
+            readonly properties: {
+                readonly member: {
+                    readonly type: "string";
+                    readonly description: "\"CubeName.fieldName\"";
+                };
+                readonly operator: {
+                    readonly type: "string";
+                    readonly enum: readonly ["equals", "notEquals", "contains", "notContains", "startsWith", "notStartsWith", "endsWith", "notEndsWith", "gt", "gte", "lt", "lte", "between", "notBetween", "in", "notIn", "like", "notLike", "ilike", "regex", "notRegex", "set", "notSet", "isEmpty", "isNotEmpty", "inDateRange", "beforeDate", "afterDate", "arrayContains", "arrayOverlaps", "arrayContained"];
+                };
+                readonly values: {
+                    readonly type: "array";
+                    readonly items: {};
+                    readonly description: "Filter values. Omit for set/notSet/isEmpty/isNotEmpty.";
+                };
+            };
+            readonly required: readonly ["member", "operator"];
+        };
+        readonly description: "Filter conditions. Flat array — for AND/OR logic use { \"and\": [...] } or { \"or\": [...] } wrappers.";
+    };
+    readonly timeDimensions: {
+        readonly type: "array";
+        readonly items: {
+            readonly type: "object";
+            readonly properties: {
+                readonly dimension: {
+                    readonly type: "string";
+                    readonly description: "\"CubeName.timeDimension\"";
+                };
+                readonly granularity: {
+                    readonly type: "string";
+                    readonly enum: readonly ["second", "minute", "hour", "day", "week", "month", "quarter", "year"];
+                    readonly description: "Time bucket size. REQUIRED for time series; omit only for date range filtering.";
+                };
+                readonly dateRange: {
+                    readonly description: "Relative string (\"last 7 days\", \"this month\", \"last quarter\") or absolute tuple [\"YYYY-MM-DD\", \"YYYY-MM-DD\"]";
+                };
+                readonly fillMissingDates: {
+                    readonly type: "boolean";
+                    readonly description: "Fill gaps in time series with fillMissingDatesValue (default: true). Requires granularity + dateRange.";
+                };
+                readonly compareDateRange: {
+                    readonly type: "array";
+                    readonly items: {};
+                    readonly description: "Period-over-period comparison. Array of date ranges: [\"last 30 days\", [\"2024-01-01\", \"2024-01-30\"]]";
+                };
+            };
+            readonly required: readonly ["dimension"];
+        };
+        readonly description: "Time dimensions with optional granularity for time series. Use filters with inDateRange for aggregated totals instead.";
+    };
+    readonly order: {
+        readonly type: "object";
+        readonly description: "Sort order. Keys MUST be a measure or dimension already in this query, in \"CubeName.fieldName\" format. Values: \"asc\" or \"desc\". Example: {\"Sales.revenue\": \"desc\"}";
+    };
+    readonly limit: {
+        readonly type: "number";
+        readonly description: "Maximum rows to return";
+    };
+    readonly offset: {
+        readonly type: "number";
+        readonly description: "Number of rows to skip (for pagination)";
+    };
+    readonly ungrouped: {
+        readonly type: "boolean";
+        readonly description: "When true, returns raw row-level data without GROUP BY. Requires at least one dimension. Incompatible with count/countDistinct measures and analysis modes.";
+    };
+    readonly funnel: {
+        readonly type: "object";
+        readonly properties: {
+            readonly bindingKey: {
+                readonly type: "string";
+                readonly description: "Entity identifier dimension (e.g., \"Events.userId\")";
+            };
+            readonly timeDimension: {
+                readonly type: "string";
+                readonly description: "Time ordering dimension (e.g., \"Events.timestamp\")";
+            };
+            readonly steps: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly name: {
+                            readonly type: "string";
+                            readonly description: "Human-readable step name";
+                        };
+                        readonly filter: {
+                            readonly description: "Filter or array of filters for this step";
+                        };
+                        readonly timeToConvert: {
+                            readonly type: "string";
+                            readonly description: "ISO 8601 duration — max time from previous step (e.g., \"P7D\" for 7 days, \"PT1H\" for 1 hour)";
+                        };
+                    };
+                    readonly required: readonly ["name"];
+                };
+                readonly description: "Ordered funnel steps (minimum 2). Put inDateRange time filter ONLY on step 0.";
+            };
+            readonly includeTimeMetrics: {
+                readonly type: "boolean";
+                readonly description: "Include avg/median/p90 time-to-convert per step";
+            };
+            readonly globalTimeWindow: {
+                readonly type: "string";
+                readonly description: "ISO 8601 duration — all steps must complete within this window from step 0";
+            };
+        };
+        readonly required: readonly ["bindingKey", "timeDimension", "steps"];
+        readonly description: "Funnel analysis. When provided, measures/dimensions are ignored.";
+    };
+    readonly flow: {
+        readonly type: "object";
+        readonly properties: {
+            readonly bindingKey: {
+                readonly type: "string";
+                readonly description: "Entity identifier dimension (e.g., \"Events.userId\")";
+            };
+            readonly timeDimension: {
+                readonly type: "string";
+                readonly description: "Time ordering dimension (e.g., \"Events.timestamp\")";
+            };
+            readonly eventDimension: {
+                readonly type: "string";
+                readonly description: "Dimension whose values become node labels (e.g., \"Events.eventType\")";
+            };
+            readonly startingStep: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly name: {
+                        readonly type: "string";
+                        readonly description: "Display name for the starting step";
+                    };
+                    readonly filter: {
+                        readonly description: "Filter(s) identifying the starting event";
+                    };
+                };
+                readonly required: readonly ["name"];
+                readonly description: "The anchor point — an object with { name, filter }, NOT a plain string.";
+            };
+            readonly stepsBefore: {
+                readonly type: "number";
+                readonly description: "Steps to explore before starting step (0-5)";
+            };
+            readonly stepsAfter: {
+                readonly type: "number";
+                readonly description: "Steps to explore after starting step (0-5)";
+            };
+            readonly entityLimit: {
+                readonly type: "number";
+                readonly description: "Max entities to process (performance tuning)";
+            };
+            readonly outputMode: {
+                readonly type: "string";
+                readonly enum: readonly ["sankey", "sunburst"];
+                readonly description: "Visualization mode (default: sankey)";
+            };
+        };
+        readonly required: readonly ["bindingKey", "timeDimension", "eventDimension", "startingStep"];
+        readonly description: "Flow (path) analysis. When provided, measures/dimensions are ignored.";
+    };
+    readonly retention: {
+        readonly type: "object";
+        readonly properties: {
+            readonly timeDimension: {
+                readonly type: "string";
+                readonly description: "Timestamp dimension (e.g., \"Events.timestamp\")";
+            };
+            readonly bindingKey: {
+                readonly type: "string";
+                readonly description: "Entity identifier (e.g., \"Events.userId\")";
+            };
+            readonly dateRange: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly start: {
+                        readonly type: "string";
+                        readonly description: "YYYY-MM-DD";
+                    };
+                    readonly end: {
+                        readonly type: "string";
+                        readonly description: "YYYY-MM-DD";
+                    };
+                };
+                readonly required: readonly ["start", "end"];
+                readonly description: "Cohort date range — MUST be an object { start, end }, NOT an array or string.";
+            };
+            readonly granularity: {
+                readonly type: "string";
+                readonly enum: readonly ["day", "week", "month"];
+                readonly description: "Period size for retention buckets";
+            };
+            readonly periods: {
+                readonly type: "number";
+                readonly description: "Number of retention periods to calculate";
+            };
+            readonly retentionType: {
+                readonly type: "string";
+                readonly enum: readonly ["classic", "rolling"];
+                readonly description: "classic = returned in period N exactly; rolling = returned in period N or later";
+            };
+            readonly cohortFilters: {
+                readonly description: "Optional filters on cohort entry events";
+            };
+            readonly activityFilters: {
+                readonly description: "Optional filters on return activity events";
+            };
+            readonly breakdownDimensions: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Segment retention by these dimensions (e.g., [\"Events.country\"])";
+            };
+        };
+        readonly required: readonly ["timeDimension", "bindingKey", "dateRange", "granularity", "periods"];
+        readonly description: "Retention (cohort) analysis. When provided, measures/dimensions are ignored.";
+    };
+};
+/**
+ * TypeScript DSL reference for query construction.
+ * Used in MCP prompts and agent system prompt as the authoritative query language spec.
+ */
+export declare const QUERY_LANGUAGE_REFERENCE: string;

package/dist/server/server/ai/schemas.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Generic query schemas for AI agents
+ * Teaches AI how to construct analysis queries
+ *
+ * These schemas are returned by the `discover` tool to help LLMs
+ * understand the correct query shape for each analysis mode.
+ */
+export declare const QUERY_SCHEMAS: {
+    readonly funnel: {
+        readonly description: "Track conversion through sequential steps. Entities (identified by bindingKey) move through ordered steps.";
+        readonly structure: {
+            readonly funnel: {
+                readonly bindingKey: "Cube.dimension - identifies entities moving through funnel";
+                readonly timeDimension: "Cube.dimension - time field for ordering events";
+                readonly steps: readonly [{
+                    readonly name: "string - human readable step name";
+                    readonly filter: "{ member, operator, values } or array of filters. Put inDateRange ONLY on step 0.";
+                    readonly timeToConvert: "optional - ISO 8601 duration e.g. \"P7D\" for 7 days, \"PT1H\" for 1 hour";
+                }];
+                readonly includeTimeMetrics: "optional boolean - include avg/median/p90 time-to-convert";
+                readonly globalTimeWindow: "optional - ISO 8601 duration, all steps must complete within this window";
+            };
+        };
+    };
+    readonly flow: {
+        readonly description: "Analyze paths users take before/after a specific event. Shows event sequences as Sankey/sunburst.";
+        readonly structure: {
+            readonly flow: {
+                readonly bindingKey: "Cube.dimension - identifies entities";
+                readonly timeDimension: "Cube.dimension - time field for ordering";
+                readonly eventDimension: "Cube.dimension - the event type field (values become node labels)";
+                readonly startingStep: {
+                    readonly name: "string - display name for the starting step";
+                    readonly filter: "{ member, operator, values } - filter identifying the starting event";
+                };
+                readonly stepsBefore: "number (0-5) - how many steps to show before starting step";
+                readonly stepsAfter: "number (0-5) - how many steps to show after starting step";
+                readonly entityLimit: "optional number - max entities to process (performance)";
+                readonly outputMode: "optional \"sankey\" | \"sunburst\" (default: sankey)";
+            };
+        };
+    };
+    readonly retention: {
+        readonly description: "Measure how many users return over time periods after initial activity.";
+        readonly structure: {
+            readonly retention: {
+                readonly timeDimension: "Cube.dimension - time field for cohort assignment";
+                readonly bindingKey: "Cube.dimension - identifies entities";
+                readonly dateRange: {
+                    readonly start: "YYYY-MM-DD - cohort start date";
+                    readonly end: "YYYY-MM-DD - cohort end date";
+                };
+                readonly granularity: "day | week | month - period size";
+                readonly periods: "number - how many periods to analyze";
+                readonly retentionType: "\"classic\" (returned in period N) | \"rolling\" (returned in N or later)";
+                readonly cohortFilters: "optional - filters on cohort entry events";
+                readonly activityFilters: "optional - filters on return activity events";
+                readonly breakdownDimensions: "optional string[] - segment by these dimensions";
+            };
+        };
+    };
+};
+export type QuerySchemas = typeof QUERY_SCHEMAS;

package/dist/server/server/ai/suggestion-helpers.d.ts

@@ -0,0 +1,33 @@
+import { CubeMetadata } from '../types/metadata';
+/** Format a Date as a YYYY-MM-DD string (UTC). */
+export declare function formatDate(d: Date): string;
+/** Resolve a numeric "last N days/weeks/months" expression. */
+export declare function parseRelativeNExpression(n: number, lowerText: string): {
+    dateRange: [string, string];
+    granularity?: string;
+} | null;
+/** Resolve a "Q1".."Q4" quarter expression for the current year. */
+export declare function parseQuarterExpression(quarterMatch: string): {
+    dateRange: [string, string];
+    granularity?: string;
+};
+/**
+ * Match measures in the primary cube against keywords in the text.
+ * Mutates `measures`/`reasoning` and returns the confidence delta to apply.
+ */
+export declare function matchMeasuresInText(primaryCube: CubeMetadata, lowerText: string, measures: string[], reasoning: string[]): number;
+/** Aggregation intent shape produced by detectAggregationIntent. */
+export interface AggregationIntent {
+    type: 'sum' | 'count' | 'avg' | 'max' | 'min';
+    confidence: number;
+}
+/**
+ * Backfill measures when none matched directly, using the aggregation intent.
+ * Mutates `measures`/`reasoning`.
+ */
+export declare function applyAggregationFallback(primaryCube: CubeMetadata, aggregationIntent: AggregationIntent, measures: string[], reasoning: string[]): void;
+/**
+ * Resolve grouping dimensions from grouping keywords and explicit "by/per X" text.
+ * Mutates `dimensions`/`reasoning` and returns the confidence delta to apply.
+ */
+export declare function matchDimensions(relevantCubes: CubeMetadata[], groupingKeywords: string[], lowerText: string, dimensions: string[], reasoning: string[]): number;

package/dist/server/server/ai/suggestion.d.ts

@@ -0,0 +1,16 @@
+import { CubeMetadata } from '../types/metadata';
+import { SemanticQuery } from '../types/query';
+/**
+ * Suggested query result
+ */
+export interface QuerySuggestion {
+    query: Partial<SemanticQuery>;
+    confidence: number;
+    reasoning: string[];
+    warnings?: string[];
+    /** Detected analysis mode */
+    analysisMode: 'query' | 'funnel' | 'flow' | 'retention';
+    /** Next steps when mode != 'query' */
+    nextSteps?: string[];
+}
+export declare function suggestQuery(metadata: CubeMetadata[], naturalLanguage: string, targetCube?: string): QuerySuggestion;

package/dist/server/server/ai/validation-helpers.d.ts

@@ -0,0 +1,21 @@
+import { TranslationKey } from '../../i18n/types';
+import { CubeMetadata } from '../types/metadata';
+import { SemanticQuery, Filter } from '../types/query';
+import { ValidationError, ValidationWarning } from './validation';
+/** Validate that a required event-stream field is present and (if a string) a valid dimension. */
+export declare function validateRequiredDimensionField(value: unknown, missingMessageKey: TranslationKey, validateDimension: (dimension: string, errors: ValidationError[]) => void, errors: ValidationError[]): void;
+/** Apply field-name corrections to a measures/dimensions string array. */
+export declare function applyCorrectionsToList(list: string[], corrections: Map<string, string>): string[];
+/** Build the corrected query by applying field corrections (returns undefined if none). */
+export declare function buildCorrectedQuery(query: SemanticQuery, corrections: Map<string, string>): SemanticQuery | undefined;
+/** Push performance/best-practice warnings for an oversized standard query. */
+export declare function collectPerformanceWarnings(query: SemanticQuery, warnings: ValidationWarning[]): void;
+/** Warn when a declared time dimension is not actually of time type. */
+export declare function checkTimeDimensionType(dimensionRef: string, metadata: CubeMetadata[], warnings: ValidationWarning[]): void;
+/** Validate a single member-style filter (cube + field existence). */
+export declare function validateMemberFilter(filter: Extract<Filter, {
+    member: string;
+}>, metadata: CubeMetadata[], errors: ValidationError[], corrections: Map<string, string>, findClosestField: (fieldName: string, available: string[]) => {
+    field: string;
+    distance: number;
+} | null): void;

package/dist/server/server/ai/validation.d.ts

@@ -0,0 +1,31 @@
+import { CubeMetadata } from '../types/metadata';
+import { SemanticQuery } from '../types/query';
+/**
+ * Validation result with corrections
+ */
+export interface ValidationResult {
+    isValid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+    correctedQuery?: SemanticQuery;
+}
+/**
+ * Validation error with optional correction
+ */
+export interface ValidationError {
+    type: 'cube_not_found' | 'measure_not_found' | 'dimension_not_found' | 'invalid_filter' | 'invalid_time_dimension' | 'syntax_error';
+    message: string;
+    field?: string;
+    suggestion?: string;
+    correctedValue?: string;
+}
+/**
+ * Validation warning (query will work but may have issues)
+ */
+export interface ValidationWarning {
+    type: 'ambiguous_field' | 'performance' | 'best_practice';
+    message: string;
+    field?: string;
+    suggestion?: string;
+}
+export declare function validateQuery(query: SemanticQuery, metadata: CubeMetadata[]): ValidationResult;