Metadata-Version: 2.4
Name: bioforge
Version: 2.3.0
Summary: High-performance bioinformatics engine for Edge Computing — 5-bit encoding, vectorised NumPy core, optional C backend
Author-email: Aarón Aranda Torrijos <noe9601@gmail.com>
License: # PolyForm Noncommercial License 1.0.0
        
        <https://polyformproject.org/licenses/noncommercial/1.0.0>
        
        Required Notice: Copyright 2026 Aarón Aranda Torrijos
        (https://github.com/erlanders177/bioforge)
        
        ## Acceptance
        
        In order to get any license under these terms, you must agree
        to them as both strict obligations and conditions to all
        your licenses.
        
        ## Copyright License
        
        The licensor grants you a copyright license for the
        software to do everything you might do with the software
        that would otherwise infringe the licensor's copyright
        in it for any permitted purpose.  However, you may
        only distribute the software according to [Distribution
        License](#distribution-license) and make changes or new works
        based on the software according to [Changes and New Works
        License](#changes-and-new-works-license).
        
        ## Distribution License
        
        The licensor grants you an additional copyright license
        to distribute copies of the software.  Your license
        to distribute covers distributing the software with
        changes and new works permitted by [Changes and New Works
        License](#changes-and-new-works-license).
        
        ## Notices
        
        You must ensure that anyone who gets a copy of any part of
        the software from you also gets a copy of these terms or the
        URL for them above, as well as copies of any plain-text lines
        beginning with `Required Notice:` that the licensor provided
        with the software.  For example:
        
        > Required Notice: Copyright 2026 Aarón Aranda Torrijos
        > (https://github.com/erlanders177/bioforge)
        
        ## Changes and New Works License
        
        The licensor grants you an additional copyright license to
        make changes and new works based on the software for any
        permitted purpose.
        
        ## Patent License
        
        The licensor grants you a patent license for the software that
        covers patent claims the licensor can license, or becomes able
        to license, that you would infringe by using the software.
        
        ## Noncommercial Purposes
        
        Any noncommercial purpose is a permitted purpose.
        
        ## Personal Uses
        
        Personal use for research, experiment, and testing for
        the benefit of public knowledge, personal study, private
        entertainment, hobby projects, amateur pursuits, or religious
        observance, without any anticipated commercial application,
        is use for a permitted purpose.
        
        ## Noncommercial Organizations
        
        Use by any charitable organization, educational institution,
        public research organization, public safety or health
        organization, environmental protection organization,
        or government institution is use for a permitted purpose
        regardless of the source of funding or obligations resulting
        from the funding.
        
        ## Fair Use
        
        You may have "fair use" rights for the software under the
        law. These terms do not limit them.
        
        ## No Other Rights
        
        These terms do not allow you to sublicense or transfer any of
        your licenses to anyone else, or prevent the licensor from
        granting licenses to anyone else.  These terms do not imply
        any other licenses.
        
        ## Patent Defense
        
        If you make any written claim that the software infringes or
        contributes to infringement of any patent, your patent license
        for the software granted under these terms ends immediately. If
        your company makes such a claim, your patent license ends
        immediately for work on behalf of your company.
        
        ## Violations
        
        The first time you are notified in writing that you have
        violated any of these terms, or done anything with the software
        not covered by your licenses, your licenses can nonetheless
        continue if you come into full compliance with these terms,
        and take practical steps to correct past violations, within
        32 days of receiving notice.  Otherwise, all your licenses
        end immediately.
        
        ## No Liability
        
        ***As far as the law allows, the software comes as is, without
        any warranty or condition, and the licensor will not be liable
        to you for any damages arising out of these terms or the use
        or nature of the software, under any kind of legal claim.***
        
        ## Definitions
        
        The **licensor** is the individual or entity offering these
        terms, and the **software** is the software the licensor makes
        available under these terms.
        
        **You** refers to the individual or entity agreeing to these
        terms.
        
        **Your company** is any legal entity, sole proprietorship,
        or other kind of organization that you work for, plus all
        organizations that have control over, are under the control of,
        or are under common control with that organization.  **Control**
        means ownership of substantially all the assets of an entity,
        or the power to direct its management and policies by vote,
        contract, or otherwise.  Control can be direct or indirect.
        
        **Your licenses** are all the licenses granted to you for the
        software under these terms.
        
        **Use** means anything you do with the software requiring one
        of your licenses.
        
        ---
        
        # Traducción al español (informativa)
        
        > **Nota:** Esta traducción se ofrece únicamente como referencia.
        > El texto legalmente vinculante es el inglés que aparece arriba.
        
        ---
        
        # Licencia PolyForm No Comercial 1.0.0
        
        <https://polyformproject.org/licenses/noncommercial/1.0.0>
        
        Aviso obligatorio: Copyright 2026 Aarón Aranda Torrijos
        (https://github.com/erlanders177/bioforge)
        
        ## Aceptación
        
        Para obtener cualquier licencia bajo estos términos, debes aceptarlos
        como obligaciones estrictas y condiciones de todas tus licencias.
        
        ## Licencia de derechos de autor
        
        El licenciante te otorga una licencia de derechos de autor sobre el
        software para hacer todo lo que podrías hacer con él y que de otro modo
        infringiría los derechos de autor del licenciante, para cualquier
        propósito permitido. Sin embargo, solo puedes distribuir el software
        según la [Licencia de distribución](#licencia-de-distribución) y realizar
        cambios u obras nuevas basadas en el software según la
        [Licencia de cambios y obras nuevas](#licencia-de-cambios-y-obras-nuevas).
        
        ## Licencia de distribución
        
        El licenciante te otorga una licencia adicional de derechos de autor
        para distribuir copias del software. Tu licencia de distribución cubre
        la distribución del software con los cambios y obras nuevas permitidos
        por la Licencia de cambios y obras nuevas.
        
        ## Avisos
        
        Debes asegurarte de que cualquier persona que reciba una copia de
        cualquier parte del software de tu parte también reciba una copia de
        estos términos o la URL indicada arriba, así como copias de las líneas
        de texto plano que comiencen con `Aviso obligatorio:` que el licenciante
        haya proporcionado con el software. Por ejemplo:
        
        > Aviso obligatorio: Copyright 2026 Aarón Aranda Torrijos
        > (https://github.com/erlanders177/bioforge)
        
        ## Licencia de cambios y obras nuevas
        
        El licenciante te otorga una licencia adicional de derechos de autor
        para realizar cambios y obras nuevas basadas en el software para
        cualquier propósito permitido.
        
        ## Licencia de patentes
        
        El licenciante te otorga una licencia de patentes sobre el software que
        cubre las reivindicaciones de patentes que el licenciante puede
        licenciar, o llegue a poder licenciar, que infringirías al usar el
        software.
        
        ## Propósitos no comerciales
        
        Cualquier propósito no comercial es un propósito permitido.
        
        ## Usos personales
        
        El uso personal para investigación, experimentación y pruebas en
        beneficio del conocimiento público, estudio personal, entretenimiento
        privado, proyectos de aficionado, actividades de amateur u observancia
        religiosa, sin ninguna aplicación comercial prevista, es un uso para un
        propósito permitido.
        
        ## Organizaciones no comerciales
        
        El uso por parte de cualquier organización benéfica, institución
        educativa, organización de investigación pública, organización de
        seguridad o salud pública, organización de protección ambiental o
        institución gubernamental es un uso para un propósito permitido,
        independientemente de la fuente de financiación u obligaciones
        derivadas de dicha financiación.
        
        ## Uso legítimo
        
        Puedes tener derechos de "uso legítimo" sobre el software según la
        ley. Estos términos no los limitan.
        
        ## Ningún otro derecho
        
        Estos términos no te permiten sublicenciar ni transferir ninguna de
        tus licencias a ninguna otra persona, ni impiden que el licenciante
        otorgue licencias a otras personas. Estos términos no implican ninguna
        otra licencia.
        
        ## Defensa de patentes
        
        Si realizas cualquier reclamación por escrito de que el software
        infringe o contribuye a la infracción de cualquier patente, tu licencia
        de patentes sobre el software otorgada bajo estos términos termina
        inmediatamente. Si tu empresa realiza dicha reclamación, tu licencia
        de patentes termina inmediatamente para el trabajo en nombre de tu
        empresa.
        
        ## Infracciones
        
        La primera vez que se te notifique por escrito que has infringido
        alguno de estos términos, o que has hecho algo con el software no
        cubierto por tus licencias, tus licencias pueden no obstante continuar
        si cumples completamente con estos términos y tomas medidas prácticas
        para corregir las infracciones pasadas, dentro de los 32 días
        siguientes a la recepción de la notificación. De lo contrario, todas
        tus licencias terminan inmediatamente.
        
        ## Sin responsabilidad
        
        ***En la medida en que lo permita la ley, el software se proporciona
        tal cual, sin ninguna garantía ni condición, y el licenciante no será
        responsable ante ti por ningún daño derivado de estos términos o del
        uso o la naturaleza del software, bajo ningún tipo de reclamación
        legal.***
        
        ## Definiciones
        
        El **licenciante** es la persona o entidad que ofrece estos términos,
        y el **software** es el software que el licenciante pone a disposición
        bajo estos términos.
        
        **Tú** hace referencia a la persona o entidad que acepta estos
        términos.
        
        **Tu empresa** es cualquier entidad legal, empresa unipersonal u otro
        tipo de organización para la que trabajas, más todas las organizaciones
        que tienen control sobre ella, están bajo su control, o están bajo
        control común con ella. **Control** significa la titularidad de
        prácticamente todos los activos de una entidad, o el poder de dirigir
        su gestión y políticas mediante voto, contrato u otro medio. El control
        puede ser directo o indirecto.
        
        **Tus licencias** son todas las licencias que se te otorgan sobre el
        software bajo estos términos.
        
        **Uso** significa cualquier cosa que hagas con el software que requiera
        una de tus licencias.
        
Project-URL: Homepage, https://github.com/erlanders177/bioforge
Project-URL: Source, https://github.com/erlanders177/bioforge
Project-URL: Issues, https://github.com/erlanders177/bioforge/issues
Keywords: bioinformatics,genomics,sequence-analysis,edge-computing,numpy,fastq,fasta
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
Requires-Dist: hypothesis>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pyright>=1.1; extra == "dev"
Requires-Dist: pre-commit>=3.7; extra == "dev"
Provides-Extra: profile
Requires-Dist: scalene>=1.5; extra == "profile"
Requires-Dist: py-spy>=0.3; extra == "profile"
Provides-Extra: bench
Requires-Dist: biopython>=1.80; extra == "bench"
Requires-Dist: psutil>=5.9; extra == "bench"
Dynamic: license-file

# BioForge — High-Performance Bioinformatics Engine

[![Tests](https://github.com/erlanders177/bioforge/actions/workflows/tests.yml/badge.svg)](https://github.com/erlanders177/bioforge/actions/workflows/tests.yml)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-PolyForm_NC_1.0-blue)](LICENSE)

A bioinformatics engine built for **Edge Computing**.  
No Biopython. No heavy dependencies. NumPy core + optional C engine for maximum speed.

---

## Why this exists

Most bioinformatics tools are built for servers with gigabytes of RAM.  
BioForge was built for the opposite: low-power hardware, minimal footprint,
maximum speed — running genetic analysis **offline and locally**.

Two core rules:
- **Zero Python loops** in the hot path — every operation is vectorised with NumPy.
- **5-bit encoding** — every biological symbol fits in 5 bits, saving 37.5% memory vs ASCII.

---

## Key numbers

| Operation | Result |
|-----------|--------|
| Memory (30M bases) | **18.75 MB** (37.5% less than plain ASCII) |
| Translation throughput | **~5 M amino acids / second** (NumPy) · **~27× faster** with C engine |
| NW alignment 1000×1000 nt | **~165 ms** (NumPy) · **~29× faster** with C engine |
| FASTA ingestion (C batch parser) | **~80 M bases / second** |
| FASTQ ingestion (C batch parser) | **~14 M bases / s · ~94 K reads / s** |
| QC filter 200 K reads (columnar) | **0.28 s** — **18.6× faster** than per-record |
| vs Biopython — QC filter | **~5–6× faster**, identical result |
| vs Biopython — load all in RAM | **~6.9× less memory** (115 MB vs 801 MB) · ~9.5× faster |
| Compressed input | **`.gz` read transparently in C** (zlib, static-linked) |
| Dependencies | **NumPy** (C engine included, pre-compiled) |

---

## Architecture

```
┌──────────────────────────────────────────────────────────────┐
│  Level 3 — bioforge/aligner.py           NW alignment         │
│  Anti-diagonal wavefront O(m+n) · mutation detection         │
├──────────────────────────────────────────────────────────────┤
│  Level 2 — bioforge/smart_translator.py  DNA → Protein       │
│  CODON_LUT + sliding_window_view · first-ATG ORF detection   │
├──────────────────────────────────────────────────────────────┤
│  Level 1 — bioforge/biocore.py           5-bit storage        │
│  BitPacker · PackedSequence · SmartImporter · LUTs           │
├──────────────────────────────────────────────────────────────┤
│  C engine — bioforge/engine/engine.c     Optional backend     │
│  GCC -O3 -march=native -fopenmp · auto-loaded via ctypes     │
└──────────────────────────────────────────────────────────────┘
```

### The 5-bit unified alphabet

Every biological symbol — nucleotides, amino acids, gaps, stop codons and
ambiguous bases — fits in a single 5-bit scheme (32 states).  
One encoding covers DNA, RNA, and proteins in the same pipeline.

```
State  Symbol            State  Symbol
  0    Adenine   (A)      14    Methionine    (M)
  1    Cytosine  (C)      ...   (all 20 amino acids: 4–23)
  2    Guanine   (G)      24    STOP codon    (*)
  3    Thymine / Uracil   25    Alignment gap (-)
 4–23  Amino acids        31    Unknown / ambiguous
```

---

## Installation

```bash
git clone https://github.com/erlanders177/bioforge.git
cd bioforge
pip install -r requirements.txt      # only needs NumPy
```

**Requirements**
- Python ≥ 3.10
- NumPy ≥ 1.24 — the only runtime dependency
- The C engine ships pre-compiled (`engine.dll`, zlib statically linked). If it
  can't load on your platform, BioForge falls back to NumPy automatically.

**Optional — compile the C engine** (27–29× faster on translation and alignment):
```bash
python bioforge/engine/build.py
```
Requires GCC. On Windows: [MinGW-w64](https://www.mingw-w64.org/). On Linux/Mac: `sudo apt install gcc` / `brew install gcc`.  
If not compiled, BioForge falls back to NumPy automatically — no code changes needed.

For development and testing:
```bash
pip install hypothesis pytest pytest-benchmark
```

---

## Quick start

### Import and encode a FASTA sequence

```python
from bioforge import SmartImporter, SeqType

records = SmartImporter.from_string(""">gene_1
ATGGTGCACCTGACTCCTGAGGAGAAGTCTGCC
""")

seq = records[0]
print(seq.n_symbols)      # 33
print(len(seq.data))      # 21  (37.5% smaller than ASCII)
print(seq.to_string())    # ATGGTGCACCTGACTCCTGAGGAGAAGTCTGCC
```

### Stream a huge FASTA/FASTQ with constant RAM

```python
from bioforge import SmartImporter

# One PackedSequence at a time — never loads the whole file
for seq in SmartImporter.stream("genome.fa"):
    print(seq.header, seq.n_symbols)

# FASTQ yields FastqRecord (sequence + Phred qualities)
for rec in SmartImporter.stream_fastq("reads.fastq"):
    if rec.passes_quality(20):
        process(rec.sequence)
```

### Quality-filter millions of reads — the fast lane (columnar)

```python
from bioforge import SmartImporter

total = passed = 0
for batch in SmartImporter.stream_fastq_batches("reads.fastq"):
    mask = batch.passes(20)          # ONE NumPy op for thousands of reads
    total  += len(batch)
    passed += int(mask.sum())
    kept = batch.filter(mask)        # new ReadBatch, no per-read objects
print(f"{passed}/{total} reads with mean quality >= 20")
```

`stream_fastq_batches` keeps a whole batch as contiguous matrices instead of
one object per read, so filtering 200 000 reads drops from ~5.3 s to ~0.28 s.
Materialise a single read only when you need it: `batch[i]` → `FastqRecord`.

Compressed `.gz` files are read transparently (decompressed in C):

```python
for rec in SmartImporter.stream_fastq("reads.fastq.gz"):   # no manual gunzip
    ...
```

Pass `n_threads` to go multi-core (an adaptive dispatcher picks the best path):

```python
# plain → parallel parse · .gz → libdeflate (~2× faster) + parse
for batch in SmartImporter.stream_fastq_batches("reads.fastq.gz", n_threads=0):
    ...   # n_threads: 1 = sequential (constant RAM) · >1 = threads · 0 = all cores
```

Reading compressed FASTQ is **~1.6× faster** this way (libdeflate beats zlib);
plain-file parse parallelism is memory-bandwidth bound, so its gain is modest on
few cores but scales on many-core servers.

### BGZF — parallel-decompressible `.gz` (~2× faster reads)

A BGZF file is a **valid `.gz`** (any `gunzip` reads it) but split into
independent 64 KB blocks, so BioForge decompresses it across all cores. Convert
once a file you'll process repeatedly:

```bash
python -m bioforge.bgzf reads.fastq        # or: bioforge-bgzip reads.fastq
# → reads.fastq.gz (BGZF). Reads at ~113 M bases/s vs ~58 for plain .gz.
```

BioForge auto-detects BGZF and routes to the parallel path; plain `.gz` keeps
using single-thread libdeflate.

### GC content and k-mer spectrum — vectorised over a whole batch

```python
from bioforge import SmartImporter

spectrum = None
for batch in SmartImporter.stream_fastq_batches("reads.fastq"):
    gc = batch.gc_content()              # GC fraction per read (NumPy array)
    s  = batch.kmer_spectrum(k=4)        # counts of all 4^4 k-mers in the batch
    spectrum = s if spectrum is None else spectrum + s
# spectrum[i] = how many times k-mer #i appears across the whole file
```

Both run with zero per-read objects; ambiguous bases (N) are skipped from k-mers.

### Fast FASTQ quality report (FastQC-style)

```bash
python -m bioforge.qcreport reads.fastq.gz        # or: bioforge-qc reads.fastq.gz
```

One pass, constant RAM. Reports read/base counts, length, overall GC, mean
quality, %reads ≥ Q20/Q30, plus per-read quality and GC histograms,
**per-position mean quality** (the FastQC signature plot) and per-base
composition — all built on the columnar API. Use `-o report.txt` to save it.

### Translate DNA to protein

```python
from bioforge import SmartTranslator

protein = SmartTranslator.translate(seq)
print(protein.to_string())   # MVHLTPEEKSA
```

### Detect mutations between two sequences

```python
from bioforge import SequenceAligner, format_alignment

result = SequenceAligner.align(seq_ref, seq_query)

print(f"Identity: {result.identity:.1%}")
print(format_alignment(result))

for mut in result.mutations:
    print(mut)
# Mutation(kind='substitution', pos_a=18, pos_b=18, sym_a='A', sym_b='T')
```

### Full mutation analysis pipeline (DNA + protein)

```python
from bioforge import run, build_report

result = run("reference.fa", "query.fa", mode="both")
print(build_report(result))
```

### Error handling

```python
from bioforge import BioForgeError, TranslationError, SmartImporter, SmartTranslator

try:
    for rec in SmartImporter.stream_fastq("reads.fastq.gz"):
        protein = SmartTranslator.translate(rec.sequence)
except TranslationError as e:
    print(f"Translation failed: {e}")   # e.g. no ATG found
except BioForgeError as e:
    print(f"BioForge error: {e}")       # ANY engine error: parse, I/O, decompress…
```

**One exception family.** Every engine error subclasses `BioForgeError`, so a
single `except BioForgeError` catches them all — translation, alignment, parsing,
file I/O (`BioForgeIOError`), engine/decompression (`EngineError`). Each also
subclasses the matching builtin (`ValueError`, `OSError`, `RuntimeError`…), so
existing `except OSError`-style code keeps working.

### Run the verifier (no coding knowledge required)

```bash
python check.py
```

---

## Project structure

```
bioforge/               Python package — all core modules
  __init__.py           Public API entry point (from bioforge import ...)
  biocore.py            Level 1 — 5-bit storage engine
  smart_translator.py   Level 2 — DNA → protein translation
  aligner.py            Level 3 — pairwise alignment + mutation detection
  analyze.py            Full pipeline: DNA + protein analysis, report generation
  qcreport.py           Fast FASTQ quality report (FastQC-style, columnar)
  bgzf.py               BGZF converter (parallel block gzip) — bioforge-bgzip
  engine/
    engine.c            C source — pack, unpack, NW align, translate (GCC -O3)
    engine.dll          Compiled C backend (Windows)
    _loader.py          ctypes wrapper with automatic NumPy fallback

check.py                Non-programmer verifier (runs all checks automatically)
conftest.py             Pytest fixtures shared across all tests

tools/
  visor.py              Interactive step-by-step translator (CLI)
  comparador.py         Sequence comparator tool (CLI)
  stress_test.py        30M-base performance benchmark
  bench_vs_biopython.py BioForge vs Biopython: time + RAM (FASTQ parse/QC/load)

tests/
  test_biocore.py       L1: property-based tests (Hypothesis) + benchmarks
  test_translator.py    L2: genetic code correctness + error paths
  test_aligner.py       L3: alignment properties + mutation detection
  test_analyze.py       Pipeline: full integration tests + CLI tests
  test_streaming.py     Streaming/batch parser + columnar API (Sequence/ReadBatch)
  test_qcreport.py      FASTQ quality report (qcreport.py)

docs/
  architecture.md       Design rules, levels, encoding details
  api_reference.md      Code examples for every module
  benchmarks.md         Measured numbers and methodology
  roadmap.md            Status and planned extensions
```

---

## How the vectorisation works

### Translation (Level 2)

```
① decode PackedSequence → uint8 array  [0–3 per nucleotide]
② find first ATG        → C engine scan / NumPy sliding_window_view
③ extract ORF, reshape  → (N, 3) codon matrix
④ base-4 index          → idx = n₁×16 + n₂×4 + n₃  (vectorised)
⑤ CODON_LUT[idx]        → amino acid array  (single fancy-index)
⑥ argmax on STOP mask   → truncate at stop codon
```

### Alignment (Level 3)

Needleman-Wunsch has a cell-level data dependency that prevents full 2D
vectorisation. The solution: **anti-diagonal wavefront**.

Cells on the same anti-diagonal (`i + j = d`) are mutually independent,
so each diagonal is a single vectorised operation.  
Python-level iterations: **O(m+n)** instead of O(m·n).

When the C engine is available, the entire DP matrix is computed in C
with OpenMP, giving **~29× speedup** over the NumPy wavefront.

### C engine

`bioforge/engine/engine.c` provides optimised implementations of all hot-path
operations. Loaded automatically via `ctypes` at import time.  
If `engine.dll` is missing, all code falls back to NumPy silently.

```python
from bioforge.engine._loader import C_AVAILABLE
print(C_AVAILABLE)   # True if C engine loaded, False if using NumPy fallback
```

---

## Running the tests

```bash
# Full test suite (269 tests)
pytest tests/ -v

# Benchmarks only
pytest tests/ --benchmark-only

# Quick smoke check (no coding knowledge required)
python check.py
```

---

## Known limitations

| Limitation | Detail |
|------------|--------|
| Aligner memory (full NW) | O(m·n) matrix — sequences > 15 000 bp may exhaust RAM. Use `band=N` for large sequences. |
| Protein auto-detection | Sequences without E/F/I/L/P/Q/* are classified as nucleotides. Use `force_type=SeqType.PROTEIN` to override. |
| C engine | Pre-compiled `.dll`/`.so` not included. Run `python bioforge/engine/build.py` to compile. Requires GCC. |
| Banded NW (NumPy fallback) | Without the C engine, banded NW uses the full matrix with NEG_INF masking — same result, standard RAM. |

---

## Roadmap

- [x] Level 1 — 5-bit storage, FASTA parser, SmartImporter
- [x] Level 2 — vectorised genetic code translation (C + NumPy)
- [x] Level 3 — Needleman-Wunsch alignment + mutation detection (C + NumPy)
- [x] Full mutation analysis pipeline (DNA + protein, 3 modes)
- [x] BioForgeError exception hierarchy for library users
- [x] Reverse complement vectorised — `PackedSequence.reverse_complement()`
- [x] 6-frame translation — `SmartTranslator.translate_all_frames()`
- [x] Banded NW — `SequenceAligner.align(seq_a, seq_b, band=N)`
- [x] Smith-Waterman local alignment — `SequenceAligner.align_local()`
- [x] Streaming FASTA/FASTQ parser in C — `SmartImporter.stream()` / `stream_fastq()`
- [x] Batch parser (5-bit encoding in C) — ~80 M bases/s FASTA, ~94 K reads/s FASTQ
- [x] Columnar QC API — `stream_fastq_batches()` · `ReadBatch.passes()` / `filter()`
- [x] Compressed `.gz` decoded in C (zlib, static-linked, transparent)
- [x] Object-free columnar k-mer spectrum + per-read GC — `kmer_spectrum()` / `gc_content()`
- [x] Benchmark vs Biopython — `tools/bench_vs_biopython.py`
- [x] Fast FASTQ quality report (FastQC-style) — `bioforge-qc` / `bioforge.qcreport`
- [x] Adaptive multi-core dispatcher — `n_threads=`: parallel parse + libdeflate `.gz`
- [x] BGZF parallel-decompressible `.gz` + converter — `bioforge-bgzip`
- [ ] Native per-platform wheels on PyPI (cibuildwheel)
- [ ] Long-read / genome-scale aligner (k-mer seeding)

---

## Author

**Aarón Aranda Torrijos** — [github.com/erlanders177](https://github.com/erlanders177)

---

## License

PolyForm Noncommercial 1.0.0 — free for personal, academic and research use.  
Commercial use requires explicit permission from the author.

See [LICENSE](LICENSE) for full terms.
