abi-agent 1.5.6

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

ABI — Agent-Bioinformatics Interface

ABI is a Python interface layer for agent-driven bioinformatics workflows. It standardizes 7 analysis plugins behind a common plan -> dry-run -> run -> inspect -> report lifecycle, with provenance, standard TSV tables, multi-LLM tool descriptors (OpenAI, Anthropic Claude, Google Gemini, DeepSeek, 智谱 GLM, Kimi, Qwen, MiniMax), optional MCP transport, Nextflow export/runtime support, DAG/contract static analysis, resource auto-discovery + install, a publication-grade scientific figure compiler (abi-sciplot, 15 plot types, PDF/SVG/PNG/TIFF), and a queue-backed HTTP Job Service with force-kill capability.

:cn: 中文版

Engineering status (v1.5.5 source, 2026-07-12): local freeze candidate. 2296 tests pass (83% statement coverage), risk-based module coverage gates pass, and a clean wheel runs all 7 built-in plugin dry-runs. Hard freeze still requires a green remote Python 3.10-3.13 matrix, fixed real-tool benchmarks with biological acceptance criteria, two defect-only release candidates, and one week without new P0/P1 defects.

Installation

pip install abi-agent

# Development install
pip install -e ".[dev]"

# Optional MCP server dependencies
pip install -e ".[dev,mcp]"

Python 3.10-3.13 is supported.

Quick Start

# List installed analysis plugins
abi list-types

# Show version
abi --version

# Build a plan without executing tools
abi plan --type metatranscriptomics --config config.yaml --sample-sheet samples.tsv

# Write dry-run provenance and table skeletons
abi dry-run --type metatranscriptomics --config config.yaml --sample-sheet samples.tsv

# Execute only after explicit confirmation
abi run --type metatranscriptomics --config config.yaml --sample-sheet samples.tsv \
  --confirm-execution

# Inspect and rebuild reports
abi inspect --result-dir results/
abi report --result-dir results/ --type metatranscriptomics

# Lightweight metadata query (~50ms, reads DAG + tool registry only)
abi query --type metatranscriptomics --what stages
abi query --type metatranscriptomics --what tools
abi query --type metatranscriptomics --what platforms
abi query --type metatranscriptomics --step qc_fastp --what inputs

# Export agent/runtime interfaces
abi export-nextflow --type metatranscriptomics --output workflow.nf
abi export-openai-tools --type metatranscriptomics --format responses    # legacy compat
abi export-tools --type metatranscriptomics --format openai --provider openai   # OpenAI
abi export-tools --type metatranscriptomics --format openai --provider deepseek # DeepSeek
abi export-tools --type metatranscriptomics --format openai --provider zhipu    # 智谱 GLM
abi export-tools --type metatranscriptomics --format anthropic           # Claude
abi export-tools --type metatranscriptomics --format gemini              # Gemini
abi export-agent-context --type metatranscriptomics --format json
abi doctor-agent --type metatranscriptomics

# Resource discovery and auto-install
abi check-resources --type metagenomic_plasmid
abi setup-resources --type metagenomic_plasmid --confirm

# Static contract / DAG validation (L1 literature + L2 path + L3 validation)
abi contract-lint --type metagenomic_plasmid
abi contract-lint --type metagenomic_plasmid --strict

# Headless agent dispatch (used by Job Service workers)
abi dispatch --command list-types --arguments '{}'

# Start the safe MCP stdio server for agent platforms
abi-mcp

# Install and diagnose an agent integration (claude-code, opencode, codex)
abi agent install codex --scope project
abi agent doctor codex --scope project

# Scientific figure compiler (validate, render, lint, export)
abi-sciplot validate --spec figure.yaml
abi-sciplot render --spec figure.yaml
abi-sciplot lint --spec figure.yaml
abi-sciplot list-plot-types

# Job Service with optional force-kill subprocess workers
abi job-service --workers 2 --store jobs.json --subprocess-workers

All agent-facing commands support --output-json.

Release-Ready Runtime Locks

ABI can snapshot the exact Conda packages, registered tools, databases, host runtime, ABI version, and Git commit used by a production workflow. A normal lock-runtime invocation is an audit snapshot; --strict is the release gate.

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

Strict mode fails closed on missing/extra Conda environments, omitted or failed package snapshots, unresolved release-scope tools, non-ready release-scope resources, missing code identity, or a dirty Git worktree. Add --require-all-tools only when certifying every optional registered capability.

The canonical cloud layout keeps plasmid/metagenome databases under resources/autoplasm/ and RNA references at the top level. On the managed ABI cloud host, scripts/cloud/prepare_release_lock.sh creates checksum-verified, read-only, version-and-commit-qualified locks atomically. The current helper certifies the six provisioned workflows; viral_viwrap remains outside that release scope until its separate multi-environment and database bundle is installed. See release-ready runtime locks.

