merge-cli 1.0.0__tar.gz

merge_cli-1.0.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: merge-cli
+Version: 1.0.0
+Summary: CLI for MERGE variant pathogenicity prediction
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1
+Requires-Dist: requests>=2.31
+Requires-Dist: rich>=13.0
+Requires-Dist: keyring>=24.0
+
+# MERGE CLI
+
+MERGE 变异致病性预测命令行工具。所有计算在服务器端完成，本地只需 Python 3.9+。
+
+## 安装
+
+```bash
+pip install merge-cli
+```
+
+## 快速开始
+
+```bash
+# 1. 配置服务器地址（只需配置一次）
+merge config set-url https://your-server.com
+merge config set-token YOUR_API_TOKEN
+
+# 2. 单变异预测
+merge predict --chrom chr17 --pos 43092919 --ref A --alt G
+
+# 3. 批量预测（上传 VCF，结果发邮件）
+merge batch my_variants.vcf --email you@example.com
+```
+
+## 命令详解
+
+### `merge predict` — 单变异预测
+
+```
+选项：
+  --chrom     染色体（chr17 或 17 均可）   [必填]
+  --pos       变异位置（1-based）           [必填]
+  --ref       参考碱基                      [必填]
+  --alt       突变碱基                      [必填]
+  --genome    hg38 / hg19                  [默认: hg38]
+  --format    table / json / tsv           [默认: table]
+  --no-ensemble   跳过 MERGE 集成打分
+  --no-alphagenome / --no-hyenadna / --no-nt
+  --no-alphamissense / --no-esm1b / --no-gpn-msa
+  --no-popeve / --no-evo2 / --no-evo1
+```
+
+**输出示例（table 模式）：**
+
+```
+╭──────────────────────────────────────────╮
+│          MERGE 预测结果                   │
+├──────────────────┬───────────────────────┤
+│ 变异位点         │ chr17:43092919 A → G  │
+│ 基因 / 转录本    │ BRCA1 / ENST00000357654│
+├──────────────────┼───────────────────────┤
+│ MERGE 致病性     │ 87.3%  Likely Pathogenic│
+│ 使用模型         │ ClinVar               │
+├──────────────────┼───────────────────────┤
+│ AlphaMissense    │ 0.9341                │
+│ ESM1b            │ -3.2180               │
+│ GPN-MSA          │ -1.4420               │
+│ popEVE           │ 0.8812                │
+│ AlphaGenome      │ 0.0234                │
+│ HyenaDNA         │ -2.1100               │
+│ NT               │ -1.8830               │
+│ Evo2 LLR         │ -4.2210               │
+│ Evo1 Delta       │ -3.9910               │
+╰──────────────────┴───────────────────────╯
+```
+
+**管道输出（TSV 模式，方便写脚本）：**
+
+```bash
+merge predict --chrom chr17 --pos 43092919 --ref A --alt G --format tsv >> results.tsv
+```
+
+**脚本批量调用单变异（小于 20 个时比上传 VCF 更快）：**
+
+```bash
+while IFS=$'\t' read -r chrom pos ref alt; do
+    merge predict --chrom "$chrom" --pos "$pos" --ref "$ref" --alt "$alt" --format tsv
+done < variants.tsv >> results.tsv
+```
+
+---
+
+### `merge batch` — 批量 VCF 预测
+
+```bash
+merge batch variants.vcf --email you@example.com
+merge batch variants.vcf.gz --email you@example.com --genome hg19 --no-evo2
+```
+
+任务提交成功后返回 Job ID，结果通过邮件发送，附件包含：
+- `batch_predictions.csv`  — 所有模型分数汇总（可直接用 Excel 打开）
+- `batch_predictions.vcf`  — 标准 VCF 格式，含 MERGE 及各模型分数
+- `imputation_details.csv` — MERGE 各特征缺失填补情况
+
+服务端限制：每 IP 每日 5 次，同一邮箱间隔 1 小时，单次最多 2000 个变异。
+
+---
+
+### `merge status` — 查询批量任务
+
+```bash
+merge status A3F2C1B0          # 查看一次
+merge status A3F2C1B0 --watch  # 每 30 秒轮询
+```
+
+---
+
+## 环境变量（适合 CI / 服务器环境）
+
+```bash
+export MERGE_API_URL=https://your-server.com
+export MERGE_API_TOKEN=your-token
+merge predict --chrom chr1 --pos 100000 --ref C --alt T
+```

merge_cli-1.0.0/README.md

