jupytermind 0.3.0

package/src/ai_genomics_scientist/sequence_features.py

@@ -0,0 +1,111 @@
+"""Sequence feature analysis module (DES-AGENOM-010 / REQ-AGENOM-010)."""
+
+from __future__ import annotations
+
+from ai_genomics_scientist.validation import (
+    fail,
+    ok,
+    register_batch_item_validator,
+    validate_batch_item,
+)
+
+_MODULE_NAME = "sequence-features"
+_DNA_BASES = frozenset({"A", "C", "G", "T"})
+_STOP_CODONS = frozenset({"TAA", "TAG", "TGA"})
+_SEQUENCE_CONSTRAINT = "must be a non-empty uppercase DNA string over {A,C,G,T} with length >= 3"
+
+
+def _is_valid_dna_sequence(sequence: str, *, min_length: int) -> bool:
+    return (
+        isinstance(sequence, str)
+        and len(sequence) >= min_length
+        and sequence.isupper()
+        and set(sequence).issubset(_DNA_BASES)
+    )
+
+
+def _sequence_features_batch_item_validator(item_params: dict) -> dict:
+    """DES-AGENOM-002 registered per-item validator for this module."""
+    sequence = item_params.get("sequence")
+    if not _is_valid_dna_sequence(sequence, min_length=3):
+        return fail("sequence", _SEQUENCE_CONSTRAINT)
+    return ok()
+
+
+register_batch_item_validator(_MODULE_NAME, _sequence_features_batch_item_validator)
+
+
+def _find_longest_orf(sequence: str) -> dict | None:
+    best_orf: dict | None = None
+    best_length = -1
+
+    for frame in range(3):
+        for start_index in range(frame, len(sequence) - 2, 3):
+            if sequence[start_index : start_index + 3] != "ATG":
+                continue
+            for stop_index in range(start_index + 3, len(sequence) - 2, 3):
+                codon = sequence[stop_index : stop_index + 3]
+                if codon not in _STOP_CODONS:
+                    continue
+                orf_length = stop_index + 3 - start_index
+                candidate = {
+                    "frame": frame,
+                    "start_index": start_index,
+                    "length": orf_length,
+                }
+                if orf_length > best_length or (
+                    orf_length == best_length
+                    and best_orf is not None
+                    and (frame, start_index) < (best_orf["frame"], best_orf["start_index"])
+                ):
+                    best_orf = candidate
+                    best_length = orf_length
+                break
+
+    return best_orf
+
+
+def _count_codons(sequence: str, longest_orf: dict | None) -> dict[str, int]:
+    if longest_orf is None:
+        return {}
+
+    start = longest_orf["start_index"]
+    stop = start + longest_orf["length"]
+    counts: dict[str, int] = {}
+    for index in range(start, stop, 3):
+        codon = sequence[index : index + 3]
+        counts[codon] = counts.get(codon, 0) + 1
+    return counts
+
+
+# @id CODE-AGENOM-010
+# @implements REQ-AGENOM-010
+# @design DES-AGENOM-010
+def run_sequence_features(sequences: list[str]) -> list[dict]:
+    """Compute fixed sequence features for each valid DNA string in ``sequences``."""
+    results: list[dict] = []
+
+    for sequence in sequences:
+        validation = validate_batch_item(_MODULE_NAME, {"sequence": sequence})
+        if not validation["ok"]:
+            results.append(
+                {
+                    "sequence": sequence,
+                    "ok": False,
+                    "parameter": validation["parameter"],
+                    "constraint": validation["constraint"],
+                }
+            )
+            continue
+
+        longest_orf = _find_longest_orf(sequence)
+        results.append(
+            {
+                "length": len(sequence),
+                "gc_content": (sequence.count("G") + sequence.count("C")) / len(sequence),
+                "longest_orf": longest_orf,
+                "codon_usage": _count_codons(sequence, longest_orf),
+            }
+        )
+
+    return results

package/src/ai_genomics_scientist/splice_site_scoring.py

