synbio-torch 0.2.0__tar.gz

synbio_torch-0.2.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.

synbio_torch-0.2.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: synbio-torch
+Version: 0.2.0
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic>=2.13
+Requires-Dist: pyarrow>=24
+Requires-Dist: numpy>=2.4
+Requires-Dist: pyyaml>=6
+Requires-Dist: torch>=2.12
+Requires-Dist: transformers>=4.57,<5
+Requires-Dist: tokenizers>=0.22
+Requires-Dist: einops>=0.8
+Requires-Dist: torch-geometric>=2.8
+Requires-Dist: wandb>=0.27
+Requires-Dist: pytest>=9 ; extra == 'dev'
+Requires-Dist: pytest-mock>=3.15 ; extra == 'dev'
+Requires-Dist: respx>=0.23 ; extra == 'dev'
+Requires-Dist: black>=26.5 ; extra == 'dev'
+Requires-Dist: isort>=8 ; extra == 'dev'
+Requires-Dist: flake8>=7.3 ; extra == 'dev'
+Requires-Dist: mypy>=2.1 ; extra == 'dev'
+Requires-Dist: pre-commit>=4.6 ; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0 ; extra == 'dev'
+Requires-Dist: maturin>=1.7 ; extra == 'dev'
+Provides-Extra: dev
+License-File: LICENSE
+Summary: A PyTorch library for synthetic biology and biodesign machine learning
+Author-email: Mike Arpaia <mike@arpaia.co>
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# synbio-torch
+
+A PyTorch library for synthetic biology and biodesign machine learning.
+
+Installed as `synbio-torch`, imported as `synbiotorch` (commonly `import synbiotorch as st`).
+
+synbio-torch ingests biological designs and sequences from many sources — labeled
+FASTA, CSV/TSV tables, GenBank, SBOL, an [sbol-db](https://github.com/marpaia/sbol-db)
+instance, or a synthetic generator — normalizes them into a single record type
+(`Design`), 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. GenBank and SBOL are parsed
+in-process by native [sbol-rs](https://github.com/marpaia/sbol-rs) bindings.
+
+## Capabilities
+
+| Axis | Options |
+|------|---------|
+| **Data sources** | labeled **FASTA**, CSV/TSV **tables**, **GenBank**, **SBOL** (2 & 3), the sbol-db REST API, or a **synthetic** generator; loaded in-memory or **streamed** from sharded Parquet for corpora larger than RAM |
+| **Tokenizers** | pretrained HuggingFace (`hf`), overlapping k-mer, or character-level over a nucleotide **or protein** alphabet (encode + decode) |
+| **Modalities** | `sequence`, `structure_aware` (feature boundaries), `graph` (PyG composition transformer) |
+| **Objectives** | `supervised` / `frozen` heads, `mlm` and `causal` pretraining (from-scratch or continued) |
+| **Architectures** | from-scratch or pretrained; absolute or **RoPE** positions (`gpt_neox`/`llama`/`modernbert`), SDPA/FlashAttention, configurable context length |
+| **Generation** | autoregressive sampling (temperature / top-k / top-p) and design completion from a causal backbone (`synbiotorch generate`) |
+| **Engine** | raw-PyTorch loop, epoch- or **step-budgeted**; AMP (`fp16`/`bf16`), gradient accumulation/clipping, gradient checkpointing, `torch.compile`; **resumable** checkpoints; early stopping; LR schedule |
+| **Scaling** | token **packing**, multi-GPU **DDP** (data-parallel) via `torchrun` |
+| **Tracking** | per-epoch `metrics.jsonl`, optional [Weights & Biases](https://docs.wandb.ai/) (scalars, config, lineage, model artifact) |
+| **Reproducibility** | one validated config per run, seeded / hash splits, content-fingerprinted sharded Parquet cache, resumable runs |
+
+## Install
+
+```bash
+pip install synbio-torch
+```
+
+synbio-torch ships a native extension (PyO3 bindings to the sbol-rs Rust crates).
+Building from source needs a Rust toolchain (≥ 1.93); a prebuilt wheel needs none.
+
+For development, build the extension into the venv with maturin:
+
+```bash
+uv venv
+uv pip install -e '.[dev]'    # compiles the Rust extension on install
+# After editing Rust under rust/, rebuild with:
+uv run maturin develop
+```
+
+## 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).
+synbiotorch ingest examples/configs/finetune_expression.yaml
+
+# Train. Resolved config, per-epoch metrics.jsonl, and best.pt land in output_dir.
+synbiotorch train examples/configs/finetune_expression.yaml
+
+# Resume an interrupted run from its rolling checkpoint (needs checkpoint_every_n_steps).
+synbiotorch train examples/configs/pretrain_mlm.yaml --resume runs/pretrain_mlm/last.pt
+
+# Generate from a trained causal backbone — point model.backbone at the run's
+# backbone/ (with from_scratch: false), then complete a design from a prompt.
+synbiotorch generate my_causal_run.yaml --prompt ATGCGT --max-new-tokens 200 --temperature 0.8
+```
+
+Train multi-GPU with `torchrun` and `train.distributed.strategy: ddp`:
+
+```bash
+torchrun --nproc_per_node=<gpus> -m synbiotorch.cli train examples/configs/pretrain_causal_long.yaml
+```
+
+Or from Python:
+
+```python
+import synbiotorch 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/synbio-torch/blob/master/examples/configs/finetune_expression.yaml) | Frozen DNABERT-2 backbone feeding a regression head. |
+| [`pretrain_mlm.yaml`](https://github.com/marpaia/synbio-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/synbio-torch/blob/master/examples/configs/finetune_structure_aware.yaml) | Sequence + feature-boundary markers. |
+| [`train_graph.yaml`](https://github.com/marpaia/synbio-torch/blob/master/examples/configs/train_graph.yaml) | Graph transformer over the composition graph. |
+| [`pretrain_causal_long.yaml`](https://github.com/marpaia/synbio-torch/blob/master/examples/configs/pretrain_causal_long.yaml) | Long-context causal pretraining: RoPE decoder, SDPA, streamed + packed corpus. |
+| [`finetune_protein.yaml`](https://github.com/marpaia/synbio-torch/blob/master/examples/configs/finetune_protein.yaml) | Protein regression from a labeled CSV table with the protein char tokenizer. |
+| [`benchmark_dna_classification.yaml`](https://github.com/marpaia/synbio-torch/blob/master/examples/configs/benchmark_dna_classification.yaml) | Genomics-ML benchmark shape: a labeled table fed to a pretrained DNA backbone for classification. |
+| [`ingest_genbank.yaml`](https://github.com/marpaia/synbio-torch/blob/master/examples/configs/ingest_genbank.yaml) | Import GenBank to the Parquet cache via the native binding. |
+
+## Experiment tracking
+
+The two synthetic-data configs ([`train_graph.yaml`](https://github.com/marpaia/synbio-torch/blob/master/examples/configs/train_graph.yaml)
+and [`finetune_structure_aware.yaml`](https://github.com/marpaia/synbio-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/synbio-torch/master/docs/images/wandb_train_graph.png) | ![structure_aware W&B run](https://raw.githubusercontent.com/marpaia/synbio-torch/master/docs/images/wandb_structure_aware.png) |
+
+## Documentation
+
+| Doc | Contents |
+|-----|----------|
+| [architecture.md](https://github.com/marpaia/synbio-torch/blob/master/docs/architecture.md) | How the system is built — record type, plug points, engine, data flow. |
+| [capabilities.md](https://github.com/marpaia/synbio-torch/blob/master/docs/capabilities.md) | Modalities, objectives, tokenizers, metrics. |
+| [configuration.md](https://github.com/marpaia/synbio-torch/blob/master/docs/configuration.md) | Complete `RunConfig` reference. |
+| [data.md](https://github.com/marpaia/synbio-torch/blob/master/docs/data.md) | Data sources, native parsing, materialization, fixtures. |
+| [backbones.md](https://github.com/marpaia/synbio-torch/blob/master/docs/backbones.md) | Choosing/loading backbones and environment constraints. |
+| [extending.md](https://github.com/marpaia/synbio-torch/blob/master/docs/extending.md) | Adding a tokenizer, encoder, task, callback, or data source. |
+
+Release history is in [CHANGELOG.md](https://github.com/marpaia/synbio-torch/blob/master/CHANGELOG.md).
+
+## Develop
+
+```bash
+uv run maturin develop      # rebuild the Rust extension after editing rust/
+uv run pytest
+pre-commit run --all-files
+```
+

synbio_torch-0.2.0/README.md

@@ -0,0 +1,133 @@
+# synbio-torch
+
+A PyTorch library for synthetic biology and biodesign machine learning.
+
+Installed as `synbio-torch`, imported as `synbiotorch` (commonly `import synbiotorch as st`).
+
+synbio-torch ingests biological designs and sequences from many sources — labeled
+FASTA, CSV/TSV tables, GenBank, SBOL, an [sbol-db](https://github.com/marpaia/sbol-db)
+instance, or a synthetic generator — normalizes them into a single record type
+(`Design`), 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. GenBank and SBOL are parsed
+in-process by native [sbol-rs](https://github.com/marpaia/sbol-rs) bindings.
+
+## Capabilities
+
+| Axis | Options |
+|------|---------|
+| **Data sources** | labeled **FASTA**, CSV/TSV **tables**, **GenBank**, **SBOL** (2 & 3), the sbol-db REST API, or a **synthetic** generator; loaded in-memory or **streamed** from sharded Parquet for corpora larger than RAM |
+| **Tokenizers** | pretrained HuggingFace (`hf`), overlapping k-mer, or character-level over a nucleotide **or protein** alphabet (encode + decode) |
+| **Modalities** | `sequence`, `structure_aware` (feature boundaries), `graph` (PyG composition transformer) |
+| **Objectives** | `supervised` / `frozen` heads, `mlm` and `causal` pretraining (from-scratch or continued) |
+| **Architectures** | from-scratch or pretrained; absolute or **RoPE** positions (`gpt_neox`/`llama`/`modernbert`), SDPA/FlashAttention, configurable context length |
+| **Generation** | autoregressive sampling (temperature / top-k / top-p) and design completion from a causal backbone (`synbiotorch generate`) |
+| **Engine** | raw-PyTorch loop, epoch- or **step-budgeted**; AMP (`fp16`/`bf16`), gradient accumulation/clipping, gradient checkpointing, `torch.compile`; **resumable** checkpoints; early stopping; LR schedule |
+| **Scaling** | token **packing**, multi-GPU **DDP** (data-parallel) via `torchrun` |
+| **Tracking** | per-epoch `metrics.jsonl`, optional [Weights & Biases](https://docs.wandb.ai/) (scalars, config, lineage, model artifact) |
+| **Reproducibility** | one validated config per run, seeded / hash splits, content-fingerprinted sharded Parquet cache, resumable runs |
+
+## Install
+
+```bash
+pip install synbio-torch
+```
+
+synbio-torch ships a native extension (PyO3 bindings to the sbol-rs Rust crates).
+Building from source needs a Rust toolchain (≥ 1.93); a prebuilt wheel needs none.
+
+For development, build the extension into the venv with maturin:
+
+```bash
+uv venv
+uv pip install -e '.[dev]'    # compiles the Rust extension on install
+# After editing Rust under rust/, rebuild with:
+uv run maturin develop
+```
+
+## 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).
+synbiotorch ingest examples/configs/finetune_expression.yaml
+
+# Train. Resolved config, per-epoch metrics.jsonl, and best.pt land in output_dir.
+synbiotorch train examples/configs/finetune_expression.yaml
+
+# Resume an interrupted run from its rolling checkpoint (needs checkpoint_every_n_steps).
+synbiotorch train examples/configs/pretrain_mlm.yaml --resume runs/pretrain_mlm/last.pt
+
+# Generate from a trained causal backbone — point model.backbone at the run's
+# backbone/ (with from_scratch: false), then complete a design from a prompt.
+synbiotorch generate my_causal_run.yaml --prompt ATGCGT --max-new-tokens 200 --temperature 0.8
+```
+
+Train multi-GPU with `torchrun` and `train.distributed.strategy: ddp`:
+
+```bash
+torchrun --nproc_per_node=<gpus> -m synbiotorch.cli train examples/configs/pretrain_causal_long.yaml
+```
+
+Or from Python:
+
+```python
+import synbiotorch 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/synbio-torch/blob/master/examples/configs/finetune_expression.yaml) | Frozen DNABERT-2 backbone feeding a regression head. |
+| [`pretrain_mlm.yaml`](https://github.com/marpaia/synbio-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/synbio-torch/blob/master/examples/configs/finetune_structure_aware.yaml) | Sequence + feature-boundary markers. |
+| [`train_graph.yaml`](https://github.com/marpaia/synbio-torch/blob/master/examples/configs/train_graph.yaml) | Graph transformer over the composition graph. |
+| [`pretrain_causal_long.yaml`](https://github.com/marpaia/synbio-torch/blob/master/examples/configs/pretrain_causal_long.yaml) | Long-context causal pretraining: RoPE decoder, SDPA, streamed + packed corpus. |
+| [`finetune_protein.yaml`](https://github.com/marpaia/synbio-torch/blob/master/examples/configs/finetune_protein.yaml) | Protein regression from a labeled CSV table with the protein char tokenizer. |
+| [`benchmark_dna_classification.yaml`](https://github.com/marpaia/synbio-torch/blob/master/examples/configs/benchmark_dna_classification.yaml) | Genomics-ML benchmark shape: a labeled table fed to a pretrained DNA backbone for classification. |
+| [`ingest_genbank.yaml`](https://github.com/marpaia/synbio-torch/blob/master/examples/configs/ingest_genbank.yaml) | Import GenBank to the Parquet cache via the native binding. |
+
+## Experiment tracking
+
+The two synthetic-data configs ([`train_graph.yaml`](https://github.com/marpaia/synbio-torch/blob/master/examples/configs/train_graph.yaml)
+and [`finetune_structure_aware.yaml`](https://github.com/marpaia/synbio-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/synbio-torch/master/docs/images/wandb_train_graph.png) | ![structure_aware W&B run](https://raw.githubusercontent.com/marpaia/synbio-torch/master/docs/images/wandb_structure_aware.png) |
+
+## Documentation
+
+| Doc | Contents |
+|-----|----------|
+| [architecture.md](https://github.com/marpaia/synbio-torch/blob/master/docs/architecture.md) | How the system is built — record type, plug points, engine, data flow. |
+| [capabilities.md](https://github.com/marpaia/synbio-torch/blob/master/docs/capabilities.md) | Modalities, objectives, tokenizers, metrics. |
+| [configuration.md](https://github.com/marpaia/synbio-torch/blob/master/docs/configuration.md) | Complete `RunConfig` reference. |
+| [data.md](https://github.com/marpaia/synbio-torch/blob/master/docs/data.md) | Data sources, native parsing, materialization, fixtures. |
+| [backbones.md](https://github.com/marpaia/synbio-torch/blob/master/docs/backbones.md) | Choosing/loading backbones and environment constraints. |
+| [extending.md](https://github.com/marpaia/synbio-torch/blob/master/docs/extending.md) | Adding a tokenizer, encoder, task, callback, or data source. |
+
+Release history is in [CHANGELOG.md](https://github.com/marpaia/synbio-torch/blob/master/CHANGELOG.md).
+
+## Develop
+
+```bash
+uv run maturin develop      # rebuild the Rust extension after editing rust/
+uv run pytest
+pre-commit run --all-files
+```

synbio_torch-0.2.0/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+# Distribution name on PyPI is hyphenated (`pip install synbio-torch`); the import
+# package is `synbiotorch` (commonly `import synbiotorch as st`).
+name = "synbio-torch"
+version = "0.2.0"
+description = "A PyTorch library for synthetic biology and biodesign machine learning"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Mike Arpaia", email = "mike@arpaia.co" }]
+dependencies = [
+    "httpx>=0.28",
+    "pydantic>=2.13",
+    "pyarrow>=24",
+    "numpy>=2.4",
+    "pyyaml>=6",
+    "torch>=2.12",
+    # Pin to the 4.x line: transformers 5.x breaks the custom/ESM modeling code
+    # the pretrained DNA backbones (Nucleotide Transformer, DNABERT) target.
+    "transformers>=4.57,<5",
+    "tokenizers>=0.22",
+    "einops>=0.8",
+    "torch-geometric>=2.8",
+    "wandb>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9",
+    "pytest-mock>=3.15",
+    "respx>=0.23",
+    "black>=26.5",
+    "isort>=8",
+    "flake8>=7.3",
+    "mypy>=2.1",
+    "pre-commit>=4.6",
+    "types-PyYAML>=6.0",
+    "maturin>=1.7",
+]
+
+[project.scripts]
+synbiotorch = "synbiotorch.cli:main"
+
+[build-system]
+requires = ["maturin>=1.7,<2"]
+build-backend = "maturin"
+
+[tool.maturin]
+# Mixed Python/Rust project: Python lives under src/, the Rust crate under rust/.
+# The compiled extension is importable as ``synbiotorch._sbol``.
+python-source = "src"
+manifest-path = "rust/Cargo.toml"
+module-name = "synbiotorch._sbol"
+features = ["pyo3/extension-module"]
+# Bundle the license into the sdist; its metadata declares License-File: LICENSE.
+include = ["LICENSE"]
+
+[tool.black]
+line-length = 120
+target-version = ["py311"]
+
+[tool.isort]
+profile = "black"
+line_length = 120
+# Confine first-party detection to the source tree so import grouping is
+# deterministic across machines. Without this, isort's auto-detection varies by
+# OS and installed packages (e.g. misclassifying wandb as first-party), making
+# the same code pass on one host and fail on another.
+src_paths = ["src"]
+known_first_party = ["synbiotorch"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_unused_configs = true
+disallow_untyped_defs = true
+ignore_missing_imports = true
+files = ["src/synbiotorch"]