drizzle-cube 0.5.7 → 0.5.8

package/dist/server/server/adapters/postgres-adapter.d.ts

@@ -0,0 +1,119 @@
+import { SQL, AnyColumn } from 'drizzle-orm';
+import { TimeGranularity } from '../types';
+import { BaseDatabaseAdapter, DatabaseCapabilities, WindowFunctionType, WindowFunctionConfig } from './base-adapter';
+export declare class PostgresAdapter extends BaseDatabaseAdapter {
+    getEngineType(): 'postgres';
+    /**
+     * PostgreSQL supports LATERAL joins since version 9.3
+     */
+    supportsLateralJoins(): boolean;
+    /**
+     * Build PostgreSQL INTERVAL from ISO 8601 duration
+     * PostgreSQL supports INTERVAL literal syntax: INTERVAL '7 days'
+     */
+    buildIntervalFromISO(duration: string): SQL;
+    /**
+     * Build PostgreSQL time difference in seconds using EXTRACT(EPOCH FROM ...)
+     * Returns (end - start) as seconds
+     */
+    buildTimeDifferenceSeconds(end: SQL, start: SQL): SQL;
+    /**
+     * Build PostgreSQL timestamp + interval expression
+     */
+    buildDateAddInterval(timestamp: SQL, duration: string): SQL;
+    /**
+     * Build PostgreSQL conditional aggregation using FILTER clause
+     * PostgreSQL supports the standard SQL FILTER clause for efficient conditional aggregation
+     * Example: AVG(time_diff) FILTER (WHERE step_1_time IS NOT NULL)
+     */
+    buildConditionalAggregation(aggFn: 'count' | 'avg' | 'min' | 'max' | 'sum', expr: SQL | null, condition: SQL): SQL;
+    /**
+     * Build PostgreSQL date difference in periods using AGE and EXTRACT
+     * For retention analysis period calculations
+     */
+    buildDateDiffPeriods(startDate: SQL, endDate: SQL, unit: 'day' | 'week' | 'month'): SQL;
+    /**
+     * Build PostgreSQL period series using generate_series
+     * PostgreSQL's generate_series returns a set directly usable as a table
+     */
+    buildPeriodSeriesSubquery(maxPeriod: number): SQL;
+    /**
+     * Build PostgreSQL time dimension using DATE_TRUNC function
+     * Extracted from executor.ts:649-670 and multi-cube-builder.ts:306-320
+     */
+    buildTimeDimension(granularity: TimeGranularity, fieldExpr: AnyColumn | SQL): SQL;
+    /**
+     * Build PostgreSQL string matching conditions using ILIKE (case-insensitive)
+     * Extracted from executor.ts:807-813 and multi-cube-builder.ts:468-474
+     */
+    buildStringCondition(fieldExpr: AnyColumn | SQL, operator: 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'like' | 'notLike' | 'ilike' | 'regex' | 'notRegex', value: string): SQL;
+    /**
+     * Build PostgreSQL type casting using :: syntax
+     * Extracted from various locations where ::timestamp was used
+     */
+    castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Build PostgreSQL AVG aggregation with COALESCE for NULL handling
+     * PostgreSQL AVG returns NULL for empty sets, so we use COALESCE for consistent behavior
+     * Extracted from multi-cube-builder.ts:284
+     */
+    buildAvg(fieldExpr: AnyColumn | SQL): SQL;
+    /**
+     * Build PostgreSQL CASE WHEN conditional expression
+     */
+    buildCaseWhen(conditions: Array<{
+        when: SQL;
+        then: any;
+    }>, elseValue?: any): SQL;
+    /**
+     * Build PostgreSQL boolean literal
+     * PostgreSQL uses TRUE/FALSE keywords
+     */
+    buildBooleanLiteral(value: boolean): SQL;
+    /**
+     * Convert filter values - PostgreSQL uses native types
+     * No conversion needed for PostgreSQL
+     */
+    convertFilterValue(value: any): any;
+    /**
+     * Prepare date value for PostgreSQL
+     * PostgreSQL accepts Date objects directly
+     */
+    prepareDateValue(date: Date): any;
+    /**
+     * PostgreSQL stores timestamps as native timestamp types
+     */
+    isTimestampInteger(): boolean;
+    /**
+     * PostgreSQL time dimensions already return proper values
+     * No conversion needed
+     */
+    convertTimeDimensionResult(value: any): any;
+    /**
+     * PostgreSQL has full support for statistical and window functions
+     */
+    getCapabilities(): DatabaseCapabilities;
+    /**
+     * Build PostgreSQL STDDEV aggregation
+     * Uses STDDEV_POP for population, STDDEV_SAMP for sample
+     */
+    buildStddev(fieldExpr: AnyColumn | SQL, useSample?: boolean): SQL;
+    /**
+     * Build PostgreSQL VARIANCE aggregation
+     * Uses VAR_POP for population, VAR_SAMP for sample
+     */
+    buildVariance(fieldExpr: AnyColumn | SQL, useSample?: boolean): SQL;
+    /**
+     * Build PostgreSQL PERCENTILE_CONT aggregation
+     * Uses ordered-set aggregate function
+     */
+    buildPercentile(fieldExpr: AnyColumn | SQL, percentile: number): SQL;
+    /**
+     * Build PostgreSQL window function expression
+     * PostgreSQL has full window function support
+     */
+    buildWindowFunction(type: WindowFunctionType, fieldExpr: AnyColumn | SQL | null, partitionBy?: (AnyColumn | SQL)[], orderBy?: Array<{
+        field: AnyColumn | SQL;
+        direction: 'asc' | 'desc';
+    }>, config?: WindowFunctionConfig): SQL;
+}

