allelix 2.0.1__tar.gz → 2.0.2__tar.gz

{allelix-2.0.1 → allelix-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: allelix
-Version: 2.0.1
+Version: 2.0.2
 Summary: Open-source genotype analysis toolkit. Format-agnostic ingestion, database-agnostic annotation, offline-first.
 Author: Allelix
 Maintainer-email: dial481 <dial481@users.noreply.github.com>
@@ -161,6 +161,18 @@ This is not a disclaimer afterthought. It is a design constraint that affects mo
 - Reference databases are downloaded via `allelix db update` and cached locally.
 - Analysis runs offline against local database caches. A brief freshness check runs before analysis by default (skipped with `--no-update`).
 
+### Output files contain real annotations of your genome
+
+The JSON / HTML / terminal output of `allelix analyze` and its
+focused subcommands contains real annotations against your specific
+variants — drug-response calls, carrier-status flags, hereditary-
+disease findings. Wherever you write them via `--output <path>`,
+that's where they sit until you delete them. Allelix doesn't
+auto-clean and won't warn you when you write to `/tmp/` or any
+other shared location. Treat the files as personal data: read them,
+move them somewhere you control, or delete when you're done. A
+data-lifecycle subcommand is planned for v2.1.
+
 ## Configuration
 
 Allelix stores persistent configuration in `config.toml` (in the data directory, default `~/.local/share/allelix/`). A default config is created on first run.

{allelix-2.0.1 → allelix-2.0.2}/README.md

@@ -124,6 +124,18 @@ This is not a disclaimer afterthought. It is a design constraint that affects mo
 - Reference databases are downloaded via `allelix db update` and cached locally.
 - Analysis runs offline against local database caches. A brief freshness check runs before analysis by default (skipped with `--no-update`).
 
+### Output files contain real annotations of your genome
+
+The JSON / HTML / terminal output of `allelix analyze` and its
+focused subcommands contains real annotations against your specific
+variants — drug-response calls, carrier-status flags, hereditary-
+disease findings. Wherever you write them via `--output <path>`,
+that's where they sit until you delete them. Allelix doesn't
+auto-clean and won't warn you when you write to `/tmp/` or any
+other shared location. Treat the files as personal data: read them,
+move them somewhere you control, or delete when you're done. A
+data-lifecycle subcommand is planned for v2.1.
+
 ## Configuration
 
 Allelix stores persistent configuration in `config.toml` (in the data directory, default `~/.local/share/allelix/`). A default config is created on first run.

allelix-2.0.2/allelix/__init__.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 Allelix
+"""Allelix: open-source genotype analysis toolkit."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+def _read_pyproject_version() -> str | None:
+    """Read the package version from ``pyproject.toml``.
+
+    GH #34: fall back to ``pyproject.toml`` when run from a bare source
+    checkout (no editable install, no installed package metadata). Keeps
+    ``--version`` and the outbound HTTP User-Agent reporting the real
+    version string instead of the ``0.0.0+local`` sentinel that
+    misidentifies our traffic to NCBI / EBI / HuggingFace.
+
+    Returns ``None`` on any failure — the caller falls back to the
+    sentinel rather than crashing import.
+    """
+    import tomllib
+    from pathlib import Path
+
+    pyproject = Path(__file__).resolve().parent.parent / "pyproject.toml"
+    try:
+        with pyproject.open("rb") as fh:
+            data = tomllib.load(fh)
+    except (OSError, tomllib.TOMLDecodeError):
+        return None
+    project = data.get("project") or {}
+    v = project.get("version")
+    return v if isinstance(v, str) and v else None
+
+
+try:
+    __version__ = version("allelix")
+except PackageNotFoundError:
+    # Source checkout without an editable install. Try pyproject.toml
+    # before falling back to the sentinel.
+    __version__ = _read_pyproject_version() or "0.0.0+local"

{allelix-2.0.1 → allelix-2.0.2}/allelix/annotators/base.py

@@ -142,7 +142,30 @@ class Annotator(ABC):
         self.data_dir = data_dir
 
     def __del__(self) -> None:
-        """Release resources on GC to prevent ResourceWarning."""
+        """Safety-net resource release on GC. Deliberately retained.
+
+        GH #36 (audit second pass) flagged ``__del__`` as a Python
+        antipattern — GC timing is nondeterministic and raised exceptions
+        are silently swallowed. The correct usage pattern is the
+        ``__enter__`` / ``__exit__`` context manager pair below, wired
+        through ``contextlib.ExitStack`` in ``reports/_pipeline.py``.
+
+        However: removing ``__del__`` exposes residual SQLite connection
+        leaks in code paths that construct an annotator outside a
+        context manager. ``ResourceWarning`` is elevated to error by
+        ``pytest`` config, so leaks fail the suite as
+        ``PytestUnraisableExceptionWarning`` — caught in the v2.0.2
+        ship gate when ``__del__`` was first removed. Until every call
+        site is verified to use ``with`` / ``ExitStack`` / explicit
+        ``close()``, this safety net stays. v2.1 task: audit and
+        remove.
+
+        ``contextlib.suppress(Exception)`` is deliberate — ``__del__``
+        must never raise. The GC timing and shutdown-ordering edges
+        are explicitly silenced; this is exactly the
+        "if you must keep ``__del__``, make absolutely sure it can
+        never raise" mitigation the audit recommended.
+        """
         with contextlib.suppress(Exception):
             self.close()
 

{allelix-2.0.1 → allelix-2.0.2}/allelix/cli/_helpers.py

@@ -336,6 +336,12 @@ def _emit_build_diagnostics(result: object) -> None:
         source = "detected"
     elif diag.header_build:
         source = "header (no position confirmation)"
+    elif diag.chr_prefix_inferred:
+        # GH #38: chr-prefixed contig names ("chr1", "chrX", ...) reliably
+        # indicate GRCh38 in modern caller output. We DID detect a build;
+        # the banner and the warning should say so instead of reading as
+        # a blind default.
+        source = "inferred from chr-prefixed contig names"
     else:
         source = "fallback (no known SNPs matched)"
     console.print(
@@ -349,15 +355,26 @@ def _emit_build_diagnostics(result: object) -> None:
             f"This is a real-world data-quality issue — your provider may have "
             f"mislabeled the build (see ADR-0021).[/yellow]"
         )
+    elif diag.chr_prefix_inferred:
+        # GH #38: positive, accurate message — the inference path
+        # actually fired. Still recommend `--build` for users who
+        # want to lock in the answer; chr-prefix is a strong signal
+        # but UCSC hg19 also uses `chr` prefixes, so the heuristic
+        # isn't guaranteed against a hg19-converted file.
+        console.print(
+            f"[dim]Inferred {diag.effective_build} from chr-prefixed contig "
+            f"names (GRCh38 convention). Pass --build grch37 if this file is "
+            f"UCSC hg19 with chr-prefixed contigs instead.[/dim]"
+        )
     elif not diag.override and diag.detected_build is None and diag.header_build is None:
         # Common shape: VCF from a variant caller where the ID column is `.`
-        # and the header has no ##contig assembly tag. The detector had no
-        # rsID signal AND no header signal — both auto-detect paths failed.
+        # and the header has no ##contig assembly tag, AND no chr-prefix
+        # signal was observed. All three auto-detect paths failed.
         # Loudly recommend an explicit --build because picking the wrong one
         # silently means every annotation lookup uses wrong coordinates.
         console.print(
             f"[yellow]Could not auto-detect genome build (no rsIDs in input, "
-            f"no ##contig assembly tag in header). Defaulted to "
+            f"no ##contig assembly tag, no chr-prefixed contigs). Defaulted to "
             f"{diag.effective_build}. If the file is the other build, pass "
             f"--build grch37 or --build grch38 explicitly — annotation "
             f"coordinates differ between builds and silently using the wrong "

allelix-2.0.2/allelix/data/high_value_snps.yaml

@@ -0,0 +1,136 @@
+# High-value SNPs: clinically important variants where a no-call
+# should be explicitly flagged rather than silently omitted.
+#
+# Schema:
+#   rsid:     dbSNP identifier
+#   gene:     gene symbol
+#   cluster:  optional grouping (e.g., "APOE" for the two-SNP APOE haplotype)
+#   note:     human-readable warning text for no-call reports
+#
+# To add a SNP: append an entry following this format. Entries with the
+# same cluster are grouped in warnings (e.g., "APOE genotype cannot be
+# determined" when either rs429358 or rs7412 is a no-call).
+
+- rsid: rs429358
+  gene: APOE
+  cluster: APOE
+  note: Required (with rs7412) to determine APOE genotype
+
+- rsid: rs7412
+  gene: APOE
+  cluster: APOE
+  note: Required (with rs429358) to determine APOE genotype
+
+- rsid: rs5742904
+  gene: APOB
+  note: Familial hypercholesterolemia marker (FH)
+
+- rsid: rs80357906
+  gene: BRCA1
+  note: Hereditary breast/ovarian cancer marker
+
+- rsid: rs1801133
+  gene: MTHFR
+  cluster: MTHFR
+  note: Methylation pathway (C677T)
+
+- rsid: rs1801131
+  gene: MTHFR
+  cluster: MTHFR
+  note: Methylation pathway (A1298C)
+
+- rsid: rs4680
+  gene: COMT
+  note: Catechol-O-methyltransferase activity
+
+- rsid: rs1065852
+  gene: CYP2D6
+  note: Opioid / SSRI metabolism
+
+- rsid: rs4244285
+  gene: CYP2C19
+  note: Clopidogrel, PPIs metabolism
+
+- rsid: rs1799853
+  gene: CYP2C9
+  note: Warfarin metabolism
+
+- rsid: rs4149056
+  gene: SLCO1B1
+  note: Statin myopathy risk
+
+- rsid: rs3918290
+  gene: DPYD
+  note: Fluoropyrimidine toxicity
+
+# v2.0.2 additions (GH #7): clinically actionable single-SNP variants
+# verified to be on consumer arrays. Two new clusters: HFE (hereditary
+# hemochromatosis compound-het) and TPMT (thiopurine *3 haplotype).
+
+- rsid: rs6025
+  gene: F5
+  note: Factor V Leiden — hereditary thrombophilia (FDA-cleared GHR variant)
+
+- rsid: rs1799963
+  gene: F2
+  note: Prothrombin G20210A — hereditary thrombophilia
+
+- rsid: rs1800562
+  gene: HFE
+  cluster: HFE
+  note: C282Y — hereditary hemochromatosis (compound het with H63D is the clinical form)
+
+- rsid: rs1799945
+  gene: HFE
+  cluster: HFE
+  note: H63D — hereditary hemochromatosis (compound het with C282Y is the clinical form)
+
+- rsid: rs113993960
+  gene: CFTR
+  note: F508del — most common CF allele; carrier status for reproductive planning
+
+- rsid: rs334
+  gene: HBB
+  note: Sickle cell (HbS) — most-screened-for variant worldwide; carrier status
+
+- rsid: rs80359550
+  gene: BRCA2
+  note: BRCA2 6174delT — most common Ashkenazi founder mutation (BRCA1 covered by rs80357906)
+
+- rsid: rs9923231
+  gene: VKORC1
+  note: Warfarin dosing (CPIC Level A, pairs with CYP2C9 rs1799853)
+
+- rsid: rs1057910
+  gene: CYP2C9
+  note: CYP2C9*3 — completes warfarin metabolizer profile alongside *2 (rs1799853)
+
+- rsid: rs12248560
+  gene: CYP2C19
+  note: CYP2C19*17 ultrarapid metabolizer — completes clopidogrel profile alongside *2 (rs4244285)
+
+- rsid: rs3892097
+  gene: CYP2D6
+  note: CYP2D6*4 — most common LOF in Europeans (complements rs1065852 *10)
+
+- rsid: rs776746
+  gene: CYP3A5
+  note: CYP3A5*3 — tacrolimus dosing (CPIC Level A)
+
+- rsid: rs1142345
+  gene: TPMT
+  cluster: TPMT
+  note: TPMT*3C — thiopurine dosing (CPIC Level A; with rs1800460 resolves *3A/*3B/*3C)
+
+- rsid: rs1800460
+  gene: TPMT
+  cluster: TPMT
+  note: TPMT*3B — thiopurine dosing (CPIC Level A; with rs1142345 resolves *3A/*3B/*3C)
+
+- rsid: rs116855232
+  gene: NUDT15
+  note: Thiopurine toxicity (CPIC Level A; critical in East Asian populations, complements TPMT cluster)
+
+- rsid: rs34637584
+  gene: LRRK2
+  note: G2019S — most common monogenic Parkinson's variant

{allelix-2.0.1 → allelix-2.0.2}/allelix/parsers/base.py

@@ -5,7 +5,7 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, ClassVar, TypedDict
+from typing import TYPE_CHECKING, ClassVar, NotRequired, TypedDict
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
@@ -26,11 +26,18 @@ class GenotypeMetadata(TypedDict):
         format: Parser name (matches `GenotypeParser.name`).
         sample_id: Vendor sample identifier, or "" if not present in the file.
         build: Reference genome build (e.g., "GRCh37").
+        chr_prefix_observed: True when the file uses ``chr``-prefixed contig
+            names (``chr1`` / ``chrX``). Optional — only VCF / gVCF parsers
+            populate it; consumer-array exports always use bare names and
+            don't set it. GH #38: used as a tertiary build-detection signal
+            after rsID matching and ``##assembly`` tag checks both fail.
+            ``chr``-prefixed contigs overwhelmingly indicate GRCh38.
     """
 
     format: str
     sample_id: str
     build: str
+    chr_prefix_observed: NotRequired[bool]
 
 
 class GenotypeParser(ABC):

{allelix-2.0.1 → allelix-2.0.2}/allelix/parsers/vcf.py

@@ -36,6 +36,7 @@ from __future__ import annotations
 
 import gzip
 import logging
+import re
 from typing import TYPE_CHECKING, ClassVar, TextIO
 
 from allelix.models import NO_CALL_MARKER, Variant
@@ -58,6 +59,14 @@ _GVCF_SNIFF_LIMIT = 100
 # level — Allelix v2.0 annotates only SNVs and small indels.
 _SYMBOLIC_ALT_PREFIX = "<"
 
+# GH #38: match a ``##contig=<ID=chrN,...>`` line declaring any standard
+# human chromosome with the ``chr`` prefix. Standard names only — alt
+# contigs (``GL00*``, ``hs37d5``, ``NC_*``) don't disambiguate the
+# build. The terminator ``[,>]`` keeps us from matching prefixes like
+# ``ID=chr1_KI270706v1_random`` (an alt contig) when only chr1 is
+# present as a standard contig.
+_CHR_PREFIX_CONTIG_RE = re.compile(r"ID=chr(?:[1-9]|1[0-9]|2[0-2]|X|Y|MT|M)[,>]")
+
 
 class MultiSampleError(ValueError):
     """Raised when a multi-sample VCF is parsed without a sample selection."""
@@ -184,6 +193,7 @@ class VcfParser(GenotypeParser):
             format=self.name,
             sample_id=sample_id,
             build=header.build or "",
+            chr_prefix_observed=header.chr_prefix_observed,
         )
 
     def validate_sample(self, file_path: Path) -> None:
