# SigmaPI SDK 开发计划

## 1. 核心目标

本项目的核心目标是开发和维护 `SigmaPI`，一个轻量级、通用、高性能的 SDK，用于计算预测完整性（Predictive Integrity, PI）。它旨在为任何 PyTorch 模型提供一个标准的、实时的“认知状态”监控工具。

## 2. 项目结构

随着实验框架 `PILF` 的剥离，本仓库结构将回归其核心功能：

```plain
SigmaPI/
├── main.py     # 核心 SigmaPI 计算逻辑
├── pyproject.toml # 项目打包与依赖配置
├── LICENSE
└── README.md   # 项目说明
```

## 3. 工程准则

- **torch.compile 友好**: 核心计算逻辑（`SigmaPI.calculate`）必须始终保持与 `torch.compile` 的完全兼容性，避免任何可能导致图破坏（graph break）的操作。这是最高优先级。
- **性能优先**: 所有计算都应尽可能高效，避免不必要的 Python 端操作或数据拷贝。
- **零依赖**: 除了 `torch` 之外，SDK 本身不应引入任何新的硬性依赖。
- **API 稳定**: 对外暴露的 `SigmaPI.calculate` 接口应保持稳定。任何破坏性变更都需要在主版本号中体现。
- **代码纯净**: 代码必须简洁、自解释，移除所有不必要的注释。

## 4. 开发路线图

1. **Phase 0: 核心重构 (已完成)**
    - **SigmaPI Torch 化**: 已将 `main.py` 中的计算逻辑完全重构为 `torch` 原生操作，以兼容 `torch.compile`。

2. **Phase 1: API 稳定化 (当前阶段)**
    - **目标**: 完善文档和类型提示，确保 `SigmaPI.calculate` 的接口清晰、稳定，并发布 `1.0` 版本。
    - **下一步**: 清理 `main.py` 中的代码，添加详细的函数文档和类型注解。

3. **Phase 2: 扩展功能 (未来计划)**
    - **探索批量计算**: 研究在批处理（batch）维度上进行 PI 计算的优化方法，以进一步提升性能。
    - **集成可视化**: 考虑提供一个可选的、轻量级的可视化工具，用于实时绘制 PI 指标曲线。
