allelix 2.0.1__tar.gz → 2.1.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: allelix
-Version: 2.0.1
+Version: 2.1.0
 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.1.0}/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.1.0/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.1.0}/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.1.0}/allelix/annotators/clinvar.py

@@ -30,6 +30,7 @@ from allelix.databases.manager import (
     verify_file_hash,
 )
 from allelix.models import Annotation
+from allelix.utils.allele import strand_aware_carrier_match
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Iterator
@@ -384,7 +385,6 @@ class ClinVarAnnotator(Annotator):
             (variant.rsid,),
         ).fetchall()
         annotations: list[Annotation] = []
-        carrier_alleles = {variant.allele1, variant.allele2}
         user_is_multibase = len(variant.allele1) > 1 or len(variant.allele2) > 1
         # ADR-0023: report the user's actual diploid call consistently
         # across annotators, not the matched ALT base alone.
@@ -404,7 +404,14 @@ class ClinVarAnnotator(Annotator):
             clinvar_is_indel = len(ref) > 1 or len(alt) > 1
             if clinvar_is_indel and not user_is_multibase:
                 continue
-            if alt not in carrier_alleles:
+            # ADR-0035 PR 4: strand-aware carrier match. Direct {ref, alt}
+            # membership still covers forward-stranded inputs; the
+            # complement-fallback path fires only when Variant.ref confirms
+            # reverse orientation AND the site isn't palindromic — preserving
+            # the v2.0.1 #18 multi-allelic safety invariant.
+            if not strand_aware_carrier_match(
+                variant.ref, variant.allele1, variant.allele2, ref, alt
+            ):
                 continue
             sig_label = _normalize_clnsig(clnsig) if clnsig else "unknown"
             if not self._include_benign and sig_label in _BENIGN_CLNSIGS:
@@ -562,7 +569,6 @@ class ClinVarAnnotator(Annotator):
             rows = rows_by_build_rsid.get((variant.build, variant.rsid))
             if not rows:
                 continue
-            carrier_alleles = {variant.allele1, variant.allele2}
             user_is_multibase = len(variant.allele1) > 1 or len(variant.allele2) > 1
             user_diploid = _user_diploid(variant)
             for row in rows:
@@ -580,7 +586,11 @@ class ClinVarAnnotator(Annotator):
                 clinvar_is_indel = len(ref) > 1 or len(alt) > 1
                 if clinvar_is_indel and not user_is_multibase:
                     continue
-                if alt not in carrier_alleles:
+                # ADR-0035 PR 4: strand-aware carrier match. See annotate() for
+                # the safety rationale (#18 multi-allelic invariant preserved).
+                if not strand_aware_carrier_match(
+                    variant.ref, variant.allele1, variant.allele2, ref, alt
+                ):
                     continue
                 sig_label = _normalize_clnsig(clnsig) if clnsig else "unknown"
                 if not self._include_benign and sig_label in _BENIGN_CLNSIGS:

{allelix-2.0.1 → allelix-2.1.0}/allelix/annotators/gwas.py

@@ -6,6 +6,7 @@ from __future__ import annotations
 
 import contextlib
 import logging
+import re
 import sqlite3
 import zipfile
 from typing import TYPE_CHECKING, ClassVar
@@ -56,6 +57,27 @@ logger = logging.getLogger(__name__)
 
 _BATCH_CHUNK = 500  # SQLite default SQLITE_MAX_VARIABLE_NUMBER is 999
 
