com.worthune/models

Worthune SDKs

Official SDKs for the Worthune Model API — verified financial calculation models you can cite, audit, and trust, callable over REST or MCP. Free with attribution, no API keys. The catalog grows in verified packs (loans & credit, retirement & tax, startup & small business, with more steered by requests); GET /api/v1/models is always the live list.

• JavaScript / TypeScript: npm install worthune — zero dependencies, Node 18+ and browsers
• Python: pip install worthune — zero dependencies, Python 3.9+
• No SDK at all: it's plain JSON over HTTPS — POST https://worthune.com/api/v1/models/{model} (the catalog keeps growing — GET /api/v1/models is always the live list)
• MCP (Claude, ChatGPT, agents): https://worthune.com/api/mcp/mcp — com.worthune/models in the official MCP registry

Why these models are different

Financial calculators are easy to write and easy to get subtly wrong. Worthune treats accuracy as an artifact, not a claim:

1. Every model has a published spec — inputs, units, valid domains, exact formulas, assumptions, exclusions. The spec is one GET request: GET /api/v1/models/{model}/spec.
2. Two implementations must agree. Each model is independently rebuilt from its spec, and both implementations must match on 250 fuzzed cases per model — across the entire catalog — before any change ships. Disagreement anywhere stops the release.
3. Constants have provenance. IRS limits, brackets, and SSA factors come from a sourced registry with primary-source citations and verification dates — and every response cites the constants it used.
4. No silent changes. Model behavior changes ship as spec version bumps with a public changelog. Responses pin their specVersion.

Sixty seconds to a verified computation

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;               // "1.0.0" — pinned contract
result.facts;                     // IRS/SSA constants used, with sources
await verifyRecord(result);       // true — SHA-256 audit fingerprint checks out

from worthune import Worthune, verify_record

client = Worthune()
result = client.run("relocation", {...})
result["outputs"]["breakEvenMonths"]
verify_record(result)  # True

What's in the box

Capability	JS	Python
Run any model in the catalog	client.run(model, inputs)	client.run(model, inputs)
Machine-readable contract	client.getContract(model)	client.get_contract(model)
Full spec (markdown)	client.getSpec(model)	client.get_spec(model)
Eval datasets (ground truth for financial AI)	client.getEvalDataset(model)	client.get_eval_dataset(model)
Sourced IRS/SSA constants	client.getFacts()	client.get_facts()
Decision-record verification	verifyRecord(response)	verify_record(response)

Decision records: every successful response includes record.sha256 — a hash over the canonical JSON of {model, specVersion, inputs, outputs} (keys sorted recursively). Store it next to anything you build on the outputs; recompute it later to prove the numbers came from that spec version, unaltered. Both SDKs implement the recipe, byte-exactly.

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.

Fair use & attribution

Everything here is free with attribution — a visible "Powered by Worthune" with a link where end users see results. Fair use is 5,000 model runs a month per app (a guideline, not a meter). The details, in writing: worthune.com/pricing.

What this repo is (and isn't)

This repo contains the API clients, examples, and their tests. The models themselves — the specs, the verified engine, the second implementation, and the facts pipeline — live behind the API at worthune.com. That separation is the product: you get verified computation as a service, without owning the verification burden.

License

MIT (the SDK code in this repository). API usage is governed by the Worthune terms.