@@ -0,0 +1,66 @@
+"""Splice-site strength heuristic module (DES-AGENOM-030 / REQ-AGENOM-030)."""
+
+from __future__ import annotations
+
+import math
+
+from ai_genomics_scientist.validation import fail, ok, register_validator
+
+_MODULE_NAME = "splice-site-strength"
+_DNA_BASES = frozenset({"A", "C", "G", "T"})
+
+LIMITATION_LABEL_TEXT = {
+    "en": (
+        "Heuristic only: a fixed illustrative position-weight scoring scheme, not a "
+        "validated splice-site predictor (not SpliceAI, not based on real "
+        "splice-site frequency data)."
+    ),
+    "ja": (
+        "ヒューリスティックのみ：これは固定された例示用の"
+        " position-weight スコアリング方式であり、検証済みのスプライス"
+        "部位予測器ではない（SpliceAI ではなく、実際のスプライス部位"
+        "頻度データにも基づかない）。"
+    ),
+}
+
+_PFM = (
+    {"A": 0.30, "C": 0.20, "G": 0.25, "T": 0.25},
+    {"A": 0.60, "C": 0.15, "G": 0.15, "T": 0.10},
+    {"A": 0.15, "C": 0.15, "G": 0.60, "T": 0.10},
+    {"A": 0.00, "C": 0.00, "G": 1.00, "T": 0.00},
+    {"A": 0.00, "C": 0.00, "G": 0.00, "T": 1.00},
+    {"A": 0.55, "C": 0.05, "G": 0.35, "T": 0.05},
+    {"A": 0.70, "C": 0.10, "G": 0.10, "T": 0.10},
+    {"A": 0.08, "C": 0.05, "G": 0.80, "T": 0.07},
+    {"A": 0.15, "C": 0.20, "G": 0.20, "T": 0.45},
+)
+
+
+def _is_dna_string(value: object) -> bool:
+    return isinstance(value, str) and value.isupper() and value and set(value).issubset(_DNA_BASES)
+
+
+def _splice_site_validator(params: dict) -> dict:
+    """DES-AGENOM-002 registered atomic validator for this module."""
+    window = params.get("window")
+    if not _is_dna_string(window):
+        return fail("window", "must be a non-empty uppercase DNA string over {A,C,G,T}")
+    if len(window) != 9:
+        return fail("window", "must be exactly 9 characters")
+    if window[3:5] != "GT":
+        return fail("window", "position 0,+1 must be the canonical GT dinucleotide")
+    return ok()
+
+
+register_validator(_MODULE_NAME, _splice_site_validator)
+
+
+# @id CODE-AGENOM-030
+# @implements REQ-AGENOM-030
+# @design DES-AGENOM-030
+def run_splice_site_scoring(window: str) -> dict:
+    """Score a validated 9-base donor-site window with the fixed illustrative PFM."""
+    score_bits = 0.0
+    for index, base in enumerate(window):
+        score_bits += math.log2(_PFM[index][base] / 0.25)
+    return {"window": window, "score_bits": score_bits, "canonical_site": True}

package/src/ai_genomics_scientist/validation.py

