Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 15 additions & 12 deletions docs/.vuepress/config.js
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -199,13 +188,16 @@ module.exports = {
]
},
{
title: 'Framework integration',
title: 'Integrations',
collapsable: false,
children: [
['/guide/integration-with-react', 'Integration with React'],
['/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'],
]
},
{
Expand Down Expand Up @@ -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,
Expand Down
51 changes: 51 additions & 0 deletions docs/guide/ai-sdk.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# 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';
import { createSpreadsheetTools } from 'hyperformula/ai';

// 1. Create a HyperFormula instance with initial data
const hf = HyperFormula.buildFromArray([
['Revenue', 100],
['Cost', 60],
['Profit', '=B1-B2'],
]);

// 2. Create tools your LLM agent can call
const tools = createSpreadsheetTools(hf);

// 3. Agent interaction examples
tools.evaluate({ formula: '=IRR({-1000,300,400,500,200})' });
// → 0.1189 — deterministic, no LLM math

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?"
tools.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
[Sign up for beta access](https://2fmjvg.share-eu1.hsforms.com/2e6drCkuLTn-1RuiYB91eJA)
:::
7 changes: 7 additions & 0 deletions docs/guide/built-in-functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,13 @@ It makes the page wider to accommodate large tables
.page:has(.widePage) .page-nav /* footer links to the next and prev page */ {
max-width: 1200px !important; /* override default max-width of 740px for this page */
}

/* Make wide tables horizontally scrollable on narrow screens */
.page:has(.widePage) .theme-default-content:not(.custom) table {
display: block;
overflow-x: auto;
-webkit-overflow-scrolling: touch;
}
</style>

## Overview
Expand Down
10 changes: 2 additions & 8 deletions docs/guide/custom-functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -358,18 +358,12 @@ it('returns a VALUE error if the range argument contains a string', () => {

## Working demo

Explore the full working example on [Stackblitz](https://stackblitz.com/github/handsontable/hyperformula-demos/tree/3.2.x/custom-functions?v=${$page.buildDateURIEncoded}).

This demo contains the implementation of both the
[`GREET`](#add-a-simple-custom-function) and
[`DOUBLE_RANGE`](#advanced-custom-function-example) custom functions.

<iframe
:src="`https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/3.2.x/custom-functions?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview&v=${$page.buildDateURIEncoded}`"
style="width:100%; height:1070px; border:0; border-radius: 4px; overflow:hidden;"
title="handsontable/hyperformula-demos: react-demo"
allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts">
</iframe>

## Function options

You can set the following options for your function:
Expand Down
2 changes: 1 addition & 1 deletion docs/guide/i18n-features.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Configure HyperFormula to match the languages and regions of your users.

## Function names and errors

Each of HyperFormula's [built-in functions](built-in-functions.md) and [errors](types-of-errors.md) is available in [17 languages](localizing-functions.md#list-of-supported-languages).
Each of HyperFormula's [built-in functions](built-in-functions.md) and [errors](types-of-errors.md) is available in [18 languages](localizing-functions.md#list-of-supported-languages).

You can easily [switch between languages](localizing-functions.md) ([`language`](../api/interfaces/configparams.md#language)).

Expand Down
8 changes: 1 addition & 7 deletions docs/guide/integration-with-angular.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,4 @@ For more details, see the [client-side installation](client-side-installation.md

## Demo

<iframe
:src="`https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/3.2.x/angular-demo?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview&v=${$page.buildDateURIEncoded}`"
style="width:100%; height:1070px; border:0; border-radius: 4px; overflow:hidden;"
title="handsontable/hyperformula-demos: react-demo"
allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts">
</iframe>
Explore the full working example on [Stackblitz](https://stackblitz.com/github/handsontable/hyperformula-demos/tree/3.2.x/angular-demo?v=${$page.buildDateURIEncoded}).
53 changes: 53 additions & 0 deletions docs/guide/integration-with-langchain.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# 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
from langchain_core.tools import tool
from hyperformula import HyperFormula

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
```

## 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
[Sign up for beta access](https://2fmjvg.share-eu1.hsforms.com/2e6drCkuLTn-1RuiYB91eJA)
:::
8 changes: 1 addition & 7 deletions docs/guide/integration-with-react.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,4 @@ For more details, see the [client-side installation](client-side-installation.md

## Demo

<iframe
:src="`https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/3.2.x/react-demo?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview&v=${$page.buildDateURIEncoded}`"
style="width:100%; height:1070px; border:0; border-radius: 4px; overflow:hidden;"
title="handsontable/hyperformula-demos: react-demo"
allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts">
</iframe>
Explore the full working example on [Stackblitz](https://stackblitz.com/github/handsontable/hyperformula-demos/tree/3.2.x/react-demo?v=${$page.buildDateURIEncoded}).
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stackblitz links won't interpolate page variable in URL

Medium Severity

The markdown links use JavaScript template literal syntax ${$page.buildDateURIEncoded} inside a plain markdown URL. VuePress compiles markdown into Vue templates, where only {{ }} works for text interpolation and :attr for dynamic attribute binding. The old iframes correctly used :src with backtick template literals. The new plain [text](url) markdown renders a static href, so ${...} appears literally in the URL instead of the actual build date value. This affects all five pages with Stackblitz links.

Additional Locations (2)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 90ffb71. Configure here.

8 changes: 1 addition & 7 deletions docs/guide/integration-with-svelte.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,4 @@ For more details, see the [client-side installation](client-side-installation.md

## Demo

<iframe
:src="`https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/3.2.x/svelte-demo?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview&v=${$page.buildDateURIEncoded}`"
style="width:100%; height:1070px; border:0; border-radius: 4px; overflow:hidden;"
title="handsontable/hyperformula-demos: react-demo"
allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts">
</iframe>
Explore the full working example on [Stackblitz](https://stackblitz.com/github/handsontable/hyperformula-demos/tree/3.2.x/svelte-demo?v=${$page.buildDateURIEncoded}).
10 changes: 2 additions & 8 deletions docs/guide/integration-with-vue.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,14 +31,8 @@ This function prevents Vue from converting the HyperFormula instance into a reac

## Demo

Explore the full working example on [Stackblitz](https://stackblitz.com/github/handsontable/hyperformula-demos/tree/3.2.x/vue-3-demo?v=${$page.buildDateURIEncoded}).

::: tip
This demo uses the [Vue 3](https://v3.vuejs.org/) framework. If you are looking for an example using Vue 2, check out the [code on GitHub](https://github.com/handsontable/hyperformula-demos/tree/2.5.x/vue-demo).
:::

<iframe
:src="`https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/3.2.x/vue-3-demo?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview&v=${$page.buildDateURIEncoded}`"
style="width:100%; height:1070px; border:0; border-radius: 4px; overflow:hidden;"
title="handsontable/hyperformula-demos: react-demo"
allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts">
</iframe>
7 changes: 7 additions & 0 deletions docs/guide/list-of-differences.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,13 @@ It makes the page wider to accommodate large tables
.page:has(.widePage) .page-nav /* footer links to the next and prev page */ {
max-width: 1200px !important; /* override default max-width of 740px for this page */
}

/* Make wide tables horizontally scrollable on narrow screens */
.page:has(.widePage) .theme-default-content:not(.custom) table {
display: block;
overflow-x: auto;
-webkit-overflow-scrolling: touch;
}
</style>

See a full list of differences between HyperFormula, Microsoft Excel, and Google Sheets.
Expand Down
3 changes: 2 additions & 1 deletion docs/guide/localizing-functions.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Localizing functions

You can localize a function's ID and error
messages. Currently, HyperFormula supports 17 languages, with British English
messages. Currently, HyperFormula supports 18 languages, with British English
as the default.

To change the language all you need to do is import and
Expand Down Expand Up @@ -128,6 +128,7 @@ You can localize your custom functions as well. For details, see the [Custom fun
| Spanish | esES |
| Swedish | svSE |
| Turkish | trTR |
| Indonesian | idID |

## Demo

Expand Down
44 changes: 44 additions & 0 deletions docs/guide/mcp-server.md
Original file line number Diff line number Diff line change
@@ -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
[Sign up for beta access](https://2fmjvg.share-eu1.hsforms.com/2e6drCkuLTn-1RuiYB91eJA)
:::
Loading