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

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

本层把化工 AI 的「模型」从硬编码改造为**模板化**实现：同一主干代码不变，
切换行业 / 工况只改 *配方（recipe）* —— 一个声明式 JSON 包，对齐 PRD 5.3
「**固定主干 + 可配置超参**」默认模式。

## 当前已交付

| 模块 | 对应 issue | PRD 5.3 模型 | 说明 |
|------|-----------|-------------|------|
| `cross_process_optimizer` | #38 | ③ 跨工序寻优 | 多串联工序协同寻优，可解释优化建议（采纳率≥60%） |

## 跨工序寻优（`cross_process_optimizer.py`）

化工产线由多道**串联工序**组成（氯化→精制→还原、反应→水洗→干燥）。单工序
局部最优 ≠ 全局最优：上游操作参数通过中间品指标传递到下游，影响最终收率 /
能耗 / 质量。跨工序寻优在**满足工艺约束**前提下，**协调多个工序的可调变量**，
使全流程目标达到最优，并给出**可解释的优化建议**。

### 配方（Recipe）结构

```jsonc
{
  "name": "ti-cl4-cross-process-opt",
  "industry": "海绵钛氯化车间",
  "solver": "grid",                 // grid / random / analytic / stub
  "solver_params": {"max_per_var": 6, "max_total": 5000},
  "stages": [                       // 顺序串联工序
    {
      "name": "氯化",
      "decision_vars": [            // 本工序可调决策变量
        {"name": "chlorination_temp", "low": 850, "high": 950, "step": 20, "default": 870, "unit": "℃"}
      ],
      "transfer_vars": ["ti_cl4_yield"],   // 传给下游的中间品指标
      "proxy": "0.4 * (chlorination_temp - 850) / 100 + ..."  // 上游如何影响下游（算术表达式）
    }
  ],
  "constraints": [                  // 物料平衡 / 安全限值 / 产能上下界
    {"expr": "chlorination_temp", "op": "<=", "bound": 950, "label": "安全上限"}
  ],
  "objective": {                    // 最大化收率 / 最小化能耗 / 加权多目标
    "expr": "purity - 0.01 * cl2_flow - 0.005 * chlorination_temp",
    "sense": "max", "label": "综合收率"
  },
  "acceptance_floor": 0.60          // PRD 第6章里程碑：采纳率 ≥ 60%
}
```

### 快速开始

```python
from cross_process_optimizer import build_from_recipe

# 切换行业/工况只改配方文件，模型代码零改动
opt = build_from_recipe("samples/cross-process-opt/recipe.ti.json")
result = opt.optimize()
print(result.objective_score, result.accepted)
for sug in result.suggestions:
    print(f"{sug.stage}/{sug.variable}: {sug.old_value}→{sug.new_value} ({sug.direction})")
```

### 求解策略

| solver | 适用 | 说明 |
|--------|------|------|
| `grid` | 离散变量少 | 决策变量离散网格笛卡尔积枚举，组合过大自动降级为 random |
| `random` | 变量多 / 连续 | 范围内随机采样 N 个候选解取最优（可设 seed 可复现） |
| `analytic` | 单变量线性 | 边界判定最优方向，最可解释（明确指出变量该往哪调） |
| `stub` | CI / 离线校验 | 取默认值，保证无依赖环境可加载 |

### 安全性

约束 / 目标 / proxy 表达式在**受限命名空间**里 eval（`__builtins__` 置空，
仅放行 `abs/min/max/round/pow/sum` 与已声明的变量名），禁止 `__import__` /
`open` / 任意属性访问，防止配方注入危险代码。

## 测试

```bash
cd core/model-framework
python -m unittest discover -s tests -v
python _sanity_check.py    # 离线基本验证
```

## 与规划模块的关系

接口风格对齐 issue #34 `model_recipe`（Model Recipe 插件接口）与 #36
`quality_forecast`（质量预测模板化）。本模块**自包含、不依赖未合并分支**；
待 #34 / #36 合入后，跨工序寻优可注册为 `ModelRecipe` 的一个具名模板，
业务侧零改动。