Metadata-Version: 2.4
Name: microstateledger
Version: 0.1.0
Summary: Microstate version-control system for drug discovery workflows
Author: MicrostateLedger Team
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://example.invalid/microstateledger
Keywords: cheminformatics,microstate,provenance,rdkit,docking,md
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9
Requires-Dist: pyyaml>=6
Requires-Dist: tomli; python_version < "3.11"
Provides-Extra: cheminformatics
Requires-Dist: rdkit-pypi>=2022.9.5; extra == "cheminformatics"
Requires-Dist: dimorphite-dl>=1.2; extra == "cheminformatics"
Provides-Extra: docking
Requires-Dist: meeko>=0.5; extra == "docking"
Provides-Extra: md
Requires-Dist: openff-toolkit>=0.14; extra == "md"
Requires-Dist: openff-interchange>=0.3; extra == "md"
Requires-Dist: openmm>=8.0; extra == "md"
Provides-Extra: charges
Requires-Dist: numpy>=1.23; extra == "charges"
Provides-Extra: repro
Requires-Dist: dvc>=3.0; extra == "repro"
Requires-Dist: datalad>=0.18; extra == "repro"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=4; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Dynamic: license-file

# MicrostateLedger

MicrostateLedger 是一个面向药物发现流程的“微观态版本控制系统”。

它把分子在不同阶段的状态变化（质子化、互变异构、手性/EZ、构象、配位）转成可追溯、可比较、可回滚的数据资产，覆盖从 RDKit 到 Docking、MD 的工程链路。

