uplift-model-t-learner-modeling

Name: uplift-model-t-learner-modeling
Author: QFIN-tech

40stars16forks

How to install uplift-model-t-learner-modeling?

qfin-tech/model-evo/uplift-model-t-learner-modeling

$npx -y skills add QFIN-tech/model-evo --skill uplift-model-t-learner-modeling

Installs into the current project.

Summary

已有 confirmed task_config_path、modeling_sample_spec_path 和 feature_plan_path 后，用于训练 baseline T-Learner 模型并输出模型元数据、评估指标、打分表、uplift 分箱、分 component 特征重要性和报告。不要用于特征诊断、调参、模型比较或最终报告生成。

Files · 1

View on GitHub

SKILL.md

1	# T-Learner 基线建模
2
3	## 1. 输入依赖
4
5	本 skill 只负责 baseline T-Learner 训练和评估：
6
7	- 读取已确认的 `task_config_path`、`modeling_sample_spec_path` 和 `feature_plan_path`。
8	- 只使用 `feature_plan_path` 中已确认的业务特征训练模型。
9	- treatment column 只用于拆分 treatment/control arm，不进入模型特征。
10	- 在完整 train split 的 `selected_features` 上 fit 一套共享 encoder，两个子模型共用同一 encoded feature space。
11	- binary outcome 使用两个 `LGBMClassifier`，continuous outcome 使用两个 `LGBMRegressor`。
12	- 输出模型候选、模型元数据、评估指标、打分表、uplift 分箱、分 component 特征重要性和报告。
13
14	已有 confirmed `task_config_path`、`modeling_sample_spec_path` 和 `feature_plan_path` 后使用。
15
16	## 2. 执行入口
17
18	统一 CLI：
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`。`train` 必须显式提供 `experiment_id`，格式为 `exp-001-name` 这类 `^exp-[0-9]{3}-[A-Za-z0-9][A-Za-z0-9_-]{0,63}$`。目标 experiment 已存在时返回 `needs_input / EXPERIMENT_ALREADY_EXISTS`，不覆盖、不恢复。
27
28	请求 JSON 必须通过 stdin 传入：
29
30	```json
31	{"action": "train", "payload": {"experiment_id": "exp-001-t_learner", "task_config_path": "...", "modeling_sample_spec_path": "...", "feature_plan_path": "..."}}
32	```
33
34	runner stdout 是 JSON object。调用方只读取 stdout 或 result JSON 中的 `outputs.*` 字段，例如 `outputs.modeling_result_path`、`outputs.model_candidate_path`、`outputs.report_path`。
35
36	只接受显式 `_path` / `_paths` 字段。收到旧的 `_ref` / `_refs` 输入时，runner 返回 `needs_input`，并在 `issues` 与 `next_steps` 中给出对应替代字段。
37
38	## 3. Actions 与参数说明
39
40	`train`
41
42	- 输入：`experiment_id`、`task_config_path`、`modeling_sample_spec_path`、`feature_plan_path`。
43	- 可选输入：`parameter_mode`、`parameter_overrides`。
44	- 输出：
45	- `experiment_id`
46	- `experiment_dir`
47	- `modeling_result_path`
48	- `model_candidate_path`
49	- `model_metadata_path`
50	- `evaluation_metrics_path`
51	- `score_frame_path`
52	- `uplift_bins_path`
53	- `feature_importance_path`
54	- `model_artifact_path`
55	- `report_path`
56	- `learner`
57	- `modeling_metrics`
58	- `split_evaluations`
59
60	`parameter_mode` 支持：
61
62	- `recommended_defaults`
63	- `user_overrides`
64
65	`parameter_overrides` 只允许 LightGBM 训练参数，例如 `n_estimators`、`learning_rate`、`num_leaves`、`max_depth`、`min_child_samples`、`random_state`、`n_jobs`。
66
67	## 4. 输出产物
68
69	典型输出目录：
70
71	```text
72	{run_dir}/new-models/{experiment_id}/
73	inputs/0001_train.request.json
74	results/0001_train.result.json
75	artifacts/
76	t_learner_model.v1.joblib
77	t_learner_treatment_model.v1.txt
78	t_learner_control_model.v1.txt
79	model_candidate.v1.json
80	model_metadata.v1.json
81	evaluation_metrics.v1.json
82	score_frame.v1.csv
83	uplift_bins.v1.csv
84	feature_importance.v1.csv
85	_experiment_manifest.json
86	_experiment_log.jsonl
87	report.md
88	```
89
90	所有 stdout、result、manifest 和 log 中的持久化 path 都是 `run_dir` 相对路径。`candidate_id` 使用 `experiment_id`。下游比较优先通过 `experiment_ids` 进入 `uplift-model-result-comparison` 的 `draft_comparison_plan`。
91
92	`score_frame.v1.csv` 使用 `treatment_prediction`、`control_prediction` 和 `uplift_score` 表达两个潜在 outcome 预测差值。
93
94	`feature_importance.v1.csv` 是单文件，包含 `component` 字段；`component` 取值为 `treatment_outcome` 或 `control_outcome`。
95
96	`outputs.split_evaluations` 使用和 `uplift-model-tuning` winner 一致的结构，按 split 暴露 `population_fingerprint`、`metric_name`、`metric_value`、`metric_method`、`metric_version`、`auuc_version` 和 `support`。`auuc_version` 固定标记 `{"package": "scikit-uplift", "version": "0.5.1"}`。
97
98	## 5. 与其他 skill 的关联
99
100	\| 方向 \| Skill \| 关系 \|
101	\|---\|---\|---\|
102	\| 上游 \| `uplift-model-feature-quality-analysis` \| 提供 confirmed `feature_plan_path` \|
103	\| 上游 \| `uplift-model-sample-preparation` \| 提供 confirmed `modeling_sample_spec_path` \|
104	\| 下游 \| `uplift-model-tuning` \| 消费 successful T-Learner `modeling_result_path` 生成调参 study \|
105	\| 下游 \| `uplift-model-result-comparison` \| 消费 `experiment_ids` 或 `modeling_result_path` 参与模型比较 \|
106
107	## 6. 执行约束
108
109	本 skill 不选择特征，不调参，不比较多个模型，不生成最终业务报告。
110
111	### 样本支持与风险
112
113	- train split 缺 treatment 或 control arm 时返回 `needs_input`，`issues[].code = "INSUFFICIENT_TRAIN_ARM_SUPPORT"`。
114	- binary outcome 下，train split 任一 arm 只有单一 outcome class 时返回 `needs_input`，`issues[].code = "SINGLE_CLASS_TRAIN_ARM"`。
115	- evaluation split 缺 treatment 或 control arm 时训练仍可成功，但该 split 的 `metric_value` 为 `null`，并记录 `issues[].code = "INSUFFICIENT_EVALUATION_ARM_SUPPORT"`。
116	- T-Learner 依赖 treatment/control 两个 arm 的可比性；如果上游样本选择或 treatment assignment 存在偏差，uplift 排序应保守解读。
117
118	### 模型文件安全
119
120	`t_learner_model.v1.joblib` 只能从可信来源加载。不要加载来源不明或被外部修改过的 joblib 模型文件。
121
122	## 7. 异常处理
123
124	### 7.1 缺依赖处理
125
126	本 skill 需要 `pandas`、`numpy`、`joblib`、`lightgbm` 和 `scikit-uplift==0.5.1`。runner 不安装依赖。缺包时返回结构化失败，并在 issue/next_steps 中提示阅读本 skill 的缺依赖处理说明，不返回 skill 安装目录文件路径。
127
128	AUUC 由 `sklift.metrics.uplift_auc_score` 和 `sklift.metrics.uplift_curve` 计算。
129
130	### 7.2 字段兼容与 experiment 异常
131
132	只接受显式 `_path` / `_paths` 字段。收到旧的 `_ref` / `_refs` 输入时，runner 返回 `needs_input`，并在 `issues` 与 `next_steps` 中给出对应替代字段。
133
134	目标 experiment 已存在时返回 `needs