Built-In Analysis Types

Type	Tools	Description
amplicon_16s	10	16S rRNA microbiome: cutadapt → vsearch merge/derep/denoise → SINTAX taxonomy → MAFFT+FastTree phylogeny → diversity (alpha/beta). ✅ Software workflow validated
rnaseq_expression	5	Bulk RNA-seq: fastp → STAR → featureCounts → build_count_matrix → DESeq2 → clusterProfiler. ✅ Software workflow validated
wgs_bacteria	5	Bacterial isolate WGS: fastp → SPAdes → Prokka → MLST → AMRFinderPlus. ✅ Software workflow validated
metatranscriptomics	3	Metatranscriptomics: fastp → STAR/HISAT2 → featureCounts. ✅ Software workflow validated
easymetagenome	10	P0 shotgun metagenomics: fastp → kneaddata → kraken2 → bracken → humann4 + HUMAnN utilities → seqkit. 3 workflow presets (taxonomy, functional, full), DAG-driven planner, internal handlers. ✅ Software workflow validated
viral_viwrap	1	Viral metagenomics: wraps ViWrap 1.3.1 — binning → taxonomy → host prediction → quality filtering. Managed external CLI plugin with environment checker. ✅ Software workflow validated
metagenomic_plasmid	64	Flagship plasmid analysis: QC → assembly → plasmid detection → annotation → abundance → community analysis → visualization. 10 conda envs, 90-node declarative DAG, 16 standard tables, 8 sciplot figures. ✅ Software workflow validated; assembly-mode refseq validation passed (3 plasmids, genomad+platon, majority_vote)

The autoplasm CLI is preserved for backward compatibility:

autoplasm dry-run --config examples/config_minimal.yaml --profile dry_run

Docker

Pre-built Docker images for 5 of 7 plugins (easymetagenome and viral_viwrap run locally):

# Build a plugin image
docker build -f docker/Dockerfile.amplicon -t abi-amplicon .

# Run a workflow inside the container
docker run --rm -v $PWD:/data abi-amplicon \
  abi plan --type amplicon_16s --outdir /data/results

# Start all services with Docker Compose
docker compose -f docker/docker-compose.yml up -d

Images: abi-amplicon (~1.5 GB), abi-rnaseq (~2.5 GB), abi-wgs (~2.0 GB), abi-metatranscriptomics (~2.0 GB), abi-plasmid (~15 GB). See docker/docker-compose.yml for the full orchestration.

Architecture

Agent Platforms (Claude / ChatGPT / Cursor / CI)
        │
        v
Transport Layer   CLI JSON  │  OpenAI/Anthropic/Gemini Tools  │  MCP  │  HTTP Job API  │  Skills  │  Query
        │
        v
ABIAgentInterface   plan / dry_run / run / inspect / report / dispatch / query
        │
        v
ABI Core            schemas  │  provenance  │  permissions  │  diagnostics
                    tables   │  tools       │  executor     │  report
                    contracts│  dag         │  figures      │  dag_planner
                    tsv_mapping  │  sciplot  │  resources  │  workflow
                    tool_descriptors  │  internal  │  results
        │
        v
Plugins             amplicon_16s/  rnaseq_expression/  wgs_bacteria/
                    metatranscriptomics/  easymetagenome/
                    viral_viwrap/  metagenomic_plasmid/
        │
        v
Runtimes            local  │  Docker  │  Nextflow  │  HPC (SLURM/PBS)  │  cloud  │  Job Service

Design Principles

Principle	Meaning
Thick Core	Lifecycle, permissions, diagnostics, provenance, standard tables, plugin discovery all live in Core.
Thin Transport	CLI, OpenAI tools, MCP, HTTP only adapt calls — no business logic.
Clean Plugin	Biology logic in plugins, generic mechanisms in Core.
Agent Doesn't Code	Agents call ABI through schemas, descriptors, JSON envelopes, and diagnostic hints.

Agent Transports

ABIAgentInterface is the stable transport-neutral boundary used by:

• CLI JSON through --output-json
• abi dispatch --command <name> --arguments '<json>' for headless subprocess dispatch
• abi query for lightweight metadata queries (~50ms) — pipeline stages, tools, platforms, and step-level I/O directly from DAG + tool registry, no plan required
• Multi-LLM descriptors from abi export-tools --format openai|anthropic|gemini [--provider ...] covering 7+ providers
• OpenAI-compatible descriptors from abi export-openai-tools (backward compat)
• MCP stdio server via abi-mcp (or python -m abi.mcp.server) — auto-generated from SSOT; the default safe profile omits execution and management tools, while abi-mcp --profile full adds the confirmation-gated abi_run
• HTTP Job Service via abi job-service and abi job submit/list/status/artifacts/cancel
• Agent integration installer and diagnostics via abi agent install|doctor
• Ready-to-load Claude Code, OpenCode, and Codex assets under integrations/