@@ -0,0 +1,114 @@
+# MERGE CLI
+
+MERGE 变异致病性预测命令行工具。所有计算在服务器端完成，本地只需 Python 3.9+。
+
+## 安装
+
+```bash
+pip install merge-cli
+```
+
+## 快速开始
+
+```bash
+# 1. 配置服务器地址（只需配置一次）
+merge config set-url https://your-server.com
+merge config set-token YOUR_API_TOKEN
+
+# 2. 单变异预测
+merge predict --chrom chr17 --pos 43092919 --ref A --alt G
+
+# 3. 批量预测（上传 VCF，结果发邮件）
+merge batch my_variants.vcf --email you@example.com
+```
+
+## 命令详解
+
+### `merge predict` — 单变异预测
+
+```
+选项：
+  --chrom     染色体（chr17 或 17 均可）   [必填]
+  --pos       变异位置（1-based）           [必填]
+  --ref       参考碱基                      [必填]
+  --alt       突变碱基                      [必填]
+  --genome    hg38 / hg19                  [默认: hg38]
+  --format    table / json / tsv           [默认: table]
+  --no-ensemble   跳过 MERGE 集成打分
+  --no-alphagenome / --no-hyenadna / --no-nt
+  --no-alphamissense / --no-esm1b / --no-gpn-msa
+  --no-popeve / --no-evo2 / --no-evo1
+```
+
+**输出示例（table 模式）：**
+
+```
+╭──────────────────────────────────────────╮
+│          MERGE 预测结果                   │
+├──────────────────┬───────────────────────┤
+│ 变异位点         │ chr17:43092919 A → G  │
+│ 基因 / 转录本    │ BRCA1 / ENST00000357654│
+├──────────────────┼───────────────────────┤
+│ MERGE 致病性     │ 87.3%  Likely Pathogenic│
+│ 使用模型         │ ClinVar               │
+├──────────────────┼───────────────────────┤
+│ AlphaMissense    │ 0.9341                │
+│ ESM1b            │ -3.2180               │
+│ GPN-MSA          │ -1.4420               │
+│ popEVE           │ 0.8812                │
+│ AlphaGenome      │ 0.0234                │
+│ HyenaDNA         │ -2.1100               │
+│ NT               │ -1.8830               │
+│ Evo2 LLR         │ -4.2210               │
+│ Evo1 Delta       │ -3.9910               │
+╰──────────────────┴───────────────────────╯
+```
+
+**管道输出（TSV 模式，方便写脚本）：**
+
+```bash
+merge predict --chrom chr17 --pos 43092919 --ref A --alt G --format tsv >> results.tsv
+```
+
+**脚本批量调用单变异（小于 20 个时比上传 VCF 更快）：**
+
+```bash
+while IFS=$'\t' read -r chrom pos ref alt; do
+    merge predict --chrom "$chrom" --pos "$pos" --ref "$ref" --alt "$alt" --format tsv
+done < variants.tsv >> results.tsv
+```
+
+---
+
+### `merge batch` — 批量 VCF 预测
+
+```bash
+merge batch variants.vcf --email you@example.com
+merge batch variants.vcf.gz --email you@example.com --genome hg19 --no-evo2
+```
+
+任务提交成功后返回 Job ID，结果通过邮件发送，附件包含：
+- `batch_predictions.csv`  — 所有模型分数汇总（可直接用 Excel 打开）
+- `batch_predictions.vcf`  — 标准 VCF 格式，含 MERGE 及各模型分数
+- `imputation_details.csv` — MERGE 各特征缺失填补情况
+
+服务端限制：每 IP 每日 5 次，同一邮箱间隔 1 小时，单次最多 2000 个变异。
+
+---
+
+### `merge status` — 查询批量任务
+
+```bash
+merge status A3F2C1B0          # 查看一次
+merge status A3F2C1B0 --watch  # 每 30 秒轮询
+```
+
+---
+
+## 环境变量（适合 CI / 服务器环境）
+
+```bash
+export MERGE_API_URL=https://your-server.com
+export MERGE_API_TOKEN=your-token
+merge predict --chrom chr1 --pos 100000 --ref C --alt T
+```

merge_cli-1.0.0/merge_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

merge_cli-1.0.0/merge_cli/api.py

