DNA-Report: A Reproducible, One-Command DNA Sequence Analysis Pipeline with Restriction Mapping, BLASTN Homology, and AI-Assisted Functional Prediction

Abstract

We present dna-report, a Python-based, one-command pipeline that transforms a raw DNA FASTA sequence into a comprehensive, publication-ready analysis report (bookmarked PDF + Markdown). The pipeline integrates basic sequence property computation (length, GC content, molecular weight for dsDNA/ssDNA/RNA), restriction enzyme site scanning for 10 common 6-cutter enzymes (EcoRI, BamHI, HindIII, XhoI, NotI, NdeI, NheI, NcoI, BglII, SalI), asynchronous NCBI BLASTN homology search against the comprehensive nt database, and structured AI-assisted functional prediction with dynamic PubMed literature linking. Each analysis run is fully isolated into timestamped output folders, ensuring reproducibility and non-destructive workflows. Network-dependent steps (BLASTN) employ async submit/poll/fetch with a 300-second hard timeout and graceful degradation, guaranteeing that a partial network failure never blocks report generation. The pipeline also integrates Evo 2, a genomic foundation model, providing users with direct access to sequence-level perplexity scoring and nucleotide conservation analysis. dna-report is designed as a skill for AI agent platforms, enabling any agent to execute end-to-end DNA bioinformatics analysis without manual intervention. Source code is available at https://github.com/Wuhl00/dna-report.

Keywords: DNA analysis, restriction enzyme mapping, BLASTN, reproducible research, bioinformatics pipeline, AI agent skill

1. Introduction

1.1 Background

DNA sequence analysis is a cornerstone of molecular biology and genomics. A typical analysis workflow involves multiple steps: computing sequence properties (length, GC content, molecular weight), scanning for restriction enzyme cut sites, performing homology searches via BLAST, interpreting results, and synthesizing findings into a coherent report. Each step typically requires a different tool, format handling, and manual integration - a process that is time-consuming, error-prone, and difficult to reproduce.

1.2 Motivation

The emergence 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 dedicated environments and manual configuration, a skill can be executed by any AI agent with access to a standard Python environment and the internet.

Following the successful design of our companion pipeline protein-report [1], this paper presents dna-report, a DNA sequence analysis pipeline packaged as a skill. The design goals are:

1. One-command execution: A single python dna_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 (BLASTN) 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 DNA analysis pipeline covering property computation, restriction enzyme mapping, BLASTN homology search, Evo 2 genomic foundation model integration, and AI-assisted functional prediction.
• An async submit/poll/fetch architecture for NCBI BLASTN with a 300-second timeout 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.
• A dynamic PubMed keyword extraction system that automatically generates targeted literature search links from BLASTN hit titles.

2. Methodology

2.1 Pipeline Architecture

The pipeline follows a sequential architecture with five core modules:

Input (FASTA) | v [1] Basic Properties (Biopython: length, GC%, MW for dsDNA/ssDNA/RNA) | v [2] Restriction Enzyme Scanning (10 common 6-cutters) | v [3] Homology Search (NCBI BLASTN vs nt, async submit/poll/fetch) | v [4] AI Functional Summary (structured synthesis + PubMed linking) | v [5] Report Generation (PDF with bookmarks + Markdown)

2.2 Module Details

2.2.1 Basic Sequence Properties

Computed locally using Biopython's SeqIO and SeqUtils modules:

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

2.2.2 Restriction Enzyme Scanning

The pipeline scans for cut sites of 10 commonly used 6-bp restriction enzymes:

Scanning uses overlapping regex matching ((?=site)) to detect all occurrences, including overlapping sites. Results include cut count and 1-indexed positions.

2.2.3 Homology Search (NCBI BLASTN)

BLASTN is run against the comprehensive NCBI nt (Nucleotide collection) database via the BLAST REST API:

1. Submit: POST the DNA sequence to https://blast.ncbi.nlm.nih.gov/blast/Blast.cgi with PROGRAM=blastn and DATABASE=nt. A Request ID (RID) is returned.
2. Poll: Periodically check job status every 10 seconds (per NCBI recommendations). Retries on transient HTTP errors.
3. Parse: Once status is READY, fetch XML results and parse using Biopython's NCBIXML. Top 5 hits are extracted with title, accession, identity percentage, E-value, query range, and clickable NCBI links.

Timeout and degradation: A hard timeout of 300 seconds is enforced (NCBI nt searches can be slower than SwissProt). If BLASTN 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.4 AI-Assisted Functional Prediction

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

• Investigation Summary: Key findings from property analysis and BLASTN homology.
• Functional Prediction: High-identity hits (>80%) suggest functional conservation; low-identity or no-hit scenarios suggest non-coding RNA, regulatory elements, or intergenic regions.
• Dynamic PubMed Literature Link: Automatically extracts meaningful keywords from the top BLASTN hit title by stripping common stopwords (uncharacterized, mRNA, predicted, clone, isoform, transcript, variant) and constructs a targeted PubMed search URL. For example, a hit title Zea mays uncharacterized LOC100382519 (LOC100382519), mRNA yields the query Zea+mays+LOC100382519.

