# iAOP-Core · 模型框架层（AI Model Framework）

对应 PRD 5.3「③ AI 模型框架」与 EPIC #5「内核平台化改造」。

本层把化工 AI 的「模型资产」统一注册、版本化、阶段化管理：模型 / 配方 /
估计器是资产，需要注册表统一管理——注册、加载、版本、阶段（灰度）、回滚、审计。

## 当前已交付

| 模块 | 对应 issue | PRD 5.3 模型 | 说明 |
|------|-----------|-------------|------|
| `template_registry` | #41 | ③ 模型模板注册/加载/版本机制 | 多版本 + 阶段(dev/staging/prod) + 提升 + 回滚 + 审计 + 持久化 |

## 模板注册表（`template_registry.py`）

模板化之后，模型 / 配方是「资产」，需要注册表统一管理：
- **注册**：登记一个模型模板（含主干、超参、特征列、指标、版本）；
- **加载**：按 name + version/别名/stage 取出；
- **版本**：同模板多版本共存，可回滚、可审计；
- **阶段**：版本带 stage 标签（dev/staging/prod），灰度发布可控。

### 核心组件

- **`ModelTemplate`**：模型模板数据对象（name/version/backbone/hyperparams/
  feature_columns/metrics/stage），不可变、可序列化往返。
- **`TemplateRegistry`**：注册表核心 API：
  - `register`（校验完整性 + 同版本号拒重复，force 可覆盖）
  - `get`（按 version / stage / 默认最新加载）
  - `promote`（dev→staging→prod 逐级提升）
  - `rollback`（stage 指针回退，保留历史可审计）
  - `set_stage`（直接设 stage，紧急回滚）
  - `list_versions` / `list_by_stage` / `stage_pointer` / `history`
  - `save` / `load`（JSON 持久化，重启恢复）
- **`Stage`**：阶段枚举（DEV / STAGING / PROD），PRD 灰度三段制。
- **`is_valid_version`**：语义化版本号校验（v1 / 1.0.0 / v1.2-rc1）。

### 快速开始

```python
from template_registry import ModelTemplate, Stage, TemplateRegistry

reg = TemplateRegistry()
reg.register(ModelTemplate(
    name="ti-quality", version="v1.0", backbone="quality_forecast",
    feature_columns=("furnace_temp", "cl2_flow"),
    metrics={"accuracy": 0.91}, stage="dev"))
reg.register(ModelTemplate(name="ti-quality", version="v1.1",
                           backbone="quality_forecast", metrics={"accuracy": 0.94}))

reg.promote("ti-quality", "v1.1")   # dev -> staging
reg.promote("ti-quality", "v1.1")   # staging -> prod
reg.rollback("ti-quality", Stage.PROD, "v1.0")  # 紧急回滚

serving = reg.get("ti-quality", stage=Stage.PROD)  # 按阶段加载
reg.save("registry.json")           # 持久化审计
```

## 测试

```bash
cd core/model-framework
python -m unittest discover -s tests -v
python _sanity_check.py
```

## 与规划模块的关系

接口风格对齐 #34（Model Recipe）、#36（quality_forecast）、#38
（cross_process_optimizer）、#40（pipeline）。本模块是 #40 `ModelRegistry`
的完整版（多阶段 + 回滚 + 持久化），#40 的 `RegisterStep` 未来可直接对接本
注册表，业务侧零改动。