@xbbg/langgraph 1.3.0 → 1.4.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 };