@querypanel/node-sdk 1.2.7 → 1.2.9

package/dist/index.d.cts

@@ -737,6 +737,11 @@ interface AskOptions {
      * Sent to `POST /vizspec` as `supported_chart_types`. Omitted allows all standard types.
      */
     supportedChartTypes?: ChartType[];
+    /**
+     * When true, rationale includes engineer-style schema detail (tables, columns).
+     * When false (default), rationale is client-safe for end users.
+     */
+    debug?: boolean;
 }
 /**
  * Intent analysis result from the v2 pipeline.
@@ -961,6 +966,11 @@ interface ChartModifyOptions {
      * Restrict VizSpec chart types for this call (merged with SDK default from constructor when omitted).
      */
     supportedChartTypes?: ChartType[];
+    /**
+     * When true, rationale includes engineer-style schema detail (tables, columns).
+     * When false (default), rationale is client-safe for end users.
+     */
+    debug?: boolean;
 }
 /**
  * Response from modifyChart(), extending AskResponse with modification metadata.
@@ -1233,7 +1243,7 @@ declare class QueryPanelSdkAPI {
      * It handles the complete flow: SQL generation → validation → execution → chart generation.
      *
      * @param question - Natural language question (e.g., "Show revenue by country")
-     * @param options - Query options including tenantId, database, and retry settings
+     * @param options - Query options including tenantId, database, retry settings, and optional `debug` for engineer-style rationale
      * @param signal - Optional AbortSignal for cancellation
      * @returns Response with SQL, executed data rows, and generated chart
      * @throws {Error} When SQL generation or execution fails after all retries

package/dist/index.d.ts

@@ -737,6 +737,11 @@ interface AskOptions {
      * Sent to `POST /vizspec` as `supported_chart_types`. Omitted allows all standard types.
      */
     supportedChartTypes?: ChartType[];
+    /**
+     * When true, rationale includes engineer-style schema detail (tables, columns).
+     * When false (default), rationale is client-safe for end users.
+     */
+    debug?: boolean;
 }
 /**
  * Intent analysis result from the v2 pipeline.
@@ -961,6 +966,11 @@ interface ChartModifyOptions {
      * Restrict VizSpec chart types for this call (merged with SDK default from constructor when omitted).
      */
     supportedChartTypes?: ChartType[];