+# ADR-0035 PR 3: PheCode often arrives embedded in the upstream DISEASE/TRAIT
+# field (e.g. ``"Type 2 diabetes (PheCode 250.2)"``). The annotator extracts it
+# at the boundary so downstream code reads ``Annotation.phecode`` as a
+# structured field instead of regex-parsing prose. The trimmed trait flows into
+# ``Annotation.trait``; ``description`` is rebuilt below from the structured
+# parts so display surfaces still show the PheCode label.
+_PHECODE_SUFFIX_RE = re.compile(r"\s*\(PheCode\s+([\d.]+)\)\s*$")
+
+
+def _split_trait_and_phecode(raw_trait: str) -> tuple[str, str]:
+    """Split an upstream trait into (clean_trait, phecode).
+
+    PheCode (when present) is returned as a bare numeric string like
+    ``"250.2"``. Returns ``""`` for phecode when no PheCode suffix is found.
+    The clean trait is stripped of trailing whitespace.
+    """
+    m = _PHECODE_SUFFIX_RE.search(raw_trait)
+    if m is None:
+        return raw_trait.strip(), ""
+    return raw_trait[: m.start()].rstrip(), m.group(1)
+
 
 def _magnitude(p_value: float | None, or_beta: float | None) -> float:
     """Derive magnitude from p-value and optional effect size.
@@ -288,9 +310,14 @@ class GWASCatalogAnnotator(Annotator):
                 mag = min(_magnitude(p_value, or_beta), _UNKNOWN_RISK_ALLELE_MAG_CAP)
                 risk_note = " (risk allele not specified in study)"
 
+            clean_trait, phecode = _split_trait_and_phecode(trait)
+            phecode_suffix = f" (PheCode {phecode})" if phecode else ""
             p_str = f"p={p_value:.1e}" if p_value is not None else "p=N/A"
             gene_str = gene or "—"
-            description = f"GWAS Catalog: {trait} ({p_str}, gene: {gene_str}){risk_note}"
+            description = (
+                f"GWAS Catalog: {clean_trait}{phecode_suffix} "
+                f"({p_str}, gene: {gene_str}){risk_note}"
+            )
 
             references: list[str] = []
             if pubmed_id:
@@ -309,10 +336,13 @@ class GWASCatalogAnnotator(Annotator):
                     attribution=self.attribution,
                     genotype_match=user_diploid,
                     references=references,
-                    condition=trait,
+                    condition=clean_trait,
                     gene=gene or "",
-                    alt="",
+                    alt=risk_allele or "",
                     is_must_include=variant.rsid in _MUST_INCLUDE_RSIDS,
+                    trait=clean_trait,
+                    p_value=p_value,
+                    phecode=phecode,
                 )
             )
         return annotations
@@ -377,9 +407,14 @@ class GWASCatalogAnnotator(Annotator):
                     mag = min(_magnitude(p_value, or_beta), _UNKNOWN_RISK_ALLELE_MAG_CAP)
                     risk_note = " (risk allele not specified in study)"
 
+                clean_trait, phecode = _split_trait_and_phecode(trait)
+                phecode_suffix = f" (PheCode {phecode})" if phecode else ""
                 p_str = f"p={p_value:.1e}" if p_value is not None else "p=N/A"
                 gene_str = gene or "—"
-                description = f"GWAS Catalog: {trait} ({p_str}, gene: {gene_str}){risk_note}"
+                description = (
+                    f"GWAS Catalog: {clean_trait}{phecode_suffix} "
+                    f"({p_str}, gene: {gene_str}){risk_note}"
+                )
 
                 references: list[str] = []
                 if pubmed_id:
@@ -397,10 +432,13 @@ class GWASCatalogAnnotator(Annotator):
                     attribution=self.attribution,
                     genotype_match=user_diploid,
                     references=references,
-                    condition=trait,
+                    condition=clean_trait,
                     gene=gene or "",
-                    alt="",
+                    alt=risk_allele or "",
                     is_must_include=variant.rsid in _MUST_INCLUDE_RSIDS,
+                    trait=clean_trait,
+                    p_value=p_value,
+                    phecode=phecode,
                 )
 
 

{allelix-2.0.1 → allelix-2.1.0}/allelix/annotators/pharmgkb.py

@@ -30,6 +30,7 @@ from allelix.databases.pharmgkb_loader import (
     schema_is_current,
 )
 from allelix.models import Annotation
+from allelix.utils.allele import derive_alt_from_diploid, strand_aware_genotype_match
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator
@@ -260,20 +261,25 @@ class PharmGKBAnnotator(Annotator):
         if is_clinvar_homref(variant, self._clinvar_ref_provider):
             return []
 
+        # ADR-0035 PR 4: fetch all rows for the rsid (typically <5) and apply
+        # strand-aware genotype match in Python. Forward-stranded users hit
+        # the same set of rows as the v0.7-era ``WHERE genotype = ?`` SQL;
+        # reverse-stranded users now also match when Variant.ref confirms
+        # orientation AND the source genotype is non-palindromic.
         sql = (
             "SELECT genotype, gene, drugs, phenotype, phenotype_category, "
             "annotation_text, level_of_evidence, score, pgkb_annotation_id "
             "FROM pharmgkb_annotations "
-            "WHERE rsid = ? AND genotype = ? AND is_nonfinding = 0"
+            "WHERE rsid = ? AND is_nonfinding = 0"
         )
-        params = (variant.rsid, user_geno)
+        params = (variant.rsid,)
 
         rows = self._connection().execute(sql, params).fetchall()
         annotations: list[Annotation] = []
         user_diploid = _user_diploid(variant)
         for row in rows:
             (
-                _geno,
+                geno,
                 gene,
                 drugs,
                 phenotype,
@@ -283,6 +289,10 @@ class PharmGKBAnnotator(Annotator):
                 _score,
                 pgkb_annotation_id,
             ) = row
+            if not strand_aware_genotype_match(
+                variant.allele1, variant.allele2, geno, variant.ref
+            ):
+                continue
             sig_label = level_of_evidence.strip().lower() or "unknown"
             description_parts = [f"ClinPGx: {drugs}"] if drugs else ["ClinPGx"]
             if phenotype:
@@ -306,6 +316,7 @@ class PharmGKBAnnotator(Annotator):
                     references=references,
                     condition=phenotype or "",
                     gene=gene or "",
+                    alt=derive_alt_from_diploid(variant.ref, variant.allele1, variant.allele2),
                 )
             )
         return annotations
@@ -352,7 +363,7 @@ class PharmGKBAnnotator(Annotator):
             for row in cursor:
                 rows_by_rsid.setdefault(row[0], []).append(row[1:])
 
-        for variant, user_geno in candidates:
+        for variant, _user_geno in candidates:
             rows = rows_by_rsid.get(variant.rsid)
             if not rows:
                 continue
@@ -369,7 +380,11 @@ class PharmGKBAnnotator(Annotator):
                     _score,
                     pgkb_annotation_id,
                 ) = row
-                if geno != user_geno:
+                # ADR-0035 PR 4: strand-aware genotype match. See annotate() for
+                # the safety rationale (palindrome guard + variant.ref orientation).
+                if not strand_aware_genotype_match(
+                    variant.allele1, variant.allele2, geno, variant.ref
+                ):
                     continue
                 sig_label = level_of_evidence.strip().lower() or "unknown"
                 description_parts = [f"ClinPGx: {drugs}"] if drugs else ["ClinPGx"]
@@ -393,6 +408,7 @@ class PharmGKBAnnotator(Annotator):
                     references=references,
                     condition=phenotype or "",
                     gene=gene or "",
+                    alt=derive_alt_from_diploid(variant.ref, variant.allele1, variant.allele2),
                 )
 
 

{allelix-2.0.1 → allelix-2.1.0}/allelix/annotators/snpedia.py

@@ -29,6 +29,7 @@ from allelix.databases.snpedia_loader import (
     install_prebuilt_cache,
 )
 from allelix.models import Annotation
+from allelix.utils.allele import derive_alt_from_diploid
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator
@@ -272,6 +273,7 @@ class SNPediaAnnotator(Annotator):
                     genotype_match=genotype_match,
                     references=[f"https://www.snpedia.com/index.php/{snp_url_path}"],
                     gene=gene or "",
+                    alt=derive_alt_from_diploid(variant.ref, allele1, allele2),
                 )
             )
 
@@ -356,4 +358,5 @@ class SNPediaAnnotator(Annotator):
                     genotype_match=genotype_match,
                     references=[f"https://www.snpedia.com/index.php/{snp_url_path}"],
                     gene=gene or "",
+                    alt=derive_alt_from_diploid(variant.ref, allele1, allele2),
                 )

{allelix-2.0.1 → allelix-2.1.0}/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.1.0/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.1.0}/allelix/models.py

@@ -31,6 +31,13 @@ class Variant:
         allele1: First observed allele. A/T/G/C, multi-base for indels, or "-" for no-call.
         allele2: Second observed allele. Same encoding as allele1.
         build: Reference genome build. "GRCh37" (hg19) or "GRCh38" (hg38).
+        ref: Reference allele on the forward strand at this position, when
+            known. VCF parsers populate from the REF column; array parsers
+            currently leave it None. Required by strand-aware carrier matching
+            (ADR-0035) and downstream consumers that need to identify the risk
+            allele within the user's pair. None means "cannot resolve" —
+            consumers degrade gracefully (return ambiguous, skip strand check,
+            etc.) rather than guess.
     """
 
     rsid: str
