ferro-hgvs 0.8.1

//! Python bindings for ferro-hgvs using PyO3
//!
//! This module provides Python bindings for the HGVS parser and normalizer.
//! Enable with the `python` feature flag.

use pyo3::exceptions::{PyRuntimeError, PyUserWarning, PyValueError};
use pyo3::prelude::*;
use pyo3::types::PyDict;
use std::collections::hash_map::DefaultHasher;
use std::hash::{Hash, Hasher};
use std::path::Path;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;

use crate::backtranslate::{Backtranslator, CodonChange, CodonTable};
use crate::batch::{BatchProcessor, BatchProgress, BatchResult};
use crate::convert::CoordinateMapper;
use crate::coords::{OneBasedPos, ZeroBasedPos};
use crate::effect::{Consequence, EffectPredictor, Impact, ProteinEffect};
use crate::equivalence::{EquivalenceChecker, EquivalenceLevel, EquivalenceResult};
use crate::error_handling::{
    ferro_to_mutalyzer, CorrectionWarning, ErrorConfig, ErrorMode, ErrorOverride, ErrorType,
};
use crate::hgvs::location::{AminoAcid, CdsPos, TxPos};
use crate::hgvs::variant::HgvsVariant;
use crate::mave::{is_mave_short_form, parse_mave_hgvs, MaveContext};
use crate::normalize::ShuffleDirection;
use crate::prepare::{check_references, prepare_references, PrepareConfig, ReferenceManifest};
use crate::python_helpers::{
    get_indel_length, get_num_variants, get_substitution_bases, get_variant_edit_type,
    get_variant_end, get_variant_offset, get_variant_reference, get_variant_start, is_frameshift,
    is_identity, parse_direction, variant_type_str,
};
use crate::reference::provider::ReferenceProvider;
use crate::reference::transcript::{GenomeBuild, Strand};
use crate::reference::{JsonProvider, MultiFastaProvider};
use crate::rsid::{format_rsid, parse_rsid as rust_parse_rsid, InMemoryRsIdLookup, RsIdResult};
use crate::spdi::{hgvs_to_spdi_simple, parse_spdi as rust_parse_spdi, spdi_to_hgvs, SpdiVariant};
use crate::vcf::{vcf_to_genomic_hgvs as rust_vcf_to_hgvs, VcfRecord};
use crate::{parse_hgvs, NormalizeConfig, Normalizer};

// ---------------------------------------------------------------------------
// Typed exception hierarchy
//
// Every ferro variant-processing failure surfaces as `ferro_hgvs.FerroError` or
// one of its subclasses (`ParseError`, `NormalizationError`, `ReferenceDataError`,
// `ProjectionError`) instead of a bare `ValueError`/`RuntimeError`. Each
// instance carries a structured `code` attribute (the `E####`/`W####` string,
// or `None`) and a `mutalyzer_codes` tuple of equivalent mutalyzer diagnostic
// codes, both lifted from the underlying `crate::error::FerroError`.
//
// The classes themselves are defined in `python/ferro_hgvs/__init__.py`, not
// here: each subclass multiply-inherits the built-in exception its call sites
// historically raised (`ParseError(FerroError, ValueError)`,
// `NormalizationError(FerroError, RuntimeError)`, and so on), so existing
// `except ValueError` / `except RuntimeError` callers keep working. PyO3's
// `create_exception!` only supports a single base and cannot express that, so
// the helpers below look the class up on the `ferro_hgvs` module and construct
// it, passing `(message, code, mutalyzer_codes)` to its `__init__`.
//
// Pure argument-validation failures (empty string, out-of-range index,
// unrecognized enum spelling) stay `ValueError` — they are programming errors,
// not variant-processing failures, and are intentionally outside the hierarchy.
// ---------------------------------------------------------------------------

/// Build a typed ferro exception of the named class (one of `FerroError`,
/// `ParseError`, `NormalizationError`, `ReferenceDataError`, `ProjectionError`),
/// carrying the structured `code` and `mutalyzer_codes`, wrapped as a `PyErr`.
///
/// The class is resolved on the already-imported `ferro_hgvs` module and
/// constructed via `__init__(message, code, mutalyzer_codes)`. The GIL is
/// acquired via [`Python::attach`] rather than threaded through every boundary
/// function: these helpers are only ever reached from a Python call that
/// already holds the GIL, so the attach is a cheap re-entrant no-op and keeps
/// the ~50 error sites to a single-line closure each. Building the typed class
/// should never fail at runtime (the `ferro_hgvs` module is always importable
/// when Python is calling in); if it somehow does, the original diagnostic is
/// preserved as a plain `RuntimeError` rather than being replaced by an opaque
/// `ImportError`/`AttributeError`.
fn ferro_exception(
    class: &str,
    message: String,
    code: Option<String>,
    mutalyzer_codes: &[&str],
) -> PyErr {
    Python::attach(|py| {
        let fallback = message.clone();
        match py
            .import("ferro_hgvs")
            .and_then(|module| module.getattr(class))
            .and_then(|cls| cls.call1((message, code, mutalyzer_codes)))
        {
            Ok(instance) => PyErr::from_value(instance),
            Err(_) => PyRuntimeError::new_err(fallback),
        }
    })
}

/// Map a [`crate::error::FerroError`] to a typed Python exception of the named
/// class, lifting the error's structured `code` and mutalyzer codes onto it.
fn ferro_typed(class: &str, message: String, err: &crate::error::FerroError) -> PyErr {
    ferro_exception(
        class,
        message,
        err.code().map(|c| c.as_str()),
        ferro_to_mutalyzer(err),
    )
}

/// Wrap the projector's raw projections for one input into the Python-facing
/// `PyVariantProjection` newtypes. Shared by both batch entry points.
fn wrap_projections(
    projections: Vec<crate::project::VariantProjection>,
) -> Vec<PyVariantProjection> {
    projections
        .into_iter()
        .map(|inner| PyVariantProjection { inner })
        .collect()
}

/// Turn a `(input_index, error)` pair into the batch's `ProjectionError`, whose
/// message pinpoints the failing entry via an `input[i]:` prefix.
fn projection_error_at(i: usize, e: &crate::error::FerroError) -> PyErr {
    ferro_typed(
        "ProjectionError",
        format!("Projection error at input[{i}]: {e}"),
        e,
    )
}

/// Convert a list of per-input projection lists into the Python return value —
/// a `list[list[VariantProjection]]`.
fn projections_to_pylist(
    py: Python<'_>,
    outer: Vec<Vec<PyVariantProjection>>,
) -> PyResult<Vec<Py<PyAny>>> {
    outer
        .into_iter()
        .map(|projections| Ok(projections.into_pyobject(py)?.into_any().unbind()))
        .collect()
}

/// Assemble the output for isolation mode (`return_exceptions == true`): never
/// raises. Each element is, per input and in order, either that input's
/// `list[VariantProjection]` or the `ProjectionError` instance describing its
/// failure, so one bad input can no longer discard results for the rest.
fn build_isolated_batch(
    py: Python<'_>,
    raw: Vec<Result<Vec<PyVariantProjection>, (usize, crate::error::FerroError)>>,
) -> PyResult<Vec<Py<PyAny>>> {
    let mut out = Vec::with_capacity(raw.len());
    for item in raw {
        match item {
            Ok(projections) => out.push(projections.into_pyobject(py)?.into_any().unbind()),
            Err((i, e)) => out.push(projection_error_at(i, &e).into_value(py).into_any()),
        }
    }
    Ok(out)
}

/// Validate a shuffle-direction argument at the Python boundary.
///
/// Mirrors the `assembly` argument's validate-and-raise pattern: an unrecognized
/// spelling raises `ValueError` naming the accepted values instead of silently
/// defaulting to 3' (#1016).
fn parse_direction_or_raise(direction: &str) -> PyResult<ShuffleDirection> {
    parse_direction(direction).ok_or_else(|| {
        PyValueError::new_err(format!(
            "unrecognized direction {direction:?}; expected one of \"3prime\", \"5prime\", \
             \"3\", \"5\", \"3'\", \"5'\" (case-insensitive)"
        ))
    })
}

/// Reference provider used by the Python wrappers.
///
/// `MultiFasta` is wrapped in `Arc` because `MultiFastaProvider` is large and
/// is cloned on every Python call to construct a fresh `Normalizer<P>`.
///
/// `Mock` is boxed because `JsonProvider` is itself large (it owns the test
/// reference maps); without the box this variant dwarfs the 8-byte `Arc`
/// `MultiFasta` variant and trips `clippy::large_enum_variant`.
#[derive(Clone)]
enum PyProvider {
    Mock(Box<JsonProvider>),
    MultiFasta(Arc<MultiFastaProvider>),
}

impl ReferenceProvider for PyProvider {
    fn get_transcript(
        &self,
        id: &str,
    ) -> Result<Arc<crate::reference::transcript::Transcript>, crate::error::FerroError> {
        match self {
            PyProvider::Mock(p) => p.get_transcript(id),
            PyProvider::MultiFasta(p) => p.get_transcript(id),
        }
    }

    fn get_sequence(
        &self,
        id: &str,
        start: u64,
        end: u64,
    ) -> Result<String, crate::error::FerroError> {
        match self {
            PyProvider::Mock(p) => p.get_sequence(id, start, end),
            PyProvider::MultiFasta(p) => p.get_sequence(id, start, end),
        }
    }

    fn get_genomic_sequence(
        &self,
        contig: &str,
        start: u64,
        end: u64,
    ) -> Result<String, crate::error::FerroError> {
        match self {
            PyProvider::Mock(p) => p.get_genomic_sequence(contig, start, end),
            PyProvider::MultiFasta(p) => p.get_genomic_sequence(contig, start, end),
        }
    }

    fn has_genomic_data(&self) -> bool {
        match self {
            PyProvider::Mock(p) => p.has_genomic_data(),
            PyProvider::MultiFasta(p) => p.has_genomic_data(),
        }
    }

    fn get_protein_sequence(
        &self,
        accession: &str,
        start: u64,
        end: u64,
    ) -> Result<String, crate::error::FerroError> {
        match self {
            PyProvider::Mock(p) => p.get_protein_sequence(accession, start, end),
            PyProvider::MultiFasta(p) => p.get_protein_sequence(accession, start, end),
        }
    }

    fn has_protein_data(&self) -> bool {
        match self {
            PyProvider::Mock(p) => p.has_protein_data(),
            PyProvider::MultiFasta(p) => p.has_protein_data(),
        }
    }

    fn has_transcript_version_exact(&self, id: &str) -> bool {
        // Forward to the inner provider so the protein version-exact gate (#505)
        // is enforced on the Python path; otherwise this falls through to the
        // trait default `true` and the gate is inert for Python consumers.
        match self {
            PyProvider::Mock(p) => p.has_transcript_version_exact(id),
            PyProvider::MultiFasta(p) => p.has_transcript_version_exact(id),
        }
    }

    fn genomic_placement(
        &self,
        parent: &crate::hgvs::variant::Accession,
    ) -> Option<crate::reference::GenomicPlacement> {
        // Forward to the inner provider so NG_/LRG_ parent re-anchoring (#480)
        // works on the Python path; the trait default `None` would otherwise
        // silently disable it for Python consumers.
        match self {
            PyProvider::Mock(p) => p.genomic_placement(parent),
            PyProvider::MultiFasta(p) => p.genomic_placement(parent),
        }
    }

    fn genomic_placement_on_build(
        &self,
        parent: &crate::hgvs::variant::Accession,
        build: Option<&str>,
    ) -> Option<crate::reference::GenomicPlacement> {
        // Forward the build hint to the inner provider so per-build placement
        // selection survives the PyProvider wrapper, matching the Arc/Box impls.
        match self {
            PyProvider::Mock(p) => p.genomic_placement_on_build(parent, build),
            PyProvider::MultiFasta(p) => p.genomic_placement_on_build(parent, build),
        }
    }

    fn resolve_legacy_gene_selector(
        &self,
        selector: &str,
        ng_parent: Option<&crate::hgvs::variant::Accession>,
    ) -> Option<String> {
        // Forward to the inner provider so legacy gene-symbol selector
        // resolution (#500/#792) reaches the Python path; the trait default
        // `None` would otherwise leave `NG_(GENE):c.` selectors unresolved for
        // Python consumers even when the wrapped provider can resolve them.
        match self {
            PyProvider::Mock(p) => p.resolve_legacy_gene_selector(selector, ng_parent),
            PyProvider::MultiFasta(p) => p.resolve_legacy_gene_selector(selector, ng_parent),
        }
    }

    fn sole_hosted_transcript(
        &self,
        ng_parent: &crate::hgvs::variant::Accession,
    ) -> Option<String> {
        // Forward to the inner provider so bare-`NG_` selector synthesis (#923)
        // reaches the Python path; the trait default `None` would otherwise
        // disable it for Python consumers even when the wrapped provider hosts
        // an unambiguous transcript for the parent.
        match self {
            PyProvider::Mock(p) => p.sole_hosted_transcript(ng_parent),
            PyProvider::MultiFasta(p) => p.sole_hosted_transcript(ng_parent),
        }
    }

    fn get_sequence_length(&self, id: &str) -> Result<u64, crate::error::FerroError> {
        // Forward to the inner provider so the real transcript/contig length
        // reaches the Python path (#968). The trait default returns
        // `Err(ReferenceNotFound)` unconditionally, so without this every
        // length-dependent path on the Python side (mt/`qter` bounds checks,
        // poly-A tail extension in projection) silently degrades even when the
        // wrapped `MultiFasta` provider knows the length.
        match self {
            PyProvider::Mock(p) => p.get_sequence_length(id),
            PyProvider::MultiFasta(p) => p.get_sequence_length(id),
        }
    }

    fn infer_genome_build(
        &self,
        accession: &crate::hgvs::variant::Accession,
    ) -> Option<&'static str> {
        // Forward to the inner provider so its build inference reaches the Python
        // path (#968). The trait default infers from the accession alone; the
        // wrapped `MultiFasta` provider layers in assembly-report contig aliases,
        // which the default would otherwise bypass for Python consumers.
        match self {
            PyProvider::Mock(p) => p.infer_genome_build(accession),
            PyProvider::MultiFasta(p) => p.infer_genome_build(accession),
        }
    }

    fn get_transcript_for_accession(
        &self,
        accession: &crate::hgvs::variant::Accession,
    ) -> Result<Arc<crate::reference::transcript::Transcript>, crate::error::FerroError> {
        // Forward to the inner provider so build-aware transcript resolution
        // (#332) reaches the Python path (#968). The trait default self-dispatches
        // to the build-*unaware* `get_transcript`, so without this a Python
        // consumer resolving a transcript for an `NC_*.10/.11`- or `NG_`-contexted
        // variant would bypass the wrapped `MultiFasta` provider's parent-build
        // probe and get the primary-build (or wrong-build) transcript.
        match self {
            PyProvider::Mock(p) => p.get_transcript_for_accession(accession),
            PyProvider::MultiFasta(p) => p.get_transcript_for_accession(accession),
        }
    }

    fn get_transcript_for_variant(
        &self,
        variant: &crate::hgvs::variant::HgvsVariant,
    ) -> Result<Arc<crate::reference::transcript::Transcript>, crate::error::FerroError> {
        // Forward to the inner provider so the by-variant build-aware resolution
        // (#332) reaches the Python path (#968), matching `get_transcript_for_accession`.
        match self {
            PyProvider::Mock(p) => p.get_transcript_for_variant(variant),
            PyProvider::MultiFasta(p) => p.get_transcript_for_variant(variant),
        }
    }
}

impl PyProvider {
    /// Load from a JSON file (delegates to JsonProvider::from_json).
    fn from_json(path: &Path) -> PyResult<Self> {
        JsonProvider::from_json(path)
            .map(|p| PyProvider::Mock(Box::new(p)))
            .map_err(|e| {
                ferro_typed(
                    "ReferenceDataError",
                    format!("Failed to load reference: {e}"),
                    &e,
                )
            })
    }

    /// Load from a manifest file (delegates to MultiFastaProvider::from_manifest).
    fn from_manifest(path: &Path) -> PyResult<Self> {
        MultiFastaProvider::from_manifest(path)
            .map(|p| PyProvider::MultiFasta(Arc::new(p)))
            .map_err(|e| {
                ferro_typed(
                    "ReferenceDataError",
                    format!("Failed to load manifest: {e}"),
                    &e,
                )
            })
    }

    /// Default: built-in test data.
    fn test_data() -> Self {
        PyProvider::Mock(Box::new(JsonProvider::with_test_data()))
    }

    /// Build / extract a CdotMapper for this provider.
    fn cdot_mapper(&self) -> crate::data::cdot::CdotMapper {
        match self {
            PyProvider::Mock(p) => {
                crate::data::cdot::CdotMapper::from_transcripts(p.all_transcripts())
            }
            PyProvider::MultiFasta(p) => p
                .cdot_mapper()
                .cloned()
                .unwrap_or_else(crate::data::cdot::CdotMapper::new),
        }
    }
}

/// Parse an HGVS variant string
///
/// Args:
///     hgvs_string: The HGVS variant description to parse
///
/// Returns:
///     A PyHgvsVariant object representing the parsed variant
///
/// Raises:
///     ValueError: If the HGVS string cannot be parsed
#[pyfunction]
fn parse(hgvs_string: &str) -> PyResult<PyHgvsVariant> {
    match parse_hgvs(hgvs_string) {
        Ok(variant) => Ok(PyHgvsVariant { inner: variant }),
        Err(e) => Err(ferro_typed("ParseError", format!("Parse error: {e}"), &e)),
    }
}

/// Normalize an HGVS variant string
///
/// **WARNING**: This function uses built-in test data for reference sequences.
/// For production use, create a Normalizer instance with your reference data.
///
/// Args:
///     hgvs_string: The HGVS variant description to normalize
///     direction: Shuffle direction - "3prime" (default) or "5prime"
///
/// Returns:
///     The normalized HGVS string
///
/// Raises:
///     ValueError: If the HGVS string cannot be parsed
///     RuntimeError: If normalization fails
#[pyfunction]
#[pyo3(signature = (hgvs_string, direction="3prime"))]
fn normalize(py: Python<'_>, hgvs_string: &str, direction: &str) -> PyResult<String> {
    let variant = parse_hgvs(hgvs_string)
        .map_err(|e| ferro_typed("ParseError", format!("Parse error: {e}"), &e))?;

    let config = NormalizeConfig::default().with_direction(parse_direction_or_raise(direction)?);
    // Note: Uses built-in test data. For production use, create a Normalizer with reference_json.
    let provider = JsonProvider::with_test_data();
    // This free function always uses genome-less test data; surface the
    // reduced-capability signal once per process (#1012), pointing callers at a
    // full manifest-backed Normalizer.
    emit_reduced_capability_warning(
        py,
        provider.has_genomic_data(),
        ProviderKind::TestData,
        "normalize()",
        "Normalizer.from_manifest(...)",
    )?;
    let normalizer = Normalizer::with_config(provider, config);

    let normalized = normalizer.normalize(&variant).map_err(|e| {
        ferro_typed(
            "NormalizationError",
            format!("Normalization error: {e}"),
            &e,
        )
    })?;

    Ok(normalized.to_string())
}

/// Python wrapper for HgvsVariant
#[pyclass(name = "HgvsVariant", from_py_object)]
#[derive(Clone)]
pub struct PyHgvsVariant {
    pub(crate) inner: HgvsVariant,
}

#[pymethods]
impl PyHgvsVariant {
    /// Get the string representation of the variant
    fn __str__(&self) -> String {
        self.inner.to_string()
    }

    /// Get the repr of the variant
    fn __repr__(&self) -> String {
        format!("HgvsVariant('{}')", self.inner)
    }

    /// Equality comparison
    fn __eq__(&self, other: &Self) -> bool {
        self.inner.to_string() == other.inner.to_string()
    }

    /// Hash for use in sets and dict keys
    fn __hash__(&self) -> u64 {
        let mut hasher = DefaultHasher::new();
        self.inner.to_string().hash(&mut hasher);
        hasher.finish()
    }

