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 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,
}