drizzle-cube 0.5.6 → 0.5.8

package/dist/server/server/agent/tools.d.ts

@@ -0,0 +1,28 @@
+import { SemanticLayerCompiler } from '../compiler';
+import { SecurityContext } from '../types';
+import { AgentSSEEvent } from './types';
+import { ToolDefinition } from './providers/types';
+/**
+ * Result of executing a tool call
+ */
+export interface ToolExecutionResult {
+    /** String content to return as tool_result */
+    result: string;
+    /** Whether the tool call errored */
+    isError?: boolean;
+    /** Optional SSE event to emit as a side effect (add_portlet, add_markdown) */
+    sideEffect?: AgentSSEEvent;
+}
+/**
+ * Returns the array of tool definitions for the Anthropic Messages API.
+ * Plain JSON schema — no Zod dependency.
+ */
+export declare function getToolDefinitions(): ToolDefinition[];
+/**
+ * Create a tool executor map that closes over the semantic layer and security context.
+ * Returns a Map<toolName, handler> where each handler takes parsed input and returns a result.
+ */
+export declare function createToolExecutor(options: {
+    semanticLayer: SemanticLayerCompiler;
+    securityContext: SecurityContext;
+}): Map<string, (input: Record<string, unknown>) => Promise<ToolExecutionResult>>;

package/dist/server/server/agent/types.d.ts

@@ -0,0 +1,192 @@
+import { ChartType, ChartAxisConfig, ChartDisplayConfig, DashboardConfig } from '../../client/types';
+/**
+ * A tool call from a prior conversation turn (for history replay)
+ */
+export interface AgentHistoryToolCall {
+    id: string;
+    name: string;
+    input?: unknown;
+    result?: unknown;
+    status: 'running' | 'complete' | 'error';
+}
+/**
+ * A message from a prior conversation (for history replay)
+ */
+export interface AgentHistoryMessage {
+    role: 'user' | 'assistant';
+    content: string;
+    toolCalls?: AgentHistoryToolCall[];
+}
+/**
+ * Request body for the agent chat endpoint
+ */
+export interface AgentChatRequest {
+    /** User message to send to the agent */
+    message: string;
+    /** Session ID for multi-turn conversations */
+    sessionId?: string;
+    /** Prior conversation history for session continuity (e.g. after notebook reload) */
+    history?: AgentHistoryMessage[];
+}
+/**
+ * Observability hooks for tracing agent chat lifecycle events.
+ * Called synchronously (fire-and-forget) — implementations should not throw.
+ */
+export interface AgentObservabilityHooks {
+    /** Called once when agent chat starts */
+    onChatStart?: (event: {
+        traceId: string;
+        sessionId?: string;
+        message: string;
+        model: string;
+        historyLength: number;
+    }) => void;
+    /** Called after each LLM API call completes */
+    onGenerationEnd?: (event: {
+        traceId: string;
+        turn: number;
+        model: string;
+        stopReason: string;
+        inputTokens?: number;
+        outputTokens?: number;
+        durationMs: number;
+        /** Messages array sent to the API */
+        input?: unknown;
+        /** Assistant content blocks from the response */
+        output?: unknown;
+    }) => void;
+    /** Called after each tool execution */
+    onToolEnd?: (event: {
+        traceId: string;
+        turn: number;
+        toolName: string;
+        toolUseId: string;
+        isError: boolean;
+        durationMs: number;
+    }) => void;
+    /** Called when agent chat completes */
+    onChatEnd?: (event: {
+        traceId: string;
+        sessionId?: string;
+        totalTurns: number;
+        durationMs: number;
+        error?: string;
+    }) => void;
+}
+/**
+ * Agent configuration options (provided in adapter options).
+ * Supports multiple LLM providers — defaults to Anthropic for backward compatibility.
+ * All providers use direct HTTP API calls — no subprocess spawning, fully edge-runtime compatible.
+ */
+export interface AgentConfig {
+    /**
+     * LLM provider to use (default: 'anthropic').
+     * - 'anthropic': Claude models via @anthropic-ai/sdk
+     * - 'openai': OpenAI models via openai SDK (also supports Groq, Together, Mistral, Ollama via baseURL)
+     * - 'google': Gemini models via @google/generative-ai
+     */
+    provider?: 'anthropic' | 'openai' | 'google';
+    /**
+     * Base URL for OpenAI-compatible providers.
+     * Only used when provider is 'openai'. Examples:
+     * - Groq: 'https://api.groq.com/openai/v1'
+     * - Together: 'https://api.together.xyz/v1'
+     * - Ollama: 'http://localhost:11434/v1'
+     */
+    baseURL?: string;
+    /** Server-side API key for the selected provider */
+    apiKey?: string;
+    /** Model to use (default depends on provider: 'claude-sonnet-4-6' for Anthropic, 'gpt-4.1-mini' for OpenAI, 'gemini-3-flash-preview' for Google) */
+    model?: string;
+    /** Maximum agentic turns per request (default: 25) */
+    maxTurns?: number;
+    /** Maximum tokens per response (default: 4096) */
+    maxTokens?: number;
+    /** Allow X-Agent-Api-Key header to override server apiKey */
+    allowClientApiKey?: boolean;
+    /** Optional observability hooks for tracing */
+    observability?: AgentObservabilityHooks;
+    /**
+     * Build per-request system context for the LLM prompt from the authenticated security context.
+     * Called on every agent chat request with the resolved security context.
+     * The returned string is appended to the system prompt under "## User Context".
+     *
+     * @example
+     * buildSystemContext: (securityContext) =>
+     *   `User: ${securityContext.userName}, Role: ${securityContext.role}`
+     */
+    buildSystemContext?: (securityContext: Record<string, unknown>) => string | undefined;
+}
+/**
+ * Data for an add_portlet tool call
+ */
+export interface PortletBlockData {
+    id: string;
+    title: string;
+    query: string;
+    chartType: ChartType;
+    chartConfig?: ChartAxisConfig;
+    displayConfig?: ChartDisplayConfig;
+}
+/**
+ * Data for an add_markdown tool call
+ */
+export interface MarkdownBlockData {
+    id: string;
+    title?: string;
+    content: string;
+}
+/**
+ * Data emitted when the agent saves a dashboard via the save_as_dashboard tool.
+ * The client receives this via SSE and can persist the config however it chooses.
+ */
+export interface DashboardSavedData {
+    title: string;
+    description?: string;
+    dashboardConfig: DashboardConfig;
+}
+/**
+ * SSE events emitted by the agent handler
+ */
+export type AgentSSEEvent = {
+    type: 'text_delta';
+    data: string;
+} | {
+    type: 'tool_use_start';
+    data: {
+        id: string;
+        name: string;
+        input?: unknown;
+    };
+} | {
+    type: 'tool_use_result';
+    data: {
+        id: string;
+        name: string;
+        result?: unknown;
+        isError?: boolean;
+    };
+} | {
+    type: 'add_portlet';
+    data: PortletBlockData;
+} | {
+    type: 'add_markdown';
+    data: MarkdownBlockData;
+} | {
+    type: 'dashboard_saved';
+    data: DashboardSavedData;
+} | {
+    type: 'turn_complete';
+    data: Record<string, never>;
+} | {
+    type: 'done';
+    data: {
+        sessionId: string;
+        traceId?: string;
+    };
+} | {
+    type: 'error';
+    data: {
+        message: string;
+    };
+};

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

@@ -0,0 +1,62 @@
+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;
+}
+/**
+ * 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;