    /// Get the variant type as a string
    #[getter]
    fn variant_type(&self) -> &'static str {
        variant_type_str(&self.inner)
    }

    /// Get the reference (accession) of the variant
    #[getter]
    fn reference(&self) -> PyResult<String> {
        // Argument-shaped failure (this variant kind exposes no accession), not a
        // variant-processing error: `get_variant_reference` returns a static `&str`
        // with no `FerroError`/code to lift, so this stays a plain `ValueError`
        // outside the typed hierarchy.
        get_variant_reference(&self.inner).map_err(PyValueError::new_err)
    }

    /// Get the edit type as a string
    #[getter]
    fn edit_type(&self) -> &'static str {
        get_variant_edit_type(&self.inner)
    }

    /// Get the 1-based start position of the variant.
    ///
    /// For genomic (g.), coding (c.), non-coding (n.), RNA (r.), mitochondrial (m.),
    /// and circular (o.) variants, returns the base position (without intronic
    /// offset). For single-element alleles, delegates to the sub-variant.
    /// Returns None for protein variants, RNA fusions, null/unknown alleles, and
    /// alleles with multiple sub-variants (whose start is ambiguous).
    ///
    /// 5' UTR (`c.-5A>G`) and 3' UTR (`c.*5A>G`) positions are returned as raw
    /// base values and are indistinguishable from CDS positions at the same
    /// numeric value. Use the variant string or `to_dict()` representation when
    /// the UTR distinction matters.
    #[getter]
    fn start(&self) -> Option<i64> {
        get_variant_start(&self.inner)
    }

    /// Get the 1-based end position (inclusive) of the variant.
    ///
    /// For point variants, end equals start. For single-element alleles,
    /// delegates to the sub-variant. Returns None for protein variants, RNA
    /// fusions, null/unknown alleles, and alleles with multiple sub-variants.
    #[getter]
    fn end(&self) -> Option<i64> {
        get_variant_end(&self.inner)
    }

    /// Get the intronic offset of the start position.
    ///
    /// Meaningful for coding (c.), non-coding (n.), and RNA (r.) variants with
    /// intronic positions. For `c.93+1G>T`, returns 1. For exonic positions,
    /// returns None. Always returns None for variant types without intronic
    /// offsets (genomic, mitochondrial, circular, protein, fusion, allele).
    #[getter]
    fn offset(&self) -> Option<i64> {
        get_variant_offset(&self.inner)
    }

    /// Get the substitution reference and alternative bases.
    ///
    /// Returns a tuple (ref_base, alt_base) for substitution edits,
    /// e.g., ('A', 'G') for A>G. Returns None for non-substitution edits.
    #[getter]
    fn substitution_bases(&self) -> Option<(char, char)> {
        get_substitution_bases(&self.inner)
    }

    /// Get the number of sub-variants.
    ///
    /// Returns 1 for simple variants, N for alleles with N sub-variants.
    #[getter]
    fn num_variants(&self) -> usize {
        get_num_variants(&self.inner)
    }

    /// Get sub-variants as a list.
    ///
    /// For alleles, returns the constituent variants. For simple variants,
    /// returns a single-element list containing self.
    fn variants(&self) -> Vec<PyHgvsVariant> {
        match &self.inner {
            HgvsVariant::Allele(a) => a
                .variants
                .iter()
                .map(|v| PyHgvsVariant { inner: v.clone() })
                .collect(),
            _ => vec![self.clone()],
        }
    }

    /// Get the net indel length (bases gained or lost).
    ///
    /// - Substitution/inversion/identity: 0
    /// - Deletion: negative (e.g., -3 for a 3bp deletion)
    /// - Insertion: positive (length of inserted sequence)
    /// - Delins: inserted_length - deleted_span
    /// - Duplication: positive (span of duplicated region)
    ///
    /// Returns None if the length cannot be determined (e.g., uncertain
    /// inserted sequence, protein variants).
    #[getter]
    fn indel_length(&self) -> Option<i64> {
        get_indel_length(&self.inner)
    }

    /// Check if this variant is an identity (no-change) variant.
    ///
    /// Returns true for variants with the `=` edit type.
    fn is_identity(&self) -> bool {
        is_identity(&self.inner)
    }

    /// Check if this variant causes a frameshift.
    ///
    /// Returns true if indel_length % 3 != 0.
    /// Returns false for substitutions, inversions, identity edits,
    /// and cases where indel length cannot be determined.
    fn is_frameshift(&self) -> bool {
        is_frameshift(&self.inner)
    }

    /// Check if this is a genomic variant (g. prefix)
    fn is_genomic(&self) -> bool {
        matches!(self.inner, HgvsVariant::Genome(_))
    }

    /// Check if this is a coding variant (c. prefix)
    fn is_coding(&self) -> bool {
        matches!(self.inner, HgvsVariant::Cds(_))
    }

    /// Check if this is a non-coding variant (n. prefix)
    fn is_noncoding(&self) -> bool {
        matches!(self.inner, HgvsVariant::Tx(_))
    }

    /// Check if this is a protein variant (p. prefix)
    fn is_protein(&self) -> bool {
        matches!(self.inner, HgvsVariant::Protein(_))
    }

    /// Check if this is an RNA variant (r. prefix)
    fn is_rna(&self) -> bool {
        matches!(self.inner, HgvsVariant::Rna(_))
    }

    /// Check if this is a mitochondrial variant (m. prefix)
    fn is_mitochondrial(&self) -> bool {
        matches!(self.inner, HgvsVariant::Mt(_))
    }

    /// Check if this is a substitution
    fn is_substitution(&self) -> bool {
        get_variant_edit_type(&self.inner) == "substitution"
    }

    /// Check if this is a deletion
    fn is_deletion(&self) -> bool {
        get_variant_edit_type(&self.inner) == "deletion"
    }

    /// Check if this is an insertion
    fn is_insertion(&self) -> bool {
        get_variant_edit_type(&self.inner) == "insertion"
    }

    /// Check if this is a duplication
    fn is_duplication(&self) -> bool {
        get_variant_edit_type(&self.inner) == "duplication"
    }

    /// Check if this is a deletion-insertion (delins)
    fn is_delins(&self) -> bool {
        get_variant_edit_type(&self.inner) == "delins"
    }

    /// Normalize this variant
    ///
    /// **WARNING**: This method uses built-in test data for reference sequences.
    /// For production use, create a Normalizer instance with your reference data.
    ///
    /// Args:
    ///     direction: Shuffle direction - "3prime" (default) or "5prime"
    ///
    /// Returns:
    ///     A new PyHgvsVariant representing the normalized variant
    #[pyo3(signature = (direction="3prime"))]
    fn normalize(&self, py: Python<'_>, direction: &str) -> PyResult<PyHgvsVariant> {
        let config =
            NormalizeConfig::default().with_direction(parse_direction_or_raise(direction)?);
        // Note: Uses built-in test data. For production use, create a Normalizer with reference_json.
        let provider = JsonProvider::with_test_data();
        // Genome-less test data; surface the reduced-capability signal once per
        // process (#1012), pointing callers at a full manifest-backed Normalizer.
        emit_reduced_capability_warning(
            py,
            provider.has_genomic_data(),
            ProviderKind::TestData,
            "HgvsVariant.normalize()",
            "Normalizer.from_manifest(...)",
        )?;
        let normalizer = Normalizer::with_config(provider, config);

        let normalized = normalizer.normalize(&self.inner).map_err(|e| {
            ferro_typed(
                "NormalizationError",
                format!("Normalization error: {e}"),
                &e,
            )
        })?;

        Ok(PyHgvsVariant { inner: normalized })
    }

    /// Convert to a dictionary representation
    fn to_dict<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyDict>> {
        let dict = PyDict::new(py);
        dict.set_item("string", self.inner.to_string())?;
        dict.set_item("variant_type", self.variant_type())?;
        if let Ok(ref_str) = self.reference() {
            dict.set_item("reference", ref_str)?;
        }
        dict.set_item("edit_type", self.edit_type())?;

        // Positional data
        if let Some(start) = get_variant_start(&self.inner) {
            dict.set_item("start", start)?;
        }
        if let Some(end) = get_variant_end(&self.inner) {
            dict.set_item("end", end)?;
        }
        if let Some(offset) = get_variant_offset(&self.inner) {
            dict.set_item("offset", offset)?;
        }

        // Edit details
        if let Some((ref_base, alt_base)) = get_substitution_bases(&self.inner) {
            dict.set_item("ref_base", ref_base)?;
            dict.set_item("alt_base", alt_base)?;
        }
        if let Some(indel_len) = get_indel_length(&self.inner) {
            dict.set_item("indel_length", indel_len)?;
        }

        // Allele info
        dict.set_item("num_variants", get_num_variants(&self.inner))?;

        Ok(dict)
    }

    /// Convert to JSON string
    fn to_json(&self) -> PyResult<String> {
        // Serialization infrastructure failure, not a variant-processing error:
        // there is no `FerroError`/code to lift, so this stays a plain
        // `RuntimeError` and is intentionally outside the typed hierarchy.
        serde_json::to_string(&self.inner)
            .map_err(|e| PyRuntimeError::new_err(format!("JSON serialization failed: {}", e)))
    }
}

/// Which reference backend a capability-surfacing pyclass was built from.
///
/// Surfaced to Python via `reference_summary()["provider_kind"]` so callers can
/// tell a limited build (`test_data` / `json`) apart from a full manifest-backed
/// build. Shared by every reference-backed surface: `Normalizer`,
/// `VariantProjector`, `EquivalenceChecker`, `BatchProcessor`, and
/// `CoordinateMapper`.
#[derive(Clone, Copy)]
enum ProviderKind {
    /// Built-in test data (constructed with no arguments).
    TestData,
    /// A `reference_json` file (`reference_json=...`). Labeled `"json"` because
    /// such a file may carry genomic-only data as well as transcripts;
    /// `has_genomic_data` remains the source of truth for capability.
    TranscriptsJson,
    /// A `ferro prepare` manifest (`from_manifest(...)`).
    Manifest,
}

impl ProviderKind {
    fn as_str(self) -> &'static str {
        match self {
            ProviderKind::TestData => "test_data",
            ProviderKind::TranscriptsJson => "json",
            ProviderKind::Manifest => "manifest",
        }
    }
}

/// Set once the reduced-capability `UserWarning` has been emitted for each
/// distinct message *variant*, so each variant fires at most once per process
/// regardless of how many limited reference-backed surfaces are constructed
/// (#1012 item 1). Keyed by variant — a throwaway test-data / `reference_json`
/// surface warning first must NOT suppress a genome-less *manifest* (a real
/// production misconfiguration) later in the same process, or vice versa: the
/// two carry different guidance and are independently actionable.
static REDUCED_CAPABILITY_WARNED_GENERIC: AtomicBool = AtomicBool::new(false);
static REDUCED_CAPABILITY_WARNED_MANIFEST: AtomicBool = AtomicBool::new(false);

/// Emit the shared one-time reduced-capability `UserWarning` used by every
/// Python entry point that can silently fall back to a genome-less reference
/// (#1012). Mirrors [`PyNormalizer::warn_if_reduced_capability`] but is reused
/// by the sibling surfaces (`VariantProjector`, `EquivalenceChecker`,
/// `BatchProcessor`, `CoordinateMapper`) and the free `normalize` functions.
///
/// `subject` names the surface in the message (e.g. `"VariantProjector"`);
/// `manifest_ctor` is the fully-qualified constructor to point callers at for
/// full capability (e.g. `"VariantProjector.from_manifest(...)"`). Each message
/// variant fires at most once per process, keyed by the per-variant flags
/// ([`REDUCED_CAPABILITY_WARNED_GENERIC`] / [`REDUCED_CAPABILITY_WARNED_MANIFEST`]),
/// so a limited test-data surface cannot mask a later genome-less manifest.
fn emit_reduced_capability_warning(
    py: Python<'_>,
    has_genomic_data: bool,
    kind: ProviderKind,
    subject: &str,
    manifest_ctor: &str,
) -> PyResult<()> {
    if has_genomic_data {
        return Ok(());
    }
    // Each message variant warns at most once — keyed on the same partition as
    // the message below (manifest vs test-data/reference_json), so a limited
    // test-data / reference_json surface does not consume the manifest variant's
    // one-shot slot (and vice versa).
    let warned_flag = match kind {
        ProviderKind::Manifest => &REDUCED_CAPABILITY_WARNED_MANIFEST,
        ProviderKind::TestData | ProviderKind::TranscriptsJson => {
            &REDUCED_CAPABILITY_WARNED_GENERIC
        }
    };
    if warned_flag.swap(true, Ordering::Relaxed) {
        return Ok(());
    }
    // Tailor the guidance to how the reference was built. Pointing a
    // `from_manifest(...)` caller back at `from_manifest(...)` is nonsense, so a
    // genome-less manifest gets a manifest-specific message; the test-data and
    // reference_json paths point at `from_manifest`.
    let message = match kind {
        ProviderKind::Manifest => format!(
            "{subject} manifest reference provides no genomic data: \
             genome-dependent operations will be limited. Ensure the prepared \
             reference includes a genome FASTA."
        ),
        ProviderKind::TestData | ProviderKind::TranscriptsJson => format!(
            "{subject} reference lacks genomic data: genome-dependent operations \
             will be limited (built-in test data and transcript-only reference_json \
             files carry no genome). Use {manifest_ctor} for full reference capability."
        ),
    };
    // If emitting the warning fails — most importantly when the process runs
    // under `warnings.simplefilter("error")`, so the warning is raised as an
    // exception — reset the once-per-process flag. Otherwise `swap(true, …)` above
    // would leave the flag set for a warning that never actually surfaced, and the
    // configured warning policy could be silently bypassed on a later attempt.
    // A NUL byte in the internally-built warning text is an internal invariant
    // violation, not a variant-processing error, so it stays a plain `RuntimeError`
    // outside the typed hierarchy.
    let emit = || -> PyResult<()> {
        let message = std::ffi::CString::new(message)
            .map_err(|e| PyRuntimeError::new_err(format!("invalid warning message: {e}")))?;
        PyErr::warn(py, &py.get_type::<PyUserWarning>(), &message, 1)
    };
    let result = emit();
    if result.is_err() {
        warned_flag.store(false, Ordering::Relaxed);
    }
    result
}

/// HGVS variant normalizer using a reference provider
#[pyclass(name = "Normalizer")]
pub struct PyNormalizer {
    provider: PyProvider,
    config: NormalizeConfig,
    kind: ProviderKind,
}

#[pymethods]
impl PyNormalizer {
    /// Create a new normalizer
    ///
    /// Args:
    ///     reference_json: Path to a transcripts.json file for reference data.
    ///         If not provided, uses built-in test data (limited coverage,
    ///         **not suitable for production use**).
    ///     direction: Shuffle direction - "3prime" (default) or "5prime"
    #[new]
    #[pyo3(signature = (reference_json=None, direction="3prime"))]
    fn new(py: Python<'_>, reference_json: Option<&str>, direction: &str) -> PyResult<Self> {
        // Validate the `direction` argument BEFORE loading any reference, so an
        // invalid direction always raises `ValueError` regardless of whether the
        // reference path is valid — a bad/missing path must not mask (or be
        // masked by) the argument error.
        let config =
            NormalizeConfig::default().with_direction(parse_direction_or_raise(direction)?);

        let (provider, kind) = match reference_json {
            Some(path) => (
                PyProvider::from_json(Path::new(path))?,
                ProviderKind::TranscriptsJson,
            ),
            None => (PyProvider::test_data(), ProviderKind::TestData),
        };

        let normalizer = Self {
            provider,
            config,
            kind,
        };
        normalizer.warn_if_reduced_capability(py)?;
        Ok(normalizer)
    }

    /// Create a normalizer from a reference manifest written by `ferro prepare`.
    ///
    /// Args:
    ///     manifest_path: Path to a manifest.json file (typically inside a
    ///         directory produced by `ferro prepare`).
    ///     direction: Shuffle direction - "3prime" (default) or "5prime"
    ///
    /// Returns:
    ///     A Normalizer backed by a MultiFastaProvider.
    #[staticmethod]
    #[pyo3(signature = (manifest_path, direction="3prime"))]
    fn from_manifest(py: Python<'_>, manifest_path: &str, direction: &str) -> PyResult<Self> {
        // Validate `direction` before loading the manifest (see `new`): a bad
        // manifest path must not mask an invalid-direction `ValueError`.
        let config =
            NormalizeConfig::default().with_direction(parse_direction_or_raise(direction)?);
        let provider = PyProvider::from_manifest(Path::new(manifest_path))?;
        let normalizer = Self {
            provider,
            config,
            kind: ProviderKind::Manifest,
        };
        normalizer.warn_if_reduced_capability(py)?;
        Ok(normalizer)
    }

    /// Return `True` if the backing reference provides genomic sequence data.
    ///
    /// A build with no genomic data (`Normalizer()` test data or
    /// `Normalizer(reference_json=...)`) cannot perform genome-dependent
    /// normalization; use `Normalizer.from_manifest(...)` for full capability.
    fn has_genomic_data(&self) -> bool {
        self.provider.has_genomic_data()
    }

    /// Return `True` if the backing reference provides protein sequence data.
    fn has_protein_data(&self) -> bool {
        self.provider.has_protein_data()
    }

    /// Summarize the reference backend's capabilities as a dict.
    ///
    /// Keys:
    ///     provider_kind: One of "test_data", "json", or "manifest".
    ///     has_genomic_data: Whether genomic sequences are available.
    ///     has_protein_data: Whether protein sequences are available.
    fn reference_summary<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyDict>> {
        let dict = PyDict::new(py);
        dict.set_item("provider_kind", self.kind.as_str())?;
        dict.set_item("has_genomic_data", self.provider.has_genomic_data())?;
        dict.set_item("has_protein_data", self.provider.has_protein_data())?;
        Ok(dict)
    }

    /// Parse an HGVS string
    fn parse(&self, hgvs_string: &str) -> PyResult<PyHgvsVariant> {
        parse(hgvs_string)
    }

    /// Normalize an HGVS variant
    fn normalize_variant(&self, variant: &PyHgvsVariant) -> PyResult<PyHgvsVariant> {
        let normalizer = Normalizer::with_config(self.provider.clone(), self.config.clone());

        let normalized = normalizer.normalize(&variant.inner).map_err(|e| {
            ferro_typed(
                "NormalizationError",
                format!("Normalization error: {e}"),
                &e,
            )
        })?;

        Ok(PyHgvsVariant { inner: normalized })
    }

    /// Parse and normalize an HGVS string
    fn normalize(&self, hgvs_string: &str) -> PyResult<String> {
        let variant = parse_hgvs(hgvs_string)
            .map_err(|e| ferro_typed("ParseError", format!("Parse error: {e}"), &e))?;

        let normalizer = Normalizer::with_config(self.provider.clone(), self.config.clone());

        let normalized = normalizer.normalize(&variant).map_err(|e| {
            ferro_typed(
                "NormalizationError",
                format!("Normalization error: {e}"),
                &e,
            )
        })?;

        Ok(normalized.to_string())
    }

    /// Parse and normalize an HGVS string, surfacing any warnings.
    ///
    /// Closes #395 item 5: previously `NormalizationWarning` was Rust-only;
    /// Python callers had no access to RefSeqMismatch, OverlapConflict,
    /// PositionPastEnd, AxisClampApplied, or the other warning codes the
    /// normalizer emits.
    ///
    /// Strict-mode rejections still raise `RuntimeError` (matching the
    /// existing `normalize` method). Lenient/silent return a result
    /// with the warnings vec, which may be empty.
    fn normalize_with_warnings(
        &self,
        hgvs_string: &str,
    ) -> PyResult<PyNormalizeResultWithWarnings> {
        let variant = parse_hgvs(hgvs_string)
            .map_err(|e| ferro_typed("ParseError", format!("Parse error: {e}"), &e))?;
        let normalizer = Normalizer::with_config(self.provider.clone(), self.config.clone());
        let result = normalizer
            .normalize_with_diagnostics(&variant)
            .map_err(|e| {
                ferro_typed(
                    "NormalizationError",
                    format!("Normalization error: {e}"),
                    &e,
                )
            })?;
        Ok(PyNormalizeResultWithWarnings {
            result: PyHgvsVariant {
                inner: result.result,
            },
            warnings: result
                .warnings
                .iter()
                .map(PyNormalizationWarning::from)
                .collect(),
        })
    }
}

impl PyNormalizer {
    /// Emit a one-time `UserWarning` when the backing provider has no genomic
    /// data, so users silently landing on a reduced-capability build get a
    /// runtime signal (#1012 item 1). Fires at most once per process; the
    /// `JsonProvider` test-data and `transcripts.json` paths both lack genomic
    /// data, so both trigger it.
    fn warn_if_reduced_capability(&self, py: Python<'_>) -> PyResult<()> {
        emit_reduced_capability_warning(
            py,
            self.provider.has_genomic_data(),
            self.kind,
            "Normalizer",
            "Normalizer.from_manifest(...)",
        )
    }
}

/// Warning emitted by the normalizer.
///
/// Mirrors `crate::normalize::NormalizationWarning` but flattened for
/// Python: only the code, message, and a `String` representation of the
/// variant-specific fields are surfaced. Callers can pattern-match on
/// `code` for downstream branching (matches the convention used by the
/// W4004/W5001/W5002/etc. SVA codes).
#[pyclass(name = "NormalizationWarning", from_py_object)]
#[derive(Clone)]
pub struct PyNormalizationWarning {
    /// SVA code, e.g. `"REFSEQ_MISMATCH"` / `"OVERLAP_CONFLICTING_EDITS"` /
    /// `"POSITION_PAST_END"` / `"AXIS_CLAMP_APPLIED"` /
    /// `"CROSS_AXIS_VARIANT_NOT_SHUFFLED"` /
    /// `"CANONICAL_SPLIT_SKIPPED"`.
    #[pyo3(get)]
    pub code: String,
    /// Human-readable message.
    #[pyo3(get)]
    pub message: String,
}

impl From<&crate::normalize::NormalizationWarning> for PyNormalizationWarning {
    fn from(w: &crate::normalize::NormalizationWarning) -> Self {
        Self {
            code: w.code().to_string(),
            message: w.message().to_string(),
        }
    }
}

#[pymethods]
impl PyNormalizationWarning {
    fn __repr__(&self) -> String {
        format!("NormalizationWarning({}: {})", self.code, self.message)
    }
}

/// Result of `Normalizer.normalize_with_warnings`: the normalized
/// variant plus the warnings emitted during normalization.
#[pyclass(name = "NormalizeResultWithWarnings")]
pub struct PyNormalizeResultWithWarnings {
    /// The normalized variant.
    #[pyo3(get)]
    pub result: PyHgvsVariant,
    /// Warnings emitted during normalization (may be empty).
    #[pyo3(get)]
    pub warnings: Vec<PyNormalizationWarning>,
}

#[pymethods]
impl PyNormalizeResultWithWarnings {
    /// Returns true if any warnings were emitted.
    fn has_warnings(&self) -> bool {
        !self.warnings.is_empty()
    }

    fn __repr__(&self) -> String {
        format!(
            "NormalizeResultWithWarnings({} warning{})",
            self.warnings.len(),
            if self.warnings.len() == 1 { "" } else { "s" },
        )
    }
}

// ============================================================================
// VariantProjector
// ============================================================================

#[pyclass(name = "VariantProjection")]
pub struct PyVariantProjection {
    inner: crate::project::VariantProjection,
}

#[pymethods]
impl PyVariantProjection {
    /// The normalized g. variant as an HGVS string (None when no genomic
    /// representation is available — e.g. a bare-`NM_` coding input with no
    /// genome alignment; see #498).
    #[getter]
    fn g_name(&self) -> Option<String> {
        self.inner.genomic.as_ref().map(|v| v.to_string())
    }

    /// The c./n. variant as an HGVS string (None when projection skipped).
    #[getter]
    fn c_name(&self) -> Option<String> {
        self.inner.coding.as_ref().map(|v| v.to_string())
    }

    /// The n. (transcript-relative) variant as an HGVS string. Populated for
    /// both coding transcripts (derived genome-free from the c. form) and
    /// non-coding transcripts; None when no transcript coordinate is available
    /// (e.g. an empty allele).
    #[getter]
    fn n_name(&self) -> Option<String> {
        self.inner.noncoding.as_ref().map(|v| v.to_string())
    }

    /// The p. variant as an HGVS string (None for intronic, UTR, non-coding,
    /// or non-substitution edits).
    #[getter]
    fn p_name(&self) -> Option<String> {
        self.inner.protein.as_ref().map(|v| v.to_string())
    }

    /// The predicted r. variant as an HGVS string, or `None`.
    #[getter]
    fn r_name(&self) -> Option<String> {
        self.inner.rna.as_ref().map(|v| v.to_string())
    }

    /// Warnings emitted while normalizing the input for this projection (e.g. an
    /// auto-corrected reference-sequence mismatch). Empty when the input
    /// normalized cleanly. Mirrors `Normalizer.normalize_with_warnings`, making
    /// the same diagnostics reachable off a projection (#1018).
    #[getter]
    fn warnings(&self) -> Vec<PyNormalizationWarning> {
        self.inner
            .normalization_warnings
            .iter()
            .map(PyNormalizationWarning::from)
            .collect()
    }

    /// True if any normalization warnings were emitted for this projection.
    fn has_warnings(&self) -> bool {
        !self.inner.normalization_warnings.is_empty()
    }

    #[getter]
    fn transcript_id(&self) -> String {
        self.inner.transcript_id.clone()
    }

    #[getter]
    fn gene_symbol(&self) -> Option<String> {
        self.inner.gene_symbol.clone()
    }

    #[getter]
    fn is_frameshift(&self) -> bool {
        self.inner.is_frameshift
    }

    #[getter]
    fn is_intronic(&self) -> bool {
        self.inner.is_intronic
    }

    #[getter]
    fn is_utr(&self) -> bool {
        self.inner.is_utr
    }

    fn __repr__(&self) -> String {
        format!(
            "VariantProjection(g={:?}, c={:?}, n={:?}, p={:?}, r={:?}, transcript={:?})",
            self.g_name(),
            self.c_name(),
            self.n_name(),
            self.p_name(),
            self.r_name(),
            self.transcript_id()
        )
    }

    /// Value equality over the full projection contents (all projected axes,
    /// flags, and normalization warnings), so projections compare by value
    /// rather than identity.
    ///
    /// The canonical key is the inner value's `Debug` rendering: it is complete
    /// and deterministic within a build, and avoids deriving `Eq`/`Hash` on the
    /// whole `VariantProjection` — which would cascade onto types that do not
    /// currently need them (`NormalizationWarning`). The same `Debug`-key
    /// approach is used for `ProteinEffect`, whose `AminoAcidChange` field is
    /// likewise not `Eq`.
    fn __eq__(&self, other: &Self) -> bool {
        format!("{:?}", self.inner) == format!("{:?}", other.inner)
    }

    /// Hash consistent with `__eq__`, making projections usable as dict keys and
    /// set members.
    fn __hash__(&self) -> u64 {
        let mut hasher = DefaultHasher::new();
        format!("{:?}", self.inner).hash(&mut hasher);
        hasher.finish()
    }
}

#[pyclass(name = "VariantProjector")]
pub struct PyVariantProjector {
    inner: crate::project::VariantProjector<PyProvider>,
    /// How the backing reference was built (#1012). Captured at construction
    /// because the provider is moved into `inner`.
    kind: ProviderKind,
    /// Whether the backing reference carries genomic sequence data. Captured at
    /// construction so `reference_summary()` need not reach into `inner`.
    has_genomic_data: bool,
    /// Whether the backing reference carries protein sequence data.
    has_protein_data: bool,
}

