worthune 0.1.0__tar.gz

worthune-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+__pycache__/
+*.egg-info/
+build/

worthune-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.5
+Name: worthune
+Version: 0.1.0
+Summary: Official SDK for the Worthune Model API — 27 dual-implementation-verified financial calculation models with published specs and IRS/SSA-sourced constants. Zero dependencies.
+Project-URL: Homepage, https://worthune.com
+Project-URL: Documentation, https://worthune.com/docs
+Project-URL: Repository, https://github.com/CapsteraSupport/worthune-sdk
+Author: Worthune
+License-Expression: MIT
+Keywords: api-client,calculator,evals,finance,financial-calculations,financial-planning,fintech,mortgage,retirement,verified
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# worthune
+
+Zero-dependency SDK for the [Worthune Model API](https://worthune.com/docs) —
+27 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](https://worthune.com/models/changelog).
+
+```bash
+pip install worthune
+```
+
+```python
+from worthune import Worthune, verify_record
+
+client = Worthune()
+
+result = 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
+verify_record(result)                 # True — audit fingerprint checks out
+```
+
+## API
+
+- `client.list_models()` — catalog with spec versions
+- `client.get_contract(model)` — machine-readable inputs/domains/sentinels
+- `client.get_spec(model)` — the full published spec (markdown)
+- `client.run(model, inputs)` — run; validation failures return `{"ok": False, "errors": [...]}` instead of raising
+- `client.get_eval_dataset(model)` — 250 verified input/expected-output pairs, the exact cases Worthune's dual-implementation CI verifies (ground truth for financial AI testing)
+- `client.get_facts()` — the sourced IRS/SSA constants registry
+- `verify_record(response)` — recompute the SHA-256 decision record to prove where numbers came from (byte-exact ECMAScript-compatible canonical JSON)
+
+Retirement, FIRE, rent vs. buy, refinancing, equity comp (RSUs), debt payoff,
+Social Security timing, 529 plans, estate planning, and more — the
+[full catalog](https://worthune.com/models) lists all 27.
+
+Fair use: 5,000 runs/month per app (a guideline, not a meter) —
+[the free tier, in writing](https://worthune.com/pricing).
+
+MIT licensed. The models, specs, and verification harness live behind the API
+at [worthune.com](https://worthune.com).

worthune-0.1.0/README.md

@@ -0,0 +1,54 @@
+# worthune
+
+Zero-dependency SDK for the [Worthune Model API](https://worthune.com/docs) —
+27 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](https://worthune.com/models/changelog).
+
+```bash
+pip install worthune
+```
+
+```python
+from worthune import Worthune, verify_record
+
+client = Worthune()
+
+result = 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
+verify_record(result)                 # True — audit fingerprint checks out
+```
+
+## API
+
+- `client.list_models()` — catalog with spec versions
+- `client.get_contract(model)` — machine-readable inputs/domains/sentinels
+- `client.get_spec(model)` — the full published spec (markdown)
+- `client.run(model, inputs)` — run; validation failures return `{"ok": False, "errors": [...]}` instead of raising
+- `client.get_eval_dataset(model)` — 250 verified input/expected-output pairs, the exact cases Worthune's dual-implementation CI verifies (ground truth for financial AI testing)
+- `client.get_facts()` — the sourced IRS/SSA constants registry
+- `verify_record(response)` — recompute the SHA-256 decision record to prove where numbers came from (byte-exact ECMAScript-compatible canonical JSON)
+
+Retirement, FIRE, rent vs. buy, refinancing, equity comp (RSUs), debt payoff,
+Social Security timing, 529 plans, estate planning, and more — the
+[full catalog](https://worthune.com/models) lists all 27.
+
+Fair use: 5,000 runs/month per app (a guideline, not a meter) —
+[the free tier, in writing](https://worthune.com/pricing).
+
+MIT licensed. The models, specs, and verification harness live behind the API
+at [worthune.com](https://worthune.com).

worthune-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "worthune"
+version = "0.1.0"
+description = "Official SDK for the Worthune Model API — 27 dual-implementation-verified financial calculation models with published specs and IRS/SSA-sourced constants. Zero dependencies."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Worthune" }]
+keywords = [
+  "finance",
+  "financial-calculations",
+  "fintech",
+  "retirement",
+  "mortgage",
+  "verified",
+  "calculator",
+  "api-client",
+  "financial-planning",
+  "evals",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Programming Language :: Python :: 3",
+  "Topic :: Office/Business :: Financial",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://worthune.com"
+Documentation = "https://worthune.com/docs"
+Repository = "https://github.com/CapsteraSupport/worthune-sdk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/worthune"]

worthune-0.1.0/src/worthune/__init__.py

@@ -0,0 +1,206 @@
+"""Worthune SDK — thin, zero-dependency client for the Worthune Model API.
+
+27 financial calculation models, each with a published spec and an
+independent second implementation that must agree with the first before
+anything ships. Docs: https://worthune.com/docs
+
+The SDK is a client only — the models, specs, and verification harness live
+behind the API. Free with attribution: https://worthune.com/pricing
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import urllib.error
+import urllib.request
+from decimal import Decimal
+from typing import Any
+
+__version__ = "0.1.0"
+__all__ = [
+    "Worthune",
+    "WorthuneError",
+    "canonical_json",
+    "verify_record",
+]
+
+_DEFAULT_BASE_URL = "https://worthune.com"
+_USER_AGENT = f"worthune-python/{__version__}"
+
+
+class WorthuneError(Exception):
+    """Raised for transport failures and non-validation HTTP errors."""
+
+    def __init__(self, message: str, status: int | None = None, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class Worthune:
+    """Client for the Worthune Model API.
+
+    >>> client = Worthune()
+    >>> result = client.run("relocation", {"currentSalary": 95000, ...})
+    >>> result["outputs"]["breakEvenMonths"]
+    """
+
+    def __init__(self, base_url: str = _DEFAULT_BASE_URL, timeout: float = 30.0):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    # ── transport ────────────────────────────────────────────────────────────
+    def _request(self, path: str, payload: dict[str, Any] | None = None) -> bytes:
+        url = f"{self.base_url}{path}"
+        data = None
+        headers = {"user-agent": _USER_AGENT, "accept": "*/*"}
+        if payload is not None:
+            data = json.dumps(payload).encode("utf-8")
+            headers["content-type"] = "application/json"
+        req = urllib.request.Request(url, data=data, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                return res.read()
+        except urllib.error.HTTPError as err:
+            body_bytes = err.read()
+            # 400s carry the structured validation envelope callers want;
+            # everything else (404, 429 burst backstop, 5xx) raises.
+            if err.code == 400:
+                return body_bytes
+            body: Any = None
+            try:
+                body = json.loads(body_bytes)
+            except ValueError:
+                pass
+            raise WorthuneError(
+                f"{'POST' if payload is not None else 'GET'} {path} -> {err.code}",
+                status=err.code,
+                body=body,
+            ) from err
+        except urllib.error.URLError as err:
+            raise WorthuneError(f"request to {url} failed: {err.reason}") from err
+
+    def _get_json(self, path: str) -> Any:
+        return json.loads(self._request(path))
+
+    # ── API surface ──────────────────────────────────────────────────────────
+    def list_models(self) -> list[dict[str, Any]]:
+        """Catalog of all models with spec versions."""
+        return self._get_json("/api/v1/models")["models"]
+
+    def get_contract(self, model: str) -> dict[str, Any]:
+        """Machine-readable contract: inputs, domains, sentinels, spec version."""
+        return self._get_json(f"/api/v1/models/{model}")
+
+    def get_spec(self, model: str) -> str:
+        """The full published spec, as markdown."""
+        return self._request(f"/api/v1/models/{model}/spec").decode("utf-8")
+
+    def run(self, model: str, inputs: dict[str, Any]) -> dict[str, Any]:
+        """Run a model.
+
+        Returns the full envelope — outputs, sentinels, assumptions, cited
+        facts, and the decision record. Validation failures return
+        ``{"ok": False, "errors": [...]}`` rather than raising; network and
+        server errors raise :class:`WorthuneError`.
+        """
+        return json.loads(self._request(f"/api/v1/models/{model}", payload=inputs))
+
+    def list_evals(self) -> dict[str, Any]:
+        """Index of verified eval datasets."""
+        return self._get_json("/api/v1/evals")
+
+    def get_eval_dataset(self, model: str) -> dict[str, Any]:
+        """One eval dataset: ``{"meta": {...}, "cases": [...]}``.
+
+        250 deterministic input/expected-output pairs — the exact cases
+        Worthune's dual-implementation CI harness verifies.
+        """
+        lines = self._request(f"/api/v1/evals/{model}").decode("utf-8").strip().split("\n")
+        return {
+            "meta": json.loads(lines[0]),
+            "cases": [json.loads(line) for line in lines[1:]],
+        }
+
+    def get_facts(self) -> list[dict[str, Any]]:
+        """The sourced-constants registry (IRS limits, brackets, SSA factors)."""
+        return self._get_json("/api/v1/facts")["facts"]
+
+
+# ── Decision-record verification ─────────────────────────────────────────────
+# Every successful run carries record.sha256 — SHA-256 over the canonical JSON
+# of {model, specVersion, inputs, outputs} with object keys sorted recursively
+# and numbers rendered exactly as ECMAScript renders them (the server is
+# JavaScript). Recompute it any time to prove a stored response's numbers came
+# from that spec version with those inputs, unaltered.
+
+
+def _js_number_repr(value: float) -> str:
+    """Render a float exactly as ECMAScript Number::toString(10) would.
+
+    Python and JavaScript both choose shortest round-trip digits, but format
+    them differently (e.g. Python ``5e-05`` vs JS ``0.00005``; Python
+    ``1e+21`` matches JS, but Python switches to exponent form at different
+    thresholds). JSON numbers parsed from API responses hash correctly only
+    if re-rendered the way the server rendered them.
+    """
+    if value != value or value in (float("inf"), float("-inf")):
+        raise ValueError("non-finite numbers cannot appear in JSON")
+    if value == 0:
+        return "0"  # covers -0.0, which JS renders as "0"
+    sign = "-" if value < 0 else ""
+    d = Decimal(repr(abs(value))).normalize()
+    digit_tuple, exp = d.as_tuple()[1], int(d.as_tuple()[2])
+    digits = "".join(str(x) for x in digit_tuple)
+    k = len(digits)
+    n = exp + k  # value = 0.<digits> * 10^n
+    if k <= n <= 21:
+        return sign + digits + "0" * (n - k)
+    if 0 < n <= 21:
+        return sign + digits[:n] + "." + digits[n:]
+    if -6 < n <= 0:
+        return sign + "0." + "0" * (-n) + digits
+    # exponential form; JS writes e+21 / e-7 (no zero padding)
+    e = n - 1
+    e_str = f"e+{e}" if e >= 0 else f"e-{-e}"
+    if k == 1:
+        return sign + digits + e_str
+    return sign + digits[0] + "." + digits[1:] + e_str
+
+
+def canonical_json(value: Any) -> str:
+    """Serialize with object keys sorted recursively, no whitespace,
+    JS-compatible number rendering."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if value is None:
+        return "null"
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False)
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        return _js_number_repr(value)
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(canonical_json(v) for v in value) + "]"
+    if isinstance(value, dict):
+        items = sorted(value.items(), key=lambda kv: kv[0])
+        return "{" + ",".join(
+            f"{json.dumps(k, ensure_ascii=False)}:{canonical_json(v)}" for k, v in items
+        ) + "}"
+    raise TypeError(f"unsupported type in canonical JSON: {type(value)!r}")
+
+
+def verify_record(response: dict[str, Any]) -> bool:
+    """Recompute a response's decision-record hash and compare."""
+    canonical = canonical_json(
+        {
+            "model": response["model"],
+            "specVersion": response["specVersion"],
+            "inputs": response["inputs"],
+            "outputs": response["outputs"],
+        }
+    )
+    digest = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+    return digest == response["record"]["sha256"]

worthune-0.1.0/tests/fixture-relocation.json

@@ -0,0 +1 @@
+{"ok":true,"model":"relocation","specVersion":"1.0.0","contractUrl":"/api/v1/models/relocation","specUrl":"/api/v1/models/relocation/spec","inputs":{"currentSalary":95000,"newSalary":108000,"currentMonthlyExpenses":4200,"newMonthlyExpenses":4900,"movingCosts":6000,"currentSavings":40000,"annualReturn":0.07,"yearsHorizon":10},"outputs":{"annualSalaryDelta":13000,"annualExpenseDelta":8400,"annualNetDelta":4600,"movingCostRecoveryMonths":16,"breakEvenMonths":16,"wealthAtHorizonStay":694899.6333646487,"wealthAtHorizonMove":746652.3858427971,"netWealthGain":51752.75247814844,"yearlyData":[{"year":0,"stay":40000,"move":34000},{"year":1,"stay":87400,"move":85580},{"year":2,"stay":138118,"move":140770.6},{"year":3,"stay":192386.26,"move":199824.54200000002},{"year":4,"stay":250453.29820000002,"move":263012.25994},{"year":5,"stay":312585.029074,"move":330623.11813580006},{"year":6,"stay":379065.98110918,"move":402966.7364053061},{"year":7,"stay":450200.5997868226,"move":480374.4079536775},{"year":8,"stay":526314.6417719002,"move":563200.616510435},{"year":9,"stay":607756.6666959333,"move":651824.6596661655},{"year":10,"stay":694899.6333646487,"move":746652.3858427971}]},"sentinels":[{"field":"breakEvenMonths","value":9999,"meaning":"never breaks even (monthlyNetDelta ≤ 0)","triggered":false}],"assumptions":["Implements model spec relocation v1.0.0 (dual-implementation verified)."],"facts":[],"record":{"sha256":"7891f5eac540c8e9252f832de1742778a0e54b8812d3e198fe289e1c46b6bfd9","fields":["model","specVersion","inputs","outputs"],"howToVerify":"Store this record with any advice or agent output built on these numbers. To verify later: build {model, specVersion, inputs, outputs} from the stored response, serialize as JSON with object keys sorted recursively (no whitespace), and SHA-256 it — a match proves the numbers came from this spec version with these inputs, unaltered."},"disclaimer":"Illustrative planning model, not financial advice. Outputs follow the published model spec exactly; read the spec for assumptions and exclusions before relying on any number."}

worthune-0.1.0/tests/test_sdk.py

@@ -0,0 +1,71 @@
+"""Offline tests: decision-record verification against a real captured
+response, and JS-exact number rendering (ground truth generated with Node)."""
+
+import copy
+import json
+import pathlib
+import sys
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1] / "src"))
+
+from worthune import _js_number_repr, canonical_json, verify_record  # noqa: E402
+
+FIXTURE = json.loads(
+    (pathlib.Path(__file__).parent / "fixture-relocation.json").read_text()
+)
+
+# Expected strings generated with `node -e 'console.log(String(v))'`.
+JS_NUMBER_CASES = [
+    (0.07, "0.07"),
+    (4600.0, "4600"),
+    (32409.87, "32409.87"),
+    (0.00005, "0.00005"),
+    (5e-7, "5e-7"),
+    (1e21, "1e+21"),
+    (1.5e21, "1.5e+21"),
+    (123.456, "123.456"),
+    (100.0, "100"),
+    (-0.0, "0"),
+    (1e-6, "0.000001"),
+    (9007199254740991.0, "9007199254740991"),
+    (2.5e-8, "2.5e-8"),
+    (-42.75, "-42.75"),
+    (0.1, "0.1"),
+    (3e20, "300000000000000000000"),
+]
+
+
+class TestDecisionRecord(unittest.TestCase):
+    def test_fixture_verifies(self):
+        self.assertTrue(FIXTURE["ok"])
+        self.assertTrue(verify_record(FIXTURE))
+
+    def test_tampering_detected(self):
+        tampered = copy.deepcopy(FIXTURE)
+        tampered["outputs"]["breakEvenMonths"] = 1
+        self.assertFalse(verify_record(tampered))
+
+    def test_key_order_independent(self):
+        reordered = copy.deepcopy(FIXTURE)
+        reordered["inputs"] = dict(reversed(list(reordered["inputs"].items())))
+        self.assertTrue(verify_record(reordered))
+
+
+class TestJsNumberRepr(unittest.TestCase):
+    def test_matches_ecmascript(self):
+        for value, expected in JS_NUMBER_CASES:
+            self.assertEqual(_js_number_repr(value), expected, msg=repr(value))
+
+    def test_ints_pass_through_canonical_json(self):
+        self.assertEqual(canonical_json({"a": 4600, "b": True, "c": None}), '{"a":4600,"b":true,"c":null}')
+
+    def test_canonical_sorts_recursively(self):
+        self.assertEqual(
+            canonical_json({"b": 1, "a": {"d": [2, {"z": 3, "y": 4}], "c": 5}}),
+            '{"a":{"c":5,"d":[2,{"y":4,"z":3}]},"b":1}',
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()