uplift-model-sample-homogeneity-check

Name: uplift-model-sample-homogeneity-check
Author: QFIN-tech

40stars16forks

How to install uplift-model-sample-homogeneity-check?

qfin-tech/model-evo/uplift-model-sample-homogeneity-check

$npx -y skills add QFIN-tech/model-evo --skill uplift-model-sample-homogeneity-check

Installs into the current project.

Summary

当用户想对两组数据做同质性检验时使用，例如“我想判断这两组数据是否同质/可比”；也可以在样本准备产出 confirmed modeling_sample_spec_path 后使用：起草、确认并运行 treatment/control 协变量均衡性诊断。不要用于样本切分、特征选择、模型训练、调参、模型比较或最终报告。

Files · 1

View on GitHub

SKILL.md

1	# 样本同质性检查
2
3	## 1. 输入依赖
4
5	本 skill 在 `uplift-model-sample-preparation` 已产出 `modeling_sample_spec_path` 后使用，用来检查 treatment/control 两组在已确认干预前协变量上的可比性。
6
7	流程：
8
9	```text
10	plan_covariates
11	-> confirm homogeneity_covariate_plan
12	-> run_diagnostics
13	-> homogeneity report/result artifacts
14	```
15
16	## 2. 执行入口
17
18	使用统一 runner：
19
20	```bash
21	python <skill-dir>/scripts/run.py --input - --output-dir <output_dir>
22	```
23
24	Windows 环境可按需将路径分隔符改为反斜杠。
25
26	`--output-dir` 必须是已存在的 `run_dir`；runner 不创建 run_dir，不扫描 `latest/current`。本 skill 输出到：
27
28	```text
29	{run_dir}/uplift-model-sample-homogeneity-check/{timestamp}_homogeneity_check/
30	inputs/0001_<action>.request.json
31	results/0001_<action>.result.json
32	artifacts/
33	_flow_manifest.json
34	_flow_log.jsonl
35	report.md
36	```
37
38	所有 stdout、result、manifest 和 log 中的持久化 path 都是 `run_dir` 相对路径。`plan_covariates` 创建 flow；后续 action 必须显式传入上一步 `outputs.flow_dir`，不得从 artifact path 反推 flow。
39
40	request JSON 必须通过 UTF-8 stdin 传入：
41
42	```json
43	{"action": "plan_covariates", "payload": {"modeling_sample_spec_path": "..."}}
44	```
45
46	stdout 和落盘 result JSON 都使用共同返回 shape：
47
48	```text
49	status, summary, outputs, issues, next_steps
50	```
51
52	只从 `outputs.result_path` 读取当前 action 的 result JSON。存在报告时读取 `outputs.report_path`。复用同一个 flow 时读取 `outputs.flow_dir` 后作为下一次请求的 `flow_dir` 输入。不要读取或传播顶层 `flow_dir`、`result_path`、`warnings`。
53
54	旧输入字段如果以 `_ref` 或 `_refs` 结尾，runner 会返回 `needs_input`，并在 `issues` / `next_steps` 中给出对应 `_path` 或 `_paths` 替代字段。
55
56	如果缺少 Python 包，runner 返回 `status=failed`、`code=PYTHON_IMPORT_ERROR` issue，并在 issue/next_steps 中提示阅读本 skill 的缺依赖处理说明，不返回 skill 安装目录文件路径。
57
58	## 3. Actions 与参数说明
59
60	### plan_covariates
61
62	必填 payload：
63
64	```json
65	{
66	"modeling_sample_spec_path": "<confirmed modeling_sample_spec artifact>"
67	}
68	```
69
70	可选 payload：
71
72	```json
73	{
74	"user_covariates": ["age", "tenure", "region"],
75	"max_categorical_levels": 10,
76	"prior_plan_path": null
77	}
78	```
79
80	如果省略 `user_covariates`，runner 会从启用的 split 数据集中推荐干预前候选协变量。
81
82	输出：
83
84	```text
85	outputs.homogeneity_covariate_plan_path
86	```
87
88	该 action 写入 `artifacts/homogeneity_covariate_plan.draft.v1.json`，并返回 `needs_confirmation`。
89
90	### confirm_artifact
91
92	必填 payload：
93
94	```json
95	{
96	"source_draft_path": "<draft homogeneity_covariate_plan path>",
97	"artifact_kind": "homogeneity_covariate_plan",
98	"confirmed_by": "user"
99	}
100	```
101
102	该 action 会基于启用的 split 数据集校验被选协变量，然后写入：
103
104	```text
105	artifacts/homogeneity_covariate_plan.confirmed.v1.json
106	```
107
108	输出：
109
110	```text
111	outputs.homogeneity_covariate_plan_path
112	```
113
114	### run_diagnostics
115
116	必填 payload：
117
118	```json
119	{
120	"modeling_sample_spec_path": "<confirmed modeling_sample_spec artifact>",
121	"homogeneity_covariate_plan_path": "<confirmed covariate plan artifact>"
122	}
123	```
124
125	可选 payload：
126
127	```json
128	{
129	"diagnostic_config_overrides": {}
130	}
131	```
132
133	该 action 计算 split 级 treatment predictability AUC 和 SMD 诊断。严重或关键均衡性风险不代表 runner 失败，而是表示继续下游前需要用户明确接受风险。
134
135	输出：
136
137	```text
138	outputs.sample_homogeneity_result_path
139	outputs.report_path
140	outputs.covariates_path
141	outputs.smd_detail_path
142	outputs.auc_feature_importance_path
143	outputs.diagnostic_config_path
144	```
145
146	产物：
147
148	```text
149	artifacts/covariates.v1.csv
150	artifacts/smd_detail.v1.csv
151	artifacts/auc_feature_importance.v1.csv
152	artifacts/diagnostic_config.json
153	report.md
154	```
155
156	## 4. 输出产物
157
158	典型输出目录：
159
160	```text
161	{run_dir}/uplift-model-sample-homogeneity-check/{timestamp}_homogeneity_check/
162	inputs/0001_<action>.request.json
163	results/0001_<action>.result.json
164	artifacts/
165	homogeneity_covariate_plan.draft.v1.json
166	homogeneity_covariate_plan.confirmed.v1.json
167	covariates.v1.csv
168	smd_detail.v1.csv
169	auc_feature_importance.v1.csv
170	diagnostic_config.json
171	_flow_manifest.json
172	_flow_log.jsonl
173	report.md
174	```
175
176	关键下游路径：
177
178	- `outputs.homogeneity_covariate_plan_path`
179	- `outputs.sample_homogeneity_result_path`
180	- `outputs.report_path`
181	- `outputs.covariates_path`
182	- `outputs.smd_detail_path`
183	- `outputs.auc_feature_importance_path`
184	- `outputs.diagnostic_config_path`
185
186	## 5. 与其他 skill 的关联
187
188	\| 方向 \| Skill \| 关系 \|
189	\|---\|---\|---\|
190	\| 上游 \| `uplift-model-sample-preparation` \| 提供 confirmed `modeling_sample_spec_path` \|
191	\| 下游 \| `uplift-model-feature-quality-analysis` \| 消费 `sample_homogeneity_result_path`；如跳过同质性检查，必须由用户明确接受风险 \|
192
193	## 6. 执行约束
194
195	本 skill 只负责起草、确认并运行 treatment/control 协变量均衡性诊断，不做样本切分、特征选择、模型训练、调参、模型比较或最终报告。
196
197	所有 split 数据集读取必须经过 `_common.data_loader`，其实现位于 `model-skills/_uplift-common/scripts/_common/data_loader.py`，并与 `uplift-model-sample-preparation` 使用同一公共实现。Gate 1 支持 `local_csv`；`local_parquet` 仅预留 kind，并返回明确 unsupported 结果，不做 fallback。
198
199	- `plan_covariates` 返回 `needs_confirmation` 时，必须请用户确认或修改协变量计划，不能直接运行诊断。
200	- `run_diagnostics` 如果发现 severe 或 critical 级别均衡性风险，必须明确询问用户是否接受该风险后再进入特征或建模链路。
201	- 只有拿到 `outputs.sample_homogeneity_result_path` 且用户已处理必要风险确认后，才建议继续后续 skill。
202
203	## 7. 异常处理
204
205	### 7.1 缺依赖处理
206
207	如果缺少 Python 包，runner 返回 `status=failed`、`code=PYTHON_IMPORT_ERROR` issue，并在 issue/next_steps 中提示阅读本 skill 的缺依赖处理说明，不返回 sk