## 目录
- [1. 项目定位](#1-项目定位)
- [2. 核心能力](#2-核心能力)
- [3. 架构总览](#3-架构总览)
- [4. 仓库结构](#4-仓库结构)
- [5. 环境要求](#5-环境要求)
- [6. 安装方式](#6-安装方式)
- [7. 快速开始](#7-快速开始)
- [8. 配置说明](#8-配置说明)
- [9. 命令手册](#9-命令手册)
- [10. 数据模型与ID规则](#10-数据模型与id规则)
- [11. 映射与可逆性](#11-映射与可逆性)
- [12. 可复现与审计](#12-可复现与审计)
- [13. 终极门禁（Ultimate Release Gate）](#13-终极门禁ultimate-release-gate)
- [14. GitHub 与 PyPI 发布前清单](#14-github-与-pypi-发布前清单)
- [15. 常见问题](#15-常见问题)
- [16. 许可证](#16-许可证)

---

## 1. 项目定位

MicrostateLedger 解决的是“化学正确性 + 工程可追踪性”双重问题：

- 化学侧：同一化合物存在多微观态，不同软件阶段可能引入状态漂移。
- 工程侧：跨软件格式转换导致原子编号重排，团队复现困难。

项目目标：

1. 每个微观态都有稳定 ID。
2. 每一步选择都有 decision 记录。
3. 每个输出工件都有哈希与 run 关联。
4. 异常能自动回指并给出动作建议。
5. 支持 diff / rollback / provenance 导出。

---

## 2. 核心能力

- 稳定对象标识：`CompoundID / MicrostateID / ConformerID / PoseID / ArtifactID`
- 微观态枚举：protonation / tautomer / stereo
- 构象生成：RDKit ETKDG + PEAS（按策略自动选择）
- Docking 链路：PDBQT 导出、pose 入账、Top-k 选择
- 电荷链路：gasteiger / PyPE_RESP 输入与输出对齐
- MD 参数化：OpenFF Interchange + OpenMM/GROMACS/AMBER 工件
- 异常闭环：手性翻转、E/Z 漂移、化学式变化检测与建议
- 可复现工程：SQLite ledger、artifact 哈希、commands log、gate report

---

## 3. 架构总览

三层架构：

1. Ledger Core（`msl/`）
- 配置解析、ID、DB schema、CLI orchestration。

2. Driver Scripts（`scripts/` + `msl/resources/scripts/`）
- RDKit、PEAS、Meeko、OpenFF、PyPE_RESP 等具体执行脚本。

3. Artifact 层（运行时目录）
- `objects/`、`runs/`、`reports/` 等工件与报告目录（通常不入库）。

典型流程：

`ingest -> perceive -> enumerate -> conformers -> dock-prep/dock-ingest -> charge -> md-param -> md-feedback`

---

## 4. 仓库结构

```text
MicrostateLedger/
  msl/                     # 核心包
  scripts/                 # 可直接运行的驱动脚本
  msl/resources/           # 打包内置资源（fallback）
  schemas/ledger.sql       # SQLite schema
  policies/default.yaml    # 默认策略
  tests/                   # 单元与回归测试
  docs/                    # 说明文档
  pyproject.toml           # 打包与依赖定义
  msl.toml                 # 运行配置样例
```

说明：

- `msl/resources/*` 与仓库同名资源是双轨设计。
- 当仓库脚本不可用时，CLI 会自动 fallback 到 `~/.microstateledger/resources/<version>/`。

---

## 5. 环境要求

推荐：

- OS：Linux
- Python：`>=3.10`
- 包管理：`pip`（核心）+ `conda`（多工具环境隔离）

核心 Python 依赖（自动安装）：

- `typer>=0.9`
- `pyyaml>=6`
- `tomli`（仅 Python < 3.11）

可选能力依赖（按需）：

- cheminformatics：RDKit / Dimorphite
- docking：Meeko / Vina
- md：OpenFF toolkit / Interchange / OpenMM
- repro：DVC / DataLad

---

## 6. 安装方式

### 6.1 开发/源码安装（推荐）

```bash
git clone <your-repo-url>
cd MicrostateLedger
python -m pip install -e .
```

如果网络代理或离线限制导致 build isolation 拉依赖失败，可用：

```bash
python -m pip install -e . --no-build-isolation --no-deps
```

### 6.2 从构建产物安装（wheel）

```bash
python -m pip install dist/microstateledger-0.1.0-py3-none-any.whl
```

### 6.3 PyPI 现状

当前版本 `0.1.0` 尚未公开发布到 PyPI，因此直接执行：

```bash
pip install MicrostateLedger
```

会返回 `No matching distribution found`。发布后再改用该命令。

### 6.4 server 专用 wrapper 脚本说明

`bin/msl`、`bin/rdkit_python` 等脚本是服务器路径硬编码包装器（包含固定 `ROOT` 和 `CONDA` 路径）。

在新机器上：

- 要么修改这些脚本里的路径；
- 要么直接使用可移植命令：`python -m msl.cli ...`。

---

## 7. 快速开始

### 7.1 初始化

```bash
python -m msl.cli init --config msl.toml
python -m msl.cli migrate --config msl.toml
```

### 7.2 从 SMILES 到微观态

```bash
CID=$(python -m msl.cli ingest "CCO" --config msl.toml)
python -m msl.cli perceive "$CID" --config msl.toml
python -m msl.cli enumerate "$CID" --config msl.toml
```

### 7.3 构象与 docking 准备

```bash
MID=<your_microstate_id>
python -m msl.cli conformers "$MID" --method rdkit --n 20 --topk 5 --seed 20260206 --config msl.toml
python -m msl.cli dock-prep "$MID" <conformer_id> --config msl.toml
```

### 7.4 电荷与 MD 参数化

```bash
python -m msl.cli charge "$MID" --method gasteiger --config msl.toml
python -m msl.cli md-param "$MID" --config msl.toml
```

### 7.5 MD 反馈

```bash
python -m msl.cli md-feedback "$MID" <probe_snapshot.sdf> --config msl.toml
```

### 7.6 一键 demo

```bash
python -m msl.cli demo CCO --out-dir ./demo_runs --config msl.toml
```

---

## 8. 配置说明

### 8.1 `msl.toml`

```toml
[project]
name = "MicrostateLedger"
root = "/path/to/MicrostateLedger"
objects_dir = "objects"
runs_dir = "runs"
reports_dir = "reports"
policy = "policies/default.yaml"
ledger_db = "ledger.sqlite"

[envs]
conda = "/path/to/conda"
base_dir = "envs"

[logging]
level = "INFO"
log_dir = "logs"
```

关键点：

- `root` 决定相对目录的解析基准。
- `envs.base_dir` 对应多工具环境根目录。
- `policy` 是所有阶段决策的上游输入。

### 8.2 `policies/default.yaml`

主键说明：

- `project.ph`：感知与枚举 pH 范围
- `project.max_microstates`：全局微观态上限
- `stages.pre_docking_enum.*`：枚举与 Top-k 策略
- `stages.conformer_generation.*`：构象方法与筛选
- `stages.docking.*`：pose 选择策略
- `stages.pre_md.*`：电荷、参数化、最终态选择
- `stages.md_feedback.*`：异常检查开关

---

## 9. 命令手册

CLI 总览：

```bash
msl --help
```

主要命令组：

### 9.1 初始化与数据库

- `init`：初始化 ledger
- `migrate`：schema 迁移

### 9.2 化学流程主链

- `ingest`：标准化并注册 compound
- `perceive`：风险感知
- `enumerate`：枚举微观态
- `conformers`：生成构象
- `dock-prep` / `dock-ingest` / `dock-select`
- `charge`：电荷生成或导入
- `md-param`：MD 系统参数化
- `md-feedback` / `md-transition`

### 9.3 差分与审计

- `diff-microstate`
- `diff-conformer`
- `diff-charge`
- `diff-pipeline`
- `prov-export`

### 9.4 运维与恢复

- `batch`：支持 state 文件续跑
- `clean-invalid-microstates`
- `policy-snapshot` / `checkout`
- `inject`：人工注入微观态

### 9.5 数据与外部系统

- `dvc-init` / `dvc-track`
- `datalad-init` / `datalad-save`
- `lwreg-init` / `lwreg-register`
- `receptor-add`

说明：所有命令支持 `--help`，例如：

```bash
msl conformers --help
```

---

## 10. 数据模型与ID规则

核心表：

- `runs`：执行记录（stage/tool/params/status）
- `compounds`
- `microstates`
- `conformers`
- `poses`
- `systems`
- `artifacts`
- `edges`
- `decisions`
- `anomalies`
- `atom_maps`

ID 规则（摘要）：

- `CompoundID = C-<reg_hash_prefix>`
- `MicrostateID = M-sha256(fixedH_inchi|formal_charge|stereo|coordination)`
- `ConformerID = X-<sha256(file)>`
- `PoseID = P-<sha256(file)>`

---

## 11. 映射与可逆性

MicrostateLedger 通过 canonical atom id + sidecar JSON 保证跨软件映射可追踪：

- Docking：`ligand.map.json`
- MD：`atommap.json`（以及 gromacs/amber map）

可逆判定基线：

1. `canonical_atom_id` 在 docking map 中可查。
2. 同一 `canonical_atom_id` 在 MD map 中可查。
3. 可选：元素/连接关系一致性校验。

---

## 12. 可复现与审计

项目提供以下可复现保障：

- 每个工件入库时记录 `sha256`
- 每个阶段生成 `run_id`
- 每个关键选择写入 `decisions`
- 异常写入 `anomalies` 并挂接 `target_id`
- `prov-export` 导出 PROV-JSON

建议实践：

- 每次大实验前保存 policy snapshot
- 每次发布前执行 `ultimate_release_gate.py`
- 把 `commands.log` 与 `artifact_manifest.json` 作为审计附件保留

---

## 13. 终极门禁（Ultimate Release Gate）

执行：

```bash
python scripts/ultimate_release_gate.py \
  --outdir ultimate_test_runs/ultimate_release_gate_$(date +%F) \
  --report-dir reports/ultimate_release_gate_$(date +%F) \
  --commands-log reports/ultimate_release_gate_$(date +%F)/commands.log \
  --seed 20260206 \
  --n-repeats 3
```

产物：

- `ULTIMATE_REPORT.md`
- `artifact_manifest.json`
- `commands.log`
- `gate_3_1 ... gate_3_7` JSON

详细说明见：`docs/ultimate_release_gate.md`

---

## 14. GitHub 与 PyPI 发布前清单

### 14.1 GitHub 发布前

1. 工作区干净：`git status`
2. 测试通过：`python -m pytest -q`
3. 包可构建：`python -m build`
4. README 渲染检查：`python -m twine check dist/*`
5. CI workflow 存在：`.github/workflows/ci.yml`
6. 版本号已确认：`pyproject.toml` 的 `project.version`
7. 打 tag：`git tag v0.1.0`
8. 推送分支与 tag。

### 14.2 PyPI 发布前

1. 先在 TestPyPI 验证上传
2. 确保 `twine check` 无报错
3. 检查 wheel/sdist 含必要文件（schema/policy/resources）
4. 执行上传：

```bash
python -m twine upload dist/*
```

说明：若当前未发布到 PyPI，`pip install MicrostateLedger` 会失败，这是预期状态。

---

## 15. 常见问题

### Q1: `pip install -e .` 报 SOCKS/proxy 错误

原因：代理依赖缺失（如 SOCKS）。

处理：

```bash
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY all_proxy ALL_PROXY
python -m pip install -e .
```

离线/受限环境可用：

```bash
python -m pip install -e . --no-build-isolation --no-deps
```

### Q2: 提示 `No space left on device`

原因：`/tmp` 或根分区空间不足。

处理：把临时目录和 pip cache 挪到大盘：

```bash
export TMPDIR=/data/your_tmp
export PIP_CACHE_DIR=/data/your_pip_cache
```

### Q3: `msl` 命令找不到或 wrapper 不可用

处理：

- 直接使用 `python -m msl.cli ...`
- 或修正 `bin/*` 中硬编码路径（`ROOT`/`CONDA`）

### Q4: 为什么某些阶段会记录 `missing_env` 决策

这是降级机制，表示对应可选环境不可用，系统将跳过该阶段并保留审计记录。

---

## 16. 许可证

见 `LICENSE`。

如果你用于受监管研发流程，建议把以下三类文件作为交付件归档：

- policy snapshot
- artifact manifest
- commands log