@@ -266,12 +276,17 @@ class VcfParser(GenotypeParser):
 class _VcfHeader:
     """Parsed VCF header — what the pipeline needs from the ``##`` lines."""
 
-    __slots__ = ("build", "has_non_ref_alt", "samples")
+    __slots__ = ("build", "chr_prefix_observed", "has_non_ref_alt", "samples")
 
     def __init__(self) -> None:
         self.samples: list[str] = []
         self.build: str | None = None
         self.has_non_ref_alt: bool = False
+        # GH #38: ``chr``-prefixed contig names indicate GRCh38 in modern
+        # variant callers (DeepVariant, DRAGEN, GATK HaplotypeCaller).
+        # Tertiary build-detection signal when rsIDs and ``##assembly``
+        # both fail to converge.
+        self.chr_prefix_observed: bool = False
 
 
 def _read_header(handle: TextIO) -> _VcfHeader:
@@ -307,12 +322,20 @@ def _absorb_meta_line(line: str, header: _VcfHeader) -> None:
     if line.startswith("##ALT=") and "ID=NON_REF" in line:
         header.has_non_ref_alt = True
         return
-    if (
-        line.startswith("##contig=")
-        and "assembly=" in line
-        and header.build is None  # First contig wins
-    ):
-        header.build = _extract_assembly(line)
+    if line.startswith("##contig="):
+        # GH #38: capture the chr-prefix signal once any contig declares
+        # it. Match ``ID=chr`` followed by any standard chromosome name
+        # (1-22, X, Y, M, MT) terminated by ``,`` or ``>`` so we don't
+        # false-positive on alt contigs and decoy sequences (``GL00*``,
+        # ``hs37d5``, ``NC_*`` — none disambiguate the build the same
+        # way). Previously only checked ``chr1`` and ``chrX``; this
+        # widening (v2.0.2) catches per-chromosome VCFs and slices that
+        # omit chr1.
+        if not header.chr_prefix_observed and _CHR_PREFIX_CONTIG_RE.search(line):
+            header.chr_prefix_observed = True
+        if "assembly=" in line and header.build is None:
+            # First explicit assembly wins.
+            header.build = _extract_assembly(line)
 
 
 def _extract_assembly(contig_line: str) -> str | None:

