mflowy: Instructions file for Codex

AGENTS.md

AI 编码 agent 在本仓库的唯一指引。代码是真相源——本文件只写代码里查不到的东西：约定、理由、陷阱、流程。存疑先探索再假设；动态文件树用 tree --gitignore 现查。

Project

MFlowy：YAML 配置驱动的模块化 ML 工作流引擎，全部能力以 MCP tools（pyfunc）暴露——MCP server（stdio）、JSON runner（K8s Job 容器）、直接 import 三入口。

Language: Python 3.12 | 代码注释与文档：中文

开发命令

uv sync --all-extras --all-groups   # 首次/依赖变更后
make test                           # 全量测试
make lint && make fmt               # ruff
uv run cmd list_modules                          # base 能力（无数据栈）
uv run --extra modeling cmd modeling '{"modeling_steps_yaml": "...", "name": "...", "desc": "..."}'
uv run mcpSrv                                     # MCP server（stdio）

用户态分发（PyPI/uvx/wheel/Docker）见 README 与 docker/；MCP 客户端 stdio 配置见 .mcp.json.example。

uvx 陷阱（uvx 不读 pyproject 的 [tool.uv.sources]）：

• torch CPU 索引（--index https://download.pytorch.org/whl/cpu + unsafe-best-match）为 [modeling] 必需——缺省时 torch 解析为 CUDA 全家桶（2–3GB）
• extras 内联进 --from "mflowy[modeling]"——uvx 的 --extra 需新版 uv
• 入口名 mcpSrv 刻意避开 mcp SDK 同名 CLI（mcp.cli:app）——uvx 解析 mcp 命令可能命中 SDK 侧启动失败

分层

层	位置	职责
MCP Tools	src/mflowy/mcp/tools.py	全部工具定义，纯委派
JobProvider	src/mflowy/mcp/job_provider/	执行策略（Local 直调 / Remote K8s Job）
Driver	src/mflowy/driver/	YAML 解析、DAG 调度、handler 派发、模块发现
Compute	src/mflowy/compute/	业务逻辑

工具三分：建模类 4 种（modeling / explanation / predict / inverse_optimization）经 JobProvider 委派；分析类 3 种（data_profile / eda / infer_task_type_by_statistic）与 info/mlflow 组始终本地执行。

• 零手工注册：compute 模块入口函数加 @handler(StepType.X, ...) 即完成注册（driver/discover.py 启动扫描 mflowy.compute.**；_ 前缀与 _EXCLUDED 词干除外）
• 通道边界：print（stdout）= 业务数据，per-task 捕获进 NodeResult.output；logger（stderr）= 过程诊断。同一信息只走一条通道
• 模块内相对导入，跨模块绝对导入；KISS
• tests/ 镜像 src/mflowy/ 路径，integration/ 端到端