# <img src="figures/abi_logo.png" alt="ABI" width="36" height="36" align="top"> 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.

[![PyPI](https://img.shields.io/pypi/v/abi-agent?style=flat-square&color=blue)](https://pypi.org/project/abi-agent/)
[![Python](https://img.shields.io/pypi/pyversions/abi-agent?style=flat-square)](https://pypi.org/project/abi-agent/)
[![CI](https://img.shields.io/github/actions/workflow/status/sleepinlava/BAI/ci.yml?branch=master&style=flat-square)](https://github.com/sleepinlava/BAI/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/badge/coverage-CI%20%E2%89%A575%25-brightgreen?style=flat-square)](https://github.com/sleepinlava/BAI/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-Sphinx-blue?style=flat-square)](https://sleepinlava.github.io/BAI/)
[![Status](https://img.shields.io/badge/status-alpha-orange?style=flat-square)](https://github.com/sleepinlava/BAI)
[![License](https://img.shields.io/pypi/l/abi-agent?style=flat-square)](https://github.com/sleepinlava/BAI/blob/master/LICENSE)

> :cn: [中文版](README.zh.md)

## 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:

```bash
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:

```text
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:

```bash
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:

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

   For example:

   ```text
   /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:

   ```text
   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](docs/en/agent_usage.md)
for integration setup and permission boundaries.

### From the ABI CLI

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

```bash
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.

```bash
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:

```bash
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`.

```bash
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.

```bash
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:

```text
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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:

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

See the [Linux support plan](docs/en/linux_support_plan.md) 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.

```bash
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](docs/en/job_service.md) and [HPC guide](docs/en/hpc_development.md).

## 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.

```bash
# 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:

```python
import abi

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

See the [Agent usage guide](docs/en/agent_usage.md) 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.

```bash
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](docs/en/abi_sciplot_design.md).

## 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.

```bash
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](docs/en/runtime_locks.md) 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](docs/en/workflow_validation.md).

## 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:

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

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

```bash
abi contract-lint --type my_analysis
abi contract-lint --type my_analysis --strict
```

For local development:

```bash
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](docs/en/development.md), [plugin development guide](docs/en/plugin_development_guide.md), and [API reference](docs/en/api.rst).

## Documentation

- [Components and architecture](docs/en/components_and_architecture.md)
- [Using ABI: lifecycle and examples](docs/en/usage_guide.md)
- [Development standards](docs/en/development_workflow.md)
- [ABI specification](docs/en/abi_spec_v0.1.md)
- [Agent usage](docs/en/agent_usage.md)
- [Plugin development](docs/en/plugin_development_guide.md)
- [Workflow validation](docs/en/workflow_validation.md)
- [Runtime locks](docs/en/runtime_locks.md)
- [Job Service](docs/en/job_service.md)
- [HPC development](docs/en/hpc_development.md)
- [RNA-seq workflow](docs/en/rnaseq_expression_workflow.md)
- [Metagenomic plasmid workflow](docs/en/metagenomic_plasmid.md)
- [Release guide](docs/en/release.md)
- [Full hosted documentation](https://sleepinlava.github.io/BAI/)

## License

ABI is available under the MIT License. See [LICENSE](LICENSE).
