# Pyruns

**[English](README-en.md) | 简体中文**

<p align="center">
  <img src="https://img.shields.io/pypi/v/pyruns.svg" alt="PyPI version">
  <img src="https://img.shields.io/pypi/pyversions/pyruns.svg" alt="Python Versions">
  <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License">
</p>

<p align="center">
  <b>轻量级 Python 实验管理 Web UI —— 调参、批量运行、实时监控，一站式解决 🚀</b>
</p>

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

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

```bash
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。

```bash
pyr train.py
```

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

### 模式 2：自定义 YAML 配置

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

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

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

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

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

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

---

## 🎯 功能概览

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

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

![Generator UI](docs/assets/multi_gen.png)

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

### 📦 Manager — 任务控制台

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

![Manager UI](docs/assets/tab_manager.png)

| | |
|:---:|:---:|
| **任务信息总览**<br>![Task Details Info](docs/assets/taskinfo.png) | **配置快照查看**<br>![Task Details Config](docs/assets/config.png) |
| **实验笔记记录**<br>![Task Details Notes](docs/assets/notes.png) | **环境变量详情**<br>![Task Details Env](docs/assets/env.png) |

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

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

![Monitor UI](docs/assets/tab_monitor.png)

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

```python
pyruns.add_monitor(last_loss=last_loss)
```

![Export Report](docs/assets/export_report.png)

---

## 🧪 批量生成语法

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

![]()

**笛卡尔积 `|`** — 全排列组合（3 × 2 = 6 个任务）：
```yaml
learning_rate: 0.001 | 0.01 | 0.1
batch_size: 32 | 64
```

**配对组合 `(|)`** — 按位置一一对应（3 个任务）：
```yaml
seed: (1 | 2 | 3)
experiment_name: (exp_a | exp_b | exp_c)
```

两种语法可混合使用。详见 [批量语法指南](docs/batch-syntax.md)。

---

## 📂 工作区结构

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

```text
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` 自定义设置：

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

---

## 📖 文档

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

---

## License

MIT
