Metadata-Version: 2.4
Name: gaspatchio
Version: 0.5.2
Requires-Dist: logfire>=3.4.0
Requires-Dist: loguru>=0.7.3
Requires-Dist: numpy>=1.24.0,<2.2
Requires-Dist: platformdirs>=4.0
Requires-Dist: psutil>=5.9
Requires-Dist: pydantic>=2.0.0
Requires-Dist: polars==1.38.1
Requires-Dist: polars[rt64]==1.38.1
Requires-Dist: rich>=13.9.4
Requires-Dist: typer>=0.15.1
Requires-Dist: pyarrow>=15.0.0
Requires-Dist: thefuzz[speedup]>=0.22.1
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Dist: holidays>=0.50
Requires-Dist: markdown-it-py>=3.0.0
Requires-Dist: docstring-parser>=0.16
Requires-Dist: fastexcel>=0.14.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: python-dotenv>=1.1.0
Requires-Dist: vl-convert-python>=1.9.0.post1
Requires-Dist: altair>=6.1.0
Requires-Dist: ddsketch>=3.0.1
Requires-Dist: polars[rt64]==1.38.1 ; extra == 'excel'
Requires-Dist: polars[rt64]==1.38.1 ; extra == 'numpy'
Requires-Dist: polars[rt64]==1.38.1 ; extra == 'pandas'
Requires-Dist: polars[rt64]==1.38.1 ; extra == 'pyarrow'
Requires-Dist: marimo>=0.10.0 ; extra == 'recipes'
Provides-Extra: excel
Provides-Extra: numpy
Provides-Extra: pandas
Provides-Extra: pyarrow
Provides-Extra: recipes
Summary: Simple, fast and best served cold
Author-email: mrmattwright <matt@opioinc.com>
License-Expression: Apache-2.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://gaspatchio.dev/
Project-URL: Homepage, https://gaspatchio.dev/
Project-URL: Issues, https://github.com/gaspatchio/gaspatchio/issues
Project-URL: Repository, https://github.com/gaspatchio/gaspatchio

# Gaspatchio (Python)

The Python package for [Gaspatchio](../../README.md) — a high-performance actuarial modeling
framework. You write models in Python that read like spreadsheet formulas, and a Rust + Polars
engine runs them over millions of model points.

📖 **Documentation, tutorials, and full API + CLI reference → [gaspatchio.dev](https://gaspatchio.dev/)**

## Install

```bash
pip install gaspatchio        # or:  uv pip install gaspatchio
```

Then `import gaspatchio_core`. For a source/dev build, see [Building from source](#building-from-source).

## Quick start

```python
from gaspatchio_core import ActuarialFrame
from gaspatchio_core.assumptions import Table

# 1. Load assumption tables (registered + optimized by the Rust engine)
mortality = Table(
    name="mortality",
    source="data/mortality.parquet",
    dimensions={"age": "age", "gender": "sex"},
    value="rate",
)

# 2. Define the model — the formula IS the code
def projection(af: ActuarialFrame) -> ActuarialFrame:
    af.attained_age = af.dob.excel.yearfrac(af.val_date) + af.t      # Excel-compatible date maths
    af.qx = mortality.lookup(age=af.attained_age, gender=af.gender)  # vectorized lookup
    af.pols_if = af.pols_start * (1 - af.qx - af.lapse_rate)         # vectorized projection
    return af

# 3. Run (millions of model points supported)
af = ActuarialFrame(data="model_points.parquet")
result = projection(af).collect()
```

New here? The [tutorials](https://gaspatchio.dev/) build from hello-world to a lifelib-reconciled
model and on to scenarios.

## CLI: `gspio`

Run models from the command line:

```bash
gspio run-model model.py model-points.parquet                  # run all policies
gspio run-single-policy model.py model-points.parquet 12345    # debug one policy (transposed output)
gspio run-model model.py data.parquet --mode optimize          # optimized execution
gspio --install-completion                                     # shell tab-completion
```

- `--policy-id-column` sets the policy-identifier column (default `"Policy number"`).
- `--mode {debug,optimize}` plus display flags (`--rows/-r`, `--first-n/-f`, `--last-n/-l`,
  `--start-at/-s`) control execution and terminal output.

**Full CLI reference, with every flag and the single-policy result transposition →
[gaspatchio.dev](https://gaspatchio.dev/).**

## Building from source

The Rust extension is built with [maturin](https://www.maturin.rs/). `uv sync` builds in **debug**
mode (fast compiles); use `--release` for benchmarking/production:

```bash
uv sync                                                        # debug build, into the venv
maturin build --release -uv                                    # optimized build
RUSTFLAGS="-C target-cpu=native" maturin build --release -uv   # + native SIMD (AVX2/512)
```

`target-cpu=native` binaries only run on CPUs with the same or newer instruction sets — use them
for local benchmarking, **not** for distributable packages or CI builds.

## Testing

```bash
uv run pytest                                                  # tests + docstring-example validation
uv run python -m mypy.stubtest gaspatchio_core --allowlist stubtest-allowlist.txt --mypy-config-file mypy-stubtest.ini
```

Public-API docstrings carry examples validated against their output. The docstring/style tooling
and contributor coding standards live in [`AGENTS.md`](AGENTS.md).

## Learn more

- 📖 [Documentation](https://gaspatchio.dev/) — guides, tutorials, full API + CLI reference
- 🦀 [Rust engine](../../core/README.md) — the core that powers this package
- 🏠 [Project overview](../../README.md)

