Metadata-Version: 2.4
Name: cfskit
Version: 0.1.3
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 写入、进程信号控制，以及一个可运行的实验工程示例：

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

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

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

| 工具实例 | 来源 | 说明 |
|----------|------|------|
| `accelerator` | `accelerate.Accelerator` | 由项目 Runtime 显式创建并持有 |
| `logger` | `cfskit.log_util` | 基于 loguru 的全局代理，tqdm 兼容，单次初始化 |
| `tb` | `cfskit.tb_util` | 基于 TensorBoard 的全局代理，多进程自动适配 |
| `ipc` | `cfskit.ipc_util` | 基于 SIGUSR1/SIGUSR2 的进程内单例，支持优雅控制训练流程 |

### 基础 API

```python
from accelerate import Accelerator
from cfskit import ipc, logger, setup_logger, setup_tensorboard, tb

accelerator = Accelerator()
setup_logger("output/demo/logs", name="nlab")
setup_tensorboard("output/demo/runs", name="nlab", accelerator=accelerator)
ipc.register_signal_handler()

accelerator.wait_for_everyone()
logger.info("experiment started")
tb.scalar("Loss/train", 0.1, step=1)
if ipc.get_s1():
    ipc.switch_s1(0)
```

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

### 安装

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

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

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

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

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

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

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

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