@bilig/headless 0.11.29 → 0.11.31
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +48 -16
- package/package.json +12 -6
package/README.md
CHANGED
|
@@ -18,6 +18,21 @@ It is not Excel desktop automation and it is not a visual grid. XLSX import and
|
|
|
18
18
|
export live in the repository import/export packages; this package executes the
|
|
19
19
|
validated WorkPaper model once data is in workbook form.
|
|
20
20
|
|
|
21
|
+
## Current Public Proof
|
|
22
|
+
|
|
23
|
+
- Live growth snapshot:
|
|
24
|
+
<https://proompteng.github.io/bilig/community-growth-snapshot.html>
|
|
25
|
+
- Latest checked-in snapshot: `24` GitHub stars, `13,427` npm downloads in the
|
|
26
|
+
last week, `30` open `good first issue` tickets, `5` GitHub Discussions, and
|
|
27
|
+
`393` recent repository views.
|
|
28
|
+
- Benchmark evidence:
|
|
29
|
+
[`46/46` comparable WorkPaper mean wins](https://github.com/proompteng/bilig/blob/main/docs/what-workpaper-benchmark-proves.md),
|
|
30
|
+
with the p95 caveat documented instead of hidden.
|
|
31
|
+
|
|
32
|
+
If the sanity check below saves you a workbook-automation spike, star or
|
|
33
|
+
bookmark the repo after you see the verification output:
|
|
34
|
+
<https://github.com/proompteng/bilig/stargazers>.
|
|
35
|
+
|
|
21
36
|
## Install
|
|
22
37
|
|
|
23
38
|
Requires Node `24+` and ESM imports.
|
|
@@ -87,11 +102,16 @@ Pick the path that matches the job:
|
|
|
87
102
|
[`npm run json-records`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#json-records-input).
|
|
88
103
|
- Wrap workbook edits as agent tools:
|
|
89
104
|
[`npm run agent:tool-call`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#agent-tool-call-loop).
|
|
105
|
+
- Adapt the same WorkPaper tools to agent frameworks:
|
|
106
|
+
[`npm run agent:framework-adapters`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#agent-framework-adapters).
|
|
107
|
+
- Map WorkPaper tools to Vercel AI SDK and LangChain:
|
|
108
|
+
[framework adapter guide](https://proompteng.github.io/bilig/vercel-ai-sdk-langchain-spreadsheet-tool.html).
|
|
90
109
|
- Put WorkPaper behind HTTP:
|
|
91
110
|
[`examples/serverless-workpaper-api`](https://github.com/proompteng/bilig/tree/main/examples/serverless-workpaper-api).
|
|
92
111
|
- Compare engines before adopting:
|
|
93
112
|
[SheetJS and ExcelJS comparison](https://github.com/proompteng/bilig/blob/main/docs/sheetjs-exceljs-alternative-formula-workbook-api.md),
|
|
94
113
|
[HyperFormula comparison](https://github.com/proompteng/bilig/blob/main/docs/hyperformula-alternative-headless-workpaper.md),
|
|
114
|
+
[headless spreadsheet engine comparison](https://github.com/proompteng/bilig/blob/main/docs/headless-spreadsheet-engine-comparison.md),
|
|
95
115
|
and
|
|
96
116
|
[benchmark explainer](https://github.com/proompteng/bilig/blob/main/docs/what-workpaper-benchmark-proves.md).
|
|
97
117
|
|
|
@@ -109,21 +129,22 @@ Star or bookmark the project: <https://github.com/proompteng/bilig>.
|
|
|
109
129
|
The full example catalog lives in
|
|
110
130
|
[`examples/headless-workpaper/README.md`](https://github.com/proompteng/bilig/blob/main/examples/headless-workpaper/README.md).
|
|
111
131
|
|
|
112
|
-
| Need | Start with
|
|
113
|
-
| ------------------------------------ |
|
|
114
|
-
| Evaluate formulas from API records | `npm run json-records`
|
|
115
|
-
| Load records already saved on disk | `npm run json-file`
|
|
116
|
-
| Persist and restore a workbook | `npm run persistence`
|
|
117
|
-
| Verify an agent writeback | `npm run agent:verify`
|
|
118
|
-
| Wrap WorkPaper operations as tools | `npm run agent:tool-call`
|
|
119
|
-
|
|
|
120
|
-
|
|
|
121
|
-
| Check
|
|
122
|
-
|
|
|
123
|
-
|
|
|
124
|
-
|
|
|
125
|
-
|
|
|
126
|
-
|
|
|
132
|
+
| Need | Start with | Existing example |
|
|
133
|
+
| ------------------------------------ | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
134
|
+
| Evaluate formulas from API records | `npm run json-records` | [JSON records input](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#json-records-input) |
|
|
135
|
+
| Load records already saved on disk | `npm run json-file` | [JSON file input](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#json-file-input) |
|
|
136
|
+
| Persist and restore a workbook | `npm run persistence` | [Persistence round trip](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#persistence-round-trip) |
|
|
137
|
+
| Verify an agent writeback | `npm run agent:verify` | [Agent writeback verification](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#agent-writeback-verification) |
|
|
138
|
+
| Wrap WorkPaper operations as tools | `npm run agent:tool-call` | [Agent tool call loop](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#agent-tool-call-loop) |
|
|
139
|
+
| Adapt tools to agent frameworks | `npm run agent:framework-adapters` | [Agent framework adapters](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#agent-framework-adapters) |
|
|
140
|
+
| Flag budget variance rows | `npm run budget-variance` | [Budget variance alerts](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#budget-variance-alerts) |
|
|
141
|
+
| Check fulfillment capacity | `npm run fulfillment-capacity` | [Fulfillment capacity plan](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#fulfillment-capacity-plan) |
|
|
142
|
+
| Check quote approval threshold | `npm run quote-approval` | [Quote approval threshold](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#quote-approval-threshold) |
|
|
143
|
+
| Forecast subscription MRR | `npm run subscription-mrr` | [Subscription MRR forecast](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#subscription-mrr-forecast) |
|
|
144
|
+
| Return workbook results over HTTP | `npm run http-json-summary` | [HTTP JSON summary](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#http-json-summary) |
|
|
145
|
+
| Calculate invoice totals | `npm run invoice-totals` | [Invoice totals](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#invoice-totals) |
|
|
146
|
+
| Inspect restored workbook shape | `npm run sheet-inspection` | [Sheet inspection](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#sheet-inspection) |
|
|
147
|
+
| Compare computed values and formulas | `npm run range-readback` | [Range readback](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#range-readback) |
|
|
127
148
|
|
|
128
149
|
## Production Status
|
|
129
150
|
|
|
@@ -137,9 +158,11 @@ Current release posture:
|
|
|
137
158
|
- Full local CI passed after the latest headless hardening work, including unit,
|
|
138
159
|
contract, fuzz, browser, clean-diff, release-budget, runtime-publish, and
|
|
139
160
|
WorkPaper competitive benchmark gates.
|
|
140
|
-
- The checked-in competitive artifact generated on `2026-05-
|
|
161
|
+
- The checked-in competitive artifact generated on `2026-05-08T15:00:27.603Z`
|
|
141
162
|
shows `46/46` comparable WorkPaper mean wins against HyperFormula-style
|
|
142
163
|
workloads: `38/38` public and `8/8` holdout.
|
|
164
|
+
- The shareable benchmark card is generated from that artifact:
|
|
165
|
+
[`docs/assets/workpaper-benchmark-card.png`](https://github.com/proompteng/bilig/blob/main/docs/assets/workpaper-benchmark-card.png).
|
|
143
166
|
- The public benchmark evidence note explains the measured workload families,
|
|
144
167
|
engine metadata, exclusions, and the current p95 nuance:
|
|
145
168
|
[`docs/headless-workpaper-benchmark-evidence.md`](https://github.com/proompteng/bilig/blob/main/docs/headless-workpaper-benchmark-evidence.md).
|
|
@@ -205,6 +228,8 @@ Repository links:
|
|
|
205
228
|
- npm: <https://www.npmjs.com/package/@bilig/headless>
|
|
206
229
|
- runnable example:
|
|
207
230
|
[`examples/headless-workpaper`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper)
|
|
231
|
+
- agent framework adapters example:
|
|
232
|
+
[`npm run agent:framework-adapters`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#agent-framework-adapters)
|
|
208
233
|
- JSON records input example:
|
|
209
234
|
[`npm run json-records`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#json-records-input)
|
|
210
235
|
- Formula diagnostics example:
|
|
@@ -239,6 +264,8 @@ Repository links:
|
|
|
239
264
|
[`docs/hyperformula-alternative-headless-workpaper.md`](https://github.com/proompteng/bilig/blob/main/docs/hyperformula-alternative-headless-workpaper.md)
|
|
240
265
|
- SheetJS and ExcelJS comparison:
|
|
241
266
|
[`docs/sheetjs-exceljs-alternative-formula-workbook-api.md`](https://github.com/proompteng/bilig/blob/main/docs/sheetjs-exceljs-alternative-formula-workbook-api.md)
|
|
267
|
+
- broader headless spreadsheet engine comparison:
|
|
268
|
+
[`docs/headless-spreadsheet-engine-comparison.md`](https://github.com/proompteng/bilig/blob/main/docs/headless-spreadsheet-engine-comparison.md)
|
|
242
269
|
- local benchmark walkthrough:
|
|
243
270
|
[`docs/local-workpaper-benchmark-walkthrough.md`](https://github.com/proompteng/bilig/blob/main/docs/local-workpaper-benchmark-walkthrough.md)
|
|
244
271
|
- XLOOKUP exact fixture walkthrough:
|
|
@@ -343,6 +370,7 @@ npm install
|
|
|
343
370
|
npm start
|
|
344
371
|
npm run http-json-summary
|
|
345
372
|
npm run agent:tool-call
|
|
373
|
+
npm run agent:framework-adapters
|
|
346
374
|
```
|
|
347
375
|
|
|
348
376
|
For the agent-specific writeback proof, run:
|
|
@@ -359,6 +387,10 @@ outputs survived the round trip.
|
|
|
359
387
|
`readRange`, `setInputCell`, computed before/after values, formula contracts,
|
|
360
388
|
persistence bytes, and restored readback equality.
|
|
361
389
|
|
|
390
|
+
`npm run agent:framework-adapters` maps the same validated WorkPaper operations
|
|
391
|
+
into Vercel AI SDK and LangChain-style tool objects without adding either
|
|
392
|
+
framework as an example dependency.
|
|
393
|
+
|
|
362
394
|
For a framework-neutral recipe that wraps WorkPaper operations as agent-callable
|
|
363
395
|
tools, see
|
|
364
396
|
[`docs/agent-workpaper-tool-calling-recipe.md`](https://github.com/proompteng/bilig/blob/main/docs/agent-workpaper-tool-calling-recipe.md).
|
package/package.json
CHANGED
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bilig/headless",
|
|
3
|
-
"version": "0.11.
|
|
4
|
-
"description": "Headless spreadsheet engine for Node.js formulas, workbook JSON persistence, and service-side spreadsheet automation.",
|
|
3
|
+
"version": "0.11.31",
|
|
4
|
+
"description": "Headless spreadsheet engine for Node.js formulas, agent tools, workbook JSON persistence, and service-side spreadsheet automation.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agent",
|
|
7
|
+
"agent-tools",
|
|
7
8
|
"agents",
|
|
8
9
|
"ai-agents",
|
|
10
|
+
"ai-sdk",
|
|
9
11
|
"ai-spreadsheet",
|
|
10
12
|
"automation",
|
|
11
13
|
"bilig",
|
|
@@ -18,6 +20,7 @@
|
|
|
18
20
|
"headless-spreadsheet",
|
|
19
21
|
"headless-workbook",
|
|
20
22
|
"hyperformula",
|
|
23
|
+
"langchain",
|
|
21
24
|
"local-first",
|
|
22
25
|
"node",
|
|
23
26
|
"node-spreadsheet",
|
|
@@ -27,12 +30,15 @@
|
|
|
27
30
|
"spreadsheet-automation",
|
|
28
31
|
"spreadsheet-engine",
|
|
29
32
|
"spreadsheet-formulas",
|
|
33
|
+
"vercel-ai-sdk",
|
|
30
34
|
"workbook",
|
|
31
35
|
"workbook-api",
|
|
32
36
|
"workbook-automation",
|
|
33
37
|
"workbook-engine",
|
|
34
38
|
"workbook-state",
|
|
35
|
-
"workpaper"
|
|
39
|
+
"workpaper",
|
|
40
|
+
"workpaper-json",
|
|
41
|
+
"xlsx"
|
|
36
42
|
],
|
|
37
43
|
"homepage": "https://proompteng.github.io/bilig/",
|
|
38
44
|
"bugs": {
|
|
@@ -66,9 +72,9 @@
|
|
|
66
72
|
"build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json"
|
|
67
73
|
},
|
|
68
74
|
"dependencies": {
|
|
69
|
-
"@bilig/core": "0.11.
|
|
70
|
-
"@bilig/formula": "0.11.
|
|
71
|
-
"@bilig/protocol": "0.11.
|
|
75
|
+
"@bilig/core": "0.11.31",
|
|
76
|
+
"@bilig/formula": "0.11.31",
|
|
77
|
+
"@bilig/protocol": "0.11.31"
|
|
72
78
|
},
|
|
73
79
|
"engines": {
|
|
74
80
|
"node": ">=24.0.0"
|