abi-agent 1.5.10

Agent-Bioinformatics Interface: plugin-based abstraction for AI-driven bioinformatics analysis

ABI — Agent-Bioinformatics Interface

Run reproducible bioinformatics workflows from the command line or an AI agent, without asking the agent to invent the pipeline.

ABI gives every supported analysis the same safe lifecycle: inspect the workflow, check inputs and resources, dry-run it, execute with explicit confirmation, then inspect standardized results and provenance.

:cn: 中文版

What ABI helps you do

• Review before you run. See the stages, tools, commands, inputs, outputs, and resource needs before spending compute time.
• Use one workflow interface. The same plan -> check -> dry-run -> run -> inspect -> report flow works across all built-in analysis types.
• Keep results traceable. Each run records resolved inputs, configuration, commands, tool versions, resources, progress, tables, and reports.
• Let agents operate safely. Agents call typed ABI tools instead of generating ad hoc shell pipelines, and execution remains confirmation-gated.
• Move between runtimes. Run the same compiled plan with the local, Nextflow, Snakemake, or native HPC backend; Docker, cloud workers, and the HTTP Job Service provide additional deployment boundaries.

ABI is an orchestration and interface layer. It does not replace the underlying bioinformatics tools, reference databases, or compute resources required by an analysis.

Who ABI is for

• Researchers and bioinformaticians who want a predictable way to preview, run, inspect, and reproduce an analysis.
• Teams using AI agents that need machine-readable tools, clear permissions, and structured diagnostics.
• Platform engineers exposing workflows through CLI, MCP, HTTP, Nextflow, Snakemake, native HPC, or cloud infrastructure.
• Plugin authors who want to add a workflow while reusing ABI's planning, provenance, validation, tables, and reporting core.

Choose an analysis workflow

If you want to...	Use --type	Main result
Profile a 16S microbial community	amplicon_16s	ASVs, taxonomy, phylogeny, alpha and beta diversity
Compare bulk RNA-seq expression	rnaseq_expression	Count matrix, differential expression, pathway enrichment
Analyze a bacterial isolate genome	wgs_bacteria	Assembly, annotation, MLST, antimicrobial resistance calls
Quantify metatranscriptomic expression	metatranscriptomics	Read QC, alignment summary, per-gene counts
Profile shotgun metagenomic reads	easymetagenome	Taxonomic and functional abundance profiles
Identify and characterize viruses	viral_viwrap	Viral bins, quality, taxonomy, hosts, normalized abundance
Reconstruct and characterize plasmids	metagenomic_plasmid	Detection consensus, typing, hosts, annotation, abundance, community analysis

All seven workflows have software-path validation. Biological acceptance depends on your data, parameters, databases, and tool versions; validate representative datasets before production use.

Use ABI itself to explore a workflow without reading its implementation:

abi list-types
abi query --type metagenomic_plasmid --what stages
abi query --type metagenomic_plasmid --what tools
abi query --type metagenomic_plasmid --step qc_fastp --what inputs

How to use ABI

From a general-purpose coding agent

First, enter this prompt in a coding agent that supports Skills:

Help me install and register ABI from https://github.com/sleepinlava/BAI
in this agent with Skills.

The agent installs ABI for the current platform, registers the Skill and MCP configuration, and runs the integration diagnostics. You can also register it manually; replace codex with claude-code or opencode as needed:

pip install "abi-agent[mcp]"
abi agent install codex --scope project
abi agent doctor codex --scope project

After registration, start a new agent session. You can then ask Codex, Claude Code, or OpenCode to use ABI in either of two ways.

1. Explicit invocation

   Invoke /abi and provide the input, analysis type, and output location:

   /abi Use ABI to analyze <input file or directory>. The analysis type is
   <analysis_type>. Save the results to <output directory>.
   

   For example:

   /abi Use ABI to analyze rnaseq-demo/samples.tsv. The analysis type is
   rnaseq_expression. Save the results to rnaseq-demo/results/run-001.
   

2. Implicit invocation

   Describe the outcome directly. An agent with the ABI Skill loaded can recognize the bioinformatics request, select or confirm the appropriate analysis_type, and follow the ABI lifecycle:

   Analyze rnaseq-demo/samples.tsv and save the results to
   rnaseq-demo/results/run-001.
   

In both cases, the agent should inspect the workflow, check inputs and resources, and present a dry-run summary first. It may start the real analysis only after your explicit approval. See the Agent usage guide for integration setup and permission boundaries.

From the ABI CLI

To operate ABI yourself, use the same lifecycle from a terminal:

abi list-types
abi plan --type <analysis_type> --config <config.yaml> \
  --sample-sheet <samples.tsv> --outdir <plan-dir>
abi check --type <analysis_type> --config <config.yaml> \
  --sample-sheet <samples.tsv>
abi dry-run --type <analysis_type> --config <config.yaml> \
  --sample-sheet <samples.tsv> --outdir <dry-run-dir>
abi run --type <analysis_type> --config <config.yaml> \
  --sample-sheet <samples.tsv> --outdir <result-dir> --confirm-execution
