drizzle-cube 0.4.5 → 0.4.8

package/dist/server/index.d.ts

@@ -1,5 +1,8 @@
 import { AnyColumn } from 'drizzle-orm';
 import { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
+import { ChartAxisConfig } from '../../client/types';
+import { ChartDisplayConfig } from '../../client/types';
+import { ChartType } from '../../client/types';
 import { MySql2Database } from 'drizzle-orm/mysql2';
 import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import { SQL } from 'drizzle-orm';
@@ -7,6 +10,75 @@ import { Subquery } from 'drizzle-orm';
 import { Table } from 'drizzle-orm';
 import { View } from 'drizzle-orm';
 
+/**
+ * Request body for the agent chat endpoint
+ */
+export declare interface AgentChatRequest {
+    /** User message to send to the agent */
+    message: string;
+    /** Session ID for multi-turn conversations */
+    sessionId?: string;
+}
+
+/**
+ * Agent configuration options (provided in adapter options).
+ * Uses `@anthropic-ai/sdk` (the standard Anthropic API client) for direct
+ * HTTP API calls — no subprocess spawning, fully edge-runtime compatible.
+ */
+export declare interface AgentConfig {
+    /** Server-side Anthropic API key */
+    apiKey?: string;
+    /** Model to use (default: 'claude-sonnet-4-6') */
+    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;
+}
+
+/**
+ * SSE events emitted by the agent handler
+ */
+export declare 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;
+    };
+} | {
+    type: 'add_portlet';
+    data: PortletBlockData;
+} | {
+    type: 'add_markdown';
+    data: MarkdownBlockData;
+} | {
+    type: 'turn_complete';
+    data: Record<string, never>;
+} | {
+    type: 'done';
+    data: {
+        sessionId: string;
+    };
+} | {
+    type: 'error';
+    data: {
+        message: string;
+    };
+};
+
 /**
  * AI-generated analysis of an execution plan
  */
@@ -92,6 +164,11 @@ export declare interface BaseQueryDefinition {
     where?: SQL;
 }
 
+/**
+ * Build the full system prompt for the agent
+ */
+export declare function buildAgentSystemPrompt(metadata: CubeMetadata[]): string;
+
 /**
  * Build the complete EXPLAIN analysis prompt with all context
  *
@@ -473,6 +550,15 @@ export declare function createPostgresExecutor(db: DrizzleDatabase, schema?: any
  */
 export declare function createSQLiteExecutor(db: DrizzleDatabase, schema?: any): SQLiteExecutor;
 
+/**
+ * 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>>;
+
 /**
  * CTEBuilder handles the construction of Common Table Expressions
  * for pre-aggregation in hasMany relationship queries.
@@ -2050,6 +2136,29 @@ export declare function getCubeInvalidationPattern(cubeName: string, keyPrefix?:
  */
 export declare function getJoinType(relationship: string, override?: string): string;
 
+/**
+ * Returns the array of tool definitions for the Anthropic Messages API.
+ * Plain JSON schema — no Zod dependency.
+ */
+export declare function getToolDefinitions(): ToolDefinition[];
+
+/**
+ * Handle an agent chat request, yielding SSE events as the agent works.
+ *
+ * Uses the Anthropic Messages API (`@anthropic-ai/sdk`) with `stream: true`
+ * (raw async iterable) for Cloudflare Workers / edge-runtime compatibility.
+ * Implements a manual agentic loop: send messages → stream response → execute
+ * tool calls → append results → repeat until stop_reason !== 'tool_use'.
+ */
+export declare function handleAgentChat(options: {
+    message: string;
+    sessionId?: string;
+    semanticLayer: SemanticLayerCompiler;
+    securityContext: SecurityContext;
+    agentConfig: AgentConfig;
+    apiKey: string;
+}): AsyncGenerator<AgentSSEEvent>;
+
 /**
  * Hierarchy definition for grouped drill-down paths
  * Groups dimensions into ordered levels for structured navigation
@@ -2743,6 +2852,15 @@ declare interface LogicalSchema {
     timeDimensions: TimeDimensionRef[];
 }
 
+/**
+ * Data for an add_markdown tool call
+ */
+export declare interface MarkdownBlockData {
+    id: string;
+    title?: string;
+    content: string;
+}
+
 /**
  * Measure definition
  */
@@ -3210,6 +3328,18 @@ export declare interface PlanOptimiser {
     optimise(plan: LogicalNode, context: OptimiserContext): LogicalNode;
 }
 
+/**
+ * Data for an add_portlet tool call
+ */
+export declare interface PortletBlockData {
+    id: string;
+    title: string;
+    query: string;
+    chartType: ChartType;
+    chartConfig?: ChartAxisConfig;
+    displayConfig?: ChartDisplayConfig;
+}
+
 /**
  * Type helpers for specific database types
  */
@@ -4600,6 +4730,31 @@ declare interface TimeDimensionRef {
 
 export declare type TimeGranularity = 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
 
+/**
+ * Anthropic API tool definition (JSON schema format)
+ */
+declare interface ToolDefinition {
+    name: string;
+    description: string;
+    input_schema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+
+/**
+ * Result of executing a tool call
+ */
+export declare 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;
+}
+
 /**
  * Window function configuration
  */