jupytermind 0.3.0

package/src/ai_structural_biology_scientist/contact_map.py

@@ -0,0 +1,87 @@
+"""Residue contact-map heuristic module (DES-ASTRUCT-050 / REQ-ASTRUCT-050)."""
+
+from __future__ import annotations
+
+import math
+from numbers import Integral
+
+from ai_structural_biology_scientist.validation import (
+    fail,
+    is_finite_real,
+    register_validator,
+    validate_coordinate,
+)
+
+_MODULE_NAME = "residue-contact-map"
+_COORDINATE_CONSTRAINT = "must be a finite numeric 3-element sequence"
+
+
+def _contact_map_validator(params: dict) -> dict:
+    """DES-ASTRUCT-002 registered atomic validator for this module."""
+    if "coordinates" not in params:
+        return fail("coordinates", "is required")
+
+    coordinates = params["coordinates"]
+    if not isinstance(coordinates, list):
+        return fail("coordinates", "must be a list")
+    if len(coordinates) < 2:
+        return fail("coordinates", "must contain at least 2 coordinates")
+    for index, coordinate in enumerate(coordinates):
+        coordinate_validation = validate_coordinate(
+            coordinate,
+            parameter=f"coordinates[{index}]",
+            constraint=_COORDINATE_CONSTRAINT,
+        )
+        if not coordinate_validation["ok"]:
+            return coordinate_validation
+
+    distance_threshold_a = params.get("distance_threshold_A", 8.0)
+    if not is_finite_real(distance_threshold_a) or distance_threshold_a <= 0:
+        return fail("distance_threshold_A", "must be > 0")
+
+    min_sequence_separation = params.get("min_sequence_separation", 3)
+    if (
+        not isinstance(min_sequence_separation, Integral)
+        or isinstance(min_sequence_separation, bool)
+        or min_sequence_separation < 1
+    ):
+        return fail("min_sequence_separation", "must be an integer >= 1")
+
+    return {"ok": True}
+
+
+register_validator(_MODULE_NAME, _contact_map_validator)
+
+
+# @id CODE-ASTRUCT-050
+# @implements REQ-ASTRUCT-050
+# @design DES-ASTRUCT-050
+def run_contact_map(
+    coordinates: list,
+    distance_threshold_A: float = 8.0,
+    min_sequence_separation: int = 3,
+) -> dict:
+    """Compute the C-alpha contact-map heuristic."""
+    validation = _contact_map_validator(
+        {
+            "coordinates": coordinates,
+            "distance_threshold_A": distance_threshold_A,
+            "min_sequence_separation": min_sequence_separation,
+        }
+    )
+    if not validation["ok"]:
+        raise ValueError("parameters must already be validated by the handler wrapper")
+
+    contact_matrix = [[False for _ in coordinates] for _ in coordinates]
+    total_contacts = 0
+    for i in range(len(coordinates)):
+        for j in range(i + 1, len(coordinates)):
+            if abs(i - j) < min_sequence_separation:
+                continue
+            distance = math.dist(coordinates[i], coordinates[j])
+            if distance <= distance_threshold_A:
+                contact_matrix[i][j] = True
+                contact_matrix[j][i] = True
+                total_contacts += 1
+
+    return {"contact_matrix": contact_matrix, "total_contacts": total_contacts}

package/src/ai_structural_biology_scientist/dispatch.py

