openprotein-python 0.8.2__1-py3-none-any.whl

openprotein/__init__.py

@@ -0,0 +1,164 @@
+"""
+OpenProtein Python client.
+
+A pythonic interface for interacting with our cutting-edge protein engineering platform.
+
+isort:skip_file
+"""
+
+from typing import TYPE_CHECKING
+import warnings
+
+from openprotein._version import __version__
+from openprotein.data import DataAPI
+from openprotein.errors import DeprecationError
+from openprotein.jobs import JobsAPI
+from openprotein.align import AlignAPI
+from openprotein.prompt import PromptAPI
+from openprotein.embeddings import EmbeddingsAPI
+from openprotein.fold import FoldAPI
+from openprotein.models import ModelsAPI
+from openprotein.svd import SVDAPI
+from openprotein.umap import UMAPAPI
+from openprotein.predictor import PredictorAPI
+from openprotein.design import DesignAPI
+from openprotein.jobs import Future
+from openprotein.base import APISession
+
+
+class OpenProtein(APISession):
+    """
+    The base class for accessing OpenProtein API functionality.
+    """
+
+    _data = None
+    _jobs = None
+    _align = None
+    _prompt = None
+    _embeddings = None
+    _svd = None
+    _umap = None
+    _fold = None
+    _predictor = None
+    _design = None
+    _models = None
+
+    def wait(self, future: Future, *args, **kwargs):
+        return future.wait(*args, **kwargs)
+
+    wait_until_done = wait
+
+    def load_job(self, job_id):
+        return self.jobs.get(job_id=job_id)
+
+    @property
+    def data(self) -> DataAPI:
+        """
+        The data submodule gives access to functionality for uploading and accessing user data.
+        """
+        if self._data is None:
+            self._data = DataAPI(self)
+        return self._data
+
+    @property
+    def jobs(self) -> JobsAPI:
+        """
+        The jobs submodule gives access to functionality for listing jobs and checking their status.
+        """
+        if self._jobs is None:
+            self._jobs = JobsAPI(self)
+        return self._jobs
+
+    @property
+    def align(self) -> AlignAPI:
+        """
+        The Align submodule gives access to the sequence alignment capabilities by building MSAs and prompts that can be used with PoET.
+        """
+        if self._align is None:
+            self._align = AlignAPI(self)
+        return self._align
+
+    @property
+    def prompt(self) -> PromptAPI:
+        """
+        The Align submodule gives access to the sequence alignment capabilities by building MSAs and prompts that can be used with PoET.
+        """
+        if self._prompt is None:
+            self._prompt = PromptAPI(self)
+        return self._prompt
+
+    @property
+    def embedding(self) -> EmbeddingsAPI:
+        """
+        The embedding submodule gives access to protein embedding models and their inference endpoints.
+        """
+        if self._embeddings is None:
+            self._embeddings = EmbeddingsAPI(self)
+        return self._embeddings
+
+    embeddings = embedding
+
+    @property
+    def svd(self) -> SVDAPI:
+        """
+        The embedding submodule gives access to protein embedding models and their inference endpoints.
+        """
+        if self._svd is None:
+            self._svd = SVDAPI(
+                session=self,
+            )
+        return self._svd
+
+    @property
+    def umap(self) -> UMAPAPI:
+        """
+        The embedding submodule gives access to protein embedding models and their inference endpoints.
+        """
+        if self._umap is None:
+            self._umap = UMAPAPI(
+                session=self,
+            )
+        return self._umap
+
+    @property
+    def predictor(self) -> PredictorAPI:
+        """
+        The predictor submodule gives access to training and predicting with predictors built on top of embeddings.
+        """
+        if self._predictor is None:
+            self._predictor = PredictorAPI(
+                session=self,
+            )
+        return self._predictor
+
+    @property
+    def design(self) -> DesignAPI:
+        """
+        The designer submodule gives access to functionality for designing new sequences using models from predictor train.
+        """
+        if self._design is None:
+            self._design = DesignAPI(
+                session=self,
+            )
+        return self._design
+
+    @property
+    def fold(self) -> FoldAPI:
+        """
+        The fold submodule gives access to functionality for folding sequences and returning PDBs.
+        """
+        if self._fold is None:
+            self._fold = FoldAPI(self)
+        return self._fold
+
+    @property
+    def models(self) -> "ModelsAPI":
+        """
+        The models submodule provides a unified entry point to all protein models.
+        """
+        if self._models is None:
+            self._models = ModelsAPI(self)
+        return self._models
+
+
+connect = OpenProtein

openprotein/_version.py

