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

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

本层把化工 AI 的「模型流水线」从硬编码改造为**编排化、配置化**实现：每个
步骤是可插拔的 `Step`，步骤间数据通过 `Context` 流转，整条流水线由声明式
配置驱动——切换模型 / 数据源只改配置，编排代码零改动。

## 当前已交付

| 模块 | 对应 issue | PRD 5.3 模型 | 说明 |
|------|-----------|-------------|------|
| `pipeline` | #40 | ③ 训练/推理流水线编排 | 数据→训练→评估→注册→加载→推理一条龙编排 |

## 训练 / 推理流水线（`pipeline.py`）

模型从「开发」到「上线」是一条流水线：**数据准备 → 特征工程 → 训练 → 评估 →
注册（版本化） → 加载 → 推理 → 监控**。手写脚本拼接不可复用、不可审计、不可
重放。本模块把这条流水线编排化、配置化。

### 核心组件

- **`Step` 抽象基类**：`prepare` / `run` / `teardown` 三段式生命周期。内置：
  - `LoadDataStep`（CSV / 内存加载数据）
  - `TrainStep`（可插拔 `Estimator` 训练）
  - `EvaluateStep`（accuracy / MAE / RMSE）
  - `RegisterStep`（注册到 `ModelRegistry`，版本化）
  - `LoadModelStep`（按版本 / 别名加载）
  - `PredictStep`（批量推理）
  - `CustomStep`（可调用 handler 快速接入业务）
- **`Pipeline` 编排器**：顺序执行 Step，自动传递 Context，支持 `dry_run` / 失败短路。
- **`Context`**：步骤间数据流转（params 只读 + artifacts 可写）。
- **`ModelRegistry`**：内存模型注册表（多版本 + latest/stable 别名），对接 issue #41 雏形。
- **`Estimator`**：可插拔训练算法（`MeanRegressor` / `MajorityClassifier` stub，无外部依赖）。
- **`PipelineConfig`**：声明式配置，`from_dict` / `to_dict` 可序列化往返。

### 快速开始

```python
from pipeline import (Pipeline, LoadDataStep, TrainStep, EvaluateStep,
                      RegisterStep, LoadModelStep, PredictStep)

# 切换模型 / 数据源只改配置，编排代码零改动
pipe = Pipeline("demo", [
    LoadDataStep("load", {"source": [[1, 10], [2, 20], [3, 30]]}),  # 末列 target
    TrainStep("train", {"estimator": "mean_regressor"}),
    EvaluateStep("eval", {}),
    RegisterStep("register", {"model_name": "demo", "version": "v1"}),
    LoadModelStep("load_model", {"model_name": "demo", "version": "v1"}),
    PredictStep("predict", {"input_key": "dataset"}),
])
result = pipe.run()
print(result.success, result.step_results)
```

### 声明式配置驱动

```python
from pipeline import Pipeline, PipelineConfig

cfg = PipelineConfig("config-driven", steps=[
    {"type": "load_data", "name": "load", "params": {"source": rows}},
    {"type": "train", "name": "train", "params": {"estimator": "mean_regressor"}},
    {"type": "evaluate", "name": "eval", "params": {}},
    {"type": "register", "name": "reg", "params": {"model_name": "demo", "version": "v1"}},
    {"type": "load_model", "name": "lm", "params": {"model_name": "demo", "version": "v1"}},
    {"type": "predict", "name": "pred", "params": {"input_key": "dataset"}},
])
result = Pipeline.from_config(cfg).run()
```

## 测试

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

## 与规划模块的关系

接口风格对齐 issue #34（Model Recipe）、#36（quality_forecast）、#38
（cross_process_optimizer）。本模块**自包含、不依赖未合并分支**；`TrainStep`
的 `Estimator` 可插拔，未来可对接 #36 质量预测模型作为具名 estimator，
`RegisterStep` 可对接 #41 完整版本机制，业务侧零改动。