@@ -0,0 +1,190 @@
+"""
+merge_cli/api.py
+封装所有对 Django 后端的 HTTP 请求。
+每个函数对应 views.py 里的一个端点，参数名与 views.py 完全一致。
+"""
+import sys
+from typing import Optional
+
+import requests
+
+from .config import get_api_url, get_token
+
+# 所有请求的默认超时（秒）
+_TIMEOUT_SINGLE = 180   # 单变异：Evo2 最慢，约 2 分钟
+_TIMEOUT_BATCH  = 60    # 批量提交：只是上传文件，后台异步处理
+
+
+def _headers() -> dict:
+    token = get_token()
+    h = {"Accept": "application/json"}
+    if token:
+        h["Authorization"] = f"Token {token}"
+    return h
+
+
+def _base() -> str:
+    url = get_api_url()
+    if not url:
+        print("错误：未配置 API 地址。请先运行：merge config set-url https://your-server.com")
+        sys.exit(1)
+    return url
+
+
+# ─────────────────────────────────────────────────────────────
+# 1. 单变异预测  POST /predict/
+# 对应 views.py: combined_prediction_view
+# ─────────────────────────────────────────────────────────────
+def predict_single(
+    chrom: str, pos: int, ref: str, alt: str,
+    genome_version: str = "hg38",
+    # 模型开关，与 views.py POST 参数名一一对应
+    use_alphagenome:   bool = True,
+    use_hyenadna:      bool = True,
+    use_nt:            bool = True,
+    use_alphamissense: bool = True,
+    use_esm1b:         bool = True,
+    use_gpn_msa:       bool = True,
+    use_popeve:        bool = True,
+    use_evo2:          bool = True,
+    use_evo1:          bool = True,
+) -> dict:
+    """
+    调用 /predict/ 端点，返回完整 prediction 字典。
+    包含 dbnsfp / alphagenome / hyenadna / nt / gpn_msa / popeve / evo2 / evo1 / errors。
+    """
+    payload = {
+        "chrom": chrom, "pos": pos, "ref": ref, "alt": alt,
+        "genome_version": genome_version,
+        "use_alphagenome":   str(use_alphagenome).lower(),
+        "use_hyenadna":      str(use_hyenadna).lower(),
+        "use_nt":            str(use_nt).lower(),
+        "use_alphamissense": str(use_alphamissense).lower(),
+        "use_esm1b":         str(use_esm1b).lower(),
+        "use_gpn_msa":       str(use_gpn_msa).lower(),
+        "use_popeve":        str(use_popeve).lower(),
+        "use_evo2":          str(use_evo2).lower(),
+        "use_evo1":          str(use_evo1).lower(),
+    }
+    resp = requests.post(
+        f"{_base()}/predict/",
+        json=payload,
+        headers=_headers(),
+        timeout=_TIMEOUT_SINGLE,
+    )
+    resp.raise_for_status()
+    return resp.json()
+
+
+# ─────────────────────────────────────────────────────────────
+# 2. 集成模型评分  POST /ensemble/
+# 对应 views.py: ensemble_predict_view
+# 通常在 predict_single 成功后自动调用
+# ─────────────────────────────────────────────────────────────
+def predict_ensemble(prediction: dict, all_transcripts: list) -> dict:
+    """
+    用 /predict/ 返回的 prediction 字典再调用 /ensemble/，
+    获取 MERGE 集成得分和 SHAP 图（base64 PNG）。
+    """
+    payload = {"prediction": prediction, "all_transcripts": all_transcripts}
+    resp = requests.post(
+        f"{_base()}/ensemble/",
+        json=payload,
+        headers=_headers(),
+        timeout=_TIMEOUT_SINGLE,
+    )
+    resp.raise_for_status()
+    return resp.json()
+
+
+# ─────────────────────────────────────────────────────────────
+# 3. 批量提交  POST /api/submit_batch_job/
+# 对应 views.py: submit_batch_job
+# ─────────────────────────────────────────────────────────────
+def submit_batch(
+    vcf_path: str,
+    email: str,
+    genome_version: str = "hg38",
+    use_alphagenome:   bool = True,
+    use_hyenadna:      bool = True,
+    use_nt:            bool = True,
+    use_alphamissense: bool = True,
+    use_esm1b:         bool = True,
+    use_gpn_msa:       bool = True,
+    use_popeve:        bool = True,
+    use_evo2:          bool = True,
+    use_evo1:          bool = True,
+) -> dict:
+    """
+    上传 VCF 文件，异步批量预测，结果发送至 email。
+    返回 job_id 供后续查询状态。
+    """
+    data = {
+        "notify_email":    email,
+        "genome_version":  genome_version,
+        "use_alphagenome":   str(use_alphagenome).lower(),
+        "use_hyenadna":      str(use_hyenadna).lower(),
+        "use_nt":            str(use_nt).lower(),
+        "use_alphamissense": str(use_alphamissense).lower(),
+        "use_esm1b":         str(use_esm1b).lower(),
+        "use_gpn_msa":       str(use_gpn_msa).lower(),
+        "use_popeve":        str(use_popeve).lower(),
+        "use_evo2":          str(use_evo2).lower(),
+        "use_evo1":          str(use_evo1).lower(),
+    }
+    with open(vcf_path, "rb") as f:
+        resp = requests.post(
+            f"{_base()}/api/submit_batch_job/",
+            data=data,
+            files={"vcf_file": (vcf_path.split("/")[-1], f)},
+            headers=_headers(),
+            timeout=_TIMEOUT_BATCH,
+        )
+    resp.raise_for_status()
+    return resp.json()
+
+
+# ─────────────────────────────────────────────────────────────
+# 4. 查询批量任务状态  GET /api/batch_job/<job_id>/
+# 对应 views.py: batch_job_status
+# ─────────────────────────────────────────────────────────────
+def get_batch_status(job_id: str) -> dict:
+    resp = requests.get(
+        f"{_base()}/api/batch_job/{job_id}/",
+        headers=_headers(),
+        timeout=30,
+    )
+    resp.raise_for_status()
+    return resp.json()
+
+
+# ─────────────────────────────────────────────────────────────
+# 5. 开放注册  POST /api/register/
+# 对应 views.py: register_and_get_token
+# 公开接口，不需要携带 Token
+# ─────────────────────────────────────────────────────────────
+def register(username: str, email: str, password: str) -> dict:
+    resp = requests.post(
+        f"{_base()}/api/register/",
+        json={"username": username, "email": email, "password": password},
+        headers={"Content-Type": "application/json", "Accept": "application/json"},
+        timeout=30,
+    )
+    resp.raise_for_status()
+    return resp.json()
+
+
+# ─────────────────────────────────────────────────────────────
+# 6. 已有账号重新登录取 Token  POST /api/login/
+# 对应 views.py: login_and_get_token
+# 公开接口，不需要携带 Token
+# ─────────────────────────────────────────────────────────────
+def login(username: str, password: str) -> dict:
+    resp = requests.post(
+        f"{_base()}/api/login/",
+        json={"username": username, "password": password},
+        headers={"Content-Type": "application/json", "Accept": "application/json"},
+        timeout=30,
+    )
+    resp.raise_for_status()
+    return resp.json()

merge_cli-1.0.0/merge_cli/cli.py

