Metadata-Version: 2.4
Name: wqsurrogatemodels
Version: 2.1.0
Summary: WQI5-based current-state water quality assessment backend for WaterMirror.
Author-email: kageryo <kageryo@coderyo.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/KageRyo/WQSurrogateModels
Project-URL: Repository, https://github.com/KageRyo/WQSurrogateModels
Project-URL: Issues, https://github.com/KageRyo/WQSurrogateModels/issues
Keywords: water quality,WQI5,FastAPI,surrogate models
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Framework :: FastAPI
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi
Requires-Dist: joblib
Requires-Dist: loguru
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: python-dotenv
Requires-Dist: python-multipart
Requires-Dist: pyyaml
Requires-Dist: scikit-learn==1.5.2
Requires-Dist: uvicorn
Provides-Extra: dev
Requires-Dist: openpyxl>=3.1; extra == "dev"
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Requires-Dist: anyio>=4.0; extra == "dev"
Provides-Extra: test
Requires-Dist: openpyxl>=3.1; extra == "test"
Requires-Dist: pytest>=7.4; extra == "test"
Requires-Dist: httpx>=0.27.0; extra == "test"
Requires-Dist: anyio>=4.0; extra == "test"
Provides-Extra: models
Requires-Dist: lightgbm; extra == "models"
Requires-Dist: xgboost; extra == "models"
Provides-Extra: package
Requires-Dist: build>=1.2; extra == "package"
Requires-Dist: twine>=5.1; extra == "package"
Dynamic: license-file

# WQSurrogateModels

`wqsurrogatemodels` is the installable Python backend for WQI5-based current-state
water quality assessment.

## Install

```bash
pip install wqsurrogatemodels
```

The package requires Python 3.10 or newer. Optional surrogate-model libraries
are available with:

```bash
pip install "wqsurrogatemodels[models]"
```

## Use the direct WQI5 baseline

```python
from wqsurrogatemodels import direct_wqi5_score

score = direct_wqi5_score(do=7.2, bod=2.1, nh3n=0.3, ec=450, ss=12)
```

## Run the API

```bash
uvicorn wqsurrogatemodels.api:app --host 0.0.0.0 --port 8001
```

The primary HTTP contract is under `/api/v2/*`. Datasets and trained surrogate
artifacts are supplied separately and are not included in the PyPI distribution.
Set `PROJECT_ROOT` to the directory containing local `data/` and `models/`
directories when running the API outside a source checkout.

## Package boundary

The distribution contains the runtime package, dependency metadata, this
description, and the Apache 2.0 license. It excludes research datasets,
serialized model binaries, generated results, experiment configurations,
reproducibility scripts, repository-only tests, and research documentation.

Repository and API documentation:
<https://github.com/KageRyo/WQSurrogateModels>
