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
```
