pyruns 0.0.8

Lightweight web UI for managing, running, and monitoring Python experiments.

Pyruns

English | 简体中文

轻量级 Python 实验管理 Web UI —— 调参、批量运行、实时监控，一站式解决 🚀

Pyruns 为你的 Python 脚本提供一个开箱即用的浏览器界面：自动解析 argparse 参数生成可视化表单，通过内置语法一键展开参数网格并批量生成任务，统一调度并行执行，在浏览器中实时追踪 ANSI 彩色日志，最后导出跨任务的指标报告。

不需要改动任何业务代码。

pip install pyruns
pyr train.py          # 就这一行

---

✨ 核心能力

能力	说明
🔌 零侵入接入	自动解析 argparse 定义，渲染为 Web 表单。也支持直接导入 YAML/JSON 配置文件
🧮 批量参数网格	lr: 0.001 | 0.01 | 0.1 一行声明，自动展开笛卡尔积或配对组合，秒级生成数百任务
⚡ 并行调度执行	内置任务队列 + 线程/进程工作池，可控并发数，一键批量运行
📋 任务全生命周期管理	卡片式看板：状态过滤、搜索、置顶、笔记、环境变量、参数快照、运行日志，一目了然
🖥️ 实时彩色终端	浏览器内流式查看 ANSI 着色日志（兼容 tqdm、colorama），增量推送零卡顿
📊 指标采集与导出	脚本中调用 pyruns.add_monitor(loss=0.23) 记录关键指标，跨任务聚合导出 CSV/JSON 报告
💻 系统资源面板	顶部实时显示 CPU / RAM / 多 GPU 利用率与显存
📁 工作区隔离	按脚本名自动隔离（_pyruns_/train/ vs _pyruns_/test/），互不干扰，软删除可恢复

---

🚀 快速开始

模式 1：Argparse 脚本（零配置）

无需修改你的代码。Pyruns 通过 AST 静态分析自动提取 argparse 参数并生成 UI。

pyr train.py

首次运行时，Pyruns 会在脚本同级目录下创建 _pyruns_/train/config_default.yaml（包含所有参数的默认值），并启动 Web UI。

模式 2：自定义 YAML 配置

对于使用 config = pyruns.load() 读取配置的脚本，首次运行时传入 YAML 文件：

pyr train.py my_config.yaml   # → 复制为 _pyruns_/train/config_default.yaml

之后直接运行即可，Pyruns 自动加载已保存的配置：

pyr train.py                   # → 自动读取 _pyruns_/train/config_default.yaml

再次传入新的 YAML 会覆盖旧模板。

pyr help      # CLI 帮助
pyr version   # 查看版本

---

🎯 功能概览

🔧 Generator — 参数配置与批量生成

加载参数模板，在结构化表单或 YAML 编辑器中调整参数。使用批量语法一次性生成参数搜索网格。

解析 argparse 时，若同时存在短参数和长参数（如 -b, --batch_size），自动采用长参数名作为配置键。

📦 Manager — 任务控制台

卡片网格展示所有任务。支持按状态过滤、模糊搜索、批量选中运行。点击卡片查看完整元数据：

任务信息总览	配置快照查看
实验笔记记录	环境变量详情

📈 Monitor — 实时日志与指标导出

浏览器内实时流式查看 ANSI 彩色终端输出。顶部面板持续展示 CPU / RAM / GPU 资源状态。

在脚本末尾调用 pyruns.add_monitor() 记录评估指标，跨任务聚合导出 CSV/JSON：

pyruns.add_monitor(last_loss=last_loss)

---

🧪 批量生成语法

在 Generator 页面中直接使用管道语法进行参数网格搜索。

笛卡尔积 | — 全排列组合（3 × 2 = 6 个任务）：

learning_rate: 0.001 | 0.01 | 0.1
batch_size: 32 | 64

配对组合 (|) — 按位置一一对应（3 个任务）：

seed: (1 | 2 | 3)
experiment_name: (exp_a | exp_b | exp_c)

两种语法可混合使用。详见 批量语法指南。

---

📂 工作区结构

首次运行 pyr train.py 时，自动创建以下结构：

your_project/
├── train.py
└── _pyruns_/
    ├── _pyruns_settings.yaml      # 全局设置（端口、并发数、执行模式等）
    └── train/                     # 按脚本名隔离
        ├── config_default.yaml    # 参数模板（自动生成或导入）
        └── tasks/
            ├── my-exp-[1-of-6]/
            │   ├── task_info.json # 元数据（状态、时间、PID、笔记等）
            │   ├── config.yaml    # 本次运行的参数快照
            │   └── run_logs/
            │       └── run1.log   # 控制台输出
            └── .trash/            # 软删除（可恢复）

不同脚本完全隔离（_pyruns_/train/ 与 _pyruns_/test/ 互不影响）。

可通过 _pyruns_settings.yaml 自定义设置：

ui_port: 8099                      # Web UI 端口
generator_form_columns: 2          # 表单列数
manager_max_workers: 4             # 最大并发数
manager_execution_mode: thread     # 执行模式: thread | process
log_enabled: false                 # 调试日志

---

📖 文档

文档	说明
📗 安装与快速开始	5 分钟上手完整工作流
📙 配置系统	_pyruns_ 目录结构、配置优先级、类型推断
📘 批量语法	笛卡尔积 / 配对组合 / 嵌套参数展开
📕 界面操作	Generator、Manager、Monitor 三页面详细操作
📓 API 参考	read() / load() / add_monitor() 及工具函数
📒 架构设计	三层架构、数据流、调度机制（面向贡献者）

---

License

MIT