bilig

Public Adoption Kit

Status: shareable evaluation material for @bilig/headless and the public proompteng/bilig repository.

Use this page when someone asks why they should look at bilig, how to try it quickly, or what claims are already backed by repository artifacts. Keep the language direct and evidence-based; do not inflate benchmark or Excel-compatibility claims.

One-Line Positioning

@bilig/headless is a headless spreadsheet engine for Node services, coding agents, local-first workbook automation, and formula-backed business workflows.

Shorter version:

A headless spreadsheet engine for agents and Node services.

Who Should Care

The current checked-in benchmark evidence records WorkPaper 46/46 mean wins on scorecard-eligible comparable workloads against HyperFormula-style workloads: 38/38 public and 8/8 holdout. Keep the p95 nuance attached to that claim: it is not a blanket “faster on every p95 row” statement.

Ten-Minute Evaluation

Use the published package path when the evaluator does not want to clone the monorepo:

mkdir bilig-headless-eval
cd bilig-headless-eval
npm init -y
npm pkg set type=module
npm install @bilig/headless

Create eval.mjs:

import {
  WorkPaper,
  createWorkPaperFromDocument,
  exportWorkPaperDocument,
  parseWorkPaperDocument,
  serializeWorkPaperDocument,
} from '@bilig/headless'

const workbook = WorkPaper.buildFromSheets({
  Revenue: [
    ['Region', 'Customers', 'ARPA', 'Revenue'],
    ['West', 20, 1200, '=B2*C2'],
    ['East', 30, 250, '=B3*C3'],
    ['Central', 18, 300, '=B4*C4'],
  ],
  Summary: [
    ['Metric', 'Value'],
    ['Total revenue', '=SUM(Revenue!D2:D4)'],
    ['West customers', '=SUMIF(Revenue!A2:A4,"West",Revenue!B2:B4)'],
  ],
})

const summary = workbook.getSheetId('Summary')
if (summary === undefined) {
  throw new Error('Summary sheet was not created')
}

const total = workbook.getCellValue({ sheet: summary, row: 1, col: 1 })
const saved = serializeWorkPaperDocument(exportWorkPaperDocument(workbook, { includeConfig: true }))
const restored = createWorkPaperFromDocument(parseWorkPaperDocument(saved))

console.log({
  total,
  sheets: restored.getSheetNames(),
})

Run it:

node eval.mjs

Use the repository path when the evaluator wants the maintained example and local validation:

git clone https://github.com/proompteng/bilig.git
cd bilig/examples/headless-workpaper
npm install
npm start

For the agent-specific writeback proof, run:

npm run agent:verify

That command records the exact assumption cells changed, verifies dependent formula outputs, persists the workbook, restores it, and checks that formulas and values survived the round trip.

Shareable Copy

Short:

@bilig/headless is a headless spreadsheet engine for agents and Node services: formulas, structural edits, persistence, and benchmark evidence in one TypeScript package.

With proof:

bilig’s @bilig/headless package exposes a WorkPaper API for programmatic spreadsheet automation. It has npm install docs, a runnable external example, persistence helpers, and checked-in benchmark evidence against HyperFormula-style workloads.

Revenue-model angle:

@bilig/headless can run a multi-sheet revenue model in Node: formulas, scenario inputs, an agent-style edit, persistence, restore, and verified readback without opening a browser grid.

For contributors:

bilig is a local-first spreadsheet engine and runtime. Good first contributions are formula parity fixtures, engine correctness tests, WorkPaper benchmark scenarios, grid accessibility fixes, and docs that turn architecture notes into runnable examples.

Benchmark reply:

the useful part is the audit trail: a checked-in benchmark artifact, a verify command, and an explicit p95 caveat. the claim is 46/46 mean wins for the current comparable headless WorkPaper workloads, not “we are faster at everything.”

What Not To Overclaim

Maintainer Checklist Before Sharing

If any public claim changes, update the README, package README, benchmark evidence note, and latest GitHub release notes together.

This site is open source. Improve this page.