Metadata-Version: 2.4
Name: cfskit
Version: 0.1.7
Summary: Common research utilities for our NUIST-GenAI-Lab and CCGM tasks
Author-email: CFuShn <1354809038@qq.com>
License-Expression: MIT
Project-URL: Repository, https://github.com/NUIST-GenAI-Lab/cfskit
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: loguru<1,>=0.6.0
Requires-Dist: tomli>=1.1.0; python_version < "3.11"
Requires-Dist: accelerate<1,>=0.23.0; python_version < "3.10"
Requires-Dist: accelerate<2,>=1.0.0; python_version >= "3.10"
Requires-Dist: tensorboard<2.20,>=2.12.0; python_version < "3.9"
Requires-Dist: tensorboard<3,>=2.20.0; python_version >= "3.9"
Provides-Extra: torch
Requires-Dist: torch<3,>=2.0.0; extra == "torch"
Provides-Extra: tb
Requires-Dist: torch<3,>=2.0.0; extra == "tb"
Provides-Extra: tb-vision
Requires-Dist: torchvision<1,>=0.15.0; extra == "tb-vision"
Provides-Extra: dev
Requires-Dist: pytest<9,>=8.0.0; extra == "dev"
Dynamic: license-file

# cfskit

cfskit 是一个轻量科研代码库，提供日志、TensorBoard、进程信号、严格配置、DDP Context、checkpoint 基础和
显式 Pipeline 抽象，以及一个默认支持多进程 DDP 的实验工程示例：

- [nlab-template](examples/nlab-template/): 使用连续编号 pipeline 表达数据准备、训练和评估的 DDP-first CIFAR-10 工程。

模板用于复现、二次开发或新实验起步；运行逻辑、配置、checkpoint 和验证证据都保留在普通代码与文档中。

本仓库推荐使用 OpenSpec 管理非平凡变更。根目录 [openspec/](openspec/) 用于讨论和设计 cfskit 工具模块迭代、模板规范化与维护变更；各模板工程内部的 `openspec/` 只服务对应 demo 项目的本地科研变更示范。

通用工程实现位于命名明确的 `cfskit.config_base`、`cfskit.context_base`、
`cfskit.checkpoint_base` 和 `cfskit.pipeline`；
模板根 `context.py` 通过双继承统一管理具体配置与 Runtime，`configs/` 只保留
TOML 实验数据。`context.py` 公开五个项目全局对象，s01 在每个 rank 上初始化
一次，后续代码直接调用：

| 全局对象 | 说明 |
|----------|------|
| `ctx` | 一级实验配置字段、派生路径和进程信息 |
| `accelerator` | 绑定当前进程的 `accelerate.Accelerator` |
| `logger` | 基于 loguru 的全局代理，tqdm 兼容，单次初始化 |
| `tb` | TensorBoard 操作代理与示例接口，非主 rank 自动 no-op |
| `ipc` | 基于 SIGUSR1/SIGUSR2 的进程内单例，通过 collective 向全部 rank 传播决策 |

### 模板调用方式

```python
from cfskit import ExperimentPipeline

if __name__ == "__main__":
    ppl = ExperimentPipeline()
    from pipeline import InitStep, PrepareDataStep, TrainStep

    ppl.add_step(InitStep())
    ppl.add_step(PrepareDataStep())
    ppl.add_step(TrainStep())
    ppl.run()
```

`ExperimentPipeline` 统一处理 Pipeline 执行、`ExperimentError` 的简短报错和 Context
收尾；项目入口只保留一行一个 step 的实验流程。`InitStep` 不区分 train/eval，
`work()` 只调用 `ctx.initialize()`，由 Context 底层读取一个必填的完整 TOML。训练恢复与
评估前置条件由各自 step 按约定做基础检查，不进入通用 Runtime 状态。`--help` 仍无
运行副作用。DDP 是模板的
主要执行架构，推荐通过 `accelerate launch --num_processes=<N> run_train.py configs/<experiment>.toml`
启动；`world_size=1` 只是同一路径的
单进程情形，不存在另一套“单卡默认实现”。每次运行只接收一个显式全量 TOML，不做默认加载或增量 TOML 合并；TOML 仍用 section 管理完整实验，
但初始化后直接使用 `ctx.batch_size`、`ctx.model_name` 等一级字段；模板
`context.py` 只以注释分隔各生命周期配置区域。

临时调试可在完整 TOML 后直接覆盖已声明的一级字段，例如
`--micro-batch-size 32 --epochs 3`。GPU 可见范围和 DDP 进程数仍分别由
`CUDA_VISIBLE_DEVICES` 与 `accelerate launch --num_processes=<N>` 管理；覆盖后的最终值会写入
`effective_config.json`。正式实验仍建议保存一份对应的完整 TOML。

推荐统一使用 `ctx.xxx`、`accelerator.xxx`、`logger.xxx`、`tb.xxx`、`ipc.xxx`。旧的
`register_signal_handler()`、`get_s1()`、`switch_s1()` 等 IPC 函数仍保留为兼容 wrapper，
但新代码不再使用散函数调用。

`logger`、`tb`、`ipc` 直接复用 cfskit 单例，不再由模板再包一层代理；`accelerator` 由
`cfskit.context_base` 提供稳定代理。`Pipeline` 使用普通 `for` 循环执行显式 step，不包含自动发现、
递归责任链、dataset registry 或隐式 DDP barrier。

`cfskit.checkpoint_base` 只提供可复用的 Accelerate state 检查和 DDP staging 发布；
`last/best/epoch` 命名、指标 metadata、train/eval 选择顺序与保留策略仍由具体科研项目定义。
它不自动扫描硬崩溃遗留的隐藏 backup，也不提供复杂策略框架。

### 安装

```bash
python -m pip install "cfskit>=0.1.7"
```

如果需要使用 `setup_tensorboard()`，请安装 torch extra：

```bash
python -m pip install "cfskit[torch]>=0.1.7"
```

如果还需要 `tb.image_grid()` 等 torchvision 能力：

```bash
python -m pip install "cfskit[torch,tb-vision]>=0.1.7"
```

仓库内直接运行 `examples/nlab-template/` 时，使用 editable 安装以确保调用当前源码：

```bash
cd examples/nlab-template
python -m pip install -e "../..[torch,tb-vision]"
```

`nlab-template` 当前要求 `cfskit>=0.1.7`。复制为独立工程后应安装对应已发布版本，不再依赖仓库相对路径。