#[pymethods]
impl PyVariantProjector {
    /// Create a variant projector.
    ///
    /// Args:
    ///     reference_json: Path to a transcripts.json file. If None, uses
    ///         built-in test data (limited; not for production).
    ///     direction: Shuffle direction passed to the internal normalizer
    ///         ("3prime" or "5prime").
    ///     assembly: Optional genome-build override ("GRCh37"/"GRCh38", or the
    ///         aliases "hg19"/"hg38") for build-agnostic inputs. A bare NG_/LRG_
    ///         input carries no build; this fills one in. An input whose
    ///         accession already encodes a build (NC_*.10/.11) keeps it.
    #[new]
    #[pyo3(signature = (reference_json=None, direction="3prime", assembly=None))]
    fn new(
        py: Python<'_>,
        reference_json: Option<&str>,
        direction: &str,
        assembly: Option<&str>,
    ) -> PyResult<Self> {
        // Validate boundary args BEFORE loading any reference (a bad path must
        // not mask an invalid direction/assembly ValueError).
        let (config, assembly_build) = parse_projector_boundary_args(direction, assembly)?;
        let (provider, kind) = match reference_json {
            Some(path) => (
                PyProvider::from_json(Path::new(path))?,
                ProviderKind::TranscriptsJson,
            ),
            None => (PyProvider::test_data(), ProviderKind::TestData),
        };
        Self::from_provider(py, provider, config, assembly_build, kind)
    }

    /// Create a projector from a ferro-prepare manifest (preferred for
    /// production — uses MultiFastaProvider with cdot data).
    #[staticmethod]
    #[pyo3(signature = (manifest_path, direction="3prime", assembly=None))]
    fn from_manifest(
        py: Python<'_>,
        manifest_path: &str,
        direction: &str,
        assembly: Option<&str>,
    ) -> PyResult<Self> {
        // Validate boundary args before loading the manifest (see `new`).
        let (config, assembly_build) = parse_projector_boundary_args(direction, assembly)?;
        let provider = PyProvider::from_manifest(Path::new(manifest_path))?;
        Self::from_provider(py, provider, config, assembly_build, ProviderKind::Manifest)
    }

    /// Return `True` if the backing reference provides genomic sequence data.
    ///
    /// A projector without genomic data (built-in test data or a transcript-only
    /// `reference_json`) cannot `project_to_genomic`; use
    /// `VariantProjector.from_manifest(...)` for full capability.
    fn has_genomic_data(&self) -> bool {
        self.has_genomic_data
    }

    /// Return `True` if the backing reference provides protein sequence data.
    fn has_protein_data(&self) -> bool {
        self.has_protein_data
    }

    /// Summarize the reference backend's capabilities as a dict.
    ///
    /// Keys:
    ///     provider_kind: One of "test_data", "json", or "manifest".
    ///     has_genomic_data: Whether genomic sequences are available.
    ///     has_protein_data: Whether protein sequences are available.
    fn reference_summary<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyDict>> {
        let dict = PyDict::new(py);
        dict.set_item("provider_kind", self.kind.as_str())?;
        dict.set_item("has_genomic_data", self.has_genomic_data)?;
        dict.set_item("has_protein_data", self.has_protein_data)?;
        Ok(dict)
    }

    /// Project a g. HGVS string onto a target transcript.
    fn project(
        &self,
        py: Python<'_>,
        hgvs_string: &str,
        transcript: &str,
    ) -> PyResult<PyVariantProjection> {
        let hgvs_string = hgvs_string.to_string();
        let transcript = transcript.to_string();
        let result = py.detach(|| self.inner.project(&hgvs_string, &transcript));
        result
            .map(|inner| PyVariantProjection { inner })
            .map_err(|e| ferro_typed("ProjectionError", format!("Projection error: {e}"), &e))
    }

    /// Parse, normalize, and project a g. HGVS string onto ALL overlapping
    /// transcripts.
    ///
    /// Returns projections in clinical priority order (MANE Select first).
    /// Individual transcript failures are silently skipped.
    ///
    /// Args:
    ///     hgvs_string: A g. HGVS variant string.
    ///
    /// Returns:
    ///     List of VariantProjection objects, one per overlapping transcript.
    ///     Empty list when no transcripts overlap the variant.
    ///
    /// Raises:
    ///     RuntimeError: If parsing or normalization fails.
    fn project_all(&self, py: Python<'_>, hgvs_string: &str) -> PyResult<Vec<PyVariantProjection>> {
        let hgvs_string = hgvs_string.to_string();
        let result = py.detach(|| self.inner.project_all(&hgvs_string));
        result
            .map(|projections| {
                projections
                    .into_iter()
                    .map(|inner| PyVariantProjection { inner })
                    .collect()
            })
            .map_err(|e| ferro_typed("ProjectionError", format!("Projection error: {e}"), &e))
    }

    /// Normalize and project an already-parsed g. variant onto a transcript.
    ///
    /// Equivalent to `project(str(variant), transcript)` but skips the
    /// re-parse — useful when a Python caller has already produced an
    /// `HgvsVariant` via `ferro_hgvs.parse(...)` or as the result of an
    /// earlier projection / conversion step.
    ///
    /// Args:
    ///     variant: An HgvsVariant (g.). Will be normalized before projection.
    ///     transcript: Transcript accession (e.g., "NM_000088.3").
    ///
    /// Returns:
    ///     VariantProjection with g./c./p. representations and flags.
    ///
    /// Raises:
    ///     RuntimeError: If normalization or projection fails.
    fn project_variant(
        &self,
        py: Python<'_>,
        variant: &PyHgvsVariant,
        transcript: &str,
    ) -> PyResult<PyVariantProjection> {
        let inner_variant = variant.inner.clone();
        let transcript = transcript.to_string();
        let result = py.detach(|| self.inner.project_variant(&inner_variant, &transcript));
        result
            .map(|inner| PyVariantProjection { inner })
            .map_err(|e| ferro_typed("ProjectionError", format!("Projection error: {e}"), &e))
    }

    /// Normalize and project an already-parsed g. variant onto ALL
    /// overlapping transcripts.
    ///
    /// Equivalent to `project_all(str(variant))` but skips the re-parse.
    ///
    /// Args:
    ///     variant: An HgvsVariant (g.). Will be normalized before projection.
    ///
    /// Returns:
    ///     List of VariantProjection objects in clinical priority order.
    ///     Empty list when no transcripts overlap the variant.
    ///
    /// Raises:
    ///     RuntimeError: If normalization or projection fails.
    fn project_variant_all(
        &self,
        py: Python<'_>,
        variant: &PyHgvsVariant,
    ) -> PyResult<Vec<PyVariantProjection>> {
        let inner_variant = variant.inner.clone();
        let result = py.detach(|| self.inner.project_variant_all(&inner_variant));
        result
            .map(|projections| {
                projections
                    .into_iter()
                    .map(|inner| PyVariantProjection { inner })
                    .collect()
            })
            .map_err(|e| ferro_typed("ProjectionError", format!("Projection error: {e}"), &e))
    }

    /// Project an already-normalized g. variant onto a single transcript,
    /// skipping the normalization step.
    ///
    /// This is more efficient than `project` when the caller has pre-normalized
    /// the variant and wants to project it against many transcripts.
    ///
    /// **Warning**: passing a non-normalized variant will produce coordinates
    /// that may not match other tools' canonical form.
    ///
    /// Args:
    ///     variant: An already-normalized HgvsVariant.
    ///     transcript: Transcript accession (e.g., "NM_000088.3").
    ///
    /// Returns:
    ///     VariantProjection with g./c./p. representations and flags.
    ///
    /// Raises:
    ///     RuntimeError: If projection fails.
    fn project_normalized(
        &self,
        py: Python<'_>,
        variant: &PyHgvsVariant,
        transcript: &str,
    ) -> PyResult<PyVariantProjection> {
        let inner_variant = variant.inner.clone();
        let transcript = transcript.to_string();
        let result = py.detach(|| self.inner.project_normalized(&inner_variant, &transcript));
        result
            .map(|inner| PyVariantProjection { inner })
            .map_err(|e| ferro_typed("ProjectionError", format!("Projection error: {e}"), &e))
    }

    /// Project an already-normalized g. variant onto ALL overlapping
    /// transcripts, skipping re-normalization.
    ///
    /// Callers that pre-normalize once and then fan-out should use this method
    /// to avoid repeated normalization overhead.
    ///
    /// Args:
    ///     variant: An already-normalized HgvsVariant.
    ///
    /// Returns:
    ///     List of VariantProjection objects in clinical priority order.
    ///     Empty list when no transcripts overlap the variant.
    ///
    /// Raises:
    ///     RuntimeError: If projection fails.
    fn project_normalized_all(
        &self,
        py: Python<'_>,
        variant: &PyHgvsVariant,
    ) -> PyResult<Vec<PyVariantProjection>> {
        let inner_variant = variant.inner.clone();
        let result = py.detach(|| self.inner.project_normalized_all(&inner_variant));
        result
            .map(|projections| {
                projections
                    .into_iter()
                    .map(|inner| PyVariantProjection { inner })
                    .collect()
            })
            .map_err(|e| ferro_typed("ProjectionError", format!("Projection error: {e}"), &e))
    }

    /// Project a transcript-coordinate variant (c./n./r.) onto its parent
    /// genomic reference and return a `Genome`-kind HgvsVariant.
    ///
    /// The output `g.` variant carries the parent NG/NC `Accession` stored in
    /// the input's `Accession.genomic_context` (e.g.
    /// `NG_007485.1(NM_000077.4):c.161_162insATC` projects onto
    /// `NG_007485.1:g.28294_28295insATC`).
    ///
    /// By default (`normalize=True`) the result is the projector-normalized
    /// genomic form — what most callers want; a `Genome` input is canonicalized
    /// too. The normalizer follows this projector's configured shuffle direction
    /// (`VariantProjector(direction=...)`): with the default `direction="3prime"`
    /// that is the spec-canonical, 3'-shifted form (e.g. a non-3'-most `g.1003del`
    /// in a poly-A run → `g.1007del`); a `direction="5prime"` projector instead
    /// returns the 5'-anchored form. Pass `normalize=False` to get the raw pivot,
    /// which intentionally does not normalize its input (#785): a non-canonical
    /// input then yields a non-canonical genomic output, and a `Genome` input
    /// passes through unchanged (idempotent). (#867)
    ///
    /// Limitations:
    ///   - `Allele` inputs are rejected pending #328.
    ///   - Plus-strand `Base::U` in r. inputs is forwarded verbatim into the
    ///     g. output; callers should pre-translate U→T.
    ///   - Intronic offsets on non-coding transcripts are rejected pending
    ///     #332.
    ///
    /// Args:
    ///     variant: A c./n./r./g. HgvsVariant. Transcript-coord variants must
    ///         have a `genomic_context` (NG/NC parent reference) on their
    ///         `Accession`.
    ///     normalize: When True (default), return the projector-normalized
    ///         genomic form (spec-canonical 3'-shifted for the default
    ///         `direction="3prime"`); when False, return the raw un-normalized
    ///         pivot.
    ///
    /// Returns:
    ///     The Genome-kind HgvsVariant for the requested projection.
    ///
    /// Raises:
    ///     RuntimeError: If the input lacks a parent reference, carries an
    ///         unknown (`?`) position, or is otherwise unsupported (`p.`/`m.`/
    ///         `o.`/Allele/fusion/null/unknown-allele).
    #[pyo3(signature = (variant, normalize=true))]
    fn project_to_genomic(
        &self,
        py: Python<'_>,
        variant: &PyHgvsVariant,
        normalize: bool,
    ) -> PyResult<PyHgvsVariant> {
        // Release the GIL for the Rust projection work so it doesn't block other
        // Python threads (mirrors `project_normalized_all`/`project_many`).
        let inner_variant = variant.inner.clone();
        let result = py.detach(|| {
            if normalize {
                self.inner.project_to_genomic_normalized(&inner_variant)
            } else {
                self.inner.project_to_genomic(&inner_variant)
            }
        });
        result
            .map(|inner| PyHgvsVariant { inner })
            .map_err(|e| ferro_typed("ProjectionError", format!("Projection error: {e}"), &e))
    }

    /// Batched parse + normalize + project_all over a list of g. HGVS strings.
    ///
    /// Equivalent to `[self.project_all(s) for s in hgvs_strings]`, but takes a
    /// single Python→Rust call, releases the GIL for the entire batch, and
    /// reuses the projector's internal transcript / ref-protein caches across
    /// all inputs. Fast path for SatMut-style fan-out workloads.
    ///
    /// Args:
    ///     hgvs_strings: List of g. HGVS variant strings.
    ///     return_exceptions: When ``False`` (default) the first failing input
    ///         aborts the batch by raising ``ProjectionError``. When ``True``
    ///         nothing is raised: each output element is either that input's
    ///         list of projections or the ``ProjectionError`` for its failure,
    ///         so one bad input does not discard the rest.
    ///
    /// Returns:
    ///     List of result lists — one inner list per input, in the same order.
    ///     Each inner list contains the projections for that variant in
    ///     clinical priority order. With ``return_exceptions=True`` an element
    ///     may instead be the ``ProjectionError`` for that input.
    ///
    /// Raises:
    ///     ProjectionError: On the first parse / projection error, unless
    ///         ``return_exceptions=True`` (then failures are returned in place).
    #[pyo3(signature = (hgvs_strings, return_exceptions=false))]
    fn project_many(
        &self,
        py: Python<'_>,
        hgvs_strings: Vec<String>,
        return_exceptions: bool,
    ) -> PyResult<Vec<Py<PyAny>>> {
        // Project one input, wrapping its results and carrying the index on
        // error so the `input[i]:` prefix can pinpoint the failing entry.
        let project = |(i, s): (usize, &String)| {
            self.inner
                .project_all(s)
                .map(wrap_projections)
                .map_err(|e| (i, e))
        };
        if return_exceptions {
            // Isolation mode: compute EVERY input (no short-circuit) so each
            // failure can be surfaced in place.
            let raw = py.detach(|| hgvs_strings.iter().enumerate().map(project).collect());
            build_isolated_batch(py, raw)
        } else {
            // Fail-fast default: collect into a `Result`, which short-circuits
            // at the first failing input — later inputs are never projected.
            let outer: Result<Vec<_>, _> =
                py.detach(|| hgvs_strings.iter().enumerate().map(project).collect());
            projections_to_pylist(py, outer.map_err(|(i, e)| projection_error_at(i, &e))?)
        }
    }

    /// Batched `project_normalized_all` over a list of already-normalized g.
    /// variants. Same batching semantics as `project_many` but skips
    /// renormalization on each input.
    ///
    /// Args:
    ///     variants: List of HgvsVariant objects (must already be normalized).
    ///     return_exceptions: When ``False`` (default) the first failing input
    ///         aborts the batch by raising ``ProjectionError``. When ``True``
    ///         nothing is raised: each output element is either that input's
    ///         list of projections or the ``ProjectionError`` for its failure.
    ///
    /// Returns:
    ///     List of result lists, one per input. With ``return_exceptions=True``
    ///     an element may instead be the ``ProjectionError`` for that input.
    ///
    /// Raises:
    ///     ProjectionError: On the first projection error, unless
    ///         ``return_exceptions=True`` (then failures are returned in place).
    #[pyo3(signature = (variants, return_exceptions=false))]
    fn project_normalized_many(
        &self,
        py: Python<'_>,
        variants: Vec<PyHgvsVariant>,
        return_exceptions: bool,
    ) -> PyResult<Vec<Py<PyAny>>> {
        let inner_variants: Vec<HgvsVariant> = variants.into_iter().map(|v| v.inner).collect();
        // Project one already-normalized input, carrying the index on error.
        let project = |(i, v): (usize, &HgvsVariant)| {
            self.inner
                .project_normalized_all(v)
                .map(wrap_projections)
                .map_err(|e| (i, e))
        };
        if return_exceptions {
            // Isolation mode: compute EVERY input so failures surface in place.
            let raw = py.detach(|| inner_variants.iter().enumerate().map(project).collect());
            build_isolated_batch(py, raw)
        } else {
            // Fail-fast default: short-circuit at the first failing input.
            let outer: Result<Vec<_>, _> =
                py.detach(|| inner_variants.iter().enumerate().map(project).collect());
            projections_to_pylist(py, outer.map_err(|(i, e)| projection_error_at(i, &e))?)
        }
    }
}

/// Parse the projector's boundary args (`direction`, `assembly`) into their
/// validated forms. Split out so callers validate them BEFORE loading a
/// reference — a bad/missing reference path must not mask (or be masked by) an
/// invalid direction/assembly `ValueError`. The assembly name is normalized to a
/// canonical "GRCh37"/"GRCh38" at the boundary so the core only sees that (#715).
fn parse_projector_boundary_args(
    direction: &str,
    assembly: Option<&str>,
) -> PyResult<(NormalizeConfig, Option<&'static str>)> {
    let config = NormalizeConfig::default().with_direction(parse_direction_or_raise(direction)?);
    let assembly_build = match assembly {
        Some(name) => Some(
            crate::liftover::aliases::normalize_assembly_name(name).ok_or_else(|| {
                PyValueError::new_err(format!(
                    "unrecognized assembly {name:?}; expected GRCh37 or GRCh38 \
                     (aliases hg19/hg38 accepted)"
                ))
            })?,
        ),
        None => None,
    };
    Ok((config, assembly_build))
}

impl PyVariantProjector {
    fn from_provider(
        py: Python<'_>,
        provider: PyProvider,
        config: NormalizeConfig,
        assembly_build: Option<&'static str>,
        kind: ProviderKind,
    ) -> PyResult<Self> {
        // Capture capability before the provider is moved into the projector.
        let has_genomic_data = provider.has_genomic_data();
        let has_protein_data = provider.has_protein_data();
        let cdot = provider.cdot_mapper();
        let projector = crate::data::projection::Projector::new(cdot);
        let projector = Self {
            inner: crate::project::VariantProjector::new(projector, provider)
                .with_normalize_config(config)
                .with_assembly(assembly_build),
            kind,
            has_genomic_data,
            has_protein_data,
        };
        // project_to_genomic needs a genome a transcripts-only reference lacks,
        // so surface the reduced-capability signal once per process (#1012).
        emit_reduced_capability_warning(
            py,
            has_genomic_data,
            kind,
            "VariantProjector",
            "VariantProjector.from_manifest(...)",
        )?;
        Ok(projector)
    }
}

// ============================================================================
// SPDI Module
// ============================================================================

/// Parse an SPDI variant string
///
/// Args:
///     spdi_string: The SPDI variant description to parse (e.g., "NC_000001.11:12344:A:G")
///
/// Returns:
///     A PySpdiVariant object representing the parsed variant
///
/// Raises:
///     ValueError: If the SPDI string cannot be parsed
#[pyfunction]
fn parse_spdi(spdi_string: &str) -> PyResult<PySpdiVariant> {
    match rust_parse_spdi(spdi_string) {
        Ok(spdi) => Ok(PySpdiVariant { inner: spdi }),
        // `rust_parse_spdi` yields a `SpdiParseError`, not a `FerroError`, so there
        // is no structured code to lift onto the exception.
        Err(e) => Err(ferro_exception(
            "ParseError",
            format!("Parse error: {e}"),
            None,
            &[],
        )),
    }
}

/// Convert an HGVS variant to SPDI format (simple conversion without reference lookup)
///
/// Args:
///     variant: An HgvsVariant object
///
/// Returns:
///     A PySpdiVariant object
///
/// Raises:
///     ValueError: If the conversion fails
#[pyfunction]
fn hgvs_to_spdi(variant: &PyHgvsVariant) -> PyResult<PySpdiVariant> {
    match hgvs_to_spdi_simple(&variant.inner) {
        Ok(spdi) => Ok(PySpdiVariant { inner: spdi }),
        // `hgvs_to_spdi_simple` yields a `ConversionError`, not a `FerroError`.
        Err(e) => Err(ferro_exception(
            "ProjectionError",
            format!("Conversion error: {e}"),
            None,
            &[],
        )),
    }
}

/// Convert an SPDI variant to HGVS format
///
/// Args:
///     spdi: A PySpdiVariant object
///
/// Returns:
///     An HgvsVariant object
///
/// Raises:
///     ValueError: If the conversion fails
#[pyfunction]
fn spdi_to_hgvs_variant(spdi: &PySpdiVariant) -> PyResult<PyHgvsVariant> {
    match spdi_to_hgvs(&spdi.inner) {
        Ok(variant) => Ok(PyHgvsVariant { inner: variant }),
        // `spdi_to_hgvs` yields a `ConversionError`, not a `FerroError`.
        Err(e) => Err(ferro_exception(
            "ProjectionError",
            format!("Conversion error: {e}"),
            None,
            &[],
        )),
    }
}

/// Python wrapper for SpdiVariant
#[pyclass(name = "SpdiVariant", from_py_object)]
#[derive(Clone)]
pub struct PySpdiVariant {
    inner: SpdiVariant,
}

#[pymethods]
impl PySpdiVariant {
    /// Create a new SPDI variant
    ///
    /// Args:
    ///     sequence: Reference sequence identifier (e.g., "NC_000001.11")
    ///     position: 0-based interbase position
    ///     deletion: Deleted sequence (can be empty for insertions)
    ///     insertion: Inserted sequence (can be empty for deletions)
    #[new]
    fn new(sequence: &str, position: u64, deletion: &str, insertion: &str) -> Self {
        Self {
            inner: SpdiVariant::new(sequence, position, deletion, insertion),
        }
    }

    /// Get the string representation of the variant
    fn __str__(&self) -> String {
        self.inner.to_string()
    }

    /// Get the repr of the variant
    fn __repr__(&self) -> String {
        format!("SpdiVariant('{}')", self.inner)
    }

    /// Equality comparison
    fn __eq__(&self, other: &Self) -> bool {
        self.inner == other.inner
    }

    /// Hash for use in sets and dict keys
    fn __hash__(&self) -> u64 {
        let mut hasher = DefaultHasher::new();
        self.inner.hash(&mut hasher);
        hasher.finish()
    }

    /// Reference sequence identifier
    #[getter]
    fn sequence(&self) -> &str {
        &self.inner.sequence
    }

    /// 0-based interbase position
    #[getter]
    fn position(&self) -> u64 {
        self.inner.position
    }

    /// Deleted sequence
    #[getter]
    fn deletion(&self) -> &str {
        &self.inner.deletion
    }

    /// Inserted sequence
    #[getter]
    fn insertion(&self) -> &str {
        &self.inner.insertion
    }

    /// Check if this is a substitution (SNV or MNV)
    fn is_substitution(&self) -> bool {
        self.inner.is_substitution()
    }

    /// Check if this is a single nucleotide variant
    fn is_snv(&self) -> bool {
        self.inner.is_substitution() && self.inner.deletion.len() == 1
    }

    /// Check if this is a pure deletion
    fn is_deletion(&self) -> bool {
        self.inner.is_deletion()
    }

    /// Check if this is a pure insertion
    fn is_insertion(&self) -> bool {
        self.inner.is_insertion()
    }

    /// Check if this is a deletion-insertion (delins)
    fn is_delins(&self) -> bool {
        self.inner.is_delins()
    }

    /// Check if this represents an identity (no change)
    fn is_identity(&self) -> bool {
        self.inner.is_identity()
    }

    /// Get the variant type as a string
    fn variant_type(&self) -> &'static str {
        self.inner.variant_type()
    }

    /// Convert 0-based SPDI position to 1-based HGVS position
    fn to_one_based_position(&self) -> u64 {
        self.inner.to_one_based_position()
    }

    /// Convert to a dictionary representation
    fn to_dict<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyDict>> {
        let dict = PyDict::new(py);
        dict.set_item("sequence", &self.inner.sequence)?;
        dict.set_item("position", self.inner.position)?;
        dict.set_item("deletion", &self.inner.deletion)?;
        dict.set_item("insertion", &self.inner.insertion)?;
        dict.set_item("variant_type", self.inner.variant_type())?;
        Ok(dict)
    }
}

// ============================================================================
// Coordinates Module
// ============================================================================

/// Python wrapper for ZeroBasedPos
#[pyclass(name = "ZeroBasedPos", from_py_object)]
#[derive(Clone)]
pub struct PyZeroBasedPos {
    inner: ZeroBasedPos,
}

#[pymethods]
impl PyZeroBasedPos {
    /// Create a new 0-based position
    #[new]
    fn new(pos: u64) -> Self {
        Self {
            inner: ZeroBasedPos::new(pos),
        }
    }

