scigantic-msa 0.2.0__tar.gz

scigantic_msa-0.2.0/LICENSE

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

scigantic_msa-0.2.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: scigantic-msa
+Version: 0.2.0
+Summary: Get a protein MSA once from the ColabFold MMseqs2 server, or bring your own A3M, and write the input files for AlphaFold 3, Boltz, Chai-1, ColabFold, OpenFold3 or Protenix.
+Author: Scigantic
+License: MIT
+Project-URL: Homepage, https://github.com/Scigantic/scigantic-msa
+Project-URL: Repository, https://github.com/Scigantic/scigantic-msa
+Project-URL: Issues, https://github.com/Scigantic/scigantic-msa/issues
+Keywords: msa,a3m,protein,alphafold3,boltz,chai,colabfold,openfold,protenix,structure-prediction
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Environment :: Console
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: chai
+Requires-Dist: pyarrow>=12; extra == "chai"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pyarrow>=12; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+# scigantic-msa
+
+Get a multiple sequence alignment (MSA) for a protein sequence once, and
+write the input files for the structure predictor you are about to run:
+AlphaFold 3, Boltz, Chai-1, ColabFold, OpenFold3 or Protenix.
+
+The alignment comes from the ColabFold MMseqs2 server (or NVIDIA's MSA
+Search, if you have a key), or from an A3M file you already have. There is
+no account and no login, and nothing is stored on our side.
+
+## Install
+
+```
+pip install scigantic-msa            # or: uv tool install scigantic-msa
+pip install 'scigantic-msa[chai]'    # adds pyarrow, needed for Chai-1 files
+```
+
+Python 3.10 or newer. The core has no dependencies.
+
+## Privacy
+
+Your sequence may be unpublished, so read this before you run a search.
+
+- `run` and `MSA().get()` send the sequence to a third-party server:
+  api.colabfold.com by default. The public ColabFold server needs no login
+  to read a result, and the job id is a hash of the sequence, so anyone who
+  knows the sequence can download the result. Treat a submission there as
+  publishing the sequence.
+- The Python API refuses to send anything unless you pass `remote=True`.
+  The command line says which server will receive the sequence and asks
+  once; `--yes` skips the question for scripts. Without a terminal and
+  without `--yes`, it stops and sends nothing.
+- `convert` and `MSA().from_a3m()` make no network connection at all.
+- The only network traffic is to the server you chose. The tool never
+  contacts a Scigantic server.
+- The sequence is never written to a log. Results are kept in a local cache
+  (`~/.cache/scigantic-msa`, or `SCIGANTIC_MSA_CACHE`) so the same sequence
+  is not submitted twice; delete the directory to forget them, or pass
+  `--no-cache`.
+- `SCIGANTIC_MSA_NO_REMOTE=1` blocks every search, whatever the code asks.
+
+The public ColabFold server is a shared resource with a rate limit of about
+one new job per minute per IP address. This client backs off, honours
+Retry-After, resumes a job from its id instead of submitting it again, and
+gives up after a bounded wait. To use your own server, pass `--host URL`
+(or `MSA(host=URL)`).
+
+## Command line
+
+```
+scigantic-msa run SEQ_OR_FASTA --model boltz --out job/
+scigantic-msa run chains.fasta --model af3 --out job/ --yes
+scigantic-msa convert my_alignment.a3m --model protenix --out job/
+scigantic-msa version
+```
+
+`--model` is one of `af3`, `boltz`, `chai`, `colabfold`, `openfold3`,
+`protenix`. A FASTA file with several records is one complex, one chain per
+record; `:` inside a sequence also separates chains. `convert` takes one
+A3M (or `.a3m.gz`, or Stockholm `.sto`) per chain, in chain order.
+`--server nvidia` uses NVIDIA's hosted MSA Search and needs
+`NVIDIA_API_KEY`.
+
+After writing the files, the command prints the command to run the model
+on them.
+
+## Python
+
+Every adapter takes one result, or a list of results for the chains of a
+complex. The result carries its sequence; if you also pass the sequence,
+it must match.
+
+AlphaFold 3:
+
+```python
+import json
+from scigantic_msa import MSA
+from scigantic_msa.adapters import AlphaFold3
+result = MSA().get(sequence, remote=True)
+json.dump(AlphaFold3.prepare(result, name="job"), open("job.json", "w"))
+```
+
+Boltz:
+
+```python
+from scigantic_msa import MSA
+from scigantic_msa.adapters import Boltz
+result = MSA().get(sequence, remote=True)
+yaml_text = Boltz.prepare(result, out_dir="boltz/")
+open("job.yaml", "w").write(yaml_text)        # then: boltz predict job.yaml
+```
+
+Chai-1:
+
+```python
+from scigantic_msa import MSA
+from scigantic_msa.adapters import Chai
+result = MSA().get(sequence, remote=True)
+msa_dir = Chai.prepare(result, out_dir="chai_msas/")
+open("job.fasta", "w").write(Chai.fasta(result))   # chai-lab fold --msa-directory chai_msas/ job.fasta out/
+```
+
+Protenix:
+
+```python
+import json
+from scigantic_msa import MSA
+from scigantic_msa.adapters import Protenix
+result = MSA().get(sequence, remote=True)
+json.dump(Protenix.prepare(result, out_dir="protenix_msas/"), open("job.json", "w"))
+```
+
+ColabFold and OpenFold3 work the same way: `ColabFold.prepare(result,
+out_dir=...)` returns the path of the A3M for `colabfold_batch`, and
+`OpenFold3.prepare(result, out_dir=...)` returns the query JSON as a dict.
+
+With an alignment you already have, and no network:
+
+```python
+result = MSA().from_a3m("my_alignment.a3m", sequence=sequence)
+```
+
+## Checks
+
+- An A3M is checked strictly: the first record must be the query (no gaps,
+  no lowercase), only `A-Z`, `a-z` and `-` are allowed, and every row must
+  have as many match columns as the query has residues.
+- Each adapter reads back what it wrote: every file it names exists, is not
+  empty, starts with the chain's sequence, and has the name the model looks
+  for. Chai-1 skips a chain's MSA without an error when the file name is
+  wrong, and Protenix ignores a file in `precomputed_msa_dir` that is not
+  called `pairing.a3m` or `non_pairing.a3m`; here both are errors.
+- `Protenix.check(path_or_jobs)` runs the same checks on any Protenix input
+  JSON, including a missing `*MsaPath`, which would make Protenix start its
+  own MSA search and send the sequence to a server.
+
+## Complexes
+
+Each chain gets its own unpaired MSA. Rows are paired across chains only
+where the rows say the species: an NCBI taxid (from ColabFold's taxonomy
+output, or `TaxID=` / `OX=` in headers) or a UniProt species code.
+Environmental and metagenomic hits have none and stay unpaired. When
+pairing is not possible the tool says why, for example "no species is
+shared by all chains; the chains get unpaired MSAs".
+
+| model | how pairing is passed on |
+| --- | --- |
+| AlphaFold 3 | paired rows first in `unpairedMsa`; run with `--resolve_msa_overlaps=false` (UniProt rows go in `pairedMsa` instead, and AF3 pairs them) |
+| Boltz | one CSV per chain; paired rows share a key |
+| Chai-1 | `pairing_key` column |
+| ColabFold | the complex A3M layout, paired rows first |
+| OpenFold3 | `colabfold_paired.a3m` per chain |
+| Protenix | `pairing.a3m` per chain, with headers Protenix reads the species from; Protenix pairs them |
+
+## Formats
+
+The file layouts follow the models' own code: AlphaFold 3
+`folding_input.py`, Boltz `main.py` and `parse/csv.py`, Chai-1
+`aligned_pqt.py`, ColabFold `input.py`, OpenFold3 0.5.1
+`inference_query_format.py`, and Protenix 2.0.0 `runner/msa_search.py`,
+`protenix/data/msa/msa_featurizer.py` and `msa_utils.py`.
+
+## Data sources and attribution
+
+The alignments come from the server you chose, under its terms:
+
+- ColabFold MMseqs2 server, run by the ColabFold team. Cite Mirdita et al.,
+  ColabFold: making protein folding accessible to all, Nature Methods 19,
+  679-682 (2022), and the databases it searches (UniRef30 and the ColabFold
+  environmental database).
+- NVIDIA MSA Search (experimental here), under NVIDIA's API trial terms.
+
+Every adapter that writes files also writes `scigantic-msa-attribution.json`
+next to them, with the server, mode, date and the terms to credit.
+
+## Settings
+
+| variable | meaning |
+| --- | --- |
+| `SCIGANTIC_MSA_CACHE` | cache directory (default `~/.cache/scigantic-msa`) |
+| `SCIGANTIC_MSA_NO_REMOTE=1` | never send a sequence to any server |
+| `SCIGANTIC_MSA_COLABFOLD_URL` | another ColabFold MMseqs2 server |
+| `SCIGANTIC_MSA_CONTACT` | text added to the User-Agent sent to the server, such as an email address |
+| `NVIDIA_API_KEY` | key for `--server nvidia` |
+
+## Development
+
+```
+pip install -e '.[dev]'
+pytest
+```
+
+The tests run offline against small real alignment files in
+`tests/fixtures/real` and a local HTTP server standing in for the ColabFold
+and NVIDIA APIs. `tests/test_predictors.py` loads the output with Boltz's
+and Chai-1's own parsers when interpreters with those packages are given;
+see the file for how.
+
+## License
+
+MIT. The alignments are under the terms of the server and databases they
+came from.

