@xbbg/langgraph 1.3.0 → 1.4.1

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.",
@@ -503,7 +888,7 @@ var OPTIONAL_LIMIT_INSTRUCTIONS = [
   "## Request limits and inputs",
   "- Keep Bloomberg requests bounded: explicit securities, explicit fields, explicit dates, limited rows, and no broad exploratory pulls unless the user narrows the universe.",
   "- Respect configured tool limits for securities, fields, rows, string size, BQL length, and search spec length. Ask the user to narrow the request rather than exceeding them.",
-  "- Use flat primitive overrides and kwargs only: string, number, or boolean values. Do not send nested objects, arrays, or inferred defaults as overrides."
+  "- Use primitive kwargs only: string, number, or boolean values. For overrides on xbbg_bdp/xbbg_bdh/xbbg_bds, use primitive values for global overrides and nested primitive maps keyed by exact security for per-security overrides. Do not send other nested objects, arrays, or inferred defaults."
 ];
 var BLOOMBERG_TOOL_INSTRUCTIONS = [
   ...REQUIRED_TOOL_INSTRUCTIONS,
@@ -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)
@@ -1383,6 +1820,60 @@ function primitiveMap(tool2, field) {
     return normalized;
   });
 }
+function overridesMap(tool2, field) {
+  return z__namespace.record(
+    z__namespace.string().min(1),
+    z__namespace.union([primitiveSchema, z__namespace.record(z__namespace.string().min(1), primitiveSchema)])
+  ).optional().transform((value, context) => {
+    if (value === void 0) {
+      return void 0;
+    }
+    const normalized = {};
+    for (const [key, entry] of Object.entries(value)) {
+      const normalizedKey = key.trim();
+      if (normalizedKey.length === 0) {
+        return normalizationIssue(context, tool2, field, new TypeError("contains an empty key"));
+      }
+      if (typeof entry !== "object") {
+        if (typeof entry === "string" && entry.length === 0) {
+          return normalizationIssue(
+            context,
+            tool2,
+            field,
+            new TypeError(`${normalizedKey} must not be an empty string`)
+          );
+        }
+        normalized[normalizedKey] = entry;
+        continue;
+      }
+      const normalizedOverrides = {};
+      for (const [overrideKey, overrideValue] of Object.entries(entry)) {
+        const normalizedOverrideKey = overrideKey.trim();
+        if (normalizedOverrideKey.length === 0) {
+          return normalizationIssue(
+            context,
+            tool2,
+            field,
+            new TypeError(`${normalizedKey} contains an empty override key`)
+          );
+        }
+        if (typeof overrideValue === "string" && overrideValue.length === 0) {
+          return normalizationIssue(
+            context,
+            tool2,
+            field,
+            new TypeError(
+              `${normalizedKey}.${normalizedOverrideKey} must not be an empty string`
+            )
+          );
+        }
+        normalizedOverrides[normalizedOverrideKey] = overrideValue;
+      }
+      normalized[normalizedKey] = normalizedOverrides;
+    }
+    return normalized;
+  });
+}
 function dateField(tool2, field) {
   return z__namespace.union([z__namespace.string(), z__namespace.number()]).transform((value, context) => {
     try {
@@ -1445,8 +1936,8 @@ function createBdpSchema(options) {
     kwargs: primitiveMap(tool2, "kwargs").describe(
       "Advanced Bloomberg request kwargs as flat string/number/boolean values only."
     ),
-    overrides: primitiveMap(tool2, "overrides").describe(
-      "Bloomberg field overrides as flat string/number/boolean values only."
+    overrides: overridesMap(tool2, "overrides").describe(
+      "Bloomberg field overrides. Use primitive values for global overrides and nested primitive maps keyed by exact security for per-security overrides."
     ),
     securities: stringArray2(
       tool2,
@@ -1477,8 +1968,8 @@ function createBdhSchema(options) {
     kwargs: primitiveMap(tool2, "kwargs").describe(
       "Advanced Bloomberg request kwargs as flat string/number/boolean values only."
     ),
-    overrides: primitiveMap(tool2, "overrides").describe(
-      "Bloomberg overrides as flat string/number/boolean values only."
+    overrides: overridesMap(tool2, "overrides").describe(
+      "Bloomberg overrides. Use primitive values for global overrides and nested primitive maps keyed by exact security for per-security overrides."
     ),
     securities: stringArray2(
       tool2,
@@ -1510,8 +2001,8 @@ function createBdsSchema(options) {
     kwargs: primitiveMap(tool2, "kwargs").describe(
       "Advanced Bloomberg request kwargs as flat string/number/boolean values only."
     ),
-    overrides: primitiveMap(tool2, "overrides").describe(
-      "Bloomberg overrides as flat string/number/boolean values only."
+    overrides: overridesMap(tool2, "overrides").describe(
+      "Bloomberg overrides. Use primitive values for global overrides and nested primitive maps keyed by exact security for per-security overrides."
     ),
     securities: stringArray2(
       tool2,
@@ -1731,7 +2222,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) {
@@ -2051,14 +2542,15 @@ function bdpWithResolver(resolver) {
     async (input) => {
       try {
         const engine = await resolver.getEngine();
-        const result = await engine.bdp(input.securities, input.fields, {
+        const options = {
           backend: "json",
           format: input.format,
           includeSecurityErrors: input.includeSecurityErrors,
           kwargs: input.kwargs,
           overrides: input.overrides,
           validateFields: validationSetting(resolver, input.validateFields)
-        });
+        };
+        const result = await engine.bdp(input.securities, input.fields, options);
         return resultString2(resolver, name, result);
       } catch (error) {
         throwWithToolContext(name, error);
@@ -2078,7 +2570,7 @@ function bdhWithResolver(resolver) {
     async (input) => {
       try {
         const engine = await resolver.getEngine();
-        const result = await engine.bdh(input.securities, input.fields, {
+        const options = {
           backend: "json",
           end: input.end,
           format: input.format,
@@ -2086,7 +2578,8 @@ function bdhWithResolver(resolver) {
           overrides: input.overrides,
           start: input.start,
           validateFields: validationSetting(resolver, input.validateFields)
-        });
+        };
+        const result = await engine.bdh(input.securities, input.fields, options);
         return resultString2(resolver, name, result);
       } catch (error) {
         throwWithToolContext(name, error);
@@ -2106,12 +2599,13 @@ function bdsWithResolver(resolver) {
     async (input) => {
       try {
         const engine = await resolver.getEngine();
-        const result = await engine.bds(input.securities, [input.field], {
+        const options = {
           backend: "json",
           kwargs: input.kwargs,
           overrides: input.overrides,
           validateFields: validationSetting(resolver, input.validateFields)
-        });
+        };
+        const result = await engine.bds(input.securities, [input.field], options);
         return resultString2(resolver, name, result);
       } catch (error) {
         throwWithToolContext(name, error);
@@ -2669,6 +3163,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;