ai4gh 1.0.0
Comprehensive Python SDK, MCP server, and compliance test suite for GA4GH specifications
Requires Python: >=3.10
Keywords: beacon, drs, ga4gh, genomics, mcp, phenopackets, vrs

# ai4gh

Comprehensive Python SDK, MCP server, and compliance test suite for [GA4GH](https://ga4gh.org) (Global Alliance for Genomics and Health) specifications.

## Features

- **Unified SDK**: Single Python package covering 14 GA4GH specifications
- **MCP Server**: Full Model Context Protocol surface with 13 tools, 14 resources, 5 prompts
- **Compliance Testing**: Per-spec test suites with JSON/HTML/JUnit reporting
- **Plugin Architecture**: Install only the specs you need via pip extras
- **Async-First**: All network operations are async (httpx + tenacity)
- **CLI**: `ai4gh` command for compliance testing, MCP serving, and configuration

## Quick Run (no install)

```bash
# Run directly with uvx — no install needed
uvx ai4gh --help
uvx ai4gh mcp serve
uvx ai4gh test beacon https://beacon.example.org
```

## Installation

```bash
# Core only
pip install ai4gh

# With specific specs
pip install "ai4gh[beacon,drs]"

# Everything
pip install "ai4gh[all]"

# Development
uv sync --extra dev
```

## Quick Start

### Python SDK

```python
from ai4gh.specs.drs.client import DRSClient

async with DRSClient(base_url="https://drs.example.org") as client:
    obj = await client.get_object("drs://example/abc123")
    print(obj.name, obj.size)
```

### Beacon Query

```python
from ai4gh.specs.beacon.client import BeaconClient

async with BeaconClient(base_url="https://beacon.example.org") as client:
    result = await client.query("BRCA1")
    print(result)
```

### MCP Server

```bash
# Start MCP server on stdio
ai4gh mcp serve
```

### Compliance Testing

```bash
# Run compliance tests
ai4gh test beacon https://beacon.example.org

# JSON report
ai4gh test drs https://drs.example.org --format json -o report.json

# HTML report
ai4gh test beacon https://beacon.example.org --format html -o report.html

# List available test suites
ai4gh list-specs
```

### Configuration

```bash
# Show current config
ai4gh config show

# Initialize config file
ai4gh config init
```

## GA4GH Specifications Covered

| Spec | Plugin | Phase | Status |
|------|--------|-------|--------|
| Beacon v2 | `ai4gh[beacon]` | Tier 1 | Done |
| DRS v1.4 | `ai4gh[drs]` | Tier 1 | Done |
| htsget v1.3 | `ai4gh[htsget]` | Tier 1 | Done |
| refget v2 | `ai4gh[refget]` | Tier 1 | Done |
| Phenopackets v2 | `ai4gh[phenopackets]` | Tier 1 | Done |
| VRS v2.0 | `ai4gh[vrs]` | Tier 1 | Done |
| WES v1.1 | `ai4gh[wes]` | Tier 2 | Done |
| TES v1.1 | `ai4gh[tes]` | Tier 2 | Done |
| TRS v2.0.1 | `ai4gh[trs]` | Tier 2 | Done |
| Data Connect v1 | `ai4gh[data-connect]` | Tier 2 | Done |
| Passports v1 | `ai4gh[passports]` | Tier 3 | Done |
| DUO | `ai4gh[duo]` | Tier 3 | Done |
| Crypt4GH v1 | `ai4gh[crypt4gh]` | Tier 3 | Done |
| Pedigree v1 | `ai4gh[pedigree]` | Tier 3 | Done |
| Cat-VRS v1 | (in vrs) | Tier 3 | Done |
| VA-Spec v1 | (in vrs) | Tier 3 | Done |

## MCP Server

The MCP server exposes GA4GH operations as tools for AI agents (Claude Code, Cursor, etc.).

### Tools (13)

- `drs_get_object` - Get a DRS object by ID
- `beacon_query` - Query a Beacon v2 server
- `htsget_reads` - Get read data from htsget
- `refget_sequence` - Get reference sequence by checksum
- `vrs_compute_id` - Compute VRS identifier
- `phenopacket_validate` - Validate a Phenopacket
- `wes_submit_run` - Submit workflow to WES
- `tes_create_task` - Create TES task
- `trs_search_tools` - Search TRS registry
- `data_connect_search` - Query via Data Connect
- `passport_decode` - Decode GA4GH Passport JWT
- `duo_match` - Check DUO compatibility
- `pedigree_validate` - Validate pedigree structure

### Resources (15)

- `ga4gh://specs` - Specification index
- `ga4gh://specs/{spec_id}` - Individual spec metadata (14 specs)

### Prompts (5)

- `find_variants` - Search for genetic variants across beacons
- `patient_summary` - Generate clinical summary from Phenopacket
- `rare_disease_search` - Search federated rare disease data
- `workflow_submit` - Submit bioinformatics workflow
- `compliance_report` - Generate compliance report

### Claude Code / MCP Integration

Add to your Claude Code MCP config (`.claude/settings.json`):

```json
{
  "mcpServers": {
    "ai4gh": {
      "command": "uvx",
      "args": ["ai4gh", "mcp", "serve"]
    }
  }
}
```

All 13 tools become available to Claude as MCP tools. No install required.

## Architecture

```
ai4gh/
  core/           # Config, auth, transport, plugin system
  specs/           # Per-spec plugins (client + models)
    beacon/        # Beacon v2
    drs/           # Data Repository Service
    htsget/        # Streaming reads/variants
    refget/        # Reference sequences
    phenopackets/  # Clinical phenotype exchange
    vrs/           # Variant representation
    wes/           # Workflow execution
    tes/           # Task execution
    trs/           # Tool registry
    data_connect/  # SQL-like data queries
    passports/     # Federated auth (JWT)
    duo/           # Data use ontology
    crypt4gh/      # File encryption
    pedigree/      # Family relationships
    cat_vrs/       # Categorical variants
    va_spec/       # Variant annotation
  mcp/             # MCP server (tools, resources, prompts)
  compliance/      # Compliance test suites + report generation
  cli/             # Typer CLI
```

## Development

```bash
# Install with dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=ai4gh --cov-report=term-missing

# Lint
uv run ruff check .

# Type check
uv run mypy src/

# Build
uv run hatch build
```

## License

Apache-2.0