gnomancer 0.3.1__tar.gz

gnomancer-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gnomancer contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gnomancer-0.3.1/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: gnomancer
+Version: 0.3.1
+Summary: Local, private deep dive into a consumer raw DNA file (AncestryDNA, 23andMe, MyHeritage, FTDNA, LivingDNA, VCF): QC, haplogroups, traits, pharmacogenomics, one HTML report.
+License: MIT
+Project-URL: Homepage, https://github.com/codebase/gnomancer
+Project-URL: Issues, https://github.com/codebase/gnomancer/issues
+Keywords: dna,genetics,23andme,ancestrydna,haplogroup,pharmacogenomics,clinvar,mcp
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: snps>=2.9
+Requires-Dist: pandas>=2.0
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: mcp>=2; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: mcp>=2; extra == "mcp"
+Dynamic: license-file
+
+# gnomancer
+
+**https://gnomancer.com**
+
+**A private, local deep dive into your raw DNA file.** One command turns an AncestryDNA, 23andMe, MyHeritage,
+FamilyTreeDNA, LivingDNA or VCF export into a readable HTML report: file quality, Y and mitochondrial lineages,
+traits, carrier sites and pharmacogenomics, each with plain-language context and honest limits.
+
+Nothing is uploaded. The only network traffic is the one-time download of public tools and reference files.
+
+```bash
+pipx install gnomancer          # or: pip install gnomancer   (Python 3.10+; Java 11+ for haplogroups and PharmCAT)
+gnomancer setup                 # downloads the open-source tools and reference files once (~250 MB) into ~/.gnomancer
+gnomancer ~/Downloads/AncestryDNA.zip
+open AncestryDNA_analysis/REPORT.html
+```
+
+No Python yet? `curl -fsSL https://gnomancer.com/install.sh | bash` does all of it on macOS/Linux/WSL.
+
+Not sure how to get the file? [gnomancer.com/get-your-data](https://gnomancer.com/get-your-data/) has the steps for every vendor.
+Full install notes, including Windows: [gnomancer.com/install](https://gnomancer.com/install/).
+
+**Use it from your AI assistant.** gnomancer is also an MCP server, so Claude Desktop, Claude Code, Cursor and others can run it and answer questions about your report, all locally:
+
+```bash
+claude mcp add gnomancer -- ~/gnomancer/.venv/bin/gnomancer serve        # Claude Code
+```
+
+Claude Desktop (`claude_desktop_config.json`):
+```json
+{ "mcpServers": { "gnomancer": { "command": "/Users/you/gnomancer/.venv/bin/gnomancer", "args": ["serve"] } } }
+```
+
+Tools: `analyze`, `summary`, `section`, `lookup`, `narrative_prompt` / `set_narrative`, and (only on request) `clinvar_findings`,
+`pharmacogenomics`. The raw file never leaves the machine; only derived results reach the assistant. The repo also doubles
+as a Claude plugin (`skills/gnomancer/SKILL.md`).
+
+![demo report](docs/demo-report.png)
+
+## What you get
+
+`<input>_analysis/`
+
+| File | Contents |
+|---|---|
+| `REPORT.html` | The report: self-contained, light/dark, printable, searchable marker tables |
+| `REPORT.md` | The same content as Markdown |
+| `summary.json` | Everything machine-readable |
+| `chromosome-qc.tsv`, `roh.tsv`, `marker-panel.tsv` | Raw tables |
+| `clinvar-hits.tsv`, `pharmcat-calls.tsv` | ClinVar and PharmCAT results |
+| `yhaplo/`, `haplogrep3/`, `pharmcat/` | Raw tool outputs |
+
+Report sections:
+
+0. **In plain language / At a glance** – a narrative summary (yours or Claude's) and an automatic digest: who the data says you are, what is worth knowing, what is reassuring, sensible next steps
+1. **Overview** – vendor, build, sex, lineages, blood group, quality flags
+2. **Quality** – no-call rate, heterozygosity per chromosome, independent sex inference, contamination flags
+3. **Runs of homozygosity** – parental relatedness and founder-population signal
+4. **Lineages** – Y haplogroup via [yhaplo](https://github.com/23andMe/yhaplo) with a second opinion from [Yleaf](https://github.com/genid/Yleaf) on current YFull/FTDNA/ISOGG trees; mtDNA via [Haplogrep3](https://github.com/genepi/haplogrep3); each with population context
+5. **Multi-site readings** – ABO blood group, lactase persistence, TAS2R38 taster haplotype, APOE (collapsed by default)
+6. **Marker panel** – ~110 curated sites: ancestry-informative, traits, health, carrier, pharmacogenomics
+7. **ClinVar scan** – every typed site checked against [ClinVar](https://www.ncbi.nlm.nih.gov/clinvar/); pathogenic alleles listed with a plausibility score (strand-ambiguous and homozygous-rare calls are flagged as probable array artifacts)
+8. **PharmCAT** – star-allele diplotypes and CPIC phenotypes for 18 pharmacogenes via [PharmCAT](https://github.com/PharmGKB/PharmCAT), with per-gene coverage so you can see how much of each gene the chip actually typed
+9. **Ancestry estimate** (`--ancestry`) – 1000 Genomes population classification via [ezancestry](https://github.com/arvkevi/ezancestry)
+10. **Limits** – what a genotyping array cannot tell you
+
+Health and carrier sections are collapsed by default so that people who would rather not see, say, their APOE
+genotype are not shown it by accident.
+
+## Vendors and quirks
+
+Parsing is delegated to [`snps`](https://github.com/apriha/snps), which detects the vendor from the header and
+normalizes everything. Quirks that are handled:
+
+| Vendor | Quirk | Handling |
+|---|---|---|
+| AncestryDNA | CRLF line endings; chromosomes coded 23=X, 24=Y, 25=PAR, 26=MT; two allele columns; no-call `0`; indels `I`/`D`; diploid-looking `GG` on Y and MT | normalized to X/Y/PAR/MT, haploid single letters, NaN no-calls |
+| AncestryDNA | V1 (~700k sites, 2012–2016) and V2 (~665k, 2016+) type different sites | report marks `not on array` per site |
+| 23andMe | single genotype column; `--` no-call; haploid `A`; internal `i3000001` IDs; v3/v4/v5 chips differ (v5 dropped many PGx sites) | handled; missing sites reported |
+| MyHeritage, FamilyTreeDNA | quoted CSV `RSID,CHROMOSOME,POSITION,RESULT` | handled |
+| FamilyTreeDNA (old) | build 36 exports | remapped to 37; mtDNA call skipped (build 36 MT is not rCRS) |
+| LivingDNA, Genes for Good, tellmeGen, Circle | tab/CSV variants | handled |
+| Build 38 exports, VCF | | remapped to GRCh37 (chain file downloaded once) |
+| Any | occasional probes reported on the reverse strand | panel auto-flips unambiguous SNPs and flags A/T and C/G ones |
+| Any | MT numbering is rCRS (NC_012920) on builds 37/38 | diffed against the bundled rCRS |
+
+## The marker panel
+
+`gnomancer/data/markers.tsv` is a plain TSV anyone can extend:
+
+```
+rsid  category  gene  label  ref  effect  interp0  interp1  interp2  note
+```
+
+`ref`/`effect` are the two alleles on the **GRCh37 forward strand**. `effect` is the allele that gets counted and
+`interp0/1/2` is shown for 0/1/2 copies. Categories: `ancestry`, `trait`, `health`, `carrier`, `pgx`.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the sourcing rules.
+
+Haplogroup context lives in `gnomancer/data/haplogroup_context.tsv`, matched by prefix so a call like `R-M269 / R1b1a2a1a2`
+shows the chain R → R1b → R-M269.
+
+## MCP server
+
+`gnomancer serve` speaks MCP over stdio. Registry manifest: `server.json`; publishing steps: `docs/mcp-registry.md`.
+
+## Options
+
+```
+gnomancer FILE [--out DIR] [--markers TSV] [--no-y] [--no-yleaf] [--no-mt] [--no-clinvar] [--no-pharmcat] [--ancestry]
+          [--summary summary.md] [--ai]
+```
+
+**Plain-language summary.** The report opens with an automatic "at a glance" block built from the results. For a narrative on
+top of that, every run also writes `summary-prompt.md`: paste it to whatever AI assistant you use (Claude, ChatGPT, a local
+model), save the answer as `summary.md`, and re-run with `--summary summary.md`. Or pass `--ai` to have Claude write it
+directly (`pip install anthropic`, credentials via `ANTHROPIC_API_KEY` or `ant auth login`). `--ai` is the one path that sends
+anything off your machine: the structured results in `summary-prompt.md`, never the raw genotype file.
+
+`--ancestry` runs [ezancestry](https://github.com/arvkevi/ezancestry) for a 1000 Genomes population classification.
+ezancestry and Yleaf need Python ≤3.11; `setup.sh` builds a side venv (`.venv-ancestry`) for both automatically when
+`python3.11` is on the PATH, and the CLI uses it when present. First runs download reference data (ezancestry models;
+Yleaf's hg19 reference, ~900 MB).
+
+## Tools used under the hood
+
+| Tool | What it contributes | Source |
+|---|---|---|
+| `snps` | vendor detection, normalization, build remapping | github.com/apriha/snps |
+| yhaplo | Y haplogroup (ISOGG 2016 tree) | github.com/23andMe/yhaplo |
+| Haplogrep3 + PhyloTree 17 | mtDNA haplogroup | github.com/genepi/haplogrep3 |
+| ClinVar | clinically classified variants at every typed site | ncbi.nlm.nih.gov/clinvar |
+| PharmCAT | CPIC/PharmGKB star-allele calling | github.com/PharmGKB/PharmCAT |
+| ezancestry | 1000 Genomes population classification | github.com/arvkevi/ezancestry |
+| Yleaf | second-opinion Y haplogroup on current YFull / FTDNA / ISOGG trees | github.com/genid/Yleaf |
+| rCRS (NC_012920.1) | mitochondrial reference | NCBI |
+
+Evaluated and not used (yet): PLINK 2 (nothing an array file needs that is not already here), ADMIXTURE (needs a multi-GB reference panel),
+pgsc_calc polygenic scores (arrays need imputation first), SNPedia (non-commercial license, no bulk use).
+
+## Try it without your own data
+
+```bash
+.venv/bin/python examples/make_demo.py demo      # synthetic AncestryDNA / 23andMe / MyHeritage files
+.venv/bin/gnomancer demo/demo_AncestryDNA.txt
+```
+
+## Limits, stated plainly
+
+- A genotyping array covers roughly 0.02% of the genome at pre-chosen common sites. It is not a sequence.
+- Negative at a site ≠ gene is normal. BRCA1/2, CFTR and similar are covered at a handful of sites only.
+- Positive at a rare site is often wrong: 40% of variants from consumer raw data were false positives when a clinical
+  lab re-tested them ([Tandy-Connor et al. 2018](https://doi.org/10.1038/gim.2018.38)). The ClinVar section scores each hit for plausibility for this reason.
+- CYP2D6 copy number, full HLA typing and rare variants are invisible.
+- Y and mtDNA resolution stops at the few thousand / few hundred sites typed.
+- Admixture percentages need a reference panel; the vendor's own estimate is the easy source.
+- **This is not medical advice.** Confirm anything that matters with a clinical-grade test and a clinician or genetic counselor.
+
+## Website
+
+`site/` is the landing page at https://gnomancer.com, served as a Cloudflare Worker with static assets (`wrangler.toml`).
+Deploy with `npx wrangler deploy` (Node 22+, `wrangler login` once). It is static: no cookies, no analytics.
+
+## Development
+
+```bash
+./setup.sh            # venv, editable install, tools
+.venv/bin/pytest
+python -m build       # sdist + wheel; releases publish to PyPI from GitHub Actions (trusted publishing)
+```
+
+CI runs the tests and builds a demo report on every push. Real raw-data files and `*_analysis/` folders are
+git-ignored; never commit them.
+
+## Related tools
+
+Local: [`apriha/lineage`](https://github.com/apriha/lineage) (shared segments between kits),
+[PLINK 2](https://github.com/chrchang/plink-ng), ADMIXTURE + 1000 Genomes, [SNPedia](https://www.snpedia.com).
+Web (uploads your data): GEDmatch, James Lick's mthap, Morley's Y-SNP predictor, Promethease, Genetic Genie.
+
+## License
+
+MIT. Haplogroup tools and references have their own licenses: yhaplo (23andMe), Haplogrep3 (GENEPI Innsbruck),
+PhyloTree, ISOGG.
+
+<!-- registry ownership proof -->
+mcp-name: io.github.codebase/gnomancer

gnomancer-0.3.1/README.md

@@ -0,0 +1,186 @@
+# gnomancer
+
+**https://gnomancer.com**
+
+**A private, local deep dive into your raw DNA file.** One command turns an AncestryDNA, 23andMe, MyHeritage,
+FamilyTreeDNA, LivingDNA or VCF export into a readable HTML report: file quality, Y and mitochondrial lineages,
+traits, carrier sites and pharmacogenomics, each with plain-language context and honest limits.
+
+Nothing is uploaded. The only network traffic is the one-time download of public tools and reference files.
+
+```bash
+pipx install gnomancer          # or: pip install gnomancer   (Python 3.10+; Java 11+ for haplogroups and PharmCAT)
+gnomancer setup                 # downloads the open-source tools and reference files once (~250 MB) into ~/.gnomancer
+gnomancer ~/Downloads/AncestryDNA.zip
+open AncestryDNA_analysis/REPORT.html
+```
+
+No Python yet? `curl -fsSL https://gnomancer.com/install.sh | bash` does all of it on macOS/Linux/WSL.
+
+Not sure how to get the file? [gnomancer.com/get-your-data](https://gnomancer.com/get-your-data/) has the steps for every vendor.
+Full install notes, including Windows: [gnomancer.com/install](https://gnomancer.com/install/).
+
+**Use it from your AI assistant.** gnomancer is also an MCP server, so Claude Desktop, Claude Code, Cursor and others can run it and answer questions about your report, all locally:
+
+```bash
+claude mcp add gnomancer -- ~/gnomancer/.venv/bin/gnomancer serve        # Claude Code
+```
+
+Claude Desktop (`claude_desktop_config.json`):
+```json
+{ "mcpServers": { "gnomancer": { "command": "/Users/you/gnomancer/.venv/bin/gnomancer", "args": ["serve"] } } }
+```
+
+Tools: `analyze`, `summary`, `section`, `lookup`, `narrative_prompt` / `set_narrative`, and (only on request) `clinvar_findings`,
+`pharmacogenomics`. The raw file never leaves the machine; only derived results reach the assistant. The repo also doubles
+as a Claude plugin (`skills/gnomancer/SKILL.md`).
+
+![demo report](docs/demo-report.png)
+
+## What you get
+
+`<input>_analysis/`
+
+| File | Contents |
+|---|---|
+| `REPORT.html` | The report: self-contained, light/dark, printable, searchable marker tables |
+| `REPORT.md` | The same content as Markdown |
+| `summary.json` | Everything machine-readable |
+| `chromosome-qc.tsv`, `roh.tsv`, `marker-panel.tsv` | Raw tables |
+| `clinvar-hits.tsv`, `pharmcat-calls.tsv` | ClinVar and PharmCAT results |
+| `yhaplo/`, `haplogrep3/`, `pharmcat/` | Raw tool outputs |
+
+Report sections:
+
+0. **In plain language / At a glance** – a narrative summary (yours or Claude's) and an automatic digest: who the data says you are, what is worth knowing, what is reassuring, sensible next steps
+1. **Overview** – vendor, build, sex, lineages, blood group, quality flags
+2. **Quality** – no-call rate, heterozygosity per chromosome, independent sex inference, contamination flags
+3. **Runs of homozygosity** – parental relatedness and founder-population signal
+4. **Lineages** – Y haplogroup via [yhaplo](https://github.com/23andMe/yhaplo) with a second opinion from [Yleaf](https://github.com/genid/Yleaf) on current YFull/FTDNA/ISOGG trees; mtDNA via [Haplogrep3](https://github.com/genepi/haplogrep3); each with population context
+5. **Multi-site readings** – ABO blood group, lactase persistence, TAS2R38 taster haplotype, APOE (collapsed by default)
+6. **Marker panel** – ~110 curated sites: ancestry-informative, traits, health, carrier, pharmacogenomics
+7. **ClinVar scan** – every typed site checked against [ClinVar](https://www.ncbi.nlm.nih.gov/clinvar/); pathogenic alleles listed with a plausibility score (strand-ambiguous and homozygous-rare calls are flagged as probable array artifacts)
+8. **PharmCAT** – star-allele diplotypes and CPIC phenotypes for 18 pharmacogenes via [PharmCAT](https://github.com/PharmGKB/PharmCAT), with per-gene coverage so you can see how much of each gene the chip actually typed
+9. **Ancestry estimate** (`--ancestry`) – 1000 Genomes population classification via [ezancestry](https://github.com/arvkevi/ezancestry)
+10. **Limits** – what a genotyping array cannot tell you
+
+Health and carrier sections are collapsed by default so that people who would rather not see, say, their APOE
+genotype are not shown it by accident.
+
+## Vendors and quirks
+
+Parsing is delegated to [`snps`](https://github.com/apriha/snps), which detects the vendor from the header and
+normalizes everything. Quirks that are handled:
+
+| Vendor | Quirk | Handling |
+|---|---|---|
+| AncestryDNA | CRLF line endings; chromosomes coded 23=X, 24=Y, 25=PAR, 26=MT; two allele columns; no-call `0`; indels `I`/`D`; diploid-looking `GG` on Y and MT | normalized to X/Y/PAR/MT, haploid single letters, NaN no-calls |
+| AncestryDNA | V1 (~700k sites, 2012–2016) and V2 (~665k, 2016+) type different sites | report marks `not on array` per site |
+| 23andMe | single genotype column; `--` no-call; haploid `A`; internal `i3000001` IDs; v3/v4/v5 chips differ (v5 dropped many PGx sites) | handled; missing sites reported |
+| MyHeritage, FamilyTreeDNA | quoted CSV `RSID,CHROMOSOME,POSITION,RESULT` | handled |
+| FamilyTreeDNA (old) | build 36 exports | remapped to 37; mtDNA call skipped (build 36 MT is not rCRS) |
+| LivingDNA, Genes for Good, tellmeGen, Circle | tab/CSV variants | handled |
+| Build 38 exports, VCF | | remapped to GRCh37 (chain file downloaded once) |
+| Any | occasional probes reported on the reverse strand | panel auto-flips unambiguous SNPs and flags A/T and C/G ones |
+| Any | MT numbering is rCRS (NC_012920) on builds 37/38 | diffed against the bundled rCRS |
+
+## The marker panel
+
+`gnomancer/data/markers.tsv` is a plain TSV anyone can extend:
+
+```
+rsid  category  gene  label  ref  effect  interp0  interp1  interp2  note
+```
+
+`ref`/`effect` are the two alleles on the **GRCh37 forward strand**. `effect` is the allele that gets counted and
+`interp0/1/2` is shown for 0/1/2 copies. Categories: `ancestry`, `trait`, `health`, `carrier`, `pgx`.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the sourcing rules.
+
+Haplogroup context lives in `gnomancer/data/haplogroup_context.tsv`, matched by prefix so a call like `R-M269 / R1b1a2a1a2`
+shows the chain R → R1b → R-M269.
+
+## MCP server
+
+`gnomancer serve` speaks MCP over stdio. Registry manifest: `server.json`; publishing steps: `docs/mcp-registry.md`.
+
+## Options
+
+```
+gnomancer FILE [--out DIR] [--markers TSV] [--no-y] [--no-yleaf] [--no-mt] [--no-clinvar] [--no-pharmcat] [--ancestry]
+          [--summary summary.md] [--ai]
+```
+
+**Plain-language summary.** The report opens with an automatic "at a glance" block built from the results. For a narrative on
+top of that, every run also writes `summary-prompt.md`: paste it to whatever AI assistant you use (Claude, ChatGPT, a local
+model), save the answer as `summary.md`, and re-run with `--summary summary.md`. Or pass `--ai` to have Claude write it
+directly (`pip install anthropic`, credentials via `ANTHROPIC_API_KEY` or `ant auth login`). `--ai` is the one path that sends
+anything off your machine: the structured results in `summary-prompt.md`, never the raw genotype file.
+
+`--ancestry` runs [ezancestry](https://github.com/arvkevi/ezancestry) for a 1000 Genomes population classification.
+ezancestry and Yleaf need Python ≤3.11; `setup.sh` builds a side venv (`.venv-ancestry`) for both automatically when
+`python3.11` is on the PATH, and the CLI uses it when present. First runs download reference data (ezancestry models;
+Yleaf's hg19 reference, ~900 MB).
+
+## Tools used under the hood
+
+| Tool | What it contributes | Source |
+|---|---|---|
+| `snps` | vendor detection, normalization, build remapping | github.com/apriha/snps |
+| yhaplo | Y haplogroup (ISOGG 2016 tree) | github.com/23andMe/yhaplo |
+| Haplogrep3 + PhyloTree 17 | mtDNA haplogroup | github.com/genepi/haplogrep3 |
+| ClinVar | clinically classified variants at every typed site | ncbi.nlm.nih.gov/clinvar |
+| PharmCAT | CPIC/PharmGKB star-allele calling | github.com/PharmGKB/PharmCAT |
+| ezancestry | 1000 Genomes population classification | github.com/arvkevi/ezancestry |
+| Yleaf | second-opinion Y haplogroup on current YFull / FTDNA / ISOGG trees | github.com/genid/Yleaf |
+| rCRS (NC_012920.1) | mitochondrial reference | NCBI |
+
+Evaluated and not used (yet): PLINK 2 (nothing an array file needs that is not already here), ADMIXTURE (needs a multi-GB reference panel),
+pgsc_calc polygenic scores (arrays need imputation first), SNPedia (non-commercial license, no bulk use).
+
+## Try it without your own data
+
+```bash
+.venv/bin/python examples/make_demo.py demo      # synthetic AncestryDNA / 23andMe / MyHeritage files
+.venv/bin/gnomancer demo/demo_AncestryDNA.txt
+```
+
+## Limits, stated plainly
+
+- A genotyping array covers roughly 0.02% of the genome at pre-chosen common sites. It is not a sequence.
+- Negative at a site ≠ gene is normal. BRCA1/2, CFTR and similar are covered at a handful of sites only.
+- Positive at a rare site is often wrong: 40% of variants from consumer raw data were false positives when a clinical
+  lab re-tested them ([Tandy-Connor et al. 2018](https://doi.org/10.1038/gim.2018.38)). The ClinVar section scores each hit for plausibility for this reason.
+- CYP2D6 copy number, full HLA typing and rare variants are invisible.
+- Y and mtDNA resolution stops at the few thousand / few hundred sites typed.
+- Admixture percentages need a reference panel; the vendor's own estimate is the easy source.
+- **This is not medical advice.** Confirm anything that matters with a clinical-grade test and a clinician or genetic counselor.
+
+## Website
+
+`site/` is the landing page at https://gnomancer.com, served as a Cloudflare Worker with static assets (`wrangler.toml`).
+Deploy with `npx wrangler deploy` (Node 22+, `wrangler login` once). It is static: no cookies, no analytics.
+
+## Development
+
+```bash
+./setup.sh            # venv, editable install, tools
+.venv/bin/pytest
+python -m build       # sdist + wheel; releases publish to PyPI from GitHub Actions (trusted publishing)
+```
+
+CI runs the tests and builds a demo report on every push. Real raw-data files and `*_analysis/` folders are
+git-ignored; never commit them.
+
+## Related tools
+
+Local: [`apriha/lineage`](https://github.com/apriha/lineage) (shared segments between kits),
+[PLINK 2](https://github.com/chrchang/plink-ng), ADMIXTURE + 1000 Genomes, [SNPedia](https://www.snpedia.com).
+Web (uploads your data): GEDmatch, James Lick's mthap, Morley's Y-SNP predictor, Promethease, Genetic Genie.
+
+## License
+
+MIT. Haplogroup tools and references have their own licenses: yhaplo (23andMe), Haplogrep3 (GENEPI Innsbruck),
+PhyloTree, ISOGG.
+
+<!-- registry ownership proof -->
+mcp-name: io.github.codebase/gnomancer

gnomancer-0.3.1/gnomancer/__init__.py

@@ -0,0 +1,2 @@
+"""gnomancer: vendor-agnostic analysis of consumer raw DNA files."""
+__version__ = "0.3.1"

gnomancer-0.3.1/gnomancer/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+main()

gnomancer-0.3.1/gnomancer/cli.py

@@ -0,0 +1,155 @@
+"""Command-line entry point: python -m gnomancer <raw file> [--out DIR]"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .load import load
+from .qc import chromosome_table, summary
+from .roh import find_roh, interpret
+from .panel import load_markers, evaluate, combos
+from .haplogroups import call_y, call_mt
+from .report import write
+from . import clinvar as clinvar_mod
+from . import pharmcat as pharmcat_mod
+from . import yleaf as yleaf_mod
+from . import summary as summary_mod
+from .report_html import write_html
+
+from .paths import DATA, ancestry_python
+
+
+def run_ezancestry(inp: Path, loaded) -> dict | None:
+    """Run ezancestry in a separate interpreter (it needs Python <=3.11) if .venv-ancestry exists, else in-process."""
+    import json as _json
+    import subprocess
+    code = ("import json,sys\nfrom snps import SNPs\nr=SNPs(sys.argv[1]).predict_ancestry()\n"
+            "print(json.dumps({k:v for k,v in r.items() if k!='ezancestry_df'}, default=str))")
+    venv_py = ancestry_python()
+    py = str(venv_py) if venv_py else sys.executable
+    try:
+        p = subprocess.run([py, "-c", code, str(inp)], capture_output=True, text=True, timeout=1800)
+        if p.returncode != 0:
+            raise RuntimeError(p.stderr.strip().splitlines()[-1] if p.stderr.strip() else "unknown error")
+        return _json.loads(p.stdout.strip().splitlines()[-1])
+    except Exception as e:  # noqa: BLE001
+        loaded.notes.append(f"ezancestry failed: {e}")
+        return None
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv[:1] == ["serve"]:
+        from .mcp_server import main as serve
+        return serve()
+    if argv[:1] == ["setup"]:
+        from .setup_cmd import run as setup
+        return setup(argv[1:])
+    ap = argparse.ArgumentParser(prog="gnomancer", description="Analyze a consumer raw DNA file locally. Subcommands: `gnomancer setup` (download tools), `gnomancer serve` (MCP server).")
+    ap.add_argument("input", help="raw data file (.txt/.csv/.tsv/.vcf, optionally .zip/.gz)")
+    ap.add_argument("--out", default=None, help="output directory (default: <input>_analysis)")
+    ap.add_argument("--markers", default=str(DATA / "markers.tsv"), help="marker panel TSV")
+    ap.add_argument("--no-y", action="store_true", help="skip Y haplogroup")
+    ap.add_argument("--no-mt", action="store_true", help="skip mtDNA haplogroup")
+    ap.add_argument("--ancestry", action="store_true", help="run ezancestry population prediction (uses .venv-ancestry if present)")
+    ap.add_argument("--no-clinvar", action="store_true", help="skip the ClinVar scan")
+    ap.add_argument("--no-yleaf", action="store_true", help="skip the Yleaf second-opinion Y call")
+    ap.add_argument("--no-pharmcat", action="store_true", help="skip PharmCAT")
+    ap.add_argument("--summary", default=None, help="Markdown/text file with a narrative summary (e.g. written by your AI agent) to show at the top of the report")
+    ap.add_argument("--ai", action="store_true", help="have Claude write the narrative summary (sends the structured results, not the raw file, to the Anthropic API; needs credentials)")
+    ap.add_argument("--version", action="version", version=__version__)
+    a = ap.parse_args(argv)
+    run_args = argv
+
+    inp = Path(a.input)
+    out = Path(a.out) if a.out else inp.with_name(inp.stem.replace(".", "_") + "_analysis")
+    out.mkdir(parents=True, exist_ok=True)
+
+    print(f"[1/6] loading {inp} ...", file=sys.stderr)
+    loaded = load(str(inp))
+    df = loaded.df
+    print(f"      {loaded.source}, build {loaded.build}, {loaded.count:,} SNPs, sex {loaded.sex or '?'}", file=sys.stderr)
+
+    print("[2/6] quality metrics ...", file=sys.stderr)
+    ct = chromosome_table(df)
+    qc = summary(df, ct, loaded.sex)
+    ct.to_csv(out / "chromosome-qc.tsv", sep="\t", index=False)
+
+    print("[3/6] runs of homozygosity ...", file=sys.stderr)
+    roh = find_roh(df)
+    roh.to_csv(out / "roh.tsv", sep="\t", index=False)
+    roh_text = interpret(roh)
+
+    print("[4/6] marker panel ...", file=sys.stderr)
+    markers = load_markers(Path(a.markers))
+    panel = evaluate(df, markers)
+    panel.to_csv(out / "marker-panel.tsv", sep="\t", index=False)
+    combo = combos(df)
+
+    is_male = qc["sex_inferred"] == "Male"
+    y = dict(error="skipped (sample is not male)" if not is_male else "skipped (--no-y)")
+    if is_male and not a.no_y:
+        print("[5/6] Y haplogroup (yhaplo) ...", file=sys.stderr)
+        y = call_y(df, out)
+        if not a.no_yleaf:
+            print("      second opinion on current trees (Yleaf) ...", file=sys.stderr)
+            y["yleaf"] = yleaf_mod.run(df, out)
+    mt = dict(error="skipped (--no-mt)")
+    if not a.no_mt:
+        print("[5/6] mtDNA haplogroup (haplogrep3) ...", file=sys.stderr)
+        mt = call_mt(df, out, loaded.build_original)
+
+    cv = dict(available=False, hits=None, note="skipped (--no-clinvar)")
+    if not a.no_clinvar:
+        print("[6/8] ClinVar scan of every typed site ...", file=sys.stderr)
+        cv = clinvar_mod.scan(df)
+        if cv["available"] and cv["hits"] is not None and not cv["hits"].empty:
+            cv["hits"].to_csv(out / "clinvar-hits.tsv", sep="\t", index=False)
+    cv_text = clinvar_mod.interpret(cv) if not a.no_clinvar else cv["note"]
+    pc = dict(available=False, calls=None, error="skipped (--no-pharmcat)", stats={})
+    if not a.no_pharmcat:
+        print("[7/8] PharmCAT pharmacogenomics ...", file=sys.stderr)
+        pc = pharmcat_mod.run(df, out)
+        if pc.get("calls") is not None and not pc["calls"].empty:
+            pc["calls"].to_csv(out / "pharmcat-calls.tsv", sep="\t", index=False)
+    pc_text = pharmcat_mod.interpret(pc) if not a.no_pharmcat else pc["error"]
+    ancestry = None
+    if a.ancestry:
+        print("[8/8] ancestry prediction (ezancestry) ...", file=sys.stderr)
+        ancestry = run_ezancestry(inp, loaded)
+
+    glance = summary_mod.at_a_glance(loaded, qc, roh, roh_text, combo, y, mt, ancestry, panel, cv, pc)
+    prompt = summary_mod.build_prompt(glance, combo, y, mt, ancestry, panel, cv, pc, qc)
+    summary_mod.write_prompt_file(out, prompt)
+    narrative = None
+    if a.summary:
+        narrative = Path(a.summary).read_text().strip()
+    elif a.ai:
+        print("      narrative summary (Claude) ...", file=sys.stderr)
+        try:
+            narrative = summary_mod.ai_summary(prompt)
+            (out / "summary.md").write_text(narrative + "\n")
+        except Exception as e:  # noqa: BLE001
+            loaded.notes.append(f"AI summary failed: {e}")
+    extra = dict(clinvar=cv, clinvar_text=cv_text, pharmcat=pc, pharmcat_text=pc_text, glance=glance, narrative=narrative)
+    rep = write(out / "REPORT.md", loaded, qc, ct, roh, roh_text, panel, combo, y, mt, ancestry, extra)
+    html = write_html(out / "REPORT.html", loaded, qc, ct, roh, roh_text, panel, combo, y, mt, ancestry, input_name=inp.name, extra=extra)
+    json.dump(dict(input=str(inp.resolve()), args=[str(Path(x).resolve()) if Path(x).exists() else x for x in run_args],
+                   report_html=str((out / "REPORT.html").resolve()), report_md=str((out / "REPORT.md").resolve()), glance=glance,
+                   source=loaded.source, build=loaded.build, count=loaded.count, qc=qc,
+                   roh_total_mb=float(roh.length_mb.sum()) if not roh.empty else 0.0, y=y, mt=mt,
+                   combos=combo, ancestry=ancestry, notes=loaded.notes,
+                   clinvar=dict(sites_in_clinvar=cv.get("sites_in_clinvar"), pathogenic_sites_typed=cv.get("pathogenic_sites_typed"),
+                                hits=(cv["hits"].to_dict("records") if cv.get("hits") is not None and not cv["hits"].empty else [])),
+                   pharmcat=dict(stats={k: v for k, v in pc.get("stats", {}).items() if k != "genes"}, error=pc.get("error"),
+                                 calls=(pc["calls"].to_dict("records") if pc.get("calls") is not None and not pc["calls"].empty else []))),
+              open(out / "summary.json", "w"), indent=1, default=str)
+    print(f"\nReport: {html}\n        {rep}", file=sys.stderr)
+    if y.get("haplogroup"):
+        print(f"Y: {y['haplogroup']}   ", end="", file=sys.stderr)
+    if mt.get("haplogroup"):
+        print(f"MT: {mt['haplogroup']}", end="", file=sys.stderr)
+    print(file=sys.stderr)