abi inspect --result-dir <result-dir>
abi report --type <analysis_type> --result-dir <result-dir>

The runnable quickstart below expands each step.

CLI quickstart in five minutes

1. Install ABI

ABI supports Python 3.10-3.13.

pip install abi-agent
abi --version

# Optional integrations
pip install "abi-agent[mcp]"       # MCP server
pip install "abi-agent[report]"    # Scientific figures and richer reports

# Inspect, preview, and install the Linux tool environments needed by a plugin
abi env discover --output-json
abi env doctor --type rnaseq_expression --output-json
abi env install --type rnaseq_expression --dry-run --output-json
abi env install --type rnaseq_expression

Environment installation is Linux-only and does not require Docker or a source checkout. ABI selects micromamba, mamba, then conda, records the solver version and exact commands, and defaults managed environments to ${XDG_DATA_HOME:-~/.local/share}/abi/mamba. Use repeated --env options for individual environments, --solver to select an executable explicitly, and abi env update to reconcile an existing environment with the packaged specification. The diagnostic report includes the current Linux architecture capability, blockers, alternatives, and evidence; unsupported plugin/environment cells and undeclared CPU architectures fail before execution. Use --type when a tool is assigned to different environments by multiple plugins.

To run the bundled example and work with the source repository:

git clone https://github.com/sleepinlava/BAI.git abi
cd abi
python -m venv .venv
. .venv/bin/activate
pip install -e .

2. Build a plan without running tools

This example resolves a three-step metatranscriptomics workflow and writes the exact plan to results/quickstart-plan/execution_plan.json.

abi plan \
  --type metatranscriptomics \
  --config examples/metatranscriptomics/config_demo.yaml \
  --sample-sheet examples/sample_sheet_transcriptomics.tsv \
  --outdir results/quickstart-plan

3. Create a dry-run result

A dry-run does not execute STAR, HISAT2, featureCounts, or other analysis tools. It creates the provenance bundle, standard table skeletons, and report preview you can inspect first.

abi dry-run \
  --type metatranscriptomics \
  --config examples/metatranscriptomics/config_demo.yaml \
  --sample-sheet examples/sample_sheet_transcriptomics.tsv \
  --outdir results/quickstart-dry-run

The result directory has a consistent shape:

results/quickstart-dry-run/
├── execution_plan.json
├── provenance/          # resolved inputs, config, commands, resources, versions
├── tables/              # workflow-specific standard TSV tables
└── report/              # Markdown and HTML report previews

4. Check the real runtime

Before a real run, point the configuration at your data and references, then check files, executables, and resources without changing them.

abi check \
  --type metatranscriptomics \
  --config path/to/config.yaml \
  --sample-sheet path/to/samples.tsv

abi check-resources \
  --type metatranscriptomics \
  --config path/to/config.yaml

Some plugins can prepare managed resources. Preview the setup first, then confirm it explicitly if the paths and downloads are correct.

abi setup-resources --type metagenomic_plasmid --dry-run
abi setup-resources --type metagenomic_plasmid --confirm

5. Run only after review

abi run will not execute without --confirm-execution. This gives both people and agents a clear approval boundary.

abi run \
  --type metatranscriptomics \
  --config path/to/config.yaml \
  --sample-sheet path/to/samples.tsv \
  --outdir results/my-run \
  --confirm-execution

abi inspect --result-dir results/my-run
abi report --result-dir results/my-run --type metatranscriptomics

Lifecycle and discovery commands support --output-json for structured automation. Run abi <command> --help for the exact options of management commands such as agent, job, and install-skills.

How the lifecycle protects your run

Command	What you get	Does it execute analysis tools?
abi query	Fast workflow metadata from the DAG and tool registry	No
abi plan	Resolved steps, commands, inputs, outputs, and dependencies	No
abi check	Input, resource, executable, and runtime diagnostics	No
abi dry-run	Plan, provenance bundle, table skeletons, report preview	No
abi run	Executed workflow and recorded artifacts	Yes, after confirmation
abi inspect	Validation and summary of an existing result directory	No
abi report	Rebuilt Markdown and HTML reports	No analysis execution

Run where you work

Local and Conda environments

ABI currently maps 99 registered tool IDs to 21 declared Conda environments through environments.yaml. Treat that manifest as the source of truth rather than copying the counts into automation. ABI checks explicit overrides, populated repository roots, global Conda-family installations, and finally the Linux user data directory.

Use abi env discover --output-json to inspect the selected root and Python paths. Set ABI_MAMBA_ROOT for an authoritative override; AUTOPLASM_MAMBA_ROOT remains available for backward compatibility.

Docker

Docker is optional. Dockerfiles are provided for amplicon, RNA-seq, bacterial WGS, metatranscriptomics, and plasmid analysis. EasyMetagenome and ViWrap currently use managed local environments.

docker build -f docker/Dockerfile.amplicon -t abi-amplicon .

docker run --rm abi-amplicon list-types
docker run --rm -v "$PWD:/data" abi-amplicon \
  init --type amplicon_16s --outdir /data/amplicon-work

docker compose -f docker/docker-compose.yml up -d

