pkasso 0.5.0__py3-none-any.whl

pkasso/__init__.py

@@ -0,0 +1,15 @@
+"""Public package exports for pKasso."""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["batch_protonate", "protonate", "scan_pH"]
+
+
+def __getattr__(name: str) -> Any:
+    if name in __all__:
+        from pkasso import py_interface
+
+        return getattr(py_interface, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

pkasso/api/__init__.py

@@ -0,0 +1 @@
+"""pKasso web application."""

pkasso/api/app.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import textwrap
+
+WEB_DEPENDENCIES = {
+    "fastapi": "fastapi",
+    "jinja2": "jinja2",
+    "multipart": "python-multipart",
+    "itsdangerous": "itsdangerous",
+    "uvicorn": "uvicorn",
+}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run the pKasso daisyUI/HTMX GUI.")
+    parser.add_argument("--host", default="0.0.0.0")
+    parser.add_argument("--port", default=8001, type=int)
+    parser.add_argument("--reload", action="store_true", help="Reload when local code changes.")
+    args = parser.parse_args()
+
+    missing = [
+        package_name for module_name, package_name in WEB_DEPENDENCIES.items() if importlib.util.find_spec(module_name) is None
+    ]
+    if missing:
+        parser.exit(
+            1,
+            "The pKasso web server dependencies are not installed.\n"
+            f"Missing: {', '.join(sorted(set(missing)))}.\n"
+            "Install them with: pip install 'pkasso[webserver]'\n",
+        )
+
+    import uvicorn
+
+    url = f"http://{args.host}:{args.port}"
+    print(
+        textwrap.dedent(f"""
+    pKasso GUI is running at {url}
+    Press Ctrl+C to stop.
+    """).strip()
+    )
+    uvicorn.run("pkasso.api.web:app", host=args.host, port=args.port, reload=args.reload)
+
+
+if __name__ == "__main__":
+    main()

pkasso/api/chemistry.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import copy
+import io
+import numpy as np
+import os
+from typing import Any
+from rdkit.Chem import AllChem
+from rdkit import Chem
+
+from .config import CUTOFF_STATES
+from .state import AppState
+
+from ..py_interface import scan_pH, protonate
+from ..postprocess import draw_mols
+
+os.environ.setdefault("MPLCONFIGDIR", "/tmp/matplotlib-pkasso")
+
+
+def _pyplot() -> Any:
+    import matplotlib
+
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+
+    return plt
+
+
+def render_svg_image(svg: str | bytes) -> str:
+    if isinstance(svg, bytes):
+        return svg.decode("utf-8")
+    return svg
+
+
+def figure_to_svg(fig: Any) -> str:
+    plt = _pyplot()
+    if fig is None:
+        fig = plt.gcf()
+    elif hasattr(fig, "figure") and not hasattr(fig, "savefig"):
+        fig = fig.figure
+
+    buffer = io.StringIO()
+    fig.savefig(buffer, format="svg", bbox_inches="tight")
+    plt.close(fig)
+    return buffer.getvalue()
+
+
+def compute_prediction(state: AppState) -> None:
+
+    state.error = None
+    smiles_out, mols_out = protonate(
+        state.smiles,
+        name=state.ligand,
+        pH=state.ph,
+        cutoff_export=0.0,
+        cutoff_states=CUTOFF_STATES,
+        tautomer_search=state.tautomer_search,
+    )
+    state.smiles_out = list(smiles_out[: state.nmols_export])
+    state.mols_out = list(mols_out[: state.nmols_export])
+    state.scan = None
+    state.scan_figures.clear()
+
+
+def compute_scan(state: AppState) -> None:
+
+    state.error = None
+    state.scan = scan_pH(
+        state.smiles,
+        name=state.ligand,
+        cutoff_states=CUTOFF_STATES,
+        tautomer_search=state.tautomer_search,
+        pHs=np.arange(0, 14.1, 0.25, dtype=np.float64),
+    )
+    state.scan_figures.clear()
+
+
+def draw_molecule_grid(mols: list[Any], show_probability: bool = True) -> str:
+
+    if not mols:
+        return ""
+
+    svg = draw_mols(
+        mols,
+        subImgSize=(400, 350),
+        max_cols=3,
+        show_probability=show_probability,
+    )
+    return render_svg_image(svg)
+
+
+def draw_single_molecule(mol: Any) -> str:
+
+    svg = draw_mols([mol], subImgSize=(520, 430), max_cols=1, show_probability=False)
+    return render_svg_image(svg)
+
+
+def scan_figure_svg(state: AppState, highlight_idx: int) -> str | None:
+
+    if state.scan is None:
+        return None
+
+    max_idx = len(getattr(state.scan, "mols_relevant", []))
+    highlight_idx = max(0, min(max_idx, highlight_idx))
+    if highlight_idx not in state.scan_figures:
+        fig = state.scan.plot_scan(highlight_idx=highlight_idx)
+        state.scan_figures[highlight_idx] = figure_to_svg(fig)
+    return state.scan_figures[highlight_idx]
+
+
+def sdf_for_state(state: AppState) -> bytes:
+
+    sdf = ""
+    for mol in state.mols_out:
+        mol2 = copy.deepcopy(mol)
+        mol2 = Chem.AddHs(mol2, addCoords=True)
+        AllChem.EmbedMolecule(mol2, randomSeed=1, useRandomCoords=True)
+        AllChem.UFFOptimizeMolecule(mol2)
+        sdf += Chem.MolToMolBlock(mol2) + "\n$$$$\n"
+    return sdf.encode("utf-8")

pkasso/api/config.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+API_ROOT = Path(__file__).resolve().parent
+STATIC_DIR = API_ROOT / "static"
+TEMPLATE_DIR = API_ROOT / "templates"
+DATA_DIR = API_ROOT / "data"
+FEEDBACK_DB = DATA_DIR / "feedback.sqlite3"
+
+DEFAULT_LIGAND = "mymolecule"
+DEFAULT_SMILES = "OC(=O)C(c1ccc(O)cc1)CNCCN"
+CUTOFF_STATES = 200

pkasso/api/feedback.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import sqlite3
+from datetime import datetime, timezone
+
+from .config import FEEDBACK_DB
+
+
+MAX_SMILES_LEN = 4000
+MAX_COMMENT_LEN = 8000
+
+
+def clean_feedback(smiles: str, comment: str) -> tuple[str, str]:
+    smiles = smiles.strip()
+    comment = comment.strip()
+    if not smiles:
+        raise ValueError("Please enter a SMILES code.")
+    if not comment:
+        raise ValueError("Please enter a comment.")
+    if len(smiles) > MAX_SMILES_LEN:
+        raise ValueError("SMILES code is too long.")
+    if len(comment) > MAX_COMMENT_LEN:
+        raise ValueError("Comment is too long.")
+    return smiles, comment
+
+
+def save_feedback(smiles: str, comment: str) -> None:
+    FEEDBACK_DB.parent.mkdir(parents=True, exist_ok=True)
+    created_at = datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+    with sqlite3.connect(FEEDBACK_DB) as db:
+        db.execute(
+            """
+            CREATE TABLE IF NOT EXISTS feedback (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                smiles TEXT NOT NULL,
+                comment TEXT NOT NULL,
+                created_at TEXT NOT NULL
+            )
+            """
+        )
+        db.execute(
+            "INSERT INTO feedback (smiles, comment, created_at) VALUES (?, ?, ?)",
+            (smiles, comment, created_at),
+        )

pkasso/api/render.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import html
+from typing import Any
+
+from .chemistry import draw_molecule_grid, draw_single_molecule, scan_figure_svg
+from .state import AppState
+
+
+def esc(value: Any) -> str:
+    return html.escape(str(value), quote=True)
+
+
+def render_empty(message: str) -> str:
+    return f"""
+    <div class="rounded-lg border border-dashed border-[color:var(--bind-border)] bg-white p-8 text-center text-sm text-[color:var(--bind-muted)]">
+      {esc(message)}
+    </div>
+    """
+
+
+def render_alert(message: str) -> str:
+    return f"""
+    <div role="alert" class="alert alert-error rounded-lg">
+      <span>{esc(message)}</span>
+    </div>
+    """
+
+
+def render_form(state: AppState) -> str:
+    tautomer_checked = "checked" if state.tautomer_search else ""
+    scan_checked = "checked" if state.scan_enabled else ""
+    return f"""
+    <form id="pkasso-form"
+          class="space-y-5"
+          hx-post="/predict"
+          hx-target="#results"
+          hx-swap="innerHTML"
+          hx-indicator="#predict-indicator">
+      <label class="form-control w-full">
+        <div class="label px-0"><span class="label-text text-xs font-semibold uppercase tracking-[0.14em] text-[color:var(--bind-muted)]">Small molecule name</span></div>
+        <input name="ligand" class="input input-bordered input-sm rounded-lg border-[color:var(--bind-border)] bg-white" value="{esc(state.ligand)}" />
+      </label>
+
+      <label class="form-control w-full">
+        <div class="label px-0"><span class="label-text text-xs font-semibold uppercase tracking-[0.14em] text-[color:var(--bind-muted)]">SMILES code</span></div>
+        <textarea name="smiles" class="textarea textarea-bordered min-h-28 rounded-lg border-[color:var(--bind-border)] bg-white font-mono text-sm">{esc(state.smiles)}</textarea>
+      </label>
+
+      <div class="grid grid-cols-1 gap-4 sm:grid-cols-[minmax(0,1fr)_minmax(0,7rem)]">
+        <div class="space-y-3">
+          <label class="flex min-w-0 cursor-pointer items-center gap-3 rounded-lg border border-[color:var(--bind-border)] bg-[color:var(--bind-soft)] px-3 py-2">
+            <input name="tautomer_search" type="checkbox" class="bind-toggle" {tautomer_checked} />
+            <span class="min-w-0 text-sm font-medium">Tautomer search</span>
+            <span class="bind-toggle-state ml-auto text-[11px] font-bold uppercase tracking-[0.12em] text-[color:var(--bind-muted)]"></span>
+          </label>
+
+          <label class="flex min-w-0 cursor-pointer items-center gap-3 rounded-lg border border-[color:var(--bind-border)] bg-[color:var(--bind-soft)] px-3 py-2">
+            <input name="scan_enabled" type="checkbox" class="bind-toggle" {scan_checked} />
+            <span class="min-w-0 text-sm font-medium">Full pH scan</span>
+            <span class="bind-toggle-state ml-auto text-[11px] font-bold uppercase tracking-[0.12em] text-[color:var(--bind-muted)]"></span>
+          </label>
+        </div>
+
+        <label class="form-control min-w-0">
+          <div class="label px-0 py-1"><span class="label-text text-xs font-semibold uppercase tracking-[0.14em] text-[color:var(--bind-muted)]">Max states</span></div>
+          <input name="nmols_export" type="number" min="1" max="20" value="{state.nmols_export}"
+                 class="input input-bordered input-sm min-w-0 rounded-lg border-[color:var(--bind-border)] bg-white" />
+        </label>
+      </div>
+
+      <div class="rounded-lg border border-[color:var(--bind-border)] bg-white p-4">
+        <div class="mb-3 flex items-center justify-between gap-3">
+          <span class="text-xs font-semibold uppercase tracking-[0.14em] text-[color:var(--bind-muted)]">pH</span>
+          <output id="phValue" for="phRange"
+                  class="min-w-14 rounded-lg bg-[color:var(--bind-soft)] px-2 py-1 text-center text-sm font-semibold text-[color:var(--bind-green)]">
+            {state.ph:.1f}
+          </output>
+        </div>
+        <input id="phRange" name="ph" type="range" min="0" max="14" step="0.1" value="{state.ph:.1f}"
+               class="bind-range w-full"
+               aria-describedby="phValue"
+               data-ph-range
+               style="--ph-position: {state.ph / 14 * 100:.3f}" />
+        <div class="mt-2 grid grid-cols-3 text-[11px] font-medium text-[color:var(--bind-muted)]">
+          <span>0</span><span class="text-center">7</span><span class="text-right">14</span>
+        </div>
+      </div>
+
+      <button type="submit" class="btn btn-primary btn-sm w-full rounded-lg">
+        <span style='color:white;'>Calculate states</span>
+        <span id="predict-indicator" class="loading loading-spinner loading-xs htmx-indicator"></span>
+      </button>
+    </form>
+    """
+
+
+def render_results(state: AppState) -> str:
+    if state.error:
+        return render_alert(state.error)
+
+    if not state.smiles_out:
+        return render_empty("Enter a SMILES string and calculate states to begin.")
+
+    smiles_lines = "\n".join(state.smiles_out)
+    try:
+        molecule_grid = draw_molecule_grid(state.mols_out, show_probability=True)
+    except Exception as exc:  # pragma: no cover - visual helper failure path
+        molecule_grid = render_alert(f"Could not render molecule images: {exc}")
+
+    scan_html = (
+        render_scan(state)
+        if state.scan is not None
+        else render_empty("Enable pH scan and calculate states to inspect microstate distributions.")
+    )
+    return f"""
+    <section class="space-y-4">
+      <div class="flex flex-wrap items-start justify-between gap-3 border-b border-[color:var(--bind-border)] pb-4">
+        <div>
+          <p class="section-kicker">Single pH prediction</p>
+          <h2 class="mt-1 text-2xl font-semibold tracking-tight">Predicted states at pH {state.ph:.1f}</h2>
+          <p class="mt-1 text-sm text-[color:var(--bind-muted)]">{len(state.mols_out)} exported microstate(s)</p>
+        </div>
+        <div class="flex flex-wrap gap-2">
+          <a class="btn btn-outline btn-sm rounded-lg" href="/download/sdf">Download SDF</a>
+          <button type="button" class="btn btn-secondary btn-sm rounded-lg" data-feedback-open>Feedback</button>
+        </div>
+      </div>
+
+      <pre class="overflow-x-auto rounded-lg border border-[color:var(--bind-border)] bg-[color:var(--bind-soft)] p-4 text-sm text-[#32716D]"><code>{esc(smiles_lines)}</code></pre>
+
+      <div class="overflow-x-auto rounded-lg border border-[color:var(--bind-border)] bg-white p-3 [&_svg]:max-w-full [&_svg]:h-auto">
+        {molecule_grid}
+      </div>
+
+      <div id="scan-panel">
+        {scan_html}
+      </div>
+    </section>
+    """
+
+
+def render_scan(state: AppState) -> str:
+    if state.scan is None:
+        return render_empty("Enable pH scan and calculate states to inspect microstate distributions.")
+
+    mols_relevant = list(getattr(state.scan, "mols_relevant", []))
+    plot = scan_plot_svg(state, 0)
+    microstates = []
+    for idx, mol in enumerate(mols_relevant):
+        try:
+            mol_svg = draw_single_molecule(mol)
+        except Exception as exc:  # pragma: no cover - visual helper failure path
+            mol_svg = render_alert(f"Could not render microstate {idx + 1}: {exc}")
+        microstates.append(
+            f"""
+            <button type="button"
+                    class="microstate rounded-lg border border-[color:var(--bind-border)] bg-white p-3 text-left transition hover:border-accent hover:bg-accent/5 focus:outline-none focus:ring-2 focus:ring-accent"
+                    data-microstate-enlarge
+                    data-microstate-title="Microstate {idx + 1}"
+                    hx-get="/scan/plot?highlight_idx={idx + 1}"
+                    hx-target="#scan-plot"
+                    hx-swap="innerHTML"
+                    hx-trigger="mouseenter, focus, click">
+              <span class="mb-2 block text-xs font-semibold uppercase tracking-[0.12em] text-[color:var(--bind-muted)]">Microstate {idx + 1}</span>
+              <span class="microstate-image block [&_svg]:h-auto [&_svg]:max-w-full">{mol_svg}</span>
+            </button>
+            """
+        )
+
+    if not microstates:
+        microstate_html = render_empty("No relevant microstates were returned for this scan.")
+    else:
+        grid_cols = "2xl:grid-cols-3" if len(microstates) > 4 else ""
+        microstate_html = f"""
+        <div class="grid grid-cols-1 gap-4 md:grid-cols-2 xl:grid-cols-2 {grid_cols}">
+          {"".join(microstates)}
+        </div>
+        """
+
+    return f"""
+    <section class="rounded-lg border border-[color:var(--bind-border)] bg-white p-4">
+      <div class="mb-3 flex flex-wrap items-center justify-between gap-3">
+        <div>
+          <p class="section-kicker">Full pH scan</p>
+          <h2 class="mt-1 text-2xl font-semibold tracking-tight">Microstate distributions</h2>
+          <p class="mt-1 text-sm text-[color:var(--bind-muted)]">Hover a microstate image to highlight it in the distribution plot; click to enlarge it.</p>
+        </div>
+        <button type="button"
+                class="btn btn-ghost btn-sm rounded-lg"
+                hx-get="/scan/plot?highlight_idx=0"
+                hx-target="#scan-plot"
+                hx-swap="innerHTML">
+          Clear highlight
+        </button>
+      </div>
+      <div class="grid grid-cols-1 gap-5 xl:grid-cols-[minmax(0,1.35fr)_minmax(28rem,0.95fr)]">
+        <div id="scan-plot" class="rounded-lg border border-[color:var(--bind-border)] bg-white p-4 [&_svg]:h-auto [&_svg]:w-full [&_svg]:max-w-full">
+          {plot}
+        </div>
+        {microstate_html}
+      </div>
+    </section>
+    """
+
+
+def scan_plot_svg(state: AppState, highlight_idx: int) -> str:
+    plot = scan_figure_svg(state, highlight_idx)
+    if plot is None:
+        return render_empty("Run a pH scan to show the distribution plot.")
+    return plot

pkasso/api/state.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .config import DEFAULT_LIGAND, DEFAULT_SMILES
+
+
+@dataclass
+class AppState:
+    ligand: str = DEFAULT_LIGAND
+    smiles: str = DEFAULT_SMILES
+    ph: float = 7.0
+    nmols_export: int = 3
+    tautomer_search: bool = True
+    scan_enabled: bool = False
+    smiles_out: list[str] = field(default_factory=list)
+    mols_out: list[Any] = field(default_factory=list)
+    scan: Any | None = None
+    scan_figures: dict[int, str] = field(default_factory=dict)
+    error: str | None = None
+
+
+SESSIONS: dict[str, AppState] = {}
+
+
+def update_state_from_form(state: AppState, form: dict[str, str]) -> None:
+    state.ligand = form.get("ligand", DEFAULT_LIGAND).strip() or DEFAULT_LIGAND
+    state.smiles = form.get("smiles", DEFAULT_SMILES).strip()
+    state.tautomer_search = form.get("tautomer_search") == "on"
+    state.scan_enabled = form.get("scan_enabled") == "on"
+
+    try:
+        state.ph = max(0.0, min(14.0, float(form.get("ph", "7.0"))))
+    except ValueError:
+        state.ph = 7.0
+
+    try:
+        state.nmols_export = max(1, min(20, int(form.get("nmols_export", "3"))))
+    except ValueError:
+        state.nmols_export = 3