使用说明

Autonomous spectroscopy reasoning agent for chemists.


	SPEQTRO 将Agent AI封装到CLI工具中，帮助化学家从光谱数据中识别未知结构，预测化学位移，搜索参考数据库，并生成可重复的分析报告——所有这些都可以从终端完成。

特性

15个内置工具 横跨核磁共振、质谱、红外光谱、结构分析和数据库搜索
交互式REPL 使用斜线命令、光谱主题UI和会话分析
Web图形用户界面 — speqtro web 打开带有聊天、验证、预测和分析历史记录的浏览器界面
多格式输入 --JCAMP-DX、CSV峰值列表、布鲁克FID、MestReNova导出和图像
供应商提供的机器学习模型 --CASCADE（1H、13C预测）、ChefNMR（结构解析）、SSIN（红外光谱分类）、ICEBERG/ms-pred（ms/ms裂解）、DP4/DP5（结构验证）
一个命令权重下载 — speqtro fetch-weights 从HuggingFace中提取CASCADE、SSIN、DP5和ICEBERG
启发式回退 --使用加性增量规则和经验表的工具在没有ML模型的情况下工作
强制性引用 --每个结果都包括方法、数据来源和再现性参数

需求

Python 3.10–3.13
人类API

安装

pip（推荐）

pip install speqtro

带有可选附加功能

# With RDKit (structure drawing, SMILES validation)
pip install "speqtro[chemistry]"

# With web GUI
pip install "speqtro[web]"

# With MCP server support
pip install "speqtro[mcp]"

# With all ML backends (PyTorch + TensorFlow)
pip install "speqtro[all]"

pipx（隔离环境，无依赖冲突）

pipx install speqtro

# With extras
pipx install "speqtro[chemistry]"

开发/可编辑安装

git clone https://github.com/OhhMoo/SPEQTRO-Agent.git
cd SPEQTRO-Agent
pip install -e ".[dev,chemistry]"

工作流程

第一步——首次设置

安装后运行交互式向导。它保存了您的Anthropic API密钥，让您选择Claude模型（Opus用于最佳精度，Haiku用于速度），并验证您的环境。

speqtro setup

步骤2--下载ML模型权重

SPEQTRO会发送供应商提供的模型代码，但不会发送重量（对于git来说太大）。只需一个命令即可从HuggingFace中提取所有内容：

speqtro fetch-weights

这将CASCADE、SSIN、DP5和ICEBERG下载到 ~/.speqtro/models/。仅下载特定型号：

speqtro fetch-weights --model cascade2    # 13C NMR predictor
speqtro fetch-weights --model iceberg     # MS/MS fragmentation
speqtro fetch-weights --model ssin        # IR functional group classifier
speqtro fetch-weights --model dp5         # Bayesian NMR scoring
speqtro fetch-weights --model cascade1    # 1H NMR GNN
speqtro fetch-weights --model chefnmr    # NMR structure elucidation (S128 variants, ~8.6 GB)

ChefNMR 由于许可，HuggingFace上没有（核磁共振的结构说明）。从下载检查点泽诺多然后把它放进去 ~/Desktop/chefnmr/ 或 ~/.speqtro/models/chefnmr/，或显式配置它：
speqtro config set chefnmr.checkpoint /path/to/checkpoint.ckpt

步骤3——验证您的环境

speqtro doctor

这打印了一个完整的诊断：Python依赖项、加载的工具、ML模型权重状态（找到/丢失/路径）和API连接。检查CASCADE、SSIN、ICEBERG和DP5是否都显示 found 在运行分析之前。

示例场景

在REPL中：

speqtro
> I have an unknown compound. 1H NMR in CDCl3: 7.26 (s, 5H), 3.71 (s, 3H), 2.35 (s, 3H).
  13C: 170.5, 55.3, 21.2. What could this be?

完整的阐明流程运行：ChefNMR生成候选SMILES→ CASCADE根据您的13C数据对每个项目进行评分→ DP4启发式算法按概率排序→ 返回候选人排名表。

场景2：多光谱解析（NMR+IR+MS）

最强大的模式。你有核磁共振峰、红外光谱文件和LC-MS的MS/MS光谱。

