Protein-Report: A Reproducible, One-Command Protein Sequence Analysis Pipeline with Domain, Homology, and Report-First Outputs

Abstract

We present protein-report, a Python-based, one-command pipeline that transforms a raw protein FASTA sequence into a comprehensive, publication-ready analysis report (bookmarked PDF + Markdown). The pipeline integrates physicochemical property computation (Biopython ProtParam), Kyte-Doolittle hydropathy profiling, asynchronous EBI InterProScan domain annotation, EBI BLASTP homology search against SwissProt/Reviewed, and structured AI-assisted functional prediction. Each analysis run is fully isolated into timestamped output folders, ensuring reproducibility and non-destructive workflows. Network-dependent steps (InterProScan, BLAST) employ async submit/poll/fetch with retry logic and graceful timeout degradation, guaranteeing that a partial network failure never blocks report generation. We demonstrate the pipeline on a 317-residue Ribose-phosphate pyrophosphokinase sequence, achieving complete domain annotation (15 domains across 8 databases) and a 100% identity top BLAST hit (P14193). protein-report is designed as a skill for AI agent platforms, enabling any agent to execute end-to-end protein bioinformatics analysis without manual intervention. Source code and example outputs are available at https://github.com/Wuhl00/protein-report.

Keywords: protein analysis, reproducible research, bioinformatics pipeline, InterProScan, BLAST, AI agent skill

1. Introduction

1.1 Background

Protein sequence analysis is a foundational task in bioinformatics. A typical workflow involves multiple steps: computing physicochemical properties, generating hydropathy profiles, running domain annotation via InterProScan, performing homology searches via BLAST, and synthesizing results into a coherent report. Each step typically requires a different tool, format conversion, and manual integration — a process that is time-consuming, error-prone, and difficult to reproduce.

1.2 Motivation

The rise of AI agent platforms (such as OpenClaw, Claude Code, and similar systems) introduces a new paradigm: skills — executable, self-contained instructions that allow AI agents to perform complex tasks autonomously. Unlike traditional bioinformatics pipelines (e.g., Galaxy, Snakemake workflows), which require a dedicated environment and manual configuration, a skill can be executed by any AI agent with access to a standard Python environment and the internet.

This paper presents protein-report, a protein sequence analysis pipeline packaged as a skill. The design goals are:

1. One-command execution: A single python protein_analyzer.py produces a complete report.
2. Reproducibility: Each run is isolated; all outputs are timestamped and self-contained.
3. Resilience: Network failures in external API calls (InterProScan, BLAST) never block the full report.
4. Agent-native: Packaged as a SKILL.md file that any compatible AI agent can consume and execute.

1.3 Contributions

• A fully integrated, one-command protein analysis pipeline covering physicochemical profiling, domain annotation, homology search, and AI-assisted functional prediction.
• An async submit/poll/fetch architecture for external API calls with retry logic and graceful degradation.
• A reproducibility-oriented skill format (SKILL.md) that enables any AI agent to clone, install, and execute the pipeline from a single instruction set.
• Demonstration on a real-world sequence with complete results.

2. Methodology

2.1 Pipeline Architecture

The pipeline follows a sequential architecture with five core modules:

Input (FASTA)
    |
    v
[1] Physicochemical Properties (Biopython ProtParam)
    |
    v
[2] Hydropathy Plot (Kyte-Doolittle, Matplotlib)
    |
    v
[3] Domain Analysis (EBI InterProScan, async)
    |
    v
[4] Homology Search (EBI BLASTP vs SwissProt, async)
    |
    v
[5] AI Functional Summary (structured synthesis)
    |
    v
[6] Report Generation (PDF + Markdown)

2.2 Module Details

2.2.1 Physicochemical Properties

Computed locally using Biopython's ProtParam module. Metrics include:

No external API calls are required. This module always succeeds.

2.2.2 Hydropathy Plot

The Kyte-Doolittle hydropathy scale is applied with a sliding window of 19 residues (standard for transmembrane helix prediction). The plot is generated using Matplotlib and saved as hydrophobicity.png.

