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.
