Introduction

The varvis-connector package

The varvis-connector package provides a Python client and command-line interface (CLI) for the varvis® API. Retrieve genomic data including SNV annotations, CNV target results, and CNV segments, process large SNV responses with low memory use, and download analysis files safely in parallel. The package handles authentication and coordinated session recovery for concurrent requests, with configurable timeouts, retries, and environment-based configuration.

Intended Use

This software is provided solely for research, educational, development, interoperability, and bioinformatics workflow automation purposes.

This project is NOT intended by the authors to be used for:

• clinical diagnosis,

• in vitro diagnostic procedures,

• patient stratification,

• treatment selection,

• medical decision-making,

• or any other medical purpose as defined under applicable medical device or in vitro diagnostic regulations, including but not limited to Regulation (EU) 2017/746 (IVDR).

The software is not a certified in vitro diagnostic medical device and has not undergone clinical performance studies, regulatory assessment, or conformity assessment procedures required for software intended for in vitro diagnostic use.

Users are solely responsible for ensuring compliance with all applicable laws, regulations, institutional policies, and validation requirements in their jurisdiction and use case.

Features

• Typed Python client and command-line interface for genomic data retrieval, person records, and virtual panels

• Low-memory SNV iteration with optional temporary-file caching; CLI JSONL streaming uses caching to avoid holding full responses in RAM (see Python API and get-snv-annotations)

• Gene and coordinate filters that support scalar and array-valued SNV annotations

• Parallel HTTPS downloads with connection pooling, configurable retries with randomized delays, and separate download retry settings

• Atomic file downloads that preserve existing files on failure, clean up partial transfers, and reject unsafe filenames and conflicting destination paths (see download-files)

• Thread-safe authentication and coordinated re-login after session invalidation, with bounded shared recovery attempts

• Separate connection and read timeouts, environment-based configuration, and comprehensive error handling

• Memory-efficient CLI JSON serialization, with output files opened only when results are ready to be written (see Command output options)

• Support for Python 3.11 through 3.15

Currently covered varvis® API endpoints

The following API endpoints are currently covered both by the CLI and the Python package:

varvis® API endpoint	varvis® docs title	CLI command varvis_connector ...	VarvisClient method
GET /api/person/{personLimsId}/id	Get Person Id	get-internal-person-id	VarvisClient.get_internal_person_id
GET /api/analysis/{analysisId}/annotations	Get Variant Annotations	get-snv-annotations	VarvisClient.get_snv_annotations
GET /api/results/{personLimsId}/cnv	Get Cnv Results	get-cnv-target-results	VarvisClient.get_cnv_target_results
GET /pending-cnv	Get Pending Cnvs	get-pending-cnv-segments	VarvisClient.get_pending_cnv_segments
GET /api/qualitycontrol/metrics/case/{personId}	Get Case Metrics	get-qc-case-metrics	VarvisClient.get_qc_case_metrics
GET /api/{personId}/coverage	Api Coverage Task Data	get-coverage-data	VarvisClient.get_coverage_data
GET /api/analyses	Find Analyses	get-analyses	VarvisClient.get_analyses
GET /person/{personLimsId}/analyses	Api Get Analyses Linked With Person	get-person-analyses	VarvisClient.get_person_analyses
GET /api/cases/{personId}/report	Get Case Report	get-case-report	VarvisClient.get_case_report
GET /api/person/{personLimsId}	Get Person Including Clinical Information	get-person	VarvisClient.get_person
PUT /api/person	Api Create Or Update Person	create-or-update-person	VarvisClient.create_or_update_person
GET /analysis-list/find-by-customer-provided-input-file-name	Find By Customer Provided Input File Name	find-analyses-by-filename	VarvisClient.find_analyses_by_filename
GET /virtual-panel/{id}	Get Virtual Panel Details	get-virtual-panel	VarvisClient.get_virtual_panel
POST /api/virtual-panel	Create Or Update Virtual Panel	create-virtual-panel / update-virtual-panel	VarvisClient.create_or_update_virtual_panel
GET /virtual-panels	Get Virtual Panel Summaries	get-virtual-panel-summaries	VarvisClient.get_virtual_panel_summaries
GET /virtual-panel-genes	Get All Genes	get-all-genes	VarvisClient.get_all_genes
GET /api/analysis/{analysisId}/get-file-download-links	Get File Download Links (and download the files)	get-file-download-links / download-files	VarvisClient.get_file_download_links / VarvisClient.download_files

In addition to that, it’s possible to send arbitrary authenticated requests to the API using the CLI request command or the VarvisClient.request method, which is especially useful for undocumented endpoints.

License

This project is licensed under the GNU General Public License v3.0 (GPLv3). See the LICENSE file for details.

Disclaimer

The varvis® logo is a registered trademark of Limbus Medical Technologies GmbH and is used in this project with permission. This project is independent and is not affiliated with, endorsed by, or officially supported by Limbus Medical Technologies GmbH.