From 16b5cb6ba8b3b19e8083f076b7e6173c3d6ee9b8 Mon Sep 17 00:00:00 2001 From: Greg Konush <12027037+gregkonush@users.noreply.github.com> Date: Fri, 22 May 2026 21:47:43 -0700 Subject: [PATCH] docs(js): add Bilig WorkPaper tool integration --- src/docs.json | 1 + .../integrations/tools/bilig_workpaper.mdx | 172 ++++++++++++++++++ .../javascript/integrations/tools/index.mdx | 13 +- 3 files changed, 183 insertions(+), 3 deletions(-) create mode 100644 src/oss/javascript/integrations/tools/bilig_workpaper.mdx diff --git a/src/docs.json b/src/docs.json index 629dbc399d..943d512a76 100644 --- a/src/docs.json +++ b/src/docs.json @@ -1837,6 +1837,7 @@ "pages": [ "oss/javascript/integrations/chat/index", "oss/javascript/integrations/tools/index", + "oss/javascript/integrations/tools/bilig_workpaper", "oss/javascript/integrations/llms/index", "oss/javascript/integrations/middleware/index", "oss/javascript/integrations/sandboxes/index", diff --git a/src/oss/javascript/integrations/tools/bilig_workpaper.mdx b/src/oss/javascript/integrations/tools/bilig_workpaper.mdx new file mode 100644 index 0000000000..387af07c40 --- /dev/null +++ b/src/oss/javascript/integrations/tools/bilig_workpaper.mdx @@ -0,0 +1,172 @@ +--- +title: "Bilig WorkPaper integration" +description: "Integrate with the Bilig WorkPaper tool using LangChain JavaScript." +--- + +[Bilig WorkPaper](https://github.com/proompteng/bilig) is a headless workbook runtime for Node.js services and agent tools. Use it when an agent needs to edit workbook input cells, recalculate formulas, and return proof that the computed output changed before the next step runs. + +This guide wraps a WorkPaper calculation as a LangChain tool. The example runs locally and does not require an API key. + +## Setup + +Install LangChain, Bilig WorkPaper, and Zod: + + +```bash npm +npm install langchain @langchain/core @bilig/workpaper zod +``` +```bash yarn +yarn add langchain @langchain/core @bilig/workpaper zod +``` +```bash pnpm +pnpm add langchain @langchain/core @bilig/workpaper zod +``` + + +## Create a WorkPaper tool + +Create a workbook with input cells and a formula output, then expose a tool that writes one input cell and returns recalculation and restore proof. + +```typescript +import { tool } from "@langchain/core/tools"; +import { + WorkPaper, + createWorkPaperFromDocument, + exportWorkPaperDocument, + parseWorkPaperDocument, + serializeWorkPaperDocument, +} from "@bilig/workpaper"; +import { z } from "zod"; + +const workbook = WorkPaper.buildFromSheets({ + Inputs: [ + ["Metric", "Value"], + ["Units", 40], + ["Price", 1200], + ], + Summary: [ + ["Metric", "Value"], + ["Revenue", "=Inputs!B2*Inputs!B3"], + ], +}); + +const cellValue = (address: string) => { + const parsed = workbook.simpleCellAddressFromString(address); + if (parsed === undefined) { + throw new Error(`Invalid cell address: ${address}`); + } + + const value = workbook.getCellValue(parsed); + return typeof value === "object" && value !== null && "value" in value + ? value.value + : value; +}; + +const setWorkPaperInputCell = tool( + async ({ target, value }) => { + const parsedTarget = workbook.simpleCellAddressFromString(target); + if (parsedTarget === undefined) { + throw new Error(`Invalid input cell: ${target}`); + } + + const editedCell = workbook.simpleCellAddressToString(parsedTarget, { + includeSheetName: true, + }); + if (!editedCell.startsWith("Inputs!")) { + throw new Error("Only Inputs sheet cells are writable"); + } + + const beforeRevenue = cellValue("Summary!B2"); + workbook.setCellContents(parsedTarget, value); + const afterRevenue = cellValue("Summary!B2"); + + const serialized = serializeWorkPaperDocument( + exportWorkPaperDocument(workbook), + ); + const restored = createWorkPaperFromDocument( + parseWorkPaperDocument(serialized), + ); + + try { + const restoredRevenueCell = restored.simpleCellAddressFromString("Summary!B2"); + if (restoredRevenueCell === undefined) { + throw new Error("Invalid restored revenue cell"); + } + + const restoredRevenueValue = restored.getCellValue(restoredRevenueCell); + const restoredRevenue = + typeof restoredRevenueValue === "object" && + restoredRevenueValue !== null && + "value" in restoredRevenueValue + ? restoredRevenueValue.value + : restoredRevenueValue; + + return JSON.stringify({ + editedCell, + beforeRevenue, + afterRevenue, + checks: { + computedOutputChanged: beforeRevenue !== afterRevenue, + restoredMatchesAfter: restoredRevenue === afterRevenue, + }, + }); + } finally { + restored.dispose(); + } + }, + { + name: "set_workpaper_input_cell", + description: + "Set one allowed WorkPaper input cell and return recalculated readback proof.", + schema: z.object({ + target: z + .string() + .describe("Sheet-qualified input cell, for example Inputs!B2"), + value: z.number().describe("Numeric input value to write"), + }), + }, +); + +const proof = await setWorkPaperInputCell.invoke({ + target: "Inputs!B2", + value: 48, +}); + +console.log(proof); +workbook.dispose(); +``` + +The output includes the edited cell, the formula result before and after the input change, and checks that the output changed and survived JSON export/restore. + +```json +{ + "editedCell": "Inputs!B2", + "beforeRevenue": 48000, + "afterRevenue": 57600, + "checks": { + "computedOutputChanged": true, + "restoredMatchesAfter": true + } +} +``` + +## Use with an agent + +Pass `setWorkPaperInputCell` with your other tools when you create an agent: + +```typescript +import { createAgent } from "langchain"; + +const agent = createAgent({ + llm, + tools: [setWorkPaperInputCell], +}); +``` + +Use a WorkPaper tool when workbook shape matters: cell addresses, stored formulas, recalculation, JSON persistence, and readback proof. For a single scalar formula that does not need workbook state, a small function tool is usually simpler. + +## Related + +- [Tool conceptual guide](/oss/langchain/tools) +- [Bilig WorkPaper documentation](https://proompteng.github.io/bilig/) +- [Bilig WorkPaper source](https://github.com/proompteng/bilig) diff --git a/src/oss/javascript/integrations/tools/index.mdx b/src/oss/javascript/integrations/tools/index.mdx index 93ac4945a1..761f1dda5a 100644 --- a/src/oss/javascript/integrations/tools/index.mdx +++ b/src/oss/javascript/integrations/tools/index.mdx @@ -12,9 +12,9 @@ A [toolkit](/oss/langchain/tools#prebuilt-tools) is a collection of tools meant The following platforms provide access to multiple tools and services through a unified interface: -| Tool/Toolkit | Number of Integrations | Pricing | Key Features | -|-------------|----------------------|---------|--------------| -| [`Composio`](/oss/integrations/tools/composio) | 500+ | Free tier available | OAuth handling, event-driven workflows, multi-user support | +| Tool/Toolkit | Number of Integrations | Pricing | Key Features | +| ------------------------------------------------- | ---------------------- | ------------------- | -------------------------------------------------------------- | +| [`Composio`](/oss/integrations/tools/composio) | 500+ | Free tier available | OAuth handling, event-driven workflows, multi-user support | ## All tools and toolkits @@ -26,6 +26,13 @@ The following platforms provide access to multiple tools and services through a arrow="true" cta="View guide" /> +