# 智能银行营销系统 (Smart Marketing System)

> **机器学习 (Python) 课程设计** | Level 1：表格预测 + 行动建议闭环

## 👥 团队成员

| 姓名 | 学号 | 贡献 |
|------|------|------|
| 林嘉烨 | 2311511113 | 全栈开发 (Data, ML, Agent, Streamlit) |

## 📝 项目简介

本项目旨在解决银行电话营销中的效率问题。利用 **Bank Marketing Dataset**，我们构建了一个**“预测 + 决策”**闭环系统。首先使用 **LightGBM** 预测客户购买定期存款的概率，然后通过 **Agent** 结合业务规则，自动生成针对不同意向客户的个性化营销策略（话术、渠道）。

**核心亮点：**
- ⚡ **高性能**：使用 Polars 进行数据处理，LightGBM 进行建模。
- 🛡️ **高可靠**：使用 Pandera 进行数据契约验证，Pydantic 保证 Agent 输出结构化。
- 🤖 **智能化**：Agent 不仅给分数，更给出可执行的行动清单。

## 🚀 快速开始

```bash
# 1. 进入项目目录
cd ml_course_design

# 2. 安装依赖 (推荐使用 uv，也可以直接 pip)
# pip install polars lightgbm pandera streamlit pydantic python-dotenv
# 或者如果使用 uv:
# uv sync

# 3. 配置环境变量
# 复制 .env.example 为 .env (Mock 模式下无需真实 Key)
cp .env.example .env

# 4. 训练模型 (这一步会生成 models/model_artifacts.pkl)
# 注意：Windows 下请确保 PYTHONPATH 包含当前目录
$env:PYTHONPATH="."; python src/train.py

# 5. 运行 Agent Demo
python src/agent_app.py

# 6. 启动 Streamlit 可视化界面
streamlit run src/streamlit_app.py
```

---

## 1️⃣ 问题定义与数据

### 1.1 任务描述
- **任务类型**：二分类 (Binary Classification)
- **目标**：预测客户是否会订阅定期存款 (term deposit)。
- **业务价值**：精准定位高意向客户，减少对低意向客户的骚扰，提高营销 ROI。

### 1.2 数据来源

| 项目 | 说明 |
|------|------|
| 数据集名称 | Bank Marketing Dataset |
| 数据链接 | [UCI Machine Learning Repository](https://archive.ics.uci.edu/ml/datasets/Bank+Marketing) |
| 样本量 | 11,162 条 (bank.csv) |
| 特征数 | 16 个 (含 label) |

### 1.3 数据切分与防泄漏
- **切分策略**：80% 训练集，20% 测试集 (`train_test_split`, random_state=42)。
- **防泄漏处理**：**移除 `duration` 字段**。该字段在执行电话营销前未知，且与结果高度相关（通话时间越长越可能成功），属于典型的“未来信息泄漏”。

---

## 2️⃣ 机器学习流水线

### 2.1 模型对比

| 模型 | F1-Score | ROC-AUC | 说明 |
|------|----------|---------|------|
| **Logistic Regression (Baseline)** | 0.6554 | 0.7329 | 简单线性模型，作为基准 |
| **LightGBM (Advanced)** | **0.6917** | **0.8030** | 梯度提升树，显著优于基线 |

### 2.2 误差分析
- LightGBM 在 AUC 上提升了约 **7个百分点**，说明其排序能力更强，更适合用于生成概率评分。
- F1 分数受限于类别不平衡（deposit=yes 的样本较少），未来可尝试 SMOTE 或 Class Weight 优化。

---

## 3️⃣ Agent 实现

### 3.1 工具定义

| 工具名 | 功能 | 输入 | 输出 |
|--------|------|------|------|
| `predict_risk` | 调用 ML 模型预测购买概率 | `CustomerFeatures` (Pydantic) | `dict` (score, top_features) |
| `get_strategy` | 规则引擎检索营销策略 | `float` (score) | `dict` (segment, action, templates) |

### 3.2 决策流程
1. **感知 (Perception)**: Agent 接收客户画像，调用 `predict_risk` 获取购买概率。
2. **规划 (Planning)**: 根据概率调用 `get_strategy` 匹配对应的客户分群和营销渠道。
3. **行动 (Action)**: 整合信息，输出 `Decision` 对象，包含具体的行动清单（话术、渠道）。

### 3.3 案例展示

**输入**：
> 35岁, 管理层(management), 余额 2000, 以前没有参加过活动

**输出 (JSON)**：
```json
{
  "risk_score": 0.4524,
  "customer_segment": "潜在客户",
  "decision": "建议采取 自动化营销",
  "actions": [
    "使用话术: 你好，近期理财活动...",
    "使用话术: 点击领取加息券"
  ],
  "rationale": "模型预测概率为 45.2%，属于潜在客户。该群体对自动化营销转化率较高。"
}
```

---

## 4️⃣ 开发心得

### 4.1 主要困难与解决方案
- **数据泄露识别**：一开始模型准确率异常高（接近100%），排查发现是 `duration` 导致的。解决方案是果断移除该特征。
- **环境配置**：Windows 下 Python 路径问题导致模块导入失败。解决方案是通过 `$env:PYTHONPATH` 显式指定路径。

### 4.2 对 AI 辅助编程的感受
- AI 在生成样板代码（如 Pydantic 模型定义、Streamlit UI 布局）方面效率极高。
- 对于复杂的业务逻辑（如 Agent 的决策树设计），仍需人工介入进行微调和规则定义。

---

## 参考资料

- [LightGBM Documentation](https://lightgbm.readthedocs.io/)
- [Polars User Guide](https://pola.rs/)
- [Pydantic Documentation](https://docs.pydantic.dev/)
- [Streamlit Documentation](https://docs.streamlit.io/)