2.2.3 Domain Analysis (InterProScan)

This module interfaces with the EBI InterProScan REST API using an asynchronous submit/poll/fetch pattern:

1. Submit: POST the protein sequence to https://www.ebi.ac.uk/interpro/api/sequence/segment/. Returns a submission ID and a status URL.
2. Poll: Periodically GET the status URL. Retries with exponential backoff on transient HTTP errors.
3. Fetch: Once status is DONE, retrieve the XML/JSON results. Parse domain hits including position, name, accession, and source database.

Results are rendered as both a visual domain map (domain_map.png) and a tabular summary sorted by genomic position. Clickable links to InterPro, Pfam, SMART, PANTHER, CDD, and other databases are embedded in the report.

2.2.4 Homology Search (BLASTP)

BLASTP is run against the SwissProt/Reviewed database via the EBI NCBI BLAST REST API:

1. Submit: POST to the BLAST API with the query sequence and database parameter set to swissprot.
2. Poll: Check job status with retry logic.
3. Parse: Extract top hits with accession, identity percentage, E-value, description, and clickable UniProt links.

Timeout and degradation: A hard timeout of 180 seconds is enforced. If BLAST does not complete within this window, the module gracefully degrades — the report is generated with a note that BLAST timed out, and a direct link to the NCBI BLAST web portal is provided for manual retry.

2.2.5 AI Functional Summary

Based on the collected data, a structured English-language summary is synthesized with three sections:

• Investigation Summary: Key findings from physicochemical analysis, domain annotation, and homology search.
• Functional Prediction: Inference of potential biochemical function based on domain composition and homology.
• Related Literature: A PubMed search link constructed from identified domain names for further reading.

2.2.6 Report Generation

Two output formats are produced:

• PDF (<FASTA_ID>_report.pdf): Generated with fpdf, then post-processed with PyPDF2 to add sidebar bookmarks corresponding to each major section. External links (UniProt, InterPro, AlphaFold, PubMed) are clickable.
• Markdown (<FASTA_ID>_report.md): A fully structured Markdown file with tables, image references, and hyperlinks — easy to edit, share, or import into other tools.

2.3 Reproducibility Design

Each run creates an isolated output folder:

analysis_runs/<FASTA_ID>_YYYYMMDD_HHMMSS/

This design ensures:

• Multiple analyses on different sequences never overwrite each other.
• Re-running the same sequence at different times produces separate, timestamped results.
• The entire output folder can be archived or shared as a self-contained result set.

2.4 Error Handling and Resilience

The pipeline follows a "best-effort completion" principle: any module failure degrades the report gracefully rather than blocking it entirely.

3. Results

3.1 Demonstration Sequence

We demonstrate the pipeline on a 317-residue protein sequence (UserSeq_1) from the repository's example dataset. The input FASTA sequence:

>UserSeq_1
MSNQYGDKNLKIFSLNSNPELAKEIADIVGVQLGKCSVTRFSDGEVQINIEESIRGCDCY
IIQSTSDPVNEHIMELLIMVDALKRASAKTINIVIPYYGYARQDRKARSREPITAKLFAN
LLETAGATRVIALDLHAPQIQGFFDIPIDHLMGVPILGEYFEGKNLEDIVIVSPDHGGVT
RARKLADRLKAPIAIIDKRRPRPNVAEVMNIVGNIEGKTAILIDDIIDTAGTITLAANAL
VENGAKEVYACCTHPVLSGPAVERINNSTIKELVVTNSIKLPEEKKIERFKQLSVGPLLA
EAIIRVHEQQSVSYLFS

3.2 Physicochemical Properties

3.3 Domain Annotation

InterProScan identified 15 domain hits across 8 databases:

The domain architecture reveals this protein belongs to the ribose-phosphate pyrophosphokinase (PRPP synthase) family, a well-characterized enzyme in nucleotide biosynthesis.

3.4 Homology Search

BLASTP against SwissProt/Reviewed returned a 100% identity top hit:

