variantgrid-api 1.2.0__tar.gz → 1.3.1__tar.gz

{variantgrid_api-1.2.0/src/variantgrid_api.egg-info → variantgrid_api-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: variantgrid_api
-Version: 1.2.0
+Version: 1.3.1
 Summary: A Python API client for VariantGrid
 Author-email: Dave Lawrence <davmlaw@gmail.com>
 License: MIT License
@@ -66,6 +66,26 @@ enrichment_kit = EnrichmentKit(name="idt_haem", version=1)
 result = api.create_enrichment_kit(enrichment_kit)
 ```
 
+## Annotate a VCF and download it back
+
+Upload a VCF, wait for VariantGrid to import + annotate any novel variants, then download the
+cohort-level annotated export (all samples, single-sample VCFs included). The whole flow is a one-liner:
+
+```python
+from variantgrid_api.api_client import VariantGridAPI
+
+api = VariantGridAPI(server="https://variantgrid.com", api_token="YOUR_API_TOKEN")
+
+# export_type is "vcf" (gzipped *.vcf.gz) or "csv" (zipped *.csv.zip)
+path = api.annotate_vcf("input.vcf", export_type="vcf", dest_path="/data/results/")
+print(f"Annotated VCF written to {path}")
+```
+
+There's also a `vg_api annotate_vcf` command line tool (first call uploads, run it again to download once
+ready), a step-by-step form (`upload_file` → `wait_for_annotation` → `download_annotated`), and a "submit now,
+download later" pattern for long-running jobs. See
+**[Annotate a VCF](https://github.com/SACGF/variantgrid_api/wiki/Annotate-a-VCF)** on the wiki.
+
 ## Testing
 
 ```

{variantgrid_api-1.2.0 → variantgrid_api-1.3.1}/README.md

@@ -23,6 +23,26 @@ enrichment_kit = EnrichmentKit(name="idt_haem", version=1)
 result = api.create_enrichment_kit(enrichment_kit)
 ```
 
+## Annotate a VCF and download it back
+
+Upload a VCF, wait for VariantGrid to import + annotate any novel variants, then download the
+cohort-level annotated export (all samples, single-sample VCFs included). The whole flow is a one-liner:
+
+```python
+from variantgrid_api.api_client import VariantGridAPI
+
+api = VariantGridAPI(server="https://variantgrid.com", api_token="YOUR_API_TOKEN")
+
+# export_type is "vcf" (gzipped *.vcf.gz) or "csv" (zipped *.csv.zip)
+path = api.annotate_vcf("input.vcf", export_type="vcf", dest_path="/data/results/")
+print(f"Annotated VCF written to {path}")
+```
+
+There's also a `vg_api annotate_vcf` command line tool (first call uploads, run it again to download once
+ready), a step-by-step form (`upload_file` → `wait_for_annotation` → `download_annotated`), and a "submit now,
+download later" pattern for long-running jobs. See
+**[Annotate a VCF](https://github.com/SACGF/variantgrid_api/wiki/Annotate-a-VCF)** on the wiki.
+
 ## Testing
 
 ```

{variantgrid_api-1.2.0 → variantgrid_api-1.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "variantgrid_api"
-version = "1.2.0"
+version = "1.3.1"
 description = "A Python API client for VariantGrid"
 authors = [
     { name = "Dave Lawrence", email = "davmlaw@gmail.com" }
@@ -23,6 +23,9 @@ dependencies = [
     "dataclasses-json",
 ]
 
+[project.scripts]
+vg_api = "variantgrid_api.cli:main"
+
 [project.optional-dependencies]
 test = ["pytest>=8", "pytest-cov>=5", "responses"]
 

variantgrid_api-1.3.1/src/variantgrid_api/api_client.py

@@ -0,0 +1,419 @@
+import datetime
+import json
+import logging
+import re
+import time
+import urllib
+import warnings
+from enum import Enum
+from pathlib import Path
+from typing import List, Optional, Callable, Union
+
+import requests
+
+from variantgrid_api.data_models import EnrichmentKit, SequencingRun, SampleSheet, JointCalledVCF, \
+    SampleSheetLookup, SequencingFile, QCGeneList, QCExecStats, QCGeneCoverage, SequencerModel, Sequencer
+
+
+_UNSET = object()
+
+
+class DateTimeEncoder(json.JSONEncoder):
+    def default(self,o):
+        if isinstance(o,(datetime.date, datetime.datetime)):
+            return o.isoformat()
+        return super().default(o)
+
+
+class EmptyInputPolicy(Enum):
+    IGNORE = "ignore"
+    WARN = "warn"
+    ERROR = "error"
+
+
+class AnnotationError(Exception):
+    """Raised when the server reports an error while importing/annotating an uploaded file."""
+
+    def __init__(self, message, status: Optional[dict] = None):
+        super().__init__(message)
+        self.status = status
+
+
+class VariantGridAPI:
+    def __init__(self, server, api_token,
+                 empty_input_policy=EmptyInputPolicy.ERROR,
+                 logger: Optional[logging.Logger] = None,
+                 log_request=False, log_response=False
+    ):
+        self.server = server
+        self.headers = {"Authorization": f"Token {api_token}"}
+        if logger is None:
+            logger = logging.getLogger(__name__)
+        self.logger = logger
+        self.validation_handler = self._get_validation_handler(empty_input_policy, logger)
+        self.log_request = log_request
+        self.log_response = log_response
+
+    def _get_url(self, url):
+        return urllib.parse.urljoin(self.server, url)
+
+    def _post(self, path, json_data):
+        url = self._get_url(path)
+        json_string = json.dumps(json_data, cls=DateTimeEncoder)
+        if self.log_request:
+            self.logger.info("POST to '%s', JSON: %s", url, json_string)
+        response = requests.post(url,
+                                 headers={**self.headers, "Content-Type": "application/json"},
+                                 data=json_string)
+
+        extra_error_message = f"{url=}, {json_string=}"
+        return self._handle_json_response(response, extra_error_message)
+
+    def _handle_json_response(self, response, extra_error_message: Optional[str] = None):
+        try:
+            json_response = response.json()
+            if self.log_response:
+                self.logger.info("Response from '%s', JSON: %s", response.url, json_response)
+        except Exception as e:
+            json_response = f"Couldn't convert JSON: {e}"
+        if not response.ok:
+            if extra_error_message:
+                self.logger.error(extra_error_message)
+            self.logger.error("Response: %s", json_response)
+            response.raise_for_status()
+        return json_response
+
+    @staticmethod
+    def _get_validation_handler(empty_input_policy: EmptyInputPolicy, logger: logging.Logger) -> Callable:
+        def _ignore(msg):
+            pass
+
+        def _warn(msg):
+            logger.warning(msg)
+
+        def _error(msg):
+            raise ValueError(msg)
+
+        return {
+            EmptyInputPolicy.IGNORE: _ignore,
+            EmptyInputPolicy.WARN: _warn,
+            EmptyInputPolicy.ERROR: _error,
+        }[empty_input_policy]
+
+    def _validate_string(self, info: str, s: Optional[str]) -> None:
+        if s is None:
+            self.validation_handler(f"{info}: is None")
+        elif s == "":
+            self.validation_handler(f"{info}: empty string")
+
+    def _validate_object(self, info: str, obj):
+        if obj is None:
+            self.validation_handler(f"{info}: is None")
+
+    def _validate_list(self, info: str, list_obj: List):
+        if not list_obj:
+            self.validation_handler(f"{info}: empty list")
+
+    def create_experiment(self, experiment: str):
+        self._validate_string("experiment", experiment)
+        json_data = {
+            "name": experiment
+        }
+        return self._post("seqauto/api/v1/experiment/", json_data)
+
+    def create_enrichment_kit(self, enrichment_kit: EnrichmentKit):
+        self._validate_object("enrichment_kit", enrichment_kit)
+        return self._post("seqauto/api/v1/enrichment_kit/",
+                          enrichment_kit.to_dict())
+
+
+    def create_sequencer_model(self, sequencer_model: SequencerModel):
+        self._validate_object("sequencer_model", sequencer_model)
+        return self._post("seqauto/api/v1/sequencer_model/",
+                          sequencer_model.to_dict())
+
+    def create_sequencer(self, sequencer: Sequencer):
+        self._validate_object("sequencer", sequencer)
+        return self._post("seqauto/api/v1/sequencer/",
+                          sequencer.to_dict())
+
+    def create_sequencing_run(self, sequencing_run: SequencingRun):
+        self._validate_object("sequencing_run", sequencing_run)
+        return self._post("seqauto/api/v1/sequencing_run/",
+                          sequencing_run.to_dict())
+
+    def create_sample_sheet(self, sample_sheet: SampleSheet):
+        self._validate_object("sample_sheet", sample_sheet)
+        json_data = sample_sheet.to_dict()
+        # We don't want all sequencing_run just the name
+        sequencing_run = json_data.pop("sequencing_run")
+        json_data["sequencing_run"] = sequencing_run["name"]
+        return self._post("seqauto/api/v1/sample_sheet/",
+                          json_data)
+
+    def create_joint_called_vcf(self, joint_called_vcf: JointCalledVCF):
+        self._validate_object("joint_called_vcf", joint_called_vcf)
+        json_data = joint_called_vcf.to_dict()
+        return self._post("seqauto/api/v1/joint_called_vcf/",
+                          json_data)
+
+    def create_sample_sheet_combined_vcf_file(self, sample_sheet_combined_vcf_file: JointCalledVCF):
+        """Deprecated alias for :meth:`create_joint_called_vcf` - use that instead. """
+        warnings.warn(
+            "create_sample_sheet_combined_vcf_file is deprecated; use create_joint_called_vcf instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.create_joint_called_vcf(sample_sheet_combined_vcf_file)
+
+    def create_sequencing_data(self, sample_sheet_lookup: SampleSheetLookup, sequencing_files: List[SequencingFile]):
+        self._validate_object("sample_sheet_lookup", sample_sheet_lookup)
+        self._validate_list("sequencing_files", sequencing_files)
+        records = []
+        for sf in sequencing_files:
+            data = sf.to_dict()
+            # put into hierarchial JSON DRF expects
+            fastq_r1 = data.pop("fastq_r1")
+            fastq_r2 = data.pop("fastq_r2")
+            data["unaligned_reads"] = {
+                "fastq_r1": {"path": fastq_r1},
+                "fastq_r2": {"path": fastq_r2}
+            }
+            records.append(data)
+
+        json_data = {
+            "sample_sheet": sample_sheet_lookup.to_dict(),
+            "records": records
+        }
+        return self._post("seqauto/api/v1/sequencing_files/bulk_create",
+                          json_data)
+
+    def create_qc_gene_list(self, qc_gene_list: QCGeneList):
+        self._validate_object("qc_gene_list", qc_gene_list)
+        json_data = qc_gene_list.to_dict()
+        return self._post("seqauto/api/v1/qc_gene_list/",
+                          json_data)
+
+
+    def create_multiple_qc_gene_lists(self, qc_gene_lists: List[QCGeneList]):
+        self._validate_list("qc_gene_lists", qc_gene_lists)
+        json_data = {
+            "records": [
+                qcgl.to_dict() for qcgl in qc_gene_lists
+            ]
+        }
+        return self._post("seqauto/api/v1/qc_gene_list/bulk_create",
+                          json_data)
+
+    def create_qc_exec_stats(self, qc_exec_stats: QCExecStats):
+        self._validate_object("qc_exec_stats", qc_exec_stats)
+        json_data = qc_exec_stats.to_dict()
+        return self._post("seqauto/api/v1/qc_exec_summary/",
+                          json_data)
+
+    def create_multiple_qc_exec_stats(self, qc_exec_stats: List[QCExecStats]):
+        self._validate_list("qc_exec_stats", qc_exec_stats)
+        json_data = {
+            "records": [
+                qces.to_dict() for qces in qc_exec_stats
+            ]
+        }
+        return self._post("seqauto/api/v1/qc_exec_summary/bulk_create",
+                          json_data)
+
+    def create_multiple_qc_gene_coverage(self, qc_gene_coverage_list: List[QCGeneCoverage]):
+        self._validate_list("qc_gene_coverage_list", qc_gene_coverage_list)
+        json_data = {
+            "records": [
+                qcgc.to_dict() for qcgc in qc_gene_coverage_list
+            ]
+        }
+        return self._post("seqauto/api/v1/qc_gene_coverage/bulk_create",
+                          json_data)
+
+    def upload_file(self, filename: str, path=_UNSET):
+        """ Upload a file via multipart POST to upload/api/v1/file_upload.
+
+            Returns {"uploaded_file_id": <id>, "sha256_hash": <hash>, ...}; identify the upload by
+            uploaded_file_id and/or sha256_hash (the server dedups on the content hash).
+
+            path: SeqAuto-only server-side hint that links the upload to a registered sequencing VCF
+                  (JointCalledVCF / SingleSampleVCF) by path. Defaults to `filename` for backwards
+                  compatibility. Pass path=None to omit the query param entirely - required for ad-hoc
+                  uploads such as the annotate/download flow, where sending a client-side path makes
+                  SeqAuto deployments try (and fail) to match it to a registered VCF. """
+        url = self._get_url("upload/api/v1/file_upload")
+        if path is _UNSET:
+            path = filename
+        params = {"path": path} if path is not None else {}
+        with open(filename, "rb") as f:
+            response = requests.post(url, headers=self.headers, files={"file": f}, params=params)
+            extra_error_message = f"{filename=}"
+            return self._handle_json_response(response, extra_error_message)
+
+    ###############
+    ## Get methods
+
+    def _get(self, path, params=None):
+        url = self._get_url(path)
+        response = requests.get(url,
+                                params,
+                                headers=self.headers)
+
+        extra_error_message = f"{url=}, {params=}"
+        return self._handle_json_response(response, extra_error_message)
+
+    def sequencing_run_has_vcf(self, sequencing_run: SequencingRun, path: Optional[str] = None):
+        """ Returns whether the SequencingRun has a VCF associated with it. If path is set, VCF must match that path
+            otherwise - any VCF present will retur True """
+        return self.sequencing_run_name_has_vcf(sequencing_run.name, path)
+
+    def sequencing_run_name_has_vcf(self, sequencing_run_name: str, path: Optional[str] = None):
+        """ Returns whether the SequencingRun has a VCF associated with it. If path is set, VCF must match that path
+            otherwise - any VCF present will retur True """
+        data = self._get(f"seqauto/api/v1/sequencing_run/{sequencing_run_name}/")
+        found_vcf = False
+        for vcf in data["vcf_set"]:
+            if path is None or path in vcf["path"]:
+                found_vcf = True
+                break
+        return found_vcf
+
+    ##################################
+    ## Uploaded file annotation flow
+
+    @staticmethod
+    def _upload_key_segment(uploaded_file_id: Optional[int], sha256: Optional[str]) -> str:
+        """ URL segment identifying an uploaded file - by uploaded_file_id (preferred) or its SHA-256 hash. """
+        if uploaded_file_id is not None:
+            return str(uploaded_file_id)
+        if sha256:
+            return f"sha256/{sha256}"
+        raise ValueError("Must provide one of 'uploaded_file_id' or 'sha256'")
+
+    def poll_upload_status(self, uploaded_file_id: Optional[int] = None, sha256: Optional[str] = None) -> dict:
+        """ Single GET of an uploaded file's import/annotation status.
+
+            Keyed by uploaded_file_id (returned from upload_file) or the SHA-256 of the uploaded file.
+            See wait_for_annotation to block until annotation is complete. """
+        segment = self._upload_key_segment(uploaded_file_id, sha256)
+        return self._get(f"upload/api/v1/upload_status/{segment}")
+
+    def wait_for_annotation(self, uploaded_file_id: Optional[int] = None, sha256: Optional[str] = None,
+                            timeout: float = 3600, poll_interval: float = 10, sleep: Callable = time.sleep,
+                            max_transient_errors: int = 5) -> dict:
+        """ Poll poll_upload_status until 'annotation_complete' is true, then return the final status dict.
+
+            Raises AnnotationError if the server reports an 'error', or TimeoutError if 'timeout' seconds elapse.
+            'sleep' is injectable so tests can avoid real delays.
+
+            Transient server hiccups (5xx / connection / timeout - e.g. a brief 500 right after upload while the
+            server is still creating the upload record) are tolerated: up to 'max_transient_errors' *consecutive*
+            failures are retried before giving up. A 4xx response is treated as a real error and raised immediately.
+            The success counter resets whenever a poll succeeds. """
+        deadline = time.monotonic() + timeout
+        transient_errors = 0
+        while True:
+            try:
+                status = self.poll_upload_status(uploaded_file_id=uploaded_file_id, sha256=sha256)
+                transient_errors = 0
+            except (requests.HTTPError, requests.ConnectionError, requests.Timeout) as e:
+                status_code = getattr(getattr(e, "response", None), "status_code", None)
+                if status_code is not None and status_code < 500:
+                    raise  # 4xx is a real client error, not a transient blip
+                transient_errors += 1
+                if transient_errors > max_transient_errors:
+                    raise
+                self.logger.warning("Transient error polling upload status (%s/%s), retrying: %s",
+                                    transient_errors, max_transient_errors, e)
+                if time.monotonic() >= deadline:
+                    raise TimeoutError(f"Annotation did not complete within {timeout}s (last error: {e})")
+                sleep(poll_interval)
+                continue
+            if error := status.get("error"):
+                raise AnnotationError(error, status)
+            if status.get("annotation_complete"):
+                return status
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"Annotation did not complete within {timeout}s (status={status})")
+            sleep(poll_interval)
+
+    @staticmethod
+    def _attachment_filename(response, export_type: str) -> str:
+        content_disposition = response.headers.get("Content-Disposition", "")
+        if m := re.search(r'filename\*?=(?:UTF-8\'\')?"?([^";]+)"?', content_disposition):
+            return urllib.parse.unquote(m.group(1))
+        ext = ".vcf.gz" if export_type == "vcf" else ".csv.zip"
+        return f"download{ext}"
+
+    def download_annotated(self, uploaded_file_id: Optional[int] = None, sha256: Optional[str] = None,
+                           export_type: str = "vcf", dest_path: Optional[Union[str, Path]] = None,
+                           timeout: float = 3600, poll_interval: float = 10,
+                           sleep: Callable = time.sleep) -> Path:
+        """ Download the cohort-level annotated export of an uploaded VCF, saving it to disk.
+
+            export_type is 'vcf' (gzipped *.vcf.gz) or 'csv' (zipped *.csv.zip). The export covers all samples
+            in the uploaded VCF (single-sample VCFs included).
+
+            The endpoint returns 202 while the file is still being generated - this polls until it is ready (200),
+            then streams the attachment to dest_path. If dest_path is None the server's attachment filename is used
+            in the current directory; if it is an existing directory the attachment filename is placed inside it;
+            otherwise it is treated as the full destination path. Returns the Path written.
+
+            Raises TimeoutError if the file isn't ready within 'timeout' seconds. """
+        if export_type not in ("vcf", "csv"):
+            raise ValueError(f"export_type must be 'vcf' or 'csv', got {export_type!r}")
+        segment = self._upload_key_segment(uploaded_file_id, sha256)
+        url = self._get_url(f"upload/api/v1/download/{segment}/{export_type}")
+        deadline = time.monotonic() + timeout
+        while True:
+            response = requests.get(url, headers=self.headers, stream=True)
+            if response.status_code == 202:
+                if self.log_response:
+                    self.logger.info("Download of '%s' still generating: %s", url, self._safe_json(response))
+                if time.monotonic() >= deadline:
+                    raise TimeoutError(f"Download not ready within {timeout}s (url={url})")
+                sleep(poll_interval)
+                continue
+            if not response.ok:
+                # Raises with logging (JSON 'error' message from the server)
+                self._handle_json_response(response, f"download {export_type} for {segment}")
+            dest = self._resolve_download_dest(dest_path, response, export_type)
+            with open(dest, "wb") as f:
+                for chunk in response.iter_content(chunk_size=8192):
+                    if chunk:
+                        f.write(chunk)
+            return dest
+
+    def _resolve_download_dest(self, dest_path: Optional[Union[str, Path]], response, export_type: str) -> Path:
+        filename = self._attachment_filename(response, export_type)
+        if dest_path is None:
+            return Path(filename)
+        dest = Path(dest_path)
+        if dest.is_dir():
+            return dest / filename
+        return dest
+
+    @staticmethod
+    def _safe_json(response):
+        try:
+            return response.json()
+        except Exception:
+            return None
+
+    def annotate_vcf(self, filename: str, export_type: str = "vcf", dest_path: Optional[Union[str, Path]] = None,
+                     timeout: float = 3600, poll_interval: float = 10, sleep: Callable = time.sleep) -> Path:
+        """ Convenience one-liner: upload a VCF, wait for annotation to finish, download the annotated export.
+
+            Chains upload_file -> wait_for_annotation -> download_annotated and returns the Path written. """
+        # path is SeqAuto-only and makes ad-hoc uploads fail the import - omit it for the annotate flow
+        upload = self.upload_file(filename, path=None)
+        uploaded_file_id = upload["uploaded_file_id"]
+        self.wait_for_annotation(uploaded_file_id=uploaded_file_id,
+                                 timeout=timeout, poll_interval=poll_interval, sleep=sleep)
+        return self.download_annotated(uploaded_file_id=uploaded_file_id, export_type=export_type,
+                                       dest_path=dest_path, timeout=timeout, poll_interval=poll_interval, sleep=sleep)
+
+
+
+

variantgrid_api-1.3.1/src/variantgrid_api/cli.py

@@ -0,0 +1,137 @@
+"""Command line interface for the VariantGrid API client.
+
+Currently provides `vg_api annotate_vcf <file>`: a stateless upload/download helper. Because the server
+dedups uploads on the file's SHA-256, the VCF file itself is the receipt - the first call uploads it, and
+running the same command again downloads the annotated result (or reports that it isn't ready yet). No local
+state (upload ids, pending.json, ...) is kept, so you can poll from any machine that has the VCF.
+"""
+import argparse
+import hashlib
+import logging
+import os
+import sys
+
+import requests
+
+from variantgrid_api.api_client import VariantGridAPI, AnnotationError
+
+DEFAULT_SERVER = "https://variantgrid.com"
+
+EXIT_OK = 0        # annotated file downloaded
+EXIT_ERROR = 1     # bad input / auth / server or annotation error
+EXIT_PENDING = 3   # uploaded just now, or still annotating - come back later
+
+
+def _sha256(path):
+    """Content hash the server dedups on - identical to `sha256sum <file>`."""
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _build_api(args):
+    token = args.token or os.environ.get("VARIANTGRID_API_TOKEN")
+    if not token:
+        raise SystemExit("No API token - pass --token or set VARIANTGRID_API_TOKEN")
+    server = args.server or os.environ.get("VARIANTGRID_API_SERVER") or DEFAULT_SERVER
+    # Own logger so we can silence the expected 404 when a file hasn't been uploaded yet.
+    logger = logging.getLogger("vg_api.cli")
+    return VariantGridAPI(server=server, api_token=token, logger=logger), logger
+
+
+def _is_not_found(exc):
+    resp = getattr(exc, "response", None)
+    return resp is not None and resp.status_code == 404
+
+
+def annotate_vcf_cmd(args):
+    if not os.path.isfile(args.vcf):
+        print(f"No such file: {args.vcf}", file=sys.stderr)
+        return EXIT_ERROR
+
+    api, logger = _build_api(args)
+    name = os.path.basename(args.vcf)
+
+    if args.wait:
+        # Blocking one-shot: upload, wait (can take hours), download.
+        path = api.annotate_vcf(args.vcf, export_type=args.export_type, dest_path=args.dest,
+                                poll_interval=args.poll_interval)
+        print(f"Annotated {args.export_type} written to {path}")
+        return EXIT_OK
+
+    sha256 = _sha256(args.vcf)
+
+    # Probe by content hash. A 404 means we've never uploaded this file - so upload it now.
+    prev_level = logger.level
+    logger.setLevel(logging.CRITICAL)  # the probe 404 is expected; don't scare the user
+    try:
+        status = api.poll_upload_status(sha256=sha256)
+    except requests.HTTPError as e:
+        if _is_not_found(e):
+            up = api.upload_file(args.vcf, path=None)
+            print(f"Uploaded {name} (id={up['uploaded_file_id']}). "
+                  f"Annotating - run the same command again later to download.")
+            return EXIT_PENDING
+        raise
+    finally:
+        logger.setLevel(prev_level)
+
+    if err := status.get("error"):
+        print(f"{name}: annotation error - {err}", file=sys.stderr)
+        return EXIT_ERROR
+    if status.get("annotation_complete"):
+        path = api.download_annotated(sha256=sha256, export_type=args.export_type, dest_path=args.dest)
+        print(f"Annotated {args.export_type} written to {path}")
+        return EXIT_OK
+
+    progress = status.get("progress_percent")
+    suffix = f" (progress {progress}%)" if progress is not None else ""
+    print(f"{name}: not ready yet{suffix} - run the same command again later.")
+    return EXIT_PENDING
+
+
+def build_parser():
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--server",
+                        help="VariantGrid server URL (default: $VARIANTGRID_API_SERVER or "
+                             f"{DEFAULT_SERVER})")
+    common.add_argument("--token", help="API token (default: $VARIANTGRID_API_TOKEN)")
+
+    parser = argparse.ArgumentParser(prog="vg_api", description="VariantGrid API command line tool")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("annotate_vcf", parents=[common],
+                       help="Upload a VCF for annotation; run again to download it once ready",
+                       description="Upload a VCF for annotation. Because uploads are keyed on the file's "
+                                   "SHA-256, running the same command again downloads the annotated result "
+                                   "when ready, or reports that it isn't ready yet - no local state is kept.")
+    p.add_argument("vcf", help="Path to the VCF (.vcf / .vcf.gz) to annotate")
+    p.add_argument("--export-type", choices=("vcf", "csv"), default="vcf",
+                   help="Download format (default: vcf)")
+    p.add_argument("-o", "--dest", default=".",
+                   help="Destination directory or file for the download (default: current directory)")
+    p.add_argument("--wait", action="store_true",
+                   help="Block until annotation finishes, then download (can take hours)")
+    p.add_argument("--poll-interval", type=float, default=10,
+                   help="Seconds between status polls when using --wait (default: 10)")
+    p.set_defaults(func=annotate_vcf_cmd)
+    return parser
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except AnnotationError as e:
+        print(f"Annotation error: {e}", file=sys.stderr)
+        return EXIT_ERROR
+    except requests.HTTPError as e:
+        print(f"HTTP error: {e}", file=sys.stderr)
+        return EXIT_ERROR
+
+
+if __name__ == "__main__":
+    sys.exit(main())