@@ -0,0 +1,318 @@
+"""
+merge_cli/cli.py
+CLI 入口，四条主命令：
+  merge config   — 配置 API 地址和 Token
+  merge predict  — 单变异预测
+  merge batch    — 批量 VCF 提交
+  merge status   — 查询批量任务进度
+"""
+import sys
+import click
+from rich.console import Console
+
+from . import api, output
+from .config import get_api_url, get_token, set_api_url, set_token, show_config
+
+console = Console()
+
+# ── 全局模型开关选项（两条命令共用）────────────────────────────
+_MODEL_OPTIONS = [
+    click.option("--no-alphagenome",   is_flag=True, default=False, help="跳过 AlphaGenome"),
+    click.option("--no-hyenadna",      is_flag=True, default=False, help="跳过 HyenaDNA"),
+    click.option("--no-nt",            is_flag=True, default=False, help="跳过 Nucleotide Transformer"),
+    click.option("--no-alphamissense", is_flag=True, default=False, help="跳过 AlphaMissense"),
+    click.option("--no-esm1b",         is_flag=True, default=False, help="跳过 ESM1b"),
+    click.option("--no-gpn-msa",       is_flag=True, default=False, help="跳过 GPN-MSA"),
+    click.option("--no-popeve",        is_flag=True, default=False, help="跳过 popEVE"),
+    click.option("--no-evo2",          is_flag=True, default=False, help="跳过 Evo2"),
+    click.option("--no-evo1",          is_flag=True, default=False, help="跳过 Evo1"),
+]
+
+def _add_model_options(f):
+    for opt in reversed(_MODEL_OPTIONS):
+        f = opt(f)
+    return f
+
+def _model_flags(**kwargs) -> dict:
+    """把 --no-xxx 转成 use_xxx=True/False 传给 api 层。"""
+    return {
+        "use_alphagenome":   not kwargs.get("no_alphagenome",   False),
+        "use_hyenadna":      not kwargs.get("no_hyenadna",      False),
+        "use_nt":            not kwargs.get("no_nt",            False),
+        "use_alphamissense": not kwargs.get("no_alphamissense", False),
+        "use_esm1b":         not kwargs.get("no_esm1b",         False),
+        "use_gpn_msa":       not kwargs.get("no_gpn_msa",       False),
+        "use_popeve":        not kwargs.get("no_popeve",        False),
+        "use_evo2":          not kwargs.get("no_evo2",          False),
+        "use_evo1":          not kwargs.get("no_evo1",          False),
+    }
+
+
+# ─────────────────────────────────────────────────────────────
+# 根命令
+# ─────────────────────────────────────────────────────────────
+@click.group()
+@click.version_option("1.0.0", prog_name="merge")
+def cli():
+    """MERGE 变异致病性预测 CLI
+
+    快速开始：
+
+    \b
+      merge config set-url https://your-server.com
+      merge config set-token YOUR_API_TOKEN
+      merge predict --chrom chr17 --pos 43092919 --ref A --alt G
+    """
+
+
+# ─────────────────────────────────────────────────────────────
+# merge config
+# ─────────────────────────────────────────────────────────────
+@cli.group()
+def config():
+    """管理 API 地址和认证 Token。"""
+
+
+@config.command("set-url")
+@click.argument("url")
+def config_set_url(url: str):
+    """设置 API 服务器地址，例如 https://your-server.com"""
+    set_api_url(url)
+    console.print(f"[green]✓[/green] API 地址已保存：{url}")
+
+
+@config.command("set-token")
+@click.argument("token")
+def config_set_token(token: str):
+    """设置 API 认证 Token（保存在系统 keyring，不写入配置文件）"""
+    set_token(token)
+    console.print("[green]✓[/green] Token 已保存。")
+
+
+@config.command("show")
+def config_show():
+    """查看当前配置。"""
+    info = show_config()
+    console.print(f"  API 地址    : [bold]{info['api_url']}[/bold]")
+    console.print(f"  Token       : [bold]{info['token']}[/bold]")
+    console.print(f"  配置文件    : [dim]{info['config_file']}[/dim]")
+
+
+# ─────────────────────────────────────────────────────────────
+# merge predict
+# ─────────────────────────────────────────────────────────────
+@cli.command()
+@click.option("--chrom",   required=True,  help="染色体，如 chr17 或 17")
+@click.option("--pos",     required=True,  type=int, help="变异位置（1-based）")
+@click.option("--ref",     required=True,  help="参考碱基，如 A")
+@click.option("--alt",     required=True,  help="突变碱基，如 G")
+@click.option("--genome",  default="hg38", show_default=True,
+              type=click.Choice(["hg38", "hg19"]), help="参考基因组版本")
+@click.option("--format",  "fmt",
+              default="table", show_default=True,
+              type=click.Choice(["table", "json", "tsv"]),
+              help="输出格式：table（彩色表格）/ json / tsv")
+@click.option("--no-ensemble", is_flag=True, default=False,
+              help="跳过 MERGE 集成打分（只返回各模型原始分数）")
+@_add_model_options
+def predict(chrom, pos, ref, alt, genome, fmt, no_ensemble, **kwargs):
+    """单变异致病性预测。
+
+    \b
+    示例：
+      merge predict --chrom chr17 --pos 43092919 --ref A --alt G
+      merge predict --chrom chr17 --pos 43092919 --ref A --alt G --genome hg19
+      merge predict --chrom chr1  --pos 100000   --ref C --alt T --no-evo2 --no-evo1
+      merge predict --chrom chr1  --pos 100000   --ref C --alt T --format json > result.json
+      merge predict --chrom chr1  --pos 100000   --ref C --alt T --format tsv  >> results.tsv
+    """
+    flags = _model_flags(**kwargs)
+
+    # 规范化 chrom（兼容用户输入 17 或 chr17）
+    if not chrom.startswith("chr"):
+        chrom = "chr" + chrom
+
+    with console.status("[bold cyan]正在预测…[/bold cyan]"):
+        try:
+            resp = api.predict_single(chrom, pos, ref, alt, genome, **flags)
+        except Exception as e:
+            console.print(f"[red]预测失败：{e}[/red]")
+            sys.exit(1)
+
+    if not resp.get("success"):
+        console.print(f"[red]服务端错误：{resp.get('error')}[/red]")
+        details = resp.get("details", {})
+        for src, msg in details.items():
+            console.print(f"  [dim]{src}: {msg}[/dim]")
+        sys.exit(1)
+
+    prediction = resp["prediction"]
+    ensemble   = None
+
+    if not no_ensemble:
+        with console.status("[bold cyan]正在计算 MERGE 集成分数…[/bold cyan]"):
+            try:
+                # 用 dbnsfp 构造最简单的 all_transcripts
+                dbnsfp = prediction.get("dbnsfp") or {}
+                transcripts = [dbnsfp] if dbnsfp else []
+                ens_resp = api.predict_ensemble(prediction, transcripts)
+                if ens_resp.get("success"):
+                    ensemble = ens_resp
+            except Exception as e:
+                console.print(f"[yellow]MERGE 集成分数获取失败（不影响原始分数）：{e}[/yellow]")
+
+    output.render_single(prediction, ensemble, fmt=fmt, errors=prediction.get("errors"))
+
+
+# ─────────────────────────────────────────────────────────────
+# merge batch
+# ─────────────────────────────────────────────────────────────
+@cli.command()
+@click.argument("vcf_file", type=click.Path(exists=True))
+@click.option("--email",    required=True,  help="结果发送邮箱（必填）")
+@click.option("--genome",   default="hg38", show_default=True,
+              type=click.Choice(["hg38", "hg19"]))
+@_add_model_options
+def batch(vcf_file, email, genome, **kwargs):
+    """批量 VCF 文件预测（异步，结果通过邮件发送）。
+
+    \b
+    服务器限制（由 views.py 中 RATE_LIMIT_CONFIG 控制）：
+      - 每个 IP 每日最多 5 次异步任务
+      - 同一邮箱两次提交间隔 ≥ 1 小时
+      - 单次最多 2000 个变异
+
+    \b
+    示例：
+      merge batch variants.vcf --email you@example.com
+      merge batch variants.vcf.gz --email you@example.com --genome hg19 --no-evo2
+    """
+    flags = _model_flags(**kwargs)
+
+    with console.status("[bold cyan]上传 VCF 文件…[/bold cyan]"):
+        try:
+            resp = api.submit_batch(vcf_file, email, genome, **flags)
+        except Exception as e:
+            console.print(f"[red]提交失败：{e}[/red]")
+            sys.exit(1)
+
+    if not resp.get("success"):
+        console.print(f"[red]提交失败：{resp.get('error')}[/red]")
+        sys.exit(1)
+
+    output.render_batch_submitted(resp["job_id"], email)
+
+
+# ─────────────────────────────────────────────────────────────
+# merge register
+# ─────────────────────────────────────────────────────────────
+@cli.command()
+@click.option("--username", prompt="用户名", help="3-30 位，字母/数字/_/-/.")
+@click.option("--email",    prompt="邮箱")
+@click.option("--password", prompt="密码", hide_input=True, confirmation_prompt="再次输入密码确认")
+def register(username, email, password):
+    """注册账号并自动保存 Token，注册后即可直接使用。
+
+    \b
+    示例：
+      merge register
+      merge register --username alice --email alice@lab.com --password MyPass123!
+    """
+    if not get_api_url():
+        console.print("[red]错误：请先配置服务器地址：[/red]")
+        console.print("  merge config set-url https://your-server.com")
+        raise SystemExit(1)
+
+    with console.status("[bold cyan]注册中…[/bold cyan]"):
+        try:
+            resp = api.register(username, email, password)
+        except Exception as e:
+            console.print(f"[red]注册失败：{e}[/red]")
+            raise SystemExit(1)
+
+    if not resp.get("success"):
+        console.print(f"[red]注册失败：{resp.get('error')}[/red]")
+        raise SystemExit(1)
+
+    # 自动保存 Token，用户无需手动 set-token
+    token = resp["token"]
+    set_token(token)
+
+    console.print(f"\n[bold green]✓ 注册成功！[/bold green]")
+    console.print(f"  用户名 : [bold]{username}[/bold]")
+    console.print(f"  Token  : [dim]{token[:8]}…[/dim]（已自动保存）")
+    console.print(f"\n现在可以直接开始使用：")
+    console.print(f"  [bold]merge predict --chrom chr17 --pos 43092919 --ref A --alt G[/bold]")
+
+
+# ─────────────────────────────────────────────────────────────
+# merge login  （已有账号，重新获取 Token）
+# ─────────────────────────────────────────────────────────────
+@cli.command()
+@click.option("--username", prompt="用户名")
+@click.option("--password", prompt="密码", hide_input=True)
+def login(username, password):
+    """已有账号时重新获取并保存 Token。
+
+    \b
+    示例：
+      merge login
+      merge login --username alice --password MyPass123!
+    """
+    if not get_api_url():
+        console.print("[red]错误：请先配置服务器地址：[/red]")
+        console.print("  merge config set-url https://your-server.com")
+        raise SystemExit(1)
+
+    with console.status("[bold cyan]登录中…[/bold cyan]"):
+        try:
+            resp = api.login(username, password)
+        except Exception as e:
+            console.print(f"[red]登录失败：{e}[/red]")
+            raise SystemExit(1)
+
+    if not resp.get("success"):
+        console.print(f"[red]登录失败：{resp.get('error')}[/red]")
+        raise SystemExit(1)
+
+    set_token(resp["token"])
+    console.print(f"[bold green]✓ 登录成功，Token 已更新。[/bold green]")
+
+
+# ─────────────────────────────────────────────────────────────
+# merge status
+# ─────────────────────────────────────────────────────────────
+@cli.command()
+@click.argument("job_id")
+@click.option("--watch", is_flag=True, default=False,
+              help="每 30 秒轮询一次，直到任务完成")
+def status(job_id, watch):
+    """查询批量任务状态。
+
+    \b
+    示例：
+      merge status A3F2C1B0
+      merge status A3F2C1B0 --watch
+    """
+    import time
+
+    def _poll():
+        try:
+            data = api.get_batch_status(job_id)
+        except Exception as e:
+            console.print(f"[red]查询失败：{e}[/red]")
+            return None
+        output.render_status(data)
+        return data
+
+    data = _poll()
+    if not watch or not data:
+        return
+
+    while data and data.get("status") == "processing":
+        console.print("\n[dim]30 秒后再次查询… Ctrl+C 退出[/dim]")
+        try:
+            time.sleep(30)
+        except KeyboardInterrupt:
+            break
+        data = _poll()

