com.worthune/models

SDKs de Worthune

SDKs oficiales para la API de modelos de Worthune — modelos de cálculo financiero verificados que puedes citar, auditar y en los que puedes confiar, invocables vía REST o MCP. Gratis con atribución, sin claves de API. El catálogo crece en paquetes verificados (préstamos y crédito, jubilación e impuestos, startups y pequeñas empresas, con más dirigidos por solicitudes); GET /api/v1/models es siempre la lista en vivo.

• JavaScript / TypeScript: npm install worthune — cero dependencias, Node 18+ y navegadores
• Python: pip install worthune — cero dependencias, Python 3.9+
• Sin SDK en absoluto: es JSON simple sobre HTTPS — POST https://worthune.com/api/v1/models/{model} (el catálogo sigue creciendo — GET /api/v1/models es siempre la lista en vivo)
• MCP (Claude, ChatGPT, agentes): https://worthune.com/api/mcp/mcp — com.worthune/models en el registro oficial de MCP

Por qué estos modelos son diferentes

Las calculadoras financieras son fáciles de escribir y fáciles de equivocar sutilmente. Worthune trata la precisión como un artefacto, no como una afirmación:

1. Cada modelo tiene una especificación publicada — entradas, unidades, dominios válidos, fórmulas exactas, suposiciones, exclusiones. La especificación es una solicitud GET: GET /api/v1/models/{model}/spec.
2. Dos implementaciones deben coincidir. Cada modelo se reconstruye de forma independiente a partir de su especificación, y ambas implementaciones deben coincidir en 250 casos fuzzeados por modelo — en todo el catálogo — antes de que cualquier cambio se publique. Un desacuerdo en cualquier punto detiene el lanzamiento.
3. Las constantes tienen procedencia. Los límites del IRS, tramos y factores de la SSA provienen de un registro con fuentes con citas de fuentes primarias y fechas de verificación — y cada respuesta cita las constantes que utilizó.
4. Sin cambios silenciosos. Los cambios de comportamiento de los modelos se publican como incrementos de versión de especificación con un registro de cambios público. Las respuestas fijan su specVersion.

Sesenta segundos para un 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

Qué incluye

Capacidad	JS	Python
Ejecutar cualquier modelo del catálogo	client.run(model, inputs)	client.run(model, inputs)
Contrato legible por máquina	client.getContract(model)	client.get_contract(model)
Especificación completa (markdown)	client.getSpec(model)	client.get_spec(model)
Conjuntos de datos de evaluación (verdad fundamental para IA financiera)	client.getEvalDataset(model)	client.get_eval_dataset(model)
Constantes IRS/SSA con fuentes	client.getFacts()	client.get_facts()
Verificación de registros de decisión	verifyRecord(response)	verify_record(response)

Registros de decisión: cada respuesta exitosa incluye record.sha256 — un hash sobre el JSON canónico de {model, specVersion, inputs, outputs} (claves ordenadas recursivamente). Guárdalo junto a cualquier cosa que construyas sobre los resultados; recalcúlalo más tarde para demostrar que los números provienen de esa versión de especificación, sin alteraciones. Ambos SDK implementan la receta, byte por byte.

Hogares: recursos de planificación con estado (v0.2)

Más allá de las ejecuciones de modelos puntuales, una clave de API abre el motor de hogares — recursos de hogar persistentes y propiedad de la organización que creas una vez, mantienes actualizados y proyectas bajo 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})

Las reemplazos usan concurrencia optimista (pasa expectedVersion y una escritura obsoleta pierde limpiamente con la versión actual), las eliminaciones archivan en lugar de destruir, y los endpoints de webhook (createWebhookEndpoint) entregan eventos firmados household.computed / household.updated / household.archived — HMAC-SHA256 sobre ${timestamp}.${body}, secreto mostrado una sola vez al crear.

Uso justo y atribución

Todo aquí es gratuito con atribución — un "Powered by Worthune" visible con un enlace donde los usuarios finales ven los resultados. El uso justo es de 5,000 ejecuciones de modelos al mes por aplicación (una guía, no un medidor). Los detalles, por escrito: worthune.com/pricing.

Qué es este repositorio (y qué no es)

Este repositorio contiene los clientes de API, ejemplos y sus pruebas. Los modelos en sí — las especificaciones, el motor verificado, la segunda implementación y el pipeline de datos — viven detrás de la API en worthune.com. Esa separación es el producto: obtienes cálculo verificado como servicio, sin asumir la carga de la verificación.

Licencia

MIT (el código del SDK en este repositorio). El uso de la API se rige por los términos de Worthune.