sbol-torch 0.1.0__tar.gz

sbol_torch-0.1.0/.flake8

@@ -0,0 +1,11 @@
+[flake8]
+max-line-length = 120
+extend-ignore = E402,W503,E203,W605
+per-file-ignores =
+    __init__.py:F401
+exclude =
+    .git,
+    __pycache__,
+    .venv,
+    build,
+    dist

sbol_torch-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+build/
+dist/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# Local materialized corpora and run outputs
+.sboltorch_cache/
+runs/
+*.parquet
+wandb/
+
+# Environment
+.env
+.env.*

sbol_torch-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+repos:
+  - repo: https://github.com/pycqa/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+  - repo: https://github.com/psf/black
+    rev: 24.3.0
+    hooks:
+      - id: black
+  - repo: https://github.com/pycqa/flake8
+    rev: 7.0.0
+    hooks:
+      - id: flake8
+  # Run mypy in the project environment so it type-checks against the real
+  # dependencies (torch, transformers, wandb). An isolated env would treat them
+  # as Any and miss real type errors.
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: uv run mypy
+        language: system
+        types: [python]
+        pass_filenames: false
+        args: [--config-file=pyproject.toml]

sbol_torch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike Arpaia
+
+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.

sbol_torch-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: sbol-torch
+Version: 0.1.0
+Summary: A PyTorch library for synthetic biology and biodesign automation
+Author-email: Mike Arpaia <mike@arpaia.co>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: einops>=0.7
+Requires-Dist: httpx>=0.27
+Requires-Dist: numpy>=1.26
+Requires-Dist: pyarrow>=15
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6
+Requires-Dist: rdflib>=7
+Requires-Dist: tokenizers>=0.19
+Requires-Dist: torch-geometric>=2.5
+Requires-Dist: torch>=2.2
+Requires-Dist: transformers<5,>=4.40
+Requires-Dist: wandb>=0.17
+Provides-Extra: dev
+Requires-Dist: black>=24.3; extra == 'dev'
+Requires-Dist: flake8>=7; extra == 'dev'
+Requires-Dist: isort>=5.13; extra == 'dev'
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sbol-torch
+
+A PyTorch library for synthetic biology and biodesign automation.
+
+Installed as `sbol-torch`, imported as `sboltorch` (commonly `import sboltorch as st`).
+
+sbol-torch pulls designs from a running [sbol-db](https://github.com/marpaia/sbol-db)
+instance (or local SBOL/FASTA files), normalizes them into a single record type,
+and trains transformer models against them. The input modality, tokenizer, and
+training objective are all set in configuration, so trying a new combination
+never means forking the pipeline.
+
+## Capabilities
+
+| Axis | Options |
+|------|---------|
+| **Data sources** | sbol-db REST API, local SBOL/FASTA files, or a synthetic generator |
+| **Tokenizers** | pretrained HuggingFace (`hf`), overlapping k-mer, or IUPAC character |
+| **Modalities** | `sequence`, `structure_aware` (feature boundaries), `graph` (PyG composition transformer) |
+| **Objectives** | `supervised` fine-tuning, `frozen`-backbone head, `mlm` pretraining (from-scratch and continued) |
+| **Engine** | raw-PyTorch loop, early stopping, checkpointing, AMP, LR schedule, gradient accumulation |
+| **Tracking** | per-epoch `metrics.jsonl`, optional [Weights & Biases](https://docs.wandb.ai/) (scalars, config, lineage, model artifact) |
+| **Reproducibility** | one validated config per run, seeded splits, content-fingerprinted Parquet cache |
+
+## Install
+
+```bash
+pip install sbol-torch
+```
+
+For development:
+
+```bash
+uv venv
+uv pip install -e '.[dev]'
+```
+
+## Quickstart
+
+A run is fully specified by one YAML config. From the command line:
+
+```bash
+# Materialize a corpus to the local Parquet cache (offline, reproducible).
+sboltorch ingest examples/configs/finetune_expression.yaml
+
+# Train. Resolved config, per-epoch metrics.jsonl, and best.pt land in output_dir.
+sboltorch train examples/configs/finetune_expression.yaml
+```
+
+Or from Python:
+
+```python
+import sboltorch as st
+
+config = st.RunConfig.from_yaml("examples/configs/train_graph.yaml")
+metrics = st.run_training(config)
+```
+
+### Example configs
+
+| Config | What it does |
+|--------|--------------|
+| [`finetune_expression.yaml`](https://github.com/marpaia/sbol-torch/blob/master/examples/configs/finetune_expression.yaml) | Frozen DNABERT-2 backbone feeding a regression head. |
+| [`pretrain_mlm.yaml`](https://github.com/marpaia/sbol-torch/blob/master/examples/configs/pretrain_mlm.yaml) | From-scratch masked-LM pretraining; writes a reusable backbone. |
+| [`finetune_structure_aware.yaml`](https://github.com/marpaia/sbol-torch/blob/master/examples/configs/finetune_structure_aware.yaml) | Sequence + feature-boundary markers. |
+| [`train_graph.yaml`](https://github.com/marpaia/sbol-torch/blob/master/examples/configs/train_graph.yaml) | Graph transformer over the composition graph. |
+
+## Experiment tracking
+
+The two synthetic-data configs ([`train_graph.yaml`](https://github.com/marpaia/sbol-torch/blob/master/examples/configs/train_graph.yaml)
+and [`finetune_structure_aware.yaml`](https://github.com/marpaia/sbol-torch/blob/master/examples/configs/finetune_structure_aware.yaml))
+ship with [Weights & Biases](https://docs.wandb.ai/) enabled. Set `WANDB_API_KEY`
+in a `.env` at the repo root and run both:
+
+```bash
+python examples/run_wandb_examples.py
+```
+
+Each run logs per-step loss and learning rate, per-epoch train/val metrics, the
+resolved config, the corpus fingerprint and split sizes as lineage, and the best
+checkpoint as a model artifact.
+
+| Graph transformer | Structure-aware sequence |
+|-------------------|--------------------------|
+| ![train_graph W&B run](https://raw.githubusercontent.com/marpaia/sbol-torch/master/docs/images/wandb_train_graph.png) | ![structure_aware W&B run](https://raw.githubusercontent.com/marpaia/sbol-torch/master/docs/images/wandb_structure_aware.png) |
+
+## Documentation
+
+| Doc | Contents |
+|-----|----------|
+| [architecture.md](https://github.com/marpaia/sbol-torch/blob/master/docs/architecture.md) | How the system is built — record type, plug points, engine, data flow. |
+| [capabilities.md](https://github.com/marpaia/sbol-torch/blob/master/docs/capabilities.md) | Modalities, objectives, tokenizers, metrics. |
+| [configuration.md](https://github.com/marpaia/sbol-torch/blob/master/docs/configuration.md) | Complete `RunConfig` reference. |
+| [data.md](https://github.com/marpaia/sbol-torch/blob/master/docs/data.md) | Data sources, the sbol-db client, materialization, fixtures. |
+| [backbones.md](https://github.com/marpaia/sbol-torch/blob/master/docs/backbones.md) | Choosing/loading backbones and environment constraints. |
+| [extending.md](https://github.com/marpaia/sbol-torch/blob/master/docs/extending.md) | Adding a tokenizer, encoder, task, callback, or data source. |
+
+## Develop
+
+```bash
+uv run pytest
+pre-commit run --all-files
+```

sbol_torch-0.1.0/README.md

@@ -0,0 +1,103 @@
+# sbol-torch
+
+A PyTorch library for synthetic biology and biodesign automation.
+
+Installed as `sbol-torch`, imported as `sboltorch` (commonly `import sboltorch as st`).
+
+sbol-torch pulls designs from a running [sbol-db](https://github.com/marpaia/sbol-db)
+instance (or local SBOL/FASTA files), normalizes them into a single record type,
+and trains transformer models against them. The input modality, tokenizer, and
+training objective are all set in configuration, so trying a new combination
+never means forking the pipeline.
+
+## Capabilities
+
+| Axis | Options |
+|------|---------|
+| **Data sources** | sbol-db REST API, local SBOL/FASTA files, or a synthetic generator |
+| **Tokenizers** | pretrained HuggingFace (`hf`), overlapping k-mer, or IUPAC character |
+| **Modalities** | `sequence`, `structure_aware` (feature boundaries), `graph` (PyG composition transformer) |
+| **Objectives** | `supervised` fine-tuning, `frozen`-backbone head, `mlm` pretraining (from-scratch and continued) |
+| **Engine** | raw-PyTorch loop, early stopping, checkpointing, AMP, LR schedule, gradient accumulation |
+| **Tracking** | per-epoch `metrics.jsonl`, optional [Weights & Biases](https://docs.wandb.ai/) (scalars, config, lineage, model artifact) |
+| **Reproducibility** | one validated config per run, seeded splits, content-fingerprinted Parquet cache |
+
+## Install
+
+```bash
+pip install sbol-torch
+```
+
+For development:
+
+```bash
+uv venv
+uv pip install -e '.[dev]'
+```
+
+## Quickstart
+
+A run is fully specified by one YAML config. From the command line:
+
+```bash
+# Materialize a corpus to the local Parquet cache (offline, reproducible).
+sboltorch ingest examples/configs/finetune_expression.yaml
+
+# Train. Resolved config, per-epoch metrics.jsonl, and best.pt land in output_dir.
+sboltorch train examples/configs/finetune_expression.yaml
+```
+
+Or from Python:
+
+```python
+import sboltorch as st
+
+config = st.RunConfig.from_yaml("examples/configs/train_graph.yaml")
+metrics = st.run_training(config)
+```
+
+### Example configs
+
+| Config | What it does |
+|--------|--------------|
+| [`finetune_expression.yaml`](https://github.com/marpaia/sbol-torch/blob/master/examples/configs/finetune_expression.yaml) | Frozen DNABERT-2 backbone feeding a regression head. |
+| [`pretrain_mlm.yaml`](https://github.com/marpaia/sbol-torch/blob/master/examples/configs/pretrain_mlm.yaml) | From-scratch masked-LM pretraining; writes a reusable backbone. |
+| [`finetune_structure_aware.yaml`](https://github.com/marpaia/sbol-torch/blob/master/examples/configs/finetune_structure_aware.yaml) | Sequence + feature-boundary markers. |
+| [`train_graph.yaml`](https://github.com/marpaia/sbol-torch/blob/master/examples/configs/train_graph.yaml) | Graph transformer over the composition graph. |
+
+## Experiment tracking
+
+The two synthetic-data configs ([`train_graph.yaml`](https://github.com/marpaia/sbol-torch/blob/master/examples/configs/train_graph.yaml)
+and [`finetune_structure_aware.yaml`](https://github.com/marpaia/sbol-torch/blob/master/examples/configs/finetune_structure_aware.yaml))
+ship with [Weights & Biases](https://docs.wandb.ai/) enabled. Set `WANDB_API_KEY`
+in a `.env` at the repo root and run both:
+
+```bash
+python examples/run_wandb_examples.py
+```
+
+Each run logs per-step loss and learning rate, per-epoch train/val metrics, the
+resolved config, the corpus fingerprint and split sizes as lineage, and the best
+checkpoint as a model artifact.
+
+| Graph transformer | Structure-aware sequence |
+|-------------------|--------------------------|
+| ![train_graph W&B run](https://raw.githubusercontent.com/marpaia/sbol-torch/master/docs/images/wandb_train_graph.png) | ![structure_aware W&B run](https://raw.githubusercontent.com/marpaia/sbol-torch/master/docs/images/wandb_structure_aware.png) |
+
+## Documentation
+
+| Doc | Contents |
+|-----|----------|
+| [architecture.md](https://github.com/marpaia/sbol-torch/blob/master/docs/architecture.md) | How the system is built — record type, plug points, engine, data flow. |
+| [capabilities.md](https://github.com/marpaia/sbol-torch/blob/master/docs/capabilities.md) | Modalities, objectives, tokenizers, metrics. |
+| [configuration.md](https://github.com/marpaia/sbol-torch/blob/master/docs/configuration.md) | Complete `RunConfig` reference. |
+| [data.md](https://github.com/marpaia/sbol-torch/blob/master/docs/data.md) | Data sources, the sbol-db client, materialization, fixtures. |
+| [backbones.md](https://github.com/marpaia/sbol-torch/blob/master/docs/backbones.md) | Choosing/loading backbones and environment constraints. |
+| [extending.md](https://github.com/marpaia/sbol-torch/blob/master/docs/extending.md) | Adding a tokenizer, encoder, task, callback, or data source. |
+
+## Develop
+
+```bash
+uv run pytest
+pre-commit run --all-files
+```

sbol_torch-0.1.0/docs/architecture.md

@@ -0,0 +1,88 @@
+# Architecture
+
+sbol-torch turns SBOL designs into trained transformer models. Three ideas shape
+it: every source normalizes to one record type, the parts that vary plug in
+behind protocols, and the training engine stays small and explicit.
+
+## One record type
+
+Every data source — the sbol-db REST API, local SBOL/FASTA files, or the synthetic
+generator — is normalized into `SbolObject` (`sboltorch.types`):
+
+```
+SbolObject(iri, sbol_class, roles, types, sequence, features, neighbors, label, raw)
+```
+
+Training code consumes only `SbolObject`s and never branches on provenance. A
+source is anything satisfying the `Corpus` protocol (`__iter__` yielding
+`SbolObject`s, plus a `fingerprint()` for caching).
+
+## Swappable plug points
+
+Three independent axes are each a `Protocol` with interchangeable implementations,
+selected by configuration:
+
+- **Tokenizer** — how a sequence becomes tokens (`hf`, `kmer`, `char`).
+- **Encoder** — the input modality, turning an `SbolObject` into model input
+  (`sequence`, `structure_aware`, `graph`).
+- **Task** — the training objective, owning loss and metrics (`supervised`,
+  `frozen`, `mlm`).
+
+Adding an implementation and registering it in the matching `build_*` factory
+extends a capability without touching the engine. See [extending.md](extending.md).
+
+## The training engine
+
+The training loop (`sboltorch.engine`) is plain PyTorch: AMP, gradient
+accumulation and clipping, a linear warmup/decay schedule, and a list of
+callbacks (`EarlyStopping`, `ModelCheckpoint`, `MetricLogger`). It learns the
+batch shape only through a `BatchAdapter`, so the same loop trains a sequence
+model (tensor-dict batches) or a graph model (PyG `Batch` objects).
+
+## Data flow
+
+A `RunConfig` drives the whole pipeline. The configured `Corpus` source is
+materialized to Parquet and split into train/val/test (seeded). The `Encoder`
+turns each `SbolObject` into model input for its modality, using the `Tokenizer`,
+and a `DataLoader` batches the result through a collator. The `Trainer` then runs
+the loop under the `Task` and `BatchAdapter`, writing a checkpoint and metrics.
+
+## Layers
+
+| Layer | Module | Responsibility |
+|-------|--------|----------------|
+| Config | `sboltorch.config` | One Pydantic `RunConfig` per run; validated, serialized. |
+| Data | `sboltorch.data` | Corpus sources (`SbolDbClient`, `LocalFileCorpus`, synthetic) and Parquet materialization. |
+| Tokenize | `sboltorch.tokenize` | `hf` / `kmer` / `char` behind one protocol. |
+| Encoders | `sboltorch.encoders` | Turn an `SbolObject` into model input, per modality. |
+| Datasets | `sboltorch.datasets` | Torch `Dataset`, padding collator, MLM collator, seeded splits. |
+| Models | `sboltorch.models` | Backbone (pretrained or from-scratch) + pooling + head; MLM and graph models. |
+| Tasks | `sboltorch.tasks` | Loss, metrics, label dtype, target transform. |
+| Engine | `sboltorch.engine` | Training loop, callbacks, batch adapters. |
+| Pipeline | `sboltorch.pipeline` | Wires the layers from a `RunConfig`. |
+
+## Key protocols
+
+- `Corpus`: `__iter__() -> Iterator[SbolObject]`, `fingerprint() -> str`.
+- `Tokenizer`: `encode`, `tokenize_content`, `vocab_size`, `pad_token_id`,
+  `mask_token_id`, `special_token_ids`, `max_length`.
+- `Encoder`: `encode(SbolObject) -> ModelInput`, `output_spec -> EncoderSpec`.
+- `Task`: `loss`, `predict`, `epoch_metrics`, `primary_metric`, `label_dtype`.
+- `BatchAdapter`: `to_device`, `forward(model, batch)`, `labels(batch)`.
+- `Callback`: `on_train_start`, `on_epoch_end`, `on_train_end`.
+
+## Reproducibility
+
+- A run is fully specified by its `RunConfig`; the resolved config is written to
+  `<output_dir>/config.resolved.yaml`.
+- `seed` seeds Python, NumPy, and torch, and the train/val/test split is a pure
+  function of `(n, ratios, seed, strategy)`.
+- Corpora are materialized to content-fingerprinted Parquet, so a run is offline
+  and byte-for-byte comparable across executions. See [data.md](data.md).
+
+## Consuming sbol-db
+
+`SbolDbClient` reads designs over the sbol-db REST API: keyset-paginated object
+listing, single/bulk IRI resolution, bounded neighborhood traversal, sequence
+search, and ontology descendant expansion. Sequence elements are read from each
+object's JSON-LD slice by predicate local-name. Details in [data.md](data.md).

sbol_torch-0.1.0/docs/backbones.md

@@ -0,0 +1,47 @@
+# Backbones & environment
+
+The backbone is any HuggingFace encoder, or one built from scratch. The `hf`
+tokenizer is a generic `AutoTokenizer` adapter, so any model that accepts a raw
+sequence string works by pointing `model.backbone` and `tokenizer.model_name` at
+the same id.
+
+## Choosing a backbone
+
+| Goal | `model` config |
+|------|----------------|
+| Fine-tune a pretrained DNA model | `backbone: <hub-id>`, `from_scratch: false` |
+| Train a head over a frozen backbone | as above, with `task.kind: frozen` |
+| Pretrain / train from scratch | `from_scratch: true` + `model.arch` (sized to the tokenizer vocab) |
+| Reuse a model you pretrained | `backbone: <output_dir>/backbone` (a local path) |
+
+`model.backbone` accepts either a hub id or a local directory. A masked-LM run
+writes its encoder to `<output_dir>/backbone/`, which a later supervised run loads
+directly.
+
+## transformers version
+
+sbol-torch pins `transformers` to the 4.x line. The 5.x line changes the ESM and
+custom modeling code that the pretrained DNA backbones rely on, so it is not
+compatible with them.
+
+## Known backbone constraints
+
+- **DNABERT-2 (`zhihan1996/DNABERT-2-117M`)** — its remote modeling code requires
+  `triton`, which has no macOS wheels, so DNABERT-2 runs on Linux/GPU only.
+  `einops` (also required by that code) is a declared dependency. The DNABERT-2
+  tokenizer loads on any platform; only the model weights need Linux/GPU.
+- **Nucleotide Transformer v2** — the tokenizer loads everywhere; the checkpoint
+  needs a transformers version whose ESM implementation matches its gated-MLP
+  shapes. Verify the pairing before relying on it.
+
+For local development on CPU/macOS, use a `from_scratch` model with the `kmer` or
+`char` tokenizer, or a small standard encoder; run bio-specific backbones like
+DNABERT-2 on a Linux/GPU host.
+
+## Structure-aware backbones
+
+The structure-aware encoder adds feature-boundary markers to the vocabulary, so
+its `output_spec.vocab_size` exceeds a base tokenizer's. A `from_scratch` model is
+sized to that vocabulary automatically. To use a pretrained backbone with the
+structure-aware encoder, resize its token embeddings to the encoder's vocab size
+first.

sbol_torch-0.1.0/docs/capabilities.md

@@ -0,0 +1,90 @@
+# Capabilities
+
+sbol-torch trains transformer models on SBOL data. The input modality, training
+objective, data source, and tokenizer are independent axes, each picked in
+configuration. Changing one reuses the same code path rather than branching it.
+
+## Input modalities (`encoder.kind`)
+
+| Modality | Consumes | Model | Config |
+|----------|----------|-------|--------|
+| `sequence` | raw sequence elements | pretrained or from-scratch encoder + pooling + head | [finetune_expression.yaml](../examples/configs/finetune_expression.yaml) |
+| `structure_aware` | sequence + feature boundaries (role, orientation) | same, over an extended vocabulary | [finetune_structure_aware.yaml](../examples/configs/finetune_structure_aware.yaml) |
+| `graph` | the SBOL composition graph | PyG graph transformer (`TransformerConv`) | [train_graph.yaml](../examples/configs/train_graph.yaml) |
+
+- **Sequence** tokenizes the object's elements directly.
+- **Structure-aware** wraps each annotated feature span with role-keyed boundary
+  markers (e.g. `[promoter] … [/promoter]`) and a reverse-complement marker,
+  injected inline as tokens. The markers extend the base tokenizer's vocabulary,
+  so the model sees SBOL structure alongside sequence. Use it with a
+  `from_scratch` model, or a pretrained backbone whose embeddings you've resized.
+- **Graph** turns each object's neighborhood into a graph: nodes carry a
+  `(sbol_class, role, identity)` feature triple, edges carry a predicate type,
+  edges are bidirectional, and a global mean pool feeds the task head.
+
+All three produce batches consumed by one training engine through a
+`BatchAdapter`, so the loop is modality-agnostic (see [extending.md](extending.md)).
+
+## Objectives (`task.kind`)
+
+| Objective | Head / loss | Metrics | Label |
+|-----------|-------------|---------|-------|
+| `frozen` | regression or classification head; backbone frozen | `val_mae`/`val_mse`/`val_r2` or `val_accuracy` | required |
+| `supervised` | same, fine-tuned end to end | same | required |
+| `mlm` | tied LM head; masked cross-entropy | `val_loss` (= masked CE), `val_masked_accuracy` | none (self-supervised) |
+
+- **Supervised regression** supports `target_transform: log1p` for expression/
+  fitness-style targets; metrics are reported back in the original space.
+- **Classification** requires `task.num_classes`.
+- **MLM** masks ~`mlm_probability` of content tokens (80% `<mask>`, 10% random,
+  10% unchanged), never masking special tokens.
+
+## Pretrain, then fine-tune
+
+An `mlm` run writes its trained encoder to `<output_dir>/backbone/` in
+HuggingFace format. A later `supervised`/`frozen` run loads it by setting
+`model.backbone` to that directory — the masked-LM pretraining and the
+downstream task share one backbone.
+
+MLM supports two modes via `model.from_scratch`:
+
+- `true` — build a fresh architecture from `model.arch` + the tokenizer vocab
+  (pretrain a DNA LM on the SBOL corpus with the k-mer/char tokenizer).
+- `false` — continued pretraining of a pretrained `model.backbone`.
+
+## Tokenizers (`tokenizer.kind`)
+
+| Tokenizer | Description |
+|-----------|-------------|
+| `hf` | Any pretrained HuggingFace `AutoTokenizer` (DNABERT-2, Nucleotide Transformer, …), wrapped behind the library's tokenizer protocol. |
+| `kmer` | Overlapping k-mers over `{A,C,G,T}`; ambiguous bases map to `<unk>`. |
+| `char` | IUPAC character-level. |
+
+All expose the same protocol (`vocab_size`, `pad_token_id`, `mask_token_id`,
+`special_token_ids`, `tokenize_content`, `encode`), so tokenizers, encoders, and
+objectives mix freely.
+
+## Metrics
+
+- Regression: MAE, MSE, R² (`val_mae`, `val_mse`, `val_r2`).
+- Classification: accuracy (`val_accuracy`).
+- MLM: masked cross-entropy as `val_loss` (perplexity is `exp(val_loss)`) and
+  `val_masked_accuracy`.
+
+Per-epoch metrics are printed and appended to `<output_dir>/metrics.jsonl`; the
+best checkpoint (by the task's primary metric) is saved to `best.pt`.
+
+## What the test suite verifies
+
+`tests/test_learning.py` trains each capability on a learnable signal and asserts
+that the loss drops and the model generalizes, not just that the code runs:
+
+| Capability | Asserted |
+|------------|----------|
+| Supervised sequence (from scratch) | val_loss falls, `val_r2 > 0.5` |
+| MLM (from scratch) | val_loss falls, masked accuracy rises |
+| Structure-aware | val_loss falls, `val_r2 > 0.5` |
+| Graph transformer | val_loss falls, `val_r2 > 0.5` |
+
+Continued pretraining and pretrained-backbone loading are exercised against a
+real hub model in the data/model tests.