    fn __str__(&self) -> String {
        self.inner.to_string()
    }

    fn __repr__(&self) -> String {
        format!("ZeroBasedPos({})", self.inner.value())
    }

    fn __eq__(&self, other: &Self) -> bool {
        self.inner == other.inner
    }

    fn __hash__(&self) -> u64 {
        let mut hasher = DefaultHasher::new();
        self.inner.hash(&mut hasher);
        hasher.finish()
    }

    fn __lt__(&self, other: &Self) -> bool {
        self.inner < other.inner
    }

    fn __le__(&self, other: &Self) -> bool {
        self.inner <= other.inner
    }

    fn __gt__(&self, other: &Self) -> bool {
        self.inner > other.inner
    }

    fn __ge__(&self, other: &Self) -> bool {
        self.inner >= other.inner
    }

    /// Get the raw value
    #[getter]
    fn value(&self) -> u64 {
        self.inner.value()
    }

    /// Convert to 1-based position
    fn to_one_based(&self) -> PyOneBasedPos {
        PyOneBasedPos {
            inner: self.inner.to_one_based(),
        }
    }

    /// Use as array index (returns int)
    fn as_index(&self) -> usize {
        self.inner.as_index()
    }
}

/// Python wrapper for OneBasedPos
#[pyclass(name = "OneBasedPos", from_py_object)]
#[derive(Clone)]
pub struct PyOneBasedPos {
    inner: OneBasedPos,
}

#[pymethods]
impl PyOneBasedPos {
    /// Create a new 1-based position
    ///
    /// Raises:
    ///     ValueError: If pos is 0 (invalid for 1-based coordinates)
    #[new]
    fn new(pos: u64) -> PyResult<Self> {
        if pos == 0 {
            return Err(PyValueError::new_err("1-based position cannot be 0"));
        }
        Ok(Self {
            inner: OneBasedPos::new(pos),
        })
    }

    fn __str__(&self) -> String {
        self.inner.to_string()
    }

    fn __repr__(&self) -> String {
        format!("OneBasedPos({})", self.inner.value())
    }

    fn __eq__(&self, other: &Self) -> bool {
        self.inner == other.inner
    }

    fn __hash__(&self) -> u64 {
        let mut hasher = DefaultHasher::new();
        self.inner.hash(&mut hasher);
        hasher.finish()
    }

    fn __lt__(&self, other: &Self) -> bool {
        self.inner < other.inner
    }

    fn __le__(&self, other: &Self) -> bool {
        self.inner <= other.inner
    }

    fn __gt__(&self, other: &Self) -> bool {
        self.inner > other.inner
    }

    fn __ge__(&self, other: &Self) -> bool {
        self.inner >= other.inner
    }

    /// Get the raw value
    #[getter]
    fn value(&self) -> u64 {
        self.inner.value()
    }

    /// Convert to 0-based position
    fn to_zero_based(&self) -> PyZeroBasedPos {
        PyZeroBasedPos {
            inner: self.inner.to_zero_based(),
        }
    }
}

/// Convert a 1-based HGVS position to a 0-based array index
#[pyfunction]
fn hgvs_pos_to_index(pos: u64) -> usize {
    crate::coords::hgvs_pos_to_index(pos)
}

/// Convert a 0-based array index to a 1-based HGVS position
#[pyfunction]
fn index_to_hgvs_pos(idx: usize) -> u64 {
    crate::coords::index_to_hgvs_pos(idx)
}

// ============================================================================
// Equivalence Module
// ============================================================================

/// Equivalence level between two variants
#[pyclass(name = "EquivalenceLevel", eq, eq_int, from_py_object)]
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum PyEquivalenceLevel {
    /// Exactly identical (same string representation)
    Identical = 0,
    /// Equivalent after normalization
    NormalizedMatch = 1,
    /// Same variant but different accession versions
    AccessionVersionDifference = 2,
    /// Not equivalent - represent different changes
    NotEquivalent = 3,
}

impl From<EquivalenceLevel> for PyEquivalenceLevel {
    fn from(level: EquivalenceLevel) -> Self {
        match level {
            EquivalenceLevel::Identical => PyEquivalenceLevel::Identical,
            EquivalenceLevel::NormalizedMatch => PyEquivalenceLevel::NormalizedMatch,
            EquivalenceLevel::AccessionVersionDifference => {
                PyEquivalenceLevel::AccessionVersionDifference
            }
            EquivalenceLevel::NotEquivalent => PyEquivalenceLevel::NotEquivalent,
        }
    }
}

#[pymethods]
impl PyEquivalenceLevel {
    fn __str__(&self) -> &'static str {
        match self {
            PyEquivalenceLevel::Identical => "Identical",
            PyEquivalenceLevel::NormalizedMatch => "NormalizedMatch",
            PyEquivalenceLevel::AccessionVersionDifference => "AccessionVersionDifference",
            PyEquivalenceLevel::NotEquivalent => "NotEquivalent",
        }
    }

    /// Returns true if the variants are considered equivalent
    fn is_equivalent(&self) -> bool {
        !matches!(self, PyEquivalenceLevel::NotEquivalent)
    }

    /// Get a human-readable description
    fn description(&self) -> &'static str {
        match self {
            PyEquivalenceLevel::Identical => "Identical representation",
            PyEquivalenceLevel::NormalizedMatch => "Equivalent after normalization",
            PyEquivalenceLevel::AccessionVersionDifference => {
                "Same variant, different accession versions"
            }
            PyEquivalenceLevel::NotEquivalent => "Not equivalent",
        }
    }
}

/// Result of an equivalence check
#[pyclass(name = "EquivalenceResult", from_py_object)]
#[derive(Clone)]
pub struct PyEquivalenceResult {
    /// The determined equivalence level
    #[pyo3(get)]
    pub level: PyEquivalenceLevel,
    /// The normalized form of the first variant (if normalization was performed)
    #[pyo3(get)]
    pub normalized_first: Option<String>,
    /// The normalized form of the second variant (if normalization was performed)
    #[pyo3(get)]
    pub normalized_second: Option<String>,
    /// Additional notes about the comparison
    #[pyo3(get)]
    pub notes: Vec<String>,
}

#[pymethods]
impl PyEquivalenceResult {
    fn __repr__(&self) -> String {
        format!(
            "EquivalenceResult(level={}, is_equivalent={})",
            self.level.__str__(),
            self.is_equivalent()
        )
    }

    /// Returns true if the variants are considered equivalent
    fn is_equivalent(&self) -> bool {
        self.level.is_equivalent()
    }
}

impl From<EquivalenceResult> for PyEquivalenceResult {
    fn from(result: EquivalenceResult) -> Self {
        Self {
            level: result.level.into(),
            normalized_first: result.normalized_first,
            normalized_second: result.normalized_second,
            notes: result.notes,
        }
    }
}

/// Equivalence checker for comparing HGVS variants
#[pyclass(name = "EquivalenceChecker")]
pub struct PyEquivalenceChecker {
    checker: EquivalenceChecker<PyProvider>,
    /// How the backing reference was built (#1012). Captured at construction
    /// because the provider is moved into `checker`.
    kind: ProviderKind,
    /// Whether the backing reference carries genomic sequence data.
    has_genomic_data: bool,
    /// Whether the backing reference carries protein sequence data.
    has_protein_data: bool,
}

#[pymethods]
impl PyEquivalenceChecker {
    /// Create a new equivalence checker
    ///
    /// Args:
    ///     reference_json: Optional path to a transcripts.json file for reference data.
    ///         If not provided, uses built-in test data.
    #[new]
    #[pyo3(signature = (reference_json=None))]
    fn new(py: Python<'_>, reference_json: Option<&str>) -> PyResult<Self> {
        let (provider, kind) = match reference_json {
            Some(path) => (
                PyProvider::from_json(Path::new(path))?,
                ProviderKind::TranscriptsJson,
            ),
            None => (PyProvider::test_data(), ProviderKind::TestData),
        };
        Self::from_provider(py, provider, kind)
    }

    /// Create an equivalence checker from a reference manifest.
    ///
    /// Args:
    ///     manifest_path: Path to a manifest.json file produced by `ferro prepare`.
    ///
    /// Returns:
    ///     An EquivalenceChecker backed by a MultiFastaProvider.
    #[staticmethod]
    fn from_manifest(py: Python<'_>, manifest_path: &str) -> PyResult<Self> {
        let provider = PyProvider::from_manifest(Path::new(manifest_path))?;
        Self::from_provider(py, provider, ProviderKind::Manifest)
    }

    /// Return `True` if the backing reference provides genomic sequence data.
    ///
    /// A checker without genomic data (built-in test data or a transcript-only
    /// `reference_json`) has limited genome-dependent capability; use
    /// `EquivalenceChecker.from_manifest(...)` for full capability.
    fn has_genomic_data(&self) -> bool {
        self.has_genomic_data
    }

    /// Return `True` if the backing reference provides protein sequence data.
    fn has_protein_data(&self) -> bool {
        self.has_protein_data
    }

    /// Summarize the reference backend's capabilities as a dict.
    ///
    /// Keys:
    ///     provider_kind: One of "test_data", "json", or "manifest".
    ///     has_genomic_data: Whether genomic sequences are available.
    ///     has_protein_data: Whether protein sequences are available.
    fn reference_summary<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyDict>> {
        let dict = PyDict::new(py);
        dict.set_item("provider_kind", self.kind.as_str())?;
        dict.set_item("has_genomic_data", self.has_genomic_data)?;
        dict.set_item("has_protein_data", self.has_protein_data)?;
        Ok(dict)
    }

    /// Check if two variants are equivalent
    ///
    /// Args:
    ///     v1: First variant
    ///     v2: Second variant
    ///
    /// Returns:
    ///     EquivalenceResult with details about the comparison
    fn check(&self, v1: &PyHgvsVariant, v2: &PyHgvsVariant) -> PyResult<PyEquivalenceResult> {
        self.checker
            .check(&v1.inner, &v2.inner)
            .map(|r| r.into())
            .map_err(|e| {
                ferro_typed(
                    "EquivalenceError",
                    format!("Equivalence check failed: {e}"),
                    &e,
                )
            })
    }

    /// Check if multiple variants are all equivalent to each other
    ///
    /// Args:
    ///     variants: List of variants to compare
    ///
    /// Returns:
    ///     True if all variants are equivalent
    fn all_equivalent(&self, variants: Vec<PyRef<PyHgvsVariant>>) -> PyResult<bool> {
        let rust_variants: Vec<HgvsVariant> = variants.iter().map(|v| v.inner.clone()).collect();
        self.checker.all_equivalent(&rust_variants).map_err(|e| {
            ferro_typed(
                "EquivalenceError",
                format!("Equivalence check failed: {e}"),
                &e,
            )
        })
    }
}

impl PyEquivalenceChecker {
    /// Build a checker from a provider, capturing capability before the provider
    /// is moved into the inner checker, and emit the one-time reduced-capability
    /// warning (#1012).
    fn from_provider(py: Python<'_>, provider: PyProvider, kind: ProviderKind) -> PyResult<Self> {
        let has_genomic_data = provider.has_genomic_data();
        let has_protein_data = provider.has_protein_data();
        let checker = Self {
            checker: EquivalenceChecker::new(provider),
            kind,
            has_genomic_data,
            has_protein_data,
        };
        emit_reduced_capability_warning(
            py,
            has_genomic_data,
            kind,
            "EquivalenceChecker",
            "EquivalenceChecker.from_manifest(...)",
        )?;
        Ok(checker)
    }
}

// ============================================================================
// Effect Prediction Module
// ============================================================================

/// Sequence Ontology consequence term
#[pyclass(name = "Consequence", eq, eq_int, from_py_object)]
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum PyConsequence {
    TranscriptAblation = 0,
    SpliceAcceptorVariant = 1,
    SpliceDonorVariant = 2,
    StopGained = 3,
    FrameshiftVariant = 4,
    StopLost = 5,
    StartLost = 6,
    MissenseVariant = 7,
    InframeInsertion = 8,
    InframeDeletion = 9,
    ProteinAlteringVariant = 10,
    SpliceRegionVariant = 11,
    SynonymousVariant = 12,
    StartRetainedVariant = 13,
    StopRetainedVariant = 14,
    FivePrimeUtrVariant = 15,
    ThreePrimeUtrVariant = 16,
    IntronVariant = 17,
    CodingSequenceVariant = 18,
}

impl From<Consequence> for PyConsequence {
    fn from(c: Consequence) -> Self {
        match c {
            Consequence::TranscriptAblation => PyConsequence::TranscriptAblation,
            Consequence::SpliceAcceptorVariant => PyConsequence::SpliceAcceptorVariant,
            Consequence::SpliceDonorVariant => PyConsequence::SpliceDonorVariant,
            Consequence::StopGained => PyConsequence::StopGained,
            Consequence::FrameshiftVariant => PyConsequence::FrameshiftVariant,
            Consequence::StopLost => PyConsequence::StopLost,
            Consequence::StartLost => PyConsequence::StartLost,
            Consequence::MissenseVariant => PyConsequence::MissenseVariant,
            Consequence::InframeInsertion => PyConsequence::InframeInsertion,
            Consequence::InframeDeletion => PyConsequence::InframeDeletion,
            Consequence::ProteinAlteringVariant => PyConsequence::ProteinAlteringVariant,
            Consequence::SpliceRegionVariant => PyConsequence::SpliceRegionVariant,
            Consequence::SynonymousVariant => PyConsequence::SynonymousVariant,
            Consequence::StartRetainedVariant => PyConsequence::StartRetainedVariant,
            Consequence::StopRetainedVariant => PyConsequence::StopRetainedVariant,
            Consequence::FivePrimeUtrVariant => PyConsequence::FivePrimeUtrVariant,
            Consequence::ThreePrimeUtrVariant => PyConsequence::ThreePrimeUtrVariant,
            Consequence::IntronVariant => PyConsequence::IntronVariant,
            Consequence::CodingSequenceVariant => PyConsequence::CodingSequenceVariant,
        }
    }
}

impl From<PyConsequence> for Consequence {
    fn from(c: PyConsequence) -> Self {
        match c {
            PyConsequence::TranscriptAblation => Consequence::TranscriptAblation,
            PyConsequence::SpliceAcceptorVariant => Consequence::SpliceAcceptorVariant,
            PyConsequence::SpliceDonorVariant => Consequence::SpliceDonorVariant,
            PyConsequence::StopGained => Consequence::StopGained,
            PyConsequence::FrameshiftVariant => Consequence::FrameshiftVariant,
            PyConsequence::StopLost => Consequence::StopLost,
            PyConsequence::StartLost => Consequence::StartLost,
            PyConsequence::MissenseVariant => Consequence::MissenseVariant,
            PyConsequence::InframeInsertion => Consequence::InframeInsertion,
            PyConsequence::InframeDeletion => Consequence::InframeDeletion,
            PyConsequence::ProteinAlteringVariant => Consequence::ProteinAlteringVariant,
            PyConsequence::SpliceRegionVariant => Consequence::SpliceRegionVariant,
            PyConsequence::SynonymousVariant => Consequence::SynonymousVariant,
            PyConsequence::StartRetainedVariant => Consequence::StartRetainedVariant,
            PyConsequence::StopRetainedVariant => Consequence::StopRetainedVariant,
            PyConsequence::FivePrimeUtrVariant => Consequence::FivePrimeUtrVariant,
            PyConsequence::ThreePrimeUtrVariant => Consequence::ThreePrimeUtrVariant,
            PyConsequence::IntronVariant => Consequence::IntronVariant,
            PyConsequence::CodingSequenceVariant => Consequence::CodingSequenceVariant,
        }
    }
}

#[pymethods]
impl PyConsequence {
    fn __str__(&self) -> &'static str {
        Consequence::from(*self).so_term()
    }

    /// Get the Sequence Ontology term
    fn so_term(&self) -> &'static str {
        Consequence::from(*self).so_term()
    }

    /// Get the Sequence Ontology ID
    fn so_id(&self) -> &'static str {
        Consequence::from(*self).so_id()
    }

    /// Get the impact level
    fn impact(&self) -> PyImpact {
        Consequence::from(*self).impact().into()
    }

    /// Get a human-readable description
    fn description(&self) -> &'static str {
        Consequence::from(*self).description()
    }
}

/// Variant impact level (VEP-style)
#[pyclass(name = "Impact", eq, eq_int, from_py_object)]
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum PyImpact {
    Modifier = 0,
    Low = 1,
    Moderate = 2,
    High = 3,
}

impl From<Impact> for PyImpact {
    fn from(i: Impact) -> Self {
        match i {
            Impact::Modifier => PyImpact::Modifier,
            Impact::Low => PyImpact::Low,
            Impact::Moderate => PyImpact::Moderate,
            Impact::High => PyImpact::High,
        }
    }
}

#[pymethods]
impl PyImpact {
    fn __str__(&self) -> &'static str {
        match self {
            PyImpact::High => "HIGH",
            PyImpact::Moderate => "MODERATE",
            PyImpact::Low => "LOW",
            PyImpact::Modifier => "MODIFIER",
        }
    }
}

/// Protein effect prediction result
#[pyclass(name = "ProteinEffect", from_py_object)]
#[derive(Clone)]
pub struct PyProteinEffect {
    inner: ProteinEffect,
}

#[pymethods]
impl PyProteinEffect {
    /// Get all applicable consequences
    #[getter]
    fn consequences(&self) -> Vec<PyConsequence> {
        self.inner
            .consequences
            .iter()
            .map(|c| (*c).into())
            .collect()
    }

    /// Get the highest impact level
    #[getter]
    fn impact(&self) -> PyImpact {
        self.inner.impact.into()
    }

    /// Check if this is a high-impact variant
    fn is_high_impact(&self) -> bool {
        self.inner.is_high_impact()
    }

    /// Check if this is a protein-altering variant
    fn is_protein_altering(&self) -> bool {
        self.inner.is_protein_altering()
    }

    fn __repr__(&self) -> String {
        format!(
            "ProteinEffect(impact={}, consequences={:?})",
            self.inner.impact,
            self.inner
                .consequences
                .iter()
                .map(|c| c.so_term())
                .collect::<Vec<_>>()
        )
    }

    /// Value equality over the full effect (consequences, impact, amino-acid
    /// change, and intronic offset), so effects compare by value.
    ///
    /// Uses the inner value's `Debug` rendering as the canonical key (see
    /// `VariantProjection.__eq__`): the `AminoAcidChange` field is not `Eq`, so
    /// a `Debug`-key avoids cascading `Eq`/`Hash` derives while staying
    /// deterministic within a build.
    fn __eq__(&self, other: &Self) -> bool {
        format!("{:?}", self.inner) == format!("{:?}", other.inner)
    }

    /// Hash consistent with `__eq__`, making effects usable as dict keys and set
    /// members.
    fn __hash__(&self) -> u64 {
        let mut hasher = DefaultHasher::new();
        format!("{:?}", self.inner).hash(&mut hasher);
        hasher.finish()
    }
}

/// Protein effect predictor
#[pyclass(name = "EffectPredictor")]
pub struct PyEffectPredictor {
    inner: EffectPredictor,
}

#[pymethods]
impl PyEffectPredictor {
    /// Create a new effect predictor
    #[new]
    fn new() -> Self {
        Self {
            inner: EffectPredictor::new(),
        }
    }

    /// Classify an amino acid change
    ///
    /// Args:
    ///     ref_aa: Reference amino acid (3-letter code, e.g., "Val")
    ///     alt_aa: Alternate amino acid (3-letter code, e.g., "Glu")
    ///     position: Position in protein (1-based)
    ///
    /// Returns:
    ///     ProteinEffect with consequences and impact
    fn classify_amino_acid_change(
        &self,
        ref_aa: &str,
        alt_aa: &str,
        position: u64,
    ) -> PyResult<PyProteinEffect> {
        let ref_aa = parse_amino_acid(ref_aa)?;
        let alt_aa = parse_amino_acid(alt_aa)?;
        Ok(PyProteinEffect {
            inner: self
                .inner
                .classify_amino_acid_change(&ref_aa, &alt_aa, position),
        })
    }

    /// Classify an indel by frame effect
    ///
    /// Args:
    ///     ref_len: Length of reference sequence
    ///     alt_len: Length of alternate sequence
    ///
    /// Returns:
    ///     ProteinEffect with consequences and impact
    fn classify_indel(&self, ref_len: usize, alt_len: usize) -> PyProteinEffect {
        PyProteinEffect {
            inner: self.inner.classify_indel(ref_len, alt_len),
        }
    }

    /// Classify a splice site variant by distance from splice site
    ///
    /// Args:
    ///     offset: Distance from splice site (negative for acceptor, positive for donor)
    ///
    /// Returns:
    ///     ProteinEffect with consequences and impact
    fn classify_splice_variant(&self, offset: i64) -> PyProteinEffect {
        PyProteinEffect {
            inner: self.inner.classify_splice_variant(offset),
        }
    }

    /// Classify a UTR variant
    ///
    /// Args:
    ///     is_5_prime: True for 5' UTR, False for 3' UTR
    ///
    /// Returns:
    ///     ProteinEffect with consequences and impact
    fn classify_utr_variant(&self, is_5_prime: bool) -> PyProteinEffect {
        PyProteinEffect {
            inner: self.inner.classify_utr_variant(is_5_prime),
        }
    }
}

/// Helper function to parse amino acid from 3-letter code
fn parse_amino_acid(code: &str) -> PyResult<AminoAcid> {
    match code.to_uppercase().as_str() {
        "ALA" | "A" => Ok(AminoAcid::Ala),
        "ARG" | "R" => Ok(AminoAcid::Arg),
        "ASN" | "N" => Ok(AminoAcid::Asn),
        "ASP" | "D" => Ok(AminoAcid::Asp),
        "CYS" | "C" => Ok(AminoAcid::Cys),
        "GLN" | "Q" => Ok(AminoAcid::Gln),
        "GLU" | "E" => Ok(AminoAcid::Glu),
        "GLY" | "G" => Ok(AminoAcid::Gly),
        "HIS" | "H" => Ok(AminoAcid::His),
        "ILE" | "I" => Ok(AminoAcid::Ile),
        "LEU" | "L" => Ok(AminoAcid::Leu),
        "LYS" | "K" => Ok(AminoAcid::Lys),
        "MET" | "M" => Ok(AminoAcid::Met),
        "PHE" | "F" => Ok(AminoAcid::Phe),
        "PRO" | "P" => Ok(AminoAcid::Pro),
        "SER" | "S" => Ok(AminoAcid::Ser),
        "THR" | "T" => Ok(AminoAcid::Thr),
        "TRP" | "W" => Ok(AminoAcid::Trp),
        "TYR" | "Y" => Ok(AminoAcid::Tyr),
        "VAL" | "V" => Ok(AminoAcid::Val),
        "TER" | "*" | "X" => Ok(AminoAcid::Ter),
        "SEC" | "U" => Ok(AminoAcid::Sec),
        _ => Err(PyValueError::new_err(format!(
            "Unknown amino acid: {}",
            code
        ))),
    }
}

// ============================================================================
// MAVE Module
// ============================================================================

/// Context for parsing MAVE-HGVS short-form notation
#[pyclass(name = "MaveContext", from_py_object)]
#[derive(Clone)]
pub struct PyMaveContext {
    inner: MaveContext,
}

#[pymethods]
impl PyMaveContext {
    /// Create a new empty context
    #[new]
    fn new() -> Self {
        Self {
            inner: MaveContext::new(),
        }
    }

    /// Set the protein sequence accession for p. variants
    fn with_protein_accession(&self, accession: &str) -> Self {
        Self {
            inner: self.inner.clone().with_protein_accession(accession),
        }
    }

    /// Set the coding sequence accession for c. variants
    fn with_coding_accession(&self, accession: &str) -> Self {
        Self {
            inner: self.inner.clone().with_coding_accession(accession),
        }
    }

    /// Set the non-coding transcript accession for n. variants
    fn with_noncoding_accession(&self, accession: &str) -> Self {
        Self {
            inner: self.inner.clone().with_noncoding_accession(accession),
        }
    }

