@querypanel/node-sdk 1.0.51 → 1.0.52

package/dist/index.d.cts

@@ -180,6 +180,7 @@ declare const QueryErrorCode: {
     readonly SQL_GENERATION_FAILED: "SQL_GENERATION_FAILED";
     readonly SQL_VALIDATION_FAILED: "SQL_VALIDATION_FAILED";
     readonly CONTEXT_RETRIEVAL_FAILED: "CONTEXT_RETRIEVAL_FAILED";
+    readonly CLARIFICATION_NEEDED: "CLARIFICATION_NEEDED";
     readonly INTERNAL_ERROR: "INTERNAL_ERROR";
     readonly AUTHENTICATION_REQUIRED: "AUTHENTICATION_REQUIRED";
     readonly VALIDATION_ERROR: "VALIDATION_ERROR";
@@ -208,6 +209,10 @@ declare class QueryPipelineError extends Error {
      * Check if this is any guardrail error (relevance or security)
      */
     isGuardrailError(): boolean;
+    /**
+     * Check if this is a clarification needed error (v2 pipeline)
+     */
+    isClarificationNeeded(): boolean;
 }
 
 type ParamValue = string | number | boolean | string[] | number[];
@@ -514,6 +519,40 @@ interface AskOptions {
      * Use this to reuse a previously returned session for follow-up prompts.
      */
     querypanelSessionId?: string;
+    /**
+     * Pipeline version to use for query generation.
+     * - "v1" (default): Original query pipeline
+     * - "v2": Improved pipeline with intent planning, hybrid retrieval, schema linking, and SQL reflection
+     */
+    pipeline?: "v1" | "v2";
+}
+/**
+ * Intent analysis result from the v2 pipeline.
+ */
+interface IntentResult {
+    intent: string;
+    confidence: number;
+    plan: {
+        tables: string[];
+        operations: string[];
+        filters: string[];
+        orderBy?: string;
+        limit?: number;
+    };
+    ambiguities: Array<{
+        issue: string;
+        suggestion: string;
+    }>;
+}
+/**
+ * Pipeline execution trace with step-level timing.
+ */
+interface PipelineTrace {
+    totalDurationMs: number;
+    steps: Array<{
+        step: string;
+        durationMs: number;
+    }>;
 }
 /**
  * Response returned after executing a query.
@@ -545,6 +584,10 @@ interface AskResponse {
     target_db?: string;
     /** QueryPanel session ID for follow-up queries. */
     querypanelSessionId?: string;
+    /** Intent analysis from v2 pipeline. */
+    intent?: IntentResult;
+    /** Pipeline execution trace from v2 pipeline. */
+    trace?: PipelineTrace;
 }
 declare function anonymizeResults(rows: Array<Record<string, unknown>>): Array<Record<string, string>>;
 
