release: add CHANGELOG, RELEASING runbook, and readthedocs config

Adds the supporting files that the avitai sibling repos use around their
publish workflow:

- .readthedocs.yaml: ubuntu-22.04 + Python 3.11 build, mkdocs-material
  install, mkdocs.yml as configuration source, [docs] extras for the
  project install. Mirrors the opifex setup so docs.avitai.bio /
  ReadTheDocs hosting behave consistently.

- CHANGELOG.md: Keep a Changelog format with the 0.1.0 entry describing
  the initial public release surface (40+ operators, 6 pipelines, soft
  ops, sources, splitters, losses, training, docs, benchmarks, CI/CD).

- RELEASING.md: step-by-step runbook for the next maintainer release —
  bump version, update changelog, run the local checks (pytest,
  pre-commit, mkdocs build --strict, uv build, twine check), tag,
  push, and run the publish workflow with target=github-release.
  Documents the PYPI_API_TOKEN / TEST_PYPI_API_TOKEN repo-secret
  requirements.

Author: mahdi-shafiei

.readthedocs.yaml

@@ -0,0 +1,23 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  jobs:
+    post_install:
+      - pip install mkdocs-material
+
+mkdocs:
+  configuration: mkdocs.yml
+  fail_on_warning: false
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to DiffBio will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-02
+
+Initial public release of DiffBio: end-to-end differentiable bioinformatics
+pipelines built on JAX, Flax NNX, and the Datarax / Artifex / Opifex /
+Calibrax ecosystem.
+
+### Added
+
+- 40+ differentiable operators across alignment, variant calling, single-cell
+  analysis, drug discovery, epigenomics, multi-omics, RNA structure, protein
+  structure, molecular dynamics, foundation models, and preprocessing.
+- Six end-to-end pipelines: `VariantCallingPipeline`,
+  `EnhancedVariantCallingPipeline`, `SingleCellPipeline`,
+  `DifferentialExpressionPipeline`, `PerturbationPipeline`, and
+  `PreprocessingPipeline`.
+- Soft-operations primitive layer (`diffbio.core.soft_ops`) with
+  straight-through and gradient-replacement variants for use inside
+  differentiable bioinformatics workflows.
+- Dataset sources for FASTA, BAM, AnnData, MoleculeNet, and indexed views.
+- Dataset splitters for random, stratified, scaffold, Tanimoto cluster, and
+  sequence-identity splits.
+- Loss functions for alignment, biological regularization, single-cell
+  analysis, statistical models, and metric learning.
+- Training utilities (`Trainer`, `TrainingConfig`, optimizer factories,
+  synthetic data generation, gradient clipping).
+- Documentation site: getting-started guides, user-guide, API reference,
+  examples (basic / intermediate / advanced), and contributor guides.
+- Benchmark suite under `benchmarks/` with tier-based runner
+  (`run_all.py --tier ci|nightly|full`) and SOTA baseline comparisons across
+  single-cell, alignment, RNA structure, protein, molecular dynamics, and
+  statistical domains.
+- CI/CD: sharded unit tests with `pytest-xdist`, integration / e2e /
+  performance jobs, coverage aggregation, security scanning, build
+  verification, and documentation deployment workflows.

README.md

@@ -48,7 +48,7 @@ This enables learning optimal pipeline parameters directly from data, rather tha
 - **Composable Architecture** built on the Datarax, Artifex, Opifex, and Calibrax stack
 - **Training Utilities** with gradient clipping, custom loss functions, and synthetic data generation
 
