rowan-python 3.0.0__py3-none-any.whl → 3.0.1__py3-none-any.whl

rowan/__init__.py

@@ -1,5 +1,22 @@
 # ruff: noqa
 from . import constants
+from stjames import (
+    Constraint,
+    ConstraintType,
+    Correction,
+    Engine,
+    Method,
+    Mode,
+    OptimizationSettings,
+    Settings,
+    SolventSettings,
+    Task,
+)
+from stjames.optimization.freezing_string_method import (
+    FSMInterpolation,
+    FSMOptimizationCoordinates,
+    FSMSettings,
+)
 
 api_key: str | None = None
 project_uuid: str | None = None

rowan/protein.py

@@ -211,7 +211,7 @@ class Protein(BaseModel):
 
         raise RuntimeError(f"Protein preparation timed out after {timeout:.0f}s for {self.uuid}.")
 
-    def validate_protein_forcefield(self) -> None:
+    def validate_protein_forcefield(self, exclude_residue_names: list[str] | None = None) -> None:
         """
         Validate that this protein can be parameterized with the MD forcefield.
 
@@ -219,13 +219,21 @@ class Protein(BaseModel):
         recognized by OpenMM and that there are no clashing atoms. Call this
         before submitting any MD workflow to catch preparation issues early.
 
+        Ligand residues (``LIG``) are always excluded — they are parameterized
+        separately by the MD workflow from the provided SMILES.
+
         If validation fails, try re-preparing with ``remove_invalid_hydrogens=True``:
         ``protein.prepare(remove_invalid_hydrogens=True)``
 
+        :param exclude_residue_names: Additional residue names to skip during validation.
         :raises requests.HTTPError: if validation fails or the API request fails.
         """
+        excluded = list({"LIG"} | {name.upper() for name in (exclude_residue_names or [])})
         with api_client() as client:
-            response = client.post(f"/protein/{self.uuid}/validate_forcefield")
+            response = client.post(
+                f"/protein/{self.uuid}/validate_forcefield",
+                json=excluded,
+            )
             response.raise_for_status()
 
     def download_pdb_file(self, path: Path | str | None = None, name: str | None = None) -> None:

rowan/rowan_rdkit/chem_utils.py

@@ -98,24 +98,24 @@ def _get_rdkit_mol_from_uuid(calculation_uuid: str) -> RdkitMol:
     calc = rowan.retrieve_calculation(calculation_uuid)
     if calc.molecule is None:
         raise ValueError(f"Calculation {calculation_uuid} has no molecules")
-    return Chem.MolFromXYZBlock(calc.molecule.to_xyz())
+    return Chem.MolFromXYZBlock(calc.molecule.to_xyz())  # type: ignore[attr-defined]
 
 
 def _embed_rdkit_mol(rdkm: RdkitMol) -> RdkitMol:
     try:
-        AllChem.SanitizeMol(rdkm)  # type: ignore [attr-defined]
+        AllChem.SanitizeMol(rdkm)  # type: ignore[attr-defined]
     except Exception as e:
         raise ValueError("Molecule could not be generated -- invalid chemistry!") from e
 
-    rdkm = AllChem.AddHs(rdkm)  # type: ignore [attr-defined]
+    rdkm = AllChem.AddHs(rdkm)  # type: ignore[attr-defined]
     try:
-        assert AllChem.EmbedMolecule(rdkm, maxAttempts=200) >= 0  # type: ignore [attr-defined]
+        assert AllChem.EmbedMolecule(rdkm, maxAttempts=200) >= 0  # type: ignore[attr-defined]
     except AssertionError as e:
-        status1 = AllChem.EmbedMolecule(rdkm, maxAttempts=200, useRandomCoords=True)  # type: ignore [attr-defined]
+        status1 = AllChem.EmbedMolecule(rdkm, maxAttempts=200, useRandomCoords=True)  # type: ignore[attr-defined]
         if status1 < 0:
             raise ValueError("Cannot embed molecule!") from e
     try:
-        assert AllChem.MMFFOptimizeMolecule(rdkm, maxIters=200) >= 0  # type: ignore [attr-defined]
+        assert AllChem.MMFFOptimizeMolecule(rdkm, maxIters=200) >= 0  # type: ignore[attr-defined, call-arg]
     except AssertionError:
         pass
 