@@ -688,6 +731,12 @@ interface ChartModifyOptions {
     chartMaxRetries?: number;
     /** Chart generation method: 'vega-lite' or 'vizspec' */
     chartType?: "vega-lite" | "vizspec";
+    /**
+     * Pipeline version to use for SQL regeneration.
+     * - "v1" (default): Original query pipeline
+     * - "v2": Improved pipeline with intent planning, hybrid retrieval, schema linking, and SQL reflection
+     */
+    pipeline?: "v1" | "v2";
 }
 /**
  * Response from modifyChart(), extending AskResponse with modification metadata.
@@ -1283,4 +1332,4 @@ declare class QueryPanelSdkAPI {
     }, signal?: AbortSignal): Promise<void>;
 }
 
-export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, type ChartListOptions, type ChartModifyInput, type ChartModifyOptions, type ChartModifyResponse, type ChartSpec, type ChartType, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type EncodingHints, type FieldRef, type FieldRefInput, type FieldType, type IngestResponse, type MetricEncoding, type MetricField, type MetricSpec, type PaginatedResponse$1 as PaginatedResponse, type PaginationInfo$1 as PaginationInfo, type PaginationQuery$1 as PaginationQuery, type ParamRecord, type ParamValue, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryErrorCode, QueryErrorCode as QueryErrorCodeType, QueryPanelSdkAPI, QueryPipelineError, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, type SdkSession, type SdkSessionTurn, type SessionGetOptions, type SessionListOptions, type SessionUpdateInput, type SqlModifications, type StackingMode, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type ValueFormat, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecGeneratorInput, type VizSpecKind, type VizSpecResponse, type VizSpecResult, anonymizeResults };
+export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, type ChartListOptions, type ChartModifyInput, type ChartModifyOptions, type ChartModifyResponse, type ChartSpec, type ChartType, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type EncodingHints, type FieldRef, type FieldRefInput, type FieldType, type IngestResponse, type IntentResult, type MetricEncoding, type MetricField, type MetricSpec, type PaginatedResponse$1 as PaginatedResponse, type PaginationInfo$1 as PaginationInfo, type PaginationQuery$1 as PaginationQuery, type ParamRecord, type ParamValue, type PipelineTrace, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryErrorCode, QueryErrorCode as QueryErrorCodeType, QueryPanelSdkAPI, QueryPipelineError, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, type SdkSession, type SdkSessionTurn, type SessionGetOptions, type SessionListOptions, type SessionUpdateInput, type SqlModifications, type StackingMode, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type ValueFormat, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecGeneratorInput, type VizSpecKind, type VizSpecResponse, type VizSpecResult, anonymizeResults };

package/dist/index.d.ts

@@ -180,6 +180,7 @@ declare const QueryErrorCode: {
     readonly SQL_GENERATION_FAILED: "SQL_GENERATION_FAILED";
     readonly SQL_VALIDATION_FAILED: "SQL_VALIDATION_FAILED";
     readonly CONTEXT_RETRIEVAL_FAILED: "CONTEXT_RETRIEVAL_FAILED";
+    readonly CLARIFICATION_NEEDED: "CLARIFICATION_NEEDED";
     readonly INTERNAL_ERROR: "INTERNAL_ERROR";
     readonly AUTHENTICATION_REQUIRED: "AUTHENTICATION_REQUIRED";
     readonly VALIDATION_ERROR: "VALIDATION_ERROR";
@@ -208,6 +209,10 @@ declare class QueryPipelineError extends Error {
      * Check if this is any guardrail error (relevance or security)
      */
     isGuardrailError(): boolean;
+    /**
+     * Check if this is a clarification needed error (v2 pipeline)
+     */
+    isClarificationNeeded(): boolean;
 }
 
 type ParamValue = string | number | boolean | string[] | number[];
@@ -514,6 +519,40 @@ interface AskOptions {
      * Use this to reuse a previously returned session for follow-up prompts.
      */
     querypanelSessionId?: string;
+    /**
+     * Pipeline version to use for query generation.
+     * - "v1" (default): Original query pipeline
+     * - "v2": Improved pipeline with intent planning, hybrid retrieval, schema linking, and SQL reflection
+     */
+    pipeline?: "v1" | "v2";
+}
+/**
+ * Intent analysis result from the v2 pipeline.
+ */
+interface IntentResult {
+    intent: string;
+    confidence: number;
+    plan: {
+        tables: string[];
+        operations: string[];
+        filters: string[];
+        orderBy?: string;
+        limit?: number;
+    };
+    ambiguities: Array<{
+        issue: string;
+        suggestion: string;
+    }>;
+}
+/**
+ * Pipeline execution trace with step-level timing.
+ */
+interface PipelineTrace {
+    totalDurationMs: number;
+    steps: Array<{
+        step: string;
+        durationMs: number;
+    }>;
 }
 /**
  * Response returned after executing a query.
@@ -545,6 +584,10 @@ interface AskResponse {
     target_db?: string;
     /** QueryPanel session ID for follow-up queries. */
     querypanelSessionId?: string;
+    /** Intent analysis from v2 pipeline. */
+    intent?: IntentResult;
+    /** Pipeline execution trace from v2 pipeline. */
+    trace?: PipelineTrace;
 }
 declare function anonymizeResults(rows: Array<Record<string, unknown>>): Array<Record<string, string>>;
 