package/dist/server/server/adapters/singlestore-adapter.d.ts

@@ -0,0 +1,4 @@
+import { MySQLAdapter } from './mysql-adapter';
+export declare class SingleStoreAdapter extends MySQLAdapter {
+    getEngineType(): 'singlestore';
+}

package/dist/server/server/adapters/snowflake-adapter.d.ts

@@ -0,0 +1,116 @@
+import { SQL, AnyColumn } from 'drizzle-orm';
+import { TimeGranularity } from '../types';
+import { BaseDatabaseAdapter, DatabaseCapabilities, WindowFunctionType, WindowFunctionConfig } from './base-adapter';
+export declare class SnowflakeAdapter extends BaseDatabaseAdapter {
+    getEngineType(): 'snowflake';
+    /**
+     * Snowflake supports LATERAL joins
+     */
+    supportsLateralJoins(): boolean;
+    /**
+     * Build Snowflake INTERVAL from ISO 8601 duration
+     * Snowflake doesn't support INTERVAL literal syntax directly in all contexts,
+     * so we chain DATEADD calls. For standalone interval expressions, we return
+     * a DATEADD chain applied to TIMESTAMP '1970-01-01' and subtract it back.
+     * However, buildIntervalFromISO is typically used with buildDateAddInterval,
+     * so we return a structured representation.
+     */
+    buildIntervalFromISO(duration: string): SQL;
+    /**
+     * Build Snowflake time difference in seconds
+     * Uses DATEDIFF('SECOND', start, end)
+     */
+    buildTimeDifferenceSeconds(end: SQL, start: SQL): SQL;
+    /**
+     * Build Snowflake timestamp + interval expression
+     * Uses chained DATEADD(unit, amount, timestamp) calls
+     */
+    buildDateAddInterval(timestamp: SQL, duration: string): SQL;
+    /**
+     * Build Snowflake conditional aggregation using CASE WHEN
+     * Snowflake supports FILTER clause but CASE WHEN is more portable
+     */
+    buildConditionalAggregation(aggFn: 'count' | 'avg' | 'min' | 'max' | 'sum', expr: SQL | null, condition: SQL): SQL;
+    /**
+     * Build Snowflake date difference in periods using DATEDIFF
+     */
+    buildDateDiffPeriods(startDate: SQL, endDate: SQL, unit: 'day' | 'week' | 'month'): SQL;
+    /**
+     * Build Snowflake period series using TABLE(GENERATOR(ROWCOUNT => n)) + ROW_NUMBER()
+     */
+    buildPeriodSeriesSubquery(maxPeriod: number): SQL;
+    /**
+     * Build Snowflake time dimension using DATE_TRUNC function
+     * Snowflake supports DATE_TRUNC with quoted granularity like PostgreSQL
+     */
+    buildTimeDimension(granularity: TimeGranularity, fieldExpr: AnyColumn | SQL): SQL;
+    /**
+     * Build Snowflake string matching conditions using native ILIKE
+     * Snowflake supports ILIKE natively
+     */
+    buildStringCondition(fieldExpr: AnyColumn | SQL, operator: 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'like' | 'notLike' | 'ilike' | 'regex' | 'notRegex', value: string): SQL;
+    /**
+     * Build Snowflake type casting using :: syntax
+     * Snowflake supports both :: syntax and CAST() function
+     */
+    castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Build Snowflake AVG aggregation with COALESCE for NULL handling
+     */
+    buildAvg(fieldExpr: AnyColumn | SQL): SQL;
+    /**
+     * Build Snowflake CASE WHEN conditional expression
+     */
+    buildCaseWhen(conditions: Array<{
+        when: SQL;
+        then: any;
+    }>, elseValue?: any): SQL;
+    /**
+     * Build Snowflake boolean literal
+     * Snowflake uses TRUE/FALSE keywords
+     */
+    buildBooleanLiteral(value: boolean): SQL;
+    /**
+     * Convert filter values - Snowflake uses native types
+     */
+    convertFilterValue(value: any): any;
+    /**
+     * Prepare date value for Snowflake
+     * Snowflake accepts Date objects directly
+     */
+    prepareDateValue(date: Date): any;
+    /**
+     * Snowflake stores timestamps as native timestamp types
+     */
+    isTimestampInteger(): boolean;
+    /**
+     * Snowflake time dimensions already return proper values
+     */
+    convertTimeDimensionResult(value: any): any;
+    /**
+     * Snowflake capabilities - full SQL support
+     */
+    getCapabilities(): DatabaseCapabilities;
+    /**
+     * Build Snowflake STDDEV aggregation
+     */
+    buildStddev(fieldExpr: AnyColumn | SQL, useSample?: boolean): SQL;
+    /**
+     * Build Snowflake VARIANCE aggregation
+     * Snowflake supports native VAR_POP/VAR_SAMP
+     */
+    buildVariance(fieldExpr: AnyColumn | SQL, useSample?: boolean): SQL;
+    /**
+     * Build Snowflake PERCENTILE_CONT aggregation
+     * Uses ordered-set aggregate function
+     */
+    buildPercentile(fieldExpr: AnyColumn | SQL, percentile: number): SQL;
+    /**
+     * Build Snowflake window function expression
+     * Snowflake has full window function support
+     */
+    buildWindowFunction(type: WindowFunctionType, fieldExpr: AnyColumn | SQL | null, partitionBy?: (AnyColumn | SQL)[], orderBy?: Array<{
+        field: AnyColumn | SQL;
+        direction: 'asc' | 'desc';
+    }>, config?: WindowFunctionConfig): SQL;
+}