@@ -478,9 +478,9 @@ async def _single_energy(
     get_api_key()
     method = stjames.Method(method)
 
-    if mol.GetNumConformers() == 0:
+    if mol.GetNumConformers() == 0:  # type: ignore[call-arg]
         mol = _embed_rdkit_mol(mol)
-        if mol.GetNumConformers() == 0:
+        if mol.GetNumConformers() == 0:  # type: ignore[call-arg]
             raise NoConformersError("This molecule has no conformers")
 
     if method not in FAST_METHODS:
@@ -490,7 +490,7 @@ async def _single_energy(
 
     workflow_uuids = []
     for conformer in mol.GetConformers():
-        cid = conformer.GetId()
+        cid = conformer.GetId()  # type: ignore[call-arg]
         stjames_mol = _rdkit_to_stjames(mol, cid)
         post = rowan.submit_workflow(
             name=name,
@@ -625,9 +625,9 @@ async def _single_optimize(
     get_api_key()
     method = stjames.Method(method)
 
-    if mol.GetNumConformers() == 0:
+    if mol.GetNumConformers() == 0:  # type: ignore[call-arg]
         mol = _embed_rdkit_mol(mol)
-        if mol.GetNumConformers() == 0:
+        if mol.GetNumConformers() == 0:  # type: ignore[call-arg]
             raise NoConformersError("This molecule has no conformers")
 
     if method not in FAST_METHODS:
@@ -639,7 +639,7 @@ async def _single_optimize(
 
     workflow_uuids = []
     for conformer in mol.GetConformers():
-        cid = conformer.GetId()
+        cid = conformer.GetId()  # type: ignore[call-arg]
         stjames_mol = _rdkit_to_stjames(mol, cid)
 
         post = rowan.submit_workflow(
@@ -680,7 +680,7 @@ async def _single_optimize(
                 energies.append(calc.energy)
 
     for i, conformer in enumerate(optimized_mol.GetConformers()):
-        conformer.SetPositions(np.array(optimized_positions[i]))
+        conformer.SetPositions(np.array(optimized_positions[i]))  # type: ignore[attr-defined]
 
     return {
         "molecule": mol,
@@ -799,9 +799,9 @@ async def _single_conformers(
     get_api_key()
     method = stjames.Method(method)
 
-    if mol.GetNumConformers() == 0:
+    if mol.GetNumConformers() == 0:  # type: ignore[call-arg]
         mol = _embed_rdkit_mol(mol)
-        if mol.GetNumConformers() == 0:
+        if mol.GetNumConformers() == 0:  # type: ignore[call-arg]
             raise NoConformersError("This molecule has no conformers")
 
     if method not in FAST_METHODS:
@@ -861,14 +861,14 @@ async def _single_conformers(
     lowest_n_uuids = [item[1][0] for item in sorted_data[:num_conformers]]
     lowest_energies = [item[0] for item in sorted_data[:num_conformers]]
 
-    AllChem.EmbedMultipleConfs(mol, numConfs=num_conformers)  # type: ignore [attr-defined]
+    AllChem.EmbedMultipleConfs(mol, numConfs=num_conformers)  # type: ignore[attr-defined]
 
     for i, conformer in enumerate(mol.GetConformers()):
         calc = rowan.retrieve_calculation(lowest_n_uuids[i])
         if calc.molecule is None:
             raise ValueError(f"Calculation {lowest_n_uuids[i]} has no molecules")
         pos = [atom.position for atom in calc.molecule.atoms]
-        conformer.SetPositions(np.array(pos))
+        conformer.SetPositions(np.array(pos))  # type: ignore[attr-defined]
 
     return {
         "molecule": mol,
@@ -964,9 +964,9 @@ async def _single_charges(
     get_api_key()
     method = stjames.Method(method)
 
-    if mol.GetNumConformers() == 0:
+    if mol.GetNumConformers() == 0:  # type: ignore[call-arg]
         mol = _embed_rdkit_mol(mol)
-        if mol.GetNumConformers() == 0:
+        if mol.GetNumConformers() == 0:  # type: ignore[call-arg]
             raise NoConformersError("This molecule has no conformers")
 
     if method not in FAST_METHODS:
@@ -976,7 +976,7 @@ async def _single_charges(
 
     workflow_uuids = []
     for conformer in mol.GetConformers():
-        cid = conformer.GetId()
+        cid = conformer.GetId()  # type: ignore[call-arg]
 
         post = rowan.submit_workflow(
             name=name,

rowan/types.py

@@ -9,7 +9,7 @@ from .molecule import Molecule as RowanMolecule
 
 RdkitMol: TypeAlias = Chem.rdchem.Mol | Chem.rdchem.RWMol
 StJamesMolecule: TypeAlias = stjames.Molecule
-MoleculeInput: TypeAlias = dict[str, Any] | RowanMolecule | StJamesMolecule | RdkitMol
+MoleculeInput: TypeAlias = dict[str, Any] | RowanMolecule | StJamesMolecule | RdkitMol | str
 SolventInput: TypeAlias = stjames.Solvent | str | None
 SMILES: TypeAlias = str
 UUID: TypeAlias = str

rowan/user.py

@@ -1,3 +1,7 @@
+import hashlib
+import hmac
+import time
+
 from pydantic import BaseModel
 
 from .utils import api_client
@@ -135,3 +139,64 @@ def whoami() -> User:
         response.raise_for_status()
 
     return User(**response.json())
+
+
+def get_webhook_secret() -> str | None:
+    """Get current webhook secret, or None if not set."""
+    with api_client() as client:
+        response = client.get("/user/me/webhook_secret")
+        response.raise_for_status()
+    return response.json().get("webhook_secret")
+
+
+def create_webhook_secret() -> str:
+    """Create a webhook secret if one doesn't exist, return it."""
+    with api_client() as client:
+        response = client.post("/user/me/webhook_secret")
+        response.raise_for_status()
+    return response.json()["webhook_secret"]
+
+
+def rotate_webhook_secret() -> str:
+    """Generate a new webhook secret, invalidating the old one."""
+    with api_client() as client:
+        response = client.post("/user/me/webhook_secret/rotate")
+        response.raise_for_status()
+    return response.json()["webhook_secret"]
+
+
+def verify_webhook_secret(
+    raw_body: bytes,
+    signature_header: str,
+    secret: str,
+    max_age_seconds: int = 300,
+) -> bool:
+    """Verify an incoming webhook request from Rowan.
+
+    :param raw_body: The raw (unparsed) request body bytes.
+    :param signature_header: Value of the X-Rowan-Signature header.
+    :param secret: Your webhook secret (from :func:`create_webhook_secret` or
+        :func:`rotate_webhook_secret`).
+    :param max_age_seconds: Reject requests older than this many seconds (default 5 min).
+    :returns: True if the signature is valid and the request is fresh.
+    """
+    try:
+        parts = dict(part.split("=", 1) for part in signature_header.split(","))
+    except ValueError:
+        return False
+    timestamp = parts.get("t", "")
+    received_digest = parts.get("sha256", "")
+
+    if not timestamp or not received_digest:
+        return False
+
+    if abs(time.time() - int(timestamp)) > max_age_seconds:
+        return False
+
+    expected_digest = hmac.new(
+        secret.encode(),
+        f"{timestamp}.".encode() + raw_body,
+        hashlib.sha256,
+    ).hexdigest()
+
+    return hmac.compare_digest(expected_digest, received_digest)

rowan/workflows/admet.py

@@ -31,6 +31,7 @@ def submit_admet_workflow(
     folder_uuid: str | None = None,
     folder: Folder | None = None,
     max_credits: int | None = None,
+    webhook_url: str | None = None,
 ) -> Workflow:
     """
     Submits an ADMET workflow to predict drug-likeness properties.
@@ -43,6 +44,7 @@ def submit_admet_workflow(
     :param folder_uuid: UUID of the folder to store the workflow in.
     :param folder: Folder object to store the workflow in.
     :param max_credits: Maximum number of credits to use for the workflow.
+    :param webhook_url: URL that Rowan will POST to when the workflow completes.
     :returns: Workflow object representing the submitted workflow.
     :raises ValueError: If the molecule has no SMILES associated with it.
     :raises requests.HTTPError: if the request to the API fails.
@@ -55,12 +57,13 @@ def submit_admet_workflow(
     workflow = stjames.ADMETWorkflow(initial_smiles=initial_smiles)
 
     data = {
-        "name": name,
-        "folder_uuid": folder_uuid,
         "workflow_type": "admet",
         "workflow_data": workflow.model_dump(mode="json"),
         "initial_smiles": initial_smiles,
+        "name": name,
+        "folder_uuid": folder_uuid,
         "max_credits": max_credits,
+        "webhook_url": webhook_url,
     }
 
     with api_client() as client:

rowan/workflows/analogue_docking.py

@@ -166,6 +166,7 @@ def submit_analogue_docking_workflow(
     folder_uuid: str | None = None,
     folder: Folder | None = None,
     max_credits: int | None = None,
+    webhook_url: str | None = None,
 ) -> Workflow:
     """
     Submits an analogue-docking workflow to the API.
@@ -180,6 +181,7 @@ def submit_analogue_docking_workflow(
     :param folder_uuid: UUID of the folder to place the workflow in.
     :param folder: Folder object to store the workflow in.
     :param max_credits: Maximum number of credits to use for the workflow.
+    :param webhook_url: URL that Rowan will POST to when the workflow completes.
     :returns: Workflow object representing the submitted analogue-docking workflow.
     :raises requests.HTTPError: if the request to the API fails.
     """
@@ -206,12 +208,13 @@ def submit_analogue_docking_workflow(
     )
 
     data = {
-        "name": name,
-        "folder_uuid": folder_uuid,
         "initial_molecule": initial_molecule,
         "workflow_type": "analogue_docking",
         "workflow_data": workflow.model_dump(serialize_as_any=True, mode="json"),
+        "name": name,
+        "folder_uuid": folder_uuid,
         "max_credits": max_credits,
+        "webhook_url": webhook_url,
     }
 
     with api_client() as client:

rowan/workflows/base.py

@@ -10,7 +10,7 @@ from pathlib import Path
 from typing import Any, Callable, ClassVar, Self
 
 import stjames
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
 from rdkit import Chem
 
 from ..folder import Folder
@@ -71,7 +71,7 @@ class WorkflowResult:
     workflow_data: dict[str, Any]
     workflow_type: str
     workflow_uuid: str
-    eager: bool = field(default=True, repr=False)
+    complete: bool = field(default=True, repr=False)
     _workflow: Any = field(default=None, init=False)
     _cache: dict[str, Any] = field(default_factory=dict, init=False)
 
@@ -83,8 +83,11 @@ class WorkflowResult:
     def __post_init__(self) -> None:
         """Parse workflow data into stjames object for typed access."""
         if self._stjames_class is not None:
-            obj = self._stjames_class.model_validate(self.workflow_data)  # type: ignore[attr-defined]
-            object.__setattr__(self, "_workflow", obj)
+            try:
+                obj = self._stjames_class.model_validate(self.workflow_data)  # type: ignore[attr-defined]
+                object.__setattr__(self, "_workflow", obj)
+            except ValidationError:
+                pass  # incomplete or invalid data; _workflow stays None
 
     @property
     def data(self) -> dict[str, Any]:
@@ -115,7 +118,7 @@ def register_result(workflow_type: str) -> Callable[[type[WorkflowResult]], type
 
 
 def create_result(
-    workflow_data: dict[str, Any], workflow_type: str, workflow_uuid: str, eager: bool = True
+    workflow_data: dict[str, Any], workflow_type: str, workflow_uuid: str, complete: bool = True
 ) -> WorkflowResult:
     """
     Factory function to create the appropriate result type for a workflow.
@@ -123,7 +126,7 @@ def create_result(
     :param workflow_data: Raw data dict from the workflow.
     :param workflow_type: Workflow type string.
     :param workflow_uuid: UUID of the parent workflow.
-    :param eager: If True (default), eagerly fetch related data (e.g. calculations)
+    :param complete: If True (default), eagerly fetch related data (e.g. calculations)
         in ``__post_init__``. Set to False when polling partial results with
         ``result(wait=False)`` to avoid unnecessary API calls.
     :returns: Typed WorkflowResult subclass, or base WorkflowResult if unknown.
@@ -133,7 +136,7 @@ def create_result(
         workflow_data=workflow_data,
         workflow_type=workflow_type,
         workflow_uuid=workflow_uuid,
-        eager=eager,
+        complete=complete,
     )
 
 
@@ -158,6 +161,7 @@ class Workflow(BaseModel):
     :param data: Data of the workflow.
     :param email_when_complete: Whether to send an email when the workflow completes.
     :param max_credits: Maximum number of credits to use for the workflow.
+    :param webhook_url: URL that Rowan will POST to when the workflow completes.
     :param elapsed: Elapsed time of the workflow.
     :param credits_charged: Number of credits charged for the workflow.
     :param logfile: Workflow logfile.
@@ -323,8 +327,8 @@ Workflow:  {self.name}
             raise WorkflowError(
                 f"Workflow '{self.name}' has no results yet (status={status}, uuid={self.uuid})"
             )
-        eager = self.status == stjames.Status.COMPLETED_OK
-        return create_result(self.data, self.workflow_type, self.uuid, eager=eager)
+        complete = self.status == stjames.Status.COMPLETED_OK
+        return create_result(self.data, self.workflow_type, self.uuid, complete=complete)
 
     def stream_result(self, poll_interval: int = 5) -> Iterator["WorkflowResult"]:
         """
@@ -525,6 +529,8 @@ def molecule_to_dict(mol: MoleculeInput) -> dict[str, Any]:
     :returns: Dict representation suitable for API submission.
     """
     match mol:
+        case str():
+            return RowanMolecule.from_smiles(mol).to_stjames().model_dump(mode="json")
         case RowanMolecule():
             return mol.to_stjames().model_dump(mode="json")
         case stjames.Molecule():
@@ -545,6 +551,7 @@ def submit_workflow(
     name: str | None = None,
     folder_uuid: str | Folder | None = None,
     max_credits: int | None = None,
+    webhook_url: str | None = None,
 ) -> Workflow:
     """
     Submits a workflow to the API.
@@ -556,6 +563,7 @@ def submit_workflow(
     :param name: Name for the workflow.
     :param folder_uuid: UUID of the folder to store the workflow in, or a Folder object.
     :param max_credits: Maximum number of credits to use for the workflow.
+    :param webhook_url: URL that Rowan will POST to when the workflow completes.
     :returns: Workflow object representing the submitted workflow.
     :raises ValueError: If neither `initial_smiles` nor a valid `initial_molecule` is provided.
     :raises HTTPError: If the API request fails.
@@ -573,6 +581,7 @@ def submit_workflow(
         "workflow_type": workflow_type,
         "workflow_data": workflow_data,
         "max_credits": max_credits,
+        "webhook_url": webhook_url,
     }
 
     if initial_smiles is not None:
@@ -709,6 +718,7 @@ def batch_submit_workflow(
     names: list[str] | None = None,
     folder_uuid: str | Folder | None = None,
     max_credits: int | None = None,
+    webhook_url: str | None = None,
 ) -> list[Workflow]:
     """
     Submits a batch of workflows to the API.
@@ -723,6 +733,7 @@ def batch_submit_workflow(
     :param names: Names for the submitted workflows.
     :param folder_uuid: UUID of the folder to store the workflows in.
     :param max_credits: Maximum number of credits to use per workflow.
+    :param webhook_url: URL to call when each workflow completes.
     :returns: List of Workflow objects representing the submitted workflows.
     """
     if names is not None:
@@ -745,6 +756,7 @@ def batch_submit_workflow(
                     name=name,
                     folder_uuid=folder_uuid,
                     max_credits=max_credits,
+                    webhook_url=webhook_url,
                 )
             )
     elif initial_molecules is not None:
@@ -758,6 +770,7 @@ def batch_submit_workflow(
                     name=name,
                     folder_uuid=folder_uuid,
                     max_credits=max_credits,
+                    webhook_url=webhook_url,
                 )
             )
     else: