@moleculeagora/cli 0.1.0

package/dist/python-v1/protein-binder-assay-metric.py

@@ -0,0 +1,600 @@
+import csv
+import math
+
+from agora_runtime import (
+    fail_runtime,
+    load_json_file,
+    load_runtime_context,
+    reject_submission,
+    resolve_evaluation_artifact,
+    resolve_scoring_asset,
+    resolve_submission_artifact,
+    write_score,
+)
+
+REQUIRED_SUBMISSION_COLUMNS = ("design_id", "sequence")
+REQUIRED_ASSAY_COLUMNS = (
+    "design_id",
+    "metric",
+    "target",
+    "value_type",
+    "value",
+    "unit",
+)
+OPTIONAL_SUBMISSION_COLUMNS = ("rank", "track", "method_id")
+SUPPORTED_REPLICATE_POLICIES = ("median", "geometric_mean")
+SUPPORTED_QUALIFIERS = ("exact", "not_detected", "greater_than", "less_than")
+AMINO_ACIDS = set("ACDEFGHIKLMNPQRSTVWY")
+
+
+def require_string(value, label, invalid_handler=fail_runtime):
+    if not isinstance(value, str) or not value.strip():
+        invalid_handler(f"{label} must be a non-empty string.")
+    return value.strip()
+
+
+def normalize_token(value, label, invalid_handler=fail_runtime):
+    return require_string(value, label, invalid_handler).strip().lower()
+
+
+def require_config_dict(config, key):
+    value = config.get(key)
+    if not isinstance(value, dict):
+        fail_runtime(f"compiled_config.{key} must be an object.")
+    return value
+
+
+def require_literal(value, expected, label):
+    if value != expected:
+        fail_runtime(f"{label} must be {expected!r}.")
+    return value
+
+
+def require_replicate_policy(value, label):
+    policy = normalize_token(value, label)
+    if policy not in SUPPORTED_REPLICATE_POLICIES:
+        fail_runtime(
+            f"{label} must be one of {', '.join(SUPPORTED_REPLICATE_POLICIES)}."
+        )
+    return policy
+
+
+def require_non_binding_policy(value):
+    if not isinstance(value, dict):
+        fail_runtime("assay_metric.non_binding_policy must be an object.")
+    require_literal(
+        value.get("kind"),
+        "fixed_score",
+        "assay_metric.non_binding_policy.kind",
+    )
+    score = value.get("score")
+    if isinstance(score, bool) or not isinstance(score, (int, float)):
+        fail_runtime("assay_metric.non_binding_policy.score must be a finite number.")
+    score = float(score)
+    if not math.isfinite(score) or score < 0.0:
+        fail_runtime(
+            "assay_metric.non_binding_policy.score must be finite and nonnegative."
+        )
+    return {"kind": "fixed_score", "score": score}
+
+
+def normalize_gates(value):
+    if not isinstance(value, list):
+        fail_runtime("assay_metric.gates must be an array.")
+    gates = []
+    for index, gate in enumerate(value):
+        if not isinstance(gate, dict):
+            fail_runtime(f"assay_metric.gates[{index}] must be an object.")
+        metric = normalize_token(gate.get("metric"), f"assay_metric.gates[{index}].metric")
+        target = gate.get("target")
+        normalized_target = (
+            normalize_token(target, f"assay_metric.gates[{index}].target")
+            if target is not None
+            else None
+        )
+        value_type = normalize_token(
+            gate.get("value_type"),
+            f"assay_metric.gates[{index}].value_type",
+        )
+        if value_type == "boolean":
+            if not isinstance(gate.get("pass"), bool):
+                fail_runtime(f"assay_metric.gates[{index}].pass must be boolean.")
+            gates.append(
+                {
+                    "metric": metric,
+                    "target": normalized_target,
+                    "value_type": "boolean",
+                    "pass": gate["pass"],
+                }
+            )
+            continue
+        if value_type == "label":
+            disallow = gate.get("disallow")
+            if not isinstance(disallow, list) or not disallow:
+                fail_runtime(
+                    f"assay_metric.gates[{index}].disallow must be a non-empty array."
+                )
+            labels = set()
+            for label_index, raw_label in enumerate(disallow):
+                labels.add(
+                    normalize_token(
+                        raw_label,
+                        f"assay_metric.gates[{index}].disallow[{label_index}]",
+                    )
+                )
+            gates.append(
+                {
+                    "metric": metric,
+                    "target": normalized_target,
+                    "value_type": "label",
+                    "disallow": labels,
+                }
+            )
+            continue
+        fail_runtime(
+            f"assay_metric.gates[{index}].value_type must be boolean or label."
+        )
+    return gates
+
+
+def load_assay_metric_config(config):
+    assay_metric = require_config_dict(config, "assay_metric")
+    primary_target = normalize_token(
+        assay_metric.get("primary_target"),
+        "assay_metric.primary_target",
+    )
+    require_literal(assay_metric.get("primary_metric"), "kd", "assay_metric.primary_metric")
+    require_literal(assay_metric.get("kd_unit"), "M", "assay_metric.kd_unit")
+    require_literal(
+        assay_metric.get("score_transform"),
+        "negative_log10_molar",
+        "assay_metric.score_transform",
+    )
+    return {
+        "primary_target": primary_target,
+        "primary_metric": "kd",
+        "kd_unit": "M",
+        "score_transform": "negative_log10_molar",
+        "replicate_policy": require_replicate_policy(
+            assay_metric.get("replicate_policy"),
+            "assay_metric.replicate_policy",
+        ),
+        "non_binding_policy": require_non_binding_policy(
+            assay_metric.get("non_binding_policy")
+        ),
+        "gates": normalize_gates(assay_metric.get("gates")),
+    }
+
+
+def require_csv_slot(runtime_context, lane, role):
+    artifact_contract = runtime_context.get("artifact_contract")
+    if not isinstance(artifact_contract, dict):
+        fail_runtime("Runtime context is missing artifact_contract.")
+    slots = artifact_contract.get(lane)
+    if not isinstance(slots, list):
+        fail_runtime(f"Runtime context is missing artifact_contract.{lane}.")
+    for slot in slots:
+        if not isinstance(slot, dict) or slot.get("role") != role:
+            continue
+        validator = slot.get("validator")
+        if not isinstance(validator, dict) or validator.get("kind") != "csv_columns":
+            fail_runtime(
+                f"{lane} role {role} must use validator.kind=csv_columns for protein_binder_assay_metric."
+            )
+        return
+    fail_runtime(f"Runtime context is missing {lane} slot for role {role}.")
+
+
+def read_csv_rows(path, label, invalid_handler):
+    try:
+        with path.open("r", encoding="utf-8", newline="") as handle:
+            reader = csv.DictReader(handle)
+            fieldnames = reader.fieldnames
+            if not fieldnames:
+                invalid_handler(f"{label} must include a CSV header row.")
+            normalized = []
+            seen = set()
+            for fieldname in fieldnames:
+                if not isinstance(fieldname, str) or not fieldname.strip():
+                    invalid_handler(f"{label} contains an empty CSV column name.")
+                column = fieldname.strip()
+                if column in seen:
+                    invalid_handler(f"{label} contains duplicate CSV column {column!r}.")
+                seen.add(column)
+                normalized.append((fieldname, column))
+            rows = []
+            for row_index, row in enumerate(reader, start=2):
+                if None in row:
+                    invalid_handler(f"{label} row {row_index} has too many columns.")
+                rows.append(
+                    {
+                        normalized_name: row.get(raw_name, "")
+                        for raw_name, normalized_name in normalized
+                    }
+                )
+    except FileNotFoundError:
+        invalid_handler(f"Missing {label} at {path}.")
+    except OSError as error:
+        invalid_handler(f"Unable to read {label}: {error}.")
+    return [column for _, column in normalized], rows
+
+
+def require_columns(fieldnames, required_columns, label, invalid_handler):
+    missing = [column for column in required_columns if column not in fieldnames]
+    if missing:
+        invalid_handler(f"{label} is missing required columns: {', '.join(missing)}.")
+
+
+def parse_rank(raw_value, label):
+    if raw_value is None or not str(raw_value).strip():
+        return None
+    text = str(raw_value).strip()
+    try:
+        rank = float(text)
+    except ValueError:
+        reject_submission(f"{label} must be numeric when present.")
+    if not math.isfinite(rank) or rank <= 0.0:
+        reject_submission(f"{label} must be finite and positive when present.")
+    return rank
+
+
+def normalize_sequence(raw_value, label):
+    sequence = require_string(raw_value, label, reject_submission).upper()
+    invalid = sorted(set(sequence) - AMINO_ACIDS)
+    if invalid:
+        reject_submission(
+            f"{label} contains unsupported amino acid letters {''.join(invalid)!r}; use canonical one-letter protein residues only."
+        )
+    return sequence
+
+
+def load_candidate_designs(path, role):
+    fieldnames, rows = read_csv_rows(
+        path,
+        f"submission artifact {role}",
+        reject_submission,
+    )
+    require_columns(
+        fieldnames,
+        REQUIRED_SUBMISSION_COLUMNS,
+        f"submission artifact {role}",
+        reject_submission,
+    )
+    allowed_columns = set(REQUIRED_SUBMISSION_COLUMNS) | set(OPTIONAL_SUBMISSION_COLUMNS)
+    for column in fieldnames:
+        if column not in allowed_columns:
+            continue
+    candidates = {}
+    for row_index, row in enumerate(rows, start=2):
+        design_id = require_string(
+            row.get("design_id"),
+            f"submission artifact {role} row {row_index} design_id",
+            reject_submission,
+        )
+        if design_id in candidates:
+            reject_submission(
+                f"submission artifact {role} contains duplicate design_id {design_id!r}."
+            )
+        candidates[design_id] = {
+            "design_id": design_id,
+            "sequence": normalize_sequence(
+                row.get("sequence"),
+                f"submission artifact {role} row {row_index} sequence",
+            ),
+            "rank": parse_rank(
+                row.get("rank"),
+                f"submission artifact {role} row {row_index} rank",
+            )
+            if "rank" in fieldnames
+            else None,
+        }
+    if not candidates:
+        reject_submission(f"submission artifact {role} must contain at least one design.")
+    return candidates
+
+
+def normalize_qualifier(raw_value, label):
+    text = ""
+    if raw_value is not None:
+        text = str(raw_value).strip().lower()
+    qualifier = text or "exact"
+    if qualifier not in SUPPORTED_QUALIFIERS:
+        fail_runtime(
+            f"{label} qualifier must be one of {', '.join(SUPPORTED_QUALIFIERS)}."
+        )
+    return qualifier
+
+
+def load_assay_rows(path, role):
+    fieldnames, rows = read_csv_rows(
+        path,
+        f"evaluation artifact {role}",
+        fail_runtime,
+    )
+    require_columns(
+        fieldnames,
+        REQUIRED_ASSAY_COLUMNS,
+        f"evaluation artifact {role}",
+        fail_runtime,
+    )
+    assay_by_design = {}
+    for row_index, row in enumerate(rows, start=2):
+        design_id = require_string(
+            row.get("design_id"),
+            f"evaluation artifact {role} row {row_index} design_id",
+        )
+        metric = normalize_token(
+            row.get("metric"),
+            f"evaluation artifact {role} row {row_index} metric",
+        )
+        target = normalize_token(
+            row.get("target"),
+            f"evaluation artifact {role} row {row_index} target",
+        )
+        value_type = normalize_token(
+            row.get("value_type"),
+            f"evaluation artifact {role} row {row_index} value_type",
+        )
+        assay_row = {
+            "row_index": row_index,
+            "design_id": design_id,
+            "metric": metric,
+            "target": target,
+            "value_type": value_type,
+            "value": row.get("value", ""),
+            "unit": str(row.get("unit", "")).strip(),
+            "qualifier": normalize_qualifier(
+                row.get("qualifier"),
+                f"evaluation artifact {role} row {row_index}",
+            )
+            if "qualifier" in fieldnames
+            else "exact",
+        }
+        assay_by_design.setdefault(design_id, []).append(assay_row)
+    if not rows:
+        fail_runtime(f"evaluation artifact {role} must contain at least one assay row.")
+    return assay_by_design
+
+
+def parse_boolean_value(raw_value, label):
+    value = normalize_token(raw_value, label)
+    if value == "true":
+        return True
+    if value == "false":
+        return False
+    fail_runtime(f"{label} must be true or false.")
+
+
+def parse_label_value(raw_value, label):
+    return normalize_token(raw_value, label)
+
+
+def gate_matches(row, gate):
+    if row["metric"] != gate["metric"]:
+        return False
+    if row["value_type"] != gate["value_type"]:
+        return False
+    if gate["target"] is not None and row["target"] != gate["target"]:
+        return False
+    return True
+
+
+def design_passes_gate(rows, gate):
+    matching = [row for row in rows if gate_matches(row, gate)]
+    if not matching:
+        return False
+    if gate["value_type"] == "boolean":
+        expected = gate["pass"]
+        for row in matching:
+            observed = parse_boolean_value(
+                row["value"],
+                f"evaluation assay row {row['row_index']} boolean gate value",
+            )
+            if observed != expected:
+                return False
+        return True
+    for row in matching:
+        observed = parse_label_value(
+            row["value"],
+            f"evaluation assay row {row['row_index']} label gate value",
+        )
+        if observed in gate["disallow"]:
+            return False
+    return True
+
+
+def primary_row_matches(row, params):
+    return (
+        row["metric"] == params["primary_metric"]
+        and row["target"] == params["primary_target"]
+    )
+
+
+def parse_kd_value(raw_value, label):
+    text = str(raw_value).strip()
+    if not text:
+        fail_runtime(f"{label} must be present for exact KD rows.")
+    try:
+        value = float(text)
+    except ValueError:
+        fail_runtime(f"{label} must be numeric, received {text!r}.")
+    if not math.isfinite(value) or value <= 0.0:
+        fail_runtime(f"{label} must be finite and positive.")
+    return value
+
+
+def aggregate_exact_kd(values, policy):
+    ordered = sorted(values)
+    if policy == "median":
+        midpoint = len(ordered) // 2
+        if len(ordered) % 2 == 1:
+            return ordered[midpoint]
+        return (ordered[midpoint - 1] + ordered[midpoint]) / 2.0
+    log_sum = sum(math.log(value) for value in ordered)
+    return math.exp(log_sum / len(ordered))
+
+
+def score_exact_kd(kd_m):
+    score = -math.log10(kd_m)
+    if not math.isfinite(score) or score < 0.0:
+        fail_runtime(
+            "negative_log10_molar produced a negative or non-finite score. Next step: provide KD values between 0 and 1 M for v1 scoring."
+        )
+    return score
+
+
+def score_design(candidate, rows, params):
+    if not all(design_passes_gate(rows, gate) for gate in params["gates"]):
+        return None
+    primary_rows = [row for row in rows if primary_row_matches(row, params)]
+    if not primary_rows:
+        return None
+    exact_values = []
+    has_not_detected = False
+    for row in primary_rows:
+        if row["unit"] != params["kd_unit"]:
+            fail_runtime(
+                f"evaluation assay row {row['row_index']} uses unit {row['unit']!r}; protein_binder_assay_metric@1 requires M."
+            )
+        if row["value_type"] != "number":
+            fail_runtime(
+                f"evaluation assay row {row['row_index']} primary KD value_type must be number."
+            )
+        qualifier = row["qualifier"]
+        if qualifier == "exact":
+            exact_values.append(
+                parse_kd_value(
+                    row["value"],
+                    f"evaluation assay row {row['row_index']} KD value",
+                )
+            )
+            continue
+        if qualifier == "not_detected":
+            has_not_detected = True
+            continue
+        fail_runtime(
+            f"evaluation assay row {row['row_index']} uses qualifier {qualifier}; v1 scores only exact KD values and not_detected rows."
+        )
+    if exact_values:
+        kd_m = aggregate_exact_kd(exact_values, params["replicate_policy"])
+        return {
+            "design_id": candidate["design_id"],
+            "rank": candidate["rank"],
+            "score": score_exact_kd(kd_m),
+            "best_kd_m": kd_m,
+            "assay_outcome": "exact",
+            "replicate_count": len(exact_values),
+        }
+    if has_not_detected:
+        return {
+            "design_id": candidate["design_id"],
+            "rank": candidate["rank"],
+            "score": params["non_binding_policy"]["score"],
+            "best_kd_m": 0.0,
+            "assay_outcome": "not_detected",
+            "replicate_count": 0,
+        }
+    return None
+
+
+def choose_best_design(results):
+    return sorted(
+        results,
+        key=lambda item: (
+            -item["score"],
+            item["rank"] if item["rank"] is not None else math.inf,
+            item["design_id"],
+        ),
+    )[0]
+
+
+def main():
+    runtime_context = load_runtime_context()
+    config_path = resolve_scoring_asset(
+        runtime_context,
+        "compiled_config",
+        kind="config",
+    )
+    try:
+        config = load_json_file(config_path, label="compiled_config")
+    except RuntimeError as error:
+        fail_runtime(str(error))
+    if not isinstance(config, dict):
+        fail_runtime("compiled_config must be a JSON object.")
+
+    assay_results_role = require_string(
+        config.get("assay_results_role"),
+        "compiled_config.assay_results_role",
+    )
+    candidate_designs_role = require_string(
+        config.get("candidate_designs_role"),
+        "compiled_config.candidate_designs_role",
+    )
+    final_score_key = require_string(
+        config.get("final_score_key"),
+        "compiled_config.final_score_key",
+    )
+    objective = require_string(
+        runtime_context.get("objective"),
+        "runtime_context.objective",
+    )
+    if objective != "maximize":
+        fail_runtime("protein_binder_assay_metric requires objective=maximize.")
+
+    params = load_assay_metric_config(config)
+    require_csv_slot(runtime_context, "evaluation", assay_results_role)
+    require_csv_slot(runtime_context, "submission", candidate_designs_role)
+    assay_path = resolve_evaluation_artifact(runtime_context, assay_results_role)
+    candidates_path = resolve_submission_artifact(
+        runtime_context,
+        candidate_designs_role,
+    )
+    candidates = load_candidate_designs(candidates_path, candidate_designs_role)
+    assay_by_design = load_assay_rows(assay_path, assay_results_role)
+
+    assay_matched_design_ids = set()
+    scored_results = []
+    for design_id, candidate in candidates.items():
+        rows = assay_by_design.get(design_id, [])
+        primary_rows = [row for row in rows if primary_row_matches(row, params)]
+        if primary_rows:
+            assay_matched_design_ids.add(design_id)
+        result = score_design(candidate, rows, params)
+        if result is not None:
+            scored_results.append(result)
+
+    if not assay_matched_design_ids:
+        reject_submission(
+            "Submission did not match any assay_results rows for the configured primary target and metric.",
+            details={
+                "valid_design_count": 0,
+                "assay_matched_design_count": 0,
+            },
+        )
+    if not scored_results:
+        reject_submission(
+            "No submitted design passed assay gates with scoreable KD evidence.",
+            details={
+                "valid_design_count": 0,
+                "assay_matched_design_count": len(assay_matched_design_ids),
+            },
+        )
+
+    best = choose_best_design(scored_results)
+    details = {
+        final_score_key: best["score"],
+        "score": best["score"],
+        "best_kd_m": best["best_kd_m"],
+        "valid_design_count": len(scored_results),
+        "assay_matched_design_count": len(assay_matched_design_ids),
+        "best_design_id": best["design_id"],
+        "best_assay_outcome": best["assay_outcome"],
+        "best_replicate_count": best["replicate_count"],
+        "replicate_policy": params["replicate_policy"],
+        "score_transform": params["score_transform"],
+    }
+    write_score(score=best["score"], details=details)
+
+
+if __name__ == "__main__":
+    main()