package/dist/server/server/adapters/sqlite-adapter.d.ts

@@ -0,0 +1,140 @@
+import { SQL, AnyColumn } from 'drizzle-orm';
+import { TimeGranularity } from '../types';
+import { BaseDatabaseAdapter, DatabaseCapabilities, WindowFunctionType, WindowFunctionConfig } from './base-adapter';
+export declare class SQLiteAdapter extends BaseDatabaseAdapter {
+    getEngineType(): 'sqlite';
+    /**
+     * SQLite does not support LATERAL joins
+     * Flow queries require LATERAL for efficient execution and are not supported on SQLite
+     */
+    supportsLateralJoins(): boolean;
+    /**
+     * Build SQLite INTERVAL from ISO 8601 duration
+     * SQLite doesn't have native interval types, so we convert to seconds
+     * for arithmetic operations on Unix timestamps
+     */
+    buildIntervalFromISO(duration: string): SQL;
+    /**
+     * Build SQLite time difference in seconds
+     * SQLite timestamps are stored as Unix seconds, so simple subtraction works
+     * Returns (end - start) as seconds
+     */
+    buildTimeDifferenceSeconds(end: SQL, start: SQL): SQL;
+    /**
+     * Build SQLite timestamp + interval expression
+     * Since SQLite stores timestamps as Unix seconds, just add the seconds
+     */
+    buildDateAddInterval(timestamp: SQL, duration: string): SQL;
+    /**
+     * Build SQLite conditional aggregation using CASE WHEN
+     * SQLite doesn't support FILTER clause, so we use CASE WHEN pattern
+     * Example: AVG(CASE WHEN step_1_time IS NOT NULL THEN time_diff END)
+     */
+    buildConditionalAggregation(aggFn: 'count' | 'avg' | 'min' | 'max' | 'sum', expr: SQL | null, condition: SQL): SQL;
+    /**
+     * Build SQLite date difference in periods
+     * SQLite uses Julian day calculations for date arithmetic
+     * Note: SQLite timestamps are stored as Unix seconds
+     */
+    buildDateDiffPeriods(startDate: SQL, endDate: SQL, unit: 'day' | 'week' | 'month'): SQL;
+    /**
+     * Build SQLite period series using recursive CTE
+     * SQLite 3.8.3+ supports recursive CTEs for generating sequences
+     */
+    buildPeriodSeriesSubquery(maxPeriod: number): SQL;
+    /**
+     * Build SQLite time dimension using date/datetime functions with modifiers
+     * For integer timestamp columns (milliseconds), first convert to datetime
+     * SQLite doesn't have DATE_TRUNC like PostgreSQL, so we use strftime and date modifiers
+     * Returns datetime strings for consistency with other databases
+     */
+    buildTimeDimension(granularity: TimeGranularity, fieldExpr: AnyColumn | SQL): SQL;
+    /**
+     * Build SQLite string matching conditions using LOWER() + LIKE for case-insensitive matching
+     * SQLite LIKE is case-insensitive by default, but LOWER() ensures consistency
+     */
+    buildStringCondition(fieldExpr: AnyColumn | SQL, operator: 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'like' | 'notLike' | 'ilike' | 'regex' | 'notRegex', value: string): SQL;
+    /**
+     * Build SQLite type casting using CAST() function
+     * SQLite has dynamic typing but supports CAST for consistency
+     */
+    castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Build SQLite AVG aggregation with IFNULL for NULL handling
+     * SQLite AVG returns NULL for empty sets, using IFNULL for consistency
+     */
+    buildAvg(fieldExpr: AnyColumn | SQL): SQL;
+    /**
+     * Build SQLite CASE WHEN conditional expression
+     */
+    buildCaseWhen(conditions: Array<{
+        when: SQL;
+        then: any;
+    }>, elseValue?: any): SQL;
+    /**
+     * Build SQLite boolean literal
+     * SQLite uses 1/0 for true/false
+     */
+    buildBooleanLiteral(value: boolean): SQL;
+    /**
+     * Preprocess calculated measure templates for SQLite-specific handling
+     *
+     * SQLite performs integer division by default (5/2 = 2 instead of 2.5).
+     * This method wraps division operands with CAST to REAL to ensure float division.
+     *
+     * Pattern matched: {measure1} / {measure2} or {measure1} / NULLIF({measure2}, 0)
+     * Transforms to: CAST({measure1} AS REAL) / ...
+     *
+     * @param calculatedSql - Template string with {member} references
+     * @returns Preprocessed template with CAST for division operations
+     */
+    preprocessCalculatedTemplate(calculatedSql: string): string;
+    /**
+     * Convert filter values to SQLite-compatible types
+     * SQLite doesn't support boolean types - convert boolean to integer (1/0)
+     * Convert Date objects to milliseconds for integer timestamp columns
+     */
+    convertFilterValue(value: any): any;
+    /**
+     * Prepare date value for SQLite integer timestamp storage
+     * Convert Date objects to milliseconds (Unix timestamp * 1000)
+     */
+    prepareDateValue(date: Date): any;
+    /**
+     * SQLite stores timestamps as integers (milliseconds)
+     */
+    isTimestampInteger(): boolean;
+    /**
+     * Convert SQLite time dimension results back to Date objects
+     * SQLite time dimensions return datetime strings, but clients expect Date objects
+     */
+    convertTimeDimensionResult(value: any): any;
+    /**
+     * SQLite has limited statistical support (no native STDDEV/VARIANCE/PERCENTILE)
+     * but supports window functions since SQLite 3.25
+     */
+    getCapabilities(): DatabaseCapabilities;
+    /**
+     * SQLite does not have native STDDEV
+     * Returns null for graceful degradation
+     */
+    buildStddev(_fieldExpr: AnyColumn | SQL, _useSample?: boolean): SQL | null;
+    /**
+     * SQLite does not have native VARIANCE
+     * Returns null for graceful degradation
+     */
+    buildVariance(_fieldExpr: AnyColumn | SQL, _useSample?: boolean): SQL | null;
+    /**
+     * SQLite does not have native PERCENTILE
+     * Returns null for graceful degradation
+     */
+    buildPercentile(_fieldExpr: AnyColumn | SQL, _percentile: number): SQL | null;
+    /**
+     * Build SQLite window function expression
+     * SQLite 3.25+ supports window functions
+     */
+    buildWindowFunction(type: WindowFunctionType, fieldExpr: AnyColumn | SQL | null, partitionBy?: (AnyColumn | SQL)[], orderBy?: Array<{
+        field: AnyColumn | SQL;
+        direction: 'asc' | 'desc';
+    }>, config?: WindowFunctionConfig): SQL;
+}