speqtro
> Elucidate this compound:
  1H NMR (CDCl3): 7.35 (m, 5H), 5.12 (s, 2H), 3.72 (s, 3H)
  13C NMR: 171.2, 136.1, 128.5, 128.2, 128.0, 66.8, 52.1
  IR file: /data/compound1.jdx
  MS/MS precursor m/z 180.07, collision energy 20 eV,
  fragment ions: 149.0, 121.0, 105.0, 91.0, 77.0

SPEQTRO协调整个流程：

SSIN 读取IR文件→ 检测酯C=O，芳香族C-H
ChefNMR 从NMR峰生成10个候选结构
级联预测每个候选者的13C变化→ 计算MAD与观测值
DP4启发式 根据核磁共振概率对候选人进行排名
冰山预测每个候选人的MS/MS→ 余弦相似性与碎片离子
合奏评分 合并所有四个证据流→ 最终排名输出

场景3：在运行实验之前预测光谱

计划一个合成，并想在制作之前知道产品应该是什么样子：

# Predict all spectral handles for a target molecule
speqtro predict h1  --smiles "CC(=O)Oc1ccccc1C(=O)O"
speqtro predict c13 --smiles "CC(=O)Oc1ccccc1C(=O)O"
speqtro predict ir  --smiles "CC(=O)Oc1ccccc1C(=O)O"
speqtro predict ms  --smiles "CC(=O)Oc1ccccc1C(=O)O" --adduct "[M+H]+"

直接读取光谱文件

SPEQTRO可以解析仪器文件，而无需手动拾取峰值：

# Parse a JCAMP-DX NMR file and send to agent
speqtro --file spectrum.jdx "verify against aspirin"

# Parse a Bruker experiment directory
speqtro --file /data/bruker/1 "what functional groups are present?"

# Parse a MestReNova peak export CSV
speqtro --file peaks.csv "elucidate this structure"

Web图形用户界面

speqtro web

在以下位置打开基于浏览器的界面 http://127.0.0.1:8080 通过聊天、一键验证/预测和本地分析历史日志。需要 web 额外：

ML模型权重

供应商提供的型号代码包含在包装中。权重使用单独下载 speqtro fetch-weights （HuggingFace）或手动进行ChefNMR。

模型	任务	`fetch-weights`	配置键	环境变量
CASCADE 1.0	1H核磁共振预测（GNN）	`--model cascade1`	`cascade1.model_dir`	`SPEQ_CASCADE1_DIR`
CASCADE 2.0	13C核磁共振预测（GNN）	`--model cascade2`	`cascade.model_dir`	`SPEQ_CASCADE_DIR`
SSIN	IR官能团检测	`--model ssin`	`ssin.repo_dir`	`SPEQ_SSIN_DIR`
DP5	贝叶斯核磁共振评分	`--model dp5`	`dp5.repo_dir`	`SPEQ_DP5_DIR`
ICEBERG	MS/MS碎片化（DAG GNN）	`--model iceberg`	`mspred.gen_checkpoint`	`SPEQ_MSPRED_GEN_CKPT`
ChefNMR	NMR结构解析	`--model chefnmr`	`chefnmr.checkpoint`	`SPEQ_CHEFNMR_CKPT`

当权重不存在时，所有模型都会优雅地回归到启发式方法。

冰山使用两个检查点（生成器+强度预测器）。两者均已下载 fetch-weights --model iceberg 进入 ~/.speqtro/models/iceberg/ 并自动发现。无需手动配置路径。

ChefNMR 将涵盖所有车型系列（NP、SB、US）的四个S128（较小）检查点下载到 ~/.speqtro/models/chefnmr/ 并且被自动发现。要显式配置特定检查点，请执行以下操作：

speqtro config set chefnmr.checkpoint /path/to/checkpoint.ckpt

环境诊断

`speqtro doctor`

全面的诊断覆盖：Python依赖性、工具注册表、ML模型权重状态和Anthropic/PubChem API连接。

`speqtro pytorch`

PyTorch特定报告：版本、CUDA/MPS可用性、活动设备以及SSIN、ICEBERG和ChefNMR的重量状态。

`speqtro tf`

TensorFlow特定报告：CASCADE 1.0和2.0的版本、GPU设备、Keras、h5py和权重状态。

MCP服务器——使用Claude.ai、游标和VSCode中的speqtro

speqtro将其所有光谱工具作为 模型上下文协议（MCP）服务器 因此，您可以直接从Claude.ai、Cursor或VSCode Copilot Chat呼叫他们，而无需打开终端。

