@querypanel/node-sdk 1.0.48 → 1.0.50

package/dist/index.d.cts

@@ -368,7 +368,8 @@ interface VizSpecBase {
         sourceId: string;
     };
 }
-type ChartType = 'line' | 'bar' | 'area' | 'scatter' | 'pie';
+type VizSpecKind = VizSpecBase["kind"];
+type ChartType = 'line' | 'bar' | 'column' | 'area' | 'scatter' | 'pie';
 type StackingMode = 'none' | 'stacked' | 'percent';
 interface ChartEncoding {
     chartType: ChartType;
@@ -415,6 +416,50 @@ interface MetricSpec extends VizSpecBase {
     encoding: MetricEncoding;
 }
 type VizSpec = ChartSpec | TableSpec | MetricSpec;
+/**
+ * Encoding hints for vizspec modifications.
+ * These hints guide the LLM to generate specific visualization configurations.
+ */
+interface EncodingHints {
+    /** Preferred vizspec kind (chart, table, metric) */
+    kind?: 'chart' | 'table' | 'metric';
+    /** Preferred chart type (bar, line, area, scatter, pie) */
+    chartType?: ChartType;
+    /** X axis field configuration */
+    xAxis?: AxisField;
+    /** Y axis field configuration (single or multiple) */
+    yAxis?: AxisField | AxisField[];
+    /** Series/color field for multi-series charts */
+    series?: FieldRef;
+    /** Stacking mode for multi-series */
+    stacking?: StackingMode;
+    /** Maximum rows to display */
+    limit?: number;
+}
+/**
+ * Input for vizspec generator service
+ */
+interface VizSpecGeneratorInput {
+    question: string;
+    sql: string;
+    rationale?: string;
+    fields: string[];
+    rows: Array<Record<string, unknown>>;
+    maxRetries?: number;
+    queryId?: string;
+    /**
+     * Optional encoding hints for visualization modification.
+     * When provided, these guide the LLM to generate specific visualization configurations.
+     */
+    encodingHints?: EncodingHints;
+}
+/**
+ * Output from vizspec generator service
+ */
+interface VizSpecResult {
+    spec: VizSpec;
+    notes: string | null;
+}
 
 /**
  * Context document returned by the query pipeline.
@@ -573,6 +618,8 @@ interface SqlModifications {
  * These changes only affect how the chart is rendered.
  */
 interface VizModifications {
+    /** Change the VizSpec kind (chart, table, metric). Applies to vizspec only. */
+    kind?: VizSpecKind;
     /** Change the chart type (line, bar, area, scatter, pie) */
     chartType?: ChartType;
     /** Configure the X axis field and settings */
@@ -750,6 +797,11 @@ interface VizSpecGenerateInput {
     rows: Array<Record<string, unknown>>;
     max_retries?: number;
     query_id?: string;
+    /**
+     * Optional encoding hints for visualization modification.
+     * When provided, these guide the LLM to generate specific visualization configurations.
+     */
+    encoding_hints?: EncodingHints;
 }
 interface VizSpecGenerateOptions {
     tenantId?: string;
@@ -1231,4 +1283,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 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 VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecResponse, 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 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 };

package/dist/index.d.ts

@@ -368,7 +368,8 @@ interface VizSpecBase {
         sourceId: string;
     };
 }
-type ChartType = 'line' | 'bar' | 'area' | 'scatter' | 'pie';
+type VizSpecKind = VizSpecBase["kind"];
+type ChartType = 'line' | 'bar' | 'column' | 'area' | 'scatter' | 'pie';
 type StackingMode = 'none' | 'stacked' | 'percent';
 interface ChartEncoding {
     chartType: ChartType;
@@ -415,6 +416,50 @@ interface MetricSpec extends VizSpecBase {
     encoding: MetricEncoding;
 }
 type VizSpec = ChartSpec | TableSpec | MetricSpec;
+/**
+ * Encoding hints for vizspec modifications.
+ * These hints guide the LLM to generate specific visualization configurations.
+ */
+interface EncodingHints {
+    /** Preferred vizspec kind (chart, table, metric) */
+    kind?: 'chart' | 'table' | 'metric';
+    /** Preferred chart type (bar, line, area, scatter, pie) */
+    chartType?: ChartType;
+    /** X axis field configuration */
+    xAxis?: AxisField;
+    /** Y axis field configuration (single or multiple) */
+    yAxis?: AxisField | AxisField[];
+    /** Series/color field for multi-series charts */
+    series?: FieldRef;
+    /** Stacking mode for multi-series */
+    stacking?: StackingMode;
+    /** Maximum rows to display */
+    limit?: number;
+}
+/**
+ * Input for vizspec generator service
+ */
+interface VizSpecGeneratorInput {
+    question: string;
+    sql: string;
+    rationale?: string;
+    fields: string[];
+    rows: Array<Record<string, unknown>>;
+    maxRetries?: number;
+    queryId?: string;
+    /**
+     * Optional encoding hints for visualization modification.
+     * When provided, these guide the LLM to generate specific visualization configurations.
+     */
+    encodingHints?: EncodingHints;
+}
+/**
+ * Output from vizspec generator service
+ */
+interface VizSpecResult {
+    spec: VizSpec;
+    notes: string | null;
+}
 
 /**
  * Context document returned by the query pipeline.
@@ -573,6 +618,8 @@ interface SqlModifications {
  * These changes only affect how the chart is rendered.
  */
 interface VizModifications {
+    /** Change the VizSpec kind (chart, table, metric). Applies to vizspec only. */
+    kind?: VizSpecKind;
     /** Change the chart type (line, bar, area, scatter, pie) */
     chartType?: ChartType;
     /** Configure the X axis field and settings */
@@ -750,6 +797,11 @@ interface VizSpecGenerateInput {
     rows: Array<Record<string, unknown>>;
     max_retries?: number;
     query_id?: string;
+    /**
+     * Optional encoding hints for visualization modification.
+     * When provided, these guide the LLM to generate specific visualization configurations.
+     */
+    encoding_hints?: EncodingHints;
 }
 interface VizSpecGenerateOptions {
     tenantId?: string;
@@ -1231,4 +1283,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 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 VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecResponse, 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 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 };

package/dist/index.js

@@ -1430,6 +1430,9 @@ function buildModifiedQuestion(originalQuestion, modifications) {
 }
 function buildVizHints(modifications) {
   const hints = {};
+  if (modifications.kind) {
+    hints.kind = modifications.kind;
+  }
   if (modifications.chartType) {
     hints.chartType = modifications.chartType;
   }
@@ -1450,6 +1453,13 @@ function buildVizHints(modifications) {
   }
   return hints;
 }
+function stripVizSpecOnlyHints(hints) {
+  if (!("kind" in hints)) {
+    return hints;
+  }
+  const { kind: _kind, ...rest } = hints;
+  return rest;
+}
 function resolveTenantId5(client, tenantId) {
   const resolved = tenantId ?? client.getDefaultTenantId();
   if (!resolved) {
@@ -1533,6 +1543,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
   };
   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",
@@ -1545,7 +1556,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
           max_retries: options?.chartMaxRetries ?? 3,
           query_id: queryId,
           // Include viz hints for the chart generator
-          ...hasVizMods ? { encoding_hints: vizHints } : {}
+          ...hasVizMods ? { encoding_hints: vizHintsForChart } : {}
         },
         tenantId,
         options?.userId,
@@ -1570,7 +1581,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
           max_retries: options?.chartMaxRetries ?? 3,
           query_id: queryId,
           // Include viz hints for the chart generator
-          ...hasVizMods ? { encoding_hints: vizHints } : {}
+          ...hasVizMods ? { encoding_hints: vizHintsForChart } : {}
         },
         tenantId,
         options?.userId,
@@ -1690,7 +1701,8 @@ async function generateVizSpec(client, input, options, signal) {
       fields: input.fields,
       rows: input.rows,
       max_retries: options?.maxRetries ?? input.max_retries ?? 3,
-      query_id: input.query_id
+      query_id: input.query_id,
+      encoding_hints: input.encoding_hints
     },
     tenantId,
     options?.userId,