Metadata-Version: 2.4
Name: mars-risk
Version: 0.0.27
Summary: High-performance Risk Modeling Toolkit powered by Polars
Author-email: christian <lee_sq001@163.com>
License: MIT License
        
        Copyright (c) 2026 Christian Li and Tina
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Keywords: credit-risk,credit-scoring,risk-analytics,risk-modeling,scorecard,feature-binning,feature-selection,risk-monitoring,polars,pipeline,psi,ks
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.13,>=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: polars==1.8.2; python_version < "3.9"
Requires-Dist: polars>=1.33.1; python_version >= "3.9"
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: jinja2>=3.1.2
Requires-Dist: pyarrow>=14.0.0
Requires-Dist: scikit-learn<1.4,>=1.3.2; python_version < "3.9"
Requires-Dist: scikit-learn<1.7,>=1.6.1; python_version >= "3.9" and python_version < "3.10"
Requires-Dist: scikit-learn>=1.7.2; python_version >= "3.10"
Requires-Dist: scipy>=1.10.0
Requires-Dist: ruptures>=1.1.9
Requires-Dist: optbinning>=0.19.0
Requires-Dist: joblib>=1.3.0
Requires-Dist: colorlog>=6.7.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: ipython>=8.0.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: xlsxwriter>=3.1.0
Requires-Dist: xlwings>=0.30.0
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: seaborn>=0.12.0
Provides-Extra: notebook
Requires-Dist: jupyterlab>=4.0.0; extra == "notebook"
Provides-Extra: ml
Requires-Dist: xgboost>=3.0.0; extra == "ml"
Requires-Dist: lightgbm>=4.6.0; extra == "ml"
Requires-Dist: catboost>=1.2.9; extra == "ml"
Requires-Dist: statsmodels>=0.14.0; extra == "ml"
Requires-Dist: shap>=0.45.0; extra == "ml"
Provides-Extra: tuning
Requires-Dist: optuna>=4.0.0; extra == "tuning"
Requires-Dist: optuna-integration>=4.0.0; extra == "tuning"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.25.0; extra == "docs"
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.2.0; extra == "docs"
Requires-Dist: mkdocs-jupyter>=0.25.0; extra == "docs"
Requires-Dist: nbclient>=0.10.0; extra == "docs"
Requires-Dist: nbformat>=5.10.0; extra == "docs"
Requires-Dist: ipykernel>=6.29.0; extra == "docs"
Requires-Dist: tomli>=2.0.0; python_version < "3.11" and extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Requires-Dist: mypy==1.13.0; extra == "dev"
Requires-Dist: pydoclint>=0.8.0; extra == "dev"
Requires-Dist: mkdocs-material>=9.5.0; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.25.0; extra == "dev"
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.2.0; extra == "dev"
Requires-Dist: mkdocs-jupyter>=0.25.0; extra == "dev"
Requires-Dist: nbclient>=0.10.0; extra == "dev"
Requires-Dist: nbformat>=5.10.0; extra == "dev"
Requires-Dist: ipykernel>=6.29.0; extra == "dev"
Requires-Dist: tomli>=2.0.0; python_version < "3.11" and extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: jupyterlab>=4.0.0; extra == "dev"
Requires-Dist: tqdm>=4.66.0; extra == "dev"
Requires-Dist: psutil>=5.9.0; extra == "dev"
Requires-Dist: statsmodels>=0.14.0; extra == "dev"
Requires-Dist: shap>=0.45.0; extra == "dev"
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: packaging>=24.0; extra == "dev"
Requires-Dist: twine>=5.1.0; extra == "dev"
Dynamic: license-file

# MARS

<div align="center">

<img src="docs/assets/mars-logo.svg" alt="MARS" width="800">

<img src="docs/assets/mars-wordmark.svg" alt="MODELING ANALYSIS RISK SCORE" width="720">

<img src="docs/assets/mars-tagline.svg" alt="面向信用风控分析与建模的 Polars-first 高性能工具库" width="720">

<img src="docs/assets/mars-workflow.svg" alt="Profile -> Bin/Evaluate -> Analyze -> Select -> Modeling -> Pipeline -> Monitor -> Report" width="820">

