A LangGraph-based intelligent pipeline for spidroin repeat unit identification
基于 LangGraph 的蛛丝蛋白重复单元自动识别系统
SpidroinRepeatAgent is an autonomous analysis pipeline that automatically identifies repeat units in spidroin (spider silk protein) and Bombyx mori fibroin central repeat regions from fragmented Augustus ab initio predictions.
SpidroinRepeatAgent 是一个自主分析流水线，专为从 Augustus 从头预测的蛛丝蛋白（spidroin）和家蚕丝素蛋白（Bombyx mori fibroin）氨基酸序列中，自动识别中央重复区并切分重复单元而设计。
Core capability / 核心能力：
Given one or more candidate spidroin sequences, automatically identify the central repeat region, segment repeat units, generate consensus sequences, subtype classifications, architectural patterns, and provide traceable confidence scores with evidence.
从一条或多条候选蛛丝蛋白序列中，自动识别中央重复区，切分重复单元，生成共识单元、单元亚型、重复架构图，并给出可追溯的置信度与证据。
┌─────────────────────────────┐
│ validator_node │ ← Spidroin candidate detection
└────────────┬────────────────┘ 蛛丝蛋白候选判定
│
┌────────────▼────────────────┐
│ parser_node │ ← NTD / Repeat / CTD partitioning
└──┬──────────────────────┬───┘ 三区划分
│ │
┌────────────▼──┐ ┌──────────────▼──────┐ ┌─────────────────┐
│ kmer_node │ │ tandem_node │ │ dotplot_node │
│ K-mer 谱峰 │ │ 自相关检测 │ │ 对角线累积 │
└────────────┬──┘ └──────────────┬───────┘ └────────┬────────┘
└──────────────────────┴────────────────────┘
│ Fan-in (3 paths)
┌───────────────▼──────────────────┐
│ candidate_merge_node │ ← 三路合并 + 谐波折叠
└───────────────┬──────────────────┘
│
┌───────────────▼──────────────────┐
│ rough_segmentation_node │ ← 锚点定位 + 粗切
└───────────────┬──────────────────┘
│
┌───────────────▼──────────────────┐
│ boundary_refinement_node │ ← DP全局精修
└───────────────┬──────────────────┘
│
┌─────────────────────────▼────────────────────────┐
│ repeat_typing_node (UPGMA + MSA consensus) │ ← 层次聚类 + 架构识别
└─────────────────────────┬────────────────────────┘
│
┌─────────────────────────▼────────────────────────┐
│ evidence_scoring_node (4-dimensional scoring) │ ← 四维证据评分
└─────────────────────────┬────────────────────────┘
│
┌───────────────▼──────────────────┐
│ export_report_node │ ← JSON + GFF3 + HTML
└──────────────────────────────────┘
19 LangGraph nodes | 3 parallel discovery paths | 3 conditional routing stages
-
Three-path independent discovery / 三路独立发现
- Path A: K-mer spectral period detection
- Path B: Tandem autocorrelation with harmonic disambiguation
- Path C: Dotplot diagonal accumulation (de novo, motif-free)
-
Dynamic Controller Agent / 动态控制器
- Adaptive routing based on sequence features (length, complexity, period strength)
- Automatic fallback handling for fragmented Augustus predictions
-
Biologically-aware segmentation / 生物学感知切分
- poly-A crystal domain boundary detection with whitelist exemption
- Spacer vs. repeat unit discrimination via compositional analysis
-
UPGMA hierarchical clustering + profile MSA consensus / 层次聚类 + 多序列比对共识
-
5-type repeat architecture classification / 五类架构模式识别
- LINEAR | ALTERNATING | DOMINANT_WITH_VARIANT | REGIONAL | COMPLEX
-
Multi-format output / 多格式输出
- JSON (structured analysis) | GFF3 (genome browser) | HTML (interactive visualization) | FASTA (unit sequences)
-
Cross-species compatible / 跨物种兼容
- Validated on 8 spider species (130 Augustus sequences) + Bombyx mori Fib-H
git clone https://github.com/Gasly729/silk-agent.git
cd silk-agent
pip install -r requirements.txtRequirements / 环境要求：
- Python 3.10+
- No external bioinformatics binaries required (pure Python + numpy)
- 不依赖任何外部二进制程序（BLAST、MAFFT 等）
cd pipline
# Analyze a single FASTA file / 分析单个 FASTA 文件
python agent_graph.py ../data/example/example_input.fasta
# Output will be written to output_results/
# 结果写入 output_results/ 目录from pipline.agent_graph import build_graph, run_single_sequence, run_from_fasta
# Single sequence / 单序列
graph = build_graph()
result = run_single_sequence(graph, "MaSp1_example", "MAAAGGYGGLGSQ...")
print(result["global_confidence"]["level"]) # "high"
print(result["repeat_types"]["architecture_type"]) # "LINEAR"
# Batch FASTA / 批量 FASTA
results = run_from_fasta("my_spidroins.fasta")# Start server / 启动服务
cd pipline
uvicorn api_server:app --host 0.0.0.0 --port 8000
# Analyze single sequence / 分析单条序列
curl -X POST http://localhost:8000/analyze/sequence \
-H "Content-Type: application/json" \
-d '{"sequence_id": "MaSp1", "sequence": "MAAAGGYGGLGSQ..."}'
# Batch FASTA upload / 批量上传
curl -X POST http://localhost:8000/analyze/fasta \
-F "file=@my_spidroins.fasta"
# Interactive API docs / 在线接口文档
open http://localhost:8000/docsEach analyzed sequence generates four output files:
output_results/
├── {seq_id}.json # Complete analysis (confidence, units, routing log)
├── {seq_id}.gff3 # Standard GFF3 annotation (IGV/JBrowse compatible)
├── {seq_id}_report.html # Interactive HTML visualization
└── {seq_id}_units.fasta # Extracted repeat unit sequences
Key JSON fields / 关键 JSON 字段：
{
"is_spidroin": true,
"global_confidence": {"level": "high", "weighted_total": 0.87},
"period_top1": 178,
"total_units": 25,
"architecture_type": "LINEAR",
"architecture_description": "Single repeat type (A) throughout",
"routing_log": [...],
"errors": []
}See docs/output_schema_v1.md for full schema.
完整字段定义见 docs/output_schema_v1.md。
Tested on 130 Augustus ab initio fragmented predictions across 8 spider species:
在 8 个蜘蛛物种的 130 条 Augustus 从头预测序列上的测试结果：
| Metric | Value |
|---|---|
| Sequences tested | 130 |
| Spidroin detected (is_spidroin=True) | 124 (95.4%) |
| Global confidence = high | 107/124 (86.3%) |
| Dotplot 3-path confirmation | 104/120 valid (86.7%) |
| Crashes | 0 |
| Average processing time | ~5s/sequence (development machine) |
Architecture type distribution across 8 species (n=120 valid sequences):
| Architecture | Count | Description |
|---|---|---|
| LINEAR | 47 | Single uniform repeat type |
| DOMINANT_WITH_VARIANT | 37 | One dominant type + rare variants |
| REGIONAL | 25 | Subtypes concentrated in specific regions |
| COMPLEX | 6 | Complex mixed architecture |
| ALTERNATING | 4 | Regular AB-type alternation |
-
AgSp sub-period issue (L-1): Aggregate silk proteins (~400 aa true period) may be over-segmented due to harmonic disambiguation ambiguity.
聚合丝蛋白（真实周期 ~400 aa）因谐波歧义问题可能被过度切分。
-
High-CV overconfidence (L-2): Sequences with unit CV > 0.35 may receive "high" global confidence despite poor segmentation quality, due to the discovery score dimension masking unit variability.
重复单元长度 CV > 0.35 的序列，发现维度分数可能掩盖切分质量问题，导致置信度虚高。
If you use SpidroinRepeatAgent in your research, please cite:
如在研究中使用本工具，请引用：
[Citation placeholder — manuscript in preparation]
SpidroinRepeatAgent: A LangGraph-based intelligent pipeline for
automated spidroin repeat unit identification.
GitHub: https://github.com/Gasly729/silk-agent
MIT License — see LICENSE for details.