@@ -0,0 +1,269 @@
+"""Method manifest & request dispatcher (DES-ASTRUCT-001 / REQ-ASTRUCT-001/002)."""
+
+from __future__ import annotations
+
+import importlib
+import json
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+import ai_structural_biology_scientist.contact_map as _contact_map  # noqa: F401
+import ai_structural_biology_scientist.hydrophobicity as _hydrophobicity  # noqa: F401
+import ai_structural_biology_scientist.protein_docking_score as _protein_docking_score  # noqa: F401
+import ai_structural_biology_scientist.secondary_structure as _secondary_structure  # noqa: F401
+import ai_structural_biology_scientist.structural_similarity as _structural_similarity  # noqa: F401
+from ai_data_scientist.language_router import detect_language as _detect_language
+from ai_structural_biology_scientist.evidence import record_run
+from ai_structural_biology_scientist.validation import validate_parameters
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_MANIFEST_PATH = (
+    REPO_ROOT / ".github" / "skills" / "ai-structural-biology-scientist" / "manifest.json"
+)
+
+_LIMITATION_LABEL_MODULES = frozenset(
+    {"secondary-structure-heuristic", "protein-protein-docking-score"}
+)
+_RUN_MODULE_PATHS = {
+    "secondary-structure-heuristic": "ai_structural_biology_scientist.secondary_structure",
+    "hydrophobicity-burial-heuristic": "ai_structural_biology_scientist.hydrophobicity",
+    "protein-protein-docking-score": "ai_structural_biology_scientist.protein_docking_score",
+    "structural-similarity-rmsd": "ai_structural_biology_scientist.structural_similarity",
+    "residue-contact-map": "ai_structural_biology_scientist.contact_map",
+}
+_RUN_FUNCTION_NAMES = {
+    "secondary-structure-heuristic": "run_secondary_structure",
+    "hydrophobicity-burial-heuristic": "run_hydrophobicity",
+    "protein-protein-docking-score": "run_protein_docking_score",
+    "structural-similarity-rmsd": "run_structural_similarity",
+    "residue-contact-map": "run_contact_map",
+}
+_SUPPORTED_LANGUAGES = ("en", "ja")
+
+
+def _require_manifest_string(entry: dict[str, Any], method: str, field_name: str) -> None:
+    value = entry.get(field_name)
+    if not isinstance(value, str) or value == "":
+        raise ValueError(  # noqa: TRY004
+            f"manifest entry '{method}' must define a string '{field_name}'"
+        )
+
+
+def _validate_manifest(manifest: Any) -> dict[str, dict[str, Any]]:
+    if not isinstance(manifest, dict):
+        raise ValueError("manifest must be a JSON object")  # noqa: TRY004
+
+    for method, entry in manifest.items():
+        if not isinstance(entry, dict):
+            raise ValueError(f"manifest entry '{method}' must be a JSON object")  # noqa: TRY004
+        _require_manifest_string(entry, method, "modulePath")
+        _require_manifest_string(entry, method, "functionName")
+        names = entry.get("names")
+        if not isinstance(names, dict):
+            raise ValueError(f"manifest entry '{method}' must define an object 'names'")  # noqa: TRY004
+        for language in _SUPPORTED_LANGUAGES:
+            candidates = names.get(language)
+            if not isinstance(candidates, list) or any(
+                not isinstance(candidate, str) or candidate == "" for candidate in candidates
+            ):
+                raise ValueError(  # noqa: TRY004
+                    f"manifest entry '{method}' must define a list of non-empty strings at "
+                    f"'names.{language}'"
+                )
+    return manifest
+
+
+def load_manifest(manifest_path: Path | None = None) -> dict:
+    """Load the static method-name-to-module manifest."""
+    path = manifest_path or DEFAULT_MANIFEST_PATH
+    return _validate_manifest(json.loads(path.read_text(encoding="utf-8")))
+
+
+def _matched_methods(request_text: str, manifest: dict) -> list[str]:
+    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-ASTRUCT-901
+# @implements REQ-ASTRUCT-002
+# @design DES-ASTRUCT-001
+def extract_params(request_text: Any) -> dict[str, Any] | None:
+    """Extract structured params or a single embedded JSON object from input."""
+    if isinstance(request_text, dict):
+        return dict(request_text)
+    if not isinstance(request_text, str):
+        return None
+    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):
+    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:
+    if method not in _LIMITATION_LABEL_MODULES:
+        return result
+    module = importlib.import_module(_RUN_MODULE_PATHS[method])
+    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) -> dict:
+    params = extract_params(request_text)
+    if params is None:
+        return _no_params_outcome(language)
+
+    validation = validate_parameters(method, params)
+    if not validation["ok"]:
+        return {
+            "ok": False,
+            "parameter": validation["parameter"],
+            "constraint": validation["constraint"],
+            "language": language,
+        }
+
+    result = _resolve_run_function(method)(**params)
+    result = _localize_limitation_label(method, result, language)
+    run_record = record_run(
+        module_name=method,
+        params=params,
+        result=result,
+        numpy_version=np.__version__,
+    )
+    return {"ok": True, "run_record": run_record}
+
+
+# @id CODE-ASTRUCT-011
+# @implements REQ-ASTRUCT-002 REQ-ASTRUCT-003
+# @design DES-ASTRUCT-001
+def handle_secondary_structure(request_text: str, language: str) -> dict:
+    """Handler wrapper for the secondary-structure module."""
+    return _handle_module("secondary-structure-heuristic", request_text, language)
+
+
+# @id CODE-ASTRUCT-021
+# @implements REQ-ASTRUCT-002 REQ-ASTRUCT-003
+# @design DES-ASTRUCT-001
+def handle_hydrophobicity(request_text: str, language: str) -> dict:
+    """Handler wrapper for the hydrophobicity module."""
+    return _handle_module("hydrophobicity-burial-heuristic", request_text, language)
+
+
+# @id CODE-ASTRUCT-031
+# @implements REQ-ASTRUCT-002 REQ-ASTRUCT-003
+# @design DES-ASTRUCT-001
+def handle_protein_docking_score(request_text: str, language: str) -> dict:
+    """Handler wrapper for the protein-docking module."""
+    return _handle_module("protein-protein-docking-score", request_text, language)
+
+
+# @id CODE-ASTRUCT-041
+# @implements REQ-ASTRUCT-002 REQ-ASTRUCT-003
+# @design DES-ASTRUCT-001
+def handle_structural_similarity(request_text: str, language: str) -> dict:
+    """Handler wrapper for the structural-similarity module."""
+    return _handle_module("structural-similarity-rmsd", request_text, language)
+
+
+# @id CODE-ASTRUCT-051
+# @implements REQ-ASTRUCT-002 REQ-ASTRUCT-003
+# @design DES-ASTRUCT-001
+def handle_contact_map(request_text: str, language: str) -> dict:
+    """Handler wrapper for the contact-map module."""
+    return _handle_module("residue-contact-map", request_text, language)
+
+
+def _render_clarification(candidates: list[str], language: str) -> str:
+    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:
+    if language == "ja":
+        return "対応する手法が要求から認識されませんでした。"
+    return "No supported method was recognized in your request."
+
+
+# @id CODE-ASTRUCT-001
+# @implements REQ-ASTRUCT-001 REQ-ASTRUCT-002
+# @design DES-ASTRUCT-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."""
+    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 = getattr(importlib.import_module(entry["modulePath"]), entry["functionName"])
+        return {
+            "outcome": "dispatch",
+            "module": method,
+            "language": detected_language,
+            "handler_result": handler(request_text, detected_language),
+        }
+    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),
+    }