@@ -0,0 +1,48 @@
+"""Compute the version number and store it in the `__version__` variable.
+
+Based on <https://github.com/maresb/hatch-vcs-footgun-example>.
+"""
+
+
+def _get_hatch_version():
+    """Compute the most up-to-date version number in a development environment.
+
+    Returns `None` if Hatchling is not installed, e.g. in a production environment.
+
+    For more details, see <https://github.com/maresb/hatch-vcs-footgun-example/>.
+    """
+    import os
+
+    try:
+        from hatchling.metadata.core import ProjectMetadata
+        from hatchling.plugin.manager import PluginManager
+        from hatchling.utils.fs import locate_file
+    except ImportError:
+        # Hatchling is not installed, so probably we are not in
+        # a development environment.
+        return None
+
+    pyproject_toml = locate_file(__file__, "pyproject.toml")
+    if pyproject_toml is None:
+        raise RuntimeError("pyproject.toml not found although hatchling is installed")
+    root = os.path.dirname(pyproject_toml)
+    metadata = ProjectMetadata(root=root, plugin_manager=PluginManager())
+    # Version can be either statically set in pyproject.toml or computed dynamically:
+    return metadata.core.version or metadata.hatch.version.cached
+
+
+def _get_importlib_metadata_version():
+    """Compute the version number using importlib.metadata.
+
+    This is the official Pythonic way to get the version number of an installed
+    package. However, it is only updated when a package is installed. Thus, if a
+    package is installed in editable mode, and a different version is checked out,
+    then the version number will not be updated.
+    """
+    from importlib.metadata import version
+
+    __version__ = version(__package__)  # type: ignore
+    return __version__
+
+
+__version__ = _get_hatch_version() or _get_importlib_metadata_version()

openprotein/align/__init__.py

@@ -0,0 +1,8 @@
+"""
+Align module for creating and searching alignments on OpenProtein.
+
+isort:skip_file
+"""
+
+from .msa import MSAFuture
+from .align import AlignAPI

openprotein/align/align.py

