balrox 0.1.1

Pure-Rust learned bacterial gene/ORF quality scorer: a dilated temporal CNN (architecture inspired by Balrog) with independently-trained weights on RefSeq CDS, used to rerank/filter spurious ORF calls. Database-free, self-contained inference.
Documentation
# balrox

Pure-Rust learned bacterial **gene / ORF quality scorer**. A dilated temporal
convolutional network reads a candidate ORF's amino-acid sequence and returns
*P(real protein-coding gene)* — used to **rerank / filter spurious ORF calls**.
Self-contained, database-free, no ML runtime, no Python at inference time.

```rust
let m = balrox::Model::embedded();
let s = m.score(b"MSKIVKIIGREIIDSRGNPTVEAEVHLEGGFVGMAAAPSGASTGSRE");   // 0.0..=1.0
```

CLI:

```
balrox orfs.faa
#id   score
orf1  0.996561
```

## Role

Inside a gene-annotation pipeline (e.g. bactars), balrox is an **additive reranker** over
a faithful gene caller (Prodigal / rustygal): the caller still finds ORFs, and balrox
scores them so borderline / shadow / spurious calls can be down-ranked or filtered. It
does **not** replace the gene caller.

## Model & provenance

A dilated temporal CNN: `Embedding(21→C)` → 4 × `[DilatedConv1d(k=7, dilation∈{1,2,4,8})
→ ReLU]` → masked global-average pool → `Linear(C,1)` → sigmoid. Architecture **inspired
by Balrog** (Sommer & Salzberg 2021), but this is an independent clean-room implementation
with its own code and its own weights, **trained from scratch on public RefSeq/GenBank
bacterial CDS** (positives) versus frame-shift-simulated and shadow ORFs (negatives). No
Balrog source code or trained weights were used.

Weights are embedded in the crate (`weights.json`); inference is pure-Rust (embedding
lookup, dilated `conv1d`, ReLU, masked pool, linear head) and was verified to match the
reference PyTorch model to 6 decimal places.

> Note: held-out discrimination is very high against the synthetic negative set; the
> operating threshold should be calibrated on real genomes (real-vs-shadow ORFs) before
> use as a hard filter.

## Changelog

### 0.1.1
- Performance: rewrote the dilated `conv1d` kernel (branch-free contiguous AXPY inner loop +
  flattened weight layout). Multiple× faster single-thread; **bit-identical output** (same
  floating-point accumulation order — verified byte-for-byte on a full proteome).

### 0.1.0
- Initial release: distilled/trained pure-Rust model, gzip-embedded weights, PyTorch-parity verified.

## License

MIT OR Apache-2.0. Training data derived from NCBI RefSeq/GenBank (public domain) and
UniProt (CC-BY 4.0).