@@ -688,6 +731,12 @@ interface ChartModifyOptions {
     chartMaxRetries?: number;
     /** Chart generation method: 'vega-lite' or 'vizspec' */
     chartType?: "vega-lite" | "vizspec";
+    /**
+     * Pipeline version to use for SQL regeneration.
+     * - "v1" (default): Original query pipeline
+     * - "v2": Improved pipeline with intent planning, hybrid retrieval, schema linking, and SQL reflection
+     */
+    pipeline?: "v1" | "v2";
 }
 /**
  * Response from modifyChart(), extending AskResponse with modification metadata.
@@ -1283,4 +1332,4 @@ declare class QueryPanelSdkAPI {
     }, signal?: AbortSignal): Promise<void>;
 }
 
-export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, type ChartListOptions, type ChartModifyInput, type ChartModifyOptions, type ChartModifyResponse, type ChartSpec, type ChartType, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type EncodingHints, type FieldRef, type FieldRefInput, type FieldType, type IngestResponse, type MetricEncoding, type MetricField, type MetricSpec, type PaginatedResponse$1 as PaginatedResponse, type PaginationInfo$1 as PaginationInfo, type PaginationQuery$1 as PaginationQuery, type ParamRecord, type ParamValue, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryErrorCode, QueryErrorCode as QueryErrorCodeType, QueryPanelSdkAPI, QueryPipelineError, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, type SdkSession, type SdkSessionTurn, type SessionGetOptions, type SessionListOptions, type SessionUpdateInput, type SqlModifications, type StackingMode, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type ValueFormat, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecGeneratorInput, type VizSpecKind, type VizSpecResponse, type VizSpecResult, anonymizeResults };
+export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, type ChartListOptions, type ChartModifyInput, type ChartModifyOptions, type ChartModifyResponse, type ChartSpec, type ChartType, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type EncodingHints, type FieldRef, type FieldRefInput, type FieldType, type IngestResponse, type IntentResult, type MetricEncoding, type MetricField, type MetricSpec, type PaginatedResponse$1 as PaginatedResponse, type PaginationInfo$1 as PaginationInfo, type PaginationQuery$1 as PaginationQuery, type ParamRecord, type ParamValue, type PipelineTrace, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryErrorCode, QueryErrorCode as QueryErrorCodeType, QueryPanelSdkAPI, QueryPipelineError, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, type SdkSession, type SdkSessionTurn, type SessionGetOptions, type SessionListOptions, type SessionUpdateInput, type SqlModifications, type StackingMode, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type ValueFormat, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecGeneratorInput, type VizSpecKind, type VizSpecResponse, type VizSpecResult, anonymizeResults };

package/dist/index.js

@@ -888,6 +888,8 @@ var QueryErrorCode = {
   SQL_VALIDATION_FAILED: "SQL_VALIDATION_FAILED",
   // Context retrieval errors
   CONTEXT_RETRIEVAL_FAILED: "CONTEXT_RETRIEVAL_FAILED",
+  // Clarification errors (v2)
+  CLARIFICATION_NEEDED: "CLARIFICATION_NEEDED",
   // General errors
   INTERNAL_ERROR: "INTERNAL_ERROR",
   AUTHENTICATION_REQUIRED: "AUTHENTICATION_REQUIRED",
@@ -924,6 +926,12 @@ var QueryPipelineError = class extends Error {
   isGuardrailError() {
     return this.isRelevanceError() || this.isSecurityError();
   }
+  /**
+   * Check if this is a clarification needed error (v2 pipeline)
+   */
+  isClarificationNeeded() {
+    return this.code === QueryErrorCode.CLARIFICATION_NEEDED;
+  }
 };
 
 // src/routes/charts.ts
@@ -1235,6 +1243,7 @@ async function ask(client, queryEngine, question, options, signal) {
   let attempt = 0;
   let lastError = options.lastError;
   let previousSql = options.previousSql;
+  const queryEndpoint = options.pipeline === "v2" ? "/v2/query" : "/query";
   while (attempt <= maxRetry) {
     console.log({ lastError, previousSql });
     const databaseName = options.database ?? queryEngine.getDefaultDatabase();
@@ -1248,7 +1257,7 @@ async function ask(client, queryEngine, question, options, signal) {
       };
     }
     const queryResponse = await client.postWithHeaders(
-      "/query",
+      queryEndpoint,
       {
         question,
         ...querypanelSessionId ? { session_id: querypanelSessionId } : {},
@@ -1364,7 +1373,9 @@ async function ask(client, queryEngine, question, options, signal) {
         context: queryResponse.data.context,
         attempts: attempt + 1,
         target_db: dbName,
-        querypanelSessionId: responseSessionId ?? void 0
+        querypanelSessionId: responseSessionId ?? void 0,
+        intent: queryResponse.data.intent,
+        trace: queryResponse.data.trace
       };
     } catch (error) {
       attempt++;
@@ -1476,6 +1487,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
   const hasSqlMods = !!input.sqlModifications;
   const hasVizMods = !!input.vizModifications;
   const hasCustomSql = !!input.sqlModifications?.customSql;
+  const queryEndpoint = options?.pipeline === "v2" ? "/v2/query" : "/query";
   let finalSql = input.sql;
   let finalParams = input.params ?? {};
   let paramMetadata = [];
@@ -1508,7 +1520,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
       input.sqlModifications
     );
     const queryResponse = await client.post(
-      "/query",
+      queryEndpoint,
       {
         question: modifiedQuestion,
         previous_sql: input.sql,