sbol-torch 0.1.0

A PyTorch library for synthetic biology and biodesign automation

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 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 (scalars, config, lineage, model artifact)
Reproducibility	one validated config per run, seeded splits, content-fingerprinted Parquet cache

Install

pip install sbol-torch

For development:

uv venv
uv pip install -e '.[dev]'

Quickstart

A run is fully specified by one YAML config. From the command line:

# 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:

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	Frozen DNABERT-2 backbone feeding a regression head.
pretrain_mlm.yaml	From-scratch masked-LM pretraining; writes a reusable backbone.
finetune_structure_aware.yaml	Sequence + feature-boundary markers.
train_graph.yaml	Graph transformer over the composition graph.

Experiment tracking

The two synthetic-data configs (train_graph.yaml and finetune_structure_aware.yaml) ship with Weights & Biases enabled. Set WANDB_API_KEY in a .env at the repo root and run both:

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

Documentation

Doc	Contents
architecture.md	How the system is built — record type, plug points, engine, data flow.
capabilities.md	Modalities, objectives, tokenizers, metrics.
configuration.md	Complete RunConfig reference.
data.md	Data sources, the sbol-db client, materialization, fixtures.
backbones.md	Choosing/loading backbones and environment constraints.
extending.md	Adding a tokenizer, encoder, task, callback, or data source.

Develop

uv run pytest
pre-commit run --all-files