package/src/ai_structural_biology_scientist/evidence.py

@@ -0,0 +1,43 @@
+"""Run evidence recorder (DES-ASTRUCT-003 / REQ-ASTRUCT-004)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy
+
+SCHEMA_VERSION = 1
+
+
+def _json_safe_value(value: Any) -> Any:
+    if value is None or isinstance(value, (str, bool, int, float)):
+        return value
+    if isinstance(value, numpy.generic):
+        return _json_safe_value(value.item())
+    if isinstance(value, dict):
+        return {key: _json_safe_value(nested) for key, nested in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_json_safe_value(item) for item in value]
+    raise TypeError(f"unsupported non-JSON-safe value: {type(value).__name__}")
+
+
+# @id CODE-ASTRUCT-003
+# @implements REQ-ASTRUCT-004
+# @design DES-ASTRUCT-003
+def record_run(
+    module_name: str,
+    params: dict[str, Any],
+    result: Any,
+    *,
+    numpy_version: str,
+) -> dict:
+    """Build a RunRecord with exactly `metadata`, `parameters`, `result`."""
+    return {
+        "metadata": {
+            "module": module_name,
+            "schema_version": SCHEMA_VERSION,
+            "numpy_version": numpy_version,
+        },
+        "parameters": _json_safe_value(params),
+        "result": _json_safe_value(result),
+    }

package/src/ai_structural_biology_scientist/hydrophobicity.py

@@ -0,0 +1,101 @@
+"""Hydrophobicity / burial heuristic module (DES-ASTRUCT-020 / REQ-ASTRUCT-020)."""
+
+from __future__ import annotations
+
+from numbers import Integral
+
+from ai_structural_biology_scientist.validation import (
+    fail,
+    is_finite_real,
+    register_validator,
+    validate_uppercase_sequence,
+)
+
+_MODULE_NAME = "hydrophobicity-burial-heuristic"
+_KD_SCALE = {
+    "A": 1.8,
+    "R": -4.5,
+    "N": -3.5,
+    "D": -3.5,
+    "C": 2.5,
+    "Q": -3.5,
+    "E": -3.5,
+    "G": -0.4,
+    "H": -3.2,
+    "I": 4.5,
+    "L": 3.8,
+    "K": -3.9,
+    "M": 1.9,
+    "F": 2.8,
+    "P": -1.6,
+    "S": -0.8,
+    "T": -0.7,
+    "W": -0.9,
+    "Y": -1.3,
+    "V": 4.2,
+}
+
+
+def _hydrophobicity_validator(params: dict) -> dict:
+    """DES-ASTRUCT-002 registered atomic validator for this module."""
+    if "sequence" not in params:
+        return fail("sequence", "is required")
+    sequence_validation = validate_uppercase_sequence(params)
+    if not sequence_validation["ok"]:
+        return sequence_validation
+
+    window_size = params.get("window_size", 9)
+    if (
+        not isinstance(window_size, Integral)
+        or isinstance(window_size, bool)
+        or window_size < 1
+        or window_size % 2 == 0
+    ):
+        return fail("window_size", "must be a positive odd integer")
+
+    burial_threshold = params.get("burial_threshold", 1.5)
+    if not is_finite_real(burial_threshold):
+        return fail("burial_threshold", "must be a finite number")
+
+    return {"ok": True}
+
+
+register_validator(_MODULE_NAME, _hydrophobicity_validator)
+
+
+# @id CODE-ASTRUCT-020
+# @implements REQ-ASTRUCT-020
+# @design DES-ASTRUCT-020
+def run_hydrophobicity(
+    sequence: str,
+    window_size: int = 9,
+    burial_threshold: float = 1.5,
+) -> dict:
+    """Compute the Kyte-Doolittle burial heuristic for ``sequence``."""
+    validation = _hydrophobicity_validator(
+        {
+            "sequence": sequence,
+            "window_size": window_size,
+            "burial_threshold": burial_threshold,
+        }
+    )
+    if not validation["ok"]:
+        raise ValueError("parameters must already be validated by the handler wrapper")
+
+    half_window = window_size // 2
+    residues = []
+    for position, residue in enumerate(sequence):
+        start = max(0, position - half_window)
+        stop = min(len(sequence), position + half_window + 1)
+        window_values = [_KD_SCALE[window_residue] for window_residue in sequence[start:stop]]
+        window_average = sum(window_values) / len(window_values)
+        residues.append(
+            {
+                "position": position,
+                "residue": residue,
+                "kd_value": _KD_SCALE[residue],
+                "window_average": window_average,
+                "label": "buried" if window_average > burial_threshold else "exposed",
+            }
+        )
+    return {"residues": residues}

package/src/ai_structural_biology_scientist/protein_docking_score.py

@@ -0,0 +1,104 @@
+"""Protein docking-score heuristic module (DES-ASTRUCT-030 / REQ-ASTRUCT-030)."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from numbers import Integral
+
+from ai_structural_biology_scientist.validation import fail, is_finite_real, register_validator
+
+_MODULE_NAME = "protein-protein-docking-score"
+_REFERENCE_INTERFACE_AREA_A2 = 800.0
+
+LIMITATION_LABEL_KEY = "protein_docking_score_heuristic_limitation"
+LIMITATION_LABEL_TEXT = {
+    "en": (
+        "Heuristic only: a fixed-formula geometric/compositional complementarity "
+        "score, not a physically accurate protein-protein docking simulation (no "
+        "3D structure, no energy function)."
+    ),
+    "ja": (
+        "ヒューリスティックのみ：固定式の幾何・組成補完性スコアであり、"
+        "物理的に正確なタンパク質間ドッキングシミュレーションではない"
+        "（3D 構造なし、エネルギー関数なし）。"
+    ),
+}
+
+
+def _is_non_negative_int(value) -> bool:
+    return isinstance(value, Integral) and not isinstance(value, bool) and value >= 0
+
+
+def _validate_partner(params: dict, name: str) -> dict:
+    partner = params.get(name)
+    if not isinstance(partner, Mapping):
+        return fail(name, "must be a dict")
+    for key in ("hydrophobic_count", "charged_count"):
+        if key not in partner:
+            return fail(f"{name}.{key}", "is required")
+        if not _is_non_negative_int(partner[key]):
+            return fail(f"{name}.{key}", "must be a finite non-negative integer")
+    return {"ok": True}
+
+
+def _protein_docking_score_validator(params: dict) -> dict:
+    """DES-ASTRUCT-002 registered atomic validator for this module."""
+    for name in ("partner_a", "partner_b"):
+        if name not in params:
+            return fail(name, "is required")
+        partner_validation = _validate_partner(params, name)
+        if not partner_validation["ok"]:
+            return partner_validation
+
+    interface_area_a2 = params.get("interface_area_A2")
+    if not is_finite_real(interface_area_a2) or interface_area_a2 <= 0:
+        return fail("interface_area_A2", "must be > 0")
+
+    return {"ok": True}
+
+
+register_validator(_MODULE_NAME, _protein_docking_score_validator)
+
+
+# @id CODE-ASTRUCT-030
+# @implements REQ-ASTRUCT-030
+# @design DES-ASTRUCT-030
+def run_protein_docking_score(
+    partner_a: dict,
+    partner_b: dict,
+    interface_area_A2: float,
+) -> dict:
+    """Compute the fixed-formula protein docking-score heuristic."""
+    validation = _protein_docking_score_validator(
+        {
+            "partner_a": partner_a,
+            "partner_b": partner_b,
+            "interface_area_A2": interface_area_A2,
+        }
+    )
+    if not validation["ok"]:
+        raise ValueError("parameters must already be validated by the handler wrapper")
+
+    size_term = min(
+        1.0,
+        max(
+            0.0,
+            1.0
+            - abs(interface_area_A2 - _REFERENCE_INTERFACE_AREA_A2) / _REFERENCE_INTERFACE_AREA_A2,
+        ),
+    )
+    hydrophobic_complementarity = min(
+        partner_a["hydrophobic_count"], partner_b["hydrophobic_count"]
+    ) / max(1, partner_a["hydrophobic_count"] + partner_b["hydrophobic_count"])
+    charge_complementarity = min(partner_a["charged_count"], partner_b["charged_count"]) / max(
+        1, partner_a["charged_count"] + partner_b["charged_count"]
+    )
+    score = 0.5 * size_term + 0.25 * hydrophobic_complementarity + 0.25 * charge_complementarity
+
+    return {
+        "size_term": size_term,
+        "hydrophobic_complementarity": hydrophobic_complementarity,
+        "charge_complementarity": charge_complementarity,
+        "score": score,
+        "limitation_label_key": LIMITATION_LABEL_KEY,
+    }