@@ -39,9 +46,10 @@ class Variant:
     allele1: str
     allele2: str
     build: str = DEFAULT_BUILD
+    ref: str | None = None
 
     def __post_init__(self) -> None:
-        """Normalize allele case at construction (GH #14).
+        """Normalize allele case at construction (GH #14, ADR-0035).
 
         Reference databases (ClinVar, gnomAD, ClinPGx, etc.) all ship
         uppercase alleles, and carrier matching is raw set membership
@@ -53,11 +61,20 @@ class Variant:
         at the model boundary so the invariant is impossible to
         violate downstream. The no-call marker is left as-is;
         multi-base alleles (indels) are uppercased in place.
+
+        ``ref`` (ADR-0035) is a sibling allele field feeding the same
+        downstream matching path (PR 4 strand-aware carrier matching
+        compares ``ref`` against ``{allele1, allele2}`` and against
+        gnomAD's uppercased REF). VCFs derived from soft-masked
+        references emit lowercase bases in the REF column, so the
+        same normalization applies here for the same reason.
         """
         if self.allele1 and self.allele1 != NO_CALL_MARKER:
             self.allele1 = self.allele1.upper()
         if self.allele2 and self.allele2 != NO_CALL_MARKER:
             self.allele2 = self.allele2.upper()
+        if self.ref is not None and self.ref != NO_CALL_MARKER:
+            self.ref = self.ref.upper()
 
     @property
     def is_heterozygous(self) -> bool:
@@ -126,6 +143,15 @@ class Annotation:
     am_pathogenicity: float | None = None
     am_class: str = ""
     cadd_phred: float | None = None
+    # ADR-0035 cluster manifest (PR 3): structured GWAS fields promoted out of
+    # the rendered ``description`` prose. `description` still carries the same
+    # rendered text for HTML / terminal display, but downstream code (rollup,
+    # diff, future consumers) reads the structured fields directly instead of
+    # regex-parsing prose. Populated by the GWAS annotator; empty / None on
+    # non-GWAS rows.
+    trait: str = ""
+    p_value: float | None = None
+    phecode: str = ""
 
     @property
     def zygosity(self) -> str:

{allelix-2.0.1 → allelix-2.1.0}/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):