+    /**
+     * When true, rationale includes engineer-style schema detail (tables, columns).
+     * When false (default), rationale is client-safe for end users.
+     */
+    debug?: boolean;
 }
 /**
  * Response from modifyChart(), extending AskResponse with modification metadata.
@@ -1233,7 +1243,7 @@ declare class QueryPanelSdkAPI {
      * It handles the complete flow: SQL generation → validation → execution → chart generation.
      *
      * @param question - Natural language question (e.g., "Show revenue by country")
-     * @param options - Query options including tenantId, database, and retry settings
+     * @param options - Query options including tenantId, database, retry settings, and optional `debug` for engineer-style rationale
      * @param signal - Optional AbortSignal for cancellation
      * @returns Response with SQL, executed data rows, and generated chart
      * @throws {Error} When SQL generation or execution fails after all retries

package/dist/index.js

@@ -1798,7 +1798,6 @@ async function ask(client, queryEngine, question, options, signal) {
   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();
     const metadata = databaseName ? queryEngine.getDatabaseMetadata(databaseName) : void 0;
     let tenantSettings;
@@ -1821,7 +1820,8 @@ async function ask(client, queryEngine, question, options, signal) {
         ...databaseName ? { database: databaseName } : {},
         ...metadata?.dialect ? { dialect: metadata.dialect } : {},
         ...options.model?.trim() ? { model: options.model.trim() } : {},
-        ...options.pipeline === "v2" && options.systemPrompt?.trim() ? { system_prompt: options.systemPrompt.trim() } : {}
+        ...options.pipeline === "v2" && options.systemPrompt?.trim() ? { system_prompt: options.systemPrompt.trim() } : {},
+        debug: options.debug ?? false
       },
       tenantId,
       options.userId,
@@ -1863,60 +1863,58 @@ async function ask(client, queryEngine, question, options, signal) {
         specType: chartType,
         notes: rows.length === 0 ? "Query returned no rows." : null
       };
-      if (rows.length > 0) {
-        if (chartType === "vizspec") {
-          const vizspecResponse = await client.post(
-            "/vizspec",
-            {
-              question,
-              sql,
-              rationale: queryResponse.data.rationale,
-              fields: execution.fields,
-              rows: anonymizeResults(rows),
-              max_retries: options.chartMaxRetries ?? 3,
-              query_id: queryResponse.data.queryId,
-              ...options.supportedChartTypes?.length ? {
-                supported_chart_types: options.supportedChartTypes
-              } : {}
-            },
-            tenantId,
-            options.userId,
-            options.scopes,
-            signal,
-            sessionId
-          );
-          chart = {
-            vizSpec: vizspecResponse.spec,
-            specType: "vizspec",
-            notes: vizspecResponse.notes
-          };
-        } else {
-          const chartResponse = await client.post(
-            "/chart",
-            {
-              question,
-              sql,
-              rationale: queryResponse.data.rationale,
-              fields: execution.fields,
-              rows: anonymizeResults(rows),
-              max_retries: options.chartMaxRetries ?? 3,
-              query_id: queryResponse.data.queryId
-            },
-            tenantId,
-            options.userId,
-            options.scopes,
-            signal,
-            sessionId
-          );
-          chart = {
-            vegaLiteSpec: chartResponse.chart ? {
-              ...chartResponse.chart,
-              data: { values: rows }
-            } : null,
-            specType: "vega-lite",
-            notes: chartResponse.notes
-          };
-        }
+      if (chartType === "vizspec") {
+        const vizspecResponse = await client.post(
+          "/vizspec",
+          {
+            question,
+            sql,
+            rationale: queryResponse.data.rationale,
+            fields: execution.fields,
+            rows: anonymizeResults(rows),
+            max_retries: options.chartMaxRetries ?? 3,
+            query_id: queryResponse.data.queryId,
+            ...options.supportedChartTypes?.length ? {
+              supported_chart_types: options.supportedChartTypes
+            } : {}
+          },
+          tenantId,
+          options.userId,
+          options.scopes,
+          signal,
+          sessionId
+        );
+        chart = {
+          vizSpec: vizspecResponse.spec,
+          specType: "vizspec",
+          notes: rows.length === 0 ? vizspecResponse.notes ?? "Query returned no rows." : vizspecResponse.notes
+        };
+      } else {
+        const chartResponse = await client.post(
+          "/chart",
+          {
+            question,
+            sql,
+            rationale: queryResponse.data.rationale,
+            fields: execution.fields,
+            rows: anonymizeResults(rows),
+            max_retries: options.chartMaxRetries ?? 3,
+            query_id: queryResponse.data.queryId
+          },
+          tenantId,
+          options.userId,
+          options.scopes,
+          signal,
+          sessionId
+        );
+        chart = {
+          vegaLiteSpec: chartResponse.chart ? {
+            ...chartResponse.chart,
+            data: { values: rows }
+          } : null,
+          specType: "vega-lite",
+          notes: rows.length === 0 ? chartResponse.notes ?? "Query returned no rows." : chartResponse.notes
+        };
       }
       return {
         sql,
@@ -1942,9 +1940,14 @@ async function ask(client, queryEngine, question, options, signal) {
       }
       lastError = error instanceof Error ? error.message : String(error);
       previousSql = queryResponse.data.sql ?? previousSql;
-      console.warn(
-        `SQL execution failed (attempt ${attempt}/${maxRetry + 1}): ${lastError}. Retrying...`
-      );
+      console.warn("SQL execution failed, retrying query generation", {
+        attempt,
+        maxAttempts: maxRetry + 1,
+        error: lastError,
+        sql: queryResponse.data.sql ?? null,
+        paramMetadata,
+        params: paramValues
+      });
     }
   }
   throw new Error("Unexpected error in ask retry loop");
@@ -2170,7 +2173,8 @@ async function modifyChart(client, queryEngine, input, options, signal) {
         ...options?.maxRetry ? { max_retry: options.maxRetry } : {},
         ...tenantSettings ? { tenant_settings: tenantSettings } : {},
         ...databaseName ? { database: databaseName } : {},
-        ...metadata?.dialect ? { dialect: metadata.dialect } : {}
+        ...metadata?.dialect ? { dialect: metadata.dialect } : {},
+        debug: options?.debug ?? false
       },
       tenantId,
       options?.userId,
@@ -2203,64 +2207,62 @@ async function modifyChart(client, queryEngine, input, options, signal) {
     specType: chartType,
     notes: rows.length === 0 ? "Query returned no rows." : null
   };
-  if (rows.length > 0) {
-    const vizHints = hasVizMods ? buildVizHints(input.vizModifications) : {};
-    const vizHintsForChart = chartType === "vizspec" ? vizHints : stripVizSpecOnlyHints(vizHints);
-    if (chartType === "vizspec") {
-      const vizspecResponse = await client.post(
-        "/vizspec",
-        {
-          question: finalQuestion,
-          sql: finalSql,
-          rationale,
-          fields: execution.fields,
-          rows: anonymizeResults(rows),
-          max_retries: options?.chartMaxRetries ?? 3,
-          query_id: queryId,
-          // Include viz hints for the chart generator
-          ...hasVizMods ? { encoding_hints: vizHintsForChart } : {},
-          ...options?.supportedChartTypes?.length ? { supported_chart_types: options.supportedChartTypes } : {}
-        },
-        tenantId,
-        options?.userId,
-        options?.scopes,
-        signal,
-        sessionId
-      );
-      chart = {
-        vizSpec: vizspecResponse.spec,
-        specType: "vizspec",
-        notes: vizspecResponse.notes
-      };
-    } else {
-      const chartResponse = await client.post(
-        "/chart",
-        {
-          question: finalQuestion,
-          sql: finalSql,
-          rationale,
-          fields: execution.fields,
-          rows: anonymizeResults(rows),
-          max_retries: options?.chartMaxRetries ?? 3,
-          query_id: queryId,
-          // Include viz hints for the chart generator
-          ...hasVizMods ? { encoding_hints: vizHintsForChart } : {}
-        },
-        tenantId,
-        options?.userId,
-        options?.scopes,
-        signal,
-        sessionId
-      );
-      chart = {
-        vegaLiteSpec: chartResponse.chart ? {
-          ...chartResponse.chart,
-          data: { values: rows }
-        } : null,
-        specType: "vega-lite",
-        notes: chartResponse.notes
-      };
-    }
+  const vizHints = hasVizMods ? buildVizHints(input.vizModifications) : {};
+  const vizHintsForChart = chartType === "vizspec" ? vizHints : stripVizSpecOnlyHints(vizHints);
+  if (chartType === "vizspec") {
+    const vizspecResponse = await client.post(
+      "/vizspec",
+      {
+        question: finalQuestion,
+        sql: finalSql,
+        rationale,
+        fields: execution.fields,
+        rows: anonymizeResults(rows),
+        max_retries: options?.chartMaxRetries ?? 3,
+        query_id: queryId,
+        // Include viz hints for the chart generator
+        ...hasVizMods ? { encoding_hints: vizHintsForChart } : {},
+        ...options?.supportedChartTypes?.length ? { supported_chart_types: options.supportedChartTypes } : {}
+      },
+      tenantId,
+      options?.userId,
+      options?.scopes,
+      signal,
+      sessionId
+    );
+    chart = {
+      vizSpec: vizspecResponse.spec,
+      specType: "vizspec",
+      notes: rows.length === 0 ? vizspecResponse.notes ?? "Query returned no rows." : vizspecResponse.notes
+    };
+  } else {
+    const chartResponse = await client.post(
+      "/chart",
+      {
+        question: finalQuestion,
+        sql: finalSql,
+        rationale,
+        fields: execution.fields,
+        rows: anonymizeResults(rows),
+        max_retries: options?.chartMaxRetries ?? 3,
+        query_id: queryId,
+        // Include viz hints for the chart generator
+        ...hasVizMods ? { encoding_hints: vizHintsForChart } : {}
+      },
+      tenantId,
+      options?.userId,
+      options?.scopes,
+      signal,
+      sessionId
+    );
+    chart = {
+      vegaLiteSpec: chartResponse.chart ? {
+        ...chartResponse.chart,
+        data: { values: rows }
+      } : null,
+      specType: "vega-lite",
+      notes: rows.length === 0 ? chartResponse.notes ?? "Query returned no rows." : chartResponse.notes
+    };
   }
   return {
     sql: finalSql,
@@ -2551,7 +2553,7 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
    * It handles the complete flow: SQL generation → validation → execution → chart generation.
    *
    * @param question - Natural language question (e.g., "Show revenue by country")
-   * @param options - Query options including tenantId, database, and retry settings
+   * @param options - Query options including tenantId, database, retry settings, and optional `debug` for engineer-style rationale
    * @param signal - Optional AbortSignal for cancellation
    * @returns Response with SQL, executed data rows, and generated chart
    * @throws {Error} When SQL generation or execution fails after all retries