merge_cli-1.0.0/merge_cli/config.py

@@ -0,0 +1,71 @@
+"""
+merge_cli/config.py
+管理 API 地址和 Token 的持久化存储。
+Token 优先级：命令行 --token > 环境变量 MERGE_API_TOKEN > keyring 存储
+"""
+import os
+import json
+from pathlib import Path
+
+import keyring
+
+_SERVICE = "merge-cli"
+_CONFIG_FILE = Path.home() / ".config" / "merge-cli" / "config.json"
+
+
+def _load_file() -> dict:
+    if _CONFIG_FILE.exists():
+        try:
+            return json.loads(_CONFIG_FILE.read_text())
+        except Exception:
+            pass
+    return {}
+
+
+def _save_file(data: dict) -> None:
+    _CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True)
+    _CONFIG_FILE.write_text(json.dumps(data, indent=2))
+
+
+def get_api_url() -> str:
+    env = os.environ.get("MERGE_API_URL")
+    if env:
+        return env.rstrip("/")
+    cfg = _load_file()
+    return cfg.get("api_url", "").rstrip("/")
+
+
+def set_api_url(url: str) -> None:
+    cfg = _load_file()
+    cfg["api_url"] = url.rstrip("/")
+    _save_file(cfg)
+
+
+def get_token() -> str:
+    env = os.environ.get("MERGE_API_TOKEN")
+    if env:
+        return env
+    try:
+        tok = keyring.get_password(_SERVICE, "token")
+        return tok or ""
+    except Exception:
+        cfg = _load_file()
+        return cfg.get("token", "")
+
+
+def set_token(token: str) -> None:
+    try:
+        keyring.set_password(_SERVICE, "token", token)
+    except Exception:
+        # keyring 不可用时回退到配置文件
+        cfg = _load_file()
+        cfg["token"] = token
+        _save_file(cfg)
+
+
+def show_config() -> dict:
+    return {
+        "api_url": get_api_url() or "(未设置)",
+        "token":   ("***" + get_token()[-4:]) if get_token() else "(未设置)",
+        "config_file": str(_CONFIG_FILE),
+    }