@@ -0,0 +1,83 @@
+"""Shared parameter & validity validator (DES-AGENOM-002 / REQ-AGENOM-003)."""
+
+from __future__ import annotations
+
+import importlib
+from collections.abc import Callable, Mapping
+from typing import Any
+
+ValidationResult = dict[str, Any]
+ValidatorFn = Callable[[dict[str, Any]], ValidationResult]
+BatchItemValidatorFn = Callable[[dict[str, Any]], ValidationResult]
+
+_REGISTRY: dict[str, ValidatorFn] = {}
+_BATCH_ITEM_REGISTRY: dict[str, BatchItemValidatorFn] = {}
+_VALIDATOR_MODULES = {
+    "sequence-features": "ai_genomics_scientist.sequence_features",
+    "variant-effect-annotation": "ai_genomics_scientist.variant_effect",
+    "splice-site-strength": "ai_genomics_scientist.splice_site_scoring",
+    "gene-set-enrichment": "ai_genomics_scientist.gene_set_enrichment",
+    "pairwise-sequence-alignment": "ai_genomics_scientist.sequence_alignment",
+    "differential-expression": "ai_genomics_scientist.differential_expression",
+    "variant-pathogenicity": "ai_genomics_scientist.variant_pathogenicity",
+}
+
+
+def ok() -> ValidationResult:
+    return {"ok": True}
+
+
+def fail(parameter: str, constraint: str) -> ValidationResult:
+    return {"ok": False, "parameter": parameter, "constraint": constraint}
+
+
+def _ensure_validator_registered(module_name: str) -> None:
+    if module_name in _REGISTRY and module_name in _BATCH_ITEM_REGISTRY:
+        return
+    module_path = _VALIDATOR_MODULES.get(module_name)
+    if module_path is not None:
+        importlib.import_module(module_path)
+
+
+# @id CODE-AGENOM-002
+# @implements REQ-AGENOM-003
+# @design DES-AGENOM-002
+def register_validator(module_name: str, validator: ValidatorFn) -> None:
+    """Register ``module_name``'s atomic validator."""
+    _REGISTRY[module_name] = validator
+
+
+# @id CODE-AGENOM-003
+# @implements REQ-AGENOM-003
+# @design DES-AGENOM-002
+def validate_parameters(module_name: str, params: dict[str, Any]) -> ValidationResult:
+    """Dispatch to ``module_name``'s registered atomic validator."""
+    _ensure_validator_registered(module_name)
+    validator = _REGISTRY.get(module_name)
+    if validator is None:
+        return fail("module", f"no validator registered for module '{module_name}'")
+    if not isinstance(params, Mapping):
+        return fail("params", "must be a dict")
+    return validator(dict(params))
+
+
+# @id CODE-AGENOM-004
+# @implements REQ-AGENOM-003
+# @design DES-AGENOM-002
+def register_batch_item_validator(module_name: str, validator: BatchItemValidatorFn) -> None:
+    """Register ``module_name``'s per-item validator."""
+    _BATCH_ITEM_REGISTRY[module_name] = validator
+
+
+# @id CODE-AGENOM-005
+# @implements REQ-AGENOM-003
+# @design DES-AGENOM-002
+def validate_batch_item(module_name: str, item_params: dict[str, Any]) -> ValidationResult:
+    """Dispatch to ``module_name``'s registered per-item validator."""
+    _ensure_validator_registered(module_name)
+    validator = _BATCH_ITEM_REGISTRY.get(module_name)
+    if validator is None:
+        return fail("module", f"no batch-item validator registered for module '{module_name}'")
+    if not isinstance(item_params, Mapping):
+        return fail("params", "must be a dict")
+    return validator(dict(item_params))

package/src/ai_genomics_scientist/variant_effect.py

