worthune

Zero-dependency SDK for the Worthune Model API — verified financial calculation models you can cite, audit, and trust. No API keys. Free with attribution.

Every model has a published spec, an independent second implementation that must agree with the first on 250 fuzzed cases before anything ships, and IRS/SSA constants traced to primary sources. Model changes are never silent: responses pin specVersion, and the changelog is public.

npm install worthune

import { Worthune, verifyRecord } from "worthune";

const client = new Worthune();

const result = await client.run("relocation", {
  currentSalary: 95000, newSalary: 108000,
  currentMonthlyExpenses: 4200, newMonthlyExpenses: 4900,
  movingCosts: 6000, currentSavings: 40000,
  annualReturn: 0.07, yearsHorizon: 10,
});

result.outputs.breakEvenMonths;  // 16
result.specVersion;              // pinned contract version
result.facts;                    // IRS/SSA constants used, with sources
result.sentinels;                // special values, explained
await verifyRecord(result);      // true — audit fingerprint checks out

Works in Node 18+, browsers, and edge runtimes (anything with fetch and Web Crypto).

API

• client.listModels() — catalog with spec versions
• client.getContract(model) — machine-readable inputs/domains/sentinels
• client.getSpec(model) — the full published spec (markdown)
• client.run(model, inputs) — run; validation failures return {ok: false, errors} instead of throwing
• client.getEvalDataset(model) — 250 verified input/expected-output pairs, the exact cases Worthune's dual-implementation CI verifies (ground truth for financial AI testing)
• client.getFacts() — the sourced IRS/SSA constants registry
• verifyRecord(response) — recompute the SHA-256 decision record to prove where numbers came from
• canonicalJson(value) — the canonical serialization the record hashes

Retirement, FIRE, rent vs. buy, loans and credit, retirement tax (RMDs, Roth ladders, capital gains), and startup finance (SAFE dilution, burn rate, SBA loan cost) — the catalog grows in verified packs; client.listModels() or the live catalog is always current.

Model runs are never metered. The three sample models need no key; the rest of the catalog and the household resources take a paid wk_ key — pricing, in writing.

MIT licensed. The models, specs, and verification harness live behind the API at worthune.com.

Households: stateful planning resources (v0.2)

Beyond one-shot model runs, an API key opens the household engine — persistent, organization-owned household resources you create once, keep updated, and project on demand:

const client = new Worthune({ apiKey: "wk_…" });
const { household } = await client.createHousehold(doc, "The Alvarez family");
const run = await client.projectHousehold(household.id, {
  horizon: { startYear: 2027, years: 40 },
  monteCarlo: { seed: 42 },           // same seed, same result
});
// run.assumptionsSource names where the assumptions came from;
// run.projection.assumptionsApplied lists every simplification that fired.

client = Worthune(api_key="wk_…")
created = client.create_household(doc, label="The Alvarez family")
run = client.project_household(created["household"]["id"],
                               horizon={"startYear": 2027, "years": 40},
                               monte_carlo={"seed": 42})

Replaces use optimistic concurrency (pass expectedVersion and a stale write loses cleanly with the current version), deletes archive rather than destroy, and webhook endpoints (createWebhookEndpoint) deliver signed household.computed / household.updated / household.archived events — HMAC-SHA256 over ${timestamp}.${body}, secret shown once at create.