merge_cli-1.0.0/merge_cli/output.py

@@ -0,0 +1,202 @@
+"""
+merge_cli/output.py
+把 API 返回的原始 JSON 渲染成三种格式：
+  - table  : Rich 彩色表格（终端默认）
+  - json   : 紧凑 JSON（管道/脚本用）
+  - tsv    : 制表符分隔（直接导入 Excel / R / Python）
+字段来源完全对应 views.py 里 batch_predictions.csv 的列定义。
+"""
+import json as _json
+import sys
+from typing import Optional
+
+from rich.console import Console
+from rich.table import Table
+from rich import box
+from rich.text import Text
+
+console = Console()
+
+
+# ─── 颜色映射（对应 ensemble_predict.py: interpret_score 返回的 label）───
+_LABEL_STYLE = {
+    "Pathogenic":         "bold red",
+    "Likely Pathogenic":  "red",
+    "Uncertain":          "yellow",
+    "Likely Benign":      "green",
+    "Benign":             "bold green",
+}
+
+
+def _fmt(val, decimals: int = 4) -> str:
+    """把 None / 'N/A' / float 统一格式化为字符串。"""
+    if val is None or val in ("N/A", ".", ""):
+        return "-"
+    try:
+        return f"{float(val):.{decimals}f}"
+    except (ValueError, TypeError):
+        return str(val)
+
+
+def _score_text(score: Optional[float], label: Optional[str]) -> Text:
+    """把 MERGE 分数 + 解读标签合并成带颜色的 Rich Text。"""
+    if score is None:
+        return Text("-", style="dim")
+    pct = f"{score * 100:.1f}%"
+    style = _LABEL_STYLE.get(label or "", "white")
+    t = Text(pct, style=style)
+    if label:
+        t.append(f"  {label}", style=style)
+    return t
+
+
+def _extract_flat(prediction: dict, ensemble: Optional[dict] = None) -> dict:
+    """
+    把 /predict/ + /ensemble/ 的嵌套 JSON 压平成一行字典，
+    字段顺序与 batch_predictions.csv 的列头一致。
+    """
+    inp   = prediction.get("input", {})
+    db    = prediction.get("dbnsfp") or {}
+    ann   = db.get("annotations") or {}
+    dlm   = db.get("dl_models") or {}
+    ag    = prediction.get("alphagenome") or {}
+    hy    = prediction.get("hyenadna") or {}
+    nt    = prediction.get("nt") or {}
+    gpn   = prediction.get("gpn_msa") or {}
+    pop   = prediction.get("popeve") or {}
+    evo2  = prediction.get("evo2") or {}
+    evo1  = prediction.get("evo1") or {}
+
+    # ensemble 分数
+    ens_score = ens_label = ens_model = None
+    if ensemble:
+        for _key, _val in ensemble.get("ensemble_results", {}).items():
+            ens_score = _val.get("score")
+            ens_label = (_val.get("interpretation") or {}).get("label")
+            ens_model = _key
+            break
+
+    return {
+        "Chr":                inp.get("chrom", ann.get("chr", "-")),
+        "Pos":                inp.get("pos", ann.get("pos", "-")),
+        "Ref":                inp.get("ref", ann.get("ref", "-")),
+        "Alt":                inp.get("alt", ann.get("alt", "-")),
+        "Gene":               ann.get("genename", "-"),
+        "Transcript":         ann.get("Ensembl_transcriptid", "-"),
+        "MERGE_Score":        ens_score,
+        "MERGE_Label":        ens_label,
+        "MERGE_Model":        ens_model,
+        # dbNSFP 里的 DL 模型（来自 DL_MODELS 字典，col 132/129）
+        "AlphaMissense":      (dlm.get("AlphaMissense") or {}).get("score"),
+        "ESM1b":              (dlm.get("ESM1b") or {}).get("score"),
+        # 独立模型
+        "GPN_MSA":            gpn.get("score"),
+        "popEVE":             pop.get("score"),
+        "AlphaGenome_Mean":   (ag.get("statistics") or {}).get("raw_score_mean"),
+        "HyenaDNA":           hy.get("score"),
+        "NT":                 nt.get("score"),
+        "Evo2_LLR":           evo2.get("llr_score"),
+        "Evo2_Ref":           evo2.get("ref_score"),
+        "Evo2_Var":           evo2.get("var_score"),
+        "Evo2_Interp":        evo2.get("interpretation"),
+        "Evo1_Delta":         evo1.get("evo1_delta_score"),
+        "Evo1_Ref":           evo1.get("ref_score"),
+        "Evo1_Var":           evo1.get("var_score"),
+    }
+
+
+# ─────────────────────────────────────────────────────────────
+# 公开接口
+# ─────────────────────────────────────────────────────────────
+
+def render_single(prediction: dict, ensemble: Optional[dict],
+                  fmt: str = "table", errors: dict = None) -> None:
+    """渲染单变异预测结果。"""
+    flat = _extract_flat(prediction, ensemble)
+
+    if fmt == "json":
+        _json.dump({"prediction": prediction, "ensemble": ensemble}, sys.stdout, indent=2, ensure_ascii=False)
+        print()
+        return
+
+    if fmt == "tsv":
+        print("\t".join(flat.keys()))
+        print("\t".join(_fmt(v) for v in flat.values()))
+        return
+
+    # ── Rich table ──────────────────────────────────────────
+    t = Table(box=box.ROUNDED, show_header=True, header_style="bold cyan",
+              title="MERGE 预测结果", title_style="bold")
+    t.add_column("项目",     style="dim", no_wrap=True, min_width=18)
+    t.add_column("结果",     min_width=30)
+
+    # 变异基本信息
+    t.add_section()
+    t.add_row("变异位点",
+              f"[bold]{flat['Chr']}:{flat['Pos']}  {flat['Ref']} → {flat['Alt']}[/bold]")
+    t.add_row("基因 / 转录本",
+              f"{_fmt(flat['Gene'])}  /  {_fmt(flat['Transcript'])}")
+
+    # MERGE 集成分数
+    t.add_section()
+    t.add_row("MERGE 致病性",
+              _score_text(flat["MERGE_Score"], flat["MERGE_Label"]))
+    t.add_row("使用模型", _fmt(flat["MERGE_Model"]))
+
+    # 各模型分数
+    t.add_section()
+    for label, key in [
+        ("AlphaMissense",  "AlphaMissense"),
+        ("ESM1b",          "ESM1b"),
+        ("GPN-MSA",        "GPN_MSA"),
+        ("popEVE",         "popEVE"),
+        ("AlphaGenome",    "AlphaGenome_Mean"),
+        ("HyenaDNA",       "HyenaDNA"),
+        ("NT",             "NT"),
+        ("Evo2 LLR",       "Evo2_LLR"),
+        ("Evo1 Delta",     "Evo1_Delta"),
+    ]:
+        val = flat[key]
+        t.add_row(label, _fmt(val))
+
+    console.print(t)
+
+    # 警告/错误
+    if errors:
+        console.print("\n[yellow]部分模型未返回结果：[/yellow]")
+        for src, msg in errors.items():
+            console.print(f"  [dim]{src}:[/dim] {msg}")
+
+
+def render_batch_submitted(job_id: str, email: str) -> None:
+    console.print(f"\n[bold green]✓ 批量任务已提交[/bold green]")
+    console.print(f"  Job ID : [bold]{job_id}[/bold]")
+    console.print(f"  邮箱   : {email}")
+    console.print(f"  完成后结果将发送至邮箱（附件含 3 个文件）")
+    console.print(f"\n查询进度：[bold]merge status {job_id}[/bold]")
+
+
+def render_status(status_data: dict) -> None:
+    """渲染批量任务状态。"""
+    if not status_data.get("found"):
+        console.print(f"[red]任务不存在或服务已重启。[/red]")
+        return
+
+    state = status_data.get("status", "unknown")
+    color = {"processing": "yellow", "complete": "green", "error": "red"}.get(state, "white")
+
+    t = Table(box=box.SIMPLE, show_header=False)
+    t.add_column("key",   style="dim")
+    t.add_column("value")
+    t.add_row("状态",       f"[{color}]{state}[/{color}]")
+    t.add_row("提交时间",   status_data.get("submitted_at", "-"))
+    t.add_row("成功变异数", str(status_data.get("n_ok", "-")))
+    t.add_row("警告/错误",  str(status_data.get("n_err", "-")))
+    t.add_row("邮件已发送", "是" if status_data.get("mail_sent") else "否")
+    console.print(t)
+
+    logs = status_data.get("log", [])
+    if logs:
+        console.print("\n[dim]── 任务日志 ──────────────────────────[/dim]")
+        for line in logs[-20:]:   # 最多显示最后 20 行
+            console.print(f"  [dim]{line}[/dim]")

