From a759bb4be8f879443f9781e0a9d5bb28d04182c8 Mon Sep 17 00:00:00 2001 From: Kuba Sekowski Date: Mon, 11 May 2026 14:56:13 +0200 Subject: [PATCH] Refine the AI toolkits landing pages --- docs/guide/ai-sdk.md | 35 ++++----- docs/guide/integration-with-langchain.md | 96 ++++++++++++++---------- docs/guide/mcp-server.md | 73 +++++++++++------- docs/guide/types-of-values.md | 2 +- 4 files changed, 119 insertions(+), 87 deletions(-) diff --git a/docs/guide/ai-sdk.md b/docs/guide/ai-sdk.md index d46a798776..c4c627fc4a 100644 --- a/docs/guide/ai-sdk.md +++ b/docs/guide/ai-sdk.md @@ -2,15 +2,18 @@ A [Vercel AI SDK](https://sdk.vercel.ai/docs) tool that gives your agents deterministic spreadsheet and formula computation — backed by HyperFormula's Excel-compatible engine. -::: warning Prototype — not yet released -We have a working prototype. We'll make it available as soon as we open the beta. The API below is a preview and is likely to change before the first release. +::: warning Not available yet — coming soon +This integration is on our roadmap and **cannot be installed or used today**. The API shown below is a preview and may still change before the first release. + +If you'd like to try it, [join the early access list](https://2fmjvg.share-eu1.hsforms.com/2e6drCkuLTn-1RuiYB91eJA) — we'll ping you the moment the first beta is ready, and your sign-up directly tells us how strongly to prioritize this integration. ::: ## What it does -- **Evaluate formulas on the fly** — your agent runs any Excel-compatible formula without placing it in a cell, so the model never has to do math itself. +- **Evaluate formulas deterministically** — your agent runs any Excel-compatible formula through HyperFormula instead of asking the LLM to do math. Results are exact, reproducible, and auditable. - **Read and write cells and ranges** — the agent inspects, populates, or modifies sheet data through typed tool calls. -- **Trace dependencies** — precedents and dependents are surfaced so the agent can explain how a value is derived. +- **Trace dependencies** — precedents and dependents are surfaced so the agent can explain how every value was derived. +- **400+ built-in functions out of the box** — the agent has access to the full Excel-compatible function set (`SUM`, `VLOOKUP`, `IRR`, `INDEX/MATCH`, and the rest), no implementation work required. ## Example @@ -41,26 +44,18 @@ A single import, one extra line in `tools`, and the model can evaluate formulas, ## Use cases -- **Explain a sheet** — an agent summarizes what a spreadsheet does, which cells are inputs, and how outputs are derived. -- **Generate a what-if scenario** — the model tweaks assumptions and reports how downstream results change. +- **Spreadsheet Q&A** — ask the agent what a workbook does, which cells are inputs, and how each output is derived; get answers grounded in real formula evaluation. +- **What-if scenarios and forecasting** — the agent tweaks assumptions and reports how downstream results change, deterministically. - **Validate and clean data** — the agent scans ranges for errors, missing values, or inconsistencies and fixes them in place. -- **Create formulas from natural language** — the model translates a plain-English calculation into a verified Excel formula. - -## Safety and guardrails - -HyperFormula runs locally in your Node.js or browser process — there's no remote service and no network or filesystem access through the tools. The agent's blast radius is limited to the in-memory workbook you hand it. - -Planned for the beta: +- **Generate formulas from natural language** — the agent translates a plain-English calculation into a verified, working Excel formula. +- **Financial modeling and reporting** — NPV, IRR, amortization, KPI rollups, and other quantitative workflows where the answer must be exact and auditable. -- **Permissions per tool** — opt in to read-only, write, or formula-evaluation tools individually. -- **Range scoping** — restrict an agent to a named range, sheet, or address pattern. -- **Operation limits** — cap the number of cell writes or formula evaluations per turn. -- **Audit log** — every tool call returns a structured record of what changed. +## Get early access -## Join the waitlist +::: tip Be the first to try it +We're actively building this integration. Drop your email and we'll notify you the moment the first beta lands — so you can try it before the public release. -::: tip -**When we're ready to launch the beta, you'll be the first to know.** [Drop your email in the waitlist →](https://2fmjvg.share-eu1.hsforms.com/2e6drCkuLTn-1RuiYB91eJA) +[Join the early access list →](https://2fmjvg.share-eu1.hsforms.com/2e6drCkuLTn-1RuiYB91eJA) ::: ## Links diff --git a/docs/guide/integration-with-langchain.md b/docs/guide/integration-with-langchain.md index cbb695dcd2..fad45db79d 100644 --- a/docs/guide/integration-with-langchain.md +++ b/docs/guide/integration-with-langchain.md @@ -1,53 +1,71 @@ # Integration with LangChain/LangGraph -A LangChain/LangGraph tool that gives AI agents deterministic, Excel-compatible formula evaluation instead of relying on LLM-generated math. +A [LangChain.js](https://js.langchain.com/) / [LangGraph](https://langchain-ai.github.io/langgraphjs/) tool that gives your agents deterministic spreadsheet and formula computation — backed by HyperFormula's Excel-compatible engine. -## 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 -from langchain_core.tools import tool -from hyperformula import HyperFormula - -hf = HyperFormula.build_from_array([[-1000, 300, 400, 500, 200]]) +::: warning Not available yet — coming soon +This integration is on our roadmap and **cannot be installed or used today**. The API shown below is a preview and may still change before the first release. -@tool -def evaluate_formula(formula: str) -> str: - """Evaluate an Excel-compatible formula using HyperFormula.""" - return hf.calculate_formula(formula, sheet_id=0) +If you'd like to try it, [join the early access list](https://2fmjvg.share-eu1.hsforms.com/2e6drCkuLTn-1RuiYB91eJA) — we'll ping you the moment the first beta is ready, and your sign-up directly tells us how strongly to prioritize this integration. +::: -agent = create_react_agent(llm, [evaluate_formula]) +## What it does -# Agent calls: evaluate_formula("=IRR(A1:E1)") -# → 0.1189 ← deterministic, auditable +- **Evaluate formulas deterministically** — your agent runs any Excel-compatible formula through HyperFormula instead of asking the LLM to do math. Results are exact, reproducible, and auditable. +- **Read and write cells and ranges** — the agent inspects, populates, or modifies sheet data through typed tool calls. +- **Trace dependencies** — precedents and dependents are surfaced so the agent can explain how every value was derived. +- **400+ built-in functions out of the box** — the agent has access to the full Excel-compatible function set (`SUM`, `VLOOKUP`, `IRR`, `INDEX/MATCH`, and the rest), no implementation work required. + +## Example + +Wiring HyperFormula into a LangGraph ReAct agent: + +```js +import { ChatOpenAI } from '@langchain/openai'; +import { createReactAgent } from '@langchain/langgraph/prebuilt'; +import HyperFormula from 'hyperformula'; +import { createSpreadsheetTools } from 'hyperformula/langchain'; + +const hf = HyperFormula.buildFromArray([ + ['Revenue', 100], + ['Cost', 60], + ['Profit', '=B1-B2'], +]); + +const agent = createReactAgent({ + llm: new ChatOpenAI({ model: 'gpt-4o' }), + tools: createSpreadsheetTools(hf), +}); + +await agent.invoke({ + messages: [ + { role: 'user', content: 'What drives the profit number, and what happens if revenue doubles?' }, + ], +}); ``` -## 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. +A single import, one entry in `tools`, and the agent can evaluate formulas, read ranges, and edit cells through LangChain — without inventing numbers. ## 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 +- **Spreadsheet Q&A** — ask the agent what a workbook does, which cells are inputs, and how each output is derived; get answers grounded in real formula evaluation. +- **What-if scenarios and forecasting** — the agent tweaks assumptions and reports how downstream results change, deterministically. +- **Validate and clean data** — the agent scans ranges for errors, missing values, or inconsistencies and fixes them in place. +- **Generate formulas from natural language** — the agent translates a plain-English calculation into a verified, working Excel formula. +- **Financial modeling and reporting** — NPV, IRR, amortization, KPI rollups, and other quantitative workflows where the answer must be exact and auditable. -## Beta access +## Get early access -::: tip -[Sign up for beta access](https://2fmjvg.share-eu1.hsforms.com/2e6drCkuLTn-1RuiYB91eJA) +::: tip Be the first to try it +We're actively building this integration. Drop your email and we'll notify you the moment the first beta lands — so you can try it before the public release. + +[Join the early access list →](https://2fmjvg.share-eu1.hsforms.com/2e6drCkuLTn-1RuiYB91eJA) ::: + +## Links + +- [LangChain.js documentation](https://js.langchain.com/) +- [LangGraph documentation](https://langchain-ai.github.io/langgraphjs/) +- [HyperFormula on GitHub](https://github.com/handsontable/hyperformula) +- [HyperFormula on npm](https://www.npmjs.com/package/hyperformula) +- [Built-in functions](built-in-functions.md) +- [Custom functions](custom-functions.md) diff --git a/docs/guide/mcp-server.md b/docs/guide/mcp-server.md index 618323f22b..7216032db6 100644 --- a/docs/guide/mcp-server.md +++ b/docs/guide/mcp-server.md @@ -1,44 +1,63 @@ # 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. +An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that exposes HyperFormula as a tool for any MCP-compatible AI client (Claude Desktop, Cursor, VS Code, and others) — giving LLMs deterministic spreadsheet and formula computation. -## What it does +::: warning Not available yet — coming soon +This integration is on our roadmap and **cannot be installed or used today**. The API shown below is a preview and may still change before the first release. -- **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. +If you'd like to try it, [join the early access list](https://2fmjvg.share-eu1.hsforms.com/2e6drCkuLTn-1RuiYB91eJA) — we'll ping you the moment the first beta is ready, and your sign-up directly tells us how strongly to prioritize this integration. +::: -**Without HyperFormula:** +## What it does -``` -User: What's the NPV at 8% for these cash flows? -Agent: "Approximately $142.50" ← non-deterministic, unverifiable -``` +- **Evaluate formulas deterministically** — your agent runs any Excel-compatible formula through HyperFormula instead of asking the LLM to do math. Results are exact, reproducible, and auditable. +- **Read and write cells and ranges** — the agent inspects, populates, or modifies sheet data through typed tool calls. +- **Trace dependencies** — precedents and dependents are surfaced so the agent can explain how every value was derived. +- **400+ built-in functions out of the box** — the agent has access to the full Excel-compatible function set (`SUM`, `VLOOKUP`, `IRR`, `INDEX/MATCH`, and the rest), no implementation work required. -**With HyperFormula MCP server:** +## Example -``` -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 +Run the server (no install needed once published): + +```bash +npx -y @hyperformula/mcp ``` -## How it works +Wire it into an MCP client by adding it to the client's config (for example, `claude_desktop_config.json` or `.cursor/mcp.json`): + +```json +{ + "mcpServers": { + "hyperformula": { + "command": "npx", + "args": ["-y", "@hyperformula/mcp"] + } + } +} +``` -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. +The client now sees tools like `evaluate`, `getCellValue`, and `setCellContents`, and the agent can call them as part of any conversation — without inventing 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 +- **Spreadsheet Q&A** — ask the agent what a workbook does, which cells are inputs, and how each output is derived; get answers grounded in real formula evaluation. +- **What-if scenarios and forecasting** — the agent tweaks assumptions and reports how downstream results change, deterministically. +- **Validate and clean data** — the agent scans ranges for errors, missing values, or inconsistencies and fixes them in place. +- **Generate formulas from natural language** — the agent translates a plain-English calculation into a verified, working Excel formula. +- **Financial modeling and reporting** — NPV, IRR, amortization, KPI rollups, and other quantitative workflows where the answer must be exact and auditable. + +## Get early access -## Beta access +::: tip Be the first to try it +We're actively building this integration. Drop your email and we'll notify you the moment the first beta lands — so you can try it before the public release. -::: tip -[Sign up for beta access](https://2fmjvg.share-eu1.hsforms.com/2e6drCkuLTn-1RuiYB91eJA) +[Join the early access list →](https://2fmjvg.share-eu1.hsforms.com/2e6drCkuLTn-1RuiYB91eJA) ::: + +## Links + +- [Model Context Protocol specification](https://modelcontextprotocol.io/) +- [HyperFormula on GitHub](https://github.com/handsontable/hyperformula) +- [HyperFormula on npm](https://www.npmjs.com/package/hyperformula) +- [Built-in functions](built-in-functions.md) +- [Custom functions](custom-functions.md) diff --git a/docs/guide/types-of-values.md b/docs/guide/types-of-values.md index b0312e88fd..67bca940fa 100644 --- a/docs/guide/types-of-values.md +++ b/docs/guide/types-of-values.md @@ -103,7 +103,7 @@ operations such as calculating the number of days between two dates. When working with text values directly inside formulas, you must enclose them in double quotes (`"`). This is different from entering text into cells, where quotes are not required. E.g.: -```excel +``` =IF(B1="Active", "Status OK", "Check Status") ```