Metadata-Version: 2.4
Name: numeratica
Version: 1.0.0
Summary: Official Python SDK for the Numeratica financial-planning API — generated from the OpenAPI spec.
Author: Numeratica / Francis Townsend-Merino
License-Expression: MIT
Project-URL: Homepage, https://docs.numeratica.com
Project-URL: Repository, https://github.com/numeratica/fin
Project-URL: Issues, https://github.com/numeratica/fin/issues
Keywords: numeratica,retirement,tax,finance,api,sdk,openapi
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx<0.29.0,>=0.23.1
Requires-Dist: attrs>=22.2.0

# numeratica (Python SDK)

Official **Python SDK** for the [Numeratica](https://docs.numeratica.com) financial-planning
API — retirement Monte Carlo, taxes, RMDs, Social Security, Roth conversions, and more.
Fully typed, **generated from the OpenAPI spec** (never hand-written), so it never drifts
from the API.

**Get a free API key at [docs.numeratica.com](https://docs.numeratica.com).**

## Install

```sh
pip install numeratica
```

## Use

```python
import os
from numeratica import AuthenticatedClient
from numeratica.api.default import retirement_monte_carlo
from numeratica.models import MonteCarloRequest

client = AuthenticatedClient(
    base_url="https://api.numeratica.com",
    token=os.environ["NUMERATICA_API_KEY"],
)

resp = retirement_monte_carlo.sync(
    client=client,
    body=MonteCarloRequest.from_dict({
        "current_age": 40, "retirement_age": 65, "end_age": 95,
        "current_balance": 500000, "annual_contribution": 30000, "annual_spending": 60000,
        "expected_return": 0.06, "return_volatility": 0.12,
    }),
)
print(resp.result.success_probability, resp.result_id)
```

Each endpoint is a module under `numeratica.api.default`, named from the operation's
`operationId` (`tvm`, `tax_estimate`, `retirement_monte_carlo`, `medicare_irmaa`, …), with
`.sync()`, `.sync_detailed()`, and `.asyncio()` variants. The key is sent as
`Authorization: Bearer <token>`.

## Notes

The `numeratica/` package is generated from `api/openapi.yaml` (`make sdk-py` in the main
repo) and must not be edited by hand. Requires Python ≥ 3.11. Docs & reference:
<https://docs.numeratica.com>.

MIT © Numeratica / Francis Townsend-Merino
