wealthschema 0.1.0__tar.gz

wealthschema-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+node_modules/
+.next/
+.env
+.env.local
+.env.development
+.env.production
+.env.test
+*.log
+.turso/
+dist/
+out/
+*.tsbuildinfo
+*.db
+*.db-journal
+.DS_Store
+
+# Regenerable machine output from `npm run audit-claims` (baseline + report are committed)
+content-audit/claims-inventory.json
+
+# QA harness output (the harness scripts in qa/ are committed; their
+# artifacts — screenshots, captured emails, reports — are regenerable)
+qa/screenshots/
+qa/outbox/
+qa/report.json
+qa/report.md
+qa/flows-report.json

wealthschema-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.5
+Name: wealthschema
+Version: 0.1.0
+Summary: Official SDK for WealthSchema: cited U.S. financial-planning figures (API + MCP), synthetic-household evaluation samples, and the free Planning Benchmark for AI financial-advisor agents.
+Project-URL: Homepage, https://www.wealthschema.com
+Project-URL: Repository, https://github.com/CapsteraSupport/wealthschema-py
+Author: WealthSchema
+License: MIT
+Keywords: ai-agent-evaluation,benchmark,fintech,irs,mcp,no-pii,planning-figures,synthetic-data,synthetic-financial-data,tax,test-data,wealthschema,wealthtech
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# wealthschema (Python)
+
+Official Python SDK for [WealthSchema](https://www.wealthschema.com) — the data layer for building and testing financial software. Zero dependencies (standard library only).
+
+It wraps WealthSchema's public, free surfaces:
+
+- **Rule Sets** — cited, current U.S. planning figures (IRS, SSA, CMS, Treasury) with issuer, document, section, and effective date.
+- **Evaluation samples** — one deliberately-insufficient synthetic household per archetype.
+- **Free Planning Benchmark** — tasks with ground-truth answers for evaluating AI financial-advisor agents.
+- **Catalog** — the product catalog.
+
+> The full synthetic-household **corpus is a one-time purchase**, delivered as files after checkout — not a metered API. This SDK intentionally has no method to download it. Samples are banded and truncated for evaluation only.
+
+## Install
+
+```bash
+pip install wealthschema
+```
+
+## Quickstart
+
+```python
+from wealthschema import WealthSchema
+
+ws = WealthSchema()  # or WealthSchema(api_key="...") ; falls back to WEALTHSCHEMA_API_KEY
+
+# A cited planning figure, with its source and effective date:
+fact = ws.get_fact("us-federal-2026", "retirement.401k.elective_deferral.under_50")
+print(fact["value"], fact["source"])  # 24500 {'issuer': 'IRS', 'document': 'Notice 2025-67', ...}
+
+# A sample synthetic household (evaluation only):
+sample = ws.get_sample_household("young-family-first-home")
+
+# The free Planning Benchmark for agent evals:
+bench = ws.get_benchmark(withhold_answers=True)  # omit for the answer key
+```
+
+Get a free API key at https://www.wealthschema.com/account/api-keys. The free tier works without a key.
+
+## API
+
+| Method | Returns |
+|---|---|
+| `list_reference_datasets()` | Reference index + tier matrix |
+| `get_reference_dataset(id)` | All cited facts for a dataset |
+| `get_fact(id, key)` | One cited fact by key, or `None` |
+| `get_manifest()` | Archetype/bundle taxonomy + sample links |
+| `get_sample_household(archetype_id)` | One insufficient sample household |
+| `get_catalog()` | Product catalog |
+| `get_benchmark(withhold_answers=False)` | Free Planning Benchmark tasks |
+
+Requests raise `WealthSchemaError` with `.status` and `.code` (e.g. `code="rate_limited"` on HTTP 429).
+
+## MCP
+
+Rule Sets is also an MCP server:
+
+```json
+{ "mcpServers": { "wealthschema": { "url": "https://www.wealthschema.com/api/mcp" } } }
+```
+
+## License
+
+MIT. Data and API use are governed by the [feed terms](https://www.wealthschema.com/reference-feed-terms) and per-purchase license.

wealthschema-0.1.0/README.md

@@ -0,0 +1,64 @@
+# wealthschema (Python)
+
+Official Python SDK for [WealthSchema](https://www.wealthschema.com) — the data layer for building and testing financial software. Zero dependencies (standard library only).
+
+It wraps WealthSchema's public, free surfaces:
+
+- **Rule Sets** — cited, current U.S. planning figures (IRS, SSA, CMS, Treasury) with issuer, document, section, and effective date.
+- **Evaluation samples** — one deliberately-insufficient synthetic household per archetype.
+- **Free Planning Benchmark** — tasks with ground-truth answers for evaluating AI financial-advisor agents.
+- **Catalog** — the product catalog.
+
+> The full synthetic-household **corpus is a one-time purchase**, delivered as files after checkout — not a metered API. This SDK intentionally has no method to download it. Samples are banded and truncated for evaluation only.
+
+## Install
+
+```bash
+pip install wealthschema
+```
+
+## Quickstart
+
+```python
+from wealthschema import WealthSchema
+
+ws = WealthSchema()  # or WealthSchema(api_key="...") ; falls back to WEALTHSCHEMA_API_KEY
+
+# A cited planning figure, with its source and effective date:
+fact = ws.get_fact("us-federal-2026", "retirement.401k.elective_deferral.under_50")
+print(fact["value"], fact["source"])  # 24500 {'issuer': 'IRS', 'document': 'Notice 2025-67', ...}
+
+# A sample synthetic household (evaluation only):
+sample = ws.get_sample_household("young-family-first-home")
+
+# The free Planning Benchmark for agent evals:
+bench = ws.get_benchmark(withhold_answers=True)  # omit for the answer key
+```
+
+Get a free API key at https://www.wealthschema.com/account/api-keys. The free tier works without a key.
+
+## API
+
+| Method | Returns |
+|---|---|
+| `list_reference_datasets()` | Reference index + tier matrix |
+| `get_reference_dataset(id)` | All cited facts for a dataset |
+| `get_fact(id, key)` | One cited fact by key, or `None` |
+| `get_manifest()` | Archetype/bundle taxonomy + sample links |
+| `get_sample_household(archetype_id)` | One insufficient sample household |
+| `get_catalog()` | Product catalog |
+| `get_benchmark(withhold_answers=False)` | Free Planning Benchmark tasks |
+
+Requests raise `WealthSchemaError` with `.status` and `.code` (e.g. `code="rate_limited"` on HTTP 429).
+
+## MCP
+
+Rule Sets is also an MCP server:
+
+```json
+{ "mcpServers": { "wealthschema": { "url": "https://www.wealthschema.com/api/mcp" } } }
+```
+
+## License
+
+MIT. Data and API use are governed by the [feed terms](https://www.wealthschema.com/reference-feed-terms) and per-purchase license.

wealthschema-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "wealthschema"
+version = "0.1.0"
+description = "Official SDK for WealthSchema: cited U.S. financial-planning figures (API + MCP), synthetic-household evaluation samples, and the free Planning Benchmark for AI financial-advisor agents."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "WealthSchema" }]
+keywords = [
+  "wealthschema", "synthetic-data", "synthetic-financial-data", "fintech",
+  "wealthtech", "test-data", "irs", "tax", "planning-figures", "mcp",
+  "ai-agent-evaluation", "benchmark", "no-pii",
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://www.wealthschema.com"
+Repository = "https://github.com/CapsteraSupport/wealthschema-py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["wealthschema"]

wealthschema-0.1.0/wealthschema/__init__.py

@@ -0,0 +1,120 @@
+"""WealthSchema Python SDK.
+
+A thin, dependency-free client for WealthSchema's public, free surfaces:
+
+- Rule Sets: cited, current U.S. planning figures (API + MCP).
+- Evaluation samples: one deliberately-insufficient synthetic household per
+  archetype (a taste; the full corpus is a one-time purchase, not an API).
+- The free Planning Benchmark for AI financial-advisor agents.
+- The product catalog.
+
+By design there is no method to download the synthetic-household corpus: it is
+static reference data sold once via checkout, never a metered data API. Samples
+are intentionally banded/truncated. See https://www.wealthschema.com/llms.txt
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Optional
+
+__version__ = "0.1.0"
+__all__ = ["WealthSchema", "WealthSchemaError"]
+
+_DEFAULT_BASE = "https://www.wealthschema.com"
+
+
+class WealthSchemaError(Exception):
+    """Raised when a request fails. Carries HTTP ``status`` and optional ``code``."""
+
+    def __init__(self, message: str, status: Optional[int] = None, code: Optional[str] = None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+
+
+class WealthSchema:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = _DEFAULT_BASE,
+        timeout: float = 30.0,
+    ):
+        self.api_key = api_key or os.environ.get("WEALTHSCHEMA_API_KEY")
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _get(self, path: str, auth: bool = False, query: Optional[dict] = None) -> Any:
+        url = self.base_url + path
+        if query:
+            clean = {k: v for k, v in query.items() if v is not None}
+            if clean:
+                url += "?" + urllib.parse.urlencode(clean)
+        headers = {"Accept": "application/json", "User-Agent": f"wealthschema-py/{__version__}"}
+        if auth and self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        req = urllib.request.Request(url, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            if e.code == 429:
+                retry = e.headers.get("Retry-After")
+                raise WealthSchemaError(
+                    f"Rate limited{f'; retry after {retry}s' if retry else ''}. "
+                    "Add an API key or upgrade your tier.",
+                    status=429,
+                    code="rate_limited",
+                ) from None
+            body = {}
+            try:
+                body = json.loads(e.read().decode("utf-8"))
+            except Exception:
+                pass
+            raise WealthSchemaError(
+                body.get("message") or body.get("error") or f"Request failed ({e.code})",
+                status=e.code,
+                code=body.get("code"),
+            ) from None
+
+    # ── Rule Sets: cited planning figures ────────────────────────────────
+    def list_reference_datasets(self) -> Any:
+        """Index of reference datasets + tier matrix."""
+        return self._get("/api/reference/v1", auth=True)
+
+    def get_reference_dataset(self, dataset_id: str) -> Any:
+        """All cited facts for a dataset, e.g. ``us-federal-2026``."""
+        return self._get(f"/api/reference/v1/{urllib.parse.quote(dataset_id)}", auth=True)
+
+    def get_fact(self, dataset_id: str, key: str) -> Optional[dict]:
+        """One cited fact by key, or None."""
+        doc = self.get_reference_dataset(dataset_id)
+        for fact in (doc or {}).get("facts", []):
+            if fact.get("key") == key:
+                return fact
+        return None
+
+    # ── Evaluation samples (a taste; not the corpus) ─────────────────────
+    def get_manifest(self) -> Any:
+        """Machine manifest: archetype/bundle taxonomy + sample links."""
+        return self._get("/api/for-agents")
+
+    def get_sample_household(self, archetype_id: str) -> Any:
+        """One deliberately-insufficient sample household (evaluation only)."""
+        return self._get(f"/api/for-agents/households/{urllib.parse.quote(archetype_id)}")
+
+    def get_catalog(self) -> Any:
+        """Product catalog."""
+        return self._get("/api/catalog")
+
+    # ── Free Planning Benchmark ──────────────────────────────────────────
+    def get_benchmark(self, withhold_answers: bool = False) -> Any:
+        """The free Planning Benchmark for AI financial-advisor agents."""
+        return self._get(
+            "/api/benchmark/v1",
+            query={"withhold_answers": "true"} if withhold_answers else None,
+        )