@xbbg/langgraph 1.3.0 → 1.3.1

package/README.md

@@ -166,6 +166,7 @@ Extension helper tools:
 - `xbbg_ext_constants` - static constants and formatting helpers for dates, futures months, dividend types, and ETF/dividend columns.
 - `xbbg_ext_columns` - rename helpers for dividend, ETF, and earnings-shaped Bloomberg responses.
 - `xbbg_ext_calculate` - small numeric helper for level percentage calculations.
+- `xbbg_ext_chart_spec` - renderer-neutral chart specs for frontend generative UI; converts bounded rows from `xbbg_bdh`, `xbbg_bdib`, holdings, depth, or already-shaped row data into Vega-Lite JSON.
 
 ```ts
 import { createBloombergExtTools, createAllBloombergTools } from "@xbbg/langgraph";
@@ -176,6 +177,34 @@ const allTools = createAllBloombergTools({
 });
 ```
 
+### Chart specs and generative UI frontends
+
+`xbbg_ext_chart_spec` does not fetch Bloomberg data and does not render images. Use a data tool first, then pass its bounded rows into the chart-spec helper. The result is a portable visualization payload:
+
+```json
+{
+  "kind": "xbbg.visualization",
+  "component": "xbbg_chart",
+  "renderer": "vega-lite",
+  "spec": { "data": { "values": [] }, "mark": { "type": "line" } }
+}
+```
+
+Frontend runtimes should register their own `xbbg_chart` component and render `data.spec` with their preferred Vega-Lite React wrapper. This keeps `@xbbg/langgraph` dependency-free and works with CopilotKit `useRenderTool`, assistant-ui data/generative UI renderers, Vercel AI SDK tool parts, or LangGraph `typedUi()` adapters.
+
+Example tool input after a historical request:
+
+```json
+{
+  "source": "bdh",
+  "rows": [{ "ticker": "AAPL US Equity", "date": "20240102", "value": 190.1 }],
+  "xField": "date",
+  "yFields": ["value"],
+  "seriesField": "ticker",
+  "title": "AAPL PX_LAST"
+}
+```
+
 ## Engine handling
 
 By default the first tool invocation lazily imports `@xbbg/core`, calls `connect(engineConfig)`, and reuses the resulting engine across the tool set. Parallel LangGraph tool calls share the same in-flight initialization promise.

package/dist/index.d.ts

@@ -5,7 +5,7 @@ type XbbgCoreModule = typeof xbbg;
 type XbbgEngineLike = Pick<Awaited<ReturnType<XbbgCoreModule["connect"]>>, "bdp" | "bdh" | "bds" | "bdib" | "bdtick" | "bql" | "bsrch" | "bqr" | "bflds" | "beqs" | "yas" | "preferreds" | "corporateBonds" | "indexMembers" | "resolveIsins" | "issuerIsins" | "etfHoldings" | "stream" | "mktbar" | "depth">;
 type XbbgCoreLike = Pick<XbbgCoreModule, "connect" | "ext">;
 
