# macro_lactone_toolkit

`macro_lactone_toolkit` 是一个用于 12-20 元大环内酯识别、canonical numbering、侧链裂解和拼接准备的 Python 工具包。

## 先看哪里

- 只想快速上手: [docs/index.md](docs/index.md)
- 只想看编号规则: [docs/user-guide/ring-numbering.md](docs/user-guide/ring-numbering.md)
- 只想看项目结构: [docs/development/project-structure.md](docs/development/project-structure.md)
- 只想看 agent 入口: [AGENTS.md](AGENTS.md)

## 渐进式入口

### 1. 先确认编号契约

这个仓库只有一套 canonical numbering：

- `1 = 内酯羰基碳`
- `2 = 相邻酯氧`
- `3..N = 从 2 位出发沿环唯一图遍历顺序继续编号`

对 16 元环，镜像映射是固定的：

- `3 → 16`
- `4 → 15`
- `5 → 14`
- `6 → 13`
- `7 → 12`
- `8 → 11`
- `9 → 10`
- `10 → 9`
- `11 → 8`
- `12 → 7`
- `13 → 6`
- `14 → 5`
- `15 → 4`
- `16 → 3`

这不是视觉顺时针/逆时针切换，公开 API 也不提供 `clockwise` / `anticlockwise` 参数。

### 2. 再看最小用法

```python
from macro_lactone_toolkit import MacroLactoneAnalyzer, MacrolactoneFragmenter

analyzer = MacroLactoneAnalyzer()
fragmenter = MacrolactoneFragmenter()

print(analyzer.get_valid_ring_sizes("O=C1CCCCCCCCCCCCCCO1"))
print(fragmenter.number_molecule("O=C1CCCCCCCCCCCCCCO1").position_to_atom)
```

```bash
pixi install
pixi run pytest
pixi run macro-lactone-toolkit analyze --smiles "O=C1CCCCCCCCCCCCCCO1"
pixi run macro-lactone-toolkit number --smiles "O=C1CCCCCCCCCCCCCCO1"
pixi run macro-lactone-toolkit fragment --smiles "O=C1CCCC(C)CCCCCCCCCCO1" --parent-id mol_001
```

### 3. 再深入到页面

- [docs/getting-started.md](docs/getting-started.md)
- [docs/user-guide/index.md](docs/user-guide/index.md)
- [docs/development/index.md](docs/development/index.md)

## 维护约束

- 根目录 `AGENTS.md` 是唯一权威 agent 入口。
- 入口文档只保留当前真实存在、持续维护的页面。
- 如果你要把药化文献里的镜像位置拿来对照，先按 canonical numbering 记账，再做镜像转换。