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.

🇨🇳 中文版

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

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

# Plugins are downloaded on demand from abi-plugin GitHub Releases, not PyPI:
pip install https://github.com/sleepinlava/abi-plugin/releases/download/v1.7.0/abi_agent_plugin_metatranscriptomics-1.7.0-py3-none-any.whl

# Optional integrations
pip install "abi-agent[mcp]"       # MCP server

# Read-only discovery and diagnostics for externally prepared tool environments
abi env discover --output-json
abi env doctor --type rnaseq_expression --output-json

ABI does not create tool environments. Environment provisioning belongs to an external system; abi env discover and abi env doctor read the machine state and report 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 --recurse-submodules 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 declare managed resources. ABI never downloads or installs them; setup is an external-system responsibility. Report per-resource readiness and manual-preparation guidance instead.

abi setup-resources --type metagenomic_plasmid            # readiness + guidance
abi setup-resources --type metagenomic_plasmid --dry-run  # preparation plan

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

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

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 emits structured result tables and audit reports. Use external plotting tools for publication figures; SciPlot and Study are no longer bundled with ABI. The core package does not require NumPy, pandas, SciPy, or plotting libraries. Analysis plugins declare their own scientific dependencies.

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 analysis plugins are self-contained packages under src/abi/plugins/<analysis_type>/ — Python adapters and their declarative definitions (DAG, tool registry, limitations) live side by side and ship as per-plugin distributions (abi-agent-plugin-<id>); the core abi-agent wheel stays plugin-free.

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.