@xbbg/langgraph 1.2.7 → 1.3.1

package/README.md

@@ -140,12 +140,12 @@ Core Bloomberg request tools:
 - `xbbg_mktbar_snapshot` - bounded `//blp/mktbar` live bar observation for one ticker.
 - `xbbg_depth_snapshot` - bounded `//blp/mktdepthdata` market-depth observation for one ticker.
 
-For raw identifiers, ask for or pass Bloomberg's identifier syntax directly: `/isin/<ISIN>` for ISINs and `/cusip/<CUSIP>` for CUSIPs.
+Securities are passed through in the form the user supplied them: Bloomberg tickers as `<TICKER> <MARKET_SECTOR>` (for example `<TICKER> <EXCHANGE> Equity`, `<INDEX_TICKER> Index`, `<CCY_PAIR> Curncy`), raw ISINs as `/isin/<ISIN>`, raw CUSIPs as `/cusip/<CUSIP>`. The market sector ending is Bloomberg's yellow key — `Equity`, `Index`, `Curncy`, `Comdty`, `Corp`, `Govt`, `Muni`, `Mtge`, `M-Mkt`, or `Pfd` (preferred securities) — and request tools pass it through to Bloomberg unvalidated. The agent guidance and every securities/ticker field description instruct the model that the ticker format is a template, not authorization to construct one — identifiers are never converted into guessed tickers; `xbbg_resolve_isins` exists for explicit resolution. Note `xbbg_ext_ticker`'s `parse_ticker` is narrower than the request tools: it parses generic futures-style tickers only (`Index`/`Curncy`/`Comdty`/`Corp`, or `<ROOT><N> <EXCHANGE> Equity`) and rejects other sectors.
 BQL is passed as one complete expression string. Use placeholder shapes such as `get(<FIELD>) for('<TICKER> <MARKET_SECTOR>')`, `get(<FIELD_1>, <FIELD_2>) for(['<TICKER_1> <MARKET_SECTOR>', '<TICKER_2> <MARKET_SECTOR>'])`, `get(<FIELD>, <WEIGHT_FIELD>) for(holdings('<ETF_TICKER> <MARKET_SECTOR>'))`, or `get(<FIELD>) for(members('<INDEX_TICKER> <MARKET_SECTOR>')) with(...)`. Prefer `xbbg_bdp`/`xbbg_bdh` for simple reference or historical requests.
 
 Dealer quote / BQR workflows in xbbg use fixed-income identifiers with a quote source, for example `/isin/<ISIN>@<QUOTE_SOURCE> <MARKET_SECTOR>`; use `xbbg_bqr` for that workflow and `xbbg_bdtick` for raw intraday ticks.
 
-Streaming surfaces are intentionally exposed only as bounded snapshot tools. Each snapshot requires `maxUpdates`, applies the configured `maxStreamUpdates`/`maxStreamWaitMs` caps, stops on count, timeout, or stream completion, and calls `unsubscribe(false)` unless `drain: true` is explicitly provided. The package does not expose open-ended async subscription iterators as agent tools.
+Streaming surfaces are intentionally exposed only as bounded snapshot tools. Each snapshot requires `maxUpdates`, applies the configured `maxStreamUpdates`/`maxStreamWaitMs` caps, stops on count, timeout, or stream completion, and calls `unsubscribe(false)` unless `drain: true` is explicitly provided. The package does not expose open-ended async subscription iterators as agent tools. If collection succeeds but releasing the subscription fails, the snapshot result still returns the collected updates and reports the failure in an `unsubscribeError` field instead of discarding data.
 
 ```ts
 import { createBloombergTools, createBdpTool } from "@xbbg/langgraph";
@@ -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,10 +177,40 @@ 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.
 
+Lazily connected engines get a hard per-request timeout (`DEFAULT_ENGINE_REQUEST_TIMEOUT_MS`, 60s) because `@xbbg/core` disables request timeouts by default, which would let a wedged Terminal session hang tool calls forever. Pass `engineConfig: { requestTimeoutMs: ... }` to change it, or `0` to disable. A user-supplied `engine` is used as-is — its configuration and lifecycle (including disconnect) stay with the caller.
+
 ```ts
 import * as xbbg from "@xbbg/core";
 import { createBloombergTools } from "@xbbg/langgraph";