scigantic_msa-0.2.0/README.md

@@ -0,0 +1,202 @@
+# scigantic-msa
+
+Get a multiple sequence alignment (MSA) for a protein sequence once, and
+write the input files for the structure predictor you are about to run:
+AlphaFold 3, Boltz, Chai-1, ColabFold, OpenFold3 or Protenix.
+
+The alignment comes from the ColabFold MMseqs2 server (or NVIDIA's MSA
+Search, if you have a key), or from an A3M file you already have. There is
+no account and no login, and nothing is stored on our side.
+
+## Install
+
+```
+pip install scigantic-msa            # or: uv tool install scigantic-msa
+pip install 'scigantic-msa[chai]'    # adds pyarrow, needed for Chai-1 files
+```
+
+Python 3.10 or newer. The core has no dependencies.
+
+## Privacy
+
+Your sequence may be unpublished, so read this before you run a search.
+
+- `run` and `MSA().get()` send the sequence to a third-party server:
+  api.colabfold.com by default. The public ColabFold server needs no login
+  to read a result, and the job id is a hash of the sequence, so anyone who
+  knows the sequence can download the result. Treat a submission there as
+  publishing the sequence.
+- The Python API refuses to send anything unless you pass `remote=True`.
+  The command line says which server will receive the sequence and asks
+  once; `--yes` skips the question for scripts. Without a terminal and
+  without `--yes`, it stops and sends nothing.
+- `convert` and `MSA().from_a3m()` make no network connection at all.
+- The only network traffic is to the server you chose. The tool never
+  contacts a Scigantic server.
+- The sequence is never written to a log. Results are kept in a local cache
+  (`~/.cache/scigantic-msa`, or `SCIGANTIC_MSA_CACHE`) so the same sequence
+  is not submitted twice; delete the directory to forget them, or pass
+  `--no-cache`.
+- `SCIGANTIC_MSA_NO_REMOTE=1` blocks every search, whatever the code asks.
+
+The public ColabFold server is a shared resource with a rate limit of about
+one new job per minute per IP address. This client backs off, honours
+Retry-After, resumes a job from its id instead of submitting it again, and
+gives up after a bounded wait. To use your own server, pass `--host URL`
+(or `MSA(host=URL)`).
+
+## Command line
+
+```
+scigantic-msa run SEQ_OR_FASTA --model boltz --out job/
+scigantic-msa run chains.fasta --model af3 --out job/ --yes
+scigantic-msa convert my_alignment.a3m --model protenix --out job/
+scigantic-msa version
+```
+
+`--model` is one of `af3`, `boltz`, `chai`, `colabfold`, `openfold3`,
+`protenix`. A FASTA file with several records is one complex, one chain per
+record; `:` inside a sequence also separates chains. `convert` takes one
+A3M (or `.a3m.gz`, or Stockholm `.sto`) per chain, in chain order.
+`--server nvidia` uses NVIDIA's hosted MSA Search and needs
+`NVIDIA_API_KEY`.
+
+After writing the files, the command prints the command to run the model
+on them.
+
+## Python
+
+Every adapter takes one result, or a list of results for the chains of a
+complex. The result carries its sequence; if you also pass the sequence,
+it must match.
+
+AlphaFold 3:
+
+```python
+import json
+from scigantic_msa import MSA
+from scigantic_msa.adapters import AlphaFold3
+result = MSA().get(sequence, remote=True)
+json.dump(AlphaFold3.prepare(result, name="job"), open("job.json", "w"))
+```
+
+Boltz:
+
+```python
+from scigantic_msa import MSA
+from scigantic_msa.adapters import Boltz
+result = MSA().get(sequence, remote=True)
+yaml_text = Boltz.prepare(result, out_dir="boltz/")
+open("job.yaml", "w").write(yaml_text)        # then: boltz predict job.yaml
+```
+
+Chai-1:
+
+```python
+from scigantic_msa import MSA
+from scigantic_msa.adapters import Chai
+result = MSA().get(sequence, remote=True)
+msa_dir = Chai.prepare(result, out_dir="chai_msas/")
+open("job.fasta", "w").write(Chai.fasta(result))   # chai-lab fold --msa-directory chai_msas/ job.fasta out/
+```
+
+Protenix:
+
+```python
+import json
+from scigantic_msa import MSA
+from scigantic_msa.adapters import Protenix
+result = MSA().get(sequence, remote=True)
+json.dump(Protenix.prepare(result, out_dir="protenix_msas/"), open("job.json", "w"))
+```
+
+ColabFold and OpenFold3 work the same way: `ColabFold.prepare(result,
+out_dir=...)` returns the path of the A3M for `colabfold_batch`, and
+`OpenFold3.prepare(result, out_dir=...)` returns the query JSON as a dict.
+
+With an alignment you already have, and no network:
+
+```python
+result = MSA().from_a3m("my_alignment.a3m", sequence=sequence)
+```
+
+## Checks
+
+- An A3M is checked strictly: the first record must be the query (no gaps,
+  no lowercase), only `A-Z`, `a-z` and `-` are allowed, and every row must
+  have as many match columns as the query has residues.
+- Each adapter reads back what it wrote: every file it names exists, is not
+  empty, starts with the chain's sequence, and has the name the model looks
+  for. Chai-1 skips a chain's MSA without an error when the file name is
+  wrong, and Protenix ignores a file in `precomputed_msa_dir` that is not
+  called `pairing.a3m` or `non_pairing.a3m`; here both are errors.
+- `Protenix.check(path_or_jobs)` runs the same checks on any Protenix input
+  JSON, including a missing `*MsaPath`, which would make Protenix start its
+  own MSA search and send the sequence to a server.
+
+## Complexes
+
+Each chain gets its own unpaired MSA. Rows are paired across chains only
+where the rows say the species: an NCBI taxid (from ColabFold's taxonomy
+output, or `TaxID=` / `OX=` in headers) or a UniProt species code.
+Environmental and metagenomic hits have none and stay unpaired. When
+pairing is not possible the tool says why, for example "no species is
+shared by all chains; the chains get unpaired MSAs".
+
+| model | how pairing is passed on |
+| --- | --- |
+| AlphaFold 3 | paired rows first in `unpairedMsa`; run with `--resolve_msa_overlaps=false` (UniProt rows go in `pairedMsa` instead, and AF3 pairs them) |
+| Boltz | one CSV per chain; paired rows share a key |
+| Chai-1 | `pairing_key` column |
+| ColabFold | the complex A3M layout, paired rows first |
+| OpenFold3 | `colabfold_paired.a3m` per chain |
+| Protenix | `pairing.a3m` per chain, with headers Protenix reads the species from; Protenix pairs them |
+
+## Formats
+
+The file layouts follow the models' own code: AlphaFold 3
+`folding_input.py`, Boltz `main.py` and `parse/csv.py`, Chai-1
+`aligned_pqt.py`, ColabFold `input.py`, OpenFold3 0.5.1
+`inference_query_format.py`, and Protenix 2.0.0 `runner/msa_search.py`,
+`protenix/data/msa/msa_featurizer.py` and `msa_utils.py`.
+
+## Data sources and attribution
+
+The alignments come from the server you chose, under its terms:
+
+- ColabFold MMseqs2 server, run by the ColabFold team. Cite Mirdita et al.,
+  ColabFold: making protein folding accessible to all, Nature Methods 19,
+  679-682 (2022), and the databases it searches (UniRef30 and the ColabFold
+  environmental database).
+- NVIDIA MSA Search (experimental here), under NVIDIA's API trial terms.
+
+Every adapter that writes files also writes `scigantic-msa-attribution.json`
+next to them, with the server, mode, date and the terms to credit.
+
+## Settings
+
+| variable | meaning |
+| --- | --- |
+| `SCIGANTIC_MSA_CACHE` | cache directory (default `~/.cache/scigantic-msa`) |
+| `SCIGANTIC_MSA_NO_REMOTE=1` | never send a sequence to any server |
+| `SCIGANTIC_MSA_COLABFOLD_URL` | another ColabFold MMseqs2 server |
+| `SCIGANTIC_MSA_CONTACT` | text added to the User-Agent sent to the server, such as an email address |
+| `NVIDIA_API_KEY` | key for `--server nvidia` |
+
+## Development
+
+```
+pip install -e '.[dev]'
+pytest
+```
+
+The tests run offline against small real alignment files in
+`tests/fixtures/real` and a local HTTP server standing in for the ColabFold
+and NVIDIA APIs. `tests/test_predictors.py` loads the output with Boltz's
+and Chai-1's own parsers when interpreters with those packages are given;
+see the file for how.
+
+## License
+
+MIT. The alignments are under the terms of the server and databases they
+came from.