-declare const BLOOMBERG_TOOL_NAMES: readonly ["xbbg_bdp", "xbbg_bdh", "xbbg_bds", "xbbg_bdib", "xbbg_bdtick", "xbbg_bql", "xbbg_bsrch", "xbbg_bqr", "xbbg_bflds", "xbbg_beqs", "xbbg_yas", "xbbg_preferreds", "xbbg_corporate_bonds", "xbbg_index_members", "xbbg_resolve_isins", "xbbg_issuer_isins", "xbbg_etf_holdings", "xbbg_stream_snapshot", "xbbg_mktbar_snapshot", "xbbg_depth_snapshot", "xbbg_ext_ticker", "xbbg_ext_futures", "xbbg_ext_cdx", "xbbg_ext_currency", "xbbg_ext_bql_builder", "xbbg_ext_market_session", "xbbg_ext_yas_overrides", "xbbg_ext_constants", "xbbg_ext_columns", "xbbg_ext_calculate"];
+declare const BLOOMBERG_TOOL_NAMES: readonly ["xbbg_bdp", "xbbg_bdh", "xbbg_bds", "xbbg_bdib", "xbbg_bdtick", "xbbg_bql", "xbbg_bsrch", "xbbg_bqr", "xbbg_bflds", "xbbg_beqs", "xbbg_yas", "xbbg_preferreds", "xbbg_corporate_bonds", "xbbg_index_members", "xbbg_resolve_isins", "xbbg_issuer_isins", "xbbg_etf_holdings", "xbbg_stream_snapshot", "xbbg_mktbar_snapshot", "xbbg_depth_snapshot", "xbbg_ext_ticker", "xbbg_ext_futures", "xbbg_ext_cdx", "xbbg_ext_currency", "xbbg_ext_bql_builder", "xbbg_ext_chart_spec", "xbbg_ext_market_session", "xbbg_ext_yas_overrides", "xbbg_ext_constants", "xbbg_ext_columns", "xbbg_ext_calculate"];
 type BloombergToolName = (typeof BLOOMBERG_TOOL_NAMES)[number];
 interface BloombergToolsOptions {
     readonly engine?: XbbgEngineLike;
@@ -75,7 +75,7 @@ interface BloombergToolInstructionsOptions {
 }
 declare function getBloombergToolInstructions(options?: BloombergToolInstructionsOptions): string;
 
-declare const BLOOMBERG_EXT_TOOL_NAMES: readonly ("xbbg_bdp" | "xbbg_bdh" | "xbbg_bds" | "xbbg_bdib" | "xbbg_bdtick" | "xbbg_bql" | "xbbg_bsrch" | "xbbg_bqr" | "xbbg_bflds" | "xbbg_beqs" | "xbbg_yas" | "xbbg_preferreds" | "xbbg_corporate_bonds" | "xbbg_index_members" | "xbbg_resolve_isins" | "xbbg_issuer_isins" | "xbbg_etf_holdings" | "xbbg_stream_snapshot" | "xbbg_mktbar_snapshot" | "xbbg_depth_snapshot" | "xbbg_ext_ticker" | "xbbg_ext_futures" | "xbbg_ext_cdx" | "xbbg_ext_currency" | "xbbg_ext_bql_builder" | "xbbg_ext_market_session" | "xbbg_ext_yas_overrides" | "xbbg_ext_constants" | "xbbg_ext_columns" | "xbbg_ext_calculate")[];
+declare const BLOOMBERG_EXT_TOOL_NAMES: readonly ("xbbg_bdp" | "xbbg_bdh" | "xbbg_bds" | "xbbg_bdib" | "xbbg_bdtick" | "xbbg_bql" | "xbbg_bsrch" | "xbbg_bqr" | "xbbg_bflds" | "xbbg_beqs" | "xbbg_yas" | "xbbg_preferreds" | "xbbg_corporate_bonds" | "xbbg_index_members" | "xbbg_resolve_isins" | "xbbg_issuer_isins" | "xbbg_etf_holdings" | "xbbg_stream_snapshot" | "xbbg_mktbar_snapshot" | "xbbg_depth_snapshot" | "xbbg_ext_ticker" | "xbbg_ext_futures" | "xbbg_ext_cdx" | "xbbg_ext_currency" | "xbbg_ext_bql_builder" | "xbbg_ext_chart_spec" | "xbbg_ext_market_session" | "xbbg_ext_yas_overrides" | "xbbg_ext_constants" | "xbbg_ext_columns" | "xbbg_ext_calculate")[];
 declare function createExtTickerTool(options?: BloombergToolsOptions): BloombergTool;
 declare function createExtFuturesTool(options?: BloombergToolsOptions): BloombergTool;
 declare function createExtCdxTool(options?: BloombergToolsOptions): BloombergTool;
@@ -86,6 +86,7 @@ declare function createExtYasOverridesTool(options?: BloombergToolsOptions): Blo
 declare function createExtConstantsTool(options?: BloombergToolsOptions): BloombergTool;
 declare function createExtColumnsTool(options?: BloombergToolsOptions): BloombergTool;
 declare function createExtCalculateTool(options?: BloombergToolsOptions): BloombergTool;
+declare function createExtChartSpecTool(options?: BloombergToolsOptions): BloombergTool;
 declare function createBloombergExtTools(options?: BloombergToolsOptions): BloombergTool[];
 
 interface ToolEnvelope {
@@ -111,6 +112,68 @@ interface ToolInvocationConfig {
  */
 declare function toolParameterJsonSchema(toolInstance: StructuredToolInterface): Record<string, unknown>;
 
+type BloombergChartSource = "bdh" | "bdib" | "holdings" | "depth" | "rows";
+type ChartKind = "line" | "area" | "bar" | "scatter" | "candlestick" | "depth";
+type ChartRenderer = "vega-lite";
+type ChartScalar = string | number | boolean | null;
+type ChartRow = Readonly<Record<string, ChartScalar>>;
+interface ChartSpecInput {
+    readonly source: BloombergChartSource;
+    readonly rows: readonly ChartRow[];
+    readonly renderer?: ChartRenderer;
+    readonly chart?: ChartKind;
+    readonly title?: string;
+    readonly xField?: string;
+    readonly yFields?: readonly string[];
+    readonly seriesField?: string;
+    readonly labelField?: string;
+    readonly valueField?: string;
+    readonly openField?: string;
+    readonly highField?: string;
+    readonly lowField?: string;
+    readonly closeField?: string;
+    readonly sideField?: string;
+    readonly priceField?: string;
+    readonly sizeField?: string;
+    readonly maxPoints?: number;
+}
+
+interface ChartSpecSummary {
+    readonly chart: ChartKind;
+    readonly inputRows: number;
+    readonly renderer: "vega-lite";
+    readonly rowCount: number;
+    readonly source: BloombergChartSource;
+    readonly title: string;
+    readonly truncatedInput: boolean;
+    readonly xField?: string;
+    readonly yFields: readonly string[];
+    readonly seriesField?: string;
+}
+interface VegaLiteSpec {
+    readonly $schema: "https://vega.github.io/schema/vega-lite/v5.json";
+    readonly data: {
+        readonly values: readonly ChartRow[];
+    };
+    readonly description: string;
+    readonly title: string;
+    readonly [key: string]: unknown;
+}
+interface ChartSpecOutput {
+    readonly kind: "xbbg.visualization";
+    readonly version: 1;
+    readonly component: "xbbg_chart";
+    readonly renderer: "vega-lite";
+    readonly rowCount: number;
+    readonly inputRowCount: number;
+    readonly truncatedInput: boolean;
+    readonly source: BloombergChartSource;
+    readonly chart: ChartKind;
+    readonly summary: ChartSpecSummary;
+    readonly spec: VegaLiteSpec;
+    readonly warnings: readonly string[];
+}
+
 declare function createAllBloombergTools(options?: BloombergToolsOptions): BloombergTool[];
 
-export { BLOOMBERG_EXT_TOOL_NAMES, BLOOMBERG_TOOL_INSTRUCTIONS, BLOOMBERG_TOOL_NAMES, type BloombergTool, type BloombergToolInstructionsOptions, type BloombergToolName, type BloombergToolsOptions, DEFAULT_ENGINE_REQUEST_TIMEOUT_MS, type NormalizedBloombergToolsOptions, type ToolEnvelope, type ToolInvocationConfig, createAllBloombergTools, createBdhTool, createBdibTool, createBdpTool, createBdsTool, createBdtickTool, createBeqsTool, createBfldsTool, createBloombergExtTools, createBloombergTools, createBqlTool, createBqrTool, createBsrchTool, createCorporateBondsTool, createDepthSnapshotTool, createEtfHoldingsTool, createExtBqlBuilderTool, createExtCalculateTool, createExtCdxTool, createExtColumnsTool, createExtConstantsTool, createExtCurrencyTool, createExtFuturesTool, createExtMarketSessionTool, createExtTickerTool, createExtYasOverridesTool, createIndexMembersTool, createIssuerIsinsTool, createMktbarSnapshotTool, createPreferredsTool, createResolveIsinsTool, createStreamSnapshotTool, createYasTool, getBloombergToolInstructions, toolParameterJsonSchema };
+export { BLOOMBERG_EXT_TOOL_NAMES, BLOOMBERG_TOOL_INSTRUCTIONS, BLOOMBERG_TOOL_NAMES, type BloombergChartSource, type BloombergTool, type BloombergToolInstructionsOptions, type BloombergToolName, type BloombergToolsOptions, type ChartKind, type ChartRenderer, type ChartRow, type ChartScalar, type ChartSpecInput, type ChartSpecOutput, type ChartSpecSummary, DEFAULT_ENGINE_REQUEST_TIMEOUT_MS, type NormalizedBloombergToolsOptions, type ToolEnvelope, type ToolInvocationConfig, type VegaLiteSpec, createAllBloombergTools, createBdhTool, createBdibTool, createBdpTool, createBdsTool, createBdtickTool, createBeqsTool, createBfldsTool, createBloombergExtTools, createBloombergTools, createBqlTool, createBqrTool, createBsrchTool, createCorporateBondsTool, createDepthSnapshotTool, createEtfHoldingsTool, createExtBqlBuilderTool, createExtCalculateTool, createExtCdxTool, createExtChartSpecTool, createExtColumnsTool, createExtConstantsTool, createExtCurrencyTool, createExtFuturesTool, createExtMarketSessionTool, createExtTickerTool, createExtYasOverridesTool, createIndexMembersTool, createIssuerIsinsTool, createMktbarSnapshotTool, createPreferredsTool, createResolveIsinsTool, createStreamSnapshotTool, createYasTool, getBloombergToolInstructions, toolParameterJsonSchema };

package/dist/index.js

@@ -51,6 +51,7 @@ var BLOOMBERG_TOOL_NAMES = [
   "xbbg_ext_cdx",
   "xbbg_ext_currency",
   "xbbg_ext_bql_builder",
+  "xbbg_ext_chart_spec",
   "xbbg_ext_market_session",
   "xbbg_ext_yas_overrides",
   "xbbg_ext_constants",
@@ -244,12 +245,12 @@ function rowCountOf(value) {
   if (typeof value !== "object" || value === null) {
     return null;
   }
-  const record2 = value;
-  const rowCount = record2.rowCount;
+  const record3 = value;
+  const rowCount = record3.rowCount;
   if (typeof rowCount === "number" && Number.isInteger(rowCount) && rowCount >= 0) {
     return rowCount;
   }
-  const updateCount = record2.updateCount;
+  const updateCount = record3.updateCount;
   if (typeof updateCount === "number" && Number.isInteger(updateCount) && updateCount >= 0) {
     return updateCount;
   }
@@ -401,6 +402,389 @@ function createBloombergStructuredTool(func, fields) {
   );
 }
 
+// src/chart-spec.ts
+var VEGA_SCHEMA = "https://vega.github.io/schema/vega-lite/v5.json";
+var COMPONENT_NAME = "xbbg_chart";
+var X_FIELD_CANDIDATES = ["date", "time", "datetime", "timestamp"];
+var LABEL_FIELD_CANDIDATES = ["ticker", "security", "member", "name", "label"];
+var SERIES_FIELD_CANDIDATES = ["ticker", "security", "field", "side", "category"];
+var VALUE_FIELD_CANDIDATES = [
+  "value",
+  "PX_LAST",
+  "close",
+  "price",
+  "weight",
+  "marketValue",
+  "market_value"
+];
+var OPEN_FIELD_CANDIDATES = ["open", "OPEN", "PX_OPEN"];
+var HIGH_FIELD_CANDIDATES = ["high", "HIGH", "PX_HIGH"];
+var LOW_FIELD_CANDIDATES = ["low", "LOW", "PX_LOW"];
+var CLOSE_FIELD_CANDIDATES = ["close", "CLOSE", "PX_LAST", "last", "value"];
+var SIDE_FIELD_CANDIDATES = ["side", "SIDE", "type"];
+var PRICE_FIELD_CANDIDATES = ["price", "PRICE", "px", "PX"];
+var SIZE_FIELD_CANDIDATES = ["size", "SIZE", "quantity", "qty", "volume"];
+function defaultChartForSource(source) {
+  switch (source) {
+    case "bdib":
+      return "candlestick";
+    case "depth":
+      return "depth";
+    case "holdings":
+      return "bar";
+    case "bdh":
+    case "rows":
+      return "line";
+  }
+}
+function fieldExists(rows, field) {
+  for (const row of rows) {
+    if (Object.prototype.hasOwnProperty.call(row, field)) {
+      return true;
+    }
+  }
+  return false;
+}
+function findCandidateField(rows, candidates) {
+  for (const candidate of candidates) {
+    if (fieldExists(rows, candidate)) {
+      return candidate;
+    }
+  }
+  const first = rows[0];
+  if (first === void 0) {
+    return void 0;
+  }
+  const keys = Object.keys(first);
+  for (const candidate of candidates) {
+    const lower = candidate.toLowerCase();
+    const match = keys.find((key) => key.toLowerCase() === lower);
+    if (match !== void 0 && fieldExists(rows, match)) {
+      return match;
+    }
+  }
+  return void 0;
+}
+function requireField(rows, field, label, candidates) {
+  const resolved = field ?? findCandidateField(rows, candidates);
+  if (resolved === void 0 || !fieldExists(rows, resolved)) {
+    throw new Error(
+      `Missing ${label}; pass ${label} explicitly or include one of: ${candidates.join(", ")}`
+    );
+  }
+  return resolved;
+}
+function hasFiniteNumber(rows, field) {
+  for (const row of rows) {
+    if (typeof row[field] === "number" && Number.isFinite(row[field])) {
+      return true;
+    }
+  }
+  return false;
+}
+function firstNumericField(rows, excludedField) {
+  const first = rows[0];
+  if (first === void 0) {
+    return void 0;
+  }
+  for (const key of Object.keys(first)) {
+    if (key !== excludedField && hasFiniteNumber(rows, key)) {
+      return key;
+    }
+  }
+  return void 0;
+}
+function requireNumericField(rows, field, label) {
+  if (!hasFiniteNumber(rows, field)) {
+    throw new Error(`${label} (${field}) must contain at least one finite numeric value`);
+  }
+}
+function inferVegaType(rows, field) {
+  for (const row of rows) {
+    const value = row[field];
+    if (typeof value === "number") {
+      return "quantitative";
+    }
+    if (typeof value === "string" && (/^\d{4}-\d{2}-\d{2}(?:$|[T\s])/u.test(value) || /^\d{8}$/u.test(value))) {
+      return "temporal";
+    }
+  }
+  return "nominal";
+}
+function normalizeTemporalRows(rows, field) {
+  let normalized;
+  for (let index = 0; index < rows.length; index += 1) {
+    const row = rows[index];
+    if (row === void 0) {
+      continue;
+    }
+    const value = row[field];
+    if (typeof value !== "string" || !/^\d{8}$/u.test(value)) {
+      normalized?.push(row);
+      continue;
+    }
+    normalized ??= rows.slice(0, index);
+    normalized.push({
+      ...row,
+      [field]: `${value.slice(0, 4)}-${value.slice(4, 6)}-${value.slice(6, 8)}`
+    });
+  }
+  return normalized ?? rows;
+}
+function tooltip(fields) {
+  return fields.map((field) => ({
+    field,
+    type: field === "_xbbg_value" ? "quantitative" : "nominal"
+  }));
+}
+function datumField(field) {
+  return `datum[${JSON.stringify(field)}]`;
+}
+function buildGenericSpec(input, rows, chart, title) {
+  const xField = requireField(rows, input.xField, "xField", X_FIELD_CANDIDATES);
+  let yFields;
+  if (input.yFields !== void 0) {
+    yFields = input.yFields;
+  } else {
+    const yField = findCandidateField(rows, VALUE_FIELD_CANDIDATES) ?? firstNumericField(rows, xField);
+    if (yField === void 0) {
+      throw new Error("Missing yFields; include at least one numeric value field");
+    }
+    yFields = [yField];
+  }
+  if (yFields.length === 0) {
+    throw new Error("Missing yFields; include at least one numeric value field");
+  }
+  for (const field of yFields) {
+    if (!fieldExists(rows, field)) {
+      throw new Error(`Missing y field: ${field}`);
+    }
+    requireNumericField(rows, field, "yField");
+  }
+  const normalizedRows = inferVegaType(rows, xField) === "temporal" ? normalizeTemporalRows(rows, xField) : rows;
+  const seriesField = input.seriesField ?? (yFields.length === 1 ? findCandidateField(rows, SERIES_FIELD_CANDIDATES) : void 0);
+  if (seriesField !== void 0 && !fieldExists(rows, seriesField)) {
+    throw new Error(`Missing series field: ${seriesField}`);
+  }
+  const mark = chart === "scatter" ? "point" : chart;
+  const encoding = {
+    x: { field: xField, title: xField, type: inferVegaType(normalizedRows, xField) }
+  };
+  const transform = [];
+  if (yFields.length === 1) {
+    const yField = yFields[0];
+    if (yField === void 0) {
+      throw new Error("Missing yFields; include at least one numeric value field");
+    }
+    encoding.y = { field: yField, title: yField, type: "quantitative" };
+    if (seriesField !== void 0) {
+      encoding.color = { field: seriesField, title: seriesField, type: "nominal" };
+    }
+    encoding.tooltip = tooltip([
+      xField,
+      ...seriesField === void 0 ? [] : [seriesField],
+      yField
+    ]);
+  } else {
+    transform.push({ as: ["_xbbg_series", "_xbbg_value"], fold: yFields });
+    encoding.y = { field: "_xbbg_value", title: "value", type: "quantitative" };
+    encoding.color = { field: "_xbbg_series", title: "series", type: "nominal" };
+    if (seriesField !== void 0) {
+      encoding.detail = { field: seriesField, type: "nominal" };
+    }
+    encoding.tooltip = tooltip([
+      xField,
+      ...seriesField === void 0 ? [] : [seriesField],
+      "_xbbg_series",
+      "_xbbg_value"
+    ]);
+  }
+  const spec = {
+    $schema: VEGA_SCHEMA,
+    data: { values: normalizedRows },
+    description: `xbbg ${chart} chart spec for ${input.source}`,
+    mark: { type: mark, tooltip: true },
+    title,
+    ...transform.length === 0 ? {} : { transform },
+    encoding
+  };
+  return { spec, xField, yFields, ...seriesField === void 0 ? {} : { seriesField } };
+}
+function buildBarSpec(input, rows, title) {
+  const xField = requireField(
+    rows,
+    input.xField ?? input.labelField,
+    "labelField",
+    LABEL_FIELD_CANDIDATES
+  );
+  const yField = requireField(
+    rows,
+    input.valueField ?? input.yFields?.[0],
+    "valueField",
+    VALUE_FIELD_CANDIDATES
+  );
+  requireNumericField(rows, yField, "valueField");
+  const seriesField = input.seriesField;
+  if (seriesField !== void 0 && !fieldExists(rows, seriesField)) {
+    throw new Error(`Missing series field: ${seriesField}`);
+  }
+  const encoding = {
+    x: { field: xField, sort: "-y", title: xField, type: inferVegaType(rows, xField) },
+    y: { field: yField, title: yField, type: "quantitative" },
+    tooltip: tooltip([xField, ...seriesField === void 0 ? [] : [seriesField], yField])
+  };
+  if (seriesField !== void 0) {
+    encoding.color = { field: seriesField, title: seriesField, type: "nominal" };
+  }
+  return {
+    spec: {
+      $schema: VEGA_SCHEMA,
+      data: { values: rows },
+      description: `xbbg bar chart spec for ${input.source}`,
+      encoding,
+      mark: { type: "bar", tooltip: true },
+      title
+    },
+    xField,
+    yFields: [yField],
+    ...seriesField === void 0 ? {} : { seriesField }
+  };
+}
+function buildCandlestickSpec(input, rows, title) {
+  const xField = requireField(rows, input.xField, "xField", X_FIELD_CANDIDATES);
+  const openField = requireField(rows, input.openField, "openField", OPEN_FIELD_CANDIDATES);
+  const highField = requireField(rows, input.highField, "highField", HIGH_FIELD_CANDIDATES);
+  const lowField = requireField(rows, input.lowField, "lowField", LOW_FIELD_CANDIDATES);
+  const closeField = requireField(rows, input.closeField, "closeField", CLOSE_FIELD_CANDIDATES);
+  for (const [label, field] of [
+    ["openField", openField],
+    ["highField", highField],
+    ["lowField", lowField],
+    ["closeField", closeField]
+  ]) {
+    requireNumericField(rows, field, label);
+  }
+  const normalizedRows = inferVegaType(rows, xField) === "temporal" ? normalizeTemporalRows(rows, xField) : rows;
+  const color = {
+    condition: { test: `${datumField(closeField)} >= ${datumField(openField)}`, value: "#137333" },
+    value: "#c5221f"
+  };
+  return {
+    spec: {
+      $schema: VEGA_SCHEMA,
+      data: { values: normalizedRows },
+      description: `xbbg candlestick chart spec for ${input.source}`,
+      encoding: {
+        x: { field: xField, title: xField, type: inferVegaType(normalizedRows, xField) }
+      },
+      layer: [
+        {
+          mark: "rule",
+          encoding: {
+            color,
+            tooltip: tooltip([xField, openField, highField, lowField, closeField]),
+            y: { field: lowField, title: "price", type: "quantitative" },
+            y2: { field: highField }
+          }
+        },
+        {
+          mark: "bar",
+          encoding: {
+            color,
+            y: { field: openField, title: "price", type: "quantitative" },
+            y2: { field: closeField }
+          }
+        }
+      ],
+      title
+    },
+    xField,
+    yFields: [openField, highField, lowField, closeField]
+  };
+}
+function buildDepthSpec(input, rows, title) {
+  const priceField = requireField(
+    rows,
+    input.priceField ?? input.xField,
+    "priceField",
+    PRICE_FIELD_CANDIDATES
+  );
+  const sizeField = requireField(
+    rows,
+    input.sizeField ?? input.valueField ?? input.yFields?.[0],
+    "sizeField",
+    SIZE_FIELD_CANDIDATES
+  );
+  const sideField = requireField(
+    rows,
+    input.sideField ?? input.seriesField,
+    "sideField",
+    SIDE_FIELD_CANDIDATES
+  );
+  requireNumericField(rows, priceField, "priceField");
+  requireNumericField(rows, sizeField, "sizeField");
+  return {
+    spec: {
+      $schema: VEGA_SCHEMA,
+      data: { values: rows },
+      description: `xbbg market depth chart spec for ${input.source}`,
+      encoding: {
+        color: { field: sideField, title: sideField, type: "nominal" },
+        tooltip: tooltip([sideField, priceField, sizeField]),
+        x: { field: priceField, title: priceField, type: "quantitative" },
+        y: { field: sizeField, title: sizeField, type: "quantitative" }
+      },
+      mark: { type: "bar", tooltip: true },
+      title
+    },
+    xField: priceField,
+    yFields: [sizeField],
+    seriesField: sideField
+  };
+}
+function createChartSpec(input) {
+  const maxPoints = input.maxPoints ?? input.rows.length;
+  const rows = input.rows.length > maxPoints ? input.rows.slice(0, maxPoints) : input.rows;
+  if (rows.length === 0) {
+    throw new Error("rows must contain at least one chart data row");
+  }
+  const chart = input.chart ?? defaultChartForSource(input.source);
+  const title = input.title ?? `${input.source} ${chart}`;
+  const warnings = [];
+  if (rows.length !== input.rows.length) {
+    warnings.push(
+      `Chart spec contains first ${rows.length} of ${input.rows.length} rows; narrow the upstream request for a complete visualization.`
+    );
+  }
+  const built = chart === "candlestick" ? buildCandlestickSpec(input, rows, title) : chart === "depth" ? buildDepthSpec(input, rows, title) : chart === "bar" ? buildBarSpec(input, rows, title) : buildGenericSpec(input, rows, chart, title);
+  const summary = {
+    chart,
+    inputRows: input.rows.length,
+    renderer: "vega-lite",
+    rowCount: rows.length,
+    source: input.source,
+    title,
+    truncatedInput: rows.length !== input.rows.length,
+    xField: built.xField,
+    yFields: built.yFields,
+    ...built.seriesField === void 0 ? {} : { seriesField: built.seriesField }
+  };
+  return {
+    kind: "xbbg.visualization",
+    version: 1,
+    component: COMPONENT_NAME,
+    renderer: "vega-lite",
+    rowCount: rows.length,
+    inputRowCount: input.rows.length,
+    truncatedInput: rows.length !== input.rows.length,
+    source: input.source,
+    chart,
+    summary,
+    spec: built.spec,
+    warnings
+  };
+}
+
 // src/cdx-fields.ts
 var CDX_INFO_FIELDS = Object.freeze([
   "ROLLING_SERIES",
@@ -492,6 +876,7 @@ var OPTIONAL_EXTENSION_INSTRUCTIONS = [
   "- xbbg_ext_cdx: CDX ticker workflow support. Use parse_cdx_ticker to understand a CDX ticker, previous_cdx_series to roll back a series, cdx_gen_to_specific to resolve a generic CDX to a target series, and cdx_info/cdx_pricing/cdx_risk for predefined BDP field bundles. cdx_pricing and cdx_risk accept recoveryRate, which becomes the CDS_RR override.",
   "- xbbg_ext_currency: currency-planning helpers. build_fx_pair constructs the Bloomberg FX pair and conversion factor, same_currency avoids unnecessary conversion, and currencies_needing_conversion identifies which currencies differ from a target before requesting converted values.",
   "- xbbg_ext_bql_builder: safe BQL generators for common xbbg workflows. Use build_preferreds_query for preferred-stock discovery from an equity, build_corporate_bonds_query for company bond universes with optional currency/active filters, and build_etf_holdings_query for ETF constituents. Prefer these builders over hand-writing those BQL shapes.",
+  "- xbbg_ext_chart_spec: renderer-neutral chart spec helper. Convert bounded rows from xbbg_bdh, xbbg_bdib, holdings, depth, or already-shaped row data into a Vega-Lite JSON spec for frontend rendering; do not use it as proof that Bloomberg data was fetched.",
   "- xbbg_ext_market_session: exchange calendar/timezone support. derive_sessions turns day session times into session blocks, infer_timezone maps country codes to timezones, session_times_to_utc converts local sessions to UTC, get_market_rule gets MIC/exchange rules, default_turnover_dates and default_bqr_datetimes provide bounded defaults, and get/list_exchange_override inspect configured exchange metadata.",
   "- xbbg_ext_yas_overrides: builds flat YAS override maps for fixed-income BDP requests when the lower-level BDP workflow is required. Prefer xbbg_yas for actual YAS recipe fields.",
   "- xbbg_ext_constants: static lookup/format helpers for date parsing/formatting, futures month code/name mappings, dividend type mappings, and known dividend/ETF output columns.",
@@ -547,6 +932,7 @@ var EXT_FUTURES_DESCRIPTION = "Futures helpers for contract construction and sel
 var EXT_CDX_DESCRIPTION = "CDX helpers for parsing, series rolling/resolution, and predefined info/pricing/risk BDP field bundles.";
 var EXT_CURRENCY_DESCRIPTION = "Currency planning helpers: build FX pairs, test same-currency requests, and find currencies needing conversion.";
 var EXT_BQL_BUILDER_DESCRIPTION = "BQL builders for preferred stocks, corporate bonds, and ETF holdings. Prefer to construct those bounded BQL shapes before xbbg_bql.";
+var EXT_CHART_SPEC_DESCRIPTION = "Renderer-neutral chart spec helper for frontend generative UI. Converts bounded Bloomberg rows from bdh, bdib, holdings, depth, or already-shaped row data into a Vega-Lite JSON spec; it does not fetch Bloomberg data or render images.";
 var EXT_MARKET_SESSION_DESCRIPTION = "Market session and timezone helpers for deriving sessions, UTC windows, market rules, exchange metadata, turnover defaults, and BQR datetime defaults.";
 var EXT_YAS_OVERRIDES_DESCRIPTION = "Build flat Bloomberg YAS override maps for fixed-income analytics fields.";
 var EXT_CONSTANTS_DESCRIPTION = "Static Bloomberg helper constants for date parsing/formatting, futures months, dividend types, and ETF/dividend columns.";
@@ -802,6 +1188,35 @@ function calculateSchema(options) {
     }
   });
 }
+function chartSpecSchema(options) {
+  const chartScalar = z__namespace.union([
+    z__namespace.string().trim().max(options.maxStringChars),
+    z__namespace.number(),
+    z__namespace.boolean(),
+    z__namespace.null()
+  ]);
+  const fieldName = nonEmptyString(options, "Input row field name.");
+  return z__namespace.object({
+    chart: z__namespace.enum(["line", "area", "bar", "scatter", "candlestick", "depth"]).optional().describe("Chart shape to generate. Defaults from source."),
+    closeField: fieldName.optional().describe("Candlestick close-value field."),
+    highField: fieldName.optional().describe("Candlestick high-value field."),
+    labelField: fieldName.optional().describe("Categorical label field for bar charts."),
+    lowField: fieldName.optional().describe("Candlestick low-value field."),
+    maxPoints: z__namespace.number().int().positive().max(options.maxRows).optional().describe("Maximum rows to include in the frontend spec; defaults to all provided rows."),
+    openField: fieldName.optional().describe("Candlestick open-value field."),
+    priceField: fieldName.optional().describe("Market-depth price field."),
+    renderer: z__namespace.literal("vega-lite").optional().describe("Visualization spec renderer. Currently only vega-lite is generated."),
+    rows: z__namespace.array(z__namespace.record(chartScalar)).min(1).max(options.maxRows).describe("Chart data rows copied from a bounded Bloomberg tool result."),
+    seriesField: fieldName.optional().describe("Optional series/color field."),
+    sideField: fieldName.optional().describe("Market-depth bid/ask side field."),
+    sizeField: fieldName.optional().describe("Market-depth size field."),
+    source: z__namespace.enum(["bdh", "bdib", "holdings", "depth", "rows"]).describe("Bloomberg result shape that produced rows."),
+    title: nonEmptyString(options, "Chart title.").optional(),
+    valueField: fieldName.optional().describe("Primary numeric value field."),
+    xField: fieldName.optional().describe("X-axis field."),
+    yFields: stringArray(options, "Numeric value fields to plot.").optional()
+  }).strict();
+}
 
 // src/ext-tools.ts
 function resultString(resolver, name, value) {
@@ -816,6 +1231,7 @@ var EXT_TOOL_DEFINITIONS = Object.freeze([
   { create: extCdxWithResolver, name: "xbbg_ext_cdx" },
   { create: extCurrencyWithResolver, name: "xbbg_ext_currency" },
   { create: extBqlBuilderWithResolver, name: "xbbg_ext_bql_builder" },
+  { create: extChartSpecWithResolver, name: "xbbg_ext_chart_spec" },
   { create: extMarketSessionWithResolver, name: "xbbg_ext_market_session" },
   { create: extYasOverridesWithResolver, name: "xbbg_ext_yas_overrides" },
   { create: extConstantsWithResolver, name: "xbbg_ext_constants" },
@@ -825,6 +1241,24 @@ var EXT_TOOL_DEFINITIONS = Object.freeze([
 var BLOOMBERG_EXT_TOOL_NAMES = Object.freeze(
   EXT_TOOL_DEFINITIONS.map((definition) => definition.name)
 );
+function extChartSpecWithResolver(resolver) {
+  const name = "xbbg_ext_chart_spec";
+  return createBloombergStructuredTool(
+    async (input) => {
+      try {
+        return await Promise.resolve(resultString(resolver, name, createChartSpec(input)));
+      } catch (error) {
+        throwWithToolContext(name, error);
+      }
+    },
+    {
+      responseFormat: "content_and_artifact",
+      description: EXT_CHART_SPEC_DESCRIPTION,
+      name,
+      schema: chartSpecSchema(resolver.options)
+    }
+  );
+}
 function extTickerWithResolver(resolver) {
   const name = "xbbg_ext_ticker";
   return createBloombergStructuredTool(
@@ -1238,6 +1672,9 @@ function createExtColumnsTool(options = {}) {
 function createExtCalculateTool(options = {}) {
   return extCalculateWithResolver(createCoreResolver(options));
 }
+function createExtChartSpecTool(options = {}) {
+  return extChartSpecWithResolver(createCoreResolver(options));
+}
 function createBloombergExtToolsForResolver(resolver) {
   return EXT_TOOL_DEFINITIONS.filter(
     (definition) => !isToolDisabled(resolver.options, definition.name)
@@ -1731,7 +2168,7 @@ function createPreferredsSchema(options) {
     ).describe(
       "The issuer's common equity ticker as '<TICKER> <MARKET_SECTOR>', never a preferred ('Pfd') ticker and never a guessed one. Resolve a supplied ISIN/CUSIP with xbbg_resolve_isins first."
     ),
-    fields: stringArray2(tool2, "fields", options.maxFields, options.maxStringChars, '["<FIELD>"]').optional().describe("Optional fields to include in the preferreds recipe result.")
+    fields: z__namespace.array(nonEmptyString2(tool2, "fields", options.maxStringChars, '["<FIELD>"]')).max(options.maxFields, `${tool2}: fields can contain at most ${options.maxFields} values`).transform((fields) => fields.length === 0 ? void 0 : fields).optional().describe("Optional fields to include in the preferreds recipe result.")
   });
 }
 function createCorporateBondsSchema(options) {
@@ -2669,6 +3106,7 @@ exports.createEtfHoldingsTool = createEtfHoldingsTool;
 exports.createExtBqlBuilderTool = createExtBqlBuilderTool;
 exports.createExtCalculateTool = createExtCalculateTool;
 exports.createExtCdxTool = createExtCdxTool;
+exports.createExtChartSpecTool = createExtChartSpecTool;
 exports.createExtColumnsTool = createExtColumnsTool;
 exports.createExtConstantsTool = createExtConstantsTool;
 exports.createExtCurrencyTool = createExtCurrencyTool;