RettX Mutation Analysis Library
A Python library for extracting and validating genetic mutations from clinical reports using an AI-powered agentic pipeline. Supports 6 Rett Syndrome-related genes across multiple languages, returning fully normalized HGVS nomenclature with genomic coordinates on both GRCh37 and GRCh38 assemblies.
🚀 Quick Start
Installation
pip install rettxmutation
Basic Usage
import asyncio
from rettxmutation import RettxServices, DefaultConfig
async def extract():
config = DefaultConfig() # loads from .env / environment variables
with RettxServices(config) as services:
result = await services.agent_extraction_service.extract_mutations(
"The patient carries the mutation NM_004992.4:c.916C>T (p.Arg306Cys) in MECP2."
)
for key, mutation in result.mutations.items():
pt = mutation.primary_transcript
print(f"Gene: {pt.gene_id}")
print(f"Transcript: {pt.hgvs_transcript_variant}")
print(f"Protein: {pt.protein_consequence_tlr}")
print(f"Type: {mutation.variant_type}")
for assembly, coord in mutation.genomic_coordinates.items():
print(f"{assembly}: {coord.hgvs} (pos {coord.start:,}–{coord.end:,})")
asyncio.run(extract())
CLI Example
python examples/extract_from_file.py path/to/genetic_report.txt --verbose
✨ Key Features
- 🧬 Multi-Gene Support: MECP2, FOXG1, SLC6A1, CDKL5, EIF2B2, MEF2C — with curated RefSeq transcripts
- 🌍 Multilingual: Processes reports in English, Spanish, Greek, Turkish, and more
- 🤖 Agentic Extraction: Azure OpenAI-powered agent with tool-calling (gene registry lookup, variant validation, complex variant handling)
- ✅ HGVS Validation: Every mutation is validated via VariantValidator with automatic coordinate liftover (GRCh37 ↔ GRCh38)
- 🔒 PHI Redaction: Automatic removal of personal health information before LLM processing
- ⚡ Production Ready: Type-safe Pydantic v2 models, exponential backoff, connection pooling
- 🔄 Dual Assembly Output: Every mutation includes genomic coordinates on both GRCh37 and GRCh38
- 🏗️ Modular Architecture: Lazy-initialized services with dependency injection and context manager support
🧬 Supported Genes
| Gene | Chromosome | Primary Transcript | Condition |
|---|---|---|---|
| MECP2 | Xq28 | NM_004992.4 (+NM_001110792.2) | Classic Rett Syndrome |
| FOXG1 | 14q12 | NM_005249.5 | Congenital variant Rett |
| SLC6A1 | 3p25.3 | NM_003042.4 | Myoclonic-atonic epilepsy |
| CDKL5 | Xp22.13 | NM_001323289.2 | CDKL5 deficiency disorder |
| EIF2B2 | 14q24.3 | NM_014239.4 | Vanishing white matter disease |
| MEF2C | 5q14.3 | NM_002397.5 (+NM_001131005.2) | MEF2C haploinsufficiency |
📊 Output Structure
The ExtractionResult contains:
ExtractionResult
├── mutations: Dict[str, GeneMutation] ← keyed by GRCh38 genomic HGVS
├── genes_detected: List[str] ← e.g. ["MECP2"]
├── extraction_log: List[str] ← agent reasoning trace
└── tool_calls_count: int ← total tool invocations
Each GeneMutation provides:
GeneMutation
├── genomic_coordinates:
│ ├── GRCh38: { assembly, hgvs, start, end, size }
│ └── GRCh37: { assembly, hgvs, start, end, size }
├── variant_type: "SNV" | "deletion" | "duplication" | "insertion" | "indel"
├── primary_transcript:
│ ├── gene_id, transcript_id
│ ├── hgvs_transcript_variant ← e.g. NM_004992.4:c.916C>T
│ ├── protein_consequence_tlr ← e.g. NP_004983.1:p.(Arg306Cys)
│ └── protein_consequence_slr ← e.g. NP_004983.1:p.(R306C)
└── secondary_transcript (optional)
🛠️ Requirements
Python Version
- Python 3.8 or higher
Azure Services
| Service | Required? | Purpose |
|---|---|---|
| Azure OpenAI | ✅ Required | Agentic mutation extraction |
| Azure AI Search | Optional | Semantic search for keyword detection |
| Azure Cognitive Services | Optional | Text analytics enrichment |
Environment Variables
# Required — Azure OpenAI
RETTX_OPENAI_ENDPOINT=https://your-openai.openai.azure.com/
RETTX_OPENAI_KEY=your-openai-key
RETTX_OPENAI_MODEL_NAME=gpt-4o # deployment name
# Optional — Agent model (defaults to RETTX_OPENAI_MODEL_NAME if not set)
RETTX_OPENAI_AGENT_DEPLOYMENT=gpt-4o # agent-specific deployment
RETTX_OPENAI_AGENT_MODEL_VERSION=2024-11-20
# Optional — Embeddings
RETTX_EMBEDDING_DEPLOYMENT=text-embedding-ada-002
# Optional — Azure AI Search
RETTX_AI_SEARCH_SERVICE=your-search-service
RETTX_AI_SEARCH_API_KEY=your-search-key
RETTX_AI_SEARCH_INDEX_NAME=your-index-name
# Optional — Azure Cognitive Services
RETTX_COGNITIVE_SERVICES_ENDPOINT=https://your-cognitive-services.cognitiveservices.azure.com/
RETTX_COGNITIVE_SERVICES_KEY=your-cognitive-services-key
📋 Processing Pipeline
The agentic extraction pipeline works as follows:
Input Text (any language)
│
▼
┌──────────────────────┐
│ PHI Redaction │ Remove patient names, DOBs, IDs
└──────────┬───────────┘
▼
┌──────────────────────┐
│ AI Agent (OpenAI) │ Reads text, identifies mutations
│ │
│ Tools available: │
│ • lookup_gene_registry → gene info + RefSeq transcripts
│ • validate_variant → HGVS validation + coordinates
│ • validate_complex → CNV / genomic coordinate validation
└──────────┬───────────┘
▼
┌──────────────────────┐
│ Structured Output │ ExtractionResult with validated
│ │ GeneMutation objects
└──────────────────────┘
Key capabilities:
- Ensembl → RefSeq remapping: Handles reports using Ensembl transcripts (ENST*) by using genomic coordinates
- Minus-strand awareness: Correctly complements alleles for genes on the reverse strand
- Old nomenclature: Normalizes legacy formats (e.g.,
502C->T,R168X) to current HGVS
💻 Available Services
All services are lazily initialized via RettxServices:
with RettxServices(config) as services:
# Core extraction
services.agent_extraction_service # AI-powered mutation extraction
# Validation & analysis
services.variant_validator_service # HGVS validation + coordinate liftover
services.mutation_tokenizator # Mutation string tokenization
# Search & embeddings
services.embedding_service # Azure OpenAI embeddings
services.ai_search_service # Azure AI Search integration
services.keyword_detector_service # Multi-layer keyword detection
Direct Variant Validation
with RettxServices(config) as services:
vvs = services.variant_validator_service
# Validate a transcript-level variant
result = vvs.get_gene_mutation_from_transcript("NM_004992.4:c.916C>T")
print(result.primary_transcript.protein_consequence_tlr)
# → NP_004983.1:p.(Arg306Cys)
# Validate a complex / genomic variant
result = vvs.create_gene_mutation_from_complex_variant(
assembly_build="GRCh38",
assembly_refseq="NC_000023.11",
variant_description="NC_000023.11:g.154030912G>A",
gene_symbol="MECP2"
)
Custom Configuration
class MyConfig:
"""Custom configuration for production (e.g., from Key Vault)."""
RETTX_OPENAI_ENDPOINT = "https://my-openai.openai.azure.com/"
RETTX_OPENAI_KEY = get_secret("openai-key")
RETTX_OPENAI_MODEL_NAME = "gpt-4o"
# Only set fields needed for the services you use
with RettxServices(MyConfig()) as services:
result = await services.agent_extraction_service.extract_mutations(text)
🧪 Golden Test Suite
The library includes a comprehensive golden test suite with 11 real-world genetic reports:
| Gene | Variant Type | Language | Key Feature |
|---|---|---|---|
| MECP2 | SNV, splicing, deletion, duplication | EN, ES, EL, TR | Multiple transcripts |
| FOXG1 | Frameshift deletion | TR | Non-MECP2 gene |
| SLC6A1 | Whole-gene CNV (~20kb) | ES | Copy number variant |
Run golden tests:
# Mock mode (no API calls, uses recorded responses)
python -m pytest tests/golden/ --golden-mode=mock -v
# Live mode (calls real APIs)
python -m pytest tests/golden/ --golden-mode=live -v
🎯 Use Cases
- 🏥 Clinical Genetics: Extract mutations from diagnostic reports in any language
- 🔬 Research: Analyze genetic data across Rett Syndrome and related conditions
- 📊 Patient Registries: Populate genetic databases with normalized HGVS nomenclature
- 🤖 Bioinformatics Pipelines: Integrate as a library or via the CLI example
- 📱 Clinical Applications: Build tools with structured mutation data (dual-assembly coordinates)
🔧 Reliability
- Exponential Backoff: Automatic retry for VariantValidator and OpenAI API calls
- Graceful Degradation: Optional services (AI Search, Cognitive Services) degrade gracefully
- PHI Redaction: Patient data is stripped before any LLM processing
- Type Safety: Pydantic v2 models with runtime validation
- Context Manager: Automatic resource cleanup via
withstatement - Comprehensive Logging: Structured extraction logs with tool call traces
🤝 Contributing
We welcome contributions! Please see our GitHub repository for:
- Issue reporting
- Feature requests
- Pull request guidelines
- Development setup instructions
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🆘 Support
- Issues: GitHub Issues
- Documentation: API Documentation
- Contact: procha@rettsyndrome.eu
🔮 Roadmap
- Additional Genes: Expand the gene registry beyond the current 6 genes
- Batch Processing: Process multiple reports in parallel with rate limiting
- Confidence Scoring: Per-mutation confidence metrics based on report quality
- Structured Report Parsing: Native support for VCF, JSON, and HL7 FHIR formats
- Cloud Deployment: Docker containers and Azure deployment templates
1 maintainer
Metadata
1 maintainer
Release files for rettxmutation 0.3.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| rettxmutation-0.3.6.tar.gz | 76.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| rettxmutation-0.3.6-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 148.7 kB
Release files / rettxmutation-0.3.6.tar.gz
| Download URL | rettxmutation-0.3.6.tar.gz |
|---|---|
| Size | 76.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
92137e0fe7f14843d1293b468486467a50095784c5a6d09888f19d985597a84d
|
|
BLAKE2b-256 checksum How to use checksums |
834986b011ce351bb9b6746932c6e080f0248f1ab21916f1007a6ad94a3b68d7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 18, 2026.
Transparency logRelease files / rettxmutation-0.3.6-py3-none-any.whl
| Download URL | rettxmutation-0.3.6-py3-none-any.whl |
|---|---|
| Size | 72.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1459f4357aad9c58b4c8795e603bb522f12604e8d81d83b54ea074271582b0a5
|
|
BLAKE2b-256 checksum How to use checksums |
2ff560d13776610172e75fcb96fc785d418051aa5f42f25208d7256deb1bf628
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 18, 2026.
Transparency log