使用MCP支架进行安装

pip install "speqtro[mcp]"

可用命令

speqtro mcp list-tools                        # Print all tools as MCP JSON schema
speqtro mcp serve --stdio                     # stdio transport (Claude.ai / Cursor / Claude Code)
speqtro mcp serve --http                      # HTTP/SSE transport on 127.0.0.1:8765
speqtro mcp serve --http --host 0.0.0.0 --port 9000   # Custom host/port

克劳德代码

claude mcp add speqtro -- speqtro mcp serve --stdio

Claude.ai（桌面）

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "speqtro": {
      "command": "speqtro",
      "args": ["mcp", "serve", "--stdio"]
    }
  }
}

光标

添加 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "speqtro": {
      "command": "speqtro",
      "args": ["mcp", "serve", "--stdio"]
    }
  }
}

VSCode副驾驶聊天

添加 .vscode/mcp.json 在您的工作空间中：

{
  "servers": {
    "speqtro": {
      "type": "stdio",
      "command": "speqtro",
      "args": ["mcp", "serve", "--stdio"]
    }
  }
}

建筑

CLI (Typer) → Agent Loop (Claude Agent SDK) → Tool Registry → 15 Tool Modules
                                                             → 6 Vendored ML Models
Web GUI (Starlette) → AgentRunner (SSE streaming) → Tool Registry
MCP Server → Tool Registry

目录结构

src/speqtro/
├── cli.py                 # Typer entry point + all CLI commands
├── agent/                 # Claude Agent SDK agentic loop
│   ├── loop.py            # Agentic reasoning loop
│   ├── runner.py          # Agent execution (Claude Agent SDK)
│   ├── mcp_server.py      # Model Context Protocol server
│   ├── config.py          # Config (~/.speqtro/config.json)
│   ├── api_check.py       # API connectivity probes
│   └── ...
├── input/                 # Spectral format parsers
│   ├── jcamp.py           # JCAMP-DX
│   ├── csv_peaks.py       # CSV peak lists
│   ├── bruker.py          # Bruker FID
│   ├── autodetect.py      # Format auto-detection
│   └── ...
├── modes/                 # Analysis pipelines
│   ├── verify.py          # VERIFY / EXPLORE pipelines
│   └── pipeline.py        # Full multi-spectroscopy elucidation
├── tools/                 # Tool registry (15 tools)
│   ├── nmr.py             # 1H/13C prediction, JCAMP parsing
│   ├── ms.py              # Exact mass, fragmentation, formula search
│   ├── ir.py              # IR absorption prediction
│   ├── structure.py       # SMILES→formula
│   ├── database.py        # PubChem search
│   ├── cascade.py         # CASCADE 13C predictor
│   ├── chefnmr.py         # ChefNMR elucidation
│   ├── ssin.py            # SSIN IR classifier
│   ├── mspred.py          # ICEBERG MS/MS predictor
│   └── dp5.py             # DP4 structure scoring
├── ui/                    # Terminal interface
│   ├── terminal.py        # Interactive REPL
│   ├── status.py          # Animated thinking spinner
│   └── markdown.py        # Markdown renderer
├── web/                   # Browser-based GUI
│   ├── server.py          # Starlette web server + REST/SSE API
│   ├── leaderboard.py     # SQLite analysis history (~/.speqtro/leaderboard.db)
│   └── static/            # index.html + logo assets
└── vendors/               # Vendored ML model code + weights
    ├── cascade/            # 13C NMR (TensorFlow/kgcnn)
    ├── cascade1/           # 1H NMR (TensorFlow/kgcnn)
    ├── chefnmr/            # Structure elucidation (PyTorch)
    ├── dp5/                # DP4/DP5 scoring (pure SciPy)
    ├── ssin/               # IR classification (PyTorch)
    └── mspred/             # ICEBERG MS/MS fragmentation (PyTorch/DGL)

测试

pip install -e ".[dev]"
pytest

34个单元测试涵盖了启发式工具套件（核磁共振预测、质量计算、红外吸收、裂解、公式搜索）。

许可证

麻省理工学院——见许可证.

第三方通知

SPEQTRO供应商从几个开源机器学习项目中编写代码。看第三方通知和 CITATIONS.md 以获得完整的归属。