feat: add AnyVar client implementations (#21)

Author: jsstevenson

.github/workflows/python-package.yaml

@@ -8,6 +8,45 @@ permissions:
   contents: read
 
 jobs:
+  test:
+    name: test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_PASSWORD: postgres
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: 'true'
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "${{ matrix.python-version }}"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra test
+
+      - name: Run tests
+        run: uv run pytest
+        env:
+          ANYVLM_ANYVAR_TEST_STORAGE_URI: postgresql://postgres:postgres@localhost:5432/postgres
   lint:
     name: lint
     runs-on: ubuntu-latest

pyproject.toml

@@ -17,7 +17,7 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 dependencies = [
-    "ga4gh.va_spec",
+    "ga4gh.va_spec~=0.4.2",
     "biocommons.anyvar@git+https://github.com/biocommons/anyvar.git@storage-refactor-epic",
     "fastapi>=0.95.0",
     "python-multipart",  # required for fastapi file uploads
@@ -26,6 +26,7 @@ dependencies = [
     "anyio",
     "python-dotenv",
     "pydantic-settings",
+    "requests",
 ]
 dynamic = ["version"]
 
@@ -36,12 +37,14 @@ test = [
     "httpx",
     "jsonschema",
     "pyyaml",
+    "pytest-recording",
 ]
 dev = [
     "ruff==0.12.8",
     "pre-commit>=4.2.0",
     "ipykernel",
     "fastapi[standard]",
+    "seqrepo-rest-service",  # for generating SeqRepo-based tests fixtures
 ]
 
 [project.urls]

src/anyvlm/anyvar/base_client.py

@@ -2,40 +2,43 @@
 
 import abc
 
-from anyvar.utils.types import VrsObject
+from anyvar.utils.types import VrsVariation
 
-from anyvlm.schemas.domain import AlleleFrequencyAnnotation
+
+class AnyVarClientError(Exception):
+    """Generic client-related exception."""
+
+
+class UnidentifiedObjectError(AnyVarClientError):
+    """Raise if input object lacks an ID property"""
 
 
 class BaseAnyVarClient(abc.ABC):
     """Interface elements for an AnyVar client"""
 
     @abc.abstractmethod
-    def put_objects(self, objects: list[VrsObject]) -> None:
+    def put_objects(self, objects: list[VrsVariation]) -> None:
         """Register objects with AnyVar
 
-        :param objects: variation objects to register
-        """
+        All input objects must have a populated ID field. A validation check for this is
+        performed before any variants are registered.
 
-    @abc.abstractmethod
-    def put_af_annotation(self, key: str, af: AlleleFrequencyAnnotation) -> None:
-        """Add an allele frequency annotation to a variation
-
-
-        :param key: VRS ID for variation being annotated
-        :param af: frequency data for for annotation
+        :param objects: variation objects to register
+        :raise AnyVarClientError: for errors relating to specifics of client interface
+        :raise UnidentifiedObjectError: if *any* provided object lacks a VRS ID
         """
 
     @abc.abstractmethod
     def search_by_interval(
         self, accession: str, start: int, end: int
-    ) -> list[VrsObject]:
+    ) -> list[VrsVariation]:
         """Get all variation IDs located within the specified range
 
         :param accession: sequence accession
         :param start: start position for genomic region
         :param end: end position for genomic region
         :return: list of matching variant objects
+        :raise AnyVarClientError: if connection is unsuccessful during search query
         """
 
     @abc.abstractmethod

src/anyvlm/anyvar/http_client.py

@@ -0,0 +1,91 @@
+"""Provide abstraction for a VLM-to-AnyVar connection."""
+
+import logging
+
+import requests
+from anyvar.utils.types import VrsVariation
+from ga4gh.vrs import models
+
+from anyvlm.anyvar.base_client import (
+    AnyVarClientError,
+    BaseAnyVarClient,
+    UnidentifiedObjectError,
+)
+
+_logger = logging.getLogger(__name__)
+
+
+class HttpAnyVarClient(BaseAnyVarClient):
+    """AnyVar HTTP-based client"""
+
+    def __init__(
+        self, hostname: str = "http://localhost:8000", request_timeout: int = 30
+    ) -> None:
+        """Initialize client instance
+
+        :param hostname: service API root
+        :param request_timeout: timeout value, in seconds, for HTTP requests
+        """
+        self.hostname = hostname
+        self.request_timeout = request_timeout
+
+    def put_objects(self, objects: list[VrsVariation]) -> None:
+        """Register objects with AnyVar
+
+        All input objects must have a populated ID field. A validation check for this is
+        performed before any variants are registered.
+
+        :param objects: variation objects to register
+        :return: completed VRS objects
+        :raise AnyVarClientError: if connection is unsuccessful during registration request
+        :raise UnidentifiedObjectError: if *any* provided object lacks a VRS ID
+        """
+        objects_to_submit = []
+        for vrs_object in objects:
+            if not vrs_object.id:
+                _logger.error("Provided variant %s has no VRS ID", vrs_object)
+                raise UnidentifiedObjectError
+            objects_to_submit.append(
+                vrs_object.model_dump(exclude_none=True, mode="json")
+            )
+        for vrs_object in objects_to_submit:
+            response = requests.put(
+                f"{self.hostname}/vrs_variation",
+                json=vrs_object,
+                timeout=self.request_timeout,
+            )
+            try:
+                response.raise_for_status()
+            except requests.HTTPError as e:
+                raise AnyVarClientError from e
+
+    def search_by_interval(
+        self, accession: str, start: int, end: int
+    ) -> list[VrsVariation]:
+        """Get all variation IDs located within the specified range
+
+        :param accession: sequence accession
+        :param start: start position for genomic region
+        :param end: end position for genomic region
+        :return: list of matching variant objects
+        :raise AnyVarClientError: if connection is unsuccessful during search query
+        """
+        response = requests.get(
+            f"{self.hostname}/search?accession={accession}&start={start}&end={end}",
+            timeout=self.request_timeout,
+        )
+        try:
+            response.raise_for_status()
+        except requests.HTTPError as e:
+            if response.json() == {
+                "detail": "Unable to dereference provided accession ID"
+            }:
+                return []
+            raise AnyVarClientError from e
+        return [models.Allele(**v) for v in response.json()["variations"]]
+
+    def close(self) -> None:
+        """Clean up AnyVar connection.
+
+        This is a no-op for this class.
+        """

src/anyvlm/anyvar/python_client.py

@@ -0,0 +1,68 @@
+"""Implement AnyVar client interface for direct Python-based access."""
+
+import logging
+
+from anyvar import AnyVar
+from anyvar.storage.base_storage import Storage
+from anyvar.translate.translate import Translator
+from anyvar.utils.types import VrsVariation
+
+from anyvlm.anyvar.base_client import BaseAnyVarClient, UnidentifiedObjectError
+
+_logger = logging.getLogger(__name__)
+
+
+class PythonAnyVarClient(BaseAnyVarClient):
+    """A Python-based AnyVar client."""
+
+    def __init__(self, translator: Translator, storage: Storage) -> None:
+        """Initialize directly-connected AnyVar client
+
+        :param translator: AnyVar translator instance
+        :param storage: AnyVar storage instance
+        """
+        self.av = AnyVar(translator, storage)
+
+    def put_objects(self, objects: list[VrsVariation]) -> None:
+        """Register objects with AnyVar
+
+        All input objects must have a populated ID field. A validation check for this is
+        performed before any variants are registered.
+
+        :param objects: variation objects to register
+        :raise UnidentifiedObjectError: if *any* provided object lacks a VRS ID
+        """
+        for variant in objects:
+            if not variant.id:
+                _logger.error("Provided variant %s has no VRS ID", variant)
+                raise UnidentifiedObjectError
+        self.av.put_objects(objects)  # type: ignore[reportArgumentType]
+
+    def search_by_interval(
+        self, accession: str, start: int, end: int
+    ) -> list[VrsVariation]:
+        """Get all variation IDs located within the specified range
+
+        :param accession: sequence accession
+        :param start: start position for genomic region
+        :param end: end position for genomic region
+        :return: list of matching variant objects
+        """
+        try:
+            if accession.startswith("ga4gh:"):
+                ga4gh_id = accession
+            else:
+                ga4gh_id = self.av.translator.get_sequence_id(accession)
+        except KeyError:
+            return []
+
+        alleles = []
+        if ga4gh_id:
+            refget_accession = ga4gh_id.split("ga4gh:")[-1]
+            alleles = self.av.object_store.search_alleles(refget_accession, start, end)
+
+        return alleles  # type: ignore[reportReturnType]
+
+    def close(self) -> None:
+        """Clean up AnyVar instance."""
+        self.av.object_store.close()

src/anyvlm/config.py

@@ -22,6 +22,7 @@ class Settings(BaseSettings):
     )
 
     env: ServiceEnvironment = ServiceEnvironment.LOCAL