People who liked this also viewed

6 picks

Type

uplift-model-sample-homogeneity-check

40stars16forks

View on GitHub

How to install uplift-model-sample-homogeneity-check?

qfin-tech/model-evo/uplift-model-sample-homogeneity-check

$npx -y skills add QFIN-tech/model-evo --skill uplift-model-sample-homogeneity-check

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# 样本同质性检查
2
3	## 1. 输入依赖
4
5	本 skill 在 `uplift-model-sample-preparation` 已产出 `modeling_sample_spec_path` 后使用，用来检查 treatment/control 两组在已确认干预前协变量上的可比性。
6
7	流程：
8
9	```text
10	plan_covariates
11	-> confirm homogeneity_covariate_plan
12	-> run_diagnostics
13	-> homogeneity report/result artifacts
14	```
15
16	## 2. 执行入口
17
18	使用统一 runner：
19
20	```bash
21	python <skill-dir>/scripts/run.py --input - --output-dir <output_dir>
22	```
23
24	Windows 环境可按需将路径分隔符改为反斜杠。
25
26	`--output-dir` 必须是已存在的 `run_dir`；runner 不创建 run_dir，不扫描 `latest/current`。本 skill 输出到：
27
28	```text
29	{run_dir}/uplift-model-sample-homogeneity-check/{timestamp}_homogeneity_check/
30	inputs/0001_<action>.request.json
31	results/0001_<action>.result.json
32	artifacts/
33	_flow_manifest.json
34	_flow_log.jsonl
35	report.md
36	```
37
38	所有 stdout、result、manifest 和 log 中的持久化 path 都是 `run_dir` 相对路径。`plan_covariates` 创建 flow；后续 action 必须显式传入上一步 `outputs.flow_dir`，不得从 artifact path 反推 flow。
39
40	request JSON 必须通过 UTF-8 stdin 传入：
41
42	```json
43	{"action": "plan_covariates", "payload": {"modeling_sample_spec_path": "..."}}
44	```
45
46	stdout 和落盘 result JSON 都使用共同返回 shape：
47
48	```text
49	status, summary, outputs, issues, next_steps
50	```
51
52	只从 `outputs.result_path` 读取当前 action 的 result JSON。存在报告时读取 `outputs.report_path`。复用同一个 flow 时读取 `outputs.flow_dir` 后作为下一次请求的 `flow_dir` 输入。不要读取或传播顶层 `flow_dir`、`result_path`、`warnings`。
53
54	旧输入字段如果以 `_ref` 或 `_refs` 结尾，runner 会返回 `needs_input`，并在 `issues` / `next_steps` 中给出对应 `_path` 或 `_paths` 替代字段。
55
56	如果缺少 Python 包，runner 返回 `status=failed`、`code=PYTHON_IMPORT_ERROR` issue，并在 issue/next_steps 中提示阅读本 skill 的缺依赖处理说明，不返回 skill 安装目录文件路径。
57
58	## 3. Actions 与参数说明
59
60	### plan_covariates
61
62	必填 payload：
63
64	```json
65	{
66	"modeling_sample_spec_path": "<confirmed modeling_sample_spec artifact>"
67	}
68	```
69
70	可选 payload：
71
72	```json
73	{
74	"user_covariates": ["age", "tenure", "region"],
75	"max_categorical_levels": 10,
76	"prior_plan_path": null
77	}
78	```
79
80	如果省略 `user_covariates`，runner 会从启用的 split 数据集中推荐干预前候选协变量。
81
82	输出：
83
84	```text
85	outputs.homogeneity_covariate_plan_path
86	```
87
88	该 action 写入 `artifacts/homogeneity_covariate_plan.draft.v1.json`，并返回 `needs_confirmation`。
89
90	### confirm_artifact
91
92	必填 payload：
93
94	```json
95	{
96	"source_draft_path": "<draft homogeneity_covariate_plan path>",
97	"artifact_kind": "homogeneity_covariate_plan",
98	"confirmed_by": "user"
99	}
100	```
101
102	该 action 会基于启用的 split 数据集校验被选协变量，然后写入：
103
104	```text
105	artifacts/homogeneity_covariate_plan.confirmed.v1.json
106	```
107
108	输出：
109
110	```text
111	outputs.homogeneity_covariate_plan_path
112	```
113
114	### run_diagnostics
115
116	必填 payload：
117
118	```json
119	{
120	"modeling_sample_spec_path": "<confirmed modeling_sample_spec artifact>",
121	"homogeneity_covariate_plan_path": "<confirmed covariate plan artifact>"
122	}
123	```
124
125	可选 payload：
126
127	```json
128	{
129	"diagnostic_config_overrides": {}
130	}
131	```
132
133	该 action 计算 split 级 treatment predictability AUC 和 SMD 诊断。严重或关键均衡性风险不代表 runner 失败，而是表示继续下游前需要用户明确接受风险。
134
135	输出：
136
137	```text
138	outputs.sample_homogeneity_result_path
139	outputs.report_path
140	outputs.covariates_path
141	outputs.smd_detail_path
142	outputs.auc_feature_importance_path
143	outputs.diagnostic_config_path
144	```
145
146	产物：
147
148	```text
149	artifacts/covariates.v1.csv
150	artifacts/smd_detail.v1.csv
151	artifacts/auc_feature_importance.v1.csv
152	artifacts/diagnostic_config.json
153	report.md
154	```
155
156	## 4. 输出产物
157
158	典型输出目录：
159
160	```text
161	{run_dir}/uplift-model-sample-homogeneity-check/{timestamp}_homogeneity_check/
162	inputs/0001_<action>.request.json
163	results/0001_<action>.result.json
164	artifacts/
165	homogeneity_covariate_plan.draft.v1.json
166	homogeneity_covariate_plan.confirmed.v1.json
167	covariates.v1.csv
168	smd_detail.v1.csv
169	auc_feature_importance.v1.csv
170	diagnostic_config.json
171	_flow_manifest.json
172	_flow_log.jsonl
173	report.md
174	```
175
176	关键下游路径：
177
178	- `outputs.homogeneity_covariate_plan_path`
179	- `outputs.sample_homogeneity_result_path`
180	- `outputs.report_path`
181	- `outputs.covariates_path`
182	- `outputs.smd_detail_path`
183	- `outputs.auc_feature_importance_path`
184	- `outputs.diagnostic_config_path`
185
186	## 5. 与其他 skill 的关联
187
188	\| 方向 \| Skill \| 关系 \|
189	\|---\|---\|---\|
190	\| 上游 \| `uplift-model-sample-preparation` \| 提供 confirmed `modeling_sample_spec_path` \|
191	\| 下游 \| `uplift-model-feature-quality-analysis` \| 消费 `sample_homogeneity_result_path`；如跳过同质性检查，必须由用户明确接受风险 \|
192
193	## 6. 执行约束
194
195	本 skill 只负责起草、确认并运行 treatment/control 协变量均衡性诊断，不做样本切分、特征选择、模型训练、调参、模型比较或最终报告。
196
197	所有 split 数据集读取必须经过 `_common.data_loader`，其实现位于 `model-skills/_uplift-common/scripts/_common/data_loader.py`，并与 `uplift-model-sample-preparation` 使用同一公共实现。Gate 1 支持 `local_csv`；`local_parquet` 仅预留 kind，并返回明确 unsupported 结果，不做 fallback。
198
199	- `plan_covariates` 返回 `needs_confirmation` 时，必须请用户确认或修改协变量计划，不能直接运行诊断。
200	- `run_diagnostics` 如果发现 severe 或 critical 级别均衡性风险，必须明确询问用户是否接受该风险后再进入特征或建模链路。
201	- 只有拿到 `outputs.sample_homogeneity_result_path` 且用户已处理必要风险确认后，才建议继续后续 skill。
202
203	## 7. 异常处理
204
205	### 7.1 缺依赖处理
206
207	如果缺少 Python 包，runner 返回 `status=failed`、`code=PYTHON_IMPORT_ERROR` issue，并在 issue/next_steps 中提示阅读本 skill 的缺依赖处理说明，不返回 sk

People who liked this also viewed

6 picks

Type