merge_cli-1.0.0/merge_cli.egg-info/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: merge-cli
+Version: 1.0.0
+Summary: CLI for MERGE variant pathogenicity prediction
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1
+Requires-Dist: requests>=2.31
+Requires-Dist: rich>=13.0
+Requires-Dist: keyring>=24.0
+
+# MERGE CLI
+
+MERGE 变异致病性预测命令行工具。所有计算在服务器端完成，本地只需 Python 3.9+。
+
+## 安装
+
+```bash
+pip install merge-cli
+```
+
+## 快速开始
+
+```bash
+# 1. 配置服务器地址（只需配置一次）
+merge config set-url https://your-server.com
+merge config set-token YOUR_API_TOKEN
+
+# 2. 单变异预测
+merge predict --chrom chr17 --pos 43092919 --ref A --alt G
+
+# 3. 批量预测（上传 VCF，结果发邮件）
+merge batch my_variants.vcf --email you@example.com
+```
+
+## 命令详解
+
+### `merge predict` — 单变异预测
+
+```
+选项：
+  --chrom     染色体（chr17 或 17 均可）   [必填]
+  --pos       变异位置（1-based）           [必填]
+  --ref       参考碱基                      [必填]
+  --alt       突变碱基                      [必填]
+  --genome    hg38 / hg19                  [默认: hg38]
+  --format    table / json / tsv           [默认: table]
+  --no-ensemble   跳过 MERGE 集成打分
+  --no-alphagenome / --no-hyenadna / --no-nt
+  --no-alphamissense / --no-esm1b / --no-gpn-msa
+  --no-popeve / --no-evo2 / --no-evo1
+```
+
+**输出示例（table 模式）：**
+
+```
+╭──────────────────────────────────────────╮
+│          MERGE 预测结果                   │
+├──────────────────┬───────────────────────┤
+│ 变异位点         │ chr17:43092919 A → G  │
+│ 基因 / 转录本    │ BRCA1 / ENST00000357654│
+├──────────────────┼───────────────────────┤
+│ MERGE 致病性     │ 87.3%  Likely Pathogenic│
+│ 使用模型         │ ClinVar               │
+├──────────────────┼───────────────────────┤
+│ AlphaMissense    │ 0.9341                │
+│ ESM1b            │ -3.2180               │
+│ GPN-MSA          │ -1.4420               │
+│ popEVE           │ 0.8812                │
+│ AlphaGenome      │ 0.0234                │
+│ HyenaDNA         │ -2.1100               │
+│ NT               │ -1.8830               │
+│ Evo2 LLR         │ -4.2210               │
+│ Evo1 Delta       │ -3.9910               │
+╰──────────────────┴───────────────────────╯
+```
+
+**管道输出（TSV 模式，方便写脚本）：**
+
+```bash
+merge predict --chrom chr17 --pos 43092919 --ref A --alt G --format tsv >> results.tsv
+```
+
+**脚本批量调用单变异（小于 20 个时比上传 VCF 更快）：**
+
+```bash
+while IFS=$'\t' read -r chrom pos ref alt; do
+    merge predict --chrom "$chrom" --pos "$pos" --ref "$ref" --alt "$alt" --format tsv
+done < variants.tsv >> results.tsv
+```
+
+---
+
+### `merge batch` — 批量 VCF 预测
+
+```bash
+merge batch variants.vcf --email you@example.com
+merge batch variants.vcf.gz --email you@example.com --genome hg19 --no-evo2
+```
+
+任务提交成功后返回 Job ID，结果通过邮件发送，附件包含：
+- `batch_predictions.csv`  — 所有模型分数汇总（可直接用 Excel 打开）
+- `batch_predictions.vcf`  — 标准 VCF 格式，含 MERGE 及各模型分数
+- `imputation_details.csv` — MERGE 各特征缺失填补情况
+
+服务端限制：每 IP 每日 5 次，同一邮箱间隔 1 小时，单次最多 2000 个变异。
+
+---
+
+### `merge status` — 查询批量任务
+
+```bash
+merge status A3F2C1B0          # 查看一次
+merge status A3F2C1B0 --watch  # 每 30 秒轮询
+```
+
+---
+
+## 环境变量（适合 CI / 服务器环境）
+
+```bash
+export MERGE_API_URL=https://your-server.com
+export MERGE_API_TOKEN=your-token
+merge predict --chrom chr1 --pos 100000 --ref C --alt T
+```