People who liked this also viewed

6 picks

Type

uplift-model-t-learner-modeling

40stars16forks

View on GitHub

How to install uplift-model-t-learner-modeling?

qfin-tech/model-evo/uplift-model-t-learner-modeling

$npx -y skills add QFIN-tech/model-evo --skill uplift-model-t-learner-modeling

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# T-Learner 基线建模
2
3	## 1. 输入依赖
4
5	本 skill 只负责 baseline T-Learner 训练和评估：
6
7	- 读取已确认的 `task_config_path`、`modeling_sample_spec_path` 和 `feature_plan_path`。
8	- 只使用 `feature_plan_path` 中已确认的业务特征训练模型。
9	- treatment column 只用于拆分 treatment/control arm，不进入模型特征。
10	- 在完整 train split 的 `selected_features` 上 fit 一套共享 encoder，两个子模型共用同一 encoded feature space。
11	- binary outcome 使用两个 `LGBMClassifier`，continuous outcome 使用两个 `LGBMRegressor`。
12	- 输出模型候选、模型元数据、评估指标、打分表、uplift 分箱、分 component 特征重要性和报告。
13
14	已有 confirmed `task_config_path`、`modeling_sample_spec_path` 和 `feature_plan_path` 后使用。
15
16	## 2. 执行入口
17
18	统一 CLI：
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`。`train` 必须显式提供 `experiment_id`，格式为 `exp-001-name` 这类 `^exp-[0-9]{3}-[A-Za-z0-9][A-Za-z0-9_-]{0,63}$`。目标 experiment 已存在时返回 `needs_input / EXPERIMENT_ALREADY_EXISTS`，不覆盖、不恢复。
27
28	请求 JSON 必须通过 stdin 传入：
29
30	```json
31	{"action": "train", "payload": {"experiment_id": "exp-001-t_learner", "task_config_path": "...", "modeling_sample_spec_path": "...", "feature_plan_path": "..."}}
32	```
33
34	runner stdout 是 JSON object。调用方只读取 stdout 或 result JSON 中的 `outputs.*` 字段，例如 `outputs.modeling_result_path`、`outputs.model_candidate_path`、`outputs.report_path`。
35
36	只接受显式 `_path` / `_paths` 字段。收到旧的 `_ref` / `_refs` 输入时，runner 返回 `needs_input`，并在 `issues` 与 `next_steps` 中给出对应替代字段。
37
38	## 3. Actions 与参数说明
39
40	`train`
41
42	- 输入：`experiment_id`、`task_config_path`、`modeling_sample_spec_path`、`feature_plan_path`。
43	- 可选输入：`parameter_mode`、`parameter_overrides`。
44	- 输出：
45	- `experiment_id`
46	- `experiment_dir`
47	- `modeling_result_path`
48	- `model_candidate_path`
49	- `model_metadata_path`
50	- `evaluation_metrics_path`
51	- `score_frame_path`
52	- `uplift_bins_path`
53	- `feature_importance_path`
54	- `model_artifact_path`
55	- `report_path`
56	- `learner`
57	- `modeling_metrics`
58	- `split_evaluations`
59
60	`parameter_mode` 支持：
61
62	- `recommended_defaults`
63	- `user_overrides`
64
65	`parameter_overrides` 只允许 LightGBM 训练参数，例如 `n_estimators`、`learning_rate`、`num_leaves`、`max_depth`、`min_child_samples`、`random_state`、`n_jobs`。
66
67	## 4. 输出产物
68
69	典型输出目录：
70
71	```text
72	{run_dir}/new-models/{experiment_id}/
73	inputs/0001_train.request.json
74	results/0001_train.result.json
75	artifacts/
76	t_learner_model.v1.joblib
77	t_learner_treatment_model.v1.txt
78	t_learner_control_model.v1.txt
79	model_candidate.v1.json
80	model_metadata.v1.json
81	evaluation_metrics.v1.json
82	score_frame.v1.csv
83	uplift_bins.v1.csv
84	feature_importance.v1.csv
85	_experiment_manifest.json
86	_experiment_log.jsonl
87	report.md
88	```
89
90	所有 stdout、result、manifest 和 log 中的持久化 path 都是 `run_dir` 相对路径。`candidate_id` 使用 `experiment_id`。下游比较优先通过 `experiment_ids` 进入 `uplift-model-result-comparison` 的 `draft_comparison_plan`。
91
92	`score_frame.v1.csv` 使用 `treatment_prediction`、`control_prediction` 和 `uplift_score` 表达两个潜在 outcome 预测差值。
93
94	`feature_importance.v1.csv` 是单文件，包含 `component` 字段；`component` 取值为 `treatment_outcome` 或 `control_outcome`。
95
96	`outputs.split_evaluations` 使用和 `uplift-model-tuning` winner 一致的结构，按 split 暴露 `population_fingerprint`、`metric_name`、`metric_value`、`metric_method`、`metric_version`、`auuc_version` 和 `support`。`auuc_version` 固定标记 `{"package": "scikit-uplift", "version": "0.5.1"}`。
97
98	## 5. 与其他 skill 的关联
99
100	\| 方向 \| Skill \| 关系 \|
101	\|---\|---\|---\|
102	\| 上游 \| `uplift-model-feature-quality-analysis` \| 提供 confirmed `feature_plan_path` \|
103	\| 上游 \| `uplift-model-sample-preparation` \| 提供 confirmed `modeling_sample_spec_path` \|
104	\| 下游 \| `uplift-model-tuning` \| 消费 successful T-Learner `modeling_result_path` 生成调参 study \|
105	\| 下游 \| `uplift-model-result-comparison` \| 消费 `experiment_ids` 或 `modeling_result_path` 参与模型比较 \|
106
107	## 6. 执行约束
108
109	本 skill 不选择特征，不调参，不比较多个模型，不生成最终业务报告。
110
111	### 样本支持与风险
112
113	- train split 缺 treatment 或 control arm 时返回 `needs_input`，`issues[].code = "INSUFFICIENT_TRAIN_ARM_SUPPORT"`。
114	- binary outcome 下，train split 任一 arm 只有单一 outcome class 时返回 `needs_input`，`issues[].code = "SINGLE_CLASS_TRAIN_ARM"`。
115	- evaluation split 缺 treatment 或 control arm 时训练仍可成功，但该 split 的 `metric_value` 为 `null`，并记录 `issues[].code = "INSUFFICIENT_EVALUATION_ARM_SUPPORT"`。
116	- T-Learner 依赖 treatment/control 两个 arm 的可比性；如果上游样本选择或 treatment assignment 存在偏差，uplift 排序应保守解读。
117
118	### 模型文件安全
119
120	`t_learner_model.v1.joblib` 只能从可信来源加载。不要加载来源不明或被外部修改过的 joblib 模型文件。
121
122	## 7. 异常处理
123
124	### 7.1 缺依赖处理
125
126	本 skill 需要 `pandas`、`numpy`、`joblib`、`lightgbm` 和 `scikit-uplift==0.5.1`。runner 不安装依赖。缺包时返回结构化失败，并在 issue/next_steps 中提示阅读本 skill 的缺依赖处理说明，不返回 skill 安装目录文件路径。
127
128	AUUC 由 `sklift.metrics.uplift_auc_score` 和 `sklift.metrics.uplift_curve` 计算。
129
130	### 7.2 字段兼容与 experiment 异常
131
132	只接受显式 `_path` / `_paths` 字段。收到旧的 `_ref` / `_refs` 输入时，runner 返回 `needs_input`，并在 `issues` 与 `next_steps` 中给出对应替代字段。
133
134	目标 experiment 已存在时返回 `needs

People who liked this also viewed

6 picks

Type