    /// Set the genomic sequence accession for g. variants
    fn with_genomic_accession(&self, accession: &str) -> Self {
        Self {
            inner: self.inner.clone().with_genomic_accession(accession),
        }
    }

    /// Set the gene symbol (informational)
    fn with_gene_symbol(&self, symbol: &str) -> Self {
        Self {
            inner: self.inner.clone().with_gene_symbol(symbol),
        }
    }

    /// Check if this context has any accessions defined
    fn has_accessions(&self) -> bool {
        self.inner.has_accessions()
    }

    /// Check if this context can handle a specific coordinate type
    ///
    /// Args:
    ///     coord_type: Single character coordinate type ('p', 'c', 'n', 'g', etc.)
    fn supports_coordinate_type(&self, coord_type: &str) -> PyResult<bool> {
        let c = coord_type
            .chars()
            .next()
            .ok_or_else(|| PyValueError::new_err("coord_type must be a non-empty string"))?;
        Ok(self.inner.supports_coordinate_type(c))
    }

    #[getter]
    fn noncoding_accession(&self) -> Option<String> {
        self.inner.noncoding_accession.clone()
    }

    #[getter]
    fn protein_accession(&self) -> Option<String> {
        self.inner.protein_accession.clone()
    }

    #[getter]
    fn coding_accession(&self) -> Option<String> {
        self.inner.coding_accession.clone()
    }

    #[getter]
    fn genomic_accession(&self) -> Option<String> {
        self.inner.genomic_accession.clone()
    }

    #[getter]
    fn gene_symbol(&self) -> Option<String> {
        self.inner.gene_symbol.clone()
    }
}

/// Parse a MAVE-HGVS variant string with context
///
/// Args:
///     hgvs_string: The MAVE-HGVS variant description (e.g., "p.Glu6Val")
///     context: MaveContext with accession information
///
/// Returns:
///     A HgvsVariant object with the accession filled in from context
///
/// Raises:
///     ValueError: If parsing fails or context doesn't support the coordinate type
#[pyfunction]
fn parse_mave_hgvs_variant(hgvs_string: &str, context: &PyMaveContext) -> PyResult<PyHgvsVariant> {
    match parse_mave_hgvs(hgvs_string, &context.inner) {
        Ok(variant) => Ok(PyHgvsVariant { inner: variant }),
        // `parse_mave_hgvs` yields a `MaveParseError`, not a `FerroError`, so there
        // is no structured code to lift onto the exception.
        Err(e) => Err(ferro_exception(
            "ParseError",
            format!("Parse error: {e}"),
            None,
            &[],
        )),
    }
}

/// Check if a string is in MAVE short-form notation (no accession)
///
/// Args:
///     hgvs_string: The HGVS string to check
///
/// Returns:
///     True if the string is in short form (e.g., "p.Val600Glu"), False otherwise
#[pyfunction]
fn is_mave_short_form_variant(hgvs_string: &str) -> bool {
    is_mave_short_form(hgvs_string)
}

// ============================================================================
// Batch Processing Module
// ============================================================================

/// Progress information for batch processing
#[pyclass(name = "BatchProgress", from_py_object)]
#[derive(Clone)]
pub struct PyBatchProgress {
    #[pyo3(get)]
    pub processed: usize,
    #[pyo3(get)]
    pub total: usize,
    #[pyo3(get)]
    pub successes: usize,
    #[pyo3(get)]
    pub failures: usize,
}

#[pymethods]
impl PyBatchProgress {
    /// Get the percentage complete
    fn percent(&self) -> f64 {
        if self.total == 0 {
            100.0
        } else {
            (self.processed as f64 / self.total as f64) * 100.0
        }
    }
}

impl From<&BatchProgress> for PyBatchProgress {
    fn from(p: &BatchProgress) -> Self {
        Self {
            processed: p.processed,
            total: p.total,
            successes: p.success,
            failures: p.errors,
        }
    }
}

/// Result of batch processing
#[pyclass(name = "BatchResult")]
pub struct PyBatchResult {
    inner: BatchResult<HgvsVariant>,
}

#[pymethods]
impl PyBatchResult {
    /// Total number of items processed
    fn total(&self) -> usize {
        self.inner.total()
    }

    /// Number of successful items
    fn success_count(&self) -> usize {
        self.inner.success_count()
    }

    /// Number of failed items
    fn error_count(&self) -> usize {
        self.inner.error_count()
    }

    /// Success rate as a percentage
    fn success_rate(&self) -> f64 {
        self.inner.success_rate()
    }

    /// Get successfully parsed/normalized variants
    fn successes(&self) -> Vec<PyHgvsVariant> {
        self.inner
            .results
            .iter()
            .filter_map(|r| match r {
                crate::batch::ItemResult::Ok(v) => Some(PyHgvsVariant { inner: v.clone() }),
                _ => None,
            })
            .collect()
    }

    /// Get errors as (index, error_message) tuples
    fn errors(&self) -> Vec<(usize, String)> {
        self.inner
            .results
            .iter()
            .enumerate()
            .filter_map(|(i, r)| match r {
                crate::batch::ItemResult::Err { error, .. } => Some((i, error.to_string())),
                _ => None,
            })
            .collect()
    }

    fn __repr__(&self) -> String {
        format!(
            "BatchResult(total={}, successes={}, errors={})",
            self.total(),
            self.success_count(),
            self.error_count()
        )
    }
}

/// Batch processor for parsing and normalizing multiple variants
#[pyclass(name = "BatchProcessor")]
pub struct PyBatchProcessor {
    processor: BatchProcessor<PyProvider>,
    /// How the backing reference was built (#1012). Captured at construction
    /// because the provider is moved into `processor`.
    kind: ProviderKind,
    /// Whether the backing reference carries genomic sequence data.
    has_genomic_data: bool,
    /// Whether the backing reference carries protein sequence data.
    has_protein_data: bool,
}

#[pymethods]
impl PyBatchProcessor {
    /// Create a new batch processor
    ///
    /// Args:
    ///     reference_json: Optional path to a transcripts.json file for reference data.
    ///         If not provided, uses built-in test data.
    #[new]
    #[pyo3(signature = (reference_json=None))]
    fn new(py: Python<'_>, reference_json: Option<&str>) -> PyResult<Self> {
        let (provider, kind) = match reference_json {
            Some(path) => (
                PyProvider::from_json(Path::new(path))?,
                ProviderKind::TranscriptsJson,
            ),
            None => (PyProvider::test_data(), ProviderKind::TestData),
        };
        Self::from_provider(py, provider, kind)
    }

    /// Create a batch processor from a reference manifest.
    ///
    /// Args:
    ///     manifest_path: Path to a manifest.json file produced by `ferro prepare`.
    ///
    /// Returns:
    ///     A BatchProcessor backed by a MultiFastaProvider.
    #[staticmethod]
    fn from_manifest(py: Python<'_>, manifest_path: &str) -> PyResult<Self> {
        let provider = PyProvider::from_manifest(Path::new(manifest_path))?;
        Self::from_provider(py, provider, ProviderKind::Manifest)
    }

    /// Return `True` if the backing reference provides genomic sequence data.
    ///
    /// A processor without genomic data (built-in test data or a transcript-only
    /// `reference_json`) has limited genome-dependent capability; use
    /// `BatchProcessor.from_manifest(...)` for full capability.
    fn has_genomic_data(&self) -> bool {
        self.has_genomic_data
    }

    /// Return `True` if the backing reference provides protein sequence data.
    fn has_protein_data(&self) -> bool {
        self.has_protein_data
    }

    /// Summarize the reference backend's capabilities as a dict.
    ///
    /// Keys:
    ///     provider_kind: One of "test_data", "json", or "manifest".
    ///     has_genomic_data: Whether genomic sequences are available.
    ///     has_protein_data: Whether protein sequences are available.
    fn reference_summary<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyDict>> {
        let dict = PyDict::new(py);
        dict.set_item("provider_kind", self.kind.as_str())?;
        dict.set_item("has_genomic_data", self.has_genomic_data)?;
        dict.set_item("has_protein_data", self.has_protein_data)?;
        Ok(dict)
    }

    /// Parse multiple HGVS strings.
    ///
    /// The batch is processed across a thread pool with the GIL released, so it
    /// scales across cores and does not block other Python threads. Results are
    /// returned in input order.
    ///
    /// Args:
    ///     variants: List of HGVS strings to parse
    ///     workers: Number of worker threads. 0 (default) uses all available
    ///         cores; 1 runs serially; N uses N threads.
    ///
    /// Returns:
    ///     BatchResult with parsed variants and errors
    #[pyo3(signature = (variants, workers=0))]
    fn parse(&self, py: Python<'_>, variants: Vec<String>, workers: usize) -> PyBatchResult {
        let inner = py.detach(|| self.processor.parse_parallel(&variants, workers));
        PyBatchResult { inner }
    }

    /// Parse and normalize multiple HGVS strings.
    ///
    /// The batch is processed across a thread pool with the GIL released, so it
    /// scales across cores and does not block other Python threads. Results are
    /// returned in input order.
    ///
    /// Args:
    ///     variants: List of HGVS strings to parse and normalize
    ///     workers: Number of worker threads. 0 (default) uses all available
    ///         cores; 1 runs serially; N uses N threads.
    ///
    /// Returns:
    ///     BatchResult with normalized variants and errors
    #[pyo3(signature = (variants, workers=0))]
    fn parse_and_normalize(
        &self,
        py: Python<'_>,
        variants: Vec<String>,
        workers: usize,
    ) -> PyBatchResult {
        let inner = py.detach(|| {
            self.processor
                .parse_and_normalize_parallel(&variants, workers)
        });
        PyBatchResult { inner }
    }

    /// Parse multiple HGVS strings with progress callback
    ///
    /// Args:
    ///     variants: List of HGVS strings to parse
    ///     callback: Python callable that receives BatchProgress
    ///
    /// Returns:
    ///     BatchResult with parsed variants and errors
    fn parse_with_progress(
        &self,
        variants: Vec<String>,
        callback: Bound<'_, pyo3::PyAny>,
    ) -> PyResult<PyBatchResult> {
        let result = self.processor.parse_with_progress(&variants, |progress| {
            let py_progress = PyBatchProgress::from(&progress);
            // Call the Python callback, ignoring errors
            let _ = callback.call1((py_progress,));
        });
        Ok(PyBatchResult { inner: result })
    }
}

impl PyBatchProcessor {
    /// Build a processor from a provider, capturing capability before the
    /// provider is moved into the inner processor, and emit the one-time
    /// reduced-capability warning (#1012).
    fn from_provider(py: Python<'_>, provider: PyProvider, kind: ProviderKind) -> PyResult<Self> {
        let has_genomic_data = provider.has_genomic_data();
        let has_protein_data = provider.has_protein_data();
        let processor = Self {
            processor: BatchProcessor::new(provider),
            kind,
            has_genomic_data,
            has_protein_data,
        };
        emit_reduced_capability_warning(
            py,
            has_genomic_data,
            kind,
            "BatchProcessor",
            "BatchProcessor.from_manifest(...)",
        )?;
        Ok(processor)
    }
}

// ============================================================================
// Error Handling Module
// ============================================================================

/// Error handling mode
#[pyclass(name = "ErrorMode", eq, eq_int, from_py_object)]
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum PyErrorMode {
    /// Strict mode - reject all non-standard input
    Strict = 0,
    /// Lenient mode - auto-correct with warnings
    Lenient = 1,
    /// Silent mode - auto-correct without warnings
    Silent = 2,
}

impl From<ErrorMode> for PyErrorMode {
    fn from(mode: ErrorMode) -> Self {
        match mode {
            ErrorMode::Strict => PyErrorMode::Strict,
            ErrorMode::Lenient => PyErrorMode::Lenient,
            ErrorMode::Silent => PyErrorMode::Silent,
        }
    }
}

impl From<PyErrorMode> for ErrorMode {
    fn from(mode: PyErrorMode) -> Self {
        match mode {
            PyErrorMode::Strict => ErrorMode::Strict,
            PyErrorMode::Lenient => ErrorMode::Lenient,
            PyErrorMode::Silent => ErrorMode::Silent,
        }
    }
}

/// Error type for configurable error handling
#[pyclass(name = "ErrorType", eq, eq_int, from_py_object)]
#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
pub enum PyErrorType {
    LowercaseAminoAcid = 0,
    MissingVersion = 1,
    WrongDashCharacter = 2,
    ExtraWhitespace = 3,
    ProteinSubstitutionArrow = 4,
    // Discriminant 5 was `PositionZero` (W4002), retired in issue #269.
    // The numeric value is intentionally skipped so existing variants keep
    // their stable repr-C discriminants — Python consumers that hold any
    // value other than 5 continue to round-trip unchanged.
    SingleLetterAminoAcid = 6,
    WrongQuoteCharacter = 7,
    LowercaseAccessionPrefix = 8,
    MixedCaseEditType = 9,
    OldSubstitutionSyntax = 10,
    InvalidUnicodeCharacter = 11,
    SwappedPositions = 12,
    TrailingAnnotation = 13,
    MissingCoordinatePrefix = 14,
    OldAlleleFormat = 15,
    RefSeqMismatch = 16,
    DeprecatedStopCodonStar = 17,
    DeprecatedStopCodonX = 18,
    DeprecatedFrameshiftStar = 19,
    DeprecatedFrameshiftX = 20,
    DelSizeSuffix = 21,
    EmptyDelinsInsert = 22,
    RedundantRepeatLabel = 23,
    SinglePositionRange = 24,
    DeprecatedIvsNotation = 25,
    DeprecatedConSyntax = 26,
    LengthMismatch = 27,
    AlleleFractionAnnotation = 28,
    ClinVarProseMultiAllelic = 29,
    // 30 is W3020 RnaThymineCanonicalized (in main). 31 is W3021
    // ProteinBracketedAaInsertion (in main). 32 is W4004 PositionPastEnd.
    // 33 is W5003 VariantExceedsReference. 34 is W3019 NonSpecMosaicForm
    // (in main). 35 is W5002 OverlapConflictingEdits (in main). 36 is
    // W3022 InitiatorMetCanonicalization. The W-code is the canonical
    // identity; the integer is only a Python-side ABI tag.
    RnaThymineCanonicalized = 30,
    ProteinBracketedAaInsertion = 31,
    PositionPastEnd = 32,
    VariantExceedsReference = 33,
    NonSpecMosaicForm = 34,
    OverlapConflictingEdits = 35,
    InitiatorMetCanonicalization = 36,
    // 37 is W3023 DupSizeSuffix, 38 is W3024 DupExplicitSeq, 39 is W3025
    // DelExplicitSeq — soft-prohibition warnings for dup<N>/dup<seq>/del<seq>.
    DupSizeSuffix = 37,
    DupExplicitSeq = 38,
    DelExplicitSeq = 39,
    // 40 is W3026 NonConformantBracketCardinality — standalone single-member
    // allele bracket (c.[76A>C], p.[=]); brackets require >=2 cis members or
    // >=2 trans groups.
    NonConformantBracketCardinality = 40,
    // 41 is W4005 UnresolvableCentromere — `cen` has no sequence-derivable
    // coordinate; strict mode rejects, lenient/silent preserve (#488).
    UnresolvableCentromere = 41,
    // 42 is W4006 TranscriptFlankNotDescribable — pter/qter on a genomic-reference
    // c. denotes a 5'/3' transcript-flank position, not c.-numberable (#488).
    TranscriptFlankNotDescribable = 42,
    // 43 is W4007 IntronicOnBareTranscript — an intronic offset on a bare
    // transcript reference (NM_ c. / NR_ n., no NG_(…)/NC_(…) context); strict
    // mode rejects, lenient warns (#486).
    IntronicOnBareTranscript = 43,
    // 44 is W5004 IncompleteCdsStartReference — a c./p./r. variant against a
    // transcript with an incomplete (unconfirmed ATG) 5' CDS start
    // (cds_start_NF); strict mode rejects, lenient warns + preserves the
    // input unchanged, silent preserves without warning (#972).
    IncompleteCdsStartReference = 44,
}

impl From<ErrorType> for PyErrorType {
    fn from(t: ErrorType) -> Self {
        match t {
            ErrorType::LowercaseAminoAcid => PyErrorType::LowercaseAminoAcid,
            ErrorType::MissingVersion => PyErrorType::MissingVersion,
            ErrorType::WrongDashCharacter => PyErrorType::WrongDashCharacter,
            ErrorType::ExtraWhitespace => PyErrorType::ExtraWhitespace,
            ErrorType::ProteinSubstitutionArrow => PyErrorType::ProteinSubstitutionArrow,
            ErrorType::SingleLetterAminoAcid => PyErrorType::SingleLetterAminoAcid,
            ErrorType::WrongQuoteCharacter => PyErrorType::WrongQuoteCharacter,
            ErrorType::LowercaseAccessionPrefix => PyErrorType::LowercaseAccessionPrefix,
            ErrorType::MixedCaseEditType => PyErrorType::MixedCaseEditType,
            ErrorType::OldSubstitutionSyntax => PyErrorType::OldSubstitutionSyntax,
            ErrorType::InvalidUnicodeCharacter => PyErrorType::InvalidUnicodeCharacter,
            ErrorType::SwappedPositions => PyErrorType::SwappedPositions,
            ErrorType::TrailingAnnotation => PyErrorType::TrailingAnnotation,
            ErrorType::MissingCoordinatePrefix => PyErrorType::MissingCoordinatePrefix,
            ErrorType::OldAlleleFormat => PyErrorType::OldAlleleFormat,
            ErrorType::RefSeqMismatch => PyErrorType::RefSeqMismatch,
            ErrorType::DeprecatedStopCodonStar => PyErrorType::DeprecatedStopCodonStar,
            ErrorType::DeprecatedStopCodonX => PyErrorType::DeprecatedStopCodonX,
            ErrorType::DeprecatedFrameshiftStar => PyErrorType::DeprecatedFrameshiftStar,
            ErrorType::DeprecatedFrameshiftX => PyErrorType::DeprecatedFrameshiftX,
            ErrorType::DelSizeSuffix => PyErrorType::DelSizeSuffix,
            ErrorType::EmptyDelinsInsert => PyErrorType::EmptyDelinsInsert,
            ErrorType::RedundantRepeatLabel => PyErrorType::RedundantRepeatLabel,
            ErrorType::SinglePositionRange => PyErrorType::SinglePositionRange,
            ErrorType::DeprecatedIvsNotation => PyErrorType::DeprecatedIvsNotation,
            ErrorType::DeprecatedConSyntax => PyErrorType::DeprecatedConSyntax,
            ErrorType::LengthMismatch => PyErrorType::LengthMismatch,
            ErrorType::AlleleFractionAnnotation => PyErrorType::AlleleFractionAnnotation,
            ErrorType::ClinVarProseMultiAllelic => PyErrorType::ClinVarProseMultiAllelic,
            ErrorType::RnaThymineCanonicalized => PyErrorType::RnaThymineCanonicalized,
            ErrorType::ProteinBracketedAaInsertion => PyErrorType::ProteinBracketedAaInsertion,
            ErrorType::NonSpecMosaicForm => PyErrorType::NonSpecMosaicForm,
            ErrorType::VariantExceedsReference => PyErrorType::VariantExceedsReference,
            ErrorType::PositionPastEnd => PyErrorType::PositionPastEnd,
            ErrorType::OverlapConflictingEdits => PyErrorType::OverlapConflictingEdits,
            ErrorType::InitiatorMetCanonicalization => PyErrorType::InitiatorMetCanonicalization,
            ErrorType::DupSizeSuffix => PyErrorType::DupSizeSuffix,
            ErrorType::DupExplicitSeq => PyErrorType::DupExplicitSeq,
            ErrorType::DelExplicitSeq => PyErrorType::DelExplicitSeq,
            ErrorType::NonConformantBracketCardinality => {
                PyErrorType::NonConformantBracketCardinality
            }
            ErrorType::UnresolvableCentromere => PyErrorType::UnresolvableCentromere,
            ErrorType::TranscriptFlankNotDescribable => PyErrorType::TranscriptFlankNotDescribable,
            ErrorType::IntronicOnBareTranscript => PyErrorType::IntronicOnBareTranscript,
            ErrorType::IncompleteCdsStartReference => PyErrorType::IncompleteCdsStartReference,
        }
    }
}

impl From<PyErrorType> for ErrorType {
    fn from(t: PyErrorType) -> Self {
        match t {
            PyErrorType::LowercaseAminoAcid => ErrorType::LowercaseAminoAcid,
            PyErrorType::MissingVersion => ErrorType::MissingVersion,
            PyErrorType::WrongDashCharacter => ErrorType::WrongDashCharacter,
            PyErrorType::ExtraWhitespace => ErrorType::ExtraWhitespace,
            PyErrorType::ProteinSubstitutionArrow => ErrorType::ProteinSubstitutionArrow,
            PyErrorType::SingleLetterAminoAcid => ErrorType::SingleLetterAminoAcid,
            PyErrorType::WrongQuoteCharacter => ErrorType::WrongQuoteCharacter,
            PyErrorType::LowercaseAccessionPrefix => ErrorType::LowercaseAccessionPrefix,
            PyErrorType::MixedCaseEditType => ErrorType::MixedCaseEditType,
            PyErrorType::OldSubstitutionSyntax => ErrorType::OldSubstitutionSyntax,
            PyErrorType::InvalidUnicodeCharacter => ErrorType::InvalidUnicodeCharacter,
            PyErrorType::SwappedPositions => ErrorType::SwappedPositions,
            PyErrorType::TrailingAnnotation => ErrorType::TrailingAnnotation,
            PyErrorType::MissingCoordinatePrefix => ErrorType::MissingCoordinatePrefix,
            PyErrorType::OldAlleleFormat => ErrorType::OldAlleleFormat,
            PyErrorType::RefSeqMismatch => ErrorType::RefSeqMismatch,
            PyErrorType::DeprecatedStopCodonStar => ErrorType::DeprecatedStopCodonStar,
            PyErrorType::DeprecatedStopCodonX => ErrorType::DeprecatedStopCodonX,
            PyErrorType::DeprecatedFrameshiftStar => ErrorType::DeprecatedFrameshiftStar,
            PyErrorType::DeprecatedFrameshiftX => ErrorType::DeprecatedFrameshiftX,
            PyErrorType::DelSizeSuffix => ErrorType::DelSizeSuffix,
            PyErrorType::EmptyDelinsInsert => ErrorType::EmptyDelinsInsert,
            PyErrorType::RedundantRepeatLabel => ErrorType::RedundantRepeatLabel,
            PyErrorType::SinglePositionRange => ErrorType::SinglePositionRange,
            PyErrorType::DeprecatedIvsNotation => ErrorType::DeprecatedIvsNotation,
            PyErrorType::DeprecatedConSyntax => ErrorType::DeprecatedConSyntax,
            PyErrorType::LengthMismatch => ErrorType::LengthMismatch,
            PyErrorType::AlleleFractionAnnotation => ErrorType::AlleleFractionAnnotation,
            PyErrorType::ClinVarProseMultiAllelic => ErrorType::ClinVarProseMultiAllelic,
            PyErrorType::RnaThymineCanonicalized => ErrorType::RnaThymineCanonicalized,
            PyErrorType::ProteinBracketedAaInsertion => ErrorType::ProteinBracketedAaInsertion,
            PyErrorType::NonSpecMosaicForm => ErrorType::NonSpecMosaicForm,
            PyErrorType::VariantExceedsReference => ErrorType::VariantExceedsReference,
            PyErrorType::PositionPastEnd => ErrorType::PositionPastEnd,
            PyErrorType::OverlapConflictingEdits => ErrorType::OverlapConflictingEdits,
            PyErrorType::InitiatorMetCanonicalization => ErrorType::InitiatorMetCanonicalization,
            PyErrorType::DupSizeSuffix => ErrorType::DupSizeSuffix,
            PyErrorType::DupExplicitSeq => ErrorType::DupExplicitSeq,
            PyErrorType::DelExplicitSeq => ErrorType::DelExplicitSeq,
            PyErrorType::NonConformantBracketCardinality => {
                ErrorType::NonConformantBracketCardinality
            }
            PyErrorType::UnresolvableCentromere => ErrorType::UnresolvableCentromere,
            PyErrorType::TranscriptFlankNotDescribable => ErrorType::TranscriptFlankNotDescribable,
            PyErrorType::IntronicOnBareTranscript => ErrorType::IntronicOnBareTranscript,
            PyErrorType::IncompleteCdsStartReference => ErrorType::IncompleteCdsStartReference,
        }
    }
}

