vibe-sketcherDocumentation

Source code for vibesketcher.document.queries

"""Read-only, snapshot-scoped queries over drawn atoms (#167).

Matching delegates to RDKit's VF2 implementation: Cordella et al., "A
(sub)graph isomorphism algorithm for matching large graphs", IEEE TPAMI
26, 1367-1372 (2004), doi:10.1109/TPAMI.2004.75. Native parsing and matching
run in a separate, deadline-limited process; no query is executable code.
"""

from __future__ import annotations

import json
import math
import subprocess
import sys
import threading
import time
from collections.abc import Callable, Sequence
from typing import Any

from pydantic import (
    BaseModel,
    ConfigDict,
    Field,
    StrictBool,
    StrictInt,
    field_validator,
    model_validator,
)

from vibesketcher.document.model import Document

MAX_QUERY = 500
MAX_QUERY_ATOMS = 128
MAX_FRAGMENTS = 1000
MAX_ATOMS = 25_000
MAX_MATCHES = 10_000
MAX_RESULT_BYTES = 8 * 2**20
MAX_SECONDS = 10.0
_WORKERS = threading.BoundedSemaphore(2)


[docs] class QueryRefused(ValueError): """A query cannot be completed safely or expressed by this service."""
[docs] class QueryCancelled(QueryRefused): """The caller cancelled a read; no partial match set is returned."""
[docs] class QueryBusy(QueryRefused): """Both matching workers are occupied; retry later."""
[docs] class AtomFilter(BaseModel): """Conjunction of simple atom predicates, with OR within elements.""" model_config = ConfigDict(extra="forbid", strict=True) elements: list[str] | None = Field(None, min_length=1, max_length=118) charge: StrictInt | None = Field(None, ge=-128, le=128) aromatic: StrictBool | None = None in_ring: StrictBool | None = None
[docs] @field_validator("elements") @classmethod def elements_known(cls, value: list[str] | None) -> list[str] | None: from vibesketcher.elements import ATOMIC_NUMBER if value is not None and (len(value) != len(set(value)) or set(value) - set(ATOMIC_NUMBER)): raise ValueError("choose distinct element symbols from the periodic table") return value
[docs] @model_validator(mode="after") def nonempty(self) -> AtomFilter: if all(value is None for value in self.model_dump().values()): raise ValueError("give at least one atom filter predicate") return self
[docs] class AtomQuery(BaseModel): """Exactly one SMARTS pattern or structured filter.""" model_config = ConfigDict(extra="forbid", strict=True) smarts: str | None = Field(None, min_length=1, max_length=MAX_QUERY) filter: AtomFilter | None = None species: list[str] | None = Field(None, max_length=MAX_FRAGMENTS) use_chirality: StrictBool = False
[docs] @model_validator(mode="after") def one_query(self) -> AtomQuery: if (self.smarts is None) == (self.filter is None): raise ValueError("give exactly one SMARTS pattern or atom filter") if self.smarts is not None and not self.smarts.strip(): raise ValueError("enter a SMARTS pattern") if self.smarts is not None and "$(" in self.smarts: raise ValueError("recursive SMARTS are unsupported; use explicit atom/bond patterns") if self.filter is not None and self.use_chirality: raise ValueError("chirality matching applies to SMARTS, not simple filters") if self.species is not None and len(set(self.species)) != len(self.species): raise ValueError("choose distinct species IDs") return self
def _worker_command() -> list[str]: return [sys.executable, "-m", "vibesketcher.chem.query_worker"] def _run_worker( payload: bytes, timeout: float, cancelled: Callable[[], bool] | None ) -> dict[str, Any]: process = subprocess.Popen( _worker_command(), stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE ) deadline = time.monotonic() + timeout first = True try: while True: if cancelled is not None and cancelled(): raise QueryCancelled("Atom query cancelled; no matches were applied.") remaining = deadline - time.monotonic() if remaining <= 0: raise QueryRefused(f"Atom query exceeded its {timeout:g}-second worker deadline.") try: output, errors = process.communicate( payload if first else None, timeout=min(0.05, remaining) ) break except subprocess.TimeoutExpired: first = False if cancelled is not None and cancelled(): raise QueryCancelled("Atom query cancelled; no matches were applied.") if process.returncode or len(output) > MAX_RESULT_BYTES: raise QueryRefused("Atom query worker failed or exceeded the result size limit.") try: result = json.loads(output) except (ValueError, UnicodeError) as error: raise QueryRefused("Atom query worker returned an invalid response.") from error if not isinstance(result, dict): raise QueryRefused("Atom query worker returned an invalid response.") if "error" in result: reason = str(result["error"]) if reason == "Invalid SMARTS": # The isolated worker's parser diagnostics, not a traceback or # command-line/path data. The pattern itself is bounded above. lines = [ line.split("SMARTS Parse Error:", 1)[1].strip() for line in errors.decode(errors="replace").splitlines() if "SMARTS Parse Error:" in line ] reason += ": " + ("; ".join(lines)[:1000] or "check atom/bond and bracket syntax") raise QueryRefused(reason) return result finally: if process.poll() is None: process.kill() process.communicate()
[docs] def query_atoms( document: Document, query: AtomQuery | dict[str, Any] | str, *, species: Sequence[str] | None = None, use_chirality: bool = False, timeout: float = MAX_SECONDS, cancelled: Callable[[], bool] | None = None, ) -> dict[str, Any]: """Match actual drawn atoms without editing the document or creating H atoms. Returned ``{node, atom}`` references require the exact source snapshot. ``species`` groups can contain several IDs if the stored model has more than one species with the same graph. Distinct drawn occurrences remain distinct. Cancellation/deadline/overflow refuse the whole result. """ from pydantic import ValidationError from vibesketcher.document.clean import canvas_digest from vibesketcher.document.properties import PropertiesRefused from vibesketcher.document.property_data import snapshot_digest try: if isinstance(query, str): spec = AtomQuery( smarts=query, species=list(species) if species is not None else None, use_chirality=use_chirality, ) else: if species is not None or use_chirality: raise QueryRefused("put species/chirality options in the structured query") spec = AtomQuery.model_validate(query) except ValidationError as error: raise QueryRefused( "; ".join(item["msg"] for item in error.errors(include_url=False)) ) from error if not math.isfinite(timeout) or not 0 < timeout <= MAX_SECONDS: raise QueryRefused(f"worker timeout must be positive and at most {MAX_SECONDS:g} seconds") if cancelled is not None and cancelled(): raise QueryCancelled("Atom query cancelled; no matches were applied.") snapshot = document.model_copy(deep=True) known = {s.id for s in snapshot.species} if spec.species is not None and set(spec.species) - known: raise QueryRefused("choose species IDs from the source document") try: digest = snapshot_digest(snapshot) except PropertiesRefused as error: raise QueryRefused(str(error)) from error canvas = snapshot.canvas.data or {} atoms = 0 for value in canvas.values(): if isinstance(value, dict): members = value.get("atoms", []) if not isinstance(members, list): raise QueryRefused("KET atoms must be an array") atoms += len(members) if atoms > MAX_ATOMS: raise QueryRefused(f"atom queries support at most {MAX_ATOMS} canvas atoms") payload = json.dumps( { "canvas": canvas, "query": spec.model_dump(mode="json"), "species": [{"id": s.id, "smiles": s.smiles} for s in snapshot.species], }, allow_nan=False, ).encode() if not _WORKERS.acquire(blocking=False): raise QueryBusy("Both atom-query workers are busy; retry later.") try: try: result = _run_worker(payload, timeout, cancelled) except OSError as error: raise QueryRefused( "Cannot start the atom-query worker; check the Python installation." ) from error finally: _WORKERS.release() return { "schema": "vibesketcher.atom-query/1", "source": { "revision": snapshot.revision, "sha256": digest, "canvas_sha256": canvas_digest(canvas), }, "query": spec.model_dump(mode="json"), **result, }