variantgrid-api 1.3.0__tar.gz → 1.3.2__tar.gz

{variantgrid_api-1.3.0/src/variantgrid_api.egg-info → variantgrid_api-1.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: variantgrid_api
-Version: 1.3.0
+Version: 1.3.2
 Summary: A Python API client for VariantGrid
 Author-email: Dave Lawrence <davmlaw@gmail.com>
 License: MIT License
@@ -68,41 +68,25 @@ 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:
+Upload a VCF, have VariantGrid import + annotate any novel variants, then download the cohort-level annotated
+export (all samples, single-sample VCFs included). Annotation can take a while, so the quickest way in is the
+`vg_api` command line tool: the first call uploads, and running the same command again downloads the result
+once it's ready.
 
-```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}")
-```
-
-Or drive each step yourself:
+```console
+$ export VARIANTGRID_API_TOKEN=YOUR_API_TOKEN
+$ vg_api annotate_vcf input.vcf.gz -o results/
+Uploaded input.vcf.gz (id=13256).
+Annotating input.vcf.gz - run the same command again later to download.
 
-```python
-# For ad-hoc uploads pass path=None so the upload isn't treated as a SeqAuto backend-link hint
-upload = api.upload_file("input.vcf", path=None)
-uploaded_file_id = upload["uploaded_file_id"]           # or upload["sha256_hash"]
-api.wait_for_annotation(uploaded_file_id, timeout=3600, poll_interval=10)  # raises on error/timeout
-path = api.download_annotated(uploaded_file_id, export_type="csv", dest_path="/data/results/")
+$ vg_api annotate_vcf input.vcf.gz -o results/        # once it's done
+Annotated vcf written to results/input.vcf_annotated_v254_GRCh38.vcf.gz
 ```
 
-`poll_upload_status(uploaded_file_id)` returns the raw status dict (including `annotation_complete`,
-`progress_percent`, `error`, `vcf_id`, `samples`, ...) if you want to inspect progress directly. All of
-these accept `sha256=<hash>` instead of `uploaded_file_id` - the server dedups on the content hash, so it is
-stable across machines and useful if you didn't retain the id.
-
-Notes:
-
-- The `annotate_vcf` wrapper already uploads with `path=None`. Only pass a `path` to `upload_file` for SeqAuto
-  uploads that link to a registered `JointCalledVCF` / `SingleSampleVCF` (that is what `path` is for - it is
-  ignored on non-SeqAuto deployments).
-- Downloads require the target deployment to have the cohort export analysis templates configured
-  (`ANALYSIS_TEMPLATES_AUTO_COHORT_EXPORT`) - otherwise a clear error is returned.
+From Python it's `upload_file()` / `poll_upload_status()` / `download_annotated()`, or the blocking
+`annotate_vcf()` one-liner. See
+**[Annotate a VCF](https://github.com/SACGF/variantgrid_api/wiki/Annotate-a-VCF)** on the wiki for batches, the
+submit-now/download-later pattern, and all the options.
 
 ## Testing
 

variantgrid_api-1.3.2/README.md

@@ -0,0 +1,54 @@
+# variantgrid_api
+
+[![PyPi version](https://img.shields.io/pypi/v/variantgrid_api.svg)](https://pypi.org/project/variantgrid_api/) [![Python versions](https://img.shields.io/pypi/pyversions/variantgrid_api.svg)](https://pypi.org/project/variantgrid_api/)
+
+Python API client for [VariantGrid](https://github.com/SACGF/variantgrid) Open source Variant database and analysis platform
+
+See [changelog](https://github.com/SACGF/variantgrid_api/blob/main/CHANGELOG.md)
+
+## Install
+
+```
+python3 -m pip install variantgrid_api
+```
+
+## Example
+
+```
+from variantgrid_api.api_client import VariantGridAPI
+from variantgrid_api.data_models import EnrichmentKit
+
+api = VariantGridAPI(server="https://variantgrid.com", api_token="YOUR_API_TOKEN")
+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, have VariantGrid import + annotate any novel variants, then download the cohort-level annotated
+export (all samples, single-sample VCFs included). Annotation can take a while, so the quickest way in is the
+`vg_api` command line tool: the first call uploads, and running the same command again downloads the result
+once it's ready.
+
+```console
+$ export VARIANTGRID_API_TOKEN=YOUR_API_TOKEN
+$ vg_api annotate_vcf input.vcf.gz -o results/
+Uploaded input.vcf.gz (id=13256).
+Annotating input.vcf.gz - run the same command again later to download.
+
+$ vg_api annotate_vcf input.vcf.gz -o results/        # once it's done
+Annotated vcf written to results/input.vcf_annotated_v254_GRCh38.vcf.gz
+```
+
+From Python it's `upload_file()` / `poll_upload_status()` / `download_annotated()`, or the blocking
+`annotate_vcf()` one-liner. See
+**[Annotate a VCF](https://github.com/SACGF/variantgrid_api/wiki/Annotate-a-VCF)** on the wiki for batches, the
+submit-now/download-later pattern, and all the options.
+
+## Testing
+
+```
+# Install required testing packages
+python3 -m pip install -e ".[test]"
+python3 -m pytest --cov=variantgrid_api
+```

{variantgrid_api-1.3.0 → variantgrid_api-1.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "variantgrid_api"
-version = "1.3.0"
+version = "1.3.2"
 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.2/src/variantgrid_api/cli.py

@@ -0,0 +1,153 @@
+"""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 _probe_status(api, logger, sha256):
+    """Poll status by content hash. Returns the status dict, or None if the server has never
+    seen this file (404) - a 404 here just means "not uploaded yet", so we silence its logging."""
+    prev_level = logger.level
+    logger.setLevel(logging.CRITICAL)
+    try:
+        return api.poll_upload_status(sha256=sha256)
+    except requests.HTTPError as e:
+        if _is_not_found(e):
+            return None
+        raise
+    finally:
+        logger.setLevel(prev_level)
+
+
+def _download(api, args, sha256):
+    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
+
+
+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)
+    sha256 = _sha256(args.vcf)
+
+    status = _probe_status(api, logger, sha256)
+    if status is None:
+        # We've never uploaded this file - do it now.
+        up = api.upload_file(args.vcf, path=None)
+        print(f"Uploaded {name} (id={up['uploaded_file_id']}).")
+
+    if args.wait:
+        # Poll the server ourselves until annotation finishes (can take hours), then download.
+        if status is None or not status.get("annotation_complete"):
+            print("Waiting for annotation to finish - this can take a while...")
+            api.wait_for_annotation(sha256=sha256, timeout=args.timeout, poll_interval=args.poll_interval)
+        return _download(api, args, sha256)
+
+    # Single-shot: report where it's at, download only if it's ready.
+    if status is None:
+        print(f"Annotating {name} - run the same command again later to download.")
+        return EXIT_PENDING
+    if err := status.get("error"):
+        print(f"{name}: annotation error - {err}", file=sys.stderr)
+        return EXIT_ERROR
+    if status.get("annotation_complete"):
+        return _download(api, args, sha256)
+
+    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="Poll until annotation finishes and download it, instead of returning immediately "
+                        "(can take hours)")
+    p.add_argument("--poll-interval", type=float, default=10,
+                   help="Seconds between status polls when using --wait (default: 10)")
+    p.add_argument("--timeout", type=float, default=86400,
+                   help="Give up after this many seconds when using --wait (default: 86400 = 24h)")
+    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())

{variantgrid_api-1.3.0 → variantgrid_api-1.3.2/src/variantgrid_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: variantgrid_api
-Version: 1.3.0
+Version: 1.3.2
 Summary: A Python API client for VariantGrid
 Author-email: Dave Lawrence <davmlaw@gmail.com>
 License: MIT License
@@ -68,41 +68,25 @@ 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:
+Upload a VCF, have VariantGrid import + annotate any novel variants, then download the cohort-level annotated
+export (all samples, single-sample VCFs included). Annotation can take a while, so the quickest way in is the
+`vg_api` command line tool: the first call uploads, and running the same command again downloads the result
+once it's ready.
 
-```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}")
-```
-
-Or drive each step yourself:
+```console
+$ export VARIANTGRID_API_TOKEN=YOUR_API_TOKEN
+$ vg_api annotate_vcf input.vcf.gz -o results/
+Uploaded input.vcf.gz (id=13256).
+Annotating input.vcf.gz - run the same command again later to download.
 
-```python
-# For ad-hoc uploads pass path=None so the upload isn't treated as a SeqAuto backend-link hint
-upload = api.upload_file("input.vcf", path=None)
-uploaded_file_id = upload["uploaded_file_id"]           # or upload["sha256_hash"]
-api.wait_for_annotation(uploaded_file_id, timeout=3600, poll_interval=10)  # raises on error/timeout
-path = api.download_annotated(uploaded_file_id, export_type="csv", dest_path="/data/results/")
+$ vg_api annotate_vcf input.vcf.gz -o results/        # once it's done
+Annotated vcf written to results/input.vcf_annotated_v254_GRCh38.vcf.gz
 ```
 
-`poll_upload_status(uploaded_file_id)` returns the raw status dict (including `annotation_complete`,
-`progress_percent`, `error`, `vcf_id`, `samples`, ...) if you want to inspect progress directly. All of
-these accept `sha256=<hash>` instead of `uploaded_file_id` - the server dedups on the content hash, so it is
-stable across machines and useful if you didn't retain the id.
-
-Notes:
-
-- The `annotate_vcf` wrapper already uploads with `path=None`. Only pass a `path` to `upload_file` for SeqAuto
-  uploads that link to a registered `JointCalledVCF` / `SingleSampleVCF` (that is what `path` is for - it is
-  ignored on non-SeqAuto deployments).
-- Downloads require the target deployment to have the cohort export analysis templates configured
-  (`ANALYSIS_TEMPLATES_AUTO_COHORT_EXPORT`) - otherwise a clear error is returned.
+From Python it's `upload_file()` / `poll_upload_status()` / `download_annotated()`, or the blocking
+`annotate_vcf()` one-liner. See
+**[Annotate a VCF](https://github.com/SACGF/variantgrid_api/wiki/Annotate-a-VCF)** on the wiki for batches, the
+submit-now/download-later pattern, and all the options.
 
 ## Testing
 

{variantgrid_api-1.3.0 → variantgrid_api-1.3.2}/src/variantgrid_api.egg-info/SOURCES.txt

@@ -2,17 +2,20 @@ LICENSE
 README.md
 pyproject.toml
 src/variantgrid_api/api_client.py
+src/variantgrid_api/cli.py
 src/variantgrid_api/data_models.py
 src/variantgrid_api/mock_variantgrid_api.py
 src/variantgrid_api.egg-info/PKG-INFO
 src/variantgrid_api.egg-info/SOURCES.txt
 src/variantgrid_api.egg-info/dependency_links.txt
+src/variantgrid_api.egg-info/entry_points.txt
 src/variantgrid_api.egg-info/requires.txt
 src/variantgrid_api.egg-info/top_level.txt
 tests/test_api_client.py
 tests/test_api_client_annotation.py
 tests/test_api_client_bulk.py
 tests/test_api_client_validation.py
+tests/test_cli.py
 tests/test_data_models.py
 tests/test_mock_variantgrid_api.py
 tests/test_sequencer_model_from_name.py

variantgrid_api-1.3.2/src/variantgrid_api.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vg_api = variantgrid_api.cli:main

variantgrid_api-1.3.2/tests/test_cli.py

@@ -0,0 +1,127 @@
+import re
+
+import pytest
+import responses
+
+from variantgrid_api import cli
+
+SERVER = "https://vg.example.org"
+
+STATUS_RE = re.compile(rf"{SERVER}/upload/api/v1/upload_status/sha256/[0-9a-f]+$")
+UPLOAD_URL = f"{SERVER}/upload/api/v1/file_upload"
+DOWNLOAD_RE = re.compile(rf"{SERVER}/upload/api/v1/download/sha256/[0-9a-f]+/(vcf|csv)$")
+
+
+@pytest.fixture
+def vcf(tmp_path):
+    p = tmp_path / "input.vcf"
+    p.write_text("##fileformat=VCFv4.2\n")
+    return str(p)
+
+
+def _argv(vcf, *extra):
+    return ["annotate_vcf", vcf, "--server", SERVER, "--token", "T", *extra]
+
+
+@responses.activate
+def test_first_call_uploads(vcf):
+    """Unknown file (status 404) -> upload it and report pending."""
+    responses.add(responses.GET, STATUS_RE, json={"detail": "not found"}, status=404)
+    responses.add(responses.POST, UPLOAD_URL, json={"uploaded_file_id": 42}, status=200)
+
+    rc = cli.main(_argv(vcf))
+
+    assert rc == cli.EXIT_PENDING
+    assert any(c.request.method == "POST" and c.request.url.startswith(UPLOAD_URL)
+               for c in responses.calls)
+    # Ad-hoc upload must omit the SeqAuto path hint
+    upload_call = next(c for c in responses.calls if c.request.url.startswith(UPLOAD_URL))
+    assert "path=" not in upload_call.request.url
+
+
+@responses.activate
+def test_second_call_downloads_when_ready(vcf, tmp_path):
+    responses.add(responses.GET, STATUS_RE, json={"annotation_complete": True, "error": None}, status=200)
+    responses.add(responses.GET, DOWNLOAD_RE, body=b"vcfdata", status=200,
+                  headers={"Content-Disposition": 'attachment; filename="out.vcf.gz"'})
+
+    rc = cli.main(_argv(vcf, "-o", str(tmp_path)))
+
+    assert rc == cli.EXIT_OK
+    assert (tmp_path / "out.vcf.gz").read_bytes() == b"vcfdata"
+    # It must NOT re-upload when the file is already known
+    assert not any(c.request.method == "POST" for c in responses.calls)
+
+
+@responses.activate
+def test_not_ready_reports_pending(vcf):
+    responses.add(responses.GET, STATUS_RE,
+                  json={"annotation_complete": False, "error": None, "progress_percent": 40}, status=200)
+
+    rc = cli.main(_argv(vcf))
+
+    assert rc == cli.EXIT_PENDING
+    assert not any(re.match(DOWNLOAD_RE, c.request.url) for c in responses.calls)
+
+
+@responses.activate
+def test_server_error_status_is_error(vcf):
+    responses.add(responses.GET, STATUS_RE,
+                  json={"annotation_complete": False, "error": "Pipeline failed"}, status=200)
+
+    rc = cli.main(_argv(vcf))
+    assert rc == cli.EXIT_ERROR
+
+
+@responses.activate
+def test_csv_export_type(vcf, tmp_path):
+    responses.add(responses.GET, STATUS_RE, json={"annotation_complete": True, "error": None}, status=200)
+    responses.add(responses.GET, DOWNLOAD_RE, body=b"zip", status=200,
+                  headers={"Content-Disposition": 'attachment; filename="out.csv.zip"'})
+
+    rc = cli.main(_argv(vcf, "--export-type", "csv", "-o", str(tmp_path)))
+
+    assert rc == cli.EXIT_OK
+    assert (tmp_path / "out.csv.zip").read_bytes() == b"zip"
+    download_call = next(c for c in responses.calls if re.match(DOWNLOAD_RE, c.request.url))
+    assert download_call.request.url.endswith("/csv")
+
+
+@responses.activate
+def test_wait_uploads_polls_then_downloads(vcf, tmp_path):
+    """--wait on a new file: upload, poll until complete, then download - no external loop."""
+    responses.add(responses.GET, STATUS_RE, json={"detail": "not found"}, status=404)  # probe
+    responses.add(responses.POST, UPLOAD_URL, json={"uploaded_file_id": 7}, status=200)
+    responses.add(responses.GET, STATUS_RE, json={"annotation_complete": False, "error": None}, status=200)
+    responses.add(responses.GET, STATUS_RE, json={"annotation_complete": True, "error": None}, status=200)
+    responses.add(responses.GET, DOWNLOAD_RE, body=b"data", status=200,
+                  headers={"Content-Disposition": 'attachment; filename="out.vcf.gz"'})
+
+    rc = cli.main(_argv(vcf, "--wait", "-o", str(tmp_path), "--poll-interval", "0"))
+
+    assert rc == cli.EXIT_OK
+    assert (tmp_path / "out.vcf.gz").read_bytes() == b"data"
+
+
+@responses.activate
+def test_wait_downloads_without_reupload_when_already_known(vcf, tmp_path):
+    """--wait on an already-uploaded, already-complete file must not re-upload."""
+    responses.add(responses.GET, STATUS_RE, json={"annotation_complete": True, "error": None}, status=200)
+    responses.add(responses.GET, DOWNLOAD_RE, body=b"data", status=200,
+                  headers={"Content-Disposition": 'attachment; filename="out.vcf.gz"'})
+
+    rc = cli.main(_argv(vcf, "--wait", "-o", str(tmp_path), "--poll-interval", "0"))
+
+    assert rc == cli.EXIT_OK
+    assert not any(c.request.method == "POST" for c in responses.calls)
+
+
+def test_missing_file_is_error(tmp_path):
+    rc = cli.main(_argv(str(tmp_path / "nope.vcf")))
+    assert rc == cli.EXIT_ERROR
+
+
+def test_missing_token_raises(vcf, monkeypatch):
+    monkeypatch.delenv("VARIANTGRID_API_TOKEN", raising=False)
+    with pytest.raises(SystemExit):
+        cli.main(["annotate_vcf", vcf, "--server", SERVER])

variantgrid_api-1.3.0/README.md

@@ -1,70 +0,0 @@
-# variantgrid_api
-
-[![PyPi version](https://img.shields.io/pypi/v/variantgrid_api.svg)](https://pypi.org/project/variantgrid_api/) [![Python versions](https://img.shields.io/pypi/pyversions/variantgrid_api.svg)](https://pypi.org/project/variantgrid_api/)
-
-Python API client for [VariantGrid](https://github.com/SACGF/variantgrid) Open source Variant database and analysis platform
-
-See [changelog](https://github.com/SACGF/variantgrid_api/blob/main/CHANGELOG.md)
-
-## Install
-
-```
-python3 -m pip install variantgrid_api
-```
-
-## Example
-
-```
-from variantgrid_api.api_client import VariantGridAPI
-from variantgrid_api.data_models import EnrichmentKit
-
-api = VariantGridAPI(server="https://variantgrid.com", api_token="YOUR_API_TOKEN")
-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}")
-```
-
-Or drive each step yourself:
-
-```python
-# For ad-hoc uploads pass path=None so the upload isn't treated as a SeqAuto backend-link hint
-upload = api.upload_file("input.vcf", path=None)
-uploaded_file_id = upload["uploaded_file_id"]           # or upload["sha256_hash"]
-api.wait_for_annotation(uploaded_file_id, timeout=3600, poll_interval=10)  # raises on error/timeout
-path = api.download_annotated(uploaded_file_id, export_type="csv", dest_path="/data/results/")
-```
-
-`poll_upload_status(uploaded_file_id)` returns the raw status dict (including `annotation_complete`,
-`progress_percent`, `error`, `vcf_id`, `samples`, ...) if you want to inspect progress directly. All of
-these accept `sha256=<hash>` instead of `uploaded_file_id` - the server dedups on the content hash, so it is
-stable across machines and useful if you didn't retain the id.
-
-Notes:
-
-- The `annotate_vcf` wrapper already uploads with `path=None`. Only pass a `path` to `upload_file` for SeqAuto
-  uploads that link to a registered `JointCalledVCF` / `SingleSampleVCF` (that is what `path` is for - it is
-  ignored on non-SeqAuto deployments).
-- Downloads require the target deployment to have the cohort export analysis templates configured
-  (`ANALYSIS_TEMPLATES_AUTO_COHORT_EXPORT`) - otherwise a clear error is returned.
-
-## Testing
-
-```
-# Install required testing packages
-python3 -m pip install -e ".[test]"
-python3 -m pytest --cov=variantgrid_api
-```