/// Override behavior for a specific error type
#[pyclass(name = "ErrorOverride", eq, eq_int, from_py_object)]
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum PyErrorOverride {
    /// Use the base mode's behavior
    Default = 0,
    /// Always return an error
    Reject = 1,
    /// Auto-correct and emit a warning
    WarnCorrect = 2,
    /// Auto-correct without warning
    SilentCorrect = 3,
    /// Accept the input as-is without correction
    Accept = 4,
}

impl From<ErrorOverride> for PyErrorOverride {
    fn from(o: ErrorOverride) -> Self {
        match o {
            ErrorOverride::Default => PyErrorOverride::Default,
            ErrorOverride::Reject => PyErrorOverride::Reject,
            ErrorOverride::WarnCorrect => PyErrorOverride::WarnCorrect,
            ErrorOverride::SilentCorrect => PyErrorOverride::SilentCorrect,
            ErrorOverride::Accept => PyErrorOverride::Accept,
        }
    }
}

impl From<PyErrorOverride> for ErrorOverride {
    fn from(o: PyErrorOverride) -> Self {
        match o {
            PyErrorOverride::Default => ErrorOverride::Default,
            PyErrorOverride::Reject => ErrorOverride::Reject,
            PyErrorOverride::WarnCorrect => ErrorOverride::WarnCorrect,
            PyErrorOverride::SilentCorrect => ErrorOverride::SilentCorrect,
            PyErrorOverride::Accept => ErrorOverride::Accept,
        }
    }
}

/// Warning generated during preprocessing
#[pyclass(name = "CorrectionWarning", from_py_object)]
#[derive(Clone)]
pub struct PyCorrectionWarning {
    #[pyo3(get)]
    pub error_type: PyErrorType,
    #[pyo3(get)]
    pub message: String,
    #[pyo3(get)]
    pub original: String,
    #[pyo3(get)]
    pub corrected: String,
}

impl From<&CorrectionWarning> for PyCorrectionWarning {
    fn from(w: &CorrectionWarning) -> Self {
        Self {
            error_type: w.error_type.into(),
            message: w.message.clone(),
            original: w.original.clone(),
            corrected: w.corrected.clone(),
        }
    }
}

#[pymethods]
impl PyCorrectionWarning {
    fn __repr__(&self) -> String {
        format!(
            "CorrectionWarning({:?}: '{}' -> '{}')",
            self.error_type, self.original, self.corrected
        )
    }
}

/// Error handling configuration
#[pyclass(name = "ErrorConfig", from_py_object)]
#[derive(Clone)]
pub struct PyErrorConfig {
    inner: ErrorConfig,
}

#[pymethods]
impl PyErrorConfig {
    /// Create a strict configuration (reject all non-standard input)
    #[staticmethod]
    fn strict() -> Self {
        Self {
            inner: ErrorConfig::strict(),
        }
    }

    /// Create a lenient configuration (auto-correct with warnings)
    #[staticmethod]
    fn lenient() -> Self {
        Self {
            inner: ErrorConfig::lenient(),
        }
    }

    /// Create a silent configuration (auto-correct without warnings)
    #[staticmethod]
    fn silent() -> Self {
        Self {
            inner: ErrorConfig::silent(),
        }
    }

    /// Add an override for a specific error type
    fn with_override(&self, error_type: PyErrorType, override_: PyErrorOverride) -> Self {
        Self {
            inner: self
                .inner
                .clone()
                .with_override(error_type.into(), override_.into()),
        }
    }

    /// Get the current error mode
    #[getter]
    fn mode(&self) -> PyErrorMode {
        self.inner.mode.into()
    }

    /// Check if the given error type should be rejected
    fn should_reject(&self, error_type: PyErrorType) -> bool {
        self.inner.should_reject(error_type.into())
    }

    /// Check if the given error type should be corrected
    fn should_correct(&self, error_type: PyErrorType) -> bool {
        self.inner.should_correct(error_type.into())
    }

    /// Check if the given error type should emit a warning
    fn should_warn(&self, error_type: PyErrorType) -> bool {
        self.inner.should_warn(error_type.into())
    }
}

/// Parse result with warnings
#[pyclass(name = "ParseResultWithWarnings")]
pub struct PyParseResultWithWarnings {
    #[pyo3(get)]
    pub variant: PyHgvsVariant,
    #[pyo3(get)]
    pub warnings: Vec<PyCorrectionWarning>,
    #[pyo3(get)]
    pub original_input: String,
    #[pyo3(get)]
    pub preprocessed_input: String,
}

#[pymethods]
impl PyParseResultWithWarnings {
    /// Returns true if there were any corrections made
    fn had_corrections(&self) -> bool {
        self.original_input != self.preprocessed_input
    }

    /// Returns true if there are any warnings
    fn has_warnings(&self) -> bool {
        !self.warnings.is_empty()
    }
}

/// Parse an HGVS string with lenient error handling
///
/// Args:
///     hgvs_string: The HGVS variant description to parse
///     config: Optional ErrorConfig (defaults to lenient mode)
///
/// Returns:
///     ParseResultWithWarnings containing the parsed variant and any warnings
///
/// Raises:
///     ValueError: If the HGVS string cannot be parsed even after corrections
#[pyfunction]
#[pyo3(signature = (hgvs_string, config=None))]
fn parse_lenient(
    hgvs_string: &str,
    config: Option<&PyErrorConfig>,
) -> PyResult<PyParseResultWithWarnings> {
    let config = config
        .map(|c| c.inner.clone())
        .unwrap_or_else(ErrorConfig::lenient);

    let preprocessor = config.preprocessor();
    let preprocess_result = preprocessor.preprocess(hgvs_string);

    if !preprocess_result.success {
        return Err(ferro_exception(
            "ParseError",
            format!("Preprocessing failed: {:?}", preprocess_result.warnings),
            None,
            &[],
        ));
    }

    let variant = parse_hgvs(&preprocess_result.preprocessed)
        .map_err(|e| ferro_typed("ParseError", format!("Parse error: {e}"), &e))?;

    Ok(PyParseResultWithWarnings {
        variant: PyHgvsVariant { inner: variant },
        warnings: preprocess_result
            .warnings
            .iter()
            .map(|w| w.into())
            .collect(),
        original_input: hgvs_string.to_string(),
        preprocessed_input: preprocess_result.preprocessed,
    })
}

// ============================================================================
// Backtranslation Module
// ============================================================================

/// A codon change representing a DNA variant
#[pyclass(name = "CodonChange", from_py_object)]
#[derive(Clone)]
pub struct PyCodonChange {
    inner: CodonChange,
}

#[pymethods]
impl PyCodonChange {
    /// Reference codon (e.g., "CTT")
    #[getter]
    fn ref_codon(&self) -> String {
        self.inner.ref_codon.to_string()
    }

    /// Alternate codon (e.g., "TTT")
    #[getter]
    fn alt_codon(&self) -> String {
        self.inner.alt_codon.to_string()
    }

    /// Position(s) in codon that changed (1-indexed)
    #[getter]
    fn changed_positions(&self) -> Vec<u8> {
        self.inner.changed_positions.clone()
    }

    /// Number of nucleotide changes
    fn num_changes(&self) -> usize {
        self.inner.nucleotide_changes.len()
    }

    fn __str__(&self) -> String {
        self.inner.to_string()
    }

    fn __repr__(&self) -> String {
        format!(
            "CodonChange({} -> {}, positions={:?})",
            self.inner.ref_codon, self.inner.alt_codon, self.inner.changed_positions
        )
    }
}

/// Codon table (genetic code)
#[pyclass(name = "CodonTable", from_py_object)]
#[derive(Clone)]
pub struct PyCodonTable {
    inner: CodonTable,
}

#[pymethods]
impl PyCodonTable {
    /// Get the standard genetic code
    #[staticmethod]
    fn standard() -> Self {
        Self {
            inner: CodonTable::standard(),
        }
    }
}

/// Backtranslation engine for converting protein changes to DNA changes
#[pyclass(name = "Backtranslator")]
pub struct PyBacktranslator {
    inner: Backtranslator,
}

#[pymethods]
impl PyBacktranslator {
    /// Create a new backtranslator with the given codon table
    #[new]
    #[pyo3(signature = (codon_table=None))]
    fn new(codon_table: Option<&PyCodonTable>) -> Self {
        let table = codon_table
            .map(|t| t.inner.clone())
            .unwrap_or_else(CodonTable::standard);
        Self {
            inner: Backtranslator::new(table),
        }
    }

    /// Create a backtranslator with the standard genetic code
    #[staticmethod]
    fn standard() -> Self {
        Self {
            inner: Backtranslator::standard(),
        }
    }

    /// Backtranslate an amino acid substitution
    ///
    /// Args:
    ///     ref_aa: Reference amino acid (3-letter code, e.g., "Leu")
    ///     alt_aa: Alternate amino acid (3-letter code, e.g., "Phe")
    ///
    /// Returns:
    ///     List of possible CodonChange objects (single-nucleotide changes only)
    fn backtranslate_substitution(
        &self,
        ref_aa: &str,
        alt_aa: &str,
    ) -> PyResult<Vec<PyCodonChange>> {
        let ref_aa = parse_amino_acid(ref_aa)?;
        let alt_aa = parse_amino_acid(alt_aa)?;
        Ok(self
            .inner
            .backtranslate_substitution(&ref_aa, &alt_aa)
            .into_iter()
            .map(|c| PyCodonChange { inner: c })
            .collect())
    }

    /// Backtranslate a nonsense mutation (amino acid to stop codon)
    ///
    /// Args:
    ///     ref_aa: Reference amino acid (3-letter code)
    ///
    /// Returns:
    ///     List of possible CodonChange objects
    fn backtranslate_to_stop(&self, ref_aa: &str) -> PyResult<Vec<PyCodonChange>> {
        let ref_aa = parse_amino_acid(ref_aa)?;
        Ok(self
            .inner
            .backtranslate_to_stop(&ref_aa)
            .into_iter()
            .map(|c| PyCodonChange { inner: c })
            .collect())
    }

    /// Backtranslate a stop loss (stop codon to amino acid)
    ///
    /// Args:
    ///     alt_aa: Alternate amino acid (3-letter code)
    ///
    /// Returns:
    ///     List of possible CodonChange objects
    fn backtranslate_stop_loss(&self, alt_aa: &str) -> PyResult<Vec<PyCodonChange>> {
        let alt_aa = parse_amino_acid(alt_aa)?;
        Ok(self
            .inner
            .backtranslate_stop_loss(&alt_aa)
            .into_iter()
            .map(|c| PyCodonChange { inner: c })
            .collect())
    }
}

// ============================================================================
// rsID Module
// ============================================================================

/// Parse rsID string to numeric value
///
/// Args:
///     rsid: rsID string (e.g., "rs121913529" or "121913529")
///
/// Returns:
///     Numeric rsID value
///
/// Raises:
///     ValueError: If the rsID cannot be parsed
#[pyfunction]
fn parse_rsid_value(rsid: &str) -> PyResult<u64> {
    rust_parse_rsid(rsid).map_err(|e| ferro_typed("ParseError", format!("Invalid rsID: {e}"), &e))
}

/// Format numeric rsID to string with "rs" prefix
///
/// Args:
///     rsid_num: Numeric rsID value
///
/// Returns:
///     rsID string (e.g., "rs121913529")
#[pyfunction]
fn format_rsid_value(rsid_num: u64) -> String {
    format_rsid(rsid_num)
}

/// Result of rsID lookup
#[pyclass(name = "RsIdResult", from_py_object)]
#[derive(Clone)]
pub struct PyRsIdResult {
    inner: RsIdResult,
}

#[pymethods]
impl PyRsIdResult {
    #[getter]
    fn rsid(&self) -> &str {
        &self.inner.rsid
    }

    #[getter]
    fn contig(&self) -> &str {
        &self.inner.contig
    }

    #[getter]
    fn position(&self) -> u64 {
        self.inner.position
    }

    #[getter]
    fn reference(&self) -> &str {
        &self.inner.reference
    }

    #[getter]
    fn alternate(&self) -> &str {
        &self.inner.alternate
    }

    #[getter]
    fn hgvs(&self) -> Option<&str> {
        self.inner.hgvs.as_deref()
    }

    #[getter]
    fn allele_frequency(&self) -> Option<f64> {
        self.inner.allele_frequency
    }

    #[getter]
    fn clinical_significance(&self) -> Option<&str> {
        self.inner.clinical_significance.as_deref()
    }

    /// Check if this is a substitution (SNV)
    fn is_snv(&self) -> bool {
        self.inner.is_snv()
    }

    /// Check if this is a deletion
    fn is_deletion(&self) -> bool {
        self.inner.is_deletion()
    }

    /// Check if this is an insertion
    fn is_insertion(&self) -> bool {
        self.inner.is_insertion()
    }

    /// Generate simple genomic HGVS notation
    fn to_hgvs(&self) -> String {
        self.inner.to_hgvs()
    }

    fn __repr__(&self) -> String {
        format!(
            "RsIdResult({}, {}:{}, {}>{})",
            self.inner.rsid,
            self.inner.contig,
            self.inner.position,
            self.inner.reference,
            self.inner.alternate
        )
    }
}

/// Simple in-memory rsID lookup for testing
#[pyclass(name = "InMemoryRsIdLookup")]
pub struct PyInMemoryRsIdLookup {
    inner: InMemoryRsIdLookup,
}

#[pymethods]
impl PyInMemoryRsIdLookup {
    /// Create with common test variants (BRAF V600E, BRCA1 185delAG)
    #[staticmethod]
    fn with_test_data() -> Self {
        Self {
            inner: InMemoryRsIdLookup::with_test_data(),
        }
    }

    /// Look up rsID and return matching variants
    ///
    /// Args:
    ///     rsid: rsID string (e.g., "rs121913529")
    ///
    /// Returns:
    ///     List of RsIdResult objects
    ///
    /// Raises:
    ///     ValueError: If rsID not found
    fn lookup(&self, rsid: &str) -> PyResult<Vec<PyRsIdResult>> {
        use crate::rsid::RsIdLookup;
        self.inner
            .lookup(rsid)
            .map(|results| {
                results
                    .into_iter()
                    .map(|r| PyRsIdResult { inner: r })
                    .collect()
            })
            .map_err(|e| ferro_typed("ReferenceDataError", format!("Lookup failed: {e}"), &e))
    }

    /// Check if rsID exists
    fn contains(&self, rsid: &str) -> bool {
        use crate::rsid::RsIdLookup;
        self.inner.contains(rsid)
    }
}

// ============================================================================
// VCF Module
// ============================================================================

/// A VCF record
#[pyclass(name = "VcfRecord", from_py_object)]
#[derive(Clone)]
pub struct PyVcfRecord {
    inner: VcfRecord,
}

#[pymethods]
impl PyVcfRecord {
    /// Create a new VCF record
    ///
    /// Args:
    ///     chrom: Chromosome name (e.g., "chr7")
    ///     pos: 1-based position
    ///     reference: Reference allele
    ///     alternate: Alternate allele(s) - can be a single string or list of strings
    ///     id: Optional variant ID (e.g., rsID)
    #[new]
    #[pyo3(signature = (chrom, pos, reference, alternate, id=None))]
    fn new(chrom: &str, pos: u64, reference: &str, alternate: &str, id: Option<&str>) -> Self {
        Self {
            inner: VcfRecord {
                chrom: chrom.to_string(),
                pos,
                id: id.map(|s| s.to_string()),
                reference: reference.to_string(),
                alternate: vec![alternate.to_string()],
                quality: None,
                filter: None,
                info: std::collections::HashMap::new(),
                format: None,
                samples: Vec::new(),
                genome_build: GenomeBuild::default(),
            },
        }
    }

    /// Create a SNV record
    ///
    /// Args:
    ///     chrom: Chromosome name
    ///     pos: 1-based position
    ///     ref_base: Reference base (single character)
    ///     alt_base: Alternate base (single character)
    ///
    /// Raises:
    ///     ValueError: If ref_base or alt_base is empty
    #[staticmethod]
    fn snv(chrom: &str, pos: u64, ref_base: &str, alt_base: &str) -> PyResult<Self> {
        let ref_char = ref_base
            .chars()
            .next()
            .ok_or_else(|| PyValueError::new_err("ref_base must be a non-empty string"))?;
        let alt_char = alt_base
            .chars()
            .next()
            .ok_or_else(|| PyValueError::new_err("alt_base must be a non-empty string"))?;
        Ok(Self {
            inner: VcfRecord::snv(chrom, pos, ref_char, alt_char),
        })
    }

    #[getter]
    fn chrom(&self) -> &str {
        &self.inner.chrom
    }

    #[getter]
    fn pos(&self) -> u64 {
        self.inner.pos
    }

    #[getter]
    fn id(&self) -> Option<&str> {
        self.inner.id.as_deref()
    }

    #[getter]
    fn reference(&self) -> &str {
        &self.inner.reference
    }

    /// Get the first alternate allele (for simple variants)
    #[getter]
    fn alternate(&self) -> Option<&str> {
        self.inner.alternate.first().map(|s| s.as_str())
    }

    /// Get all alternate alleles
    #[getter]
    fn alternates(&self) -> Vec<String> {
        self.inner.alternate.clone()
    }

    fn __repr__(&self) -> String {
        let alt_str = self.inner.alternate.join(",");
        format!(
            "VcfRecord({}:{} {}>{})",
            self.inner.chrom, self.inner.pos, self.inner.reference, alt_str
        )
    }
}

/// Convert a VCF record to genomic HGVS notation
///
/// Args:
///     record: VcfRecord object
///     alt_index: Index of the alternate allele to convert (default 0)
///
/// Returns:
///     HgvsVariant object
///
/// Raises:
///     ValueError: If conversion fails
#[pyfunction]
#[pyo3(signature = (record, alt_index=0))]
fn vcf_to_genomic_hgvs(record: &PyVcfRecord, alt_index: usize) -> PyResult<PyHgvsVariant> {
    rust_vcf_to_hgvs(&record.inner, alt_index)
        .map(|v| PyHgvsVariant {
            inner: HgvsVariant::Genome(v),
        })
        .map_err(|e| ferro_typed("ProjectionError", format!("Conversion error: {e}"), &e))
}

// ============================================================================
// Prepare Module
// ============================================================================

/// Configuration for reference data preparation
#[pyclass(name = "PrepareConfig", from_py_object)]
#[derive(Clone)]
pub struct PyPrepareConfig {
    inner: PrepareConfig,
}

#[pymethods]
impl PyPrepareConfig {
    /// Create a new prepare configuration
    #[new]
    #[pyo3(signature = (
        output_dir="ferro-reference",
        download_transcripts=true,
        download_genome=false,
        download_genome_grch37=false,
        download_refseqgene=false,
        download_lrg=false,
        download_cdot=true,
        skip_existing=true,
        dry_run=false,
        download_cdot_grch37=false,
        download_ensembl=false,
        backfill_transcripts=None
    ))]
    #[allow(clippy::too_many_arguments)]
    fn new(
        output_dir: &str,
        download_transcripts: bool,
        download_genome: bool,
        download_genome_grch37: bool,
        download_refseqgene: bool,
        download_lrg: bool,
        download_cdot: bool,
        skip_existing: bool,
        dry_run: bool,
        download_cdot_grch37: bool,
        download_ensembl: bool,
        backfill_transcripts: Option<&str>,
    ) -> Self {
        Self {
            inner: PrepareConfig {
                output_dir: std::path::PathBuf::from(output_dir),
                download_transcripts,
                download_proteins: false,
                download_genome,
                download_genome_grch37,
                download_refseqgene,
                download_lrg,
                download_cdot,
                download_cdot_grch37,
                download_ensembl,
                skip_existing,
                clinvar_file: None,
                patterns_file: None,
                validate_canonical_accessions: None,
                derive_ng_placements: None,
                backfill_transcripts: backfill_transcripts.map(std::path::PathBuf::from),
                genome: "grch38".to_string(),
                dry_run,
            },
        }
    }

    #[getter]
    fn output_dir(&self) -> String {
        self.inner.output_dir.display().to_string()
    }

    #[getter]
    fn download_transcripts(&self) -> bool {
        self.inner.download_transcripts
    }

    #[getter]
    fn download_genome(&self) -> bool {
        self.inner.download_genome
    }

    #[getter]
    fn download_cdot(&self) -> bool {
        self.inner.download_cdot
    }

    #[getter]
    fn download_cdot_grch37(&self) -> bool {
        self.inner.download_cdot_grch37
    }

    #[getter]
    fn download_ensembl(&self) -> bool {
        self.inner.download_ensembl
    }

    #[getter]
    fn backfill_transcripts(&self) -> Option<String> {
        self.inner
            .backfill_transcripts
            .as_ref()
            .map(|p| p.display().to_string())
    }
}

/// Manifest of prepared reference data
#[pyclass(name = "ReferenceManifest", from_py_object)]
#[derive(Clone)]
pub struct PyReferenceManifest {
    inner: ReferenceManifest,
}

#[pymethods]
impl PyReferenceManifest {
    #[getter]
    fn prepared_at(&self) -> &str {
        &self.inner.prepared_at
    }

    #[getter]
    fn transcript_count(&self) -> usize {
        self.inner.transcript_count
    }

    #[getter]
    fn transcript_fastas(&self) -> Vec<String> {
        self.inner
            .transcript_fastas
            .iter()
            .map(|p| p.display().to_string())
            .collect()
    }

    #[getter]
    fn genome_fasta(&self) -> Option<String> {
        self.inner
            .genome_fasta
            .as_ref()
            .map(|p| p.display().to_string())
    }

    #[getter]
    fn cdot_json(&self) -> Option<String> {
        self.inner
            .cdot_json
            .as_ref()
            .map(|p| p.display().to_string())
    }

    #[getter]
    fn cdot_grch37_json(&self) -> Option<String> {
        self.inner
            .cdot_grch37_json
            .as_ref()
            .map(|p| p.display().to_string())
    }

    #[getter]
    fn available_prefixes(&self) -> Vec<String> {
        self.inner.available_prefixes.clone()
    }

    fn __repr__(&self) -> String {
        format!(
            "ReferenceManifest(transcripts={}, prefixes={:?})",
            self.inner.transcript_count, self.inner.available_prefixes
        )
    }
}

/// Prepare reference data for normalization
///
/// Args:
///     config: PrepareConfig with download options
///
/// Returns:
///     ReferenceManifest describing the prepared data
///
/// Raises:
///     RuntimeError: If preparation fails
#[pyfunction]
fn prepare_reference_data(config: &PyPrepareConfig) -> PyResult<PyReferenceManifest> {
    prepare_references(&config.inner)
        .map(|m| PyReferenceManifest { inner: m })
        .map_err(|e| ferro_typed("ReferenceDataError", format!("Prepare failed: {e}"), &e))
}

/// Check existing reference data
///
/// Args:
///     directory: Path to reference data directory
///
/// Returns:
///     ReferenceManifest if manifest.json exists
///
/// Raises:
///     RuntimeError: If check fails
#[pyfunction]
fn check_reference_data(directory: &str) -> PyResult<PyReferenceManifest> {
    check_references(Path::new(directory))
        .map(|m| PyReferenceManifest { inner: m })
        .map_err(|e| ferro_typed("ReferenceDataError", format!("Check failed: {e}"), &e))
}

// ============================================================================
// Convert-GFF (GFF3/GTF -> transcripts.json)
// ============================================================================