-For complete operator and pipeline listings, see the [Operators Overview](https://docs.avitai.bio/diffbio/user-guide/operators/overview/) and [Pipelines Overview](https://docs.avitai.bio/diffbio/user-guide/pipelines/overview/) in the documentation.
+For complete operator and pipeline listings, see the [Operators Overview](https://diffbio.readthedocs.io/en/latest/user-guide/operators/overview/) and [Pipelines Overview](https://diffbio.readthedocs.io/en/latest/user-guide/pipelines/overview/) in the documentation.
 
 ## Installation
 
@@ -70,24 +70,22 @@ import jax
 import jax.numpy as jnp
 from flax import nnx
 
-from diffbio.operators import DifferentiableQualityFilter
-from diffbio.operators.variant.pileup import DifferentiablePileup
-from diffbio.operators.alignment.smith_waterman import SmoothSmithWaterman
+from diffbio.operators import DifferentiableQualityFilter, QualityFilterConfig
 
-# Quality filtering with learnable threshold
+# Quality filtering with learnable threshold (default initial_threshold=20.0)
 quality_filter = DifferentiableQualityFilter(
-    threshold=20.0,
-    temperature=1.0,
+    QualityFilterConfig(initial_threshold=20.0),
     rngs=nnx.Rngs(0),
 )
 
-# Apply to reads
+# Apply to a one-hot encoded sequence with per-position quality scores
 quality_scores = jnp.array([35.0, 15.0, 28.0, 10.0])
-reads = jax.nn.one_hot(jnp.array([[0, 1, 2, 3]] * 4), 4)
-data = {"reads": reads, "quality": quality_scores}
+sequence = jax.nn.one_hot(jnp.array([0, 1, 2, 3]), 4)  # (length, alphabet=4)
+data = {"sequence": sequence, "quality_scores": quality_scores}
 
 filtered_data, _, _ = quality_filter.apply(data, {}, None)
-# filtered_data["weights"] contains soft weights for each read
+# filtered_data["sequence"]        — sequence with low-quality positions softly suppressed
+# filtered_data["quality_scores"]  — pass-through quality values
 ```
 
 ### Using the Variant Calling Pipeline
@@ -178,7 +176,10 @@ DiffBio sits on a layered ecosystem rather than standing alone:
 | Modeling substrate | [Artifex](https://github.com/avitai/artifex) | Reusable transformer and generative-model components |
 | Scientific ML substrate | [Opifex](https://github.com/avitai/Opifex) | Scientific optimization, operator learning, and advanced training methods |
 | Evaluation substrate | [Calibrax](https://github.com/avitai/calibrax) | Metrics, benchmarking, comparison, profiling, and regression checks |
-| Biology-specific layer | DiffBio | Differentiable biological operators and domain compositions |
+
+DiffBio itself sits on top of these as the biology-specific layer: differentiable
+biological operators and end-to-end pipeline compositions (alignment, variant
+calling, single-cell analysis, drug discovery, structural biology, multi-omics).
 
 Each DiffBio operator inherits from Datarax's `OperatorModule` and implements:
 
@@ -193,18 +194,31 @@ This enables:
 
 ### Operator Composition
 
-Operators are chained by threading the `(data, state, metadata)` triple
-returned by `apply()` into the next operator:
+`apply()` runs an operator on a single element (no batch dimension). Operators
+are chained by threading the `(data, state, metadata)` triple returned by
+`apply()` into the next operator:
 
 ```python
-data, state, metadata = quality_filter.apply(batch_data, {}, None)
+data, state, metadata = quality_filter.apply(element_data, {}, None)
 data, state, metadata = pileup.apply(data, state, metadata)
 data, state, metadata = classifier.apply(data, state, metadata)
 
 # `data` is a dict of JAX arrays — read out the per-position predictions
 predictions = data["logits"]
 ```
 
+For batched data wrapped in a Datarax `Batch`, call the operator directly
+(or use `apply_batch()`); both delegate to the same code path:
+
+```python
+from datarax import Batch
+
+batch = Batch.from_parts(...)        # construct from a list of elements
+batch = quality_filter(batch)         # equivalent to quality_filter.apply_batch(batch)
+batch = pileup(batch)
+batch = classifier(batch)
+```
+
 ## Testing
 
 ```bash
@@ -225,24 +239,38 @@ uv run pytest tests/integration/ -vv
 ```
 DiffBio/
 ├── src/diffbio/
-│   ├── core/               # Base operators, graph utils, soft ops
-│   ├── operators/           # 35+ differentiable operators
+│   ├── core/                # Base operators, graph utils, soft ops, neural components
+│   ├── operators/           # 40+ differentiable operators
 │   │   ├── alignment/       # Smith-Waterman, profile HMM, soft MSA
-│   │   ├── variant/         # Pileup, classifiers, CNV segmentation
-│   │   ├── singlecell/      # Clustering, trajectory, velocity, GRN, ...
-│   │   ├── drug_discovery/  # Fingerprints, property prediction, ADMET
-│   │   ├── epigenomics/     # Peak calling, chromatin state
-│   │   ├── normalization/   # VAE normalizer, UMAP, PHATE
+│   │   ├── assembly/        # GNN assembly, metagenomic binning
+│   │   ├── crispr/          # Guide RNA scoring
+│   │   ├── drug_discovery/  # Fingerprints, ADMET, AttentiveFP, MACCS keys
+│   │   ├── epigenomics/     # Peak calling, chromatin state, contextual epigenomics
+│   │   ├── foundation_models/ # Geneformer/scGPT adapters, transformer encoders
+│   │   ├── mapping/         # Neural read mapping
+│   │   ├── metabolomics/    # Spectral similarity
+│   │   ├── molecular_dynamics/ # Force fields, MD integrators
+│   │   ├── multiomics/      # Hi-C, spatial deconvolution, multi-omics VAE
+│   │   ├── normalization/   # VAE normalizer, UMAP, PHATE, embeddings
+│   │   ├── population/      # Ancestry estimation
+│   │   ├── preprocessing/   # Adapter removal, duplicate weighting, error correction
+│   │   ├── protein/         # Secondary structure
+│   │   ├── rna_structure/   # RNA folding
+│   │   ├── rnaseq/          # Splicing PSI, motif discovery
+│   │   ├── singlecell/      # Clustering, trajectory, velocity, GRN, batch correction, ...
 │   │   ├── statistical/     # HMM, NB GLM, EM quantification
-│   │   ├── multiomics/      # Hi-C, spatial deconvolution
-│   │   └── ...              # preprocessing, protein, RNA, assembly, ...
-│   ├── pipelines/           # End-to-end pipelines
-│   ├── losses/              # Alignment, single-cell, statistical losses
-│   ├── sources/             # Data loaders (FASTA, BAM, MolNet, ...)
-│   ├── splitters/           # Dataset splitting strategies
-│   └── utils/               # Training utilities
+│   │   └── variant/         # Pileup, classifiers, CNV segmentation
+│   ├── pipelines/           # 6 end-to-end pipelines
+│   ├── losses/              # Alignment, biological-regularization, single-cell, statistical, metric
+│   ├── sources/             # Data loaders (FASTA, BAM, AnnData, MoleculeNet, indexed views)
+│   ├── splitters/           # Random, stratified, scaffold, Tanimoto, sequence-identity
+│   ├── samplers/            # Perturbation samplers
+│   ├── sequences/           # DNA / RNA encoding utilities
+│   ├── evaluation/          # Evaluation runner and graders
+│   └── utils/               # Training utilities, dependency-runtime checks
 ├── tests/                   # Unit, integration, and benchmark tests
 ├── benchmarks/              # Domain benchmarks with training + baselines
+├── examples/                # Runnable example scripts paired with notebooks
 └── docs/                    # MkDocs documentation
 ```
 
@@ -262,7 +290,6 @@ MIT License. See [LICENSE](LICENSE) for details.
 ## Acknowledgments
 
 DiffBio builds on ideas from:
-- [SMURF](https://www.biorxiv.org/content/10.1101/2021.10.23.465204): Differentiable Smith-Waterman for end-to-end MSA learning
 - [Datarax](https://github.com/avitai/datarax): Composable data processing framework
 - [Artifex](https://github.com/avitai/artifex): Generative-model and transformer substrate
 - [Opifex](https://github.com/avitai/Opifex): Scientific ML and advanced optimization substrate

RELEASING.md

@@ -0,0 +1,90 @@
+# Releasing DiffBio
+
+DiffBio publishes through `.github/workflows/publish.yml`.
+No commit or tag push creates a release by itself. Release timing and versioning
+stay under operator control. The manual `target=github-release` workflow path
+creates a GitHub Release for an explicit existing tag with
+`softprops/action-gh-release@v2` and `generate_release_notes: true`, then
+publishes to PyPI. Publishing an existing GitHub Release also runs the PyPI
+upload path.
+
+## Release Checklist
+
+1. Activate the local environment.
+
+   ```bash
+   source activate.sh
+   ```
+
+2. Bump the package version in `pyproject.toml` (the static `version = "X.Y.Z"`
+   field under `[project]`).
+3. Update `CHANGELOG.md` by moving unreleased entries under the new version and
+   date.
+4. Run the release checks.
+
+   ```bash
+   uv run pytest
+   uv run pre-commit run --all-files
+   uv run mkdocs build --strict --clean
+   rm -rf dist/
+   uv build
+   uv run twine check dist/*
+   ```
+
+5. Commit the version and changelog updates.
+6. Create and push an annotated tag from the exact release commit.
+
+   ```bash
+   target_sha=$(git rev-parse HEAD)
+   git tag -a vX.Y.Z -m "diffbio X.Y.Z"
+   git push origin main vX.Y.Z
+   ```
+
+7. In GitHub Actions, manually run `Publish to PyPI` with:
+
+   - `target=github-release`
+   - `version_tag=vX.Y.Z`
+
+   The workflow verifies that the tag exists, creates the GitHub Release with
+   generated release notes, then publishes to PyPI.
+
+## Manual Release Recovery
+
+If the manual generated-release workflow is interrupted before creating the
+GitHub Release, use GitHub generated notes manually from the exact tagged
+commit.
+
+```bash
+gh release create vX.Y.Z --target "$target_sha" --generate-notes
+```
+
+Publishing that release triggers the same PyPI upload workflow.
+
+## TestPyPI
+
+Use the manual `workflow_dispatch` path in `publish.yml` with `target=testpypi`
+when validating publishing setup before a real release.
+
+## PyPI Authentication
+
+The publish workflow uses API token authentication. Two repo secrets must be
+set on `avitai/DiffBio`:
+
+- `PYPI_API_TOKEN`      — account-scoped token used by the `pypi` job
+- `TEST_PYPI_API_TOKEN` — account-scoped token used by the `testpypi` job
+
+For the maiden release of a new project, the token must be **account-scoped**
+(project-scoped tokens cannot create new projects). Once the project exists on
+PyPI, project-scoped tokens are preferred for least-privilege rotation.
+
+To migrate to OIDC trusted publishing later, register the project at
+<https://pypi.org/manage/account/publishing/> (and the TestPyPI equivalent)
+with:
+
+- Owner: `avitai`
+- Repository: `DiffBio`
+- Workflow: `publish.yml`
+- Environment: `pypi` (and `testpypi`)
+
+Then remove the `password` inputs from the publish steps and add
+`permissions: id-token: write` to each publish job.

docs/index.md

@@ -162,11 +162,12 @@ Traditional bioinformatics pipelines consist of discrete, non-differentiable ope
 If you use DiffBio in your research, please cite:
 
 ```bibtex
-@software{diffbio2024,
+@software{diffbio2026,
   title={DiffBio: End-to-End Differentiable Bioinformatics Pipelines},
   author={Shafiei, Mahdi},
-  year={2024},
-  url={https://github.com/avitai/DiffBio}
+  year={2026},
+  url={https://github.com/avitai/DiffBio},
+  version={0.1.0}
 }
 ```
 

mkdocs.yml

@@ -1,7 +1,7 @@
 site_name: DiffBio
 site_description: End-to-end differentiable bioinformatics pipelines built on JAX/Flax NNX, Datarax, Artifex, Opifex, and Calibrax
 site_author: Mahdi Shafiei
-site_url: https://docs.avitai.bio/diffbio
+site_url: https://diffbio.readthedocs.io/en/latest/
 repo_url: https://github.com/avitai/DiffBio
 repo_name: avitai/DiffBio
 edit_uri: edit/main/docs/