esm3di-training 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. esm3di_training-0.2.0/LICENSE +21 -0
  2. esm3di_training-0.2.0/PKG-INFO +44 -0
  3. esm3di_training-0.2.0/README.md +19 -0
  4. esm3di_training-0.2.0/pyproject.toml +49 -0
  5. esm3di_training-0.2.0/setup.cfg +4 -0
  6. esm3di_training-0.2.0/src/esm3di/esmretrain.py +5 -0
  7. esm3di_training-0.2.0/src/esm3di/esmretrain_mlm.py +5 -0
  8. esm3di_training-0.2.0/src/esm3di/hf_publish.py +7 -0
  9. esm3di_training-0.2.0/src/esm3di/losses.py +4 -0
  10. esm3di_training-0.2.0/src/esm3di/prepare_data.py +9 -0
  11. esm3di_training-0.2.0/src/esm3di/train_3di.py +9 -0
  12. esm3di_training-0.2.0/src/esm3di/train_mlm.py +9 -0
  13. esm3di_training-0.2.0/src/esm3di/training/__init__.py +1 -0
  14. esm3di_training-0.2.0/src/esm3di/training/__main__.py +3 -0
  15. esm3di_training-0.2.0/src/esm3di/training/cli.py +7 -0
  16. esm3di_training-0.2.0/src/esm3di/training/prepare_data.py +7 -0
  17. esm3di_training-0.2.0/src/esm3di/training/train_3di.py +7 -0
  18. esm3di_training-0.2.0/src/esm3di/training/train_mlm.py +7 -0
  19. esm3di_training-0.2.0/src/esm3di_training/__init__.py +1 -0
  20. esm3di_training-0.2.0/src/esm3di_training/__main__.py +3 -0
  21. esm3di_training-0.2.0/src/esm3di_training/cli.py +242 -0
  22. esm3di_training-0.2.0/src/esm3di_training/hf_publish.py +133 -0
  23. esm3di_training-0.2.0/src/esm3di_training/losses.py +659 -0
  24. esm3di_training-0.2.0/src/esm3di_training/prepare_data.py +452 -0
  25. esm3di_training-0.2.0/src/esm3di_training/train_3di.py +820 -0
  26. esm3di_training-0.2.0/src/esm3di_training/train_mlm.py +597 -0
  27. esm3di_training-0.2.0/src/esm3di_training.egg-info/PKG-INFO +44 -0
  28. esm3di_training-0.2.0/src/esm3di_training.egg-info/SOURCES.txt +30 -0
  29. esm3di_training-0.2.0/src/esm3di_training.egg-info/dependency_links.txt +1 -0
  30. esm3di_training-0.2.0/src/esm3di_training.egg-info/entry_points.txt +6 -0
  31. esm3di_training-0.2.0/src/esm3di_training.egg-info/requires.txt +8 -0
  32. esm3di_training-0.2.0/src/esm3di_training.egg-info/top_level.txt +2 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ESM3di Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,44 @@