/// Coerce a `--transcripts` / `--genes` filter argument, accepted as either a
/// single comma-separated string (`"NM_1.1,NM_2.1"`, matching the CLI flag) or
/// a Python list of strings (`["NM_1.1", "NM_2.1"]`), into the trimmed
/// `Vec<String>` the library filter expects. `None` (or Python `None`) means
/// "no filter".
fn coerce_filter(obj: Option<&Bound<'_, PyAny>>) -> PyResult<Option<Vec<String>>> {
    let Some(obj) = obj else { return Ok(None) };
    if obj.is_none() {
        return Ok(None);
    }
    // Try a single string first: a Python str also extracts as `Vec<String>`
    // (iterating its characters), so the list branch must not see it.
    if let Ok(s) = obj.extract::<String>() {
        Ok(Some(s.split(',').map(|t| t.trim().to_string()).collect()))
    } else if let Ok(v) = obj.extract::<Vec<String>>() {
        Ok(Some(v.into_iter().map(|t| t.trim().to_string()).collect()))
    } else {
        Err(PyValueError::new_err(
            "transcripts/genes must be a string or a list of strings",
        ))
    }
}

/// Configuration for [`convert_gff`], mirroring the `ferro convert-gff` CLI
/// flags. Construct it, then pass it to `convert_gff`.
#[pyclass(name = "ConvertGffConfig", from_py_object)]
#[derive(Clone)]
pub struct PyConvertGffConfig {
    gff: String,
    fasta: Option<String>,
    output: Option<String>,
    build: String,
    mane_only: bool,
    transcripts: Option<Vec<String>>,
    genes: Option<Vec<String>>,
    error_mode: String,
    validate_fasta: bool,
    emit_genomic_sequences: bool,
    diagnostics_json: Option<String>,
}

#[pymethods]
impl PyConvertGffConfig {
    /// Create a convert-gff configuration.
    ///
    /// Args:
    ///     gff: Path to the input GFF3/GTF annotation file.
    ///     fasta: Optional reference FASTA, used to extract exonic sequences and
    ///         (with ``emit_genomic_sequences``) the embedded contig sequences.
    ///     output: Optional output path for the ``transcripts.json``. If ``None``
    ///         (the default), the JSON is returned in ``ConvertGffReport.transcripts_json``
    ///         instead of written to disk (mirrors the CLI's stdout default).
    ///     build: Genome build recorded in the output ("GRCh38" or "GRCh37").
    ///     mane_only: Emit only MANE Select / MANE Plus Clinical transcripts.
    ///     transcripts: Optional transcript-ID filter — a list of IDs or a single
    ///         comma-separated string.
    ///     genes: Optional gene-symbol filter — a list of symbols or a single
    ///         comma-separated string.
    ///     error_mode: "lenient" (default), "strict", or "silent".
    ///     validate_fasta: Run CDS-length / start-codon FASTA validation when a
    ///         FASTA is supplied (default True; the inverse of ``--no-validate-fasta``).
    ///     emit_genomic_sequences: Embed referenced contig sequences so the output
    ///         is genome-capable. Requires ``fasta``.
    ///     diagnostics_json: Optional path to write the sampled loader diagnostics.
    #[new]
    #[pyo3(signature = (
        gff,
        fasta=None,
        output=None,
        build="GRCh38".to_string(),
        mane_only=false,
        transcripts=None,
        genes=None,
        error_mode="lenient".to_string(),
        validate_fasta=true,
        emit_genomic_sequences=false,
        diagnostics_json=None
    ))]
    #[allow(clippy::too_many_arguments)]
    fn new(
        gff: String,
        fasta: Option<String>,
        output: Option<String>,
        build: String,
        mane_only: bool,
        transcripts: Option<Bound<'_, PyAny>>,
        genes: Option<Bound<'_, PyAny>>,
        error_mode: String,
        validate_fasta: bool,
        emit_genomic_sequences: bool,
        diagnostics_json: Option<String>,
    ) -> PyResult<Self> {
        Ok(Self {
            gff,
            fasta,
            output,
            build,
            mane_only,
            transcripts: coerce_filter(transcripts.as_ref())?,
            genes: coerce_filter(genes.as_ref())?,
            error_mode,
            validate_fasta,
            emit_genomic_sequences,
            diagnostics_json,
        })
    }
}

/// Result of a [`convert_gff`] run.
#[pyclass(name = "ConvertGffReport")]
pub struct PyConvertGffReport {
    summary: String,
    transcripts_json: Option<String>,
    output_path: Option<String>,
    transcript_count: usize,
    emitted_genomic_bytes: u64,
    warnings: Vec<String>,
}

#[pymethods]
impl PyConvertGffReport {
    /// One-line loader summary (records read, transcripts built, diagnostics).
    #[getter]
    fn summary(&self) -> &str {
        &self.summary
    }

    /// The serialized ``transcripts.json`` text, present only when the config's
    /// ``output`` was ``None`` (otherwise the JSON was written to that path and
    /// this is ``None``). Feed it to a normalizer by writing it to a file:
    /// ``Normalizer(reference_json=path)`` reads a path, not inline JSON.
    #[getter]
    fn transcripts_json(&self) -> Option<&str> {
        self.transcripts_json.as_deref()
    }

    /// The path the ``transcripts.json`` was written to, or ``None`` if it was
    /// returned in ``transcripts_json`` instead.
    #[getter]
    fn output_path(&self) -> Option<&str> {
        self.output_path.as_deref()
    }

    /// Number of transcripts emitted.
    #[getter]
    fn transcript_count(&self) -> usize {
        self.transcript_count
    }

    /// Total bytes of genomic sequence embedded under ``genomic_sequences``
    /// (0 when ``emit_genomic_sequences`` was off or nothing was placed).
    #[getter]
    fn emitted_genomic_bytes(&self) -> u64 {
        self.emitted_genomic_bytes
    }

    /// Non-fatal warnings raised during conversion (also emitted as
    /// ``UserWarning``), e.g. an ``emit_genomic_sequences`` request with nothing
    /// to place, or an unusually large embedded genome.
    #[getter]
    fn warnings(&self) -> Vec<String> {
        self.warnings.clone()
    }
}

/// Convert a GFF3/GTF annotation into the ``transcripts.json`` format.
///
/// This is the in-process equivalent of `ferro convert-gff`; both call the same
/// library serializer, so the output is byte-identical for the same inputs and
/// flags. Use it to build a reference for `Normalizer(reference_json=...)`
/// without shelling out to the CLI.
///
/// Args:
///     config: A ConvertGffConfig describing the inputs and options.
///
/// Returns:
///     ConvertGffReport with the loader summary, the written path (or the JSON
///     text when ``output`` is ``None``), and any warnings.
///
/// Raises:
///     ValueError: If ``error_mode`` is not recognized, or
///         ``emit_genomic_sequences`` is set without a ``fasta``.
///     ReferenceDataError: If the annotation or FASTA cannot be read/parsed, or
///         (in strict mode) an error diagnostic is recorded.
#[pyfunction]
fn convert_gff(py: Python<'_>, config: &PyConvertGffConfig) -> PyResult<PyConvertGffReport> {
    use crate::reference::annotation::{
        convert::LARGE_GENOMIC_SEQUENCES_WARN_BYTES, convert_gff as lib_convert_gff,
        ConvertGffConfig,
    };

    // Map the string error mode to the library's strict/silent flags.
    let (strict, silent) = match config.error_mode.to_ascii_lowercase().as_str() {
        "lenient" => (false, false),
        "strict" => (true, false),
        "silent" => (false, true),
        other => {
            return Err(PyValueError::new_err(format!(
                "invalid error_mode {other:?}; expected 'lenient', 'strict', or 'silent'"
            )));
        }
    };

    // Fail fast with a clear Python error rather than deep in the library.
    if config.emit_genomic_sequences && config.fasta.is_none() {
        return Err(PyValueError::new_err(
            "emit_genomic_sequences=True requires a fasta to read the contig sequences",
        ));
    }

    let lib_config = ConvertGffConfig {
        genome_build: crate::cli::parse_genome_build(&config.build),
        mane_only: config.mane_only,
        transcripts: config.transcripts.clone(),
        genes: config.genes.clone(),
        strict,
        silent,
        no_validate_fasta: !config.validate_fasta,
        emit_genomic_sequences: config.emit_genomic_sequences,
    };

    let fasta_path = config.fasta.as_deref().map(Path::new);
    let outcome = lib_convert_gff(Path::new(&config.gff), fasta_path, &lib_config)
        .map_err(|e| ferro_typed("ReferenceDataError", format!("convert-gff failed: {e}"), &e))?;

    // Serialize exactly as the CLI does: pretty JSON. The CLI appends a trailing
    // newline via `writeln!`, so a written file matches byte-for-byte.
    let json_text = serde_json::to_string_pretty(&outcome.json)
        .map_err(|e| PyRuntimeError::new_err(format!("serialize transcripts.json: {e}")))?;

    let output_path = match config.output.as_deref() {
        Some(path) => {
            std::fs::write(path, format!("{json_text}\n"))
                .map_err(|e| PyRuntimeError::new_err(format!("write {path}: {e}")))?;
            Some(path.to_string())
        }
        None => None,
    };

    // Write diagnostics JSON if requested, matching the CLI (no trailing newline).
    if let Some(path) = config.diagnostics_json.as_deref() {
        let diagnostics = serde_json::to_string_pretty(&outcome.report.sample_diagnostics)
            .map_err(|e| PyRuntimeError::new_err(format!("serialize diagnostics: {e}")))?;
        std::fs::write(path, diagnostics)
            .map_err(|e| PyRuntimeError::new_err(format!("write {path}: {e}")))?;
    }

    // Collect the same conditions the CLI reports on stderr, and surface them as
    // Python UserWarnings (idiomatic for a binding) as well as in the report.
    let mut warnings: Vec<String> = Vec::new();
    if outcome.emit_requested_no_placement {
        warnings.push(
            "emit_genomic_sequences was set but no emitted transcript has a genomic placement; \
             genomic_sequences not written (reference stays transcript-only)"
                .to_string(),
        );
    }
    if outcome.emitted_genomic_bytes > LARGE_GENOMIC_SEQUENCES_WARN_BYTES {
        warnings.push(format!(
            "emit_genomic_sequences embedded {:.1} MB of genomic sequence; the transcripts.json \
             will be large to store and slow to parse. For a genome-scale reference prefer \
             `prepare_reference_data(...)` + `Normalizer.from_manifest(...)`.",
            outcome.emitted_genomic_bytes as f64 / 1_000_000.0
        ));
    }
    for message in &warnings {
        let message = std::ffi::CString::new(message.as_str())
            .map_err(|e| PyRuntimeError::new_err(format!("invalid warning message: {e}")))?;
        PyErr::warn(py, &py.get_type::<PyUserWarning>(), &message, 1)?;
    }

    // Return the JSON in-memory only when it was not written to a file, matching
    // the CLI's stdout-by-default behavior and keeping large payloads off-heap
    // when the caller asked for a file.
    let transcripts_json = if output_path.is_none() {
        Some(json_text)
    } else {
        None
    };
    let transcript_count = outcome
        .json
        .get("transcripts")
        .and_then(|t| t.as_array())
        .map(|a| a.len())
        .unwrap_or(0);

    Ok(PyConvertGffReport {
        summary: outcome.report.summary_line(),
        transcripts_json,
        output_path,
        transcript_count,
        emitted_genomic_bytes: outcome.emitted_genomic_bytes,
        warnings,
    })
}

// ============================================================================
// Build-Transcript (single FASTA construct -> transcripts.json)
// ============================================================================

/// Configuration for [`build_transcript`], mirroring the `ferro build-transcript`
/// CLI flags. Construct it, then pass it to `build_transcript`.
#[pyclass(name = "BuildTranscriptConfig", from_py_object)]
#[derive(Clone)]
pub struct PyBuildTranscriptConfig {
    fasta: String,
    cds_start: u64,
    cds_end: u64,
    output: Option<String>,
    id: Option<String>,
    strand: String,
    contig: Option<String>,
    gene: Option<String>,
    genome_build: String,
    emit_genomic_sequences: bool,
}

#[pymethods]
impl PyBuildTranscriptConfig {
    /// Create a build-transcript configuration.
    ///
    /// Args:
    ///     fasta: Path to the FASTA (indexed or plain; the index is built on the
    ///         fly if absent).
    ///     cds_start: CDS start position (1-based inclusive, transcript coordinates).
    ///     cds_end: CDS end position (1-based inclusive, transcript coordinates).
    ///     output: Optional output path for the ``transcripts.json``. If ``None``
    ///         (the default), the JSON is returned in
    ///         ``BuildTranscriptReport.transcripts_json`` instead of written to disk.
    ///     id: Transcript ID; defaults to the FASTA contig name.
    ///     strand: "+" (default) or "-". Minus-strand sequences are reverse-
    ///         complemented, so the CDS positions are relative to that sequence.
    ///     contig: Contig to use when the FASTA has multiple contigs.
    ///     gene: Optional gene symbol to embed in the transcript record.
    ///     genome_build: Genome build name embedded verbatim (default "GRCh38").
    ///     emit_genomic_sequences: Embed the contig's forward bytes so the output
    ///         is genome-capable.
    #[new]
    #[pyo3(signature = (
        fasta,
        cds_start,
        cds_end,
        output=None,
        id=None,
        strand="+".to_string(),
        contig=None,
        gene=None,
        genome_build="GRCh38".to_string(),
        emit_genomic_sequences=false
    ))]
    #[allow(clippy::too_many_arguments)]
    fn new(
        fasta: String,
        cds_start: u64,
        cds_end: u64,
        output: Option<String>,
        id: Option<String>,
        strand: String,
        contig: Option<String>,
        gene: Option<String>,
        genome_build: String,
        emit_genomic_sequences: bool,
    ) -> Self {
        Self {
            fasta,
            cds_start,
            cds_end,
            output,
            id,
            strand,
            contig,
            gene,
            genome_build,
            emit_genomic_sequences,
        }
    }
}

/// Result of a [`build_transcript`] run.
#[pyclass(name = "BuildTranscriptReport")]
pub struct PyBuildTranscriptReport {
    transcript_id: String,
    transcripts_json: Option<String>,
    output_path: Option<String>,
    emitted_genomic_bytes: u64,
    warnings: Vec<String>,
}

#[pymethods]
impl PyBuildTranscriptReport {
    /// The transcript ID that was emitted (the configured id or the contig name).
    #[getter]
    fn transcript_id(&self) -> &str {
        &self.transcript_id
    }

    /// The serialized ``transcripts.json`` text, present only when the config's
    /// ``output`` was ``None`` (otherwise the JSON was written to that path and
    /// this is ``None``). Feed it to a normalizer by writing it to a file:
    /// ``Normalizer(reference_json=path)`` reads a path, not inline JSON.
    #[getter]
    fn transcripts_json(&self) -> Option<&str> {
        self.transcripts_json.as_deref()
    }

    /// The path the ``transcripts.json`` was written to, or ``None`` if it was
    /// returned in ``transcripts_json`` instead.
    #[getter]
    fn output_path(&self) -> Option<&str> {
        self.output_path.as_deref()
    }

    /// Total bytes of genomic sequence embedded under ``genomic_sequences``
    /// (0 when ``emit_genomic_sequences`` was off).
    #[getter]
    fn emitted_genomic_bytes(&self) -> u64 {
        self.emitted_genomic_bytes
    }

    /// Non-fatal warnings raised during the build (also emitted as ``UserWarning``),
    /// e.g. an unusually large embedded genome.
    #[getter]
    fn warnings(&self) -> Vec<String> {
        self.warnings.clone()
    }
}

/// Build a single-construct ``transcripts.json`` from a FASTA + CDS bounds.
///
/// In-process equivalent of `ferro build-transcript`; both call the same library
/// builder, so the output is byte-identical for the same inputs and flags. Use
/// it to wrap a synthetic construct's FASTA as a reference for
/// `Normalizer(reference_json=...)` without shelling out to the CLI.
///
/// Args:
///     config: A BuildTranscriptConfig describing the inputs and options.
///
/// Returns:
///     BuildTranscriptReport with the transcript id, the written path (or the
///     JSON text when ``output`` is ``None``), and any warnings.
///
/// Raises:
///     ValueError: If ``strand`` is not "+"/"-", or the CDS bounds are invalid.
///     ReferenceDataError: If the FASTA cannot be read or the contig cannot be
///         resolved.
#[pyfunction]
fn build_transcript(
    py: Python<'_>,
    config: &PyBuildTranscriptConfig,
) -> PyResult<PyBuildTranscriptReport> {
    use crate::reference::annotation::{
        build_transcript as lib_build_transcript, convert::LARGE_GENOMIC_SEQUENCES_WARN_BYTES,
        BuildTranscriptConfig,
    };

    // Fail fast with a clear Python error rather than deep in the library.
    if config.strand != "+" && config.strand != "-" {
        return Err(PyValueError::new_err(format!(
            "invalid strand {:?}; expected '+' or '-'",
            config.strand
        )));
    }

    let lib_config = BuildTranscriptConfig {
        cds_start: config.cds_start,
        cds_end: config.cds_end,
        id: config.id.clone(),
        strand: config.strand.clone(),
        contig: config.contig.clone(),
        gene: config.gene.clone(),
        genome_build: config.genome_build.clone(),
        emit_genomic_sequences: config.emit_genomic_sequences,
    };

    let outcome = lib_build_transcript(Path::new(&config.fasta), &lib_config).map_err(|e| {
        // Invalid CDS bounds are a caller error (ValueError); everything else is a
        // reference-data failure.
        match &e {
            crate::error::FerroError::InvalidCoordinates { msg } => {
                PyValueError::new_err(msg.clone())
            }
            _ => ferro_typed(
                "ReferenceDataError",
                format!("build-transcript failed: {e}"),
                &e,
            ),
        }
    })?;

    // Serialize exactly as the CLI does: pretty JSON with NO trailing newline
    // (the CLI writes via `std::fs::write`), so a written file matches byte-for-byte.
    let json_text = serde_json::to_string_pretty(&outcome.json)
        .map_err(|e| PyRuntimeError::new_err(format!("serialize transcripts.json: {e}")))?;

    let output_path = match config.output.as_deref() {
        Some(path) => {
            std::fs::write(path, &json_text)
                .map_err(|e| PyRuntimeError::new_err(format!("write {path}: {e}")))?;
            Some(path.to_string())
        }
        None => None,
    };

    let mut warnings: Vec<String> = Vec::new();
    if outcome.emitted_genomic_bytes > LARGE_GENOMIC_SEQUENCES_WARN_BYTES {
        warnings.push(format!(
            "emit_genomic_sequences embedded {:.1} MB of genomic sequence; the transcripts.json \
             will be large to store and slow to parse. For a genome-scale reference prefer \
             `prepare_reference_data(...)` + `Normalizer.from_manifest(...)`.",
            outcome.emitted_genomic_bytes as f64 / 1_000_000.0
        ));
    }
    for message in &warnings {
        let message = std::ffi::CString::new(message.as_str())
            .map_err(|e| PyRuntimeError::new_err(format!("invalid warning message: {e}")))?;
        PyErr::warn(py, &py.get_type::<PyUserWarning>(), &message, 1)?;
    }

    let transcripts_json = if output_path.is_none() {
        Some(json_text)
    } else {
        None
    };

    Ok(PyBuildTranscriptReport {
        transcript_id: outcome.transcript_id,
        transcripts_json,
        output_path,
        emitted_genomic_bytes: outcome.emitted_genomic_bytes,
        warnings,
    })
}

// ============================================================================
// Reference Module
// ============================================================================

/// Genome build (GRCh37 or GRCh38)
#[pyclass(name = "GenomeBuild", eq, eq_int, from_py_object)]
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum PyGenomeBuild {
    GRCh37 = 0,
    GRCh38 = 1,
    Unknown = 2,
}

impl From<GenomeBuild> for PyGenomeBuild {
    fn from(b: GenomeBuild) -> Self {
        match b {
            GenomeBuild::GRCh37 => PyGenomeBuild::GRCh37,
            GenomeBuild::GRCh38 => PyGenomeBuild::GRCh38,
            GenomeBuild::Unknown => PyGenomeBuild::Unknown,
        }
    }
}

#[pymethods]
impl PyGenomeBuild {
    fn __str__(&self) -> &'static str {
        match self {
            PyGenomeBuild::GRCh37 => "GRCh37",
            PyGenomeBuild::GRCh38 => "GRCh38",
            PyGenomeBuild::Unknown => "Unknown",
        }
    }
}

/// Strand direction
#[pyclass(name = "Strand", eq, eq_int, from_py_object)]
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum PyStrand {
    Plus = 0,
    Minus = 1,
    Unknown = 2,
}

impl From<Strand> for PyStrand {
    fn from(s: Strand) -> Self {
        match s {
            Strand::Plus => PyStrand::Plus,
            Strand::Minus => PyStrand::Minus,
            Strand::Unknown => PyStrand::Unknown,
        }
    }
}

#[pymethods]
impl PyStrand {
    fn __str__(&self) -> &'static str {
        match self {
            PyStrand::Plus => "+",
            PyStrand::Minus => "-",
            PyStrand::Unknown => ".",
        }
    }
}

// ============================================================================
// Coordinate Mapper Module
// ============================================================================

/// Coordinate mapper for converting between HGVS coordinate systems
///
/// This class provides methods for converting between genomic (g.), coding (c.),
/// transcript (n.), and protein (p.) coordinate systems.
#[pyclass(name = "CoordinateMapper")]
pub struct PyCoordinateMapper {
    provider: PyProvider,
    /// How the backing reference was built (#1012).
    kind: ProviderKind,
}

#[pymethods]
impl PyCoordinateMapper {
    /// Create a new coordinate mapper
    ///
    /// Args:
    ///     reference_json: Optional path to a transcripts.json file for reference data.
    ///         If not provided, uses built-in test data.
    #[new]
    #[pyo3(signature = (reference_json=None))]
    fn new(py: Python<'_>, reference_json: Option<&str>) -> PyResult<Self> {
        let (provider, kind) = match reference_json {
            Some(path) => (
                PyProvider::from_json(Path::new(path))?,
                ProviderKind::TranscriptsJson,
            ),
            None => (PyProvider::test_data(), ProviderKind::TestData),
        };

        let mapper = Self { provider, kind };
        mapper.warn_if_reduced_capability(py)?;
        Ok(mapper)
    }

    /// Create a coordinate mapper from a reference manifest.
    ///
    /// Args:
    ///     manifest_path: Path to a manifest.json file produced by `ferro prepare`.
    ///
    /// Returns:
    ///     A CoordinateMapper backed by a MultiFastaProvider.
    #[staticmethod]
    fn from_manifest(py: Python<'_>, manifest_path: &str) -> PyResult<Self> {
        let provider = PyProvider::from_manifest(Path::new(manifest_path))?;
        let mapper = Self {
            provider,
            kind: ProviderKind::Manifest,
        };
        mapper.warn_if_reduced_capability(py)?;
        Ok(mapper)
    }

    /// Return `True` if the backing reference provides genomic sequence data.
    ///
    /// A mapper without genomic data (built-in test data or a transcript-only
    /// `reference_json`) cannot resolve genomic coordinates; use
    /// `CoordinateMapper.from_manifest(...)` for full capability.
    fn has_genomic_data(&self) -> bool {
        self.provider.has_genomic_data()
    }

    /// Return `True` if the backing reference provides protein sequence data.
    fn has_protein_data(&self) -> bool {
        self.provider.has_protein_data()
    }

    /// Summarize the reference backend's capabilities as a dict.
    ///
    /// Keys:
    ///     provider_kind: One of "test_data", "json", or "manifest".
    ///     has_genomic_data: Whether genomic sequences are available.
    ///     has_protein_data: Whether protein sequences are available.
    fn reference_summary<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyDict>> {
        let dict = PyDict::new(py);
        dict.set_item("provider_kind", self.kind.as_str())?;
        dict.set_item("has_genomic_data", self.provider.has_genomic_data())?;
        dict.set_item("has_protein_data", self.provider.has_protein_data())?;
        Ok(dict)
    }

