jupytermind 0.3.0

package/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "ai-data-scientist"
+version = "0.2.0"
+description = "GitHub Copilot Agent Skill: AI Data Scientist (MVP) over Jupyter MCP"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = [
+  "nbformat>=5.9",
+  "pandas>=2.0",
+  "scipy>=1.11",
+  "matplotlib>=3.8",
+  "openpyxl>=3.1",
+  "scikit-learn>=1.5",
+  "statsmodels>=0.14",
+  "nbconvert>=7.16",
+  "spacy>=3.7",
+  "ginza>=5.2",
+  "ja-ginza>=5.2",
+  "vaderSentiment>=3.3",
+  "plotly>=5.20",
+  "httpx>=0.27",
+  "mcp>=2.2,<2.3",
+  "jupyterlab>=4.2",
+  "jupyter-mcp-server>=2.2,<2.3",
+  "japanize-matplotlib>=1.1",
+  "packaging>=23",
+  "rdkit>=2024.3",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-json-report>=1.5", "ruff>=0.6", "pyyaml>=6.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

package/src/ai_chemistry_scientist/admet_prediction.py

@@ -0,0 +1,71 @@
+"""ADMET heuristic screening module (DES-ACHEM-020 / REQ-ACHEM-020)."""
+
+from __future__ import annotations
+
+from ai_chemistry_scientist.molecular_descriptors import compute_descriptors, parse_smiles
+from ai_chemistry_scientist.validation import fail, ok, register_validator
+
+_MODULE_NAME = "admet-prediction"
+
+#: Fixed-order Lipinski Rule-of-Five criteria (REQ-ACHEM-020 acceptance).
+_LIPINSKI_CRITERIA = (
+    ("MolWt", lambda d: d["mol_wt"] <= 500),
+    ("MolLogP", lambda d: d["mol_logp"] <= 5),
+    ("NumHDonors", lambda d: d["num_h_donors"] <= 5),
+    ("NumHAcceptors", lambda d: d["num_h_acceptors"] <= 10),
+)
+#: Fixed-order Veber rule criteria (REQ-ACHEM-020 acceptance).
+_VEBER_CRITERIA = (
+    ("NumRotatableBonds", lambda d: d["num_rotatable_bonds"] <= 10),
+    ("TPSA", lambda d: d["tpsa"] <= 140),
+)
+
+#: The handler wrapper of DES-ACHEM-001 substitutes this key for the
+#: `language`-specific text before `record_run` (REQ-ACHEM-020 Constraints).
+LIMITATION_LABEL_KEY = "admet_heuristic_limitation"
+LIMITATION_LABEL_TEXT = {
+    "en": "Heuristic only: not a physically or clinically validated ADMET prediction.",
+    "ja": ("ヒューリスティックのみ: 物理的または臨床的に検証されたADMET予測ではありません。"),
+}
+
+
+def _admet_prediction_validator(params: dict) -> dict:
+    """DES-ACHEM-002 registered atomic validator for this module."""
+    if "smiles" not in params:
+        return fail("smiles", "is required")
+    if parse_smiles(params["smiles"]) is None:
+        return fail("smiles", "must parse to a valid RDKit molecule")
+    return ok()
+
+
+register_validator(_MODULE_NAME, _admet_prediction_validator)
+
+
+# @id CODE-ACHEM-020
+# @implements REQ-ACHEM-020
+# @design DES-ACHEM-020
+def run_admet_prediction(smiles: str) -> dict:
+    """Compute descriptors and the Lipinski/Veber heuristic flags.
+
+    Receives ``smiles`` already validated atomically by its handler wrapper
+    (DES-ACHEM-001); performs no revalidation of its own.
+    """
+    mol = parse_smiles(smiles)
+    if mol is None:
+        raise ValueError("smiles must already be validated by the handler wrapper")
+    descriptors = compute_descriptors(mol)
+
+    lipinski_violations = [name for name, check in _LIPINSKI_CRITERIA if not check(descriptors)]
+    lipinski_pass = len(lipinski_violations) <= 1
+
+    veber_violations = [name for name, check in _VEBER_CRITERIA if not check(descriptors)]
+    veber_pass = len(veber_violations) == 0
+
+    return {
+        "descriptors": descriptors,
+        "lipinski_violations": lipinski_violations,
+        "lipinski_pass": lipinski_pass,
+        "veber_violations": veber_violations,
+        "veber_pass": veber_pass,
+        "limitation_label_key": LIMITATION_LABEL_KEY,
+    }

package/src/ai_chemistry_scientist/bioactivity_classification.py

@@ -0,0 +1,73 @@
+"""Bioactivity classification module (DES-ACHEM-090 / REQ-ACHEM-090)."""
+
+from __future__ import annotations
+
+from rdkit.Chem import rdMolDescriptors
+
+from ai_chemistry_scientist.molecular_descriptors import compute_descriptors, parse_smiles
+from ai_chemistry_scientist.validation import fail, ok, register_validator
+
+_MODULE_NAME = "bioactivity-classification"
+# Named decision-threshold constants (DES-ACHEM-090) so the fixed,
+# order-sensitive CNS-like/kinase-inhibitor-like boundaries are documented in
+# one place instead of as inline magic numbers.
+CNS_LIKE_TPSA_MAX = 90
+CNS_LIKE_MOLLOGP_MIN, CNS_LIKE_MOLLOGP_MAX = 2.0, 5.0
+KINASE_INHIBITOR_LIKE_MOLWT_MIN = 400
+KINASE_INHIBITOR_LIKE_AROMATIC_RING_COUNT_MIN = 3
+LIMITATION_LABEL_KEY = "bioactivity_classifier_heuristic_limitation"
+LIMITATION_LABEL_TEXT = {
+    "en": "Heuristic only: not a ChEMBL-trained or experimentally validated bioactivity classifier.",
+    "ja": (
+        "ヒューリスティックのみ: ChEMBLで学習済みでも実験的に検証済みでもない"
+        "生物活性分類器ではない。"
+    ),
+}
+
+
+# @id CODE-ACHEM-920
+# @implements REQ-ACHEM-003 REQ-ACHEM-090
+# @design DES-ACHEM-002
+def _bioactivity_classification_validator(params: dict) -> dict:
+    if "smiles" not in params:
+        return fail("smiles", "is required")
+    if parse_smiles(params["smiles"]) is None:
+        return fail("smiles", "must parse to a valid RDKit molecule")
+    return ok()
+
+
+register_validator(_MODULE_NAME, _bioactivity_classification_validator)
+
+
+# @id CODE-ACHEM-090
+# @implements REQ-ACHEM-090
+# @design DES-ACHEM-090
+def run_bioactivity_classification(smiles: str) -> dict:
+    """Assign the fixed-order heuristic label for ``smiles``."""
+    mol = parse_smiles(smiles)
+    if mol is None:
+        raise ValueError("smiles must already be validated by the handler wrapper")
+    descriptors = compute_descriptors(mol)
+    aromatic_ring_count = int(rdMolDescriptors.CalcNumAromaticRings(mol))
+
+    if (
+        descriptors["tpsa"] < CNS_LIKE_TPSA_MAX
+        and CNS_LIKE_MOLLOGP_MIN <= descriptors["mol_logp"] <= CNS_LIKE_MOLLOGP_MAX
+    ):
+        label = "CNS_like"
+    elif (
+        descriptors["mol_wt"] > KINASE_INHIBITOR_LIKE_MOLWT_MIN
+        and aromatic_ring_count >= KINASE_INHIBITOR_LIKE_AROMATIC_RING_COUNT_MIN
+    ):
+        label = "kinase_inhibitor_like"
+    else:
+        label = "other"
+
+    return {
+        "label": label,
+        "tpsa": descriptors["tpsa"],
+        "mol_logp": descriptors["mol_logp"],
+        "mol_wt": descriptors["mol_wt"],
+        "aromatic_ring_count": aromatic_ring_count,
+        "limitation_label_key": LIMITATION_LABEL_KEY,
+    }

package/src/ai_chemistry_scientist/data/sample_molecules.csv

@@ -0,0 +1,21 @@
+name,smiles
+aspirin,CC(=O)OC1=CC=CC=C1C(=O)O
+ibuprofen,CC(C)CC1=CC=C(C=C1)C(C)C(=O)O
+caffeine,CN1C=NC2=C1C(=O)N(C(=O)N2C)C
+paracetamol,CC(=O)NC1=CC=C(C=C1)O
+naproxen,COC1=CC2=CC(=CC=C2C=C1)C(C)C(=O)O
+diclofenac,OC(=O)Cc1ccccc1Nc1c(Cl)cccc1Cl
+warfarin,CC(=O)CC(c1ccccc1)c1c(O)c2ccccc2oc1=O
+metformin,CN(C)C(=N)NC(=N)N
+atorvastatin,CC(C)c1c(C(=O)Nc2ccccc2)c(-c2ccc(F)cc2)c(-c2ccc(O)cc2)n1CCC(O)CC(O)CC(=O)O
+omeprazole,CC1=CN=C(C(=C1OC)C)CS(=O)c1nc2ccc(OC)cc2[nH]1
+loratadine,CCOC(=O)N1CCC(=C2c3ccc(Cl)cc3CCc3cccnc23)CC1
+cetirizine,OC(=O)COCCN1CCN(CC1)C(c1ccccc1)c1ccc(Cl)cc1
+simvastatin,CCC(C)(C)C(=O)OC1CC(C)C=C2C=CC(C)C(CCC3CC(O)CC(=O)O3)C12
+lisinopril,CCCCC(N(CCCC(N)C(=O)O)C(=O)C(CCc1ccccc1)N)C(=O)N1CCCC1C(=O)O
+amlodipine,CCOC(=O)C1=C(COCCN)NC(C)=C(C(=O)OC)C1c1ccccc1Cl
+losartan,CCCCc1nc(Cl)c(CO)n1Cc1ccc(-c2ccccc2-c2nnn[nH]2)cc1
+metoprolol,COCCc1ccc(OCC(O)CNC(C)C)cc1
+furosemide,NS(=O)(=O)c1cc(C(=O)O)c(NCc2ccco2)cc1Cl
+ranitidine,CNC(=C[N+](=O)[O-])NCCSCc1ccc(CN(C)C)o1
+sertraline,CNC1CCC(c2ccc(Cl)c(Cl)c2)c2ccccc21

package/src/ai_chemistry_scientist/dispatch.py

@@ -0,0 +1,369 @@
+"""Method manifest & request dispatcher (DES-ACHEM-001 / REQ-ACHEM-001/002)."""
+
+from __future__ import annotations
+
+import importlib
+import json
+from pathlib import Path
+
+import rdkit
+
+# Imported eagerly (not lazily inside `_resolve_run_function`) so each
+# module's `register_validator`/`register_batch_item_validator` call runs
+# before any `validate_parameters` lookup below.
+import ai_chemistry_scientist.admet_prediction as _admet_prediction  # noqa: F401
+import ai_chemistry_scientist.bioactivity_classification as _bioactivity_classification  # noqa: F401
+import ai_chemistry_scientist.docking_score as _docking_score  # noqa: F401
+import ai_chemistry_scientist.drug_likeness_rules as _drug_likeness_rules  # noqa: F401
+import ai_chemistry_scientist.molecular_descriptors as _molecular_descriptors  # noqa: F401
+import ai_chemistry_scientist.molecular_formula_mass as _molecular_formula_mass  # noqa: F401
+import ai_chemistry_scientist.molecular_similarity as _molecular_similarity  # noqa: F401
+import ai_chemistry_scientist.qsar_modeling as _qsar_modeling  # noqa: F401
+import ai_chemistry_scientist.salt_standardization as _salt_standardization  # noqa: F401
+import ai_chemistry_scientist.structural_alerts as _structural_alerts  # noqa: F401
+import ai_chemistry_scientist.structure_format_conversion as _structure_format_conversion  # noqa: F401
+from ai_chemistry_scientist.evidence import record_run
+from ai_chemistry_scientist.validation import validate_parameters
+from ai_data_scientist.language_router import detect_language as _detect_language
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_MANIFEST_PATH = (
+    REPO_ROOT / ".github" / "skills" / "ai-chemistry-scientist" / "manifest.json"
+)
+
+#: The one module whose handler wrapper skips the separate upfront
+#: `validate_parameters` call, because its own `run_*` function interleaves
+#: per-item validation with per-item computation (ADR-0026, DES-ACHEM-001).
+_PER_ITEM_VALIDATED_MODULES = frozenset({"molecular-descriptors"})
+
+#: modules whose raw result's `limitation_label_key` is substituted with the
+#: matching `language`-specific text before `record_run` (DES-ACHEM-001).
+_LIMITATION_LABEL_MODULES = frozenset(
+    {
+        "admet-prediction",
+        "docking-score",
+        "structural-alerts",
+        "bioactivity-classification",
+        "salt-removal",
+    }
+)
+
+_RUN_MODULE_PATHS = {
+    "molecular-descriptors": "ai_chemistry_scientist.molecular_descriptors",
+    "admet-prediction": "ai_chemistry_scientist.admet_prediction",
+    "qsar-modeling": "ai_chemistry_scientist.qsar_modeling",
+    "molecular-similarity": "ai_chemistry_scientist.molecular_similarity",
+    "docking-score": "ai_chemistry_scientist.docking_score",
+    "drug-likeness-rules": "ai_chemistry_scientist.drug_likeness_rules",
+    "structural-alerts": "ai_chemistry_scientist.structural_alerts",
+    "molecular-formula-mass": "ai_chemistry_scientist.molecular_formula_mass",
+    "bioactivity-classification": "ai_chemistry_scientist.bioactivity_classification",
+    "salt-removal": "ai_chemistry_scientist.salt_standardization",
+    "structure-format-conversion": "ai_chemistry_scientist.structure_format_conversion",
+}
+_RUN_FUNCTION_NAMES = {
+    "molecular-descriptors": "run_molecular_descriptors",
+    "admet-prediction": "run_admet_prediction",
+    "qsar-modeling": "run_qsar_modeling",
+    "molecular-similarity": "run_molecular_similarity",
+    "docking-score": "run_docking_score",
+    "drug-likeness-rules": "run_drug_likeness_rules",
+    "structural-alerts": "run_structural_alerts",
+    "molecular-formula-mass": "run_molecular_formula_mass",
+    "bioactivity-classification": "run_bioactivity_classification",
+    "salt-removal": "run_salt_removal",
+    "structure-format-conversion": "run_structure_conversion",
+}
+
+
+def load_manifest(manifest_path: Path | None = None) -> dict:
+    """Load the static method-name-to-module manifest (DES-ACHEM-001)."""
+    path = manifest_path or DEFAULT_MANIFEST_PATH
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _matched_methods(request_text: str, manifest: dict) -> list[str]:
+    # Collapse runs of whitespace so extra spacing between words in a
+    # request (e.g. multi-space or tab-separated phrasing) still matches an
+    # English candidate phrase (REQ-ACHEM-002); Japanese candidates have no
+    # internal whitespace, so matching against the raw text is unaffected.
+    lowered = " ".join(request_text.lower().split())
+    matched = []
+    for method, entry in manifest.items():
+        names = entry.get("names", {})
+        candidates = list(names.get("en", [])) + list(names.get("ja", []))
+        if any(
+            (candidate.lower() in lowered) if candidate.isascii() else (candidate in request_text)
+            for candidate in candidates
+        ):
+            matched.append(method)
+    return matched
+
+
+# @id CODE-ACHEM-916
+# @implements REQ-ACHEM-002
+# @design DES-ACHEM-001
+def extract_params(request_text: str) -> dict | None:
+    """Extract a module's structured ``params`` embedded in ``request_text``.
+
+    Each handler wrapper's own documented extraction responsibility
+    (DES-ACHEM-001): a calling context supplies structured parameters by
+    embedding exactly one JSON object literal anywhere in ``request_text``
+    (e.g. a natural-language instruction followed by
+    ``{"smiles": "CC(=O)OC1=CC=CC=C1C(=O)O"}``). Returns ``None`` when no
+    balanced top-level JSON object is present or it fails to parse.
+    """
+    start = request_text.find("{")
+    if start == -1:
+        return None
+    depth = 0
+    for index in range(start, len(request_text)):
+        char = request_text[index]
+        if char == "{":
+            depth += 1
+        elif char == "}":
+            depth -= 1
+            if depth == 0:
+                candidate = request_text[start : index + 1]
+                try:
+                    parsed = json.loads(candidate)
+                except json.JSONDecodeError:
+                    return None
+                return parsed if isinstance(parsed, dict) else None
+    return None
+
+
+def _resolve_run_function(method: str):
+    """Resolve each module's raw ``run_*`` compute function by method name."""
+    module = importlib.import_module(_RUN_MODULE_PATHS[method])
+    return getattr(module, _RUN_FUNCTION_NAMES[method])
+
+
+def _localize_limitation_label(method: str, result: dict, language: str) -> dict:
+    """Substitute `limitation_label_key` with its `language` text (DES-ACHEM-001)."""
+    if method not in _LIMITATION_LABEL_MODULES:
+        return result
+    module_path = {
+        "admet-prediction": "ai_chemistry_scientist.admet_prediction",
+        "docking-score": "ai_chemistry_scientist.docking_score",
+        "structural-alerts": "ai_chemistry_scientist.structural_alerts",
+        "bioactivity-classification": "ai_chemistry_scientist.bioactivity_classification",
+        "salt-removal": "ai_chemistry_scientist.salt_standardization",
+    }[method]
+    module = importlib.import_module(module_path)
+    key = result["limitation_label_key"]
+    assert key == module.LIMITATION_LABEL_KEY
+    text = module.LIMITATION_LABEL_TEXT[language]
+    localized = dict(result)
+    del localized["limitation_label_key"]
+    localized["limitation_label"] = text
+    return localized
+
+
+def _no_params_outcome(language: str) -> dict:
+    return {
+        "ok": False,
+        "parameter": "params",
+        "constraint": "must be extractable as a JSON object embedded in request_text",
+        "language": language,
+    }
+
+
+def _handle_module(
+    method: str, request_text: str, language: str, params: dict | None = None
+) -> dict:
+    """Shared handler-wrapper body for ``method`` (DES-ACHEM-001's `handle_<method>`).
+
+    Extracts params from ``request_text``, validates (except for the
+    per-item-validated module), computes via the raw `run_*` function,
+    localizes limitation labels, and wraps the result into a RunRecord
+    (DES-ACHEM-003) — a `ModuleOutcome`.
+    """
+    resolved_params = params if params is not None else extract_params(request_text)
+    if resolved_params is None:
+        return _no_params_outcome(language)
+
+    if method not in _PER_ITEM_VALIDATED_MODULES:
+        validation = validate_parameters(method, resolved_params)
+        if not validation["ok"]:
+            return {
+                "ok": False,
+                "parameter": validation["parameter"],
+                "constraint": validation["constraint"],
+                "language": language,
+            }
+
+    run_function = _resolve_run_function(method)
+    result = run_function(**resolved_params)
+    result = _localize_limitation_label(method, result, language)
+
+    extra_kwargs = {}
+    if method == "qsar-modeling":
+        import sklearn
+
+        extra_kwargs["scikit_learn_version"] = sklearn.__version__
+
+    run_record = record_run(
+        module_name=method,
+        params=resolved_params,
+        result=result,
+        rdkit_version=rdkit.__version__,
+        **extra_kwargs,
+    )
+    return {"ok": True, "run_record": run_record}
+
+
+# @id CODE-ACHEM-011
+# @implements REQ-ACHEM-002 REQ-ACHEM-003
+# @design DES-ACHEM-001
+def handle_molecular_descriptors(request_text: str, language: str, **params) -> dict:
+    """Handler wrapper for the molecular-descriptors module (DES-ACHEM-010)."""
+    return _handle_module("molecular-descriptors", request_text, language, params or None)
+
+
+# @id CODE-ACHEM-021
+# @implements REQ-ACHEM-002 REQ-ACHEM-003
+# @design DES-ACHEM-001
+def handle_admet_prediction(request_text: str, language: str, **params) -> dict:
+    """Handler wrapper for the admet-prediction module (DES-ACHEM-020)."""
+    return _handle_module("admet-prediction", request_text, language, params or None)
+
+
+# @id CODE-ACHEM-031
+# @implements REQ-ACHEM-002 REQ-ACHEM-003
+# @design DES-ACHEM-001
+def handle_qsar_modeling(request_text: str, language: str, **params) -> dict:
+    """Handler wrapper for the qsar-modeling module (DES-ACHEM-030)."""
+    return _handle_module("qsar-modeling", request_text, language, params or None)
+
+
+# @id CODE-ACHEM-041
+# @implements REQ-ACHEM-002 REQ-ACHEM-003
+# @design DES-ACHEM-001
+def handle_molecular_similarity(request_text: str, language: str, **params) -> dict:
+    """Handler wrapper for the molecular-similarity module (DES-ACHEM-040)."""
+    return _handle_module("molecular-similarity", request_text, language, params or None)
+
+
+# @id CODE-ACHEM-051
+# @implements REQ-ACHEM-002 REQ-ACHEM-003
+# @design DES-ACHEM-001
+def handle_docking_score(request_text: str, language: str, **params) -> dict:
+    """Handler wrapper for the docking-score module (DES-ACHEM-050)."""
+    return _handle_module("docking-score", request_text, language, params or None)
+
+
+# @id CODE-ACHEM-061
+# @implements REQ-ACHEM-002 REQ-ACHEM-003
+# @design DES-ACHEM-001
+def handle_drug_likeness_rules(request_text: str, language: str, **params) -> dict:
+    """Handler wrapper for the drug-likeness-rules module (DES-ACHEM-060)."""
+    return _handle_module("drug-likeness-rules", request_text, language, params or None)
+
+
+# @id CODE-ACHEM-071
+# @implements REQ-ACHEM-002 REQ-ACHEM-003
+# @design DES-ACHEM-001
+def handle_structural_alerts(request_text: str, language: str, **params) -> dict:
+    """Handler wrapper for the structural-alerts module (DES-ACHEM-070)."""
+    return _handle_module("structural-alerts", request_text, language, params or None)
+
+
+# @id CODE-ACHEM-081
+# @implements REQ-ACHEM-002 REQ-ACHEM-003
+# @design DES-ACHEM-001
+def handle_molecular_formula_mass(request_text: str, language: str, **params) -> dict:
+    """Handler wrapper for the molecular-formula-mass module (DES-ACHEM-080)."""
+    return _handle_module("molecular-formula-mass", request_text, language, params or None)
+
+
+# @id CODE-ACHEM-091
+# @implements REQ-ACHEM-002 REQ-ACHEM-003
+# @design DES-ACHEM-001
+def handle_bioactivity_classification(request_text: str, language: str, **params) -> dict:
+    """Handler wrapper for the bioactivity-classification module (DES-ACHEM-090)."""
+    return _handle_module("bioactivity-classification", request_text, language, params or None)
+
+
+# @id CODE-ACHEM-101
+# @implements REQ-ACHEM-002 REQ-ACHEM-003
+# @design DES-ACHEM-001
+def handle_salt_removal(request_text: str, language: str, **params) -> dict:
+    """Handler wrapper for the salt-removal module (DES-ACHEM-100)."""
+    return _handle_module("salt-removal", request_text, language, params or None)
+
+
+# @id CODE-ACHEM-111
+# @implements REQ-ACHEM-002 REQ-ACHEM-003
+# @design DES-ACHEM-001
+def handle_structure_format_conversion(request_text: str, language: str, **params) -> dict:
+    """Handler wrapper for the structure-format-conversion module (DES-ACHEM-110)."""
+    return _handle_module("structure-format-conversion", request_text, language, params or None)
+
+
+# @id CODE-ACHEM-001
+# @implements REQ-ACHEM-001 REQ-ACHEM-002
+# @design DES-ACHEM-001
+def dispatch(
+    request_text: str,
+    language: str | None = None,
+    manifest_path: Path | None = None,
+) -> dict:
+    """Classify ``request_text`` and dispatch to exactly one matched module.
+
+    ``language`` may be supplied explicitly; otherwise it is detected from
+    ``request_text`` (REQ-ACHEM-001) and propagated into the result so every
+    downstream (module handler, clarification, rejection) path can render
+    its user-facing text in that language.
+    """
+    if not isinstance(request_text, str):
+        raise ValueError("request_text: must be a str")  # noqa: TRY004
+    if language is not None and language not in ("en", "ja"):
+        raise ValueError("language: must be 'en' or 'ja' when explicitly supplied")
+    detected_language = language or _detect_language(request_text)
+    manifest = load_manifest(manifest_path)
+    matched = _matched_methods(request_text, manifest)
+
+    if len(matched) == 1:
+        method = matched[0]
+        entry = manifest[method]
+        handler_module = importlib.import_module(entry["modulePath"])
+        handler = getattr(handler_module, entry["functionName"])
+        handler_result = handler(request_text, detected_language)
+        return {
+            "outcome": "dispatch",
+            "module": method,
+            "language": detected_language,
+            "handler_result": handler_result,
+        }
+    if len(matched) > 1:
+        return {
+            "outcome": "clarification",
+            "candidates": matched,
+            "language": detected_language,
+            "clarification_question": _render_clarification(matched, detected_language),
+        }
+    return {
+        "outcome": "rejected",
+        "language": detected_language,
+        "rejected_method": _render_rejection(detected_language),
+    }
+
+
+def _render_clarification(candidates: list[str], language: str) -> str:
+    """Render a single-sentence clarification question in ``language``.
+
+    Method names (e.g. ``molecular-descriptors``) are the only permitted
+    non-``language`` tokens, per REQ-ACHEM-001's acceptance.
+    """
+    names = "、".join(candidates) if language == "ja" else ", ".join(candidates)
+    if language == "ja":
+        return f"{names} のどちらを意図していますか。明確にしてください。"
+    return f"Did you mean {names}? Please clarify which method you want."
+
+
+def _render_rejection(language: str) -> str:
+    """Render a single-sentence rejection message in ``language``."""
+    if language == "ja":
+        return "対応する手法が要求から認識されませんでした。"
+    return "No supported method was recognized in your request."

package/src/ai_chemistry_scientist/docking_score.py

@@ -0,0 +1,97 @@
+"""Simplified docking-score heuristic module (DES-ACHEM-050 / REQ-ACHEM-050)."""
+
+from __future__ import annotations
+
+import math
+
+from ai_chemistry_scientist.molecular_descriptors import parse_smiles
+from ai_chemistry_scientist.validation import fail, ok, register_validator
+
+_MODULE_NAME = "docking-score"
+_VOLUME_PER_HEAVY_ATOM_A3 = 15.0
+
+#: The handler wrapper of DES-ACHEM-001 substitutes this key for the
+#: `language`-specific text before `record_run` (REQ-ACHEM-050 Constraints).
+LIMITATION_LABEL_KEY = "docking_heuristic_limitation"
+LIMITATION_LABEL_TEXT = {
+    "en": (
+        "Heuristic only: not a physically accurate docking simulation (no 3D "
+        "conformer generation, no energy function)."
+    ),
+    "ja": (
+        "ヒューリスティックのみ: 物理的に正確なドッキングシミュレーションでは"
+        "ありません（3D配座生成・エネルギー関数なし）。"
+    ),
+}
+
+
+def _is_finite_non_negative_int(value) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool) and value >= 0
+
+
+def _docking_score_validator(params: dict) -> dict:
+    """DES-ACHEM-002 registered atomic validator for this module."""
+    if "ligand_smiles" not in params:
+        return fail("ligand_smiles", "is required")
+    if "pocket_spec" not in params:
+        return fail("pocket_spec", "is required")
+    if parse_smiles(params["ligand_smiles"]) is None:
+        return fail("smiles", "must parse to a valid RDKit molecule")
+    pocket_spec = params["pocket_spec"]
+    if not isinstance(pocket_spec, dict):
+        return fail("pocket_spec", "must be a dict")
+    for key in ("pocket_volume_A3", "pocket_hba_sites", "pocket_hbd_sites"):
+        if key not in pocket_spec:
+            return fail(key, "is required")
+    pocket_volume_a3 = pocket_spec["pocket_volume_A3"]
+    if (
+        not isinstance(pocket_volume_a3, (int, float))
+        or isinstance(pocket_volume_a3, bool)
+        or not math.isfinite(pocket_volume_a3)
+        or pocket_volume_a3 <= 0
+    ):
+        return fail("pocket_volume_A3", "must be a finite number > 0")
+    if not _is_finite_non_negative_int(pocket_spec["pocket_hba_sites"]):
+        return fail("pocket_hba_sites", "must be a finite non-negative integer")
+    if not _is_finite_non_negative_int(pocket_spec["pocket_hbd_sites"]):
+        return fail("pocket_hbd_sites", "must be a finite non-negative integer")
+    return ok()
+
+
+register_validator(_MODULE_NAME, _docking_score_validator)
+
+
+# @id CODE-ACHEM-050
+# @implements REQ-ACHEM-050
+# @design DES-ACHEM-050
+def run_docking_score(ligand_smiles: str, pocket_spec: dict) -> dict:
+    """Compute the fixed-formula heuristic docking score for the ligand-pocket pair.
+
+    Receives ``ligand_smiles``/``pocket_spec`` already validated atomically
+    by its handler wrapper; performs no revalidation of its own.
+    """
+    from rdkit.Chem import Descriptors
+
+    mol = parse_smiles(ligand_smiles)
+    if mol is None:
+        raise ValueError("ligand_smiles must already be validated by the handler wrapper")
+    heavy_atom_count = mol.GetNumHeavyAtoms()
+    ligand_hbd = int(Descriptors.NumHDonors(mol))
+    ligand_hba = int(Descriptors.NumHAcceptors(mol))
+
+    pocket_volume_a3 = pocket_spec["pocket_volume_A3"]
+    pocket_hba_sites = pocket_spec["pocket_hba_sites"]
+    pocket_hbd_sites = pocket_spec["pocket_hbd_sites"]
+
+    ligand_volume = heavy_atom_count * _VOLUME_PER_HEAVY_ATOM_A3
+    size_fit = min(1.0, max(0.0, 1 - abs(ligand_volume - pocket_volume_a3) / pocket_volume_a3))
+    matched_pairs = min(ligand_hbd, pocket_hba_sites) + min(ligand_hba, pocket_hbd_sites)
+    hbond_fit = matched_pairs / max(1, ligand_hbd + ligand_hba)
+    score = 0.5 * size_fit + 0.5 * hbond_fit
+
+    return {
+        "score": score,
+        "size_fit": size_fit,
+        "hbond_fit": hbond_fit,
+        "limitation_label_key": LIMITATION_LABEL_KEY,
+    }