allelix 2.1.1__tar.gz → 2.1.2__tar.gz

{allelix-2.1.1 → allelix-2.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: allelix
-Version: 2.1.1
+Version: 2.1.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>
@@ -29,35 +29,33 @@ Requires-Dist: pysam>=0.22; extra == "cadd"
 Provides-Extra: vcf-index
 Requires-Dist: pysam>=0.22; extra == "vcf-index"
 Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == "dev"
 Requires-Dist: pre-commit>=3.7; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov<8,>=7; extra == "dev"
 Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
 Dynamic: license-file
 
+<div align="center">
+
+<img src="https://allelix.io/apple-touch-icon.png" width="180" alt="Allelix" />
+
+**Open-source genotype analysis. Format-agnostic. Offline-first.**
+
+[Website](https://allelix.io) · [Quickstart](#quickstart) · [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md)
+
+[![python](https://img.shields.io/pypi/pyversions/allelix.svg)](https://www.python.org/downloads/)
+[![pypi](https://img.shields.io/pypi/v/allelix.svg)](https://pypi.org/project/allelix/)
+[![license](https://img.shields.io/pypi/l/allelix.svg)](LICENSE)
+[![CI](https://github.com/allelix/allelix/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/allelix/allelix/actions/workflows/ci.yml)
+[![privacy: local-first](https://img.shields.io/badge/privacy-local--first-success)](#privacy)
+
+</div>
+
 # Allelix
 
-Open-source command-line toolkit for analyzing raw genotype files from consumer DNA testing services. Format-agnostic ingestion, database-agnostic annotation, offline-first.
-
-> **Status:** Production — eight parser formats (including VCF + gVCF),
-> four annotators (ClinVar + ClinPGx + GWAS Catalog + SNPedia), three
-> enrichment sources (gnomAD population frequencies + AlphaMissense
-> pathogenicity + CADD deleteriousness), licensable-source gating for
-> commercial users, dual-build ClinVar caches (GRCh37 + GRCh38),
-> HTML/JSON/terminal reports, methylation + pharmacogenomics focused
-> commands, report diffing, persistent config with commercial-mode
-> safety switch. Build auto-detection from position data (ADR-0021).
-> No regex on prose anywhere in production. **Latest: v2.1.0** —
-> ADR-0035 'Cluster B' coordinated model change: `Variant.ref` carries
-> the forward-strand reference allele, per-Annotation `alt` threading
-> on GWAS / SNPedia / ClinPGx enables allele-specific gnomAD /
-> AlphaMissense / CADD enrichment on array inputs, structured GWAS
-> fields (`trait` / `p_value` / `phecode`) replace prose re-parsing in
-> the rollup, and ClinVar / ClinPGx carrier matching is strand-aware
-> with multi-allelic safety guard. JSON `schema_version` bumped 4 → 5
-> (additive, v4 readers unaffected).
-> Release notes:
-> [`CHANGELOG.md`](https://github.com/allelix/allelix/blob/main/CHANGELOG.md).
+> **Status:** Production. Eight parser formats (including VCF + gVCF), four annotators (ClinVar + ClinPGx + GWAS Catalog + SNPedia), three enrichment sources (gnomAD + AlphaMissense + CADD), licensable-source gating for commercial users, dual-build ClinVar caches (GRCh37 + GRCh38), HTML/JSON/terminal reports, methylation + pharmacogenomics focused commands, report diffing, persistent config with commercial-mode safety switch. Build auto-detection from position data (ADR-0021). No regex on prose anywhere in production. The [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md) tracks every release.
 
 ## Quickstart
 
@@ -101,16 +99,17 @@ See [Development](#development) for source installs and running tests, [Managing
 
 Adding a new format means adding one file to `allelix/parsers/` and registering an instance in the `PARSERS` list in `allelix/parsers/__init__.py`.
 
-### v2.1+ roadmap
+### Roadmap
 
-| Feature | Notes |
+| Release | Theme |
 |---|---|
-| Per-source scoring | Magnitude breakdown by database. Users see which source drove the composite score. |
-| Annotator-level strand awareness (R-1) | Strand-flip matching wired into every annotator's carrier check. Basic `compare` strand support shipped in v1.1; full annotator integration deferred from v2.0.0. |
-| Good / Bad / Neutral repute | Per-annotation repute field. Reframes the report from "here's what's wrong" to "here's your full picture." Requires Annotation model change + renderer updates. |
-| PLINK import | Read .bed/.bim/.fam as an input format (complement to the v1.7.0 export). |
-| PharmCAT integration | Wrap CPIC's PharmCAT as an optional external engine for star-allele / diplotype calling. Requires VCF input (shipped in v2.0.0). |
-| Genome Watchtower | Real-time variant monitoring via database delta feeds. Privacy-preserving: server publishes universal feed, matching happens locally against your deviation set. Replaces full re-analysis with millisecond set intersection. |
+| **v2.2** | Annotation model expansion (cross-source conflict surfacing, risk-allele display, structured MTAG flag), custom-panel UX improvements, methylation panel retune + citations, ClinVar source switch (VCF → `variant_summary.txt`), CLI cleanups (`db clean` / `db path`). |
+| **v2.3** | Per-source magnitude decomposition, Good / Bad / Neutral annotation repute, JSON v3 (AI-legible output contract), plausibility flagging via zygosity × gnomAD MAF, ClinVar review-status weighting, functional-medicine +/− notation. |
+| **v2.4** | ACMG/AMP automated classification engine, variant consequence annotation (VEP-equivalent). |
+| **v2.5+** | CNVs and repeat-expansion support, dbSNP resolution for rsID-less VCFs, gnomAD genomes (non-coding population frequencies), supplemental genotype file merging. |
+| **v3.0** | Ancestry estimation (PCA + 1KG/HGDP reference panels), Polygenic Risk Score (PRS) integration. |
+
+Issues and milestones are tracked at [github.com/allelix/allelix/issues](https://github.com/allelix/allelix/issues). Annotator-level strand-aware carrier matching (R-1) shipped in v2.1.0's ADR-0035 cluster.
 
 ## Supported Databases
 

{allelix-2.1.1 → allelix-2.1.2}/README.md

@@ -1,26 +1,22 @@
+<div align="center">
+
+<img src="https://allelix.io/apple-touch-icon.png" width="180" alt="Allelix" />
+
+**Open-source genotype analysis. Format-agnostic. Offline-first.**
+
+[Website](https://allelix.io) · [Quickstart](#quickstart) · [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md)
+
+[![python](https://img.shields.io/pypi/pyversions/allelix.svg)](https://www.python.org/downloads/)
+[![pypi](https://img.shields.io/pypi/v/allelix.svg)](https://pypi.org/project/allelix/)
+[![license](https://img.shields.io/pypi/l/allelix.svg)](LICENSE)
+[![CI](https://github.com/allelix/allelix/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/allelix/allelix/actions/workflows/ci.yml)
+[![privacy: local-first](https://img.shields.io/badge/privacy-local--first-success)](#privacy)
+
+</div>
+
 # Allelix
 
-Open-source command-line toolkit for analyzing raw genotype files from consumer DNA testing services. Format-agnostic ingestion, database-agnostic annotation, offline-first.
-
-> **Status:** Production — eight parser formats (including VCF + gVCF),
-> four annotators (ClinVar + ClinPGx + GWAS Catalog + SNPedia), three
-> enrichment sources (gnomAD population frequencies + AlphaMissense
-> pathogenicity + CADD deleteriousness), licensable-source gating for
-> commercial users, dual-build ClinVar caches (GRCh37 + GRCh38),
-> HTML/JSON/terminal reports, methylation + pharmacogenomics focused
-> commands, report diffing, persistent config with commercial-mode
-> safety switch. Build auto-detection from position data (ADR-0021).
-> No regex on prose anywhere in production. **Latest: v2.1.0** —
-> ADR-0035 'Cluster B' coordinated model change: `Variant.ref` carries
-> the forward-strand reference allele, per-Annotation `alt` threading
-> on GWAS / SNPedia / ClinPGx enables allele-specific gnomAD /
-> AlphaMissense / CADD enrichment on array inputs, structured GWAS
-> fields (`trait` / `p_value` / `phecode`) replace prose re-parsing in
-> the rollup, and ClinVar / ClinPGx carrier matching is strand-aware
-> with multi-allelic safety guard. JSON `schema_version` bumped 4 → 5
-> (additive, v4 readers unaffected).
-> Release notes:
-> [`CHANGELOG.md`](https://github.com/allelix/allelix/blob/main/CHANGELOG.md).
+> **Status:** Production. Eight parser formats (including VCF + gVCF), four annotators (ClinVar + ClinPGx + GWAS Catalog + SNPedia), three enrichment sources (gnomAD + AlphaMissense + CADD), licensable-source gating for commercial users, dual-build ClinVar caches (GRCh37 + GRCh38), HTML/JSON/terminal reports, methylation + pharmacogenomics focused commands, report diffing, persistent config with commercial-mode safety switch. Build auto-detection from position data (ADR-0021). No regex on prose anywhere in production. The [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md) tracks every release.
 
 ## Quickstart
 
@@ -64,16 +60,17 @@ See [Development](#development) for source installs and running tests, [Managing
 
 Adding a new format means adding one file to `allelix/parsers/` and registering an instance in the `PARSERS` list in `allelix/parsers/__init__.py`.
 
-### v2.1+ roadmap
+### Roadmap
 
-| Feature | Notes |
+| Release | Theme |
 |---|---|
-| Per-source scoring | Magnitude breakdown by database. Users see which source drove the composite score. |
-| Annotator-level strand awareness (R-1) | Strand-flip matching wired into every annotator's carrier check. Basic `compare` strand support shipped in v1.1; full annotator integration deferred from v2.0.0. |
-| Good / Bad / Neutral repute | Per-annotation repute field. Reframes the report from "here's what's wrong" to "here's your full picture." Requires Annotation model change + renderer updates. |
-| PLINK import | Read .bed/.bim/.fam as an input format (complement to the v1.7.0 export). |
-| PharmCAT integration | Wrap CPIC's PharmCAT as an optional external engine for star-allele / diplotype calling. Requires VCF input (shipped in v2.0.0). |
-| Genome Watchtower | Real-time variant monitoring via database delta feeds. Privacy-preserving: server publishes universal feed, matching happens locally against your deviation set. Replaces full re-analysis with millisecond set intersection. |
+| **v2.2** | Annotation model expansion (cross-source conflict surfacing, risk-allele display, structured MTAG flag), custom-panel UX improvements, methylation panel retune + citations, ClinVar source switch (VCF → `variant_summary.txt`), CLI cleanups (`db clean` / `db path`). |
+| **v2.3** | Per-source magnitude decomposition, Good / Bad / Neutral annotation repute, JSON v3 (AI-legible output contract), plausibility flagging via zygosity × gnomAD MAF, ClinVar review-status weighting, functional-medicine +/− notation. |
+| **v2.4** | ACMG/AMP automated classification engine, variant consequence annotation (VEP-equivalent). |
+| **v2.5+** | CNVs and repeat-expansion support, dbSNP resolution for rsID-less VCFs, gnomAD genomes (non-coding population frequencies), supplemental genotype file merging. |
+| **v3.0** | Ancestry estimation (PCA + 1KG/HGDP reference panels), Polygenic Risk Score (PRS) integration. |
+
+Issues and milestones are tracked at [github.com/allelix/allelix/issues](https://github.com/allelix/allelix/issues). Annotator-level strand-aware carrier matching (R-1) shipped in v2.1.0's ADR-0035 cluster.
 
 ## Supported Databases
 

{allelix-2.1.1 → allelix-2.1.2}/allelix/annotators/__init__.py

@@ -57,18 +57,16 @@ def get_annotators(
     return [clinvar, pharmgkb, gwas, snpedia, gnomad, alphamissense, cadd]
 
 
-_ANNOTATOR_CLASSES: dict[str, type[Annotator]] = {
-    cls.name: cls
-    for cls in [
-        ClinVarAnnotator,
-        PharmGKBAnnotator,
-        GWASCatalogAnnotator,
-        SNPediaAnnotator,
-        GnomadAnnotator,
-        AlphaMissenseAnnotator,
-        CaddAnnotator,
-    ]
-}
+_ANNOTATOR_CLASS_LIST: list[type[Annotator]] = [
+    ClinVarAnnotator,
+    PharmGKBAnnotator,
+    GWASCatalogAnnotator,
+    SNPediaAnnotator,
+    GnomadAnnotator,
+    AlphaMissenseAnnotator,
+    CaddAnnotator,
+]
+_ANNOTATOR_CLASSES: dict[str, type[Annotator]] = {cls.name: cls for cls in _ANNOTATOR_CLASS_LIST}
 
 
 def get_annotator_class(name: str) -> type[Annotator] | None:

{allelix-2.1.1 → allelix-2.1.2}/allelix/annotators/base.py

@@ -4,7 +4,6 @@
 
 from __future__ import annotations
 
-import contextlib
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from enum import Enum, auto
@@ -141,43 +140,6 @@ class Annotator(ABC):
         """Bind the annotator to a data directory (created elsewhere)."""
         self.data_dir = data_dir
 
-    def __del__(self) -> None:
-        """Safety-net resource release on GC. Deliberately retained.
-
-        Status (v2.1.1 audit, GH #36):
-        - **Production callsites are clean.** ``run_analysis`` wires every
-          primary + enrichment annotator into ``contextlib.ExitStack``
-          (v2.0.2 fix). ``allelix/cli/utility.py`` lines 221 and 476 each
-          construct a ``GnomadAnnotator`` inside ``try / finally
-          gnomad.close()``. ``allelix/annotators/__init__.py`` returns a
-          list that the pipeline immediately wraps in ``ExitStack``.
-        - **Test callsites NOT yet clean.** ~27 sites in
-          ``tests/reports/test_pipeline.py`` instantiate annotators
-          directly without a context manager or explicit close. The
-          pipeline closes them via its own ``ExitStack`` during
-          ``run_analysis``, but the test still holds the closed-instance
-          reference, and the underlying sqlite3 ``Connection``'s GC
-          finalizer surfaces a ``ResourceWarning`` during the next test's
-          startup. pytest's ``error::PytestUnraisableExceptionWarning``
-          filter then converts it to a hard failure on the gate.
-
-        Removing ``__del__`` without first refactoring the test sites
-        therefore fails the gate (verified — 3 failures, all in
-        ``tests/reports/test_pipeline.py``, triggered by leaks from
-        earlier tests in the same file). The test-site refactor is
-        tracked separately; ``__del__`` stays as the safety net until
-        that lands. v2.1.x task — see the follow-up issue filed at
-        ``#36``-closure-time.
-
-        ``contextlib.suppress(Exception)`` is deliberate — ``__del__``
-        must never raise. 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()
-
     def __enter__(self) -> Annotator:
         """Return self for `with` usage."""
         return self

{allelix-2.1.1 → allelix-2.1.2}/allelix/annotators/cadd.py

@@ -24,7 +24,7 @@ from __future__ import annotations
 
 import logging
 import sqlite3
-from typing import TYPE_CHECKING, ClassVar
+from typing import TYPE_CHECKING, Any, ClassVar
 
 from allelix.annotators.base import Annotator, LicenseDescriptor
 from allelix.databases._versions import CADD_SCHEMA_VERSION
@@ -90,9 +90,11 @@ class CaddAnnotator(Annotator):
         self._conn: sqlite3.Connection | None = None
         self._full_mode = full_mode
         self._tabix_path = data_dir / CADD_FULL_FILENAME
-        self._tabix: object | None = None
+        # pysam ships no type stubs (see [tool.mypy.overrides]); the tabix
+        # handle is held as Any so call sites can use `.fetch()` / `.close()`.
+        self._tabix: Any = None
         self._indel_tabix_path = data_dir / CADD_INDEL_FILENAME
-        self._indel_tabix: object | None = None
+        self._indel_tabix: Any = None
 
     def _connection(self) -> sqlite3.Connection:
         if self._conn is None:
@@ -104,11 +106,11 @@ class CaddAnnotator(Annotator):
             self._conn = sqlite3.connect(self._db_path)
         return self._conn
 
-    def _open_tabix(self) -> object:
+    def _open_tabix(self) -> Any:  # noqa: ANN401 — pysam ships no type stubs
         """Open the tabix file for full-mode queries."""
         if self._tabix is None:
             try:
-                import pysam  # type: ignore[import-untyped]
+                import pysam
             except ImportError:
                 raise ImportError(
                     "Full CADD mode requires pysam. Install with: pip install 'allelix[cadd]'"
@@ -122,7 +124,7 @@ class CaddAnnotator(Annotator):
             self._tabix = pysam.TabixFile(str(self._tabix_path))
         return self._tabix
 
-    def _open_indel_tabix(self) -> object | None:
+    def _open_indel_tabix(self) -> Any:  # noqa: ANN401 — pysam ships no type stubs
         """Open the indel tabix file. Returns None if file doesn't exist."""
         if self._indel_tabix is None:
             if not self._indel_tabix_path.exists():
@@ -131,7 +133,7 @@ class CaddAnnotator(Annotator):
             if not tbi.exists():
                 return None
             try:
-                import pysam  # type: ignore[import-untyped]
+                import pysam
             except ImportError:
                 return None
             self._indel_tabix = pysam.TabixFile(str(self._indel_tabix_path))

{allelix-2.1.1 → allelix-2.1.2}/allelix/annotators/clinvar.py

@@ -500,9 +500,10 @@ class ClinVarAnnotator(Annotator):
             for rows in clinvar_rows.values():
                 rows.sort()
             for v in build_variants:
-                rows = clinvar_rows.get((v.chromosome, v.position))
-                if not rows:
+                pos_rows = clinvar_rows.get((v.chromosome, v.position))
+                if not pos_rows:
                     continue
+                rows = pos_rows
                 user_alleles = {v.allele1, v.allele2}
                 # Stamp only on a UNIQUE consistent match. Multiple matches
                 # mean the Variant model can't distinguish them (the 1/1

{allelix-2.1.1 → allelix-2.1.2}/allelix/cli/_helpers.py

@@ -16,7 +16,7 @@ import logging
 import re
 import sys
 import time
-from typing import TYPE_CHECKING, NamedTuple
+from typing import TYPE_CHECKING, NamedTuple, cast
 
 import click
 from rich.console import Console
@@ -34,7 +34,10 @@ from allelix.reports.terminal import render_terminal, render_terminal_diff
 if TYPE_CHECKING:
     from pathlib import Path
 
+    from allelix.annotators.alphamissense import AlphaMissenseAnnotator
     from allelix.annotators.base import Annotator
+    from allelix.annotators.cadd import CaddAnnotator
+    from allelix.annotators.gnomad import GnomadAnnotator
     from allelix.parsers.base import GenotypeParser
 
 console = Console()
@@ -489,9 +492,9 @@ def _run_analysis_command(
             ready,
             skipped_count_provider=lambda: counter.count,
             build_override=build,
-            gnomad=gnomad_annotator,
-            alphamissense=am_annotator,
-            cadd=cadd_annotator,
+            gnomad=cast("GnomadAnnotator | None", gnomad_annotator),
+            alphamissense=cast("AlphaMissenseAnnotator | None", am_annotator),
+            cadd=cast("CaddAnnotator | None", cadd_annotator),
             high_value_rsids=hv_rsids,
         )
     finally:

{allelix-2.1.1 → allelix-2.1.2}/allelix/cli/utility.py

@@ -5,7 +5,7 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 import click
 from rich.table import Table
@@ -205,7 +205,7 @@ def _execute_tabix_extract(  # pragma: no cover
     wanted: set[str],
     sample: str | None,
     data_dir: Path | None,
-    pysam: object,
+    pysam: Any,  # noqa: ANN401 — pysam ships no type stubs
 ) -> dict[str, Variant] | None:
     """Real tabix execution.
 
@@ -443,7 +443,7 @@ def export_plink_cmd(
     coding when available; falls back to monomorphic (A2=0) for positions
     without gnomAD coverage.
     """
-    from allelix.exporters.plink import _orient_genotype, export_plink
+    from allelix.exporters.plink import export_plink, resolve_ref_alt_via_gnomad
 
     parser = _helpers._resolve_parser(file_path, fmt, sample=sample)
     prefix = output_prefix if output_prefix else file_path.with_suffix("")
@@ -462,45 +462,15 @@ def export_plink_cmd(
         key=lambda v: (chrom_order.get(v.chromosome, 99), v.chromosome, v.position),
     )
 
-    variant_by_rsid: dict[str, Variant] = {}
-    for v in variants:
-        if not v.is_no_call:
-            variant_by_rsid[v.rsid] = v
-    rsids = set(variant_by_rsid)
+    variant_by_rsid: dict[str, Variant] = {v.rsid: v for v in variants if not v.is_no_call}
 
-    ref_alt_map: dict[str, tuple[str, str]] = {}
-    gnomad = None
     try:
-        from allelix.annotators.gnomad import GnomadAnnotator
-
-        gnomad = GnomadAnnotator(resolved)
-        if gnomad.is_ready():
-            coord_map = gnomad.bulk_resolve_coordinates(rsids)
-            for rsid, coords in coord_map.items():
-                if len(coords) == 1:
-                    _, _, ref, alt = coords[0]
-                    ref_alt_map[rsid] = (ref, alt)
-                else:
-                    v = variant_by_rsid[rsid]
-                    pair = {v.allele1, v.allele2}
-                    for _, _, ref, alt in coords:
-                        if _orient_genotype(
-                            v.allele1, v.allele2, ref, alt
-                        ) is not None and pair <= {ref, alt}:
-                            ref_alt_map[rsid] = (ref, alt)
-                            break
-                    else:
-                        for _, _, ref, alt in coords:
-                            if _orient_genotype(v.allele1, v.allele2, ref, alt) is not None:
-                                ref_alt_map[rsid] = (ref, alt)
-                                break
+        ref_alt_map = resolve_ref_alt_via_gnomad(variant_by_rsid, resolved)
     except Exception:
         console.print(
             "[yellow]gnomAD coordinate resolution failed; using fallback allele coding.[/yellow]"
         )
-    finally:
-        if gnomad is not None:
-            gnomad.close()
+        ref_alt_map = {}
 
     written, skipped, indel_skip, mono = export_plink(
         iter(variants), prefix, effective_build, ref_alt_map or None

{allelix-2.1.1 → allelix-2.1.2}/allelix/config.py

@@ -15,6 +15,8 @@ from allelix.annotators.base import permission as check_permission
 if TYPE_CHECKING:
     from pathlib import Path
 
+    from allelix.annotators.base import Annotator
+
 logger = logging.getLogger(__name__)
 
 CONFIG_FILENAME = "config.toml"
@@ -46,7 +48,7 @@ class AllelixConfig:
     def is_enabled(
         self,
         source_name: str,
-        annotator_classes: dict[str, type] | None = None,
+        annotator_classes: dict[str, type[Annotator]] | None = None,
     ) -> bool:
         """Check if a source is enabled, respecting the permission ladder.
 

{allelix-2.1.1 → allelix-2.1.2}/allelix/databases/cpic_loader.py

@@ -211,8 +211,8 @@ def fetch_cpic_allele_functions(
 
     out: dict[tuple[str, str], str] = {}
     for row in location_values:
-        rsid = location_to_rsid.get(row.get("locationid"))
-        function_class = allele_to_function.get(row.get("alleledefinitionid"))
+        rsid = location_to_rsid.get(row.get("locationid"))  # type: ignore[arg-type]
+        function_class = allele_to_function.get(row.get("alleledefinitionid"))  # type: ignore[arg-type]
         base = (row.get("variantallele") or "").strip().upper()
         if not rsid or function_class is None:
             continue

{allelix-2.1.1 → allelix-2.1.2}/allelix/databases/gwas_loader.py

@@ -15,7 +15,7 @@ import os
 import re
 import sqlite3
 from datetime import UTC, datetime
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 from allelix.databases.schema import GWAS_SCHEMA
 
@@ -458,7 +458,7 @@ def iter_gwas_records(tsv_path: Path) -> Iterator[dict[str, object]]:
             if existing is None:
                 best[key] = record
             else:
-                ep = existing["p_value"]
+                ep = cast("float | None", existing["p_value"])
                 if p_value is not None and (ep is None or p_value < ep):
                     best[key] = record
 

{allelix-2.1.1 → allelix-2.1.2}/allelix/databases/snpedia_parser.py

@@ -61,8 +61,10 @@ def _parse_title_alleles(title: str) -> tuple[str, str] | None:
 
 def _tmpl_param(tmpl: object, name: str) -> str:
     """Extract a named parameter from a mwparserfromhell template."""
-    if tmpl.has(name):
-        return str(tmpl.get(name).value).strip()
+    # mwparserfromhell ships no type stubs (see [[tool.mypy.overrides]]); the
+    # parameter is typed as `object` at the boundary, then unwrapped here.
+    if tmpl.has(name):  # type: ignore[attr-defined]
+        return str(tmpl.get(name).value).strip()  # type: ignore[attr-defined]
     return ""
 
 
@@ -302,9 +304,9 @@ def _parse_raw_pages_inner(conn: sqlite3.Connection, *, verbose: bool = False) -
 
         repute = _tmpl_param(tmpl, "repute") or None
         summary = _tmpl_param(tmpl, "summary") or None
-        gene = gene_map.get(snp_id) or None
+        snp_gene = gene_map.get(snp_id) or None
 
-        batch.append((snp_id, allele1, allele2, magnitude, repute, summary, gene, scraped_at))
+        batch.append((snp_id, allele1, allele2, magnitude, repute, summary, snp_gene, scraped_at))
 
         if len(batch) >= 1000:
             conn.executemany(

{allelix-2.1.1 → allelix-2.1.2}/allelix/exporters/plink.py

@@ -9,7 +9,7 @@ from typing import TYPE_CHECKING
 from allelix.utils.allele import complement, is_strand_ambiguous
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Iterator, Mapping
     from pathlib import Path
 
     from allelix.models import Variant
@@ -132,6 +132,55 @@ def export_plink(
     return written, skipped, indels, monomorphic
 
 
+def resolve_ref_alt_via_gnomad(
+    variant_by_rsid: Mapping[str, Variant], data_dir: Path
+) -> dict[str, tuple[str, str]]:
+    """Return per-rsid (ref, alt) for PLINK A1/A2 coding via gnomAD.
+
+    For each rsid in ``variant_by_rsid``, looks up gnomAD's coordinate
+    record(s). When gnomAD returns a single record, that ref/alt pair is
+    used directly. When gnomAD returns multiple records (multi-allelic
+    positions), the user's allele pair is matched against each candidate
+    via ``_orient_genotype`` and the first match that's also a subset of
+    ``{ref, alt}`` wins; if none is a subset, the first orientation-valid
+    record wins as a fallback.
+
+    Returns an empty dict if gnomAD isn't ready. Raises on any underlying
+    lookup error — the CLI catches and prints the "failed" warning, then
+    proceeds with empty (monomorphic) coding.
+    """
+    from allelix.annotators.gnomad import GnomadAnnotator
+
+    gnomad = GnomadAnnotator(data_dir)
+    try:
+        if not gnomad.is_ready():
+            return {}
+        coord_map = gnomad.bulk_resolve_coordinates(set(variant_by_rsid))
+        result: dict[str, tuple[str, str]] = {}
+        for rsid, coords in coord_map.items():
+            if len(coords) == 1:
+                _, _, ref, alt = coords[0]
+                result[rsid] = (ref, alt)
+                continue
+            v = variant_by_rsid[rsid]
+            pair = {v.allele1, v.allele2}
+            for _, _, ref, alt in coords:
+                if _orient_genotype(v.allele1, v.allele2, ref, alt) is not None and pair <= {
+                    ref,
+                    alt,
+                }:
+                    result[rsid] = (ref, alt)
+                    break
+            else:
+                for _, _, ref, alt in coords:
+                    if _orient_genotype(v.allele1, v.allele2, ref, alt) is not None:
+                        result[rsid] = (ref, alt)
+                        break
+        return result
+    finally:
+        gnomad.close()
+
+
 def _fallback_coding(v: Variant) -> tuple[str, str, int, bool]:
     """Fallback allele coding when ref/alt is unknown.
 

{allelix-2.1.1 → allelix-2.1.2}/allelix/reports/_pipeline.py

@@ -17,7 +17,7 @@ from __future__ import annotations
 import contextlib
 import logging
 from dataclasses import dataclass, field, replace
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 from allelix.utils.build_detect import (
     BUILD_GRCH36,
@@ -35,6 +35,7 @@ if TYPE_CHECKING:
     from allelix.annotators.alphamissense import AlphaMissenseAnnotator
     from allelix.annotators.base import Annotator
     from allelix.annotators.cadd import CaddAnnotator
+    from allelix.annotators.clinvar import ClinVarAnnotator
     from allelix.annotators.gnomad import GnomadAnnotator
     from allelix.models import Annotation, Variant
     from allelix.parsers.base import GenotypeParser
@@ -293,9 +294,9 @@ def _enrich_cadd(
 
     for a in annotations:
         if a.alt:
-            coords = coord_map.get(a.rsid)
-            if coords:
-                a.cadd_phred = _lookup_user_allele(a.alt, coords, scores)
+            ann_coords = coord_map.get(a.rsid)
+            if ann_coords:
+                a.cadd_phred = _lookup_user_allele(a.alt, ann_coords, scores)
         elif resolved_coords and a.rsid in resolved_coords:
             # Position fallback: rsID was resolved on the fly via
             # ClinVar; the resolved tuple carries the user's actual
@@ -399,7 +400,9 @@ def run_analysis(
                 # rsID-indexed annotators. GH #8.
                 rsidless = [v for v in batch_buf if not v.rsid.startswith("rs")]
                 if rsidless:
-                    resolution = clinvar_resolver.bulk_resolve_rsids(rsidless)
+                    resolution = cast("ClinVarAnnotator", clinvar_resolver).bulk_resolve_rsids(
+                        rsidless
+                    )
                     for (chrom, pos, ref, alt), rsid in resolution.items():
                         resolved_coords[rsid] = (chrom, pos, ref, alt)
             # ADR-0035 PR 4: populate Variant.ref for array data via gnomAD's
@@ -600,6 +603,7 @@ class _BuildDetectionState:
         if variant.rsid in KNOWN_SNP_POSITIONS:
             result = detect_build(self._buffer)
             if result.is_confident:
+                assert result.build is not None  # is_confident ⇒ build set
                 self.detected = result.build
                 self.matched_count = result.matched
                 self.inspected_count = result.inspected
@@ -653,6 +657,7 @@ class _BuildDetectionState:
                 )
         self.matched_count = result.matched
         self.inspected_count = result.inspected
+        assert self.effective is not None  # all branches above set it
         out = [replace(v, build=self.effective) for v in self._buffer]
         self._buffer.clear()
         return out

{allelix-2.1.1 → allelix-2.1.2}/allelix.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: allelix
-Version: 2.1.1
+Version: 2.1.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>
@@ -29,35 +29,33 @@ Requires-Dist: pysam>=0.22; extra == "cadd"
 Provides-Extra: vcf-index
 Requires-Dist: pysam>=0.22; extra == "vcf-index"
 Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == "dev"
 Requires-Dist: pre-commit>=3.7; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov<8,>=7; extra == "dev"
 Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
 Dynamic: license-file
 
+<div align="center">
+
+<img src="https://allelix.io/apple-touch-icon.png" width="180" alt="Allelix" />
+
+**Open-source genotype analysis. Format-agnostic. Offline-first.**
+
+[Website](https://allelix.io) · [Quickstart](#quickstart) · [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md)
+
+[![python](https://img.shields.io/pypi/pyversions/allelix.svg)](https://www.python.org/downloads/)
+[![pypi](https://img.shields.io/pypi/v/allelix.svg)](https://pypi.org/project/allelix/)
+[![license](https://img.shields.io/pypi/l/allelix.svg)](LICENSE)
+[![CI](https://github.com/allelix/allelix/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/allelix/allelix/actions/workflows/ci.yml)
+[![privacy: local-first](https://img.shields.io/badge/privacy-local--first-success)](#privacy)
+
+</div>
+
 # Allelix
 
-Open-source command-line toolkit for analyzing raw genotype files from consumer DNA testing services. Format-agnostic ingestion, database-agnostic annotation, offline-first.
-
-> **Status:** Production — eight parser formats (including VCF + gVCF),
-> four annotators (ClinVar + ClinPGx + GWAS Catalog + SNPedia), three
-> enrichment sources (gnomAD population frequencies + AlphaMissense
-> pathogenicity + CADD deleteriousness), licensable-source gating for
-> commercial users, dual-build ClinVar caches (GRCh37 + GRCh38),
-> HTML/JSON/terminal reports, methylation + pharmacogenomics focused
-> commands, report diffing, persistent config with commercial-mode
-> safety switch. Build auto-detection from position data (ADR-0021).
-> No regex on prose anywhere in production. **Latest: v2.1.0** —
-> ADR-0035 'Cluster B' coordinated model change: `Variant.ref` carries
-> the forward-strand reference allele, per-Annotation `alt` threading
-> on GWAS / SNPedia / ClinPGx enables allele-specific gnomAD /
-> AlphaMissense / CADD enrichment on array inputs, structured GWAS
-> fields (`trait` / `p_value` / `phecode`) replace prose re-parsing in
-> the rollup, and ClinVar / ClinPGx carrier matching is strand-aware
-> with multi-allelic safety guard. JSON `schema_version` bumped 4 → 5
-> (additive, v4 readers unaffected).
-> Release notes:
-> [`CHANGELOG.md`](https://github.com/allelix/allelix/blob/main/CHANGELOG.md).
+> **Status:** Production. Eight parser formats (including VCF + gVCF), four annotators (ClinVar + ClinPGx + GWAS Catalog + SNPedia), three enrichment sources (gnomAD + AlphaMissense + CADD), licensable-source gating for commercial users, dual-build ClinVar caches (GRCh37 + GRCh38), HTML/JSON/terminal reports, methylation + pharmacogenomics focused commands, report diffing, persistent config with commercial-mode safety switch. Build auto-detection from position data (ADR-0021). No regex on prose anywhere in production. The [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md) tracks every release.
 
 ## Quickstart
 
@@ -101,16 +99,17 @@ See [Development](#development) for source installs and running tests, [Managing
 
 Adding a new format means adding one file to `allelix/parsers/` and registering an instance in the `PARSERS` list in `allelix/parsers/__init__.py`.
 
-### v2.1+ roadmap
+### Roadmap
 
-| Feature | Notes |
+| Release | Theme |
 |---|---|
-| Per-source scoring | Magnitude breakdown by database. Users see which source drove the composite score. |
-| Annotator-level strand awareness (R-1) | Strand-flip matching wired into every annotator's carrier check. Basic `compare` strand support shipped in v1.1; full annotator integration deferred from v2.0.0. |
-| Good / Bad / Neutral repute | Per-annotation repute field. Reframes the report from "here's what's wrong" to "here's your full picture." Requires Annotation model change + renderer updates. |
-| PLINK import | Read .bed/.bim/.fam as an input format (complement to the v1.7.0 export). |
-| PharmCAT integration | Wrap CPIC's PharmCAT as an optional external engine for star-allele / diplotype calling. Requires VCF input (shipped in v2.0.0). |
-| Genome Watchtower | Real-time variant monitoring via database delta feeds. Privacy-preserving: server publishes universal feed, matching happens locally against your deviation set. Replaces full re-analysis with millisecond set intersection. |
+| **v2.2** | Annotation model expansion (cross-source conflict surfacing, risk-allele display, structured MTAG flag), custom-panel UX improvements, methylation panel retune + citations, ClinVar source switch (VCF → `variant_summary.txt`), CLI cleanups (`db clean` / `db path`). |
+| **v2.3** | Per-source magnitude decomposition, Good / Bad / Neutral annotation repute, JSON v3 (AI-legible output contract), plausibility flagging via zygosity × gnomAD MAF, ClinVar review-status weighting, functional-medicine +/− notation. |
+| **v2.4** | ACMG/AMP automated classification engine, variant consequence annotation (VEP-equivalent). |
+| **v2.5+** | CNVs and repeat-expansion support, dbSNP resolution for rsID-less VCFs, gnomAD genomes (non-coding population frequencies), supplemental genotype file merging. |
+| **v3.0** | Ancestry estimation (PCA + 1KG/HGDP reference panels), Polygenic Risk Score (PRS) integration. |
+
+Issues and milestones are tracked at [github.com/allelix/allelix/issues](https://github.com/allelix/allelix/issues). Annotator-level strand-aware carrier matching (R-1) shipped in v2.1.0's ADR-0035 cluster.
 
 ## Supported Databases
 

{allelix-2.1.1 → allelix-2.1.2}/allelix.egg-info/requires.txt

@@ -7,10 +7,12 @@ rich>=13.7
 pysam>=0.22
 
 [dev]
+mypy>=1.11
 pre-commit>=3.7
 pytest>=8.0
 pytest-cov<8,>=7
 ruff>=0.6
+types-PyYAML>=6.0
 
 [vcf-index]
 pysam>=0.22

{allelix-2.1.1 → allelix-2.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "allelix"
-version = "2.1.1"
+version = "2.1.2"
 description = "Open-source genotype analysis toolkit. Format-agnostic ingestion, database-agnostic annotation, offline-first."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -36,10 +36,12 @@ vcf-index = [
     "pysam>=0.22",
 ]
 dev = [
+    "mypy>=1.11",
     "pre-commit>=3.7",
     "pytest>=8.0",
     "pytest-cov>=7,<8",
     "ruff>=0.6",
+    "types-PyYAML>=6.0",
 ]
 
 [project.scripts]
@@ -89,7 +91,7 @@ convention = "google"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-addopts = "-v --strict-markers --tb=short --cov=allelix --cov-report=term-missing --cov-fail-under=92"
+addopts = "-v --strict-markers --tb=short --cov=allelix --cov-branch --cov-report=term-missing --cov-fail-under=92"
 markers = [
     "slow: marks tests that download databases or process large files",
     "integration: marks end-to-end pipeline tests",
@@ -99,6 +101,39 @@ filterwarnings = [
     "error::pytest.PytestUnraisableExceptionWarning",
 ]
 
+# GH allelix-dev #31: coverage gate now measures BOTH line and branch
+# coverage. Pre-#31 the gate was line-only — a line counted as covered
+# the moment any input crossed it, which is how the v2.0.x carrier-match
+# case/strand and download-truncation correctness bugs shipped green.
+# The 92% floor is calibrated against the branch metric (currently 92.44%
+# with branch coverage enabled); primary annotators sit at 95%+. Raise
+# the floor when new tests close documented missing branches; do not
+# lower it.
+[tool.coverage.run]
+branch = true
+
 [tool.coverage.report]
 precision = 2
 fail_under = 92.00
+
+# GH allelix-dev #33: backs the py.typed promise with a real type checker.
+# The starting baseline is intentionally permissive (no strict mode, no
+# disallow_untyped_defs) so we get the gate in CI immediately instead of
+# negotiating dozens of remediation PRs. Ratchet later by tightening the
+# global flags one at a time and chasing the new errors.
+[tool.mypy]
+python_version = "3.11"
+check_untyped_defs = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_unreachable = true
+no_implicit_optional = true
+# Don't enforce on tests — ruff's per-file-ignores already exempt tests
+# from ANN, and unit-test fixtures use a lot of pytest magic that mypy
+# would flag without strict-mode benefit.
+exclude = ["tests/", "scripts/"]
+
+# Third-party libraries without published type stubs.
+[[tool.mypy.overrides]]
+module = ["pysam", "mwparserfromhell.*"]
+ignore_missing_imports = true