Metadata-Version: 2.4
Name: nutramilo-health
Version: 0.2.0
Summary: Scientific SDK for peer-reviewed nutritional pattern indices (NIS, UIS, EDIP, DII, EDIH, NEAP, PRAL).
Home-page: https://nutramilo.com
Author: Nutramilo Labs
Author-email: Nutramilo Labs <science@nutramilo.com>
License: MIT
Project-URL: Homepage, https://nutramilo.com
Project-URL: Source, https://github.com/nutramilo/health-os
Project-URL: Tracker, https://github.com/nutramilo/health-os/issues
Keywords: nutrition,insulin-index,inflammation,DII,EDIP,PRAL,NEAP,metabolic-health
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: validation
Requires-Dist: numpy>=1.24; extra == "validation"
Requires-Dist: pandas>=2.0; extra == "validation"
Requires-Dist: matplotlib>=3.7; extra == "validation"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# nutramilo-health

[![TestPyPI](https://img.shields.io/badge/TestPyPI-0.1.1-blue.svg)](https://test.pypi.org/project/nutramilo-health/0.1.1/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-26%2F26%20passing-brightgreen.svg)](sdk/tests/)
[![EU AI Act](https://img.shields.io/badge/EU%20AI%20Act-Art.50%20compliant-success.svg)](https://eur-lex.europa.eu/eli/reg/2024/1689)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

Scientific SDK for peer-reviewed nutritional pattern indices used by the
Nutramilo Health OS platform.

> **Status:** beta — formulas validated against published cohorts (Holt n=147,
> Tabung 2016, Shivappa 2014, Frassetto 1998); API surface stable for 0.x.

---

## What's inside

| Index | Description | Citation |
|-------|-------------|----------|
| **NIS** — Nutramilo Insulin Score | 0-100 % postprandial insulin response forecast | Holt 1997 · Bell 2014 · Bao 2009 |
| **UIS** — Unified Inflammation Score | 0-100 % composite of EDIP+DII+NEAP | Nutramilo 2026 |
| **EDIP** | Empirical Dietary Inflammatory Pattern | Tabung 2016 (PMID 27358416) |
| **DII** | Dietary Inflammatory Index (9-param meal proxy) | Shivappa 2014 (PMID 23824729) |
| **EDIH** | Empirical Dietary Index for Hyperinsulinemia | Tabung 2017 (PMID 28196579) |
| **NEAP** | Net Endogenous Acid Production | Frassetto 1998 (PMID 9734733) |
| **PRAL** | Potential Renal Acid Load | Remer & Manz 1995 (PMID 7797810) |

All formulas are **deterministic**, **citation-backed**, **EU AI Act
Article 50 compliant** — no opaque ML, no proprietary model weights.

---

## Install

> **Currently published on TestPyPI** while the SDK is in beta. Once stable
> we will publish to the real PyPI index.

```bash
pip install --index-url https://test.pypi.org/simple/ --no-deps nutramilo-health
```

After v0.2.0 (real PyPI):

```bash
pip install nutramilo-health
```

Validation extras (pandas, numpy, matplotlib for the Colab notebook):

```bash
pip install "nutramilo-health[validation]"
```

---

## Quick start

```python
from nutramilo_health import (
    PlateFood,
    nutramilo_insulin_score,
    unified_inflammation_score,
)

plate = [
    PlateFood(name="grilled salmon", grams=150, protein_g=30, fat_g=10,
              category="fish"),
    PlateFood(name="quinoa", grams=120, carbs_g=39, fiber_g=4.5, protein_g=8,
              fat_g=3.5, category="grain_whole"),
    PlateFood(name="spinach", grams=80, fiber_g=4, protein_g=3,
              category="vegetable_leafy"),
]

nis = nutramilo_insulin_score(plate)
print(f"NIS = {nis['percent']} %  ({nis['tier']})")

uis = unified_inflammation_score(plate)
print(f"UIS = {uis['percent']} %  ({uis['tier_en']})")
```

```
NIS = 31.5 %  (moderate)
UIS = 12.4 %  (Strongly anti-inflammatory)
```

---

## Methodology

### NIS (Nutramilo Insulin Score) — v2.0-regression

```
# Per-1000-kJ scaled (Atwater factors: 17·C + 17·P + 37·F → kJ)
PIRU_v2     = max(0, 1.61·net_carbs_p1k + 0.66·protein_p1k
                       + 1.20·fat_p1k − 1.14·fiber_p1k)
regression% = piecewise_linear_map(PIRU_v2,
                                   anchors=[(0, 0%), (30, 50%), (75, 100%)])
holt%       = clip((il_total / 60) × 100, [0, 100])     # cross-track
tier_floor% = {low:0, medium:30, high:55}[dil_tier]     # clinical floor
NIS_final_% = max(regression%, holt%, tier_floor%)
```

**Coefficients** independently derived via OLS regression on
`HoltBellBao_v1_frozen_2026.csv` (n=147, sha256 b41eb157…). Stable across
Ridge α=1, Ridge α=10, LASSO α=0.5, and Bayesian Ridge (max delta < 0.05).
On the same cohort: **MAE 13.04** (vs Kendall heuristic 25.53), **R² 0.572**
(vs -0.315). See `notebooks/independent_regression_v2.py`.

> **Interpretation note.** Within the harmonized per-1000-kJ dataset, fat
> content contributed positively to predictive accuracy in mixed-meal
> contexts. This is an empirical regression result on the n=147 cohort and
> should NOT be interpreted as a direct physiological claim that fat alone
> stimulates insulin secretion.

**Production parity:** SDK v0.2.0+ reproduces the exact NIS computed by
the production `/api/plate-simulator/analyze` endpoint when called with
`holt_il_track=...` and `tier_floor=...` parameters.

### UIS (Unified Inflammation Score)

```
UIS% = 50 · (1 + Σ wᵢ · normalize(scoreᵢ))
where w = (0.40, 0.40, 0.20) for (EDIP, DII, NEAP)
and normalize() linearly maps cohort-anti / cohort-pro cutoffs to [-1, +1].
```

Component cutoffs:
- EDIP: anti = -0.20, pro = +0.30 (Tabung 2016 quintiles)
- DII:  anti = -1.5,  pro = +1.5  (Shivappa 2014 cohort)
- NEAP: anti = +20,   pro = +80   (Frassetto 1998 cohort)

---

## API

```python
from nutramilo_health import (
    PlateFood,
    nutramilo_insulin_score,
    piru_to_percent,
    unified_inflammation_score,
    edip_score, dii_score, edih_score, neap_score, pral_score,
)
```

Each scoring function takes an iterable of `PlateFood` and returns a dict
with at minimum: `percent` (or `score`), tier labels (BG / EN / ES for UIS),
component breakdown, citations, methodology string.

---

## License

MIT. See [LICENSE](LICENSE).

## Citation

If you use this SDK in research, please cite:

> Nutramilo Labs (2026). *nutramilo-health: A scientific SDK for peer-reviewed
> nutritional pattern indices.* Version 0.1.0.
> https://github.com/nutramilo/health-os