<p align="center">
  <a href="https://pypi.org/project/mars-risk/"><img alt="PyPI" src="https://img.shields.io/pypi/v/mars-risk?style=flat-square&label=PyPI&color=2f6f8f"></a>
  <a href="https://leeesq.github.io/mars-risk/"><img alt="Docs" src="https://img.shields.io/badge/Docs-GitHub%20Pages-7c3aed?style=flat-square"></a>
  <a href="https://pypi.org/project/mars-risk/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/mars-risk?style=flat-square&label=Python&color=364f6b"></a>
  <a href="https://pepy.tech/project/mars-risk"><img alt="Downloads" src="https://img.shields.io/pepy/dt/mars-risk?style=flat-square&label=Downloads&color=0f766e"></a>
  <a href="https://github.com/leeesq/mars-risk/actions/workflows/test.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/leeesq/mars-risk/test.yml?branch=main&style=flat-square&label=CI&color=1f7a5a"></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/leeesq/mars-risk?style=flat-square&label=License&color=6c5ce7"></a>
</p>

<p align="center">
  <a href="https://leeesq.github.io/mars-risk/">文档站</a> ·
  <a href="https://leeesq.github.io/mars-risk/getting-started/quickstart/">Quickstart</a> ·
  <a href="https://leeesq.github.io/mars-risk/user-guide/binning-risk-evaluation/">分箱评估</a> ·
  <a href="https://leeesq.github.io/mars-risk/user-guide/monitoring/">监控</a> ·
  <a href="https://leeesq.github.io/mars-risk/user-guide/reports-and-exports/">报告导出</a>
</p>

</div>

MARS 接受 Pandas 或 Polars 宽表，提供数据画像、分箱评估、特征筛选、建模、监控、结构化 report、
Excel/HTML 导出和评分卡能力。

## 安装

MARS `0.0.27` 支持 Python 3.8–3.12。Python 3.8 使用冻结兼容依赖栈；可选的建模、
调参、Notebook 和文档工具要求 Python 3.10+。

```bash
pip install mars-risk==0.0.27
```

从 GitHub 源码安装当前 `main` 分支：

```bash
pip install "git+https://github.com/leeesq/mars-risk.git"
```

也可以先克隆仓库，再从本地源码安装：

```bash
git clone https://github.com/leeesq/mars-risk.git
cd mars-risk
pip install .
```

建模与调参需要可选依赖：

```bash
pip install "mars-risk[ml,tuning]==0.0.27"
```

`0.0.27` 正式发布前，请从源码安装进行文档预览验收。Python 3.8 已停止官方安全维护；
MARS 的运行兼容不代表解释器仍有安全支持。

## 最小风险评估

```python
import polars as pl

from mars.analysis import profile_risk

df = pl.DataFrame(
    {
        "income": [3200, 3600, 5200, 6100, 3400, 4300, 5800, 6800],
        "utilization": [0.72, 0.61, 0.29, 0.18, 0.66, 0.48, 0.24, 0.12],
        "target": [1, 1, 0, 0, 1, 1, 0, 0],
    }
)

risk_profile = profile_risk(
    df,
    target="target",
    features=["income", "utilization"],
    method="quantile",
    n_bins=4,
)

summary = risk_profile.report.summary_table
binner = risk_profile.binner
```

完整的日期、分组、趋势和报告示例见
[10 分钟 Quickstart](https://leeesq.github.io/mars-risk/getting-started/quickstart/)。

## 从任务开始

| 目标 | 文档 |
| --- | --- |
| 检查缺失、分布和 PSI | [数据画像](https://leeesq.github.io/mars-risk/user-guide/data-profiling/) |
| 使用基准规则评估当前数据 | [分箱与风险评估](https://leeesq.github.io/mars-risk/user-guide/binning-risk-evaluation/) |
| 统计、线性或重要性筛选 | [特征筛选](https://leeesq.github.io/mars-risk/user-guide/feature-selection/) |
| 切分、调参、replay 与 Pipeline | [Modeling / Pipeline](https://leeesq.github.io/mars-risk/user-guide/modeling-pipeline/) |
| 分布、模型分和表现覆盖率监控 | [特征与模型监控](https://leeesq.github.io/mars-risk/user-guide/monitoring/) |
| Excel、HTML、评分卡与 SQL | [报告与评分卡](https://leeesq.github.io/mars-risk/user-guide/reports-and-exports/) |
| 精确签名、默认值和异常 | [API Reference](https://leeesq.github.io/mars-risk/reference/) |

## 稳定性

Analysis、Feature、Reporting 是当前 Stable 模块。Monitoring、Modeling、Pipeline、Scoring 为
Experimental；受控生产流程应固定精确版本，并为 report 字段、报警结果、评分映射、生成 SQL、
step 契约、replay 和 artifact 路径增加契约回归。

## 开发检查

```bash
python -m ruff check src tests scripts docs/snippets
python -m mypy src/mars
pydoclint src/mars
python scripts/check_private_docstrings.py src/mars
python -m pytest -q
python -m mkdocs build --strict
```

贡献要求见 [CONTRIBUTING.md](CONTRIBUTING.md)，许可证见 [LICENSE](LICENSE)。
