# iAOP-Core · model_framework（③ AI 模型框架 · 配置化重构）

本目录承载 EPIC #5「③ AI 模型框架 配置化重构」（PRD 5.3）的内核模块。PRD 5.3
要求把"写死在树脂场景"的 4 类模型重构为**可配置模板**，由超参包驱动，核心诉求：

> **固定主干网络 + 可配置超参**为默认；同时提供 **Model Recipe 注册表**，允许
> 高级行业模板通过声明式 recipe 选择不同网络结构（LSTM 用于时序、GNN 用于跨工序），
> **新增结构走插件注册而非改内核**。

## 模块一览

| 文件 | Issue | 职责 |
|------|-------|------|
| `model_recipe.py` | **#34** | Model Recipe 插件接口与样例协议（**结构层**插件注册表） |
| `feature_spec.py` | #35（并行 PR） | FeatureSpec 声明式特征定义引擎（**特征层**插件注册表） |

> 注：`feature_spec.py`（#35）与 `model_recipe.py`（#34）是 EPIC #5 下两个并行
> 子任务，各自独立但理念呼应——#35 在**特征算子**层提供 `register_operator`
> 插件注册，#34 在**模型结构**层提供 `register_recipe`/`register_backbone`
> 插件注册，共同构成「特征层 + 结构层」两级插件体系。两个 PR 合入后本 README
> 会整合两段说明。

---

## `model_recipe.py` — Model Recipe 插件接口（issue #34）

对应 PRD 5.3「网络结构策略 / 模板化技术路径」与 EPIC #5 验收口径：**同一框架
加载树脂与 Ti 两套 Recipe 均能跑通——切换模板仅改 Recipe，模型代码零改动**。

### 设计要点

* **声明式 Recipe**：`ModelRecipe` 是不可变数据对象（dataclass frozen），描述
  「用什么网络主干 + 默认超参 + 必需特征」。`to_dict`/`from_dict` 可序列化往返，
  便于配置台（#62~#67）展示与审计。
* **两级插件注册**：
  * `register_backbone(name, factory)` —— 注册网络主干工厂（结构层扩展点）；
  * `register_recipe(ModelRecipe(...))` —— 注册声明式 Recipe（业务层扩展点）。
  * 高级行业模板（如自研 GNN）只需 `register_backbone` + `register_recipe` 即可
    接入内核，**零改码**（对齐 PRD「新增结构走插件注册」）。
* **统一模型句柄**：所有主干工厂返回 `ModelHandle`（`fit`/`predict`/`to_dict`），
  使训练/推理流水线（#40）与配置台只面向同一接口编程。
* **零外部强依赖**：无 sklearn/torch 时，`gbdt`/`dnn`/`lstm`/`gnn` 主干自动
  退化为纯 Python `stub`（均值预测），保证边缘/离线/CI 环境可加载、注册、构造、
  （伪）拟合与推理。有 sklearn 时 `gbdt`/`dnn` 自动升级为真实实现。
* **fail-closed**：未 `fit` 的模型 `predict` 直接抛错，绝不静默返回垃圾值。

### 内置主干（覆盖 PRD 5.3 四类模型模板全部默认结构）

| 主干 | 工厂 | 说明 | 有第三方依赖时 |
|------|------|------|----------------|
| `gbdt` | `gbdt_backbone` | 梯度提升回归（质量预测默认） | sklearn `GradientBoostingRegressor` |
| `dnn` | `dnn_backbone` | 轻量 DNN（异常检测默认） | sklearn `MLPRegressor` |
| `lstm` | `lstm_backbone` | LSTM 时序（高级模板可选） | 退化为 stub，插件注入真实实现 |
| `gnn` | `gnn_backbone` | GNN 跨工序（高级模板可选） | 退化为 stub，插件注入真实实现 |
| `stub` | `stub_backbone` | 纯 Python 均值预测（兜底） | — |

### 内置四类 Recipe（与 PRD 5.3 四类模型模板 1:1 映射）

```
quality_predict.default    ① 质量预测      backbone=gbdt
process_optimize.default   ② 工艺优化      backbone=gbdt
anomaly_detect.default     ③ 异常检测      backbone=dnn
cross_process.default      ④ 跨工序寻优    backbone=gnn
```

### 使用

```python
from model_framework.model_recipe import (
    build_model, register_recipe, register_backbone, ModelRecipe,
    validate_hyperparam_pack, load_sample_recipe,
)

# 1) 用内置 Recipe 构造模型并训练
m = build_model("quality_predict.default", {"max_depth": 6, "n_estimators": 300})
m.fit(X_train, y_train)
pred = m.predict(X_test)

# 2) 插件扩展：自研 GNN 主干，零改码接入
register_backbone("my-gnn", lambda hp: MyGnnImpl(**hp))
register_recipe(ModelRecipe(
    id="cross_process.my_gnn", kind="cross_process", backbone="my-gnn",
    default_hyperparams={"hidden": 128}, description="自研 GNN",
))
m2 = build_model("cross_process.my_gnn")

# 3) 超参包校验（Recipe 视角，与 #39 的 spec 校验互补）
pack = load_sample_recipe("ti")
issues = validate_hyperparam_pack(pack)   # [] = 通过
```

### 样例协议（EPIC #5 验收口径）

`SAMPLE_RECIPES` 内置 `resin`（树脂）与 `ti`（氯化车间/海绵钛）两套超参包样例，
两者共用同一个 `recipe_id=quality_predict.default`，仅超参不同——直接验证
「同一框架加载两套 Recipe 均能 build/fit/predict，切换模板仅改超参包，模型代码
零改动」。

## 测试

```bash
cd core/model-framework/tests
python -m unittest test_model_recipe            # 30 个用例

cd core/model-framework
python _sanity_check.py                          # 端到端 sanity
```