Plan summarization: abi plan envelopes now include a summary field (pipeline stages, key tools, platforms) so agents understand the workflow structure without reading the full execution_plan.json. This saves 78-95% tokens on plan output for complex pipelines.

Agents can also get operating instructions programmatically:

import abi
print(abi.get_agent_guide())        # compact operating guide for system prompt
print(abi.list_plugins_summary())   # list all installed analysis plugins

Execution tools require explicit confirmation. abi run, abi_run, and Job Service execution submissions return confirmation_required unless confirm_execution=true or --confirm-execution is provided.

Job Service

# Start with in-process workers
abi job-service --host 127.0.0.1 --port 18791 --workers 1 --store jobs.json

# Start with subprocess workers for force-kill support
abi job-service --workers 2 --subprocess-workers

# Client commands
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>          # SIGTERM → SIGKILL (3s grace) for subprocess workers

When --subprocess-workers is enabled, each job runs in an isolated abi dispatch process and can be force-killed via SIGTERM on cancel. The job record tracks worker_pid and remote_scheduler_job_id (for HPC/cloud backends).

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

# CI-equivalent tests, branch coverage, and risk-based module gates
python -m pytest tests/ src/abi/sciplot/tests/ \
  -m "not requires_tools" --strict-markers \
  --cov=src/abi --cov-branch --cov-report=json:coverage.json \
  --cov-fail-under=75
python scripts/check_module_coverage.py --coverage coverage.json

python -m build
python -m twine check dist/*

Repository-local bioinformatics environments are described under envs/ and resolved from .mamba/envs/<env_name>/bin. Set ABI_MAMBA_ROOT to override the default .mamba root; AUTOPLASM_MAMBA_ROOT remains accepted for compatibility.

More details:

• ABI Spec v0.1
• Development Guide
• API Reference — Sphinx auto-generated from docstrings
• abi_sciplot Design — Scientific figure compiler
• Plugin Development Guide
• RNA-seq Workflow
• Workflow Validation
• HPC Development
• OpenAI/LLM Interface Standard
• Agent Usage Guide
• Job Service Guide
• Release Guide
• Dev Log

Public SDK

Plugin authors should depend on these public modules:

Module	Contents
abi.interfaces	ABIPlugin, ABIDryRunPlugin, ABIInitializablePlugin, ABIResourcePlugin, ABIResultValidationPlugin
abi.schemas	SampleInput, SampleContext, PlanStep, ExecutionPlan (ABI-prefixed aliases available)
abi.tools	ToolRegistry, ToolSkill, GenericCommandSkill, RunResult
abi.provenance	RunLogger, PipelineProgressRecorder, TSV provenance writers
abi.errors	ABIError, ConfigError, SampleSheetError, ToolError, MissingTemplateParamError
abi.contracts	ContractViolationError, validate_output_contract, evaluate_assertions, save_checksums_atomic, run_contract_lint, WorkflowSpec, WorkflowStepSpec, load_workflow_spec
abi.dag	infer_dag, ABIDAG, StepBinding — DAG inference with L1 (literature) / L2 (path) / L3 (validation) layers
abi.dag_planner	UniversalDAG, build_plan_from_dag, PathTemplateContext — declarative plan generation from pipeline_dag.yaml. Replaces all hand-written build_plan() boilerplate; used by all 7 plugins. (v1.3.2)
abi.tsv_mapping	TSVMapper, generate_rows — YAML-driven TSV/JSON/log parsing with 3 source types (tsv_mapping, json_mapping, key_value_log). Replaces ~14 boilerplate parser functions. (v1.3.2)
abi.sciplot	FigureSpec, render_figure, validate_spec, lint_figure — publication-grade scientific figure compiler. Pydantic schema, 15 plot types (including PCoA, volcano, stacked bar, heatmap, phylogeny), plotnine+seaborn backends, PDF/SVG/PNG/TIFF export, 3 themes, FigureLint, SHA256 provenance. (v1.4.0)
abi.tool_descriptors	ABI_AGENT_TOOLS, TOOL_ALIASES, export_openai_compatible, export_anthropic, export_gemini, PROVIDER_PROFILES
abi.resources	check_resources, setup_resources — plugin-capability-based resource discovery and managed setup
abi.internal	ABIInternalHandler, InternalHandlerContext, InternalHandlerResult — transport-neutral internal DAG nodes for steps without external tools
abi.results	ABIResultWriter, validate_abi_result_dir — shared result/provenance writer
abi.tables	StandardTableManager — YAML-driven table normalization
abi.config	resolved_mamba_root, PROJECT_ROOT, load_yaml, deep_merge — env resolution with 4-level priority
abi.testing	assert_plugin_contract

Register third-party plugins with:

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

License

MIT, see LICENSE.