@@ -0,0 +1,147 @@
+"""Variant effect heuristic annotation module (DES-AGENOM-020 / REQ-AGENOM-020)."""
+
+from __future__ import annotations
+
+from numbers import Integral
+
+from ai_genomics_scientist.validation import fail, ok, register_validator
+
+_MODULE_NAME = "variant-effect-annotation"
+_DNA_BASES = frozenset({"A", "C", "G", "T"})
+_STOP_REFERENCE_CONSTRAINT = "stop-reference codons must mutate to a non-stop codon"
+
+_STANDARD_GENETIC_CODE = {
+    "TTT": "F",
+    "TTC": "F",
+    "TTA": "L",
+    "TTG": "L",
+    "TCT": "S",
+    "TCC": "S",
+    "TCA": "S",
+    "TCG": "S",
+    "TAT": "Y",
+    "TAC": "Y",
+    "TAA": "*",
+    "TAG": "*",
+    "TGT": "C",
+    "TGC": "C",
+    "TGA": "*",
+    "TGG": "W",
+    "CTT": "L",
+    "CTC": "L",
+    "CTA": "L",
+    "CTG": "L",
+    "CCT": "P",
+    "CCC": "P",
+    "CCA": "P",
+    "CCG": "P",
+    "CAT": "H",
+    "CAC": "H",
+    "CAA": "Q",
+    "CAG": "Q",
+    "CGT": "R",
+    "CGC": "R",
+    "CGA": "R",
+    "CGG": "R",
+    "ATT": "I",
+    "ATC": "I",
+    "ATA": "I",
+    "ATG": "M",
+    "ACT": "T",
+    "ACC": "T",
+    "ACA": "T",
+    "ACG": "T",
+    "AAT": "N",
+    "AAC": "N",
+    "AAA": "K",
+    "AAG": "K",
+    "AGT": "S",
+    "AGC": "S",
+    "AGA": "R",
+    "AGG": "R",
+    "GTT": "V",
+    "GTC": "V",
+    "GTA": "V",
+    "GTG": "V",
+    "GCT": "A",
+    "GCC": "A",
+    "GCA": "A",
+    "GCG": "A",
+    "GAT": "D",
+    "GAC": "D",
+    "GAA": "E",
+    "GAG": "E",
+    "GGT": "G",
+    "GGC": "G",
+    "GGA": "G",
+    "GGG": "G",
+}
+
+
+def _is_dna_string(value: object, *, length: int) -> bool:
+    return (
+        isinstance(value, str)
+        and len(value) == length
+        and value.isupper()
+        and set(value).issubset(_DNA_BASES)
+    )
+
+
+def _translate_codon(codon: str) -> str:
+    return _STANDARD_GENETIC_CODE[codon]
+
+
+def _variant_effect_validator(params: dict) -> dict:
+    """DES-AGENOM-002 registered atomic validator for this module."""
+    ref_codon = params.get("ref_codon")
+    position = params.get("position")
+    alt_base = params.get("alt_base")
+
+    if not _is_dna_string(ref_codon, length=3):
+        return fail("ref_codon", "must be exactly 3 uppercase DNA bases over {A,C,G,T}")
+    if (
+        not isinstance(position, Integral)
+        or isinstance(position, bool)
+        or position not in {0, 1, 2}
+    ):
+        return fail("position", "must be an integer in {0,1,2}")
+    if not _is_dna_string(alt_base, length=1):
+        return fail("alt_base", "must be exactly 1 uppercase DNA base over {A,C,G,T}")
+    if alt_base == ref_codon[position]:
+        return fail("alt_base", "alt_base must differ from the reference base at position")
+
+    alt_codon = ref_codon[:position] + alt_base + ref_codon[position + 1 :]
+    if _translate_codon(ref_codon) == "*" and _translate_codon(alt_codon) == "*":
+        return fail("ref_codon", _STOP_REFERENCE_CONSTRAINT)
+
+    return ok()
+
+
+register_validator(_MODULE_NAME, _variant_effect_validator)
+
+
+def _classify_effect(ref_amino_acid: str, alt_amino_acid: str) -> str:
+    if ref_amino_acid == "*" and alt_amino_acid != "*":
+        return "readthrough"
+    if ref_amino_acid != "*" and alt_amino_acid == "*":
+        return "nonsense"
+    if ref_amino_acid == alt_amino_acid:
+        return "synonymous"
+    return "missense"
+
+
+# @id CODE-AGENOM-020
+# @implements REQ-AGENOM-020
+# @design DES-AGENOM-020
+def run_variant_effect(ref_codon: str, position: int, alt_base: str) -> dict:
+    """Annotate a single-codon substitution under the standard genetic code."""
+    alt_codon = ref_codon[:position] + alt_base + ref_codon[position + 1 :]
+    ref_amino_acid = _translate_codon(ref_codon)
+    alt_amino_acid = _translate_codon(alt_codon)
+    return {
+        "ref_codon": ref_codon,
+        "alt_codon": alt_codon,
+        "ref_amino_acid": ref_amino_acid,
+        "alt_amino_acid": alt_amino_acid,
+        "effect": _classify_effect(ref_amino_acid, alt_amino_acid),
+    }

