upliftlab 0.26.1__tar.gz

upliftlab-0.26.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Funbucket
+
+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.

upliftlab-0.26.1/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: upliftlab
+Version: 0.26.1
+Summary: Find the uplift model that gives the most incremental outcome for the same budget, on your own experiment data
+License-Expression: MIT
+Project-URL: Homepage, https://uplift-lab.vercel.app
+Project-URL: Source, https://github.com/Funbucket/upliftlab
+Project-URL: Documentation, https://github.com/Funbucket/upliftlab/blob/main/docs/guide.md
+Project-URL: Changelog, https://github.com/Funbucket/upliftlab/blob/main/CHANGELOG.md
+Keywords: uplift modeling,causal inference,CATE,targeting,marketing,A/B testing
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: web/fonts/LICENSE
+License-File: web/vendor/LICENSES.txt
+License-File: web/data/LICENSE-criteo.md
+Requires-Dist: numpy>=1.21
+Requires-Dist: scikit-learn>=1.2
+Requires-Dist: econml>=0.16; platform_machine != "aarch64" and platform_machine != "ARM64"
+Provides-Extra: gpu
+Requires-Dist: torch; extra == "gpu"
+Provides-Extra: templates
+Requires-Dist: lightgbm>=4; extra == "templates"
+Requires-Dist: torch; extra == "templates"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: lightgbm>=4; extra == "dev"
+Dynamic: license-file
+
+<a href="https://uplift-lab.vercel.app"><img src="https://raw.githubusercontent.com/Funbucket/upliftlab/main/docs/images/banner.png" alt="upliftlab. 같은 예산을 주고, 모델끼리 겨뤄요. Criteo 예시의 최종 순위표: Duality R-Learner 786, R-Learner 783, X-Learner 759, T-Learner 757, DML 699, Random 485. 사진 판정: 1~5위 차이는 95% CI 안이고 Random과의 차이는 유의해요."></a>
+
+<div align="center">
+
+**같은 예산에서 증분 성과를 가장 많이 내는 uplift 모델을, 운영 전에 찾아요.**
+
+[![Live demo](https://img.shields.io/badge/demo-uplift--lab.vercel.app-4d8dff?style=flat-square)](https://uplift-lab.vercel.app)
+[![PyPI](https://img.shields.io/pypi/v/upliftlab?style=flat-square&color=11141a&label=pypi)](https://pypi.org/project/upliftlab/)
+[![Built on EconML](https://img.shields.io/badge/built%20on-EconML-11141a?style=flat-square)](https://github.com/py-why/EconML)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-11141a?style=flat-square)](https://github.com/Funbucket/upliftlab/blob/main/pyproject.toml)
+[![MIT License](https://img.shields.io/badge/license-MIT-11141a?style=flat-square)](https://github.com/Funbucket/upliftlab/blob/main/LICENSE)
+
+**[웹에서 바로 실행 →](https://uplift-lab.vercel.app)** &nbsp;·&nbsp; [로컬 설치](#빠른-시작) &nbsp;·&nbsp; [사용 안내](https://github.com/Funbucket/upliftlab/blob/main/docs/guide.md)
+
+<sub>위 순위표는 Criteo 광고 실험 199,837명을 예산 40%, 8사이클로 돌린 실제 결과예요(EconML). 사이트에서는 사이클 1부터 8까지 다시 보여 줘요.</sub>
+
+</div>
+
+## 왜 upliftlab인가요
+
+Qini가 가장 높은 모델이 운영에서도 가장 많이 남길까요? 오프라인 지표 하나로 모델을 고르면, 대상 선정과 재학습을 반복하면서 생기는 차이를 놓쳐요.
+
+- **운영 루프를 그대로 돌려요.** 모델마다 대상을 고르고, 처치군과 대조군으로 효과를 재고, 재학습하는 과정을 사이클마다 반복해요.
+- **같은 조건에서만 비교해요.** 모든 모델이 같은 사용자, 같은 예산, 같은 무작위 Explore 그룹을 써요. 차이는 대상을 고른 방식에서만 생겨요.
+- **차이가 유의한지 보여 줘요.** 1위와의 차이를 95% CI로 그려서, 순위를 확정할 수 없는 박빙이면 그렇다고 적어요.
+- **데이터는 밖으로 나가지 않아요.** 웹은 브라우저 안에서, 로컬은 내 Python에서 돌아요. 공유 보고서에는 집계 값만 들어가요.
+
+## 빠른 시작
+
+**웹 · 설치 없이.** [uplift-lab.vercel.app](https://uplift-lab.vercel.app)을 열고 `비교 시작`을 눌러요. Criteo 데이터, 기본 모델 6개, 예산 40%가 이미 골라져 있어요.
+
+**로컬 · EconML로.** 같은 화면이 내 Python에서 돌아가요. 큰 데이터, 이미 설치한 라이브러리, GPU를 그대로 써요.
+
+```bash
+pip install upliftlab
+upliftlab                # http://127.0.0.1:4180 이 열려요
+```
+
+uv를 쓴다면 설치 없이 `uvx upliftlab` 한 줄이면 돼요. 처음 실행할 때 Criteo 표본(2.3MB)을 한 번 내려받아 두고, 그다음부터는 그대로 써요.
+
+> [!NOTE]
+> 브라우저에서는 EconML을 쓸 수 없어서, 웹은 같은 방법을 scikit-learn으로 쓴 경량판으로 돌려요. 결과 화면과 보고서에 어느 쪽으로 돌렸는지 표시해요.
+
+## 결과 읽는 법
+
+<a href="https://uplift-lab.vercel.app"><img src="https://raw.githubusercontent.com/Funbucket/upliftlab/main/docs/images/verdict.png" alt="결과 화면. 결승선은 박빙, 기준선과는 큰 차이. Random 대비 증분 방문 +62%, 1위와의 차이와 95% CI, P1~P5와 기준선 순위 카드"></a>
+
+- **제목**이 결론이에요. 2위와의 차이가 95% CI 안이면 `결승선은 박빙`이라고 쓰고, 기준선(Random)과의 차이가 확실한지도 함께 적어요.
+- **Random 대비**는 1위가 무작위로 고를 때보다 같은 예산으로 성과를 얼마나 더 냈는지예요.
+- **1위와의 차이 · 95% CI**에서 구간이 0을 지나는 모델은 회색, 확실히 낮은 모델은 파란색이에요. 박빙이면 `사진 판정` 표시가 붙어요.
+- 그 아래에 순위표, 1위가 고른 사용자의 특성, 사이클별 지표, Row-level 로그, Cost Curve가 이어져요.
+
+## 데이터에서 보고서까지
+
+| ① 데이터 넣기 | ② 비교 시작 | ③ 보고서 공유 |
+| :-- | :-- | :-- |
+| 실험 로그 CSV를 끌어다 놓으면 처치, 결과, 비용, 공변량 열을 알아서 골라요. | 모델, 선정 방식, 예산을 확인하고 `비교 시작`을 눌러요. 끝나면 결과로 바로 내려가요. | 1위 모델, Random 대비 증분 성과, 2위와의 차이를 HTML 보고서, PDF, 메신저 요약으로 보내요. |
+
+## 기본 모델
+
+| 모델 | EconML 구현 | 하는 일 |
+| :-- | :-- | :-- |
+| T-Learner | `metalearners.TLearner` | 처치군과 대조군 모델의 예측 차이 |
+| X-Learner | `metalearners.XLearner` | 대체한 효과를 propensity로 가중 |
+| R-Learner | `dml.NonParamDML` | 잔차로 푸는 비모수 CATE |
+| DML | `dml.LinearDML` | 잔차로 푸는 선형 CATE |
+| Duality R-Learner | `dml.NonParamDML` × 2 | 성과와 비용의 CATE를 함께 보고 λ를 validation에서 골라요 |
+| Random | NumPy | 비교 기준선 |
+
+각 파일은 `class Model` 하나라서 화면에서 바로 열어 보고 고쳐 쓸 수 있어요.
+
+## 내 알고리즘 추가
+
+upliftlab을 import하지 않는 Python 파일 하나예요. scikit-learn, LightGBM, PyTorch를 평소처럼 써요.
+
+```python
+class Model:
+    def fit(self, train, validation, context):  # train.X, train.t, train.y, train.cost
+        ...
+    def predict(self, X):                        # 사용자마다 점수 하나. 높은 순서로 대상을 골라요
+        ...
+```
+
+웹에서는 `알고리즘` 화면의 `알고리즘 추가`에서 시작 틀을 골라 편집해요. 로컬에서는 화면 없이도 비교할 수 있어요.
+
+```bash
+upliftlab run --data my_experiment.csv --algorithm my_model.py
+```
+
+<details>
+<summary><b>내 데이터 형식</b> · 처치를 무작위로 배정한 실험 로그, 1,000행 이상</summary>
+<br>
+
+열 이름은 자유예요. 형식이 헷갈리면 화면의 `예시 파일 내려받기`로 받은 파일을 참고하세요.
+
+| 역할 | 예시 열 | 값 |
+| :-- | :-- | :-- |
+| 처치 | `treatment` | 0 = 대조군, 1 = 처치. 여러 종류면 1, 2, 3… |
+| 결과 | `retained` | 전환, 구매, 리텐션처럼 늘리고 싶은 값 |
+| 비용 (선택) | `coupon_cost` | 처치로 쓴 비용. 없으면 처치 1건당 1로 계산해요 |
+| 공변량 | `visit_freq`, … | 처치 **전에** 측정한 사용자 특성 |
+
+기본 데이터는 [Criteo](https://ailab.criteo.com/criteo-uplift-prediction-dataset/) 광고 실험이에요. 원본 1,398만 명에서 처치군과 대조군을 10만 명씩 뽑은 표본(199,837명, 결과는 사이트 방문)이 사이트와 패키지에 들어 있어요.
+
+</details>
+
+## 더 보기
+
+[사용 안내](https://github.com/Funbucket/upliftlab/blob/main/docs/guide.md) · 선정 방식 5가지, 명령줄 옵션, 결과 읽는 법<br>
+[알고리즘 계약](https://github.com/Funbucket/upliftlab/blob/main/engine/README.md) · `fit`과 `predict`에 들어오는 값, 코드 검사 규칙<br>
+[개발 참여](https://github.com/Funbucket/upliftlab/blob/main/CONTRIBUTING.md) · 빌드, 테스트, 폴더 구조<br>
+[변경 기록](https://github.com/Funbucket/upliftlab/blob/main/CHANGELOG.md)
+
+<sub>[MIT](https://github.com/Funbucket/upliftlab/blob/main/LICENSE). Criteo 표본은 [CC BY-NC-SA 4.0](https://github.com/Funbucket/upliftlab/blob/main/web/data/LICENSE-criteo.md)이라 비상업적으로만 쓸 수 있어요. pip 패키지에는 넣지 않고 처음 쓸 때 이 저장소에서 내려받아요. Pretendard, Archivo, Geist Mono 글꼴은 SIL Open Font License(`web/fonts/LICENSE`), 편집기 번들은 `web/vendor/LICENSES.txt`를 따라요.</sub>

upliftlab-0.26.1/README.md

@@ -0,0 +1,114 @@
+<a href="https://uplift-lab.vercel.app"><img src="https://raw.githubusercontent.com/Funbucket/upliftlab/main/docs/images/banner.png" alt="upliftlab. 같은 예산을 주고, 모델끼리 겨뤄요. Criteo 예시의 최종 순위표: Duality R-Learner 786, R-Learner 783, X-Learner 759, T-Learner 757, DML 699, Random 485. 사진 판정: 1~5위 차이는 95% CI 안이고 Random과의 차이는 유의해요."></a>
+
+<div align="center">
+
+**같은 예산에서 증분 성과를 가장 많이 내는 uplift 모델을, 운영 전에 찾아요.**
+
+[![Live demo](https://img.shields.io/badge/demo-uplift--lab.vercel.app-4d8dff?style=flat-square)](https://uplift-lab.vercel.app)
+[![PyPI](https://img.shields.io/pypi/v/upliftlab?style=flat-square&color=11141a&label=pypi)](https://pypi.org/project/upliftlab/)
+[![Built on EconML](https://img.shields.io/badge/built%20on-EconML-11141a?style=flat-square)](https://github.com/py-why/EconML)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-11141a?style=flat-square)](https://github.com/Funbucket/upliftlab/blob/main/pyproject.toml)
+[![MIT License](https://img.shields.io/badge/license-MIT-11141a?style=flat-square)](https://github.com/Funbucket/upliftlab/blob/main/LICENSE)
+
+**[웹에서 바로 실행 →](https://uplift-lab.vercel.app)** &nbsp;·&nbsp; [로컬 설치](#빠른-시작) &nbsp;·&nbsp; [사용 안내](https://github.com/Funbucket/upliftlab/blob/main/docs/guide.md)
+
+<sub>위 순위표는 Criteo 광고 실험 199,837명을 예산 40%, 8사이클로 돌린 실제 결과예요(EconML). 사이트에서는 사이클 1부터 8까지 다시 보여 줘요.</sub>
+
+</div>
+
+## 왜 upliftlab인가요
+
+Qini가 가장 높은 모델이 운영에서도 가장 많이 남길까요? 오프라인 지표 하나로 모델을 고르면, 대상 선정과 재학습을 반복하면서 생기는 차이를 놓쳐요.
+
+- **운영 루프를 그대로 돌려요.** 모델마다 대상을 고르고, 처치군과 대조군으로 효과를 재고, 재학습하는 과정을 사이클마다 반복해요.
+- **같은 조건에서만 비교해요.** 모든 모델이 같은 사용자, 같은 예산, 같은 무작위 Explore 그룹을 써요. 차이는 대상을 고른 방식에서만 생겨요.
+- **차이가 유의한지 보여 줘요.** 1위와의 차이를 95% CI로 그려서, 순위를 확정할 수 없는 박빙이면 그렇다고 적어요.
+- **데이터는 밖으로 나가지 않아요.** 웹은 브라우저 안에서, 로컬은 내 Python에서 돌아요. 공유 보고서에는 집계 값만 들어가요.
+
+## 빠른 시작
+
+**웹 · 설치 없이.** [uplift-lab.vercel.app](https://uplift-lab.vercel.app)을 열고 `비교 시작`을 눌러요. Criteo 데이터, 기본 모델 6개, 예산 40%가 이미 골라져 있어요.
+
+**로컬 · EconML로.** 같은 화면이 내 Python에서 돌아가요. 큰 데이터, 이미 설치한 라이브러리, GPU를 그대로 써요.
+
+```bash
+pip install upliftlab
+upliftlab                # http://127.0.0.1:4180 이 열려요
+```
+
+uv를 쓴다면 설치 없이 `uvx upliftlab` 한 줄이면 돼요. 처음 실행할 때 Criteo 표본(2.3MB)을 한 번 내려받아 두고, 그다음부터는 그대로 써요.
+
+> [!NOTE]
+> 브라우저에서는 EconML을 쓸 수 없어서, 웹은 같은 방법을 scikit-learn으로 쓴 경량판으로 돌려요. 결과 화면과 보고서에 어느 쪽으로 돌렸는지 표시해요.
+
+## 결과 읽는 법
+
+<a href="https://uplift-lab.vercel.app"><img src="https://raw.githubusercontent.com/Funbucket/upliftlab/main/docs/images/verdict.png" alt="결과 화면. 결승선은 박빙, 기준선과는 큰 차이. Random 대비 증분 방문 +62%, 1위와의 차이와 95% CI, P1~P5와 기준선 순위 카드"></a>
+
+- **제목**이 결론이에요. 2위와의 차이가 95% CI 안이면 `결승선은 박빙`이라고 쓰고, 기준선(Random)과의 차이가 확실한지도 함께 적어요.
+- **Random 대비**는 1위가 무작위로 고를 때보다 같은 예산으로 성과를 얼마나 더 냈는지예요.
+- **1위와의 차이 · 95% CI**에서 구간이 0을 지나는 모델은 회색, 확실히 낮은 모델은 파란색이에요. 박빙이면 `사진 판정` 표시가 붙어요.
+- 그 아래에 순위표, 1위가 고른 사용자의 특성, 사이클별 지표, Row-level 로그, Cost Curve가 이어져요.
+
+## 데이터에서 보고서까지
+
+| ① 데이터 넣기 | ② 비교 시작 | ③ 보고서 공유 |
+| :-- | :-- | :-- |
+| 실험 로그 CSV를 끌어다 놓으면 처치, 결과, 비용, 공변량 열을 알아서 골라요. | 모델, 선정 방식, 예산을 확인하고 `비교 시작`을 눌러요. 끝나면 결과로 바로 내려가요. | 1위 모델, Random 대비 증분 성과, 2위와의 차이를 HTML 보고서, PDF, 메신저 요약으로 보내요. |
+
+## 기본 모델
+
+| 모델 | EconML 구현 | 하는 일 |
+| :-- | :-- | :-- |
+| T-Learner | `metalearners.TLearner` | 처치군과 대조군 모델의 예측 차이 |
+| X-Learner | `metalearners.XLearner` | 대체한 효과를 propensity로 가중 |
+| R-Learner | `dml.NonParamDML` | 잔차로 푸는 비모수 CATE |
+| DML | `dml.LinearDML` | 잔차로 푸는 선형 CATE |
+| Duality R-Learner | `dml.NonParamDML` × 2 | 성과와 비용의 CATE를 함께 보고 λ를 validation에서 골라요 |
+| Random | NumPy | 비교 기준선 |
+
+각 파일은 `class Model` 하나라서 화면에서 바로 열어 보고 고쳐 쓸 수 있어요.
+
+## 내 알고리즘 추가
+
+upliftlab을 import하지 않는 Python 파일 하나예요. scikit-learn, LightGBM, PyTorch를 평소처럼 써요.
+
+```python
+class Model:
+    def fit(self, train, validation, context):  # train.X, train.t, train.y, train.cost
+        ...
+    def predict(self, X):                        # 사용자마다 점수 하나. 높은 순서로 대상을 골라요
+        ...
+```
+
+웹에서는 `알고리즘` 화면의 `알고리즘 추가`에서 시작 틀을 골라 편집해요. 로컬에서는 화면 없이도 비교할 수 있어요.
+
+```bash
+upliftlab run --data my_experiment.csv --algorithm my_model.py
+```
+
+<details>
+<summary><b>내 데이터 형식</b> · 처치를 무작위로 배정한 실험 로그, 1,000행 이상</summary>
+<br>
+
+열 이름은 자유예요. 형식이 헷갈리면 화면의 `예시 파일 내려받기`로 받은 파일을 참고하세요.
+
+| 역할 | 예시 열 | 값 |
+| :-- | :-- | :-- |
+| 처치 | `treatment` | 0 = 대조군, 1 = 처치. 여러 종류면 1, 2, 3… |
+| 결과 | `retained` | 전환, 구매, 리텐션처럼 늘리고 싶은 값 |
+| 비용 (선택) | `coupon_cost` | 처치로 쓴 비용. 없으면 처치 1건당 1로 계산해요 |
+| 공변량 | `visit_freq`, … | 처치 **전에** 측정한 사용자 특성 |
+
+기본 데이터는 [Criteo](https://ailab.criteo.com/criteo-uplift-prediction-dataset/) 광고 실험이에요. 원본 1,398만 명에서 처치군과 대조군을 10만 명씩 뽑은 표본(199,837명, 결과는 사이트 방문)이 사이트와 패키지에 들어 있어요.
+
+</details>
+
+## 더 보기
+
+[사용 안내](https://github.com/Funbucket/upliftlab/blob/main/docs/guide.md) · 선정 방식 5가지, 명령줄 옵션, 결과 읽는 법<br>
+[알고리즘 계약](https://github.com/Funbucket/upliftlab/blob/main/engine/README.md) · `fit`과 `predict`에 들어오는 값, 코드 검사 규칙<br>
+[개발 참여](https://github.com/Funbucket/upliftlab/blob/main/CONTRIBUTING.md) · 빌드, 테스트, 폴더 구조<br>
+[변경 기록](https://github.com/Funbucket/upliftlab/blob/main/CHANGELOG.md)
+
+<sub>[MIT](https://github.com/Funbucket/upliftlab/blob/main/LICENSE). Criteo 표본은 [CC BY-NC-SA 4.0](https://github.com/Funbucket/upliftlab/blob/main/web/data/LICENSE-criteo.md)이라 비상업적으로만 쓸 수 있어요. pip 패키지에는 넣지 않고 처음 쓸 때 이 저장소에서 내려받아요. Pretendard, Archivo, Geist Mono 글꼴은 SIL Open Font License(`web/fonts/LICENSE`), 편집기 번들은 `web/vendor/LICENSES.txt`를 따라요.</sub>

upliftlab-0.26.1/engine/upliftlab/__init__.py

@@ -0,0 +1,5 @@
+"""UpliftLab engine: an explore/exploit targeting loop with pluggable algorithms.
+
+The same package runs in the browser (Pyodide) and natively (`python -m upliftlab serve`).
+"""
+__version__ = '0.26.1'

upliftlab-0.26.1/engine/upliftlab/__main__.py

@@ -0,0 +1,119 @@
+import argparse
+import json
+import sys
+from pathlib import Path
+
+parser = argparse.ArgumentParser(prog='upliftlab', description='upliftlab local edition: the same UI and engine as uplift-lab.vercel.app, on your own Python. Run it with no command to open the UI.')
+sub = parser.add_subparsers(dest='command', metavar='{serve,run,check}')
+web = sub.add_parser('serve', help='open the web UI on localhost and run the engine natively (the default)')
+web.add_argument('--host', default='127.0.0.1')
+web.add_argument('--port', type=int, default=4180)
+web.add_argument('--web', help='folder with the UI (defaults to web/ in a source checkout, else the UI inside the package)')
+web.add_argument('--no-browser', action='store_true', help='do not open the browser')
+check = sub.add_parser('check', help='list the libraries an algorithm file uses, then fit it once on synthetic data')
+check.add_argument('file', metavar='FILE.py')
+run = sub.add_parser('run', help='run a head-to-head comparison without the UI and write the result as JSON')
+run.add_argument('--data', default='public/criteo', help='public/criteo (the bundled 200k-row sample) | synthetic/base | path to a CSV')
+run.add_argument('--algorithms', default='all', help='comma-separated built-in ids, or "all"')
+run.add_argument('--algorithm', action='append', default=[], metavar='FILE.py', help='add your own algorithm file (repeatable)')
+run.add_argument('--cycles', type=int, default=8)
+run.add_argument('--explore', type=float, default=.2)
+run.add_argument('--target', type=float, default=.4)
+run.add_argument('--seed', type=int, default=42)
+run.add_argument('--mode', choices=['quantile', 'budget', 'knapsack', 'roi', 'validation'], default='budget', help='budget (default): by score until the budget runs out. quantile: the top q%%. knapsack: value - price * cost > 0, priced to the budget. roi: by value / cost while the expected efficiency meets --efficiency. validation: up to the share where uplift peaked on validation rows')
+run.add_argument('--budget', type=float, default=.4, help='budget as a share of the expected cost of treating every candidate')
+run.add_argument('--efficiency', type=float, default=.2, help='with --mode roi: required efficiency gain over random selection')
+run.add_argument('--base-learner', choices=['ridge', 'tree'], default='ridge', help='base model of the built-in algorithms')
+run.add_argument('--out', help='write the result JSON here (open it in the web UI under 실행 기록 → 결과 JSON 열기)')
+
+
+def main(argv=None):
+    args = parser.parse_args(argv)
+    if args.command is None:  # plain `upliftlab` opens the UI
+        args = parser.parse_args(['serve'])
+    if args.command == 'serve':
+        from .server import serve
+        serve(args.host, args.port, args.web, open_browser=not args.no_browser)
+    elif args.command == 'check':
+        from . import bridge
+        from .server import detect_devices
+        devices = detect_devices()
+        bridge.state.update(runtime='local', device=devices[0], devices=devices)
+        path = Path(args.file)
+        code = path.read_text(encoding='utf-8')
+        out = bridge.check(code, path.stem)
+        print(f"{path.name} · {out.get('name') or path.stem}")
+        shown = {'ok': lambda l: f"{l['package']} {l['version'] or ''}".strip(), 'missing': lambda l: f"{l['package']} (missing · pip install {l['package']})"}
+        print('libraries: ' + (' · '.join(shown.get(l['status'], shown['missing'])(l) for l in out['libraries']) or 'standard library only'))
+        if out['ok']:
+            out = bridge.try_algorithm(code, path.stem, out.get('name'))
+        if not out['ok']:
+            sys.exit(f"{path}:{out.get('line') or '?'}: {out['error']}")
+        print(f"quick check: ok · test AUCC truth {out['auccTruth']:.3f} · observed {out['aucc']:.3f} · fit {out['ms']:.0f} ms on {out['split']['train']:,} rows · device {devices[0]}")
+    else:
+        from . import bridge, datasets
+        from .server import detect_devices
+        devices = detect_devices()
+        bridge.state.update(runtime='local', device=devices[0], devices=devices)
+        builtins = {a['id']: a for a in bridge.builtins()}
+        ids = list(builtins) if args.algorithms == 'all' else [a for a in args.algorithms.split(',') if a]
+        unknown = [a for a in ids if a not in builtins]
+        if unknown:
+            sys.exit(f'unknown algorithm: {", ".join(unknown)} (choose from {", ".join(builtins)})')
+        algorithms = [{'id': a, 'name': builtins[a]['name'], 'code': builtins[a]['code']} for a in ids]
+        for file in args.algorithm:
+            code = Path(file).read_text(encoding='utf-8')
+            check = bridge.check(code, Path(file).stem)
+            if not check['ok']:
+                sys.exit(f'{file}:{check.get("line") or "?"}: {check["error"]}')
+            algorithms.append({'id': 'file-' + Path(file).stem, 'name': check.get('name') or Path(file).stem, 'code': code})
+        dataset = args.data
+        if dataset.startswith('public/'):
+            bridge.fetch_dataset(dataset)
+        elif not dataset.startswith('synthetic/'):
+            path = Path(dataset)
+            dataset = 'upload/' + path.name
+            bridge.add_dataset(dataset, path.read_text(encoding='utf-8'), path.name)
+        print(f'{dataset} · {len(algorithms)} algorithms · {args.cycles} cycles · device {devices[0]}', file=sys.stderr)
+        bridge.set_reporter(lambda m: (lambda d: d.get('phase') == 'done' and print(f"  c{d['cycle']} {d['arm']} done", file=sys.stderr))(json.loads(m)))
+        result = bridge.run_all(dataset, algorithms, args.cycles, args.explore, args.target, args.seed, args.mode, args.budget, args.base_learner, args.efficiency)
+        by = result['summary']['by']
+        measure = ('incremental' if by.lower().endswith('incr') else 'gain') + (' (truth)' if by.startswith('truth') else ' (observed)')
+        volume = by.lower().endswith('incr')  # ranked by incremental outcome: the band is the gap to first place, as on the screen
+        print(f"\n{'rank':<5}{'algorithm':<26}{measure:>22}{'vs 1st, 95% CI' if volume else 'observed 95% CI':>30}{'AUCC':>8}{'Qini':>8}{'fit ms':>9}")
+        for s in sorted(result['summary']['arms'], key=lambda s: s['rank']):
+            g, ci, auc, ms = s[by], s['ci'], s['aucc'], s['trainMs']
+            gain = '—' if g is None else f'{g:,.0f}' if volume else f'{g:+.1%}'
+            q = '—' if s['qini'] is None else f"{s['qini']:.3f}"
+            gap = s.get('vsLeader') or {}
+            if volume:
+                band = '1st' if s['rank'] == 1 else '—' if gap.get('diff') is None or gap.get('ci', [None])[0] is None else f"{gap['diff']:+,.0f} [{gap['ci'][0]:+,.0f}, {gap['ci'][1]:+,.0f}]"
+            else:
+                band = '—' if ci[0] is None else f'[{ci[0]:+.1%}, {ci[1]:+.1%}]'
+            auc = '—' if auc is None else f'{auc:.3f}'
+            ms = '—' if ms is None else f'{ms:.0f}'
+            print(f"{s['rank']:<5}{s['name'][:25]:<26}{gain:>22}{band:>30}{auc:>8}{q:>8}{ms:>9}")
+        print('\n' + conclusion(result, args.mode))
+        if args.out:
+            Path(args.out).write_text(json.dumps({'format': 'upliftlab.run/1', **result}, ensure_ascii=False))
+            print(f'\nwrote {args.out}', file=sys.stderr)
+
+
+def conclusion(result, mode):
+    """One line under the table: who won, by how much over Random, on which basis."""
+    arms, by = result['summary']['arms'], result['summary']['by']
+    lead = min(arms, key=lambda s: s['rank'])
+    random = next((s for s in arms if s['arm'] == 'random_baseline' and s is not lead), None)
+    basis = 'true effect, known for synthetic data' if by.startswith('truth') else 'observed: treated minus control'
+    if lead.get(by) is None:
+        return f"{lead['name']} ranks first ({basis})."
+    if by.lower().endswith('incr'):
+        line = f"{lead['name']} ranks first with {lead[by]:,.0f} incremental outcome"
+        if random and random.get(by):
+            line += f", {lead[by] - random[by]:+,.0f} ({lead[by] / random[by] - 1:+.0%}) over Random"
+        return line + (' for the same budget' if mode in ('budget', 'knapsack') else '') + f' ({basis}).'
+    return f"{lead['name']} ranks first with {lead[by]:+.1%} cost efficiency over random selection ({basis})."
+
+
+if __name__ == '__main__':
+    main()

upliftlab-0.26.1/engine/upliftlab/algorithms/__init__.py

@@ -0,0 +1,6 @@
+"""Built-in algorithms. Each file is a self-contained `class Model` that imports common libraries, never upliftlab.
+
+The files here use EconML (PyWhy) and run in the local edition. The browser has no EconML, so the web runs the files in
+lite/: the same methods written with scikit-learn only. Random has no lite version because it needs neither.
+The screen shows and runs these exact files."""
+ORDER = ['random_baseline', 'x_learner', 't_learner', 'r_learner', 'dml', 'duality_r_learner']

upliftlab-0.26.1/engine/upliftlab/algorithms/dml.py

@@ -0,0 +1,35 @@
+"""Y와 T의 잔차를 cross-fitting으로 구하고, 그 관계로 CATE를 추정해요(Double Machine Learning). 비용은 보지 않아요.
+
+EconML의 LinearDML이에요. ỹ = y − m̂(x), t̃ = t − ê(x)를 3-fold cross-fitting으로 구하고 τ̂(x) = θ₀ + θ'x를 ỹ ≈ t̃·τ(x)로 맞춰요.
+R-Learner와 달리 마지막 단계가 선형이라 해석하기 쉽고, 처치가 공변량에 따라 달라지는 로그에서도 ê(x)로 보정해요.
+"""
+import numpy as np
+from sklearn.ensemble import HistGradientBoostingClassifier, HistGradientBoostingRegressor
+from sklearn.linear_model import LogisticRegression, Ridge
+from sklearn.pipeline import make_pipeline
+from sklearn.preprocessing import StandardScaler
+from econml.dml import LinearDML
+
+NAME = 'DML'
+
+
+def regressor(kind):
+    if kind == 'tree':
+        return HistGradientBoostingRegressor(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return make_pipeline(StandardScaler(), Ridge(alpha=1.0))
+
+
+def classifier(kind):
+    if kind == 'tree':
+        return HistGradientBoostingClassifier(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return make_pipeline(StandardScaler(), LogisticRegression(max_iter=1000))
+
+
+class Model:
+    def fit(self, train, validation, context):
+        kind = getattr(context, 'base_learner', 'ridge')
+        self.est = LinearDML(model_y=regressor(kind), model_t=classifier(kind), discrete_treatment=True, cv=3, random_state=context.model_seed)
+        self.est.fit(train.y, train.t, X=train.X)
+
+    def predict(self, X):
+        return np.asarray(self.est.const_marginal_effect(X)).reshape(len(X), -1)

upliftlab-0.26.1/engine/upliftlab/algorithms/duality_r_learner.py

@@ -0,0 +1,86 @@
+"""성과와 비용의 CATE를 R-Learner로 학습하고 τ̂ʳ − λ·τ̂ᶜ 순으로 정렬해요. λ는 validation AUCC가 가장 높은 값으로 정해요.
+
+τ̂ʳ, τ̂ᶜ는 y / σ_y, cost / σ_c의 CATE이고, EconML의 NonParamDML(R-Learner)로 학습해요.
+σ_y, σ_c는 train의 표준편차예요. 정규화하므로 성과와 비용의 단위가 바뀌어도 순위가 같아요.
+"""
+import numpy as np
+from sklearn.ensemble import HistGradientBoostingClassifier, HistGradientBoostingRegressor
+from sklearn.linear_model import LogisticRegression, Ridge
+from sklearn.pipeline import make_pipeline
+from sklearn.preprocessing import StandardScaler
+from econml.dml import NonParamDML
+
+NAME = 'Duality R-Learner'
+LAMBDAS = [0, 0.05, 0.1, 0.2, 0.4, 0.8, 1.6]  # 정규화한 성과와 비용 사이의 가중치
+
+
+def regressor(kind):
+    if kind == 'tree':
+        return HistGradientBoostingRegressor(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return make_pipeline(StandardScaler(), Ridge(alpha=1.0))
+
+
+def classifier(kind):
+    if kind == 'tree':
+        return HistGradientBoostingClassifier(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return make_pipeline(StandardScaler(), LogisticRegression(max_iter=1000))
+
+
+def final(kind):
+    """마지막 단계 회귀. EconML이 sample_weight를 넘기므로 파이프라인이 아닌 모델을 써요."""
+    if kind == 'tree':
+        return HistGradientBoostingRegressor(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return Ridge(alpha=1.0)
+
+
+def r_learner(X, t, y, seed, kind):
+    est = NonParamDML(model_y=regressor(kind), model_t=classifier(kind), model_final=final(kind), discrete_treatment=True, cv=2, random_state=seed)
+    return est.fit(y, t, X=X)
+
+
+def aucc(score, t, y, cost, points=20):
+    """점수 순으로 상위 S를 골랐을 때 (증분 비용, 증분 성과) 곡선 아래 넓이를 0–1로 맞춘 값. 무작위 순서 ≈ 0.5."""
+    order = np.argsort(-score, kind='stable')
+    cut = np.round(np.arange(1, points + 1) * len(order) / points).astype(int) - 1
+    T = (t[order] > 0).astype(float)
+    nT, nC = np.cumsum(T)[cut], np.cumsum(1 - T)[cut]
+    ok = (nT > 0) & (nC > 0)
+
+    def lift(v):
+        with np.errstate(divide='ignore', invalid='ignore'):
+            return np.where(ok, nT * (np.cumsum(v[order] * T)[cut] / nT - np.cumsum(v[order] * (1 - T))[cut] / nC), 0.)
+    gain, spend = np.r_[0., lift(y)], np.r_[0., lift(cost)]
+    if gain.max() <= 0 or spend.max() <= 0:
+        return None
+    x, h = spend / spend.max(), gain / gain.max()
+    return float(np.sum(np.diff(x) * (h[1:] + h[:-1]) / 2))
+
+
+class Model:
+    score_is_effect = False  # 점수에 비용이 이미 들어 있어서 효과로 읽지 않아요. Knapsack과 효율 제약 선정에서 이 순서를 그대로 써요.
+
+    def fit(self, train, validation, context):
+        kind = getattr(context, 'base_learner', 'ridge')
+        y, cost = train.y / (train.y.std() or 1), train.cost / (train.cost.std() or 1)
+        self.arms = []
+        for arm in range(1, train.treatments + 1):
+            rows = (train.t == arm) | (train.t == 0)
+            t = (train.t[rows] == arm).astype(int)
+            self.arms.append((r_learner(train.X[rows], t, y[rows], context.model_seed, kind), r_learner(train.X[rows], t, cost[rows], context.model_seed, kind)))
+        best = None
+        for i, lam in enumerate(LAMBDAS):
+            values = []
+            for arm, (gain, spend) in enumerate(self.arms, 1):
+                rows = (validation.t == arm) | (validation.t == 0)
+                X = validation.X[rows]
+                score = np.ravel(gain.const_marginal_effect(X)) - lam * np.ravel(spend.const_marginal_effect(X))
+                values.append(aucc(score, validation.t[rows], validation.y[rows], validation.cost[rows]))
+            values = [v for v in values if v is not None]
+            val = float(np.mean(values)) if values else None
+            context.report(step=i + 1, total=len(LAMBDAS), lam=lam, val=val if val is not None else 0)
+            if best is None or (val is not None and (best[0] is None or val > best[0])):
+                best = (val, lam)
+        self.lam = best[1]
+
+    def predict(self, X):
+        return np.column_stack([np.ravel(gain.const_marginal_effect(X)) - self.lam * np.ravel(spend.const_marginal_effect(X)) for gain, spend in self.arms])

upliftlab-0.26.1/engine/upliftlab/algorithms/lite/dml.py

@@ -0,0 +1,53 @@
+"""Y와 T의 잔차를 cross-fitting으로 구하고, 그 관계로 CATE를 추정해요(Double Machine Learning). 비용은 보지 않아요.
+
+경량판: 브라우저에는 EconML이 없어서 웹에서는 같은 방법을 scikit-learn으로 직접 구현한 이 파일을 실행해요.
+로컬(upliftlab)에서는 EconML로 쓴 upliftlab/algorithms/dml.py를 실행해요.
+
+ỹ = y − m̂(x)        t̃ = t − ê(x)        τ̂(x) = θ₀ + θ'x        θ = argmin Σ (ỹ − t̃·τ(x))²
+m̂와 ê는 3-fold cross-fitting으로 구해요. 모델은 context.base_learner에 따라 Ridge·로지스틱 회귀 또는 Gradient Boosting이에요(scikit-learn).
+R-Learner와 달리 propensity ê(x)도 추정해서, 처치가 공변량에 따라 달라지는 로그에서도 쓸 수 있어요.
+무작위 배정 데이터에서는 ê(x)가 상수에 가까워 R-Learner와 비슷한 결과가 나와요.
+"""
+import numpy as np
+from sklearn.ensemble import HistGradientBoostingClassifier, HistGradientBoostingRegressor
+from sklearn.linear_model import LogisticRegression, Ridge
+from sklearn.model_selection import KFold, cross_val_predict
+from sklearn.pipeline import make_pipeline
+from sklearn.preprocessing import StandardScaler
+
+NAME = 'DML'
+FOLDS = 3
+
+
+def outcome_model(kind):
+    if kind == 'tree':
+        return HistGradientBoostingRegressor(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return make_pipeline(StandardScaler(), Ridge(alpha=1.0))
+
+
+def treatment_model(kind):
+    if kind == 'tree':
+        return HistGradientBoostingClassifier(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return make_pipeline(StandardScaler(), LogisticRegression(max_iter=1000))
+
+
+def design(scaler, X):
+    return np.column_stack([np.ones(len(X)), scaler.transform(X)])
+
+
+class Model:
+    def fit(self, train, validation, context):
+        kind = getattr(context, 'base_learner', 'ridge')
+        self.scaler = StandardScaler().fit(train.X)
+        self.finals = []
+        for arm in range(1, train.treatments + 1):
+            rows = (train.t == arm) | (train.t == 0)
+            X, y, t = train.X[rows], train.y[rows], (train.t[rows] == arm).astype(int)
+            folds = KFold(FOLDS, shuffle=True, random_state=context.model_seed)
+            y_res = y - cross_val_predict(outcome_model(kind), X, y, cv=folds)
+            t_res = t - np.clip(cross_val_predict(treatment_model(kind), X, t, cv=folds, method='predict_proba')[:, 1], .01, .99)
+            self.finals.append(Ridge(alpha=1.0, fit_intercept=False).fit(design(self.scaler, X) * t_res[:, None], y_res))
+
+    def predict(self, X):
+        Z = design(self.scaler, X)
+        return np.column_stack([final.predict(Z) for final in self.finals])