@querypanel/node-sdk 1.0.51 → 1.0.53

package/dist/index.cjs

@@ -929,6 +929,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",
@@ -965,6 +967,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
@@ -1276,6 +1284,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();
@@ -1289,7 +1298,7 @@ async function ask(client, queryEngine, question, options, signal) {
       };
     }
     const queryResponse = await client.postWithHeaders(
-      "/query",
+      queryEndpoint,
       {
         question,
         ...querypanelSessionId ? { session_id: querypanelSessionId } : {},
@@ -1405,7 +1414,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++;
@@ -1444,21 +1455,39 @@ function anonymizeResults(rows) {
 }
 
 // src/routes/modify.ts
-function buildModifiedQuestion(originalQuestion, modifications) {
+function buildModifiedQuestion(originalQuestion, modifications, pipeline) {
   const hints = [];
   if (modifications.timeGranularity) {
     hints.push(`group results by ${modifications.timeGranularity}`);
   }
   if (modifications.dateRange) {
-    const parts = [];
-    if (modifications.dateRange.from) {
-      parts.push(`from ${modifications.dateRange.from}`);
-    }
-    if (modifications.dateRange.to) {
-      parts.push(`to ${modifications.dateRange.to}`);
-    }
-    if (parts.length > 0) {
-      hints.push(`filter date range ${parts.join(" ")}`);
+    if (pipeline === "v2") {
+      const from = normalizeDateInput(modifications.dateRange.from);
+      const to = normalizeDateInput(modifications.dateRange.to);
+      if (from && to) {
+        hints.push(
+          `replace any existing date filters with exact date range from ${from} to ${to} (inclusive, do not add extra days)`
+        );
+      } else if (from) {
+        hints.push(
+          `replace any existing date filters with exact start date ${from} (do not shift this date)`
+        );
+      } else if (to) {
+        hints.push(
+          `replace any existing date filters with exact end date ${to} (inclusive, do not add extra days)`
+        );
+      }
+    } else {
+      const parts = [];
+      if (modifications.dateRange.from) {
+        parts.push(`from ${modifications.dateRange.from}`);
+      }
+      if (modifications.dateRange.to) {
+        parts.push(`to ${modifications.dateRange.to}`);
+      }
+      if (parts.length > 0) {
+        hints.push(`filter date range ${parts.join(" ")}`);
+      }
     }
   }
   if (modifications.additionalInstructions) {
@@ -1469,6 +1498,67 @@ function buildModifiedQuestion(originalQuestion, modifications) {
   }
   return `${originalQuestion} (${hints.join(", ")})`;
 }
+var START_PARAM_KEY_REGEX = /(^|_)(start|from)(_|$)/i;
+var END_PARAM_KEY_REGEX = /(^|_)(end|to)(_|$)/i;
+var ISO_DATETIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z?$/;
+var SQL_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+var SQL_DATETIME_RE = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
+function normalizeDateInput(value) {
+  if (!value) return void 0;
+  const trimmed = value.trim();
+  if (!trimmed) return void 0;
+  if (ISO_DATETIME_RE.test(trimmed)) {
+    return trimmed.replace("T", " ").replace(/\.\d+Z?$/, "").replace(/Z$/, "");
+  }
+  return trimmed;
+}
+function keyLooksLikeDateBoundary(key, boundary) {
+  return boundary === "start" ? START_PARAM_KEY_REGEX.test(key) : END_PARAM_KEY_REGEX.test(key);
+}
+function hasTimeComponent(value) {
+  return typeof value === "string" && /\d{2}:\d{2}:\d{2}/.test(value);
+}
+function formatDateOverride(dateValue, boundary, existingValue) {
+  if (SQL_DATE_RE.test(dateValue) && !hasTimeComponent(existingValue)) {
+    return dateValue;
+  }
+  if (SQL_DATE_RE.test(dateValue)) {
+    return `${dateValue} ${boundary === "start" ? "00:00:00" : "23:59:59"}`;
+  }
+  if (SQL_DATETIME_RE.test(dateValue)) {
+    return dateValue;
+  }
+  return dateValue;
+}
+function normalizeGeneratedParamKey(param, index) {
+  const nameCandidate = typeof param.name === "string" && param.name.trim() || typeof param.placeholder === "string" && param.placeholder.trim() || typeof param.position === "number" && String(param.position) || String(index + 1);
+  return nameCandidate.replace(/[{}]/g, "").replace(/(.+):.*$/, "$1").replace(/^[:$]/, "").trim();
+}
+function applyDateRangeOverrides(dateRange, params, paramMetadata) {
+  if (!dateRange) return;
+  const from = normalizeDateInput(dateRange.from);
+  const to = normalizeDateInput(dateRange.to);
+  if (!from && !to) return;
+  for (const [key, value] of Object.entries(params)) {
+    if (from && keyLooksLikeDateBoundary(key, "start")) {
+      params[key] = formatDateOverride(from, "start", value);
+    }
+    if (to && keyLooksLikeDateBoundary(key, "end")) {
+      params[key] = formatDateOverride(to, "end", value);
+    }
+  }
+  for (let i = 0; i < paramMetadata.length; i++) {
+    const param = paramMetadata[i];
+    if (!param) continue;
+    const key = normalizeGeneratedParamKey(param, i);
+    if (from && keyLooksLikeDateBoundary(key, "start")) {
+      param.value = formatDateOverride(from, "start", param.value);
+    }
+    if (to && keyLooksLikeDateBoundary(key, "end")) {
+      param.value = formatDateOverride(to, "end", param.value);
+    }
+  }
+}
 function buildVizHints(modifications) {
   const hints = {};
   if (modifications.kind) {
@@ -1501,6 +1591,9 @@ function stripVizSpecOnlyHints(hints) {
   const { kind: _kind, ...rest } = hints;
   return rest;
 }
+function isDateRangeOnly(mods) {
+  return !!mods.dateRange && !mods.timeGranularity && !mods.additionalInstructions && !mods.customSql;
+}
 function resolveTenantId5(client, tenantId) {
   const resolved = tenantId ?? client.getDefaultTenantId();
   if (!resolved) {
@@ -1517,12 +1610,14 @@ 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 = [];
   let rationale;
   let queryId;
   let sqlChanged = false;
+  let finalQuestion = input.question;
   const databaseName = input.database ?? queryEngine.getDefaultDatabase();
   if (!databaseName) {
     throw new Error(
@@ -1543,13 +1638,89 @@ async function modifyChart(client, queryEngine, input, options, signal) {
     finalParams = {};
     paramMetadata = [];
     sqlChanged = true;
+  } else if (hasSqlMods && options?.pipeline === "v2" && isDateRangeOnly(input.sqlModifications)) {
+    let usedFastPath = false;
+    try {
+      const rewriteResponse = await client.post(
+        "/v2/rewrite-datefilter",
+        {
+          previous_sql: input.sql,
+          previous_params: input.params ? Object.entries(input.params).map(([name, value]) => ({
+            name,
+            value
+          })) : [],
+          date_range: input.sqlModifications.dateRange,
+          question: input.question,
+          ...tenantSettings ? { tenant_settings: tenantSettings } : {},
+          ...databaseName ? { database: databaseName } : {},
+          ...metadata?.dialect ? { dialect: metadata.dialect } : {}
+        },
+        tenantId,
+        options?.userId,
+        options?.scopes,
+        signal,
+        sessionId
+      );
+      finalSql = rewriteResponse.sql;
+      paramMetadata = Array.isArray(rewriteResponse.params) ? rewriteResponse.params : [];
+      finalParams = queryEngine.mapGeneratedParams(paramMetadata);
+      applyDateRangeOverrides(
+        input.sqlModifications?.dateRange,
+        finalParams,
+        paramMetadata
+      );
+      rationale = rewriteResponse.rationale;
+      queryId = rewriteResponse.queryId;
+      sqlChanged = finalSql !== input.sql;
+      usedFastPath = true;
+    } catch {
+    }
+    if (!usedFastPath) {
+      const modifiedQuestion = buildModifiedQuestion(
+        input.question,
+        input.sqlModifications,
+        "v2"
+      );
+      finalQuestion = modifiedQuestion;
+      const queryResponse = await client.post(
+        queryEndpoint,
+        {
+          question: modifiedQuestion,
+          previous_sql: input.sql,
+          ...options?.maxRetry ? { max_retry: options.maxRetry } : {},
+          ...tenantSettings ? { tenant_settings: tenantSettings } : {},
+          ...databaseName ? { database: databaseName } : {},
+          ...metadata?.dialect ? { dialect: metadata.dialect } : {}
+        },
+        tenantId,
+        options?.userId,
+        options?.scopes,
+        signal,
+        sessionId
+      );
+      finalSql = queryResponse.sql;
+      paramMetadata = Array.isArray(queryResponse.params) ? queryResponse.params : [];
+      finalParams = queryEngine.mapGeneratedParams(paramMetadata);
+      applyDateRangeOverrides(
+        input.sqlModifications?.dateRange,
+        finalParams,
+        paramMetadata
+      );
+      rationale = queryResponse.rationale;
+      queryId = queryResponse.queryId;
+      sqlChanged = finalSql !== input.sql;
+    }
   } else if (hasSqlMods && !hasCustomSql) {
     const modifiedQuestion = buildModifiedQuestion(
       input.question,
-      input.sqlModifications
+      input.sqlModifications,
+      options?.pipeline
     );
+    if (options?.pipeline === "v2") {
+      finalQuestion = modifiedQuestion;
+    }
     const queryResponse = await client.post(
-      "/query",
+      queryEndpoint,
       {
         question: modifiedQuestion,
         previous_sql: input.sql,
@@ -1567,6 +1738,13 @@ async function modifyChart(client, queryEngine, input, options, signal) {
     finalSql = queryResponse.sql;
     paramMetadata = Array.isArray(queryResponse.params) ? queryResponse.params : [];
     finalParams = queryEngine.mapGeneratedParams(paramMetadata);
+    if (options?.pipeline === "v2") {
+      applyDateRangeOverrides(
+        input.sqlModifications?.dateRange,
+        finalParams,
+        paramMetadata
+      );
+    }
     rationale = queryResponse.rationale;
     queryId = queryResponse.queryId;
     sqlChanged = finalSql !== input.sql;
@@ -1589,7 +1767,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
       const vizspecResponse = await client.post(
         "/vizspec",
         {
-          question: input.question,
+          question: finalQuestion,
           sql: finalSql,
           rationale,
           fields: execution.fields,
@@ -1614,7 +1792,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
       const chartResponse = await client.post(
         "/chart",
         {
-          question: input.question,
+          question: finalQuestion,
           sql: finalSql,
           rationale,
           fields: execution.fields,