package/src/ai_genomics_scientist/variant_pathogenicity.py

@@ -0,0 +1,125 @@
+"""Variant pathogenicity heuristic module (DES-AGENOM-070 / REQ-AGENOM-070)."""
+
+from __future__ import annotations
+
+from ai_genomics_scientist.validation import fail, ok, register_validator
+
+_MODULE_NAME = "variant-pathogenicity"
+
+_AMINO_ACID_ORDER = [
+    "A",
+    "R",
+    "N",
+    "D",
+    "C",
+    "Q",
+    "E",
+    "G",
+    "H",
+    "I",
+    "L",
+    "K",
+    "M",
+    "F",
+    "P",
+    "S",
+    "T",
+    "W",
+    "Y",
+    "V",
+]
+_STANDARD_AMINO_ACIDS = frozenset(_AMINO_ACID_ORDER)
+
+# Standard published BLOSUM62 substitution matrix (symmetric, 20x20),
+# row/column order matching _AMINO_ACID_ORDER exactly, per ADR-0108.
+_BLOSUM62_ROWS = [
+    [4, -1, -2, -2, 0, -1, -1, 0, -2, -1, -1, -1, -1, -2, -1, 1, 0, -3, -2, 0],
+    [-1, 5, 0, -2, -3, 1, 0, -2, 0, -3, -2, 2, -1, -3, -2, -1, -1, -3, -2, -3],
+    [-2, 0, 6, 1, -3, 0, 0, 0, 1, -3, -3, 0, -2, -3, -2, 1, 0, -4, -2, -3],
+    [-2, -2, 1, 6, -3, 0, 2, -1, -1, -3, -4, -1, -3, -3, -1, 0, -1, -4, -3, -3],
+    [0, -3, -3, -3, 9, -3, -4, -3, -3, -1, -1, -3, -1, -2, -3, -1, -1, -2, -2, -1],
+    [-1, 1, 0, 0, -3, 5, 2, -2, 0, -3, -2, 1, 0, -3, -1, 0, -1, -2, -1, -2],
+    [-1, 0, 0, 2, -4, 2, 5, -2, 0, -3, -3, 1, -2, -3, -1, 0, -1, -3, -2, -2],
+    [0, -2, 0, -1, -3, -2, -2, 6, -2, -4, -4, -2, -3, -3, -2, 0, -2, -2, -3, -3],
+    [-2, 0, 1, -1, -3, 0, 0, -2, 8, -3, -3, -1, -2, -1, -2, -1, -2, -2, 2, -3],
+    [-1, -3, -3, -3, -1, -3, -3, -4, -3, 4, 2, -3, 1, 0, -3, -2, -1, -3, -1, 3],
+    [-1, -2, -3, -4, -1, -2, -3, -4, -3, 2, 4, -2, 2, 0, -3, -2, -1, -2, -1, 1],
+    [-1, 2, 0, -1, -3, 1, 1, -2, -1, -3, -2, 5, -1, -3, -1, 0, -1, -3, -2, -2],
+    [-1, -1, -2, -3, -1, 0, -2, -3, -2, 1, 2, -1, 5, 0, -2, -1, -1, -1, -1, 1],
+    [-2, -3, -3, -3, -2, -3, -3, -3, -1, 0, 0, -3, 0, 6, -4, -2, -2, 1, 3, -1],
+    [-1, -2, -2, -1, -3, -1, -1, -2, -2, -3, -3, -1, -2, -4, 7, -1, -1, -4, -3, -2],
+    [1, -1, 1, 0, -1, 0, 0, 0, -1, -2, -2, 0, -1, -2, -1, 4, 1, -3, -2, -2],
+    [0, -1, 0, -1, -1, -1, -1, -2, -2, -1, -1, -1, -1, -2, -1, 1, 5, -2, -2, 0],
+    [-3, -3, -4, -4, -2, -2, -3, -2, -2, -3, -2, -3, -1, 1, -4, -3, -2, 11, 2, -3],
+    [-2, -2, -2, -3, -2, -1, -2, -3, 2, -1, -1, -2, -1, 3, -3, -2, -2, 2, 7, -1],
+    [0, -3, -3, -3, -1, -2, -2, -3, -3, 3, 1, -2, 1, -1, -2, -2, 0, -3, -1, 4],
+]
+_BLOSUM62 = {
+    (row_aa, col_aa): _BLOSUM62_ROWS[row_index][col_index]
+    for row_index, row_aa in enumerate(_AMINO_ACID_ORDER)
+    for col_index, col_aa in enumerate(_AMINO_ACID_ORDER)
+}
+
+_TIER_THRESHOLDS = [
+    (0.3, "benign"),
+    (0.5, "likely_benign"),
+    (0.7, "uncertain_significance"),
+    (0.85, "likely_pathogenic"),
+]
+
+
+def _variant_pathogenicity_validator(params: dict) -> dict:
+    """DES-AGENOM-002 registered atomic validator for this module."""
+    ref_aa = params.get("ref_aa")
+    alt_aa = params.get("alt_aa")
+    conservation_score = params.get("conservation_score")
+    in_functional_domain = params.get("in_functional_domain")
+
+    if not isinstance(ref_aa, str) or ref_aa not in _STANDARD_AMINO_ACIDS:
+        return fail("ref_aa", "must be one of the 20 standard single-letter amino acid codes")
+    if not isinstance(alt_aa, str) or alt_aa not in _STANDARD_AMINO_ACIDS:
+        return fail("alt_aa", "must be one of the 20 standard single-letter amino acid codes")
+    if alt_aa == ref_aa:
+        return fail("alt_aa", "alt_aa must differ from ref_aa")
+    if (
+        not isinstance(conservation_score, float)
+        or isinstance(conservation_score, bool)
+        or not (0 <= conservation_score <= 1)
+    ):
+        return fail("conservation_score", "must be a float in the closed interval [0, 1]")
+    if not isinstance(in_functional_domain, bool):
+        return fail("in_functional_domain", "must be a boolean")
+
+    return ok()
+
+
+register_validator(_MODULE_NAME, _variant_pathogenicity_validator)
+
+
+def _classify(score: float) -> str:
+    for threshold, tier in _TIER_THRESHOLDS:
+        if score < threshold:
+            return tier
+    return "pathogenic"
+
+
+# @id CODE-AGENOM-070
+# @implements REQ-AGENOM-070
+# @design DES-AGENOM-070
+def run_variant_pathogenicity(
+    ref_aa: str, alt_aa: str, conservation_score: float, in_functional_domain: bool
+) -> dict:
+    """Compute the fixed BLOSUM62 + weighted-sum pathogenicity heuristic score."""
+    blosum_score = _BLOSUM62[(ref_aa, alt_aa)]
+    dissimilarity = min(max((3 - blosum_score) / 7, 0.0), 1.0)
+    domain_bonus = 0.15 if in_functional_domain else 0.0
+    pathogenicity_score = min(
+        max(0.5 * dissimilarity + 0.35 * conservation_score + domain_bonus, 0.0), 1.0
+    )
+    return {
+        "ref_aa": ref_aa,
+        "alt_aa": alt_aa,
+        "blosum_score": blosum_score,
+        "pathogenicity_score": pathogenicity_score,
+        "classification": _classify(pathogenicity_score),
+    }