merge_cli-1.0.0/merge_cli.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+merge_cli/__init__.py
+merge_cli/api.py
+merge_cli/cli.py
+merge_cli/config.py
+merge_cli/output.py
+merge_cli.egg-info/PKG-INFO
+merge_cli.egg-info/SOURCES.txt
+merge_cli.egg-info/dependency_links.txt
+merge_cli.egg-info/entry_points.txt
+merge_cli.egg-info/requires.txt
+merge_cli.egg-info/top_level.txt

merge_cli-1.0.0/merge_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

merge_cli-1.0.0/merge_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+merge = merge_cli.cli:cli

merge_cli-1.0.0/merge_cli.egg-info/requires.txt

@@ -0,0 +1,4 @@
+click>=8.1
+requests>=2.31
+rich>=13.0
+keyring>=24.0

merge_cli-1.0.0/merge_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+merge_cli

merge_cli-1.0.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "merge-cli"
+version = "1.0.0"
+description = "CLI for MERGE variant pathogenicity prediction"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+
+dependencies = [
+    "click>=8.1",
+    "requests>=2.31",
+    "rich>=13.0",
+    "keyring>=24.0",
+]
+
+[project.scripts]
+merge = "merge_cli.cli:cli"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["merge_cli*"]

merge_cli-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+