From a711691aca66794093746b9dc017f863c6bd3eba Mon Sep 17 00:00:00 2001 From: greenflux Date: Thu, 26 Mar 2026 16:49:15 -0400 Subject: [PATCH 1/3] Add AI integration docs and reorganize sidebar - Add landing pages for HyperFormula AI SDK, LangChain/LangGraph integration, and MCP Server under Framework integration - Rename sidebar "Overview" section to "About" and move above Miscellaneous - Promote "Getting started" to second position in sidebar Co-Authored-By: Claude Opus 4.6 --- docs/.vuepress/config.js | 25 +++++---- docs/guide/ai-sdk.md | 69 ++++++++++++++++++++++++ docs/guide/integration-with-langchain.md | 44 +++++++++++++++ docs/guide/mcp-server.md | 44 +++++++++++++++ 4 files changed, 171 insertions(+), 11 deletions(-) create mode 100644 docs/guide/ai-sdk.md create mode 100644 docs/guide/integration-with-langchain.md create mode 100644 docs/guide/mcp-server.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 46e040b9a..1ddf22c62 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -175,17 +175,6 @@ module.exports = { ['/guide/demo', 'Demo'], ] }, - { - title: 'Overview', - collapsable: false, - children: [ - ['/guide/quality', 'Quality'], - ['/guide/supported-browsers', 'Supported browsers'], - ['/guide/dependencies', 'Dependencies'], - ['/guide/licensing', 'Licensing'], - ['/guide/support', 'Support'], - ] - }, { title: 'Getting started', collapsable: false, @@ -206,6 +195,9 @@ module.exports = { ['/guide/integration-with-vue', 'Integration with Vue'], ['/guide/integration-with-angular', 'Integration with Angular'], ['/guide/integration-with-svelte', 'Integration with Svelte'], + ['/guide/ai-sdk', 'HyperFormula AI SDK'], + ['/guide/integration-with-langchain', 'Integration with LangChain'], + ['/guide/mcp-server', 'HyperFormula MCP Server'], ] }, { @@ -276,6 +268,17 @@ module.exports = { ['/guide/migration-from-2.x-to-3.0', 'Migrating from 2.x to 3.0'], ] }, + { + title: 'About', + collapsable: false, + children: [ + ['/guide/quality', 'Quality'], + ['/guide/supported-browsers', 'Supported browsers'], + ['/guide/dependencies', 'Dependencies'], + ['/guide/licensing', 'Licensing'], + ['/guide/support', 'Support'], + ] + }, { title: 'Miscellaneous', collapsable: false, diff --git a/docs/guide/ai-sdk.md b/docs/guide/ai-sdk.md new file mode 100644 index 000000000..1d5f0dc19 --- /dev/null +++ b/docs/guide/ai-sdk.md @@ -0,0 +1,69 @@ +# HyperFormula AI SDK + +Let LLMs safely read/write spreadsheets and compute formulas via a deterministic engine. + +## What it does + +- **Evaluate formulas on the fly** —call `calculateFormula()` to evaluate any Excel-compatible formula without placing it in a cell. +- **Read and write cells and ranges** —get or set individual cells and multi-cell ranges so an LLM can inspect, populate, or modify sheet data programmatically. +- **Trace dependencies** —call `getCellDependents()` and `getCellPrecedents()` to understand which cells feed into a formula and what downstream values would change. + +## Quickstart + +```js +import HyperFormula from 'hyperformula'; + +// 1. Create a HyperFormula instance with initial data +const hf = HyperFormula.buildFromArray([ + ['Revenue', 100], + ['Cost', 60], + ['Profit', '=B1-B2'], +]); + +// 2. Define tools your LLM agent can call +const hfTools = { + evaluate({ formula }) { + return hf.calculateFormula(formula, 0); + }, + getCellValue({ sheet, col, row }) { + return hf.getCellValue({ sheet, col, row }); + }, + setCellContents({ sheet, col, row, value }) { + return hf.setCellContents({ sheet, col, row }, value); + }, + getDependents({ sheet, col, row }) { + return hf.getCellDependents({ sheet, col, row }); + }, + getRange({ sheet, startCol, startRow, endCol, endRow }) { + return hf.getRangeValues({ + start: { sheet, col: startCol, row: startRow }, + end: { sheet, col: endCol, row: endRow }, + }); + }, +}; + +// 3. Agent interaction examples +hfTools.evaluate({ formula: '=IRR({-1000,300,400,500,200})' }); +// → 0.1189 — deterministic, no LLM math + +hfTools.setCellContents({ sheet: 0, col: 1, row: 0, value: 200 }); +hfTools.getRange({ sheet: 0, startCol: 0, startRow: 0, endCol: 1, endRow: 2 }); +// → [['Revenue', 200], ['Cost', 60], ['Profit', 140]] + +// Agent: "What drives the profit number?" +hfTools.getDependents({ sheet: 0, col: 1, row: 0 }); +// → [{ sheet: 0, col: 1, row: 2 }] — Revenue flows into Profit +``` + +## Use cases + +- **Explain a sheet** —ask an agent to summarize what a spreadsheet does, which cells are inputs, and how outputs are derived. +- **Generate a what-if scenario** —let the model tweak assumptions (price, volume, rate) and observe how results change in real time. +- **Validate and clean data** —have the agent scan ranges for errors, missing values, or inconsistencies and fix them with formulas or direct edits. +- **Create formulas from natural language** —describe a calculation in plain English and let the model write and verify the correct Excel formula. + +## Beta access + +::: tip +Email [hello.hyperformula@handsontable.com](mailto:hello.hyperformula@handsontable.com) to sign up for beta access. +::: diff --git a/docs/guide/integration-with-langchain.md b/docs/guide/integration-with-langchain.md new file mode 100644 index 000000000..25061db20 --- /dev/null +++ b/docs/guide/integration-with-langchain.md @@ -0,0 +1,44 @@ +# Integration with LangChain/LangGraph + +A LangChain/LangGraph tool that gives AI agents deterministic, Excel-compatible formula evaluation instead of relying on LLM-generated math. + +## What it does + +**Without HyperFormula:** + +```python +result = llm.invoke( + "Calculate the IRR for these cash flows: [-1000, 300, 400, 500, 200]" +) +# "The IRR is approximately 12.4%" ← non-deterministic, unverifiable +``` + +**With HyperFormula tool:** + +```python +tools = [HyperFormulaTool()] +agent = create_react_agent(llm, tools) + +# Agent calls: hf.evaluate("=IRR(A1:A5)") +# → 0.1189 ← deterministic, auditable +``` + +## How it works + +1. **Agent populates a HyperFormula sheet** —writes data and formulas (`=SUM`, `=IF`, `=VLOOKUP`, etc.) into cells. +2. **HyperFormula evaluates deterministically** —resolves the full dependency graph using 400+ built-in functions. No LLM in the loop for math. +3. **Agent continues with verified data** —computed values flow back into the chain for reasoning, reporting, or downstream actions. + +## Use cases + +- Financial modeling (NPV, IRR, amortization) +- Data transformation and aggregation (SUMIF, VLOOKUP) +- Dynamic pricing with formula-defined logic +- What-if scenarios and forecasting +- Report generation with verified KPIs + +## Beta access + +::: tip +Email [hello.hyperformula@handsontable.com](mailto:hello.hyperformula@handsontable.com) to sign up for beta access. +::: diff --git a/docs/guide/mcp-server.md b/docs/guide/mcp-server.md new file mode 100644 index 000000000..990ad2983 --- /dev/null +++ b/docs/guide/mcp-server.md @@ -0,0 +1,44 @@ +# HyperFormula MCP Server + +An MCP (Model Context Protocol) server that exposes HyperFormula as a tool for any MCP-compatible AI client, giving LLMs deterministic spreadsheet computation. + +## What it does + +- **Evaluate formulas** —any MCP client can call HyperFormula to evaluate Excel-compatible formulas and get exact results. +- **Read and write cells** —get or set individual cell values and ranges through standard MCP tool calls. +- **Inspect dependencies** —trace which cells a formula depends on and understand the calculation graph. + +**Without HyperFormula:** + +``` +User: What's the NPV at 8% for these cash flows? +Agent: "Approximately $142.50" ← non-deterministic, unverifiable +``` + +**With HyperFormula MCP server:** + +``` +User: What's the NPV at 8% for these cash flows? +Agent → tool call: evaluate("=NPV(0.08, B1:B5)") +Agent: "$138.43" ← deterministic, auditable +``` + +## How it works + +1. **Start the MCP server** —runs HyperFormula as a local MCP server that any compatible client (Claude Desktop, Cursor, VS Code, etc.) can connect to. +2. **Client sends tool calls** —the AI client calls tools like `evaluate`, `getCellValue`, and `setCellContents` via the MCP protocol. +3. **HyperFormula evaluates deterministically** —resolves formulas using 400+ built-in functions with full dependency tracking. No LLM in the loop for math. +4. **Results flow back to the client** —computed values return through MCP, grounding the AI's response in verified numbers. + +## Use cases + +- Spreadsheet Q&A in Claude Desktop or other MCP clients +- Formula evaluation in IDE-based AI assistants +- Financial calculations in chat-based agent workflows +- Data validation and transformation via natural language + +## Beta access + +::: tip +Email [hello.hyperformula@handsontable.com](mailto:hello.hyperformula@handsontable.com) to sign up for beta access. +::: From 787b8bcb7db281e3b8f5a12de47f96accb6febac Mon Sep 17 00:00:00 2001 From: Kuba Sekowski Date: Mon, 30 Mar 2026 16:29:11 +0200 Subject: [PATCH 2/3] Update docs/.vuepress/config.js --- docs/.vuepress/config.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 1ddf22c62..70456f0da 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -188,7 +188,7 @@ module.exports = { ] }, { - title: 'Framework integration', + title: 'Integrations', collapsable: false, children: [ ['/guide/integration-with-react', 'Integration with React'], From c628756428c08e68407eba96daf900c7c68bf788 Mon Sep 17 00:00:00 2001 From: greenflux Date: Thu, 9 Apr 2026 07:11:40 -0400 Subject: [PATCH 3/3] Refine AI integration pages per review feedback - Add `hyperformula/ai` import to AI SDK quickstart example - Use idiomatic LangChain @tool decorator pattern - Replace email CTA with HubSpot form link on all three pages --- docs/guide/ai-sdk.md | 34 ++++++------------------ docs/guide/integration-with-langchain.md | 17 +++++++++--- docs/guide/mcp-server.md | 2 +- 3 files changed, 22 insertions(+), 31 deletions(-) diff --git a/docs/guide/ai-sdk.md b/docs/guide/ai-sdk.md index 1d5f0dc19..aeb93e6ca 100644 --- a/docs/guide/ai-sdk.md +++ b/docs/guide/ai-sdk.md @@ -12,6 +12,7 @@ Let LLMs safely read/write spreadsheets and compute formulas via a deterministic ```js import HyperFormula from 'hyperformula'; +import { createSpreadsheetTools } from 'hyperformula/ai'; // 1. Create a HyperFormula instance with initial data const hf = HyperFormula.buildFromArray([ @@ -20,38 +21,19 @@ const hf = HyperFormula.buildFromArray([ ['Profit', '=B1-B2'], ]); -// 2. Define tools your LLM agent can call -const hfTools = { - evaluate({ formula }) { - return hf.calculateFormula(formula, 0); - }, - getCellValue({ sheet, col, row }) { - return hf.getCellValue({ sheet, col, row }); - }, - setCellContents({ sheet, col, row, value }) { - return hf.setCellContents({ sheet, col, row }, value); - }, - getDependents({ sheet, col, row }) { - return hf.getCellDependents({ sheet, col, row }); - }, - getRange({ sheet, startCol, startRow, endCol, endRow }) { - return hf.getRangeValues({ - start: { sheet, col: startCol, row: startRow }, - end: { sheet, col: endCol, row: endRow }, - }); - }, -}; +// 2. Create tools your LLM agent can call +const tools = createSpreadsheetTools(hf); // 3. Agent interaction examples -hfTools.evaluate({ formula: '=IRR({-1000,300,400,500,200})' }); +tools.evaluate({ formula: '=IRR({-1000,300,400,500,200})' }); // → 0.1189 — deterministic, no LLM math -hfTools.setCellContents({ sheet: 0, col: 1, row: 0, value: 200 }); -hfTools.getRange({ sheet: 0, startCol: 0, startRow: 0, endCol: 1, endRow: 2 }); +tools.setCellContents({ sheet: 0, col: 1, row: 0, value: 200 }); +tools.getRange({ sheet: 0, startCol: 0, startRow: 0, endCol: 1, endRow: 2 }); // → [['Revenue', 200], ['Cost', 60], ['Profit', 140]] // Agent: "What drives the profit number?" -hfTools.getDependents({ sheet: 0, col: 1, row: 0 }); +tools.getDependents({ sheet: 0, col: 1, row: 0 }); // → [{ sheet: 0, col: 1, row: 2 }] — Revenue flows into Profit ``` @@ -65,5 +47,5 @@ hfTools.getDependents({ sheet: 0, col: 1, row: 0 }); ## Beta access ::: tip -Email [hello.hyperformula@handsontable.com](mailto:hello.hyperformula@handsontable.com) to sign up for beta access. +[Sign up for beta access](https://2fmjvg.share-eu1.hsforms.com/2e6drCkuLTn-1RuiYB91eJA) ::: diff --git a/docs/guide/integration-with-langchain.md b/docs/guide/integration-with-langchain.md index 25061db20..cbb695dcd 100644 --- a/docs/guide/integration-with-langchain.md +++ b/docs/guide/integration-with-langchain.md @@ -16,10 +16,19 @@ result = llm.invoke( **With HyperFormula tool:** ```python -tools = [HyperFormulaTool()] -agent = create_react_agent(llm, tools) +from langchain_core.tools import tool +from hyperformula import HyperFormula -# Agent calls: hf.evaluate("=IRR(A1:A5)") +hf = HyperFormula.build_from_array([[-1000, 300, 400, 500, 200]]) + +@tool +def evaluate_formula(formula: str) -> str: + """Evaluate an Excel-compatible formula using HyperFormula.""" + return hf.calculate_formula(formula, sheet_id=0) + +agent = create_react_agent(llm, [evaluate_formula]) + +# Agent calls: evaluate_formula("=IRR(A1:E1)") # → 0.1189 ← deterministic, auditable ``` @@ -40,5 +49,5 @@ agent = create_react_agent(llm, tools) ## Beta access ::: tip -Email [hello.hyperformula@handsontable.com](mailto:hello.hyperformula@handsontable.com) to sign up for beta access. +[Sign up for beta access](https://2fmjvg.share-eu1.hsforms.com/2e6drCkuLTn-1RuiYB91eJA) ::: diff --git a/docs/guide/mcp-server.md b/docs/guide/mcp-server.md index 990ad2983..618323f22 100644 --- a/docs/guide/mcp-server.md +++ b/docs/guide/mcp-server.md @@ -40,5 +40,5 @@ Agent: "$138.43" ← deterministic, auditable ## Beta access ::: tip -Email [hello.hyperformula@handsontable.com](mailto:hello.hyperformula@handsontable.com) to sign up for beta access. +[Sign up for beta access](https://2fmjvg.share-eu1.hsforms.com/2e6drCkuLTn-1RuiYB91eJA) :::