@moleculeagora/cli 0.1.0

package/dist/python-v1/assertion-set-evaluation.py

@@ -0,0 +1,879 @@
+import csv
+import json
+import math
+import re
+import tempfile
+from pathlib import Path
+
+from agora_runtime import (
+    fail_runtime,
+    load_json_file,
+    load_runtime_context,
+    resolve_evaluation_artifact,
+    reject_submission,
+    resolve_scoring_asset,
+    resolve_submission_artifact,
+    safe_extract_zip,
+    write_score,
+)
+
+FIELD_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+MOLECULE_TABLE_SCAN_MAX_ROWS = 1000
+MORGAN_RADIUS = 2
+MORGAN_BITS = 2048
+
+
+def require_string(value, label):
+    if not isinstance(value, str) or not value.strip():
+        fail_runtime(f"{label} must be a non-empty string.")
+    return value.strip()
+
+
+def require_object(value, label):
+    if not isinstance(value, dict):
+        fail_runtime(f"{label} must be a JSON object.")
+    return value
+
+
+def require_list(value, label):
+    if not isinstance(value, list):
+        fail_runtime(f"{label} must be an array.")
+    return value
+
+
+def require_number(value, label):
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        fail_runtime(f"{label} must be a finite number.")
+    number = float(value)
+    if not math.isfinite(number):
+        fail_runtime(f"{label} must be a finite number.")
+    return number
+
+
+def require_positive_number(value, label):
+    number = require_number(value, label)
+    if number <= 0:
+        fail_runtime(f"{label} must be positive.")
+    return number
+
+
+def require_nonnegative_number(value, label):
+    number = require_number(value, label)
+    if number < 0:
+        fail_runtime(f"{label} must be nonnegative.")
+    return number
+
+
+def require_positive_int(value, label):
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        fail_runtime(f"{label} must be a positive integer.")
+    return value
+
+
+def require_nonnegative_int(value, label):
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        fail_runtime(f"{label} must be a nonnegative integer.")
+    return value
+
+
+def require_unit_interval(value, label):
+    number = require_number(value, label)
+    if number < 0 or number > 1:
+        fail_runtime(f"{label} must be between 0 and 1.")
+    return number
+
+
+def require_json_scalar(value, label):
+    if (
+        value is None
+        or isinstance(value, str)
+        or isinstance(value, bool)
+        or (
+            isinstance(value, (int, float))
+            and not isinstance(value, bool)
+            and math.isfinite(float(value))
+        )
+    ):
+        return value
+    fail_runtime(f"{label} must be a JSON scalar.")
+
+
+def normalize_member_path(value, label):
+    path_value = require_string(value, label)
+    path_parts = path_value.split("/")
+    member_path = Path(path_value)
+    if member_path.is_absolute() or any(
+        part in {"", ".", ".."} for part in path_parts
+    ):
+        fail_runtime(f"{label} must be a safe relative archive path.")
+    return path_value
+
+
+def resolve_member(root, path_value, label):
+    relative_path = normalize_member_path(path_value, label)
+    root_path = root.resolve()
+    target = (root_path / relative_path).resolve()
+    try:
+        target.relative_to(root_path)
+    except ValueError:
+        fail_runtime(f"{label} must stay inside the extracted archive root.")
+    return target
+
+
+def load_compiled_config(path):
+    try:
+        return load_json_file(path, label="compiled_config")
+    except RuntimeError as error:
+        fail_runtime(str(error))
+
+
+def read_text(path, label):
+    try:
+        return True, path.read_text(encoding="utf-8"), None
+    except FileNotFoundError:
+        return False, None, f"{label} is missing."
+    except UnicodeDecodeError:
+        return False, None, f"{label} is not valid UTF-8 text."
+    except OSError as error:
+        return False, None, f"{label} could not be read: {error}."
+
+
+def load_json_member(path, label):
+    try:
+        return True, json.loads(path.read_text(encoding="utf-8")), None
+    except FileNotFoundError:
+        return False, None, f"{label} is missing."
+    except UnicodeDecodeError:
+        return False, None, f"{label} is not valid UTF-8 text."
+    except json.JSONDecodeError as error:
+        return False, None, f"{label} is not valid JSON: {error.msg}."
+    except OSError as error:
+        return False, None, f"{label} could not be read: {error}."
+
+
+def parse_json_path(path_value, label):
+    path = require_string(path_value, label)
+    if path == "$":
+        return []
+    if not path.startswith("$"):
+        fail_runtime(f"{label} must start with $.")
+    tokens = []
+    index = 1
+    while index < len(path):
+        if path[index] == ".":
+            index += 1
+            match = FIELD_RE.match(path, index)
+            if not match:
+                fail_runtime(f"{label} contains an invalid field segment.")
+            tokens.append(("field", match.group(0)))
+            index = match.end()
+            continue
+        if path[index] == "[":
+            end = path.find("]", index)
+            if end == -1:
+                fail_runtime(f"{label} contains an unterminated array index.")
+            raw_index = path[index + 1 : end]
+            if not raw_index.isdigit() or (
+                len(raw_index) > 1 and raw_index.startswith("0")
+            ):
+                fail_runtime(f"{label} contains an invalid array index.")
+            tokens.append(("index", int(raw_index)))
+            index = end + 1
+            continue
+        fail_runtime(f"{label} contains an unsupported path segment.")
+    return tokens
+
+
+def extract_json_path(data, tokens):
+    current = data
+    for kind, token in tokens:
+        if kind == "field":
+            if not isinstance(current, dict) or token not in current:
+                return False, None, f"JSON field {token} is missing."
+            current = current[token]
+            continue
+        if not isinstance(current, list) or token >= len(current):
+            return False, None, f"JSON array index {token} is missing."
+        current = current[token]
+    return True, current, None
+
+
+def json_scalar_equal(actual, expected):
+    if expected is None or isinstance(expected, bool):
+        return actual is expected
+    if isinstance(expected, str):
+        return isinstance(actual, str) and actual == expected
+    if isinstance(expected, (int, float)) and not isinstance(expected, bool):
+        return (
+            isinstance(actual, (int, float))
+            and not isinstance(actual, bool)
+            and float(actual) == float(expected)
+        )
+    return False
+
+
+def read_csv_cell(path, row_number, column, label):
+    try:
+        with path.open("r", encoding="utf-8", newline="") as handle:
+            reader = csv.DictReader(handle)
+            if reader.fieldnames is None:
+                return False, None, f"{label} is missing a header row."
+            if column not in reader.fieldnames:
+                return False, None, f"{label} is missing CSV column {column}."
+            for current_row, row in enumerate(reader, start=1):
+                if current_row == row_number:
+                    return True, row.get(column, ""), None
+    except FileNotFoundError:
+        return False, None, f"{label} is missing."
+    except UnicodeDecodeError:
+        return False, None, f"{label} is not valid UTF-8 text."
+    except csv.Error as error:
+        return False, None, f"{label} is not valid CSV: {error}."
+    except OSError as error:
+        return False, None, f"{label} could not be read: {error}."
+    return False, None, f"{label} is missing CSV row {row_number}."
+
+
+def read_csv_rows(path, label, side):
+    try:
+        with path.open("r", encoding="utf-8", newline="") as handle:
+            reader = csv.DictReader(handle)
+            if reader.fieldnames is None:
+                side_failure(side, f"{label} is missing a header row.")
+            rows = []
+            for index, row in enumerate(reader):
+                if index >= MOLECULE_TABLE_SCAN_MAX_ROWS:
+                    break
+                rows.append(row)
+    except FileNotFoundError:
+        side_failure(side, f"{label} is missing.")
+    except UnicodeDecodeError:
+        side_failure(side, f"{label} is not valid UTF-8 text.")
+    except csv.Error as error:
+        side_failure(side, f"{label} is not valid CSV: {error}.")
+    except OSError as error:
+        side_failure(side, f"{label} could not be read: {error}.")
+    return reader.fieldnames, rows
+
+
+def compare_number(actual, comparator, expected):
+    if comparator == "eq":
+        return actual == expected
+    if comparator == "neq":
+        return actual != expected
+    if comparator == "lt":
+        return actual < expected
+    if comparator == "lte":
+        return actual <= expected
+    if comparator == "gt":
+        return actual > expected
+    if comparator == "gte":
+        return actual >= expected
+    fail_runtime(f"numeric comparator {comparator} is unsupported.")
+
+
+def to_finite_number(value, label):
+    if isinstance(value, bool) or not isinstance(value, (int, float, str)):
+        return False, None, f"{label} is not numeric."
+    try:
+        number = float(value)
+    except ValueError:
+        return False, None, f"{label} is not numeric."
+    if not math.isfinite(number):
+        return False, None, f"{label} is not finite."
+    return True, number, None
+
+
+def extract_numeric(root, extractor, label):
+    extractor_kind = require_string(extractor.get("kind"), f"{label}.kind")
+    if extractor_kind == "json_path":
+        path = resolve_member(root, extractor.get("path"), f"{label}.path")
+        ok, data, reason = load_json_member(path, f"{label}.path")
+        if not ok:
+            return False, None, reason
+        tokens = parse_json_path(extractor.get("json_path"), f"{label}.json_path")
+        ok, value, reason = extract_json_path(data, tokens)
+        if not ok:
+            return False, None, reason
+        return to_finite_number(value, label)
+    if extractor_kind == "csv_cell":
+        path = resolve_member(root, extractor.get("path"), f"{label}.path")
+        row = require_positive_int(extractor.get("row"), f"{label}.row")
+        column = require_string(extractor.get("column"), f"{label}.column")
+        ok, value, reason = read_csv_cell(path, row, column, f"{label}.path")
+        if not ok:
+            return False, None, reason
+        return to_finite_number(value, label)
+    if extractor_kind == "regex_capture":
+        path = resolve_member(root, extractor.get("path"), f"{label}.path")
+        ok, text, reason = read_text(path, f"{label}.path")
+        if not ok:
+            return False, None, reason
+        pattern = require_string(extractor.get("pattern"), f"{label}.pattern")
+        group = require_positive_int(extractor.get("group"), f"{label}.group")
+        try:
+            match = re.search(pattern, text)
+        except re.error as error:
+            fail_runtime(f"{label}.pattern is not a valid regex: {error}.")
+        if not match:
+            return False, None, f"{label}.pattern did not match."
+        try:
+            value = match.group(group)
+        except IndexError:
+            fail_runtime(f"{label}.group references a missing capture group.")
+        return to_finite_number(value, label)
+    fail_runtime(f"{label}.kind={extractor_kind} is unsupported.")
+
+
+def side_failure(side, message):
+    if side == "candidate":
+        reject_submission(
+            f"Candidate molecule source is invalid: {message}",
+            details={"rejected_side": "candidate"},
+        )
+    if side == "reference":
+        fail_runtime(f"Reference molecule source is invalid: {message}")
+    fail_runtime(f"Unknown molecule source side {side}.")
+
+
+def load_rdkit(label):
+    try:
+        from rdkit import Chem, DataStructs
+        from rdkit.Chem import Descriptors, Lipinski, rdFingerprintGenerator, rdMolDescriptors
+    except ImportError as error:
+        fail_runtime(f"{label} requires RDKit in the selected runtime profile: {error}.")
+    return {
+        "Chem": Chem,
+        "DataStructs": DataStructs,
+        "Descriptors": Descriptors,
+        "Lipinski": Lipinski,
+        "rdFingerprintGenerator": rdFingerprintGenerator,
+        "rdMolDescriptors": rdMolDescriptors,
+    }
+
+
+def select_smiles_from_csv(root, source, label, side):
+    path = resolve_member(root, source.get("path"), f"{label}.path")
+    smiles_column = require_string(source.get("smiles_column"), f"{label}.smiles_column")
+    fieldnames, rows = read_csv_rows(path, f"{label}.path", side)
+    if smiles_column not in fieldnames:
+        side_failure(side, f"{label}.path is missing SMILES column {smiles_column}.")
+
+    has_row_id = "row_id" in source
+    has_row_index = "row_index" in source
+    if has_row_id == has_row_index:
+        fail_runtime(f"{label} must define exactly one of row_id or row_index.")
+
+    if has_row_index:
+        row_index = require_nonnegative_int(source.get("row_index"), f"{label}.row_index")
+        if row_index >= MOLECULE_TABLE_SCAN_MAX_ROWS:
+            fail_runtime(
+                f"{label}.row_index must be less than {MOLECULE_TABLE_SCAN_MAX_ROWS}."
+            )
+        if row_index >= len(rows):
+            side_failure(side, f"{label}.row_index selected missing row {row_index}.")
+        return rows[row_index].get(smiles_column, "")
+
+    row_id = require_object(source.get("row_id"), f"{label}.row_id")
+    row_id_column = require_string(row_id.get("column"), f"{label}.row_id.column")
+    row_id_value = require_string(row_id.get("value"), f"{label}.row_id.value")
+    if row_id_column == smiles_column:
+        fail_runtime(f"{label}.row_id.column must differ from smiles_column.")
+    if row_id_column not in fieldnames:
+        side_failure(side, f"{label}.path is missing row id column {row_id_column}.")
+    matches = [row for row in rows if row.get(row_id_column, "") == row_id_value]
+    if not matches:
+        side_failure(
+            side,
+            f"{label}.row_id selected no row with {row_id_column}={row_id_value!r} within the first {MOLECULE_TABLE_SCAN_MAX_ROWS} rows.",
+        )
+    if len(matches) > 1:
+        side_failure(
+            side,
+            f"{label}.row_id selected duplicate rows with {row_id_column}={row_id_value!r}.",
+        )
+    return matches[0].get(smiles_column, "")
+
+
+def molecule_from_smiles(root, source, label, side):
+    rdkit = load_rdkit(label)
+    smiles = select_smiles_from_csv(root, source, label, side).strip()
+    if not smiles:
+        side_failure(side, f"{label}.smiles_column selected an empty SMILES value.")
+    try:
+        molecule = rdkit["Chem"].MolFromSmiles(smiles, sanitize=True)
+    except Exception as error:
+        side_failure(side, f"{label} SMILES could not be parsed: {error}.")
+    if molecule is None:
+        side_failure(side, f"{label} SMILES could not be parsed with sanitization.")
+    return molecule
+
+
+def molecule_from_mol(root, source, label, side):
+    rdkit = load_rdkit(label)
+    path = resolve_member(root, source.get("path"), f"{label}.path")
+    ok, block, reason = read_text(path, f"{label}.path")
+    if not ok:
+        side_failure(side, reason)
+    try:
+        molecule = rdkit["Chem"].MolFromMolBlock(
+            block,
+            sanitize=True,
+            removeHs=False,
+        )
+    except Exception as error:
+        side_failure(side, f"{label}.path MOL block could not be parsed: {error}.")
+    if molecule is None:
+        side_failure(side, f"{label}.path MOL block could not be parsed with sanitization.")
+    return molecule
+
+
+def molecule_from_sdf(root, source, label, side):
+    rdkit = load_rdkit(label)
+    path = resolve_member(root, source.get("path"), f"{label}.path")
+    record_index = require_nonnegative_int(
+        source.get("record_index"),
+        f"{label}.record_index",
+    )
+    if record_index >= MOLECULE_TABLE_SCAN_MAX_ROWS:
+        fail_runtime(
+            f"{label}.record_index must be less than {MOLECULE_TABLE_SCAN_MAX_ROWS}."
+        )
+    try:
+        supplier = rdkit["Chem"].SDMolSupplier(
+            str(path),
+            sanitize=True,
+            removeHs=False,
+        )
+        molecule = supplier[record_index]
+    except FileNotFoundError:
+        side_failure(side, f"{label}.path is missing.")
+    except IndexError:
+        side_failure(side, f"{label}.record_index selected missing record {record_index}.")
+    except Exception as error:
+        side_failure(side, f"{label}.path SDF could not be parsed: {error}.")
+    if molecule is None:
+        side_failure(side, f"{label}.record_index could not be parsed with sanitization.")
+    return molecule
+
+
+def load_molecule(root, source, label, side):
+    molecule_source = require_object(source, label)
+    source_kind = require_string(molecule_source.get("kind"), f"{label}.kind")
+    if source_kind == "smiles_csv":
+        return molecule_from_smiles(root, molecule_source, label, side)
+    if source_kind == "mol":
+        return molecule_from_mol(root, molecule_source, label, side)
+    if source_kind == "sdf":
+        return molecule_from_sdf(root, molecule_source, label, side)
+    fail_runtime(f"{label}.kind={source_kind} is unsupported.")
+
+
+def canonical_smiles(molecule, label):
+    rdkit = load_rdkit(label)
+    try:
+        return rdkit["Chem"].MolToSmiles(molecule, canonical=True)
+    except Exception as error:
+        fail_runtime(f"{label} canonical SMILES failed: {error}.")
+
+
+def descriptor_value(molecule, descriptor, label):
+    rdkit = load_rdkit(label)
+    try:
+        if descriptor == "mol_wt":
+            return float(rdkit["Descriptors"].MolWt(molecule))
+        if descriptor == "exact_mol_wt":
+            return float(rdkit["Descriptors"].ExactMolWt(molecule))
+        if descriptor == "logp":
+            return float(rdkit["Descriptors"].MolLogP(molecule))
+        if descriptor == "tpsa":
+            return float(rdkit["rdMolDescriptors"].CalcTPSA(molecule))
+        if descriptor == "h_donors":
+            return float(rdkit["Lipinski"].NumHDonors(molecule))
+        if descriptor == "h_acceptors":
+            return float(rdkit["Lipinski"].NumHAcceptors(molecule))
+        if descriptor == "rotatable_bonds":
+            return float(rdkit["Lipinski"].NumRotatableBonds(molecule))
+        if descriptor == "heavy_atom_count":
+            return float(molecule.GetNumHeavyAtoms())
+    except Exception as error:
+        fail_runtime(f"{label} descriptor {descriptor} failed: {error}.")
+    fail_runtime(f"{label}.descriptor={descriptor} is unsupported.")
+
+
+def morgan_fingerprint(molecule, label):
+    rdkit = load_rdkit(label)
+    try:
+        generator = rdkit["rdFingerprintGenerator"].GetMorganGenerator(
+            radius=MORGAN_RADIUS,
+            fpSize=MORGAN_BITS,
+        )
+        return generator.GetFingerprint(molecule)
+    except AttributeError:
+        return rdkit["rdMolDescriptors"].GetMorganFingerprintAsBitVect(
+            molecule,
+            MORGAN_RADIUS,
+            nBits=MORGAN_BITS,
+        )
+    except Exception as error:
+        fail_runtime(f"{label} Morgan fingerprint failed: {error}.")
+
+
+def tanimoto_similarity(candidate_molecule, reference_molecule, label):
+    rdkit = load_rdkit(label)
+    try:
+        candidate_fingerprint = morgan_fingerprint(candidate_molecule, label)
+        reference_fingerprint = morgan_fingerprint(reference_molecule, label)
+        return float(
+            rdkit["DataStructs"].TanimotoSimilarity(
+                candidate_fingerprint,
+                reference_fingerprint,
+            )
+        )
+    except Exception as error:
+        fail_runtime(f"{label} Tanimoto similarity failed: {error}.")
+
+
+def require_reference_root(reference_root, label):
+    if reference_root is None:
+        fail_runtime(f"{label} requires compiled_config.reference_role.")
+    return reference_root
+
+
+def normalize_assertion(value, index):
+    assertion = require_object(value, f"assertion_set.assertions[{index}]")
+    assertion_id = require_string(
+        assertion.get("id"),
+        f"assertion_set.assertions[{index}].id",
+    )
+    assertion_kind = require_string(
+        assertion.get("kind"),
+        f"assertion_set.assertions[{index}].kind",
+    )
+    weight = require_positive_number(
+        assertion.get("weight"),
+        f"assertion_set.assertions[{index}].weight",
+    )
+    return assertion_id, assertion_kind, weight, assertion
+
+
+def evaluate_assertion(candidate_root, reference_root, assertion, index):
+    assertion_id, assertion_kind, weight, raw = normalize_assertion(
+        assertion,
+        index,
+    )
+    label = f"assertion_set.assertions[{index}]"
+
+    if assertion_kind == "file_exists":
+        path = resolve_member(candidate_root, raw.get("path"), f"{label}.path")
+        passed = path.is_file()
+        reason = None if passed else "file is missing."
+    elif assertion_kind == "file_absent":
+        path = resolve_member(candidate_root, raw.get("path"), f"{label}.path")
+        passed = not path.exists()
+        reason = None if passed else "file is present."
+    elif assertion_kind == "text_equals":
+        path = resolve_member(candidate_root, raw.get("path"), f"{label}.path")
+        expected = raw.get("expected")
+        if not isinstance(expected, str):
+            fail_runtime(f"{label}.expected must be a string.")
+        ok, text, reason = read_text(path, f"{label}.path")
+        passed = ok and text == expected
+    elif assertion_kind == "text_regex":
+        path = resolve_member(candidate_root, raw.get("path"), f"{label}.path")
+        pattern = require_string(raw.get("pattern"), f"{label}.pattern")
+        ok, text, reason = read_text(path, f"{label}.path")
+        if ok:
+            try:
+                passed = re.search(pattern, text) is not None
+            except re.error as error:
+                fail_runtime(f"{label}.pattern is not a valid regex: {error}.")
+            reason = None if passed else "regex did not match."
+        else:
+            passed = False
+    elif assertion_kind == "json_path_equals":
+        path = resolve_member(candidate_root, raw.get("path"), f"{label}.path")
+        expected = require_json_scalar(raw.get("expected"), f"{label}.expected")
+        ok, data, reason = load_json_member(path, f"{label}.path")
+        if ok:
+            tokens = parse_json_path(raw.get("json_path"), f"{label}.json_path")
+            ok, actual, reason = extract_json_path(data, tokens)
+        passed = ok and json_scalar_equal(actual, expected)
+        if ok and not passed:
+            reason = "JSON scalar did not equal expected value."
+    elif assertion_kind == "json_path_number_compare":
+        path = resolve_member(candidate_root, raw.get("path"), f"{label}.path")
+        comparator = require_string(raw.get("comparator"), f"{label}.comparator")
+        expected = require_number(raw.get("value"), f"{label}.value")
+        ok, data, reason = load_json_member(path, f"{label}.path")
+        if ok:
+            tokens = parse_json_path(raw.get("json_path"), f"{label}.json_path")
+            ok, actual, reason = extract_json_path(data, tokens)
+        if ok:
+            ok, actual_number, reason = to_finite_number(actual, label)
+        passed = ok and compare_number(actual_number, comparator, expected)
+        if ok and not passed:
+            reason = f"number comparison {comparator} failed."
+    elif assertion_kind == "csv_cell_equals":
+        path = resolve_member(candidate_root, raw.get("path"), f"{label}.path")
+        row = require_positive_int(raw.get("row"), f"{label}.row")
+        column = require_string(raw.get("column"), f"{label}.column")
+        expected = raw.get("expected")
+        if not isinstance(expected, str):
+            fail_runtime(f"{label}.expected must be a string.")
+        ok, value, reason = read_csv_cell(path, row, column, f"{label}.path")
+        passed = ok and value == expected
+        if ok and not passed:
+            reason = "CSV cell did not equal expected value."
+    elif assertion_kind == "numeric_tolerance":
+        extractor = require_object(raw.get("extractor"), f"{label}.extractor")
+        expected = require_number(raw.get("expected"), f"{label}.expected")
+        tolerance = require_nonnegative_number(
+            raw.get("absolute_tolerance"),
+            f"{label}.absolute_tolerance",
+        )
+        ok, actual_number, reason = extract_numeric(candidate_root, extractor, label)
+        passed = ok and abs(actual_number - expected) <= tolerance
+        if ok and not passed:
+            reason = "numeric value exceeded absolute tolerance."
+    elif assertion_kind == "numeric_interval":
+        extractor = require_object(raw.get("extractor"), f"{label}.extractor")
+        minimum = require_number(raw.get("min"), f"{label}.min")
+        maximum = require_number(raw.get("max"), f"{label}.max")
+        if minimum > maximum:
+            fail_runtime(f"{label}.min must be less than or equal to max.")
+        inclusive_min = bool(raw.get("inclusive_min", True))
+        inclusive_max = bool(raw.get("inclusive_max", True))
+        ok, actual_number, reason = extract_numeric(candidate_root, extractor, label)
+        if ok:
+            above_min = (
+                actual_number >= minimum
+                if inclusive_min
+                else actual_number > minimum
+            )
+            below_max = (
+                actual_number <= maximum
+                if inclusive_max
+                else actual_number < maximum
+            )
+            passed = above_min and below_max
+        else:
+            passed = False
+        if ok and not passed:
+            reason = "numeric value was outside the expected interval."
+    elif assertion_kind == "molecule_valid":
+        load_molecule(
+            candidate_root,
+            raw.get("source"),
+            f"{label}.source",
+            "candidate",
+        )
+        passed = True
+        reason = None
+    elif assertion_kind == "molecule_canonical_smiles_equals":
+        candidate_molecule = load_molecule(
+            candidate_root,
+            raw.get("candidate"),
+            f"{label}.candidate",
+            "candidate",
+        )
+        reference_molecule = load_molecule(
+            require_reference_root(reference_root, label),
+            raw.get("reference"),
+            f"{label}.reference",
+            "reference",
+        )
+        candidate_smiles = canonical_smiles(candidate_molecule, f"{label}.candidate")
+        reference_smiles = canonical_smiles(reference_molecule, f"{label}.reference")
+        passed = candidate_smiles == reference_smiles
+        reason = (
+            None
+            if passed
+            else f"canonical SMILES differed: candidate={candidate_smiles!r} reference={reference_smiles!r}."
+        )
+    elif assertion_kind == "molecule_descriptor_tolerance":
+        descriptor = require_string(raw.get("descriptor"), f"{label}.descriptor")
+        tolerance = require_nonnegative_number(
+            raw.get("absolute_tolerance"),
+            f"{label}.absolute_tolerance",
+        )
+        candidate_molecule = load_molecule(
+            candidate_root,
+            raw.get("candidate"),
+            f"{label}.candidate",
+            "candidate",
+        )
+        reference_molecule = load_molecule(
+            require_reference_root(reference_root, label),
+            raw.get("reference"),
+            f"{label}.reference",
+            "reference",
+        )
+        candidate_value = descriptor_value(
+            candidate_molecule,
+            descriptor,
+            f"{label}.candidate",
+        )
+        reference_value = descriptor_value(
+            reference_molecule,
+            descriptor,
+            f"{label}.reference",
+        )
+        difference = abs(candidate_value - reference_value)
+        passed = difference <= tolerance
+        reason = (
+            None
+            if passed
+            else f"descriptor {descriptor} difference {difference} exceeded absolute tolerance {tolerance}."
+        )
+    elif assertion_kind == "molecule_fingerprint_similarity":
+        fingerprint = require_string(raw.get("fingerprint"), f"{label}.fingerprint")
+        metric = require_string(raw.get("metric"), f"{label}.metric")
+        if fingerprint != "morgan_r2_2048":
+            fail_runtime(f"{label}.fingerprint={fingerprint} is unsupported.")
+        if metric != "tanimoto":
+            fail_runtime(f"{label}.metric={metric} is unsupported.")
+        min_similarity = require_unit_interval(
+            raw.get("min_similarity"),
+            f"{label}.min_similarity",
+        )
+        candidate_molecule = load_molecule(
+            candidate_root,
+            raw.get("candidate"),
+            f"{label}.candidate",
+            "candidate",
+        )
+        reference_molecule = load_molecule(
+            require_reference_root(reference_root, label),
+            raw.get("reference"),
+            f"{label}.reference",
+            "reference",
+        )
+        similarity = tanimoto_similarity(
+            candidate_molecule,
+            reference_molecule,
+            label,
+        )
+        passed = similarity >= min_similarity
+        reason = (
+            None
+            if passed
+            else f"fingerprint similarity {similarity} was below min_similarity {min_similarity}."
+        )
+    else:
+        fail_runtime(f"{label}.kind={assertion_kind} is unsupported.")
+
+    return {
+        "id": assertion_id,
+        "kind": assertion_kind,
+        "weight": weight,
+        "passed": bool(passed),
+        "score": 1.0 if passed else 0.0,
+        **({} if reason is None else {"reason": reason}),
+    }
+
+
+def normalize_assertions(assertion_set):
+    assertions = require_list(
+        assertion_set.get("assertions"),
+        "assertion_set.assertions",
+    )
+    if not assertions:
+        fail_runtime("assertion_set.assertions must be non-empty.")
+    seen = set()
+    for index, assertion in enumerate(assertions):
+        assertion_id, _, _, _ = normalize_assertion(assertion, index)
+        if assertion_id in seen:
+            fail_runtime(
+                f"assertion_set.assertions id {assertion_id} is duplicated."
+            )
+        seen.add(assertion_id)
+    return assertions
+
+
+def main():
+    runtime_context = load_runtime_context()
+    config_path = resolve_scoring_asset(
+        runtime_context,
+        "compiled_config",
+        kind="config",
+    )
+    config = require_object(load_compiled_config(config_path), "compiled_config")
+    submission_role = require_string(
+        config.get("submission_role"),
+        "compiled_config.submission_role",
+    )
+    reference_role = config.get("reference_role")
+    if reference_role is not None:
+        reference_role = require_string(
+            reference_role,
+            "compiled_config.reference_role",
+        )
+    config_score_key = require_string(
+        config.get("final_score_key"),
+        "compiled_config.final_score_key",
+    )
+    final_score_key = require_string(
+        runtime_context.get("final_score_key"),
+        "runtime_context.final_score_key",
+    )
+    if config_score_key != final_score_key:
+        fail_runtime("compiled_config.final_score_key must match runtime context.")
+    assertion_set = require_object(
+        config.get("assertion_set"),
+        "compiled_config.assertion_set",
+    )
+    assertions = normalize_assertions(assertion_set)
+    submission_path = resolve_submission_artifact(runtime_context, submission_role)
+    reference_path = (
+        resolve_evaluation_artifact(runtime_context, reference_role)
+        if reference_role is not None
+        else None
+    )
+
+    with tempfile.TemporaryDirectory(prefix="agora-artifact-assertion-") as temp_dir:
+        extracted_root = Path(temp_dir) / "candidate"
+        safe_extract_zip(
+            submission_path,
+            extracted_root,
+            label=f"submission artifact {submission_role}",
+            invalid_handler=reject_submission,
+        )
+        reference_root = None
+        if reference_path is not None:
+            reference_root = Path(temp_dir) / "reference"
+            safe_extract_zip(
+                reference_path,
+                reference_root,
+                label=f"evaluation artifact {reference_role}",
+            )
+        results = [
+            evaluate_assertion(extracted_root, reference_root, assertion, index)
+            for index, assertion in enumerate(assertions)
+        ]
+
+    total_weight = sum(result["weight"] for result in results)
+    if not math.isfinite(total_weight) or total_weight <= 0:
+        fail_runtime("assertion_set.assertions must declare finite positive total weight.")
+    earned_weight = sum(
+        result["weight"] for result in results if result["passed"]
+    )
+    score = earned_weight / total_weight
+    if not math.isfinite(score):
+        fail_runtime("assertion_set score must be finite.")
+    passed_count = sum(1 for result in results if result["passed"])
+    write_score(
+        score=score,
+        details={
+            final_score_key: score,
+            "passed_assertions": passed_count,
+            "total_assertions": len(results),
+            "earned_weight": earned_weight,
+            "total_weight": total_weight,
+            "assertion_results": results,
+        },
+    )
+
+
+if __name__ == "__main__":
+    main()