3.5 Secondary Structure Prediction

The AI synthesis module estimated secondary structure propensity:

• Alpha-helix: 32.2%
• Beta-sheet: 37.2%
• Coil/Loop: 27.1%

3.6 Output Files

The pipeline produced the following outputs in analysis_runs/UserSeq_1_20260324_124042/:

4. Discussion

4.1 Design Trade-offs

SwissProt vs. nr: We deliberately limit BLAST to SwissProt/Reviewed sequences. While this sacrifices coverage (SwissProt contains ~570K sequences vs. ~200M in nr), it dramatically improves result reliability — every hit comes from a manually curated, experimentally validated entry. Users requiring broader searches are directed to the NCBI BLAST web portal.

Timeout strategy: The 180-second BLAST timeout was chosen as a practical balance. For most sequences under 1000 residues, SwissProt BLAST completes within 60-120 seconds. Longer sequences or complex queries may timeout, but the graceful degradation ensures users still receive all other analysis results plus a path to retry.

Local vs. Cloud: All compute-intensive steps (physicochemical analysis, plotting) run locally. Only database lookups (InterProScan, BLAST) require network access. This minimizes dependency on external service availability.

4.2 Agent-Native Design

The skill format (SKILL.md) is designed for AI agent consumption. Unlike traditional software documentation, it follows a strict structure:

1. Clone — one git clone command
2. Install — one pip install command
3. Run — one python command
4. Verify — comparison against known example output

Any agent with shell access and Python can execute this pipeline without understanding the underlying bioinformatics. This is the key advantage over traditional pipelines: the skill is the documentation is the reproducibility protocol.

4.3 Limitations

• Single sequence per run: The pipeline currently processes one FASTA entry at a time.
• No structural prediction: While links to AlphaFold/ColabFold are provided, the pipeline does not perform structure prediction.
• EBI API dependency: InterProScan and BLAST depend on EBI service availability; the fallback strategy mitigates but does not eliminate this dependency.
• PDF rendering: The fpdf library has limited Unicode support; CJK characters in PDFs may not render correctly.

5. Conclusion

protein-report demonstrates that a complete protein bioinformatics analysis pipeline can be packaged as a single, reproducible skill executable by any AI agent. The combination of local computation, async API integration, graceful degradation, and timestamped output isolation achieves both robustness and reproducibility. With a 317-residue demonstration sequence, the pipeline successfully identified 15 domain annotations across 8 databases and a 100% identity homology match, producing a publication-ready report in under 5 minutes.

The skill format (SKILL.md) with its clone-install-run-verify structure represents a new paradigm for reproducible bioinformatics: instead of sharing environments, we share instructions that any agent can execute autonomously.

5.1 Future Work

• Multi-sequence batch processing support
• Integration with AlphaFold DB API for automated structure retrieval
• Interactive HTML report output
• Support for nucleotide-to-protein workflows (BLASTX, ORF finding)

6. References

1. The UniProt Consortium. UniProt: the universal protein knowledgebase. Nucleic Acids Research, 2023.
2. Jones, P. et al. InterProScan 5: genome-scale protein function classification. Bioinformatics, 2014.
3. Altschul, S.F. et al. Gapped BLAST and PSI-BLAST: a new generation of protein database search programs. Nucleic Acids Research, 1997.
4. Kyte, J. & Doolittle, R.F. A simple method for displaying the hydropathic character of a protein. Journal of Molecular Biology, 1982.
5. Gasteiger, E. et al. ProtParam: computing physicochemical properties from amino acid sequences. Nucleic Acids Research, 2005.

Appendix: Skill File

See the accompanying SKILL.md for the complete reproduction protocol. The skill enables any AI agent to:

git clone https://github.com/Wuhl00/protein-report.git
cd protein-report
pip install -r main_scripts/requirements.txt
# Place sequence in main_scripts/input.fasta, then:
cd main_scripts
python protein_analyzer.py

Example output is available at: example/UserSeq_1_20260324_124042/