@@ -188,6 +219,10 @@ const engine = await xbbg.connect({ host: "localhost", port: 8194 });
 const tools = createBloombergTools({ engine });
 ```
 
+### Cancellation
+
+Tools honor the LangChain/LangGraph `AbortSignal` (`graph.invoke(input, { signal })`): an aborted call rejects immediately, already-cancelled calls never start Bloomberg work, and snapshot tools stop collecting and unsubscribe right away (skipping `drain`) instead of running out their timeout. In-flight Bloomberg request/response calls cannot be cancelled mid-flight; they are bounded by the engine request timeout above.
+
 ## Limits and outputs
 
 Defaults:
@@ -199,6 +234,12 @@ Defaults:
 - `maxStreamUpdates = 10`
 - `maxStreamWaitMs = 15000`
 
+Date inputs accept `YYYY-MM-DD` or `YYYYMMDD` strings, integer `YYYYMMDD` values (parsed as calendar dates), and epoch milliseconds; ambiguous numbers between those ranges and ambiguous `MM/DD/YYYY` strings are rejected with actionable schema errors. `Date` instances are deliberately not part of the wire contract: JSON tool calls cannot carry them and `z.date()` breaks JSON Schema conversion in zod v4.
+
+Schemas only advertise parameters the engine accepts: `format` exists on `xbbg_bdp`/`xbbg_bdh` only, because the engine rejects it for BulkData (`xbbg_bds`), BQL, search, field-info, and BEQS output; a model-sent `format` on those tools is stripped rather than forwarded. The exported `toolParameterJsonSchema(tool)` returns the provider-ready `$ref`-free JSON Schema used in each tool's embedded provider definition.
+
+Empty results are called out in the model-facing summary (`empty result; verify identifiers, fields, and date range before concluding no data exists`) so agents distinguish "no rows" from silent failure instead of inventing data.
+
 Each tool uses `backend: "json"` for finite request results and LangChain `content_and_artifact` output. The model-facing content starts with a short summary and then includes bounded JSON data:
 
 ```text

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;
@@ -24,7 +24,7 @@ interface BloombergToolsOptions {
 }
 interface NormalizedBloombergToolsOptions {
     readonly engine?: XbbgEngineLike;
-    readonly engineConfig?: xbbg.EngineConfig;
+    readonly engineConfig: xbbg.EngineConfig;
     readonly core?: XbbgCoreLike;
     readonly maxSecurities: number;
     readonly maxFields: number;
@@ -37,6 +37,13 @@ interface NormalizedBloombergToolsOptions {
     readonly validateFields: boolean | undefined;
     readonly disabledTools: ReadonlySet<BloombergToolName>;
 }
+/**
+ * Default hard per-request timeout applied to lazily connected engines.
+ * @xbbg/core disables request timeouts by default (`requestTimeoutMs: 0`),
+ * which would let a wedged Terminal session hang tool calls forever. An
+ * explicit `engineConfig.requestTimeoutMs` (including 0) always wins.
+ */
+declare const DEFAULT_ENGINE_REQUEST_TIMEOUT_MS = 60000;
 
 type BloombergTool = StructuredToolInterface;
 declare function createBdpTool(options?: BloombergToolsOptions): BloombergTool;
@@ -68,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;
@@ -79,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 {
@@ -88,6 +96,84 @@ interface ToolEnvelope {
     readonly data: unknown;
 }
 
+/**
+ * Subset of the LangChain runnable config forwarded to tool functions.
+ * `signal` aborts the call: the LangChain wrapper rejects immediately, and
+ * Bloomberg tool functions use it to stop waiting and release subscriptions.
+ */
+interface ToolInvocationConfig {
+    readonly signal?: AbortSignal;
+}
+/**
+ * Provider-ready JSON Schema for a Bloomberg tool's input parameters, using
+ * the same conversion settings as the embedded provider tool definition
+ * ($ref-free, input-side of transforms). Exposed so consumers do not each
+ * reinvent zod -> JSON Schema conversion and sanitization.
+ */
+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, type NormalizedBloombergToolsOptions, type ToolEnvelope, 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 };
+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 };