@@ -0,0 +1,395 @@
+"""Align API interface for creating alignments and MSAs (multiple sequence alignments) which can be used for other protein tasks."""
+
+from collections.abc import Sequence
+from io import BytesIO
+from typing import BinaryIO, Iterator
+
+from openprotein.base import APISession
+from openprotein.errors import DeprecationError
+from openprotein.jobs import Job
+from openprotein.protein import Protein
+
+from . import api
+from .msa import MSAFuture
+from .schemas import AbNumberScheme, AlignType
+
+
+class AlignAPI:
+    """Align API interface for creating alignments and MSAs (multiple sequence alignments) which can be used for other protein tasks."""
+
+    def __init__(self, session: APISession):
+        self.session = session
+
+    def mafft(
+        self,
+        sequences: Sequence[bytes | str],
+        names: Sequence[str] | None = None,
+        auto: bool = True,
+        ep: float | None = None,
+        op: float | None = None,
+    ) -> MSAFuture:
+        """
+        Align sequences using the `mafft` algorithm.
+
+        Set `auto` to True to automatically attempt the best parameters. Leave a parameter as None to use system defaults.
+
+        Parameters
+        ----------
+        sequences : Sequence[bytes or str]
+            Sequences to align.
+        names : Sequence[str], optional
+            Optional list of sequence names, must be the same length as sequences if provided.
+        auto : bool, default=True
+            Set to True to automatically set algorithm parameters.
+        ep : float, optional
+            MAFFT "ep" parameter. Sets the offset value for the scoring matrix; lower values make gap opening more difficult. If None, uses system default.
+        op : float, optional
+            MAFFT "op" parameter. Sets the gap opening penalty; higher values increase the cost of opening gaps. If None, uses system default.
+
+        Returns
+        -------
+        MSAFuture
+            Future object awaiting the contents of the MSA upload.
+
+        Raises
+        ------
+        Exception
+            If names and sequences are not the same length.
+        """
+        if names is not None and len(names) != len(sequences):
+            raise Exception(
+                f"Names and sequences must be same length, but were {len(names)} and {len(sequences)}"
+            )
+        lines = []
+        if names is None:
+            # as CSV
+            lines = [s.encode() if isinstance(s, str) else s for s in sequences]
+        else:
+            # as fasta
+            for name, sequence in zip(names, sequences):
+                if isinstance(name, str):
+                    name = name.encode()
+                if isinstance(sequence, str):
+                    sequence = sequence.encode()
+                lines.append(b">" + name)
+                lines.append(sequence)
+        content = b"\n".join(lines)
+        stream = BytesIO(content)
+        return self.mafft_file(stream, auto=auto, ep=ep, op=op)
+
+    def mafft_file(self, file, auto=True, ep=None, op=None) -> MSAFuture:
+        """
+        Align sequences using the `mafft` algorithm. Sequences can be provided as FASTA or CSV formats.
+        If CSV, the file must be headerless with either a single sequence column or name, sequence columns.
+
+        Set `auto` to True to automatically attempt the best parameters. Leave a parameter as None to use system defaults.
+
+        Parameters
+        ----------
+        file : file-like object
+            Sequences to align in FASTA or CSV format.
+        auto : bool, default=True
+            Set to True to automatically set algorithm parameters.
+        ep : float, optional
+            MAFFT "ep" parameter. Sets the offset value for the scoring matrix; lower values make gap opening more difficult. If None, uses system default.
+        op : float, optional
+            MAFFT "op" parameter. Sets the gap opening penalty; higher values increase the cost of opening gaps. If None, uses system default.
+
+        Returns
+        -------
+        MSAFuture
+            Future object awaiting the contents of the MSA upload.
+        """
+        job = api.mafft_post(self.session, file, auto=auto, ep=ep, op=op)
+        return MSAFuture.create(session=self.session, job=job)
+
+    def clustalo(
+        self,
+        sequences: Sequence[bytes | str],
+        names: Sequence[str] | None = None,
+        clustersize: int | None = None,
+        iterations: int | None = None,
+    ) -> MSAFuture:
+        """
+        Align sequences using the `clustal omega` algorithm.
+
+        Sequences can be provided as FASTA or CSV formats. If CSV, the file must be headerless with either a single sequence column or name, sequence columns.
+
+        Parameters
+        ----------
+        sequences : Sequence[bytes or str]
+            Sequences to align.
+        names : Sequence[str], optional
+            Optional list of sequence names, must be the same length as sequences if provided.
+        clustersize : int, optional
+            Maximum number of sequences per cluster during guide tree generation. If None, uses the default value.
+        iterations : int, optional
+            Number of refinement iterations performed during alignment. If None, uses the default value.
+
+        Returns
+        -------
+        MSAFuture
+            Future object awaiting the contents of the MSA upload.
+
+        Raises
+        ------
+        Exception
+            If names and sequences are not the same length.
+        """
+        if names is not None and len(names) != len(sequences):
+            raise Exception(
+                f"Names and sequences must be same length, but were {len(names)} and {len(sequences)}"
+            )
+        lines = []
+        if names is None:
+            # as CSV
+            lines = [s.encode() if isinstance(s, str) else s for s in sequences]
+        else:
+            # as fasta
+            for name, sequence in zip(names, sequences):
+                if isinstance(name, str):
+                    name = name.encode()
+                if isinstance(sequence, str):
+                    sequence = sequence.encode()
+                lines.append(b">" + name)
+                lines.append(sequence)
+        content = b"\n".join(lines)
+        stream = BytesIO(content)
+        return self.clustalo_file(
+            stream, clustersize=clustersize, iterations=iterations
+        )
+
+    def clustalo_file(self, file, clustersize=None, iterations=None) -> MSAFuture:
+        """
+        Align sequences using the `clustal omega` algorithm.
+
+        Sequences can be provided as FASTA or CSV formats. If CSV, the file must be headerless with either a single sequence column or name, sequence columns.
+
+        Parameters
+        ----------
+        file : file-like object
+            Sequences to align in FASTA or CSV format.
+        clustersize : int, optional
+            Maximum number of sequences per cluster during guide tree generation. If None, uses the default value.
+        iterations : int, optional
+            Number of refinement iterations performed during alignment. If None, uses the default value.
+
+        Returns
+        -------
+        MSAFuture
+            Future object awaiting the contents of the MSA upload.
+        """
+        job = api.clustalo_post(
+            self.session, file, clustersize=clustersize, iterations=iterations
+        )
+        return MSAFuture.create(session=self.session, job=job)
+
+    def abnumber(
+        self,
+        sequences: Sequence[bytes | str],
+        names: Sequence[str] | None = None,
+        scheme: AbNumberScheme = AbNumberScheme.CHOTHIA,
+    ) -> MSAFuture:
+        """
+        Align antibody sequences using `AbNumber`.
+
+        Sequences can be provided as FASTA or CSV formats. If CSV, the file must be headerless with either a single sequence column or name, sequence columns.
+
+        The antibody numbering scheme can be specified.
+
+        Parameters
+        ----------
+        sequences : Sequence[bytes or str]
+            Sequences to align.
+        names : Sequence[str], optional
+            Optional list of sequence names, must be the same length as sequences if provided.
+        scheme : AbNumberScheme, default=AbNumberScheme.CHOTHIA
+            Antibody numbering scheme.
+
+        Returns
+        -------
+        MSAFuture
+            Future object awaiting the contents of the MSA upload.
+
+        Raises
+        ------
+        Exception
+            If names and sequences are not the same length.
+        """
+        if names is not None and len(names) != len(sequences):
+            raise Exception(
+                f"Names and sequences must be same length, but were {len(names)} and {len(sequences)}"
+            )
+        lines = []
+        if names is None:
+            # as CSV
+            lines = [s.encode() if isinstance(s, str) else s for s in sequences]
+        else:
+            # as fasta
+            for name, sequence in zip(names, sequences):
+                if isinstance(name, str):
+                    name = name.encode()
+                if isinstance(sequence, str):
+                    sequence = sequence.encode()
+                lines.append(b">" + name)
+                lines.append(sequence)
+        content = b"\n".join(lines)
+        stream = BytesIO(content)
+        return self.abnumber_file(stream, scheme=scheme)
+
+    def abnumber_file(
+        self, file, scheme: AbNumberScheme = AbNumberScheme.CHOTHIA
+    ) -> MSAFuture:
+        """
+        Align antibody sequences using `AbNumber`.
+
+        Sequences can be provided as FASTA or CSV formats. If CSV, the file must be headerless with either a single sequence column or name, sequence columns.
+
+        The antibody numbering scheme can be specified.
+
+        Parameters
+        ----------
+        file : file-like object
+            Sequences to align in FASTA or CSV format.
+        scheme : AbNumberScheme, default=AbNumberScheme.CHOTHIA
+            Antibody numbering scheme.
+
+        Returns
+        -------
+        MSAFuture
+            Future object awaiting the contents of the MSA upload.
+        """
+        job = api.abnumber_post(self.session, file, scheme=scheme)
+        return MSAFuture.create(session=self.session, job=job)
+
+    def upload_msa(self, msa_file: BinaryIO) -> MSAFuture:
+        """
+        Upload an MSA from a file.
+
+        Parameters
+        ----------
+        msa_file : str
+            Path to a ready-made MSA file.
+
+        Returns
+        -------
+        MSAFuture
+            Future object awaiting the contents of the MSA upload.
+
+        Raises
+        ------
+        APIError
+            If there is an issue with the API request.
+        """
+        return MSAFuture.create(
+            session=self.session, job=api.msa_post(self.session, msa_file=msa_file)
+        )
+
+    def create_msa(self, seed: bytes) -> MSAFuture:
+        """
+        Construct an MSA via homology search with the seed sequence.
+
+        Parameters
+        ----------
+        seed : bytes
+            Seed sequence for the MSA construction.
+
+        Returns
+        -------
+        MSAFuture
+            Future object awaiting the contents of the MSA upload.
+
+        Raises
+        ------
+        APIError
+            If there is an issue with the API request.
+        """
+        return MSAFuture.create(
+            session=self.session, job=api.msa_post(self.session, seed=seed)
+        )
+
+    def upload_prompt(self, prompt_file: BinaryIO):
+        """
+        Directly upload a prompt.
+
+        This method is deprecated. Use `create_prompt` on the `prompt` module instead.
+
+        Parameters
+        ----------
+        prompt_file : BinaryIO
+            Binary I/O object representing the prompt file.
+
+        Returns
+        -------
+        PromptJob
+            An object representing the status and results of the prompt job.
+
+        Raises
+        ------
+        DeprecationError
+            This method is no longer supported.
+        """
+        raise DeprecationError(
+            "This method is no longer supported! Use `create_prompt` on the `prompt` module instead."
+        )
+
+    def get_prompt(
+        self, job: Job, prompt_index: int | None = None
+    ) -> Iterator[list[str]]:
+        """
+        Get prompts for a given job.
+
+        This method is deprecated. Use `get_prompt` on the `prompt` module instead.
+
+        Parameters
+        ----------
+        job : Job
+            The job for which to retrieve data.
+        prompt_index : int, optional
+            The replicate number for the prompt (input_type=-PROMPT only).
+
+        Returns
+        -------
+        Iterator[list[str]]
+            An iterator over rows of the prompt data.
+
+        Raises
+        ------
+        DeprecationError
+            This method is no longer supported.
+        """
+        raise DeprecationError(
+            "This method is no longer supported! Use `get_prompt` on the `prompt` module instead."
+        )
+
+    def get_seed(self, job_id: str) -> str:
+        """
+        Get seed sequence for a given MSA job.
+
+        Parameters
+        ----------
+        job : Job
+            The job for which to retrieve data.
+
+        Returns
+        -------
+        str
+            Seed sequence that was used to generate the MSA.
+        """
+        return api.get_seed(session=self.session, job_id=job_id)
+
+    def get_msa(self, job_id: str) -> Iterator[tuple[str, str]]:
+        """
+        Get generated MSA for a given job.
+
+        Parameters
+        ----------
+        job : Job
+            The job for which to retrieve data.
+
+        Returns
+        -------
+        Iterator[tuple[str, str]]
+            An iterator over names and sequences of the MSA data.
+        """
+        return api.get_msa(session=self.session, job_id=job_id)