package/dist/server/server/agent/chart-validation.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Chart Config Validation for Agent Tool
+ *
+ * Validates chartConfig against drop zone requirements defined in the chart config registry.
+ * Auto-infers missing fields from the query structure.
+ * Builds per-chart-type guidance for the tool description.
+ */
+interface ValidationResult {
+    isValid: boolean;
+    errors: string[];
+}
+/**
+ * Validate chartConfig against the chart type's drop zone requirements.
+ */
+export declare function validateChartConfig(chartType: string, chartConfig: Record<string, unknown> | undefined, _query: Record<string, unknown>): ValidationResult;
+/**
+ * Auto-infer missing chartConfig fields from the query structure.
+ * Fills in xAxis, yAxis, series, sizeField, etc. based on query measures/dimensions
+ * and the chart type's drop zone acceptTypes.
+ */
+export declare function inferChartConfig(chartType: string, chartConfig: Record<string, unknown> | undefined, query: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Build per-chart-type requirements text for the agent tool description.
+ * Includes description, useCase, and drop zone requirements for each chart type.
+ */
+export declare function buildChartRequirementsDescription(allowedChartTypes: string[]): string;
+export {};

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

@@ -0,0 +1,25 @@
+import { SemanticLayerCompiler } from '../compiler';
+import { SecurityContext } from '../types';
+import { AgentConfig, AgentSSEEvent, AgentHistoryMessage } from './types';
+/**
+ * Handle an agent chat request, yielding SSE events as the agent works.
+ *
+ * Uses the configured LLM provider with streaming for edge-runtime compatibility.
+ * Implements a manual agentic loop: send messages → stream response → execute
+ * tool calls → append results → repeat until the model stops requesting tools.
+ */
+export declare function handleAgentChat(options: {
+    message: string;
+    sessionId?: string;
+    history?: AgentHistoryMessage[];
+    semanticLayer: SemanticLayerCompiler;
+    securityContext: SecurityContext;
+    agentConfig: AgentConfig;
+    apiKey: string;
+    /** Per-request context appended to the system prompt (e.g. user info, tenant context) */
+    systemContext?: string;
+    /** Per-request overrides from client headers (take precedence over agentConfig) */
+    providerOverride?: string;
+    modelOverride?: string;
+    baseURLOverride?: string;
+}): AsyncGenerator<AgentSSEEvent>;

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

@@ -0,0 +1,11 @@
+/**
+ * Agent Module - Public Exports
+ * Agentic AI notebook handler for drizzle-cube
+ */
+export { handleAgentChat } from './handler';
+export { getToolDefinitions, createToolExecutor } from './tools';
+export type { ToolExecutionResult } from './tools';
+export { buildAgentSystemPrompt } from './system-prompt';
+export { createProvider } from './providers';
+export type { LLMProvider, ProviderName } from './providers';
+export type { AgentChatRequest, AgentConfig, AgentObservabilityHooks, AgentSSEEvent, AgentHistoryMessage, AgentHistoryToolCall, PortletBlockData, MarkdownBlockData, DashboardSavedData } from './types';

package/dist/server/server/agent/providers/anthropic.d.ts

@@ -0,0 +1,24 @@
+import { LLMProvider, ToolDefinition, InternalMessage, ToolResult, NormalizedEvent } from './types';
+export declare class AnthropicProvider implements LLMProvider {
+    private client;
+    constructor(apiKey: string);
+    private apiKey;
+    private initialized;
+    private ensureClient;
+    createStream(params: {
+        model: string;
+        maxTokens: number;
+        system: string;
+        tools: ToolDefinition[];
+        messages: InternalMessage[];
+    }): Promise<AsyncIterable<unknown>>;
+    parseStreamEvents(stream: AsyncIterable<unknown>): AsyncGenerator<NormalizedEvent>;
+    formatTools(tools: ToolDefinition[]): unknown[];
+    formatMessages(messages: InternalMessage[], system: string): {
+        messages: unknown[];
+        system?: string;
+    };
+    formatToolResults(results: ToolResult[]): unknown;
+    shouldContinue(stopReason: string): boolean;
+    formatError(error: unknown): string;
+}

package/dist/server/server/agent/providers/factory.d.ts

@@ -0,0 +1,12 @@
+import { LLMProvider } from './types';
+export type ProviderName = 'anthropic' | 'openai' | 'google';
+/**
+ * Create an LLM provider instance.
+ *
+ * @param provider - Provider name ('anthropic', 'openai', 'google')
+ * @param apiKey - API key for the provider
+ * @param options - Optional configuration (e.g. baseURL for OpenAI-compatible services)
+ */
+export declare function createProvider(provider: ProviderName, apiKey: string, options?: {
+    baseURL?: string;
+}): Promise<LLMProvider>;

package/dist/server/server/agent/providers/google.d.ts

@@ -0,0 +1,23 @@
+import { LLMProvider, ToolDefinition, InternalMessage, ToolResult, NormalizedEvent } from './types';
+export declare class GoogleProvider implements LLMProvider {
+    private apiKey;
+    private sdk;
+    private initialized;
+    constructor(apiKey: string);
+    private ensureSDK;
+    createStream(params: {
+        model: string;
+        maxTokens: number;
+        system: string;
+        tools: ToolDefinition[];
+        messages: InternalMessage[];
+    }): Promise<AsyncIterable<unknown>>;
+    parseStreamEvents(stream: AsyncIterable<unknown>): AsyncGenerator<NormalizedEvent>;
+    formatTools(tools: ToolDefinition[]): unknown[];
+    formatMessages(messages: InternalMessage[], _system: string): {
+        messages: unknown[];
+    };
+    formatToolResults(results: ToolResult[]): unknown;
+    shouldContinue(stopReason: string): boolean;
+    formatError(error: unknown): string;
+}

package/dist/server/server/agent/providers/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * LLM Provider exports
+ */
+export type { LLMProvider, ToolDefinition, InternalMessage, ContentBlock, ToolResult, NormalizedEvent } from './types';
+export type { ProviderName } from './factory';
+export { createProvider } from './factory';

package/dist/server/server/agent/providers/openai.d.ts

@@ -0,0 +1,26 @@
+import { LLMProvider, ToolDefinition, InternalMessage, ToolResult, NormalizedEvent } from './types';
+export declare class OpenAIProvider implements LLMProvider {
+    private client;
+    private apiKey;
+    private baseURL?;
+    private initialized;
+    constructor(apiKey: string, options?: {
+        baseURL?: string;
+    });
+    private ensureClient;
+    createStream(params: {
+        model: string;
+        maxTokens: number;
+        system: string;
+        tools: ToolDefinition[];
+        messages: InternalMessage[];
+    }): Promise<AsyncIterable<unknown>>;
+    parseStreamEvents(stream: AsyncIterable<unknown>): AsyncGenerator<NormalizedEvent>;
+    formatTools(tools: ToolDefinition[]): unknown[];
+    formatMessages(messages: InternalMessage[], system: string): {
+        messages: unknown[];
+    };
+    formatToolResults(results: ToolResult[]): unknown[];
+    shouldContinue(stopReason: string): boolean;
+    formatError(error: unknown): string;
+}

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

@@ -0,0 +1,95 @@
+/**
+ * LLM Provider Abstraction Types
+ * Provider-agnostic interfaces for multi-provider LLM support in the agentic notebook.
+ */
+/**
+ * Generic tool definition (provider-agnostic).
+ * Each provider's formatTools() wraps this in its own format.
+ */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/**
+ * Provider-agnostic internal message format.
+ * The handler uses this for the conversation history; providers convert on the way in/out.
+ */
+export interface InternalMessage {
+    role: 'user' | 'assistant' | 'tool_result';
+    content: string | ContentBlock[];
+}
+export interface ContentBlock {
+    type: 'text' | 'tool_use';
+    text?: string;
+    id?: string;
+    name?: string;
+    input?: Record<string, unknown>;
+    /** Provider-specific metadata (e.g. Gemini thoughtSignature) */
+    metadata?: Record<string, unknown>;
+}
+export interface ToolResult {
+    toolUseId: string;
+    /** Tool name — needed by some providers (e.g. Gemini's functionResponse) */
+    toolName?: string;
+    content: string;
+    isError?: boolean;
+}
+/**
+ * Normalized stream events consumed by the handler's agentic loop.
+ * Every provider must emit these — the handler never sees raw provider events.
+ */
+export type NormalizedEvent = {
+    type: 'text_delta';
+    text: string;
+} | {
+    type: 'tool_use_start';
+    id: string;
+    name: string;
+    metadata?: Record<string, unknown>;
+} | {
+    type: 'tool_input_delta';
+    json: string;
+} | {
+    type: 'tool_use_end';
+    id?: string;
+    input?: Record<string, unknown>;
+} | {
+    type: 'message_meta';
+    inputTokens?: number;
+    outputTokens?: number;
+    stopReason: string;
+};
+/**
+ * The core provider interface.
+ * Each LLM provider implements these 7 methods to integrate with the agentic loop.
+ */
+export interface LLMProvider {
+    /** Create a streaming API call and return the raw iterable. */
+    createStream(params: {
+        model: string;
+        maxTokens: number;
+        system: string;
+        tools: ToolDefinition[];
+        messages: InternalMessage[];
+    }): Promise<AsyncIterable<unknown>>;
+    /** Parse the raw stream into normalized events the handler understands. */
+    parseStreamEvents(stream: AsyncIterable<unknown>): AsyncGenerator<NormalizedEvent>;
+    /** Convert generic tool definitions to provider-specific format. */
+    formatTools(tools: ToolDefinition[]): unknown[];
+    /** Convert internal messages + system prompt to provider-specific format. */
+    formatMessages(messages: InternalMessage[], system: string): {
+        messages: unknown[];
+        system?: string;
+    };
+    /** Convert tool results to provider-specific format for appending as a user message. */
+    formatToolResults(results: ToolResult[]): unknown;
+    /** Return true if the stop reason means the model wants to continue (tool use). */
+    shouldContinue(stopReason: string): boolean;
+    /** Format a provider-specific error into a user-friendly message. */
+    formatError(error: unknown): string;
+}

package/dist/server/server/agent/system-prompt.d.ts

@@ -0,0 +1,5 @@
+import { CubeMetadata } from '../types';
+/**
+ * Build the full system prompt for the agent
+ */
+export declare function buildAgentSystemPrompt(metadata: CubeMetadata[]): string;