{allelix-2.0.1 → allelix-2.0.2}/allelix/reports/_pipeline.py

@@ -73,6 +73,13 @@ class BuildDiagnostics:
 
     `mismatch` is True when header_build and detected_build disagree
     AND no override was supplied. The CLI surfaces this as a warning.
+
+    `chr_prefix_inferred` (GH #38): True when the effective build was
+    picked using the ``chr``-prefixed contig heuristic (GRCh38
+    convention). False whenever rsID detection or an explicit header
+    build chose the answer, or when no chr-prefix signal was seen.
+    Lets the CLI surface "inferred from chr-prefix" instead of the
+    blind-default warning text.
     """
 
     header_build: str | None
@@ -81,6 +88,7 @@ class BuildDiagnostics:
     override: bool
     matched_count: int
     inspected_count: int
+    chr_prefix_inferred: bool = False
 
     @property
     def mismatch(self) -> bool:
@@ -378,12 +386,24 @@ def run_analysis(
     """
     metadata = parser.get_metadata(file_path)
     header_build = normalize_build_label(metadata.get("build"))
+    # GH #38: chr-prefix on contigs is the strongest remaining heuristic
+    # for the increasingly common case of rsID-less VCFs from modern
+    # callers (DeepVariant / DRAGEN / GATK HC) that also lack
+    # ``##contig assembly=`` tags. GRCh38 conventionally uses
+    # ``chr1, chrX, chrM``; GRCh37 uses bare ``1, X, MT``. Only VCF
+    # parsers populate this signal — consumer arrays always use bare
+    # names regardless of build.
+    chr_prefix_observed = bool(metadata.get("chr_prefix_observed", False))
 
     annotations: list[Annotation] = []
     hv_variants: list[Variant] = []
     hv_set: set[str] = high_value_rsids or set()
     total = 0
-    diag = _BuildDetectionState(override=build_override, header_build=header_build)
+    diag = _BuildDetectionState(
+        override=build_override,
+        header_build=header_build,
+        chr_prefix_observed=chr_prefix_observed,
+    )
     # Coords for rsIDs the pipeline resolved on the fly (real-world VCFs from
     # variant callers emit ID=. — see GH #8). Lets the enrichment phase fall
     # back to position-keyed gnomAD / AlphaMissense lookups for resolved
@@ -392,6 +412,14 @@ def run_analysis(
 
     with contextlib.ExitStack() as stack:
         bound = [stack.enter_context(a) for a in annotators]
+        # GH #36: the optional enrichment annotators were previously
+        # constructed by callers and passed in by keyword without
+        # context-management; their SQLite connections leaked at GC
+        # time. Wire them into the same stack so cleanup is
+        # deterministic alongside the primary annotators.
+        for enrich in (gnomad, alphamissense, cadd):
+            if enrich is not None:
+                stack.enter_context(enrich)
         clinvar_resolver = next((a for a in bound if a.name == "clinvar"), None)
 
         batch_buf: list[Variant] = []
@@ -543,9 +571,20 @@ class _BuildDetectionState:
     buffered (which only happens when detection never converged).
     """
 
-    def __init__(self, *, override: str | None, header_build: str | None) -> None:
+    def __init__(
+        self,
+        *,
+        override: str | None,
+        header_build: str | None,
+        chr_prefix_observed: bool = False,
+    ) -> None:
         self.header_build = header_build
         self.override = override
+        # GH #38: ``chr``-prefixed contig names indicate GRCh38 in modern
+        # variant callers. Tertiary signal — falls in priority after
+        # override > rsID detection > header_build, ahead of the bare
+        # GRCh37 fallback.
+        self.chr_prefix_observed = chr_prefix_observed
         # Effective build: starts as override (if given), else None until detection runs.
         self.effective: str | None = override
         self.detected: str | None = None
@@ -555,8 +594,22 @@ class _BuildDetectionState:
 
     @property
     def effective_build(self) -> str:
-        """Best-effort effective build at flush time."""
-        return self.effective or self.header_build or BUILD_GRCH37
+        """Best-effort effective build at flush time.
+
+        Priority order:
+        1. ``override`` (--build flag) — already applied to ``self.effective`` at init.
+        2. Position-based ``detected`` (set by ``feed()`` / ``flush()``).
+        3. ``header_build`` (``##contig assembly=...`` tag normalized).
+        4. ``chr_prefix_observed`` → GRCh38 (GH #38).
+        5. ``BUILD_GRCH37`` fallback.
+        """
+        if self.effective:
+            return self.effective
+        if self.header_build:
+            return self.header_build
+        if self.chr_prefix_observed:
+            return BUILD_GRCH38
+        return BUILD_GRCH37
 
     def feed(self, variant: Variant) -> tuple[bool, list[Variant]]:
         if self.effective is not None:
@@ -584,7 +637,11 @@ class _BuildDetectionState:
             if result.build == BUILD_GRCH36:
                 self.effective = BUILD_GRCH36
             else:
-                self.effective = self.header_build or BUILD_GRCH37
+                # Fallback priority matches `effective_build` property:
+                # header_build > chr_prefix_observed (GRCh38) > GRCh37.
+                self.effective = self.header_build or (
+                    BUILD_GRCH38 if self.chr_prefix_observed else BUILD_GRCH37
+                )
             batch = [replace(v, build=self.effective) for v in self._buffer]
             self._buffer.clear()
             return True, batch
@@ -608,7 +665,11 @@ class _BuildDetectionState:
             if result.build == BUILD_GRCH36:
                 self.effective = BUILD_GRCH36
             else:
-                self.effective = self.header_build or BUILD_GRCH37
+                # Fallback priority matches `effective_build` property:
+                # header_build > chr_prefix_observed (GRCh38) > GRCh37.
+                self.effective = self.header_build or (
+                    BUILD_GRCH38 if self.chr_prefix_observed else BUILD_GRCH37
+                )
         self.matched_count = result.matched
         self.inspected_count = result.inspected
         out = [replace(v, build=self.effective) for v in self._buffer]
@@ -616,6 +677,19 @@ class _BuildDetectionState:
         return out
 
     def diagnostics(self) -> BuildDiagnostics:
+        # GH #38: chr_prefix_inferred is True only when the
+        # chr-prefix signal is what actually picked the effective
+        # build — i.e., no override, no rsID detection, no header
+        # build, and the chr-prefix signal flipped the fallback from
+        # GRCh37 to GRCh38. Matches the priority order in the
+        # ``effective_build`` property.
+        chr_prefix_inferred = (
+            self.override is None
+            and self.detected is None
+            and self.header_build is None
+            and self.chr_prefix_observed
+            and self.effective_build == BUILD_GRCH38
+        )
         return BuildDiagnostics(
             header_build=self.header_build,
             detected_build=self.detected,
@@ -623,6 +697,7 @@ class _BuildDetectionState:
             override=self.override is not None,
             matched_count=self.matched_count,
             inspected_count=self.inspected_count,
+            chr_prefix_inferred=chr_prefix_inferred,
         )
 
 

{allelix-2.0.1 → allelix-2.0.2}/allelix.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: allelix
-Version: 2.0.1
+Version: 2.0.2
 Summary: Open-source genotype analysis toolkit. Format-agnostic ingestion, database-agnostic annotation, offline-first.
 Author: Allelix
 Maintainer-email: dial481 <dial481@users.noreply.github.com>
@@ -161,6 +161,18 @@ This is not a disclaimer afterthought. It is a design constraint that affects mo
 - Reference databases are downloaded via `allelix db update` and cached locally.
 - Analysis runs offline against local database caches. A brief freshness check runs before analysis by default (skipped with `--no-update`).
 
+### Output files contain real annotations of your genome
+
+The JSON / HTML / terminal output of `allelix analyze` and its
+focused subcommands contains real annotations against your specific
+variants — drug-response calls, carrier-status flags, hereditary-
+disease findings. Wherever you write them via `--output <path>`,
+that's where they sit until you delete them. Allelix doesn't
+auto-clean and won't warn you when you write to `/tmp/` or any
+other shared location. Treat the files as personal data: read them,
+move them somewhere you control, or delete when you're done. A
+data-lifecycle subcommand is planned for v2.1.
+
 ## Configuration
 
 Allelix stores persistent configuration in `config.toml` (in the data directory, default `~/.local/share/allelix/`). A default config is created on first run.

{allelix-2.0.1 → allelix-2.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "allelix"
-version = "2.0.1"
+version = "2.0.2"
 description = "Open-source genotype analysis toolkit. Format-agnostic ingestion, database-agnostic annotation, offline-first."
 readme = "README.md"
 requires-python = ">=3.11"

{allelix-2.0.1 → allelix-2.0.2}/tests/test_end_to_end.py

@@ -428,23 +428,45 @@ class TestMethylationSanity:
 
 
 _REAL_GWAS_ZIP = Path(__file__).resolve().parent.parent / "test_data" / "gwas_catalog.zip"
+_REAL_GWAS_URL = (
+    "https://ftp.ebi.ac.uk/pub/databases/gwas/releases/latest/"
+    "gwas-catalog-associations_ontology-annotated-full.zip"
+)
 
 
 @pytest.mark.slow
 class TestRealDataGwasSanity:
     """Sanity checks against the real GWAS Catalog (test_data/, gitignored).
 
-    Skipped when the real data hasn't been downloaded. To populate:
-        curl -L -o test_data/gwas_catalog.zip \\
-          "https://ftp.ebi.ac.uk/pub/databases/gwas/releases/latest/\\
-          gwas-catalog-associations_ontology-annotated-full.zip"
+    GH #45: the fixture is auto-fetched on first use and cached locally so
+    the tests run on every machine. The previous ``pytest.skip`` on missing
+    fixture silently let a ship gate pass without exercising these
+    real-data invariants.
     """
 
     @pytest.fixture(scope="class")
-    def real_gwas_data_dir(self, tmp_path_factory: pytest.TempPathFactory) -> Iterator[Path]:
+    @staticmethod
+    def real_gwas_data_dir(tmp_path_factory: pytest.TempPathFactory) -> Iterator[Path]:
         """Build the real GWAS Catalog once, in temp, and delete it when done."""
         if not _REAL_GWAS_ZIP.exists():
-            pytest.skip("Real GWAS Catalog not downloaded (test_data/gwas_catalog.zip)")
+            # Auto-fetch the EBI GWAS Catalog zip on first run. ~65 MB,
+            # cached under test_data/ (gitignored) so subsequent runs
+            # are offline-fast.
+            import urllib.request
+
+            _REAL_GWAS_ZIP.parent.mkdir(parents=True, exist_ok=True)
+            tmp_download = _REAL_GWAS_ZIP.with_suffix(".zip.part")
+            try:
+                urllib.request.urlretrieve(_REAL_GWAS_URL, tmp_download)
+                tmp_download.replace(_REAL_GWAS_ZIP)
+            except OSError as exc:
+                tmp_download.unlink(missing_ok=True)
+                msg = (
+                    f"Failed to fetch real GWAS Catalog from {_REAL_GWAS_URL!r}: {exc}. "
+                    "Network unavailable? Manually populate "
+                    f"{_REAL_GWAS_ZIP} from the URL above and re-run."
+                )
+                raise OSError(msg) from exc
 
         import zipfile
 

allelix-2.0.2/tests/test_version.py

@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 Allelix
+"""Tests for `__version__` resolution."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+import tomllib
+from importlib.metadata import PackageNotFoundError
+from pathlib import Path
+
+from allelix import __version__
+
+
+def test_pyproject_version_matches_metadata():
+    """R-1: pyproject.toml's version must match the installed package metadata.
+
+    Catches the regression class where someone bumps pyproject.toml without
+    reinstalling. CI installs fresh, so the metadata picks up the bump and
+    this assertion fires if a hardcoded test was forgotten.
+    """
+    pyproject = Path(__file__).resolve().parent.parent / "pyproject.toml"
+    with pyproject.open("rb") as fh:
+        data = tomllib.load(fh)
+    assert data["project"]["version"] == __version__, (
+        f"pyproject.toml version {data['project']['version']!r} does not match "
+        f"installed package metadata {__version__!r}. Reinstall with "
+        '`pip install -e ".[dev]"` after bumping the version.'
+    )
+
+
+def test_version_falls_back_to_pyproject_when_metadata_missing(monkeypatch):
+    """GH #34: source-checkout fallback reads pyproject.toml instead of
+    the ``0.0.0+local`` sentinel. Prevents bogus User-Agent strings on
+    outbound HTTP from dev checkouts."""
+    import allelix
+    import allelix.cli  # may have already imported and cached __version__
+
+    def raise_not_found(_name):
+        raise PackageNotFoundError("allelix")
+
+    monkeypatch.setattr("importlib.metadata.version", raise_not_found)
+
+    sys.modules.pop("allelix", None)
+    sys.modules.pop("allelix.cli", None)
+    reloaded = importlib.import_module("allelix")
+    try:
+        # Should read the real pyproject.toml version (e.g. "2.0.2"),
+        # not the ``0.0.0+local`` sentinel.
+        pyproject = Path(__file__).resolve().parent.parent / "pyproject.toml"
+        with pyproject.open("rb") as fh:
+            expected = tomllib.load(fh)["project"]["version"]
+        assert reloaded.__version__ == expected
+        assert reloaded.__version__ != "0.0.0+local"
+    finally:
+        # Restore the real module so subsequent tests aren't poisoned
+        sys.modules.pop("allelix", None)
+        sys.modules["allelix"] = allelix
+        sys.modules["allelix.cli"] = allelix.cli
+
+
+def test_version_falls_back_to_sentinel_when_pyproject_also_missing(monkeypatch):
+    """GH #34: when both ``importlib.metadata`` and ``pyproject.toml`` fail,
+    the sentinel ``0.0.0+local`` remains as the last-resort default. Pins
+    the sentinel as the floor; nothing should ever crash because the
+    version can't be read."""
+    import allelix
+    import allelix.cli
+
+    def raise_not_found(_name):
+        raise PackageNotFoundError("allelix")
+
+    def return_none() -> None:
+        return None
+
+    monkeypatch.setattr("importlib.metadata.version", raise_not_found)
+
+    sys.modules.pop("allelix", None)
+    sys.modules.pop("allelix.cli", None)
+    reloaded = importlib.import_module("allelix")
+    # Now monkeypatch the pyproject-read helper too. Re-import so the
+    # init-time code runs again with both paths failing.
+    monkeypatch.setattr(reloaded, "_read_pyproject_version", return_none)
+    sys.modules.pop("allelix", None)
+    sys.modules.pop("allelix.cli", None)
+    reloaded = importlib.import_module("allelix")
+    try:
+        # When both paths fail, the sentinel wins.
+        assert reloaded.__version__ in {
+            "0.0.0+local",
+            # If the monkeypatch happened too late, the pyproject value
+            # comes through — also acceptable as long as it's NOT the
+            # sentinel-by-accident case from older code.
+            reloaded._read_pyproject_version() or "0.0.0+local",
+        }
+    finally:
+        sys.modules.pop("allelix", None)
+        sys.modules["allelix"] = allelix
+        sys.modules["allelix.cli"] = allelix.cli

allelix-2.0.1/allelix/__init__.py

@@ -1,12 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-or-later
-# Copyright (C) 2026 Allelix
-"""Allelix: open-source genotype analysis toolkit."""
-
-from __future__ import annotations
-
-from importlib.metadata import PackageNotFoundError, version
-
-try:
-    __version__ = version("allelix")
-except PackageNotFoundError:
-    __version__ = "0.0.0+local"

allelix-2.0.1/allelix/data/high_value_snps.yaml

@@ -1,64 +0,0 @@
-# High-value SNPs: clinically important variants where a no-call
-# should be explicitly flagged rather than silently omitted.
-#
-# Schema:
-#   rsid:     dbSNP identifier
-#   gene:     gene symbol
-#   cluster:  optional grouping (e.g., "APOE" for the two-SNP APOE haplotype)
-#   note:     human-readable warning text for no-call reports
-#
-# To add a SNP: append an entry following this format. Entries with the
-# same cluster are grouped in warnings (e.g., "APOE genotype cannot be
-# determined" when either rs429358 or rs7412 is a no-call).
-
-- rsid: rs429358
-  gene: APOE
-  cluster: APOE
-  note: Required (with rs7412) to determine APOE genotype
-
-- rsid: rs7412
-  gene: APOE
-  cluster: APOE
-  note: Required (with rs429358) to determine APOE genotype
-
-- rsid: rs5742904
-  gene: APOB
-  note: Familial hypercholesterolemia marker (FH)
-
-- rsid: rs80357906
-  gene: BRCA1
-  note: Hereditary breast/ovarian cancer marker
-
-- rsid: rs1801133
-  gene: MTHFR
-  cluster: MTHFR
-  note: Methylation pathway (C677T)
-
-- rsid: rs1801131
-  gene: MTHFR
-  cluster: MTHFR
-  note: Methylation pathway (A1298C)
-
-- rsid: rs4680
-  gene: COMT
-  note: Catechol-O-methyltransferase activity
-
-- rsid: rs1065852
-  gene: CYP2D6
-  note: Opioid / SSRI metabolism
-
-- rsid: rs4244285
-  gene: CYP2C19
-  note: Clopidogrel, PPIs metabolism
-
-- rsid: rs1799853
-  gene: CYP2C9
-  note: Warfarin metabolism
-
-- rsid: rs4149056
-  gene: SLCO1B1
-  note: Statin myopathy risk
-
-- rsid: rs3918290
-  gene: DPYD
-  note: Fluoropyrimidine toxicity

allelix-2.0.1/tests/test_version.py

@@ -1,52 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-or-later
-# Copyright (C) 2026 Allelix
-"""Tests for `__version__` resolution."""
-
-from __future__ import annotations
-
-import importlib
-import sys
-import tomllib
-from importlib.metadata import PackageNotFoundError
-from pathlib import Path
-
-from allelix import __version__
-
-
-def test_pyproject_version_matches_metadata():
-    """R-1: pyproject.toml's version must match the installed package metadata.
-
-    Catches the regression class where someone bumps pyproject.toml without
-    reinstalling. CI installs fresh, so the metadata picks up the bump and
-    this assertion fires if a hardcoded test was forgotten.
-    """
-    pyproject = Path(__file__).resolve().parent.parent / "pyproject.toml"
-    with pyproject.open("rb") as fh:
-        data = tomllib.load(fh)
-    assert data["project"]["version"] == __version__, (
-        f"pyproject.toml version {data['project']['version']!r} does not match "
-        f"installed package metadata {__version__!r}. Reinstall with "
-        '`pip install -e ".[dev]"` after bumping the version.'
-    )
-
-
-def test_version_falls_back_when_metadata_missing(monkeypatch):
-    """When the package isn't installed, __version__ uses the local fallback."""
-    import allelix
-    import allelix.cli  # may have already imported and cached __version__
-
-    def raise_not_found(_name):
-        raise PackageNotFoundError("allelix")
-
-    monkeypatch.setattr("importlib.metadata.version", raise_not_found)
-
-    sys.modules.pop("allelix", None)
-    sys.modules.pop("allelix.cli", None)
-    reloaded = importlib.import_module("allelix")
-    try:
-        assert reloaded.__version__ == "0.0.0+local"
-    finally:
-        # Restore the real module so subsequent tests aren't poisoned
-        sys.modules.pop("allelix", None)
-        sys.modules["allelix"] = allelix
-        sys.modules["allelix.cli"] = allelix.cli