+    anyvar_uri: str = "http://localhost:8000"
 
 
 @cache

src/anyvlm/main.py

@@ -1,13 +1,17 @@
 """Define core FastAPI app"""
 
+import logging
 from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
 from enum import Enum
 
+from anyvar.anyvar import create_storage, create_translator
 from fastapi import FastAPI
 
 from anyvlm import __version__
 from anyvlm.anyvar.base_client import BaseAnyVarClient
+from anyvlm.anyvar.http_client import HttpAnyVarClient
+from anyvlm.anyvar.python_client import PythonAnyVarClient
 from anyvlm.config import get_config
 from anyvlm.schemas.common import (
     SERVICE_DESCRIPTION,
@@ -16,16 +20,33 @@
     ServiceType,
 )
 
+_logger = logging.getLogger(__name__)
+
 
 def create_anyvar_client(
-    connection_string: str = "http://localhost:8000",
+    connection_string: str | None = None,
 ) -> BaseAnyVarClient:
     """Construct new AnyVar client instance
 
+    If given a string for connecting to an AnyVar instance via HTTP requests, then
+    create an HTTP-based client. Otherwise, try to use AnyVar resource factory functions
+    for standing up a Python-based client. In the latter case, see the AnyVar documentation
+    for configuration info (i.e. environment variables)
+
     :param connection_string: description of connection param
     :return: client instance
     """
-    raise NotImplementedError
+    if not connection_string:
+        connection_string = get_config().anyvar_uri
+    if connection_string.startswith("http://"):
+        _logger.info(
+            "Initializing HTTP-based AnyVar client under hostname %s", connection_string
+        )
+        return HttpAnyVarClient(connection_string)
+    _logger.info("Initializing AnyVar instance directly")
+    storage = create_storage()
+    translator = create_translator()
+    return PythonAnyVarClient(translator, storage)
 
 
 @asynccontextmanager