    /// Convert a CDS position to genomic position
    ///
    /// Args:
    ///     transcript_id: Transcript accession (e.g., "NM_000088.3")
    ///     cds_position: CDS position (e.g., 100 for c.100)
    ///     offset: Optional intronic offset (e.g., 5 for c.100+5)
    ///
    /// Returns:
    ///     Tuple of (chromosome, genomic_position) or None if position is intronic
    ///     without offset support
    ///
    /// Raises:
    ///     ValueError: If transcript not found or has no genomic coordinates
    #[pyo3(signature = (transcript_id, cds_position, offset=None))]
    fn c_to_g(
        &self,
        transcript_id: &str,
        cds_position: i64,
        offset: Option<i64>,
    ) -> PyResult<Option<(String, u64)>> {
        let transcript = self.provider.get_transcript(transcript_id).map_err(|e| {
            ferro_typed(
                "ReferenceDataError",
                format!("Transcript not found: {transcript_id}: {e}"),
                &e,
            )
        })?;

        let mapper = CoordinateMapper::new(&transcript);

        // Treat offset=0 as no offset (semantically equivalent)
        let effective_offset = offset.filter(|&o| o != 0);

        let cds_pos = CdsPos {
            base: cds_position,
            offset: effective_offset,
            utr3: false,
            special: None,
        };

        if effective_offset.is_some() {
            // Use intronic-aware conversion
            match mapper.cds_to_genomic_with_intron(&cds_pos) {
                Ok(genomic_pos) => {
                    let chrom = mapper
                        .chromosome()
                        .ok_or_else(|| {
                            ferro_exception(
                                "ProjectionError",
                                "Transcript has no chromosome".to_string(),
                                None,
                                &[],
                            )
                        })?
                        .to_string();
                    Ok(Some((chrom, genomic_pos)))
                }
                Err(e) => Err(ferro_typed(
                    "ProjectionError",
                    format!("Conversion error: {e}"),
                    &e,
                )),
            }
        } else {
            // Use standard conversion
            match mapper.cds_to_genomic(&cds_pos) {
                Ok(Some(genomic_pos)) => {
                    let chrom = mapper
                        .chromosome()
                        .ok_or_else(|| {
                            ferro_exception(
                                "ProjectionError",
                                "Transcript has no chromosome".to_string(),
                                None,
                                &[],
                            )
                        })?
                        .to_string();
                    Ok(Some((chrom, genomic_pos)))
                }
                Ok(None) => Ok(None),
                Err(e) => Err(ferro_typed(
                    "ProjectionError",
                    format!("Conversion error: {e}"),
                    &e,
                )),
            }
        }
    }

    /// Convert a genomic position to CDS position
    ///
    /// Args:
    ///     transcript_id: Transcript accession (e.g., "NM_000088.3")
    ///     genomic_position: Genomic position (1-based)
    ///
    /// Returns:
    ///     Tuple of (cds_position, offset, is_utr3). For exonic positions,
    ///     offset will be None. For intronic positions, offset will contain
    ///     the distance from the nearest exon boundary.
    ///
    /// Raises:
    ///     ValueError: If transcript not found, position is outside transcript bounds,
    ///         or conversion fails
    fn g_to_c(
        &self,
        transcript_id: &str,
        genomic_position: u64,
    ) -> PyResult<(i64, Option<i64>, bool)> {
        let transcript = self.provider.get_transcript(transcript_id).map_err(|e| {
            ferro_typed(
                "ReferenceDataError",
                format!("Transcript not found: {transcript_id}: {e}"),
                &e,
            )
        })?;

        let mapper = CoordinateMapper::new(&transcript);

        match mapper.genomic_to_cds(genomic_position) {
            Ok(Some(cds_pos)) => Ok((cds_pos.base, cds_pos.offset, cds_pos.utr3)),
            Ok(None) => {
                // Position is intronic, try with intronic support
                mapper
                    .genomic_to_cds_intronic(genomic_position)
                    .map(|cds_pos| (cds_pos.base, cds_pos.offset, cds_pos.utr3))
                    .map_err(|e| {
                        ferro_typed(
                            "ProjectionError",
                            format!(
                                "Position {genomic_position} is outside transcript bounds or in \
                                 an unsupported region: {e}"
                            ),
                            &e,
                        )
                    })
            }
            Err(e) => Err(ferro_typed(
                "ProjectionError",
                format!("Conversion error: {e}"),
                &e,
            )),
        }
    }

    /// Convert a CDS position to protein position
    ///
    /// Args:
    ///     transcript_id: Transcript accession (e.g., "NM_000088.3")
    ///     cds_position: CDS position (e.g., 100 for c.100)
    ///
    /// Returns:
    ///     Protein position (1-based codon number)
    ///
    /// Raises:
    ///     ValueError: If transcript not found or position is in UTR/intronic
    fn c_to_p(&self, transcript_id: &str, cds_position: i64) -> PyResult<u64> {
        let transcript = self.provider.get_transcript(transcript_id).map_err(|e| {
            ferro_typed(
                "ReferenceDataError",
                format!("Transcript not found: {transcript_id}: {e}"),
                &e,
            )
        })?;

        let mapper = CoordinateMapper::new(&transcript);

        let cds_pos = CdsPos::new(cds_position);

        mapper
            .cds_to_protein(&cds_pos)
            .map(|prot_pos| prot_pos.number)
            .map_err(|e| ferro_typed("ProjectionError", format!("Conversion error: {e}"), &e))
    }

    /// Convert a CDS position to transcript position
    ///
    /// Args:
    ///     transcript_id: Transcript accession (e.g., "NM_000088.3")
    ///     cds_position: CDS position (e.g., 100 for c.100)
    ///     offset: Optional intronic offset
    ///     utr3: Whether this is a 3' UTR position (c.*N notation)
    ///
    /// Returns:
    ///     Tuple of (transcript_position, offset)
    ///
    /// Raises:
    ///     ValueError: If transcript not found
    #[pyo3(signature = (transcript_id, cds_position, offset=None, utr3=false))]
    fn c_to_n(
        &self,
        transcript_id: &str,
        cds_position: i64,
        offset: Option<i64>,
        utr3: bool,
    ) -> PyResult<(i64, Option<i64>)> {
        let transcript = self.provider.get_transcript(transcript_id).map_err(|e| {
            ferro_typed(
                "ReferenceDataError",
                format!("Transcript not found: {transcript_id}: {e}"),
                &e,
            )
        })?;

        let mapper = CoordinateMapper::new(&transcript);

        let cds_pos = CdsPos {
            base: cds_position,
            offset,
            utr3,
            special: None,
        };

        mapper
            .cds_to_tx(&cds_pos)
            .map(|tx_pos| (tx_pos.base, tx_pos.offset))
            .map_err(|e| ferro_typed("ProjectionError", format!("Conversion error: {e}"), &e))
    }

    /// Convert a transcript position to CDS position
    ///
    /// Args:
    ///     transcript_id: Transcript accession (e.g., "NM_000088.3")
    ///     tx_position: Transcript position (1-based)
    ///     offset: Optional intronic offset
    ///     downstream: Whether this is a downstream position (n.*100 notation for
    ///         positions past the end of the transcript). Defaults to False.
    ///
    /// Returns:
    ///     Tuple of (cds_position, offset, is_utr3)
    ///
    /// Raises:
    ///     ValueError: If transcript not found or has no CDS
    #[pyo3(signature = (transcript_id, tx_position, offset=None, downstream=false))]
    fn n_to_c(
        &self,
        transcript_id: &str,
        tx_position: i64,
        offset: Option<i64>,
        downstream: bool,
    ) -> PyResult<(i64, Option<i64>, bool)> {
        let transcript = self.provider.get_transcript(transcript_id).map_err(|e| {
            ferro_typed(
                "ReferenceDataError",
                format!("Transcript not found: {transcript_id}: {e}"),
                &e,
            )
        })?;

        let mapper = CoordinateMapper::new(&transcript);

        let tx_pos = TxPos {
            base: tx_position,
            offset,
            downstream,
        };

        mapper
            .tx_to_cds(&tx_pos)
            .map(|cds_pos| (cds_pos.base, cds_pos.offset, cds_pos.utr3))
            .map_err(|e| ferro_typed("ProjectionError", format!("Conversion error: {e}"), &e))
    }

    /// Get the strand of a transcript
    ///
    /// Args:
    ///     transcript_id: Transcript accession
    ///
    /// Returns:
    ///     Strand (Plus or Minus)
    fn get_strand(&self, transcript_id: &str) -> PyResult<PyStrand> {
        let transcript = self.provider.get_transcript(transcript_id).map_err(|e| {
            ferro_typed(
                "ReferenceDataError",
                format!("Transcript not found: {transcript_id}: {e}"),
                &e,
            )
        })?;

        Ok(transcript.strand.into())
    }

    /// Get the chromosome of a transcript
    ///
    /// Args:
    ///     transcript_id: Transcript accession
    ///
    /// Returns:
    ///     Chromosome name or None if not set
    fn get_chromosome(&self, transcript_id: &str) -> PyResult<Option<String>> {
        let transcript = self.provider.get_transcript(transcript_id).map_err(|e| {
            ferro_typed(
                "ReferenceDataError",
                format!("Transcript not found: {transcript_id}: {e}"),
                &e,
            )
        })?;

        Ok(transcript.chromosome.clone())
    }

    /// Check if a transcript exists in the reference
    fn has_transcript(&self, transcript_id: &str) -> bool {
        self.provider.get_transcript(transcript_id).is_ok()
    }
}

impl PyCoordinateMapper {
    /// Emit the one-time reduced-capability warning when the backing provider
    /// has no genomic data (#1012), pointing callers at `from_manifest(...)`.
    fn warn_if_reduced_capability(&self, py: Python<'_>) -> PyResult<()> {
        emit_reduced_capability_warning(
            py,
            self.provider.has_genomic_data(),
            self.kind,
            "CoordinateMapper",
            "CoordinateMapper.from_manifest(...)",
        )
    }
}

// ============================================================================
// Enhanced PyHgvsVariant
// ============================================================================

/// ferro-hgvs Python module
#[pymodule]
fn ferro_hgvs(m: &Bound<'_, PyModule>) -> PyResult<()> {
    // Core functions
    m.add_function(wrap_pyfunction!(parse, m)?)?;
    m.add_function(wrap_pyfunction!(normalize, m)?)?;

    // SPDI functions
    m.add_function(wrap_pyfunction!(parse_spdi, m)?)?;
    m.add_function(wrap_pyfunction!(hgvs_to_spdi, m)?)?;
    m.add_function(wrap_pyfunction!(spdi_to_hgvs_variant, m)?)?;

    // Coordinate functions
    m.add_function(wrap_pyfunction!(hgvs_pos_to_index, m)?)?;
    m.add_function(wrap_pyfunction!(index_to_hgvs_pos, m)?)?;

    // MAVE functions
    m.add_function(wrap_pyfunction!(parse_mave_hgvs_variant, m)?)?;
    m.add_function(wrap_pyfunction!(is_mave_short_form_variant, m)?)?;

    // Error handling functions
    m.add_function(wrap_pyfunction!(parse_lenient, m)?)?;

    // rsID functions
    m.add_function(wrap_pyfunction!(parse_rsid_value, m)?)?;
    m.add_function(wrap_pyfunction!(format_rsid_value, m)?)?;

    // VCF functions
    m.add_function(wrap_pyfunction!(vcf_to_genomic_hgvs, m)?)?;

    // Prepare functions
    m.add_function(wrap_pyfunction!(prepare_reference_data, m)?)?;
    m.add_function(wrap_pyfunction!(check_reference_data, m)?)?;

    // Convert-GFF function
    m.add_function(wrap_pyfunction!(convert_gff, m)?)?;

    // Build-Transcript function
    m.add_function(wrap_pyfunction!(build_transcript, m)?)?;

    // Core classes
    m.add_class::<PyHgvsVariant>()?;
    m.add_class::<PyNormalizer>()?;

    // SPDI classes
    m.add_class::<PySpdiVariant>()?;

    // Coordinate classes
    m.add_class::<PyZeroBasedPos>()?;
    m.add_class::<PyOneBasedPos>()?;

    // Equivalence classes
    m.add_class::<PyEquivalenceLevel>()?;
    m.add_class::<PyEquivalenceResult>()?;
    m.add_class::<PyEquivalenceChecker>()?;

    // Effect prediction classes
    m.add_class::<PyConsequence>()?;
    m.add_class::<PyImpact>()?;
    m.add_class::<PyProteinEffect>()?;
    m.add_class::<PyEffectPredictor>()?;

    // MAVE classes
    m.add_class::<PyMaveContext>()?;

    // Batch processing classes
    m.add_class::<PyBatchProgress>()?;
    m.add_class::<PyBatchResult>()?;
    m.add_class::<PyBatchProcessor>()?;

    // Error handling classes
    m.add_class::<PyErrorMode>()?;
    m.add_class::<PyErrorType>()?;
    m.add_class::<PyErrorOverride>()?;
    m.add_class::<PyCorrectionWarning>()?;
    m.add_class::<PyErrorConfig>()?;
    m.add_class::<PyParseResultWithWarnings>()?;
    m.add_class::<PyNormalizationWarning>()?;
    m.add_class::<PyNormalizeResultWithWarnings>()?;

    // Backtranslation classes
    m.add_class::<PyCodonChange>()?;
    m.add_class::<PyCodonTable>()?;
    m.add_class::<PyBacktranslator>()?;

    // rsID classes
    m.add_class::<PyRsIdResult>()?;
    m.add_class::<PyInMemoryRsIdLookup>()?;

    // VCF classes
    m.add_class::<PyVcfRecord>()?;

    // Prepare classes
    m.add_class::<PyPrepareConfig>()?;
    m.add_class::<PyReferenceManifest>()?;

    // Convert-GFF classes
    m.add_class::<PyConvertGffConfig>()?;
    m.add_class::<PyConvertGffReport>()?;

    // Build-Transcript classes
    m.add_class::<PyBuildTranscriptConfig>()?;
    m.add_class::<PyBuildTranscriptReport>()?;

    // Reference classes
    m.add_class::<PyGenomeBuild>()?;
    m.add_class::<PyStrand>()?;

    // Coordinate mapping classes
    m.add_class::<PyCoordinateMapper>()?;

    // Variant projection classes
    m.add_class::<PyVariantProjector>()?;
    m.add_class::<PyVariantProjection>()?;

    // The typed exception hierarchy (FerroError + ParseError / NormalizationError
    // / ReferenceDataError / ProjectionError) is defined in
    // `python/ferro_hgvs/__init__.py`; the Rust raise helpers look those classes
    // up on the module at raise time. Nothing to register here.

    // Add version
    m.add("__version__", env!("CARGO_PKG_VERSION"))?;

    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Closes #395 item 5 — verifies the `From<&NormalizationWarning>
    /// for PyNormalizationWarning` converter at the Rust level.
    /// Complements `tests/python/test_issue_395_normalization_warnings.py`
    /// which exercises the Python-facing surface (under maturin develop).
    #[test]
    fn py_normalization_warning_carries_code_and_message() {
        let cases: Vec<(crate::normalize::NormalizationWarning, &str)> = vec![
            (
                crate::normalize::NormalizationWarning::RefSeqMismatch {
                    stated_ref: "A".to_string(),
                    actual_ref: "T".to_string(),
                    position: "100".to_string(),
                    corrected: true,
                    details: Some("stated A but reference is T".to_string()),
                },
                "REFSEQ_MISMATCH",
            ),
            (
                crate::normalize::NormalizationWarning::OverlapConflict {
                    accession: "NC_000001.11".to_string(),
                    coordinate_system: "g".to_string(),
                    location: "100".to_string(),
                    edit_kinds: vec!["sub".to_string(), "sub".to_string()],
                },
                "OVERLAP_CONFLICTING_EDITS",
            ),
            (
                crate::normalize::NormalizationWarning::PositionPastEnd {
                    accession: "NM_X.1".to_string(),
                    coordinate_system: "c".to_string(),
                    position: "946".to_string(),
                    bound_kind: "cds-end".to_string(),
                    bound_value: 945,
                },
                "POSITION_PAST_END",
            ),
        ];
        for (w, expected_code) in cases {
            let py: PyNormalizationWarning = (&w).into();
            assert_eq!(py.code, expected_code, "code mismatch for {expected_code}");
            assert_eq!(py.message, w.message(), "message round-trip mismatch");
        }
    }

    /// #968: `PyProvider` must forward `infer_genome_build` to its inner provider,
    /// so the wrapped `MultiFasta` provider's assembly-report-derived build
    /// inference reaches the Python path. Complements
    /// `tests/python/test_issue_968_length_build_forwarders.py` (which covers the
    /// sibling `get_sequence_length` forwarder through the Python surface).
    ///
    /// There is no Python-facing surface for `infer_genome_build` — it is consulted
    /// only internally by projection — so the forwarding contract is verified here
    /// at the Rust level (runs under `cargo test --features python`).
    ///
    /// The probe uses the report-only accession `NC_000017.99`: the hardcoded,
    /// accession-only heuristic (the trait default) returns `None` for it, so a
    /// `Some("GRCh38")` answer through the wrapper can only come from the
    /// assembly-report `ContigAliases` the inner `MultiFasta` provider loads —
    /// making the test non-vacuous (it fails if `PyProvider` falls through to the
    /// trait default instead of forwarding).
    #[test]
    fn infer_genome_build_is_forwarded_to_inner_provider() {
        use crate::hgvs::variant::Accession;
        use std::fs;
        use tempfile::tempdir;

        let dir = tempdir().unwrap();
        let d = dir.path();
        // A minimal transcript FASTA (required by `from_manifest`) + its `.fai`.
        fs::write(d.join("tx.fna"), ">NM_000001.1\nACGT\n").unwrap();
        fs::write(d.join("tx.fna.fai"), "NM_000001.1\t4\t13\t4\t5\n").unwrap();
        // A minimal assembly report whose chr17 row uses `.99` — a version the
        // hardcoded heuristic does not know, so only the report can classify it.
        let report = "# Assembly name:  GRCh38.test\n\
            # Sequence-Name\tSequence-Role\tAssigned-Molecule\tAssigned-Molecule-Location/Type\t\
            GenBank-Accn\tRelationship\tRefSeq-Accn\tAssembly-Unit\tSequence-Length\tUCSC-style-name\n\
            17\tassembled-molecule\t17\tChromosome\tCM000679.9\t=\tNC_000017.99\t\
            Primary Assembly\t83257441\tchr17\n";
        fs::write(d.join("assembly_report.txt"), report).unwrap();
        fs::write(
            d.join("manifest.json"),
            r#"{"prepared_at":"test","transcript_fastas":["tx.fna"],"assembly_report":"assembly_report.txt","transcript_count":1,"available_prefixes":[]}"#,
        )
        .unwrap();

        // Build the inner provider directly and wrap it, mirroring how the Python
        // constructors produce a `PyProvider::MultiFasta` (avoids the PyO3 GIL).
        let inner = MultiFastaProvider::from_manifest(d.join("manifest.json"))
            .expect("manifest with an assembly report loads");
        let provider = PyProvider::MultiFasta(Arc::new(inner));

        let future_chr17 = Accession::new("NC", "000017", Some(99));
        // Premise: the accession-only default cannot classify `.99`.
        assert_eq!(
            crate::liftover::aliases::infer_genome_build_from_accession(&future_chr17),
            None,
            "hardcoded heuristic must not know NC_000017.99 (test premise)",
        );
        // Forwarded: the wrapper reaches the inner provider's report-derived table.
        assert_eq!(
            provider.infer_genome_build(&future_chr17),
            Some("GRCh38"),
            "PyProvider must forward infer_genome_build to the inner MultiFasta provider",
        );
    }

    /// #968: `PyProvider` must forward the build-aware `get_transcript_for_accession`
    /// / `get_transcript_for_variant` (#332) to its inner provider. The trait default
    /// self-dispatches to the build-*unaware* `get_transcript`, so without the
    /// forwarder a Python consumer resolving a transcript for a build-bearing
    /// `genomic_context` parent would silently get the primary-build transcript
    /// instead of the parent-build one.
    ///
    /// These methods have no Python-facing surface, so the contract is verified here
    /// at the Rust level (runs under `cargo test --features python`), mirroring the
    /// `infer_genome_build` test above.
    ///
    /// The fixture gives `NM_TEST.1` a GRCh38 primary cdot (contig `NC_000017.11`)
    /// and a deferred GRCh37 secondary cdot (contig `NC_000017.10`). A bare
    /// `get_transcript` resolves the primary build (`.11`); resolving *for* an
    /// accession whose parent is the GRCh37 `NC_000017.10` must probe GRCh37 first
    /// and return the `.10` transcript. The differing chromosome makes the test
    /// non-vacuous — the trait default (bare `get_transcript`) would return `.11`.
    #[test]
    fn get_transcript_for_accession_build_aware_is_forwarded() {
        use crate::hgvs::variant::Accession;
        use std::fs;
        use tempfile::tempdir;

        let dir = tempdir().unwrap();
        let d = dir.path();

        // A 73-base transcript FASTA (matches the exon tx-span 0..73 below).
        let seq = "A".repeat(73);
        fs::write(d.join("tx.fna"), format!(">NM_TEST.1\n{seq}\n")).unwrap();
        fs::write(d.join("tx.fna.fai"), "NM_TEST.1\t73\t11\t73\t74\n").unwrap();

        // Primary GRCh38 cdot: NM_TEST.1 on NC_000017.11.
        fs::write(
            d.join("cdot.json"),
            r#"{"transcripts":{"NM_TEST.1":{"gene_name":"COL1A1","contig":"NC_000017.11",
                "strand":"+","exons":[[50184096,50184169,0,73,"M73"]],
                "start_codon":10,"stop_codon":60}}}"#,
        )
        .unwrap();

        // Deferred GRCh37 secondary cdot: same transcript on NC_000017.10, nested
        // under genome_builds["GRCh37"] (the real GRCh37 cdot shape).
        fs::write(
            d.join("cdot-grch37.json"),
            r#"{"transcripts":{"NM_TEST.1":{"gene_name":"COL1A1","genome_builds":{"GRCh37":{
                "contig":"NC_000017.10","strand":"+","exons":[[48263025,48263098,0,73,"M73"]],
                "cds_start":48263035,"cds_end":48263085}}}}}"#,
        )
        .unwrap();

        fs::write(
            d.join("manifest.json"),
            r#"{"prepared_at":"test","transcript_fastas":["tx.fna"],"cdot_json":"cdot.json",
                "cdot_grch37_json":"cdot-grch37.json","transcript_count":1,"available_prefixes":[]}"#,
        )
        .unwrap();

        let inner = MultiFastaProvider::from_manifest(d.join("manifest.json"))
            .expect("manifest with primary + GRCh37 cdot loads");
        let provider = PyProvider::MultiFasta(Arc::new(inner));

        // Bare resolution → primary GRCh38 build (contig .11).
        let bare = provider.get_transcript("NM_TEST.1").expect("bare resolves");
        assert_eq!(bare.chromosome.as_deref(), Some("NC_000017.11"));

        // Build-aware resolution for a GRCh37 (`NC_000017.10`) parent → probes GRCh37
        // first and returns the .10 transcript. Only reachable if PyProvider forwards
        // get_transcript_for_accession to the inner provider.
        let context = Accession::new("NC", "000017", Some(10));
        let accession = Accession::new("NM", "TEST", Some(1)).with_genomic_context(context);
        let aware = provider
            .get_transcript_for_accession(&accession)
            .expect("build-aware resolution succeeds");
        assert_eq!(
            aware.chromosome.as_deref(),
            Some("NC_000017.10"),
            "PyProvider must forward the build-aware get_transcript_for_accession \
             (GRCh37 parent → .10 transcript), not fall through to the primary-build default",
        );

        // The by-variant sibling delegates to the same build-aware path.
        let variant = crate::parse_hgvs("NC_000017.10(NM_TEST.1):c.1A>G").expect("parse");
        let via_variant = provider
            .get_transcript_for_variant(&variant)
            .expect("build-aware by-variant resolution succeeds");
        assert_eq!(via_variant.chromosome.as_deref(), Some("NC_000017.10"));
    }
}