package/src/ai_materials_scientist/calphad.py

@@ -0,0 +1,117 @@
+"""Simplified binary CALPHAD phase diagram module (DES-AIMS-070 / REQ-AIMS-070)."""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.optimize import brentq
+
+from ai_materials_scientist.evidence import record_run
+from ai_materials_scientist.validation import register_validator, validate_parameters
+
+_MODULE_NAME = "calphad"
+_R = 8.314
+_ROOT_BRACKET_EPSILON = 1e-9
+
+
+def _free_energy_of_mixing(x: np.ndarray, omega: float, temperature: float) -> np.ndarray:
+    return _R * temperature * (x * np.log(x) + (1 - x) * np.log(1 - x)) + omega * x * (1 - x)
+
+
+def _coexistence_residual(x: float, omega: float, temperature: float) -> float:
+    return np.log(x / (1 - x)) + (omega / (_R * temperature)) * (1 - 2 * x)
+
+
+def _calphad_validator(params: dict) -> dict:
+    """DES-AIMS-002 registered validator for module_name='calphad'."""
+    omega = params["omega"]
+    temperature = params["temperature"]
+    composition_grid = params["composition_grid"]
+
+    if not np.isfinite(omega) or omega <= 0:
+        return {"ok": False, "parameter": "omega", "constraint": "omega > 0"}
+    if not np.isfinite(temperature) or temperature <= 0:
+        return {"ok": False, "parameter": "temperature", "constraint": "temperature > 0"}
+
+    t_c = omega / (2 * _R)
+    if temperature >= t_c:
+        return {
+            "ok": False,
+            "parameter": "temperature",
+            "constraint": "temperature < consolute_temperature (omega / (2 * R))",
+        }
+
+    composition_grid = np.asarray(composition_grid, dtype=np.float64)
+    if not np.all(np.isfinite(composition_grid)):
+        return {
+            "ok": False,
+            "parameter": "composition_grid",
+            "constraint": "composition_grid entries must be finite",
+        }
+    if np.any(composition_grid <= 0) or np.any(composition_grid >= 1):
+        return {
+            "ok": False,
+            "parameter": "composition_grid",
+            "constraint": "composition_grid entries must lie in the open interval (0, 1)",
+        }
+    return {"ok": True}
+
+
+register_validator(_MODULE_NAME, _calphad_validator)
+
+
+def _validate(omega: float, temperature: float, composition_grid: np.ndarray) -> None:
+    result = validate_parameters(
+        _MODULE_NAME,
+        {"omega": omega, "temperature": temperature, "composition_grid": composition_grid},
+    )
+    if not result["ok"]:
+        raise ValueError(f"{result['parameter']}: {result['constraint']}")
+
+
+# @id CODE-AIMS-070
+# @implements REQ-AIMS-070 REQ-AIMS-003
+# @design DES-AIMS-070
+def run_calphad(omega: float, temperature: float, composition_grid: np.ndarray) -> dict:
+    """Compute the regular-solution G_mix curve and the two binodal compositions."""
+    composition_grid = np.asarray(composition_grid, dtype=np.float64)
+    _validate(omega, temperature, composition_grid)
+
+    free_energy_curve = _free_energy_of_mixing(composition_grid, omega, temperature)
+
+    x_alpha = brentq(
+        _coexistence_residual,
+        _ROOT_BRACKET_EPSILON,
+        0.5 - _ROOT_BRACKET_EPSILON,
+        args=(omega, temperature),
+    )
+    x_beta = brentq(
+        _coexistence_residual,
+        0.5 + _ROOT_BRACKET_EPSILON,
+        1.0 - _ROOT_BRACKET_EPSILON,
+        args=(omega, temperature),
+    )
+
+    return {
+        "x_alpha": x_alpha,
+        "x_beta": x_beta,
+        "free_energy_curve": free_energy_curve,
+    }
+
+
+# @id CODE-AIMS-900
+# @implements REQ-AIMS-070 REQ-AIMS-004 REQ-AIMS-005
+# @design DES-AIMS-070
+def run_calphad_with_evidence(**kwargs) -> dict:
+    """Run the CALPHAD module and wrap the result as a reproducible RunRecord."""
+    result = run_calphad(**kwargs)
+    return record_run(
+        module_name=_MODULE_NAME,
+        unit_system="J-per-mol",
+        params={k: v for k, v in kwargs.items() if k != "composition_grid"},
+        arrays={
+            "x_alpha": np.array([result["x_alpha"]], dtype=np.float64),
+            "x_beta": np.array([result["x_beta"]], dtype=np.float64),
+            "free_energy_curve": np.asarray(result["free_energy_curve"], dtype=np.float64),
+        },
+        seed=None,
+    )