scigantic_msa-0.2.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scigantic-msa"
+version = "0.2.0"
+description = "Get a protein MSA once from the ColabFold MMseqs2 server, or bring your own A3M, and write the input files for AlphaFold 3, Boltz, Chai-1, ColabFold, OpenFold3 or Protenix."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Scigantic" }]
+keywords = ["msa", "a3m", "protein", "alphafold3", "boltz", "chai", "colabfold", "openfold", "protenix", "structure-prediction"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Environment :: Console",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+# Chai-1 reads aligned parquet files.
+chai = ["pyarrow>=12"]
+dev = ["pytest>=7", "pyarrow>=12", "mypy>=1.10", "ruff>=0.5"]
+
+[project.urls]
+Homepage = "https://github.com/Scigantic/scigantic-msa"
+Repository = "https://github.com/Scigantic/scigantic-msa"
+Issues = "https://github.com/Scigantic/scigantic-msa/issues"
+
+[project.scripts]
+scigantic-msa = "scigantic_msa.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+scigantic_msa = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+  "predictors: loads outputs with the predictors' own parsers (needs them installed)",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "B"]
+ignore = ["E501", "E741", "B904", "B008", "B905"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_unused_ignores = false
+ignore_missing_imports = true

scigantic_msa-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

scigantic_msa-0.2.0/src/scigantic_msa/__init__.py

@@ -0,0 +1,25 @@
+"""scigantic-msa: one command from a protein sequence to the MSA input files
+a structure predictor reads.
+
+    from scigantic_msa import MSA
+    from scigantic_msa.adapters import AlphaFold3, Boltz
+
+    result = MSA().get(sequence, remote=True)   # sends the sequence to api.colabfold.com
+    af3_input = AlphaFold3.prepare(result)      # dict ready for json.dump
+"""
+
+__version__ = "0.2.0"
+
+from .seqkey import InvalidSequence, canonical_sequence, seq_sha256  # noqa: E402
+from .a3m import A3MError, Row, parse_a3m, parse_stockholm  # noqa: E402
+from .alignment import Alignment, SOURCES  # noqa: E402
+from .remote import ColabFoldClient, NvidiaClient, RemoteError  # noqa: E402
+from .tool import MSA, RemoteNotAllowed  # noqa: E402
+
+__all__ = [
+    "__version__",
+    "MSA", "Alignment", "SOURCES", "RemoteNotAllowed", "RemoteError",
+    "seq_sha256", "canonical_sequence", "InvalidSequence",
+    "parse_a3m", "parse_stockholm", "Row", "A3MError",
+    "ColabFoldClient", "NvidiaClient",
+]