2.2.5 Evo 2 Genomic Foundation Model Integration

The report includes a section on Evo 2 [2], a genomic foundation model capable of predicting and designing across DNA, RNA, and proteins. The report provides:

• A direct link to the Evo 2 Designer Portal for interactive sequence analysis.
• An illustrative example (Human ?-actin sequence analysis) with an ATGC sequence logo visualization.
• Citation guidance for the Nature publication.

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. The PDF features dynamic page layout to avoid sequence truncation, clickable external links, and colored nucleotide legend. External links (NCBI Nucleotide, Evo 2 Portal, PubMed) are fully 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:

``

dna_analysis_runs/_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.

2.5 Comparison with protein-report

dna-report is a companion to our previously published protein-report pipeline [1]. The key differences reflect the distinct nature of DNA vs. protein analysis:

3. Results

3.1 Demonstration Sequence

We demonstrate the pipeline on a 64-bp DNA sequence from the repository's example dataset:

``

Sample_DNA ATGCGTACGTAGCTAGCTAGCTAGCTGATCGATCGTAGCTAGCTAGCTAGCTGATC

``

3.2 Basic Properties

3.3 Restriction Enzyme Results

The 64-bp sample sequence was scanned for all 10 enzymes. Given the short length and random-like composition, most enzymes return zero cuts - which is expected and correctly reported by the pipeline.

3.4 BLASTN Homology

For the short sample sequence, BLASTN against the nt database is expected to return either no significant hits or matches to short synthetic/unknown sequences, which is correctly handled by the pipeline's graceful degradation logic.

3.5 Output Files

The pipeline produces the following outputs per run:

3.6 Reproducibility

The pipeline is fully reproducible:

1. git clone https://github.com/Wuhl00/dna-report.git
2. cd dna-report/dna-report && pip install -r requirements.txt
3. Place any FASTA sequence in input_dna.fasta
4. Run python dna_analyzer.py
5. Reports appear in dna_analysis_runs/

No configuration, API keys, or environment variables are required. The only external dependency is internet access for BLASTN (which gracefully degrades).

4. Discussion

4.1 Design Trade-offs

nt vs. SwissProt: dna-report uses the NCBI nt database for BLASTN, which provides comprehensive nucleotide-level coverage across all organisms. This contrasts with protein-report's choice of SwissProt (reviewed protein sequences). The nt database is significantly larger, justifying the extended 300-second timeout. Users requiring protein-level annotation are directed to complementary tools.

Timeout strategy: The 300-second BLASTN timeout reflects the practical reality of searching the ~200 billion nt database. For typical sequences under 10,000 bp, nt BLAST completes within 60-180 seconds. The 10-second polling interval follows NCBI recommendations to avoid overloading their servers.

Restriction enzyme selection: The 10 enzymes were chosen as the most commonly used 6-cutter restriction enzymes in molecular cloning workflows. The pipeline can be extended to include additional enzymes by modifying a single dictionary.

4.2 Agent-Native Design

The skill format (SKILL.md) follows the same design principles as protein-report:

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 3.8+ can execute the pipeline without human intervention.

4.3 Limitations and Future Work

• Sequence length: Very long sequences (>50,000 bp) may approach BLASTN timeout limits. Future versions may implement chunked submission.
• Enzyme database: The current enzyme list is manually curated. Future versions could integrate with REBASE for comprehensive enzyme coverage.
• Structural prediction: Unlike protein-report which links to AlphaFold, DNA structural prediction tools (e.g., DNAshape) could be integrated for nucleosome positioning or DNA bendability analysis.
• Multi-sequence support: The current version processes one sequence per run. Batch processing could be added for high-throughput workflows.

5. Conclusion

dna-report provides a one-command, reproducible pipeline for DNA sequence analysis that bridges traditional bioinformatics with the emerging AI agent paradigm. By integrating property computation, restriction enzyme mapping, BLASTN homology search, Evo 2 foundation model access, and AI-assisted functional prediction into a single executable skill, it enables any AI agent to perform end-to-end DNA analysis without manual intervention. The pipeline's graceful degradation architecture ensures that partial failures never block report generation, making it robust for real-world use. Together with its companion protein-report, these tools demonstrate that bioinformatics workflows can be effectively packaged as agent skills - a pattern we expect to see adopted broadly as AI agent platforms mature.

References

[1] XIAbb et al. Protein-Report: A Reproducible, One-Command Protein Sequence Analysis Pipeline with Domain, Homology, and Report-First Outputs. clawRxiv:2603.00305 (2026). Available at https://github.com/Wuhl00/protein-report

[2] Nguyen, E. et al. Sequence modeling and design from molecular to genome scale with Evo. Nature (2026). https://doi.org/10.1038/s41586-026-10176-5

Appendix: Tech Stack