com.worthune/models

SDKs da Worthune

SDKs oficiais para a API de Modelos Worthune — modelos de cálculo financeiro verificados que você pode citar, auditar e nos quais pode confiar, chamáveis via REST ou MCP. Gratuitos com atribuição, sem chaves de API. O catálogo cresce em pacotes verificados (empréstimos e crédito, aposentadoria e impostos, startups e pequenas empresas, com mais direcionados por solicitações); GET /api/v1/models é sempre a lista atualizada.

• JavaScript / TypeScript: npm install worthune — zero dependências, Node 18+ e navegadores
• Python: pip install worthune — zero dependências, Python 3.9+
• Sem SDK algum: é JSON puro via HTTPS — POST https://worthune.com/api/v1/models/{model} (o catálogo continua crescendo — GET /api/v1/models é sempre a lista atualizada)
• MCP (Claude, ChatGPT, agentes): https://worthune.com/api/mcp/mcp — com.worthune/models no registro oficial de MCP

Por que esses modelos são diferentes

Calculadoras financeiras são fáceis de escrever e fáceis de errar sutilmente. A Worthune trata a precisão como um artefato, não como uma afirmação:

1. Todo modelo tem uma especificação publicada — entradas, unidades, domínios válidos, fórmulas exatas, premissas, exclusões. A especificação é uma única solicitação GET: GET /api/v1/models/{model}/spec.
2. Duas implementações devem concordar. Cada modelo é reconstruído de forma independente a partir de sua especificação, e ambas as implementações devem corresponder em 250 casos de fuzzing por modelo — em todo o catálogo — antes que qualquer alteração seja publicada. Discordância em qualquer ponto interrompe o lançamento.
3. Constantes têm procedência. Limites do IRS, faixas e fatores do SSA vêm de um registro com fontes com citações de fontes primárias e datas de verificação — e cada resposta cita as constantes que utilizou.
4. Sem alterações silenciosas. Mudanças no comportamento dos modelos são publicadas como incrementos de versão de especificação com um registro de alterações público. As respostas fixam seu specVersion.

Sessenta segundos para um cálculo verificado

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

O que está incluído

Capacidade	JS	Python
Executar qualquer modelo no catálogo	client.run(model, inputs)	client.run(model, inputs)
Contrato legível por máquina	client.getContract(model)	client.get_contract(model)
Especificação completa (markdown)	client.getSpec(model)	client.get_spec(model)
Conjuntos de dados de avaliação (verdade fundamental para IA financeira)	client.getEvalDataset(model)	client.get_eval_dataset(model)
Constantes do IRS/SSA com fontes	client.getFacts()	client.get_facts()
Verificação de registro de decisão	verifyRecord(response)	verify_record(response)

Registros de decisão: toda resposta bem-sucedida inclui record.sha256 — um hash sobre o JSON canônico de {model, specVersion, inputs, outputs} (chaves ordenadas recursivamente). Armazene-o junto a qualquer coisa que você construir sobre as saídas; recalcule-o depois para provar que os números vieram daquela versão de especificação, sem alterações. Ambos os SDKs implementam a receita, byte por byte.

Famílias: recursos de planejamento com estado (v0.2)

Além de execuções de modelo pontuais, uma chave de API abre o mecanismo de famílias — recursos familiares persistentes e de propriedade da organização que você cria uma vez, mantém atualizados e projeta sob demanda:

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})

Substituições usam concorrência otimista (passe expectedVersion e uma gravação desatualizada falha limpo com a versão atual), exclusões arquivam em vez de destruir, e endpoints de webhook (createWebhookEndpoint) entregam eventos assinados household.computed / household.updated / household.archived — HMAC-SHA256 sobre ${timestamp}.${body}, segredo exibido uma única vez na criação.

Uso justo e atribuição

Tudo aqui é gratuito com atribuição — um "Powered by Worthune" visível com um link onde os usuários finais veem os resultados. O uso justo é de 5.000 execuções de modelo por mês por aplicativo (uma diretriz, não um medidor). Os detalhes, por escrito: worthune.com/pricing.

O que este repositório é (e não é)

Este repositório contém os clientes da API, exemplos e seus testes. Os modelos em si — as especificações, o mecanismo verificado, a segunda implementação e o pipeline de fatos — vivem atrás da API em worthune.com. Essa separação é o produto: você obtém cálculo verificado como serviço, sem arcar com o fardo da verificação.

Licença

MIT (o código do SDK neste repositório). O uso da API é regido pelos termos da Worthune.