Metadata-Version: 2.3
Name: just-dna-enricher
Version: 0.5.1
Summary: Network tier for just-dna: fills the source-independent resolution table (cache + Ensembl) that the compiler consumes
Author: Newton Winter
Author-email: Newton Winter <isoutthere@gmail.com>
Requires-Dist: just-dna-format>=0.5.0
Requires-Dist: just-dna-compiler>=0.5.1
Requires-Dist: duckdb>=1.1.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: tenacity>=9.0.0
Requires-Dist: huggingface-hub>=0.34.0
Requires-Dist: typer>=0.12.0
Requires-Dist: ga4gh-vrs>=2.3.3
Requires-Dist: pytest>=9.0.3 ; extra == 'dev'
Requires-Dist: polars>=1.42.0 ; extra == 'dev'
Requires-Dist: openpyxl>=3.1.5 ; extra == 'dev'
Maintainer: Newton Winter
Maintainer-email: Newton Winter <isoutthere@gmail.com>
Requires-Python: >=3.13
Provides-Extra: dev
Description-Content-Type: text/markdown

# just-dna-enricher

The **network tier** of the just-dna workspace. It fills the source-independent resolution table
(`resolution.csv`) that `just-dna-compiler` consumes — Ensembl cache → HuggingFace snapshot → ClinVar
cache → live Ensembl (V2 GraphQL, with a V1 REST fallback on 500/503, and tenacity retries) — then
hands off to a deterministic, offline compile. The ClinVar link sits **after** the Ensembl cache so a
variant both references know keeps its Ensembl `alts`/`source` and no already-compiled module's digest
moves; it is a complementary reference that makes an offline clinical enrich possible without the
14 GB dbSNP cache.

It is the **only** package in the workspace allowed to fetch: `just-dna-format` and
`just-dna-compiler` stay strictly inject-only (CONSTITUTION Goal 2 + the 0.5 amendment). The
dependency arrow points inward — `enricher → compiler → format` — so `httpx` / `huggingface_hub`
never enter the compile path.

```
just-dna-enricher enrich spec/ --strict            # write spec/resolution.csv
just-dna-enricher enrich spec/ --offline           # cache-only, zero egress
just-dna-enricher enrich-and-compile spec/ out/    # enrich, then compile from resolution.csv
just-dna-enricher upload out/coronary --dry-run    # publisher surface ([dev]): plan an HF upload
just-dna-enricher upload out/coronary              # upload compiled artifacts to the HF collection
just-dna-enricher clinvar build --vcf clinvar.vcf.gz --out cv/   # build the ClinVar snapshot ([dev])
just-dna-enricher clinvar publish cv/              # create-or-update datasets/just-dna-seq/clinvar
```

**Publisher / `[dev]` surface.** Snapshot *download* is part of the runtime enrich chain; the
publisher half is *upload* — pushing a compiled module (parquet + manifest) or a built ClinVar
reference snapshot (`data/*.parquet` + `release.json`) to a HuggingFace dataset repo — plus the
ClinVar *builder* (`clinvar build`, which needs `polars`). Install it explicitly:

```
pip install 'just-dna-enricher[dev]'
# or, in this workspace:
uv sync --package just-dna-enricher --group dev
```

Downstream repos (ensembl-mcp, just-dna-lite/pipelines) adopt this package as the single source of
truth for variant resolution instead of maintaining their own query/download code. Lite's
`pipelines v1-port publish` still has a local copy until it adopts the 0.5 enricher tier; the
canonical publisher API is ``just_dna_enricher.upload``.