Image size depends on the platform, tool/database versions, and build cache. Measure the exact tag you plan to deploy. CI never builds images automatically for pull requests, pushes, tags, or releases. A manual build is recommended after container inputs change and before publishing an image:

gh workflow run docker.yml --ref master \
  -f plugin=amplicon -f push=false -f push_to_dockerhub=false

See the Linux support plan for cross-machine installation criteria and the manual Docker policy.

Nextflow, Snakemake, HPC, cloud, and queued jobs

Export a workflow to Nextflow or Snakemake, select a runtime backend, or submit work through the queue-backed Job Service when a local foreground process is not enough.

abi export-nextflow --type metatranscriptomics --output workflow.nf
abi export-snakemake --type metatranscriptomics --output Snakefile

abi run --type metatranscriptomics --engine snakemake \
  --config path/to/config.yaml --confirm-execution
abi run --type metatranscriptomics --engine hpc --scheduler slurm \
  --config path/to/config.yaml --confirm-execution

abi job-service --host 127.0.0.1 --port 18791 --workers 2 --subprocess-workers
abi job submit --command run --analysis-type metatranscriptomics --confirm-execution
abi job status <JOB_ID>
abi job artifacts <JOB_ID>
abi job cancel <JOB_ID>

Subprocess workers support force-cancel with a SIGTERM-to-SIGKILL grace period. See the Job Service guide and HPC guide.

Use ABI with an AI agent

ABI exposes the same core operations through JSON CLI responses, provider-specific tool descriptors, MCP, a headless dispatcher, and HTTP jobs.

# Install a repository-scoped integration and diagnose it
abi agent install codex --scope project
abi agent doctor codex --scope project

# Start the safe MCP stdio profile
abi-mcp

# Export descriptors for your model provider
abi export-tools --type metatranscriptomics --format openai --provider openai
abi export-tools --type metatranscriptomics --format anthropic
abi export-tools --type metatranscriptomics --format gemini

# Invoke an ABI command from a worker process
abi dispatch --command list-types --arguments '{}'

The default MCP safe profile omits execution and management tools. abi-mcp --profile full adds confirmation-gated execution. Ready-to-load Claude Code, OpenCode, and Codex assets live under integrations/.

For system prompts or programmatic discovery:

import abi

print(abi.get_agent_guide())
print(abi.list_plugins_summary())

See the Agent usage guide for provider setup and permission details.

Turn results into scientific figures

abi-sciplot validates a declarative figure specification and renders publication-ready PDF, SVG, PNG, or TIFF output. It supports 15 plot types, three themes, linting, and SHA-256 provenance.

abi-sciplot validate --spec figure.yaml
abi-sciplot render --spec figure.yaml
abi-sciplot lint --spec figure.yaml
abi-sciplot list-plot-types

See the SciPlot design and usage guide.

Reproduce a production runtime

An ordinary runtime lock is an audit snapshot. A strict lock verifies Conda packages, declared tools, databases, host runtime, ABI version, Git commit, and release-scope readiness.

abi lock-runtime \
  --output-dir locks/candidate \
  --prefix abi-production \
  --mamba-root /path/to/mamba \
  --resource-root /path/to/resources \
  --db-profile full \
  --strict

Strict mode fails closed when the release environment is incomplete or the code identity is not clean. Use --require-all-tools only when every optional registered capability must be certified.

See release-ready runtime locks for the resource layout, immutable lock policy, and managed cloud procedure.

Project status and expectations

ABI is currently alpha software. Its core contracts, built-in planning paths, dry-runs, packaging, and adapters are tested, but production readiness still depends on the underlying tools and your validation data.

Before production use, pin the ABI version, capture a strict runtime lock, verify tool and database versions, and define biological acceptance criteria for representative samples.

The plasmid workflow has passed assembly-mode RefSeq validation for a three-plasmid dataset. Other claims and workflow-specific validation evidence are tracked in the workflow validation guide.

Extend ABI or contribute

Transport-neutral behavior belongs in src/abi/; CLI, MCP, HTTP, and provider integrations stay thin. Built-in workflows combine Python adapters in src/abi/plugins/ with declarative definitions in plugins/<analysis_type>/.

Register a third-party plugin with the abi.plugins entry-point group:

[project.entry-points."abi.plugins"]
my_analysis = "my_package.plugins:MyPlugin"

Validate a plugin's declarative DAG and contracts before sharing it:

abi contract-lint --type my_analysis
abi contract-lint --type my_analysis --strict

For local development:

pip install -e ".[dev]"

ruff check src/ tests/
ruff format --check src/ tests/
mypy src/abi/ --ignore-missing-imports
pytest tests/ -v --tb=short
python -m build

Start with the development guide, plugin development guide, and API reference.

Documentation

• Components and architecture
• Using ABI: lifecycle and examples
• Development standards
• ABI specification
• Agent usage
• Plugin development
• Workflow validation
• Runtime locks
• Job Service
• HPC development
• RNA-seq workflow
• Metagenomic plasmid workflow
• Release guide
• Full hosted documentation

License

ABI is available under the MIT License. See LICENSE.