1
+ Metadata-Version: 2.4
2
+ Name: esm3di-training
3
+ Version: 0.2.0
4
+ Summary: Supported ESM++ MLM and supervised LoRA/CNN training for ESM3Di
5
+ Author: Finn Tjark Weikert, Philippe Le Mercier, Christophe Dessimoz
6
+ Author-email: David Moi <dmoi@unil.ch>, Dongwook Kim <dongwook.kim@unil.ch>
7
+ Maintainer-email: David Moi <dmoi@unil.ch>, Dongwook Kim <dongwook.kim@unil.ch>
8
+ License: MIT
9
+ Project-URL: Homepage, https://github.com/DessimozLab/ESM3di
10
+ Project-URL: Repository, https://github.com/DessimozLab/ESM3di
11
+ Project-URL: Issues, https://github.com/DessimozLab/ESM3di/issues
12
+ Project-URL: Documentation, https://github.com/DessimozLab/ESM3di#training-mlm-followed-by-supervised-3di
13
+ Requires-Python: >=3.10
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Requires-Dist: esm3di==0.2.0
17
+ Requires-Dist: scipy>=1.10.0
18
+ Requires-Dist: pandas>=2.0.0
19
+ Requires-Dist: scikit-learn>=1.3.0
20
+ Requires-Dist: tensorboard>=2.14.0
21
+ Requires-Dist: pyyaml>=6.0
22
+ Requires-Dist: requests>=2.28.0
23
+ Requires-Dist: fsspec>=2023.1.0
24
+ Dynamic: license-file
25
+
26
+ # ESM3Di training distribution
27
+
28
+ This distribution adds the supported ESM++ masked-language-model and supervised
29
+ LoRA/CNN 3Di trainers to the lightweight `esm3di` inference distribution.
30
+
31
+ From the monorepo root, install both local projects:
32
+
33
+ ```bash
34
+ pip install -e . -e ./training
35
+ ```
36
+
37
+ For published packages, use `pip install 'esm3di[training]'`.
38
+ The two wheels own distinct files: `esm3di` provides inference/core; this
39
+ distribution provides `esm3di_training` and the old `esm3di.training` namespace.
40
+ No retired T5, ESM-2, iterative-head, or other experimental implementations are
41
+ included in either wheel. Their source is kept in the research archive.
42
+
43
+ Use `esm3di-learn --help` or `python -m esm3di_training --help`.
44
+ See the repository README and configs for the supported two-stage recipe.
@@ -0,0 +1,19 @@
1
+ # ESM3Di training distribution
2
+
3
+ This distribution adds the supported ESM++ masked-language-model and supervised
4
+ LoRA/CNN 3Di trainers to the lightweight `esm3di` inference distribution.
5
+
6
+ From the monorepo root, install both local projects:
7
+
8
+ ```bash
9
+ pip install -e . -e ./training
10
+ ```
11
+
12
+ For published packages, use `pip install 'esm3di[training]'`.
13
+ The two wheels own distinct files: `esm3di` provides inference/core; this
14
+ distribution provides `esm3di_training` and the old `esm3di.training` namespace.
15
+ No retired T5, ESM-2, iterative-head, or other experimental implementations are
16
+ included in either wheel. Their source is kept in the research archive.
17
+
18
+ Use `esm3di-learn --help` or `python -m esm3di_training --help`.
19
+ See the repository README and configs for the supported two-stage recipe.
@@ -0,0 +1,49 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61.0", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "esm3di-training"
7
+ version = "0.2.0"
8
+ description = "Supported ESM++ MLM and supervised LoRA/CNN training for ESM3Di"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = {text = "MIT"}
12
+ authors = [
13
+ {name = "David Moi", email = "dmoi@unil.ch"},
14
+ {name = "Dongwook Kim", email = "dongwook.kim@unil.ch"},
15
+ {name = "Finn Tjark Weikert"},
16
+ {name = "Philippe Le Mercier"},
17
+ {name = "Christophe Dessimoz"},
18
+ ]
19
+ maintainers = [
20
+ {name = "David Moi", email = "dmoi@unil.ch"},
21
+ {name = "Dongwook Kim", email = "dongwook.kim@unil.ch"},
22
+ ]
23
+ dependencies = [
24
+ "esm3di==0.2.0",
25
+ "scipy>=1.10.0",
26
+ "pandas>=2.0.0",
27
+ "scikit-learn>=1.3.0",
28
+ "tensorboard>=2.14.0",
29
+ "pyyaml>=6.0",
30
+ "requests>=2.28.0",
31
+ "fsspec>=2023.1.0",
32
+ ]
33
+
34
+ [project.urls]
35
+ Homepage = "https://github.com/DessimozLab/ESM3di"
36
+ Repository = "https://github.com/DessimozLab/ESM3di"
37
+ Issues = "https://github.com/DessimozLab/ESM3di/issues"
38
+ Documentation = "https://github.com/DessimozLab/ESM3di#training-mlm-followed-by-supervised-3di"
39
+
40
+ [project.scripts]
41
+ esm3di-learn = "esm3di_training.cli:main"
42
+ esm3di-prepare = "esm3di_training.prepare_data:main"
43
+ esm3di-train-mlm = "esm3di_training.train_mlm:main"
44
+ esm3di-train = "esm3di_training.train_3di:main"
45
+ esm3di-push-to-hub = "esm3di_training.hf_publish:main"
46
+
47
+ [tool.setuptools.packages.find]
48
+ where = ["src"]
49
+ include = ["esm3di_training*", "esm3di", "esm3di.training"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,5 @@
1
+ """Legacy entry point for the supported 3Di trainer."""
2
+ from esm3di_training.train_3di import main
3
+
4
+ if __name__ == "__main__":
5
+ main()
@@ -0,0 +1,5 @@
1
+ """Legacy entry point for the supported MLM trainer."""
2
+ from esm3di_training.train_mlm import main
3
+
4
+ if __name__ == "__main__":
5
+ main()
@@ -0,0 +1,7 @@
1
+ """Compatibility alias for publishing; requires the training distribution."""
2
+ import sys
3
+ from esm3di_training import hf_publish as _implementation
4
+ if __name__ == "__main__":
5
+ _implementation.main()
6
+ else:
7
+ sys.modules[__name__] = _implementation
@@ -0,0 +1,4 @@
1
+ """Compatibility alias; requires the training distribution."""
2
+ import sys
3
+ from esm3di_training import losses as _implementation
4
+ sys.modules[__name__] = _implementation
@@ -0,0 +1,9 @@
1
+ """Compatibility alias for structure preparation."""
2
+
3
+ import sys
4
+ from esm3di_training import prepare_data as _implementation
5
+
6
+ if __name__ == "__main__":
7
+ _implementation.main()
8
+ else:
9
+ sys.modules[__name__] = _implementation
@@ -0,0 +1,9 @@
1
+ """Compatibility alias for the supported 3Di trainer."""
2
+
3
+ import sys
4
+ from esm3di_training import train_3di as _implementation
5
+
6
+ if __name__ == "__main__":
7
+ _implementation.main()
8
+ else:
9
+ sys.modules[__name__] = _implementation
@@ -0,0 +1,9 @@
1
+ """Compatibility alias for the supported MLM trainer."""
2
+
3
+ import sys
4
+ from esm3di_training import train_mlm as _implementation
5
+
6
+ if __name__ == "__main__":
7
+ _implementation.main()
8
+ else:
9
+ sys.modules[__name__] = _implementation
@@ -0,0 +1 @@
1
+ """Compatibility namespace supplied only by the training distribution."""
@@ -0,0 +1,3 @@
1
+ from esm3di_training.cli import main
2
+
3
+ main()
@@ -0,0 +1,7 @@
1
+ """Compatibility alias for the supported learning CLI."""
2
+ import sys
3
+ from esm3di_training import cli as _implementation
4
+ if __name__ == "__main__":
5
+ _implementation.main()
6
+ else:
7
+ sys.modules[__name__] = _implementation
@@ -0,0 +1,7 @@
1
+ """Compatibility alias for structure preparation."""
2
+ import sys
3
+ from esm3di_training import prepare_data as _implementation
4
+ if __name__ == "__main__":
5
+ _implementation.main()
6
+ else:
7
+ sys.modules[__name__] = _implementation
@@ -0,0 +1,7 @@
1
+ """Compatibility alias for the 3Di trainer."""
2
+ import sys
3
+ from esm3di_training import train_3di as _implementation
4
+ if __name__ == "__main__":
5
+ _implementation.main()
6
+ else:
7
+ sys.modules[__name__] = _implementation
@@ -0,0 +1,7 @@
1
+ """Compatibility alias for the MLM trainer."""
2
+ import sys
3
+ from esm3di_training import train_mlm as _implementation
4
+ if __name__ == "__main__":
5
+ _implementation.main()
6
+ else:
7
+ sys.modules[__name__] = _implementation
@@ -0,0 +1 @@
1
+ """Supported ESM++ MLM and supervised 3Di training."""
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ main()
@@ -0,0 +1,242 @@
1
+ """esm3di command line interface.
2
+
3
+ Subcommands:
4
+
5
+ esm3di prepare structures -> train/val(/test) AA, 3Di and pLDDT-bin FASTAs (needs FoldSeek)
6
+ esm3di mlm stage 1: unsupervised masked-LM fine-tuning of ESM++ on sequences
7
+ esm3di train stage 2: supervised 3Di tagging (LoRA + CNN head) [alias: 3di]
8
+ esm3di predict 3Di FASTA (+ optional FoldSeek DB) from amino-acid FASTA
9
+ esm3di foldseekdb AA FASTA + 3Di FASTA -> FoldSeek DB (no model)
10
+ esm3di pipeline prepare -> [mlm] -> train in one command
11
+
12
+ Every training subcommand accepts --config file.json; explicit flags override it.
13
+ Run `esm3di <subcommand> --help` for all options.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import argparse
19
+ import json
20
+ import os
21
+ import sys
22
+ from typing import List, Optional, Sequence
23
+
24
+ from esm3di.checkpoints import DEFAULT_HF_MODEL
25
+
26
+
27
+ # ---------------------------------------------------------------------------
28
+ # Simple subcommands
29
+ # ---------------------------------------------------------------------------
30
+
31
+ def _cmd_prepare(ns):
32
+ from .prepare_data import run_prepare
33
+
34
+ run_prepare(ns)
35
+
36
+
37
+ def _cmd_mlm(ns):
38
+ from . import train_mlm
39
+
40
+ train_mlm.train(train_mlm.resolve_config(ns))
41
+
42
+
43
+ def _cmd_train(ns):
44
+ from . import train_3di
45
+
46
+ train_3di.train(train_3di.resolve_config(ns))
47
+
48
+
49
+ def _cmd_predict(ns):
50
+ from esm3di.predict import run_predict
51
+
52
+ run_predict(ns)
53
+
54
+
55
+ def _add_foldseekdb_args(p):
56
+ p.add_argument("--aa-fasta", required=True)
57
+ p.add_argument("--three-di-fasta", required=True)
58
+ p.add_argument("--output-db", "-o", required=True, help="Output FoldSeek DB prefix.")
59
+
60
+
61
+ def _cmd_foldseekdb(ns):
62
+ from esm3di.foldseek_db import fasta2foldseek
63
+
64
+ fasta2foldseek(ns.aa_fasta, ns.three_di_fasta, ns.output_db)
65
+ print(f"Wrote FoldSeek DB {ns.output_db}")
66
+
67
+
68
+ # ---------------------------------------------------------------------------
69
+ # Pipeline
70
+ # ---------------------------------------------------------------------------
71
+
72
+ def _add_pipeline_args(p):
73
+ g = p.add_argument_group("inputs")
74
+ g.add_argument("--structures", "-s", nargs="+",
75
+ help="Structure dirs/files (.pdb/.cif[.gz]) or .txt path lists; converted with `esm3di prepare`.")
76
+ g.add_argument("--data-dir", help="Already prepared data dir (output of `esm3di prepare`) instead of --structures.")
77
+ g.add_argument("--sequences", nargs="+",
78
+ help="Unlabelled protein FASTA(s) for the MLM stage. Omit to skip MLM.")
79
+ g.add_argument("--mlm-on-structure-sequences", action="store_true",
80
+ help="Also add the training-split sequences of the structures to the MLM corpus "
81
+ "(enables MLM when only structures are given).")
82
+ g = p.add_argument_group("starting point")
83
+ g.add_argument("--init-from", default=DEFAULT_HF_MODEL,
84
+ help="HF model id (e.g. Synthyra/ESMplusplus_small|large), an MLM checkpoint dir, "
85
+ f"or a 3Di .pt checkpoint (default {DEFAULT_HF_MODEL}). With a 3Di .pt the MLM stage is skipped.")
86
+ g = p.add_argument_group("output / control")
87
+ g.add_argument("--out-dir", "-o", required=True, help="Writes data/, mlm/ and 3di/ below this dir.")
88
+ g.add_argument("--resume", action="store_true", help="Reuse prepared data and resume/skip finished stages.")
89
+ g.add_argument("--device")
90
+ g = p.add_argument_group("prepare options")
91
+ g.add_argument("--foldseek-bin")
92
+ g.add_argument("--val-fraction", type=float, default=0.02)
93
+ g.add_argument("--test-fraction", type=float, default=0.0)
94
+ g.add_argument("--cluster-split", action="store_true")
95
+ g.add_argument("--no-plddt", action="store_true", help="Structures have no pLDDT in the B-factor column.")
96
+ g.add_argument("--min-length", type=int, default=20)
97
+ g.add_argument("--max-length", type=int)
98
+ g = p.add_argument_group("MLM stage options")
99
+ g.add_argument("--mlm-config", help="JSON config for the MLM stage (see configs/mlm_*.json).")
100
+ g.add_argument("--mlm-epochs", type=int)
101
+ g.add_argument("--mlm-batch-size", type=int)
102
+ g.add_argument("--mlm-lr", type=float)
103
+ g.add_argument("--mlm-max-train-samples", type=int)
104
+ g = p.add_argument_group("3Di stage options")
105
+ g.add_argument("--train-config", help="JSON config for the 3Di stage (see configs/3di_*.json).")
106
+ g.add_argument("--epochs", type=int)
107
+ g.add_argument("--batch-size", type=int)
108
+ g.add_argument("--lr", type=float)
109
+ g.add_argument("--max-train-samples", type=int)
110
+
111
+
112
+ def _is_3di_checkpoint(path: str) -> bool:
113
+ return os.path.isfile(path) and path.endswith((".pt", ".pth", ".bin"))
114
+
115
+
116
+ def _flags(**kwargs) -> List[str]:
117
+ argv: List[str] = []
118
+ for key, value in kwargs.items():
119
+ if value is None or value is False:
120
+ continue
121
+ flag = "--" + key.replace("_", "-")
122
+ if isinstance(value, (list, tuple)):
123
+ argv += [flag, *map(str, value)]
124
+ else:
125
+ argv += [flag, str(value)]
126
+ return argv
127
+
128
+
129
+ def _cmd_pipeline(ns):
130
+ from . import train_3di, train_mlm
131
+ from .prepare_data import data_files_from_dir, prepare
132
+
133
+ if bool(ns.structures) == bool(ns.data_dir):
134
+ raise SystemExit("pipeline: give exactly one of --structures or --data-dir")
135
+ os.makedirs(ns.out_dir, exist_ok=True)
136
+
137
+ # 1. data
138
+ data_dir = ns.data_dir or os.path.join(ns.out_dir, "data")
139
+ if ns.structures:
140
+ if ns.resume and os.path.exists(os.path.join(data_dir, "manifest.json")):
141
+ print(f"[pipeline] reusing prepared data in {data_dir}")
142
+ else:
143
+ print(f"[pipeline] preparing data from structures -> {data_dir}")
144
+ prepare(
145
+ ns.structures, data_dir, foldseek_bin=ns.foldseek_bin, use_plddt=not ns.no_plddt,
146
+ val_fraction=ns.val_fraction, test_fraction=ns.test_fraction,
147
+ min_length=ns.min_length, max_length=ns.max_length, cluster_split=ns.cluster_split,
148
+ )
149
+ files = data_files_from_dir(data_dir)
150
+
151
+ # 2. MLM
152
+ init_from = ns.init_from
153
+ mlm_inputs = list(ns.sequences or [])
154
+ if ns.mlm_on_structure_sequences:
155
+ mlm_inputs.append(files["aa_fasta"])
156
+ if mlm_inputs:
157
+ if _is_3di_checkpoint(init_from):
158
+ raise SystemExit("pipeline: --init-from is a 3Di checkpoint; MLM cannot start from it. "
159
+ "Drop --sequences or start from an HF model / MLM dir.")
160
+ mlm_dir = os.path.join(ns.out_dir, "mlm")
161
+ done = os.path.exists(os.path.join(mlm_dir, "final", "esm3di_mlm.json"))
162
+ if ns.resume and done:
163
+ print(f"[pipeline] MLM stage already finished in {mlm_dir}")
164
+ else:
165
+ print(f"[pipeline] MLM stage: {init_from} on {len(mlm_inputs)} FASTA(s) -> {mlm_dir}")
166
+ argv = (["--config", ns.mlm_config] if ns.mlm_config else []) + _flags(
167
+ input_fasta=mlm_inputs, model_name=init_from, output_dir=mlm_dir,
168
+ epochs=ns.mlm_epochs, batch_size=ns.mlm_batch_size, learning_rate=ns.mlm_lr,
169
+ max_train_samples=ns.mlm_max_train_samples, device=ns.device,
170
+ resume="auto" if ns.resume else None,
171
+ )
172
+ parser = train_mlm.add_train_mlm_args(argparse.ArgumentParser())
173
+ mlm_cfg = train_mlm.resolve_config(parser.parse_args(argv))
174
+ # The pipeline owns the data: never pick up data paths from --mlm-config.
175
+ mlm_cfg["input_txt"] = None
176
+ mlm_cfg["val_fasta"] = [files["val_aa_fasta"]] if files.get("val_aa_fasta") else None
177
+ mlm_cfg["test_fasta"] = None
178
+ train_mlm.train(mlm_cfg)
179
+ best = os.path.join(mlm_dir, "best")
180
+ init_from = best if os.path.isdir(best) else os.path.join(mlm_dir, "final")
181
+
182
+ # 3. 3Di
183
+ tdi_dir = os.path.join(ns.out_dir, "3di")
184
+ print(f"[pipeline] 3Di stage: init from {init_from} -> {tdi_dir}")
185
+ argv = (["--config", ns.train_config] if ns.train_config else []) + _flags(
186
+ data_dir=data_dir, init_from=init_from, out_dir=tdi_dir, epochs=ns.epochs,
187
+ batch_size=ns.batch_size, lr=ns.lr, max_train_samples=ns.max_train_samples,
188
+ device=ns.device, resume="auto" if ns.resume else None,
189
+ )
190
+ parser = train_3di.add_train_3di_args(argparse.ArgumentParser())
191
+ tdi_cfg = train_3di.resolve_config(parser.parse_args(argv))
192
+ # The pipeline owns data and output locations, whatever --train-config says.
193
+ tdi_cfg.update(files)
194
+ if tdi_cfg.get("tensorboard_log_dir"):
195
+ tdi_cfg["tensorboard_log_dir"] = os.path.join(tdi_dir, "tensorboard")
196
+ best_ckpt = train_3di.train(tdi_cfg)
197
+
198
+ summary = {"data_dir": data_dir, "init_from_3di": init_from, "best_3di_checkpoint": best_ckpt}
199
+ with open(os.path.join(ns.out_dir, "pipeline.json"), "w") as fh:
200
+ json.dump(summary, fh, indent=2)
201
+ print(f"[pipeline] done. Best 3Di checkpoint: {best_ckpt}")
202
+ print(f" predict with: esm3di predict --checkpoint {best_ckpt} -i proteins.fasta -o proteins_3di.fasta")
203
+
204
+
205
+ # ---------------------------------------------------------------------------
206
+
207
+ def build_parser(include_inference: bool = False) -> argparse.ArgumentParser:
208
+ from .prepare_data import add_prepare_args
209
+ from .train_3di import add_train_3di_args
210
+ from .train_mlm import add_train_mlm_args
211
+
212
+ parser = argparse.ArgumentParser(
213
+ prog="esm3di" if include_inference else "esm3di-learn",
214
+ description="ESM++ learning: prepare structures, fine-tune MLM, and train 3Di.",
215
+ formatter_class=argparse.RawDescriptionHelpFormatter
216
+ )
217
+ sub = parser.add_subparsers(dest="command", required=True, metavar="<command>")
218
+
219
+ def add(name, adder, func, help_, aliases=()):
220
+ sp = sub.add_parser(name, help=help_, description=help_, aliases=list(aliases))
221
+ adder(sp)
222
+ sp.set_defaults(func=func)
223
+
224
+ add("prepare", add_prepare_args, _cmd_prepare, "Build training FASTAs from structures with FoldSeek.")
225
+ add("mlm", add_train_mlm_args, _cmd_mlm, "Stage 1: masked-LM fine-tuning of ESM++ on sequences.")
226
+ add("train", add_train_3di_args, _cmd_train, "Stage 2: supervised 3Di token training.", aliases=["3di"])
227
+ if include_inference:
228
+ from esm3di.predict import add_predict_args
229
+
230
+ add("predict", add_predict_args, _cmd_predict, "Predict 3Di from amino-acid FASTA.")
231
+ add("foldseekdb", _add_foldseekdb_args, _cmd_foldseekdb, "Write a FoldSeek DB from AA + 3Di FASTAs.")
232
+ add("pipeline", _add_pipeline_args, _cmd_pipeline, "prepare -> [mlm] -> train in one command.")
233
+ return parser
234
+
235
+
236
+ def main(argv: Optional[Sequence[str]] = None, include_inference: bool = False):
237
+ ns = build_parser(include_inference=include_inference).parse_args(argv)
238
+ ns.func(ns)
239
+
240
+
241
+ if __name__ == "__main__":
242
+ main(sys.argv[1:])
@@ -0,0 +1,133 @@
1
+ #!/usr/bin/env python
2
+ """Utilities for publishing ESM3Di artifacts to Hugging Face Hub."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import argparse
7
+ import os
8
+ from pathlib import Path
9
+
10
+ from huggingface_hub import HfApi
11
+
12
+
13
+ def _resolve_hf_token(token_env_var: str) -> str | None:
14
+ """Resolve token from environment if available."""
15
+ return os.getenv(token_env_var) or os.getenv("HF_TOKEN") or os.getenv("HUGGINGFACE_HUB_TOKEN")
16
+
17
+
18
+ def _require_hf_token(token_env_var: str) -> str:
19
+ """Return HF token or raise a clear configuration error."""
20
+ token = _resolve_hf_token(token_env_var)
21
+ if token:
22
+ return token
23
+ raise RuntimeError(
24
+ "No Hugging Face token found. Set one of these environment variables: "
25
+ f"{token_env_var}, HF_TOKEN, or HUGGINGFACE_HUB_TOKEN."
26
+ )
27
+
28
+
29
+ def publish_directory_to_hub(
30
+ local_dir: str | Path,
31
+ repo_id: str,
32
+ *,
33
+ private: bool = False,
34
+ revision: str = "main",
35
+ commit_message: str = "Upload model artifacts",
36
+ token_env_var: str = "HF_TOKEN",
37
+ ) -> str:
38
+ """Upload a local directory to a Hugging Face model repository."""
39
+ local_dir = Path(local_dir)
40
+ if not local_dir.exists() or not local_dir.is_dir():
41
+ raise FileNotFoundError(f"Directory does not exist: {local_dir}")
42
+
43
+ token = _require_hf_token(token_env_var)
44
+ api = HfApi(token=token)
45
+ api.create_repo(repo_id=repo_id, repo_type="model", private=private, exist_ok=True)
46
+
47
+ api.upload_folder(
48
+ folder_path=str(local_dir),
49
+ repo_id=repo_id,
50
+ repo_type="model",
51
+ revision=revision,
52
+ commit_message=commit_message,
53
+ )
54
+ return f"https://huggingface.co/{repo_id}"
55
+
56
+
57
+ def publish_file_to_hub(
58
+ local_file: str | Path,
59
+ repo_id: str,
60
+ *,
61
+ path_in_repo: str,
62
+ private: bool = False,
63
+ revision: str = "main",
64
+ commit_message: str = "Upload model artifact",
65
+ token_env_var: str = "HF_TOKEN",
66
+ ) -> str:
67
+ """Upload a single file to a Hugging Face model repository."""
68
+ local_file = Path(local_file)
69
+ if not local_file.exists() or not local_file.is_file():
70
+ raise FileNotFoundError(f"File does not exist: {local_file}")
71
+
72
+ token = _require_hf_token(token_env_var)
73
+ api = HfApi(token=token)
74
+ api.create_repo(repo_id=repo_id, repo_type="model", private=private, exist_ok=True)
75
+
76
+ api.upload_file(
77
+ path_or_fileobj=str(local_file),
78
+ path_in_repo=path_in_repo,
79
+ repo_id=repo_id,
80
+ repo_type="model",
81
+ revision=revision,
82
+ commit_message=commit_message,
83
+ )
84
+ return f"https://huggingface.co/{repo_id}"
85
+
86
+
87
+ def main() -> None:
88
+ parser = argparse.ArgumentParser(
89
+ description="Publish ESM3Di artifacts (directories or files) to Hugging Face Hub.",
90
+ )
91
+ parser.add_argument("--repo-id", required=True, help="Target model repository id, e.g. org/esm3di-model")
92
+ parser.add_argument("--local-dir", default=None, help="Local directory to upload with upload_folder")
93
+ parser.add_argument("--local-file", default=None, help="Local file to upload with upload_file")
94
+ parser.add_argument("--path-in-repo", default=None, help="Required when --local-file is provided")
95
+ parser.add_argument("--private", action="store_true", help="Create private repository if it does not exist")
96
+ parser.add_argument("--revision", default="main", help="Target revision/branch in HF repo")
97
+ parser.add_argument("--commit-message", default="Upload model artifacts", help="Commit message for upload")
98
+ parser.add_argument("--token-env-var", default="HF_TOKEN", help="Env var used to read HF token")
99
+ args = parser.parse_args()
100
+
101
+ has_dir = bool(args.local_dir)
102
+ has_file = bool(args.local_file)
103
+ if has_dir == has_file:
104
+ parser.error("Provide exactly one of --local-dir or --local-file")
105
+
106
+ if has_file and not args.path_in_repo:
107
+ parser.error("--path-in-repo is required when using --local-file")
108
+
109
+ if has_dir:
110
+ repo_url = publish_directory_to_hub(
111
+ local_dir=args.local_dir,
112
+ repo_id=args.repo_id,
113
+ private=args.private,
114
+ revision=args.revision,
115
+ commit_message=args.commit_message,
116
+ token_env_var=args.token_env_var,
117
+ )
118
+ else:
119
+ repo_url = publish_file_to_hub(
120
+ local_file=args.local_file,
121
+ path_in_repo=args.path_in_repo,
122
+ repo_id=args.repo_id,
123
+ private=args.private,
124
+ revision=args.revision,
125
+ commit_message=args.commit_message,
126
+ token_env_var=args.token_env_var,
127
+ )
128
+
129
+ print(f"Published to {repo_url}")
130
+
131
+
132
+ if __name__ == "__main__":
133
+ main()