Skip to content

API reference

Generated from the docstrings in the source. The top-level neorx package re-exports the pipeline entry points, so from neorx import run_pipeline and from neorx.core.pipeline import run_pipeline are equivalent.

>>> import neorx
>>> "run_pipeline" in neorx.__all__ and "identify_causal_targets" in neorx.__all__
True

causalphylo — admissibility and identification

Edge admissibility and Pearl's backdoor criterion are not in this package. They depend on nothing but NetworkX, so they live in CausalPhylo, which NeoRx imports them from. The narrative pages that use them are Which edges earn an arrow and Identification.

They are not re-documented here. Duplicating another package's API reference means two copies that drift, and the authoritative one is CausalPhylo's own API reference.

Everything both modules make public is re-exported from the top level, so a single import reaches all of it:

>>> from causalphylo import (
...     is_causal_admissible, causal_subgraph, cyclic_components,
...     acyclic_core, AcyclicCore,
...     CAUSAL_EDGE_TYPES, GENETIC_EVIDENCE_CLASSES,
...     find_adjustment_set, Identification, IdentificationReason,
...     satisfies_backdoor, mutilated_graph, confounding_sensitivity,
...     MAX_ADJUSTMENT_SET_SIZE, MAX_CANDIDATE_POOL,
... )

The submodule paths causalphylo.graph_semantics and causalphylo.backdoor also work, and are what the CausalPhylo reference is organised by.

neorx.core.causal.identifier

Candidate evaluation and ranking. See From verdict to target.

Causal Target Identifier

This is the NOVEL core of NeoRx. While every other drug-discovery pipeline ranks targets by association scores (correlation), we apply Pearl's causal inference framework to distinguish genuine causal drivers from correlational bystanders.

The Fundamental Problem

Gene–disease association databases (Monarch Initiative, Open Targets) report that TNF-α is strongly associated with HIV. Indeed, TNF-α levels are elevated during HIV infection. But TNF-α elevation is a consequence of immune activation — it is downstream of the infection. Inhibiting TNF-α does not treat HIV; it makes it worse by suppressing immune defence.

Conversely, CCR5 is the HIV-1 co-receptor. A loss-of-function mutation (CCR5-Δ32) confers near-complete resistance to HIV-1. Maraviroc, which blocks CCR5, is an approved antiretroviral. CCR5 is a causal target.

Our Method
  1. Graph → Causal Model: Convert the disease knowledge graph into a DAG suitable for DoWhy. Each edge encodes a potential causal direction.

  2. Backdoor Criterion: For each candidate target, check whether the causal effect on the disease outcome is identifiable — i.e. whether there exists a valid adjustment set that blocks all confounding paths.

  3. Effect Estimation: Estimate the Average Treatment Effect (ATE) of intervening on the target. We use linear regression (for interpretability) and inverse propensity weighting (for robustness).

  4. Sensitivity Analysis: Apply DoWhy's refutation tests:

  5. random_common_cause: Add a random confounder.
  6. placebo_treatment: Shuffle the treatment variable.
  7. data_subset: Re-estimate on random subsets. If the estimate is fragile, the target may be correlational.

  8. Classification: Combine causal effect, robustness, graph topology (in-degree, pathway membership), and druggability into a final classification:

  9. Causal: High effect + robust + identifiable
  10. Correlational: High association but fragile/unidentifiable
  11. Inconclusive: Insufficient evidence

identify_causal_targets

identify_causal_targets(graph: DiseaseGraph, top_n: int = 10, min_causal_confidence: float = 0.3, frame: frozenset[str] | None = None) -> list[NeoRxResult]

Identify and rank causal drug targets from a disease graph.

Parameters:

Name Type Description Default
graph DiseaseGraph

The assembled disease causal graph.

required
top_n int

Maximum number of targets to return.

10
min_causal_confidence float

Minimum causal confidence threshold.

0.3
frame frozenset[str] | None

The population a dated run may evaluate -- gene symbols the pinned release associated with this disease on genetic evidence (see neorx.snapshots.frame.candidate_frame). None means undated, unchanged behaviour: every eligible node is a candidate.

None

Returns:

Type Description
list[NeoRxResult]

Ranked list of causal target assessments, best first.

Any statistic *about the evaluation* -- an identifiability rate, a
failure breakdown -- belongs on ``evaluate_all_targets`` instead:
this list is ranked by ``causal_confidence``, which itself rewards
identifiability, so a rate measured over it is measured on a sample
the rate selected.
Source code in src/neorx/core/causal/identifier.py
def identify_causal_targets(
    graph: DiseaseGraph,
    top_n: int = 10,
    min_causal_confidence: float = 0.3,
    frame: frozenset[str] | None = None,
) -> list[NeoRxResult]:
    """Identify and rank causal drug targets from a disease graph.

    Parameters
    ----------
    graph : DiseaseGraph
        The assembled disease causal graph.
    top_n : int
        Maximum number of targets to return.
    min_causal_confidence : float
        Minimum causal confidence threshold.
    frame : frozenset[str] | None
        The population a dated run may evaluate -- gene symbols the pinned
        release associated with this disease on genetic evidence (see
        ``neorx.snapshots.frame.candidate_frame``). ``None`` means
        undated, unchanged behaviour: every eligible node is a candidate.

    Returns
    -------
    list[NeoRxResult]
        Ranked list of causal target assessments, best first.

    Any statistic *about the evaluation* -- an identifiability rate, a
    failure breakdown -- belongs on ``evaluate_all_targets`` instead:
    this list is ranked by ``causal_confidence``, which itself rewards
    identifiability, so a rate measured over it is measured on a sample
    the rate selected.
    """
    return rank_causal_targets(
        evaluate_all_targets(graph, frame=frame),
        top_n=top_n,
        min_causal_confidence=min_causal_confidence,
    )

evaluate_all_targets

evaluate_all_targets(graph: DiseaseGraph, frame: frozenset[str] | None = None) -> list[NeoRxResult]

Evaluate every candidate target in the graph, filtering nothing.

This is the population identify_causal_targets then ranks and truncates, and what any statistic describing the identification procedure has to be computed over -- compute_causal_confidence awards a bonus for being identifiable, so the top-N is a sample selected partly by the property such a statistic measures.

frame, when given, restricts candidates to the population a dated run may evaluate (see identify_causal_targets). Exclusions are logged rather than raised: Monarch and ChEMBL legitimately contribute genes OpenTargets did not, so refusing on an out-of-frame gene would fail every dated run for an entirely normal condition. The log line, with the disease name and the count, is what keeps that filtering honest -- a run that suddenly excludes far more than it used to has had something change upstream, and that must be visible.

Sorted by causal_confidence descending: ordering only, nothing dropped.

Source code in src/neorx/core/causal/identifier.py
def evaluate_all_targets(
    graph: DiseaseGraph,
    frame: frozenset[str] | None = None,
) -> list[NeoRxResult]:
    """Evaluate every candidate target in the graph, filtering nothing.

    This is the population ``identify_causal_targets`` then ranks and
    truncates, and what any statistic describing the identification
    procedure has to be computed over -- ``compute_causal_confidence``
    awards a bonus for being identifiable, so the top-N is a sample
    selected partly by the property such a statistic measures.

    ``frame``, when given, restricts candidates to the population a dated
    run may evaluate (see ``identify_causal_targets``). Exclusions are
    logged rather than raised: Monarch and ChEMBL legitimately contribute
    genes OpenTargets did not, so refusing on an out-of-frame gene would
    fail every dated run for an entirely normal condition. The log line,
    with the disease name and the count, is what keeps that filtering
    honest -- a run that suddenly excludes far more than it used to has
    had something change upstream, and that must be visible.

    Sorted by ``causal_confidence`` descending: ordering only, nothing
    dropped.
    """
    G = disease_graph_to_networkx(graph)
    disease_node_id = _find_disease_node(G, graph.disease_name)

    if not disease_node_id:
        logger.error("No disease node found in graph.")
        return []

    # ── Biological intelligence layer ─────────────────────────
    disease_type = classify_disease(graph.disease_name)
    classifier = TargetClassifier()

    # The tissue gate queries the Human Protein Atlas live, and nothing
    # pins it. On a dated graph today's HPA answer would decide
    # `tissue_relevant`, and a failed gate forces CORRELATIONAL whatever
    # the confidence -- so an unpinned source would set a reported
    # classification on a graph built from a past release. That is the
    # rule this sub-project settled on: a dated build takes nothing from
    # an unpinned source.
    #
    # Not applying it is NOT the same as passing it, and the difference is
    # recorded on every result rather than left to be inferred from a
    # `tissue_relevant=True` that looks like a pass. A dated run is
    # therefore systematically more permissive here than a live one, and
    # the two classifications must not be pooled.
    tissue_filter = None if graph.as_of else TissueFilter()

    logger.info(
        "Disease type: %s → classifier active, tissue filter %s.",
        disease_type.value,
        "SKIPPED (dated build: HPA is unpinned)" if graph.as_of else "active",
    )

    # Get candidate genes/proteins
    candidates, frame_excluded = _get_candidate_nodes(G, disease_node_id, frame=frame)
    if frame_excluded:
        logger.info(
            "Frame gate excluded %d candidate nodes for %r.",
            len(frame_excluded), graph.disease_name,
        )
    logger.info("Evaluating %d candidate targets…", len(candidates))

    # Count distinct sources that actually contributed gene/protein nodes
    _gene_sources: set[str] = set()
    for node in graph.nodes:
        if node.node_type in (NodeType.GENE, NodeType.PROTEIN, NodeType.PATHOGEN_GENE) and node.source:
            for src in node.source.split(", "):
                _gene_sources.add(src.strip())
    n_active_sources = max(1, len(_gene_sources))
    logger.info("Active gene-level sources: %d (%s).",
                n_active_sources, ", ".join(sorted(_gene_sources)))

    results: list[NeoRxResult] = []
    for node_id in candidates:
        result = _evaluate_target(
            G, node_id, disease_node_id, graph,
            n_active_sources=n_active_sources,
            classifier=classifier,
            tissue_filter=tissue_filter,
            disease_name=graph.disease_name,
            disease_type=disease_type,
        )
        results.append(result)

    # Sort by causal_confidence descending
    results.sort(key=lambda r: r.causal_confidence, reverse=True)

    return results

Which evaluated targets get reported.

identifier.evaluate_all_targets evaluates every candidate in the disease graph; this module decides which of them the pipeline reports. The two are separate because they answer different questions, and conflating them corrupts any statistic about the evaluation: ranking is by causal_confidence, which awards a bonus for being identifiable, so the reported slice is a sample selected partly by a property one might want to measure over the candidates.

rank_causal_targets

rank_causal_targets(results: list[NeoRxResult], top_n: int = 10, min_causal_confidence: float = 0.3) -> list[NeoRxResult]

Filter and rank evaluated targets down to the reported top-N.

results is what evaluate_all_targets returned. Kept separate from that evaluation so the full list stays reachable: the survivors are not a representative sample of what was evaluated.

Source code in src/neorx/core/causal/ranking.py
def rank_causal_targets(
    results: list[NeoRxResult],
    top_n: int = 10,
    min_causal_confidence: float = 0.3,
) -> list[NeoRxResult]:
    """Filter and rank evaluated targets down to the reported top-N.

    ``results`` is what ``evaluate_all_targets`` returned. Kept separate
    from that evaluation so the full list stays reachable: the survivors
    are not a representative sample of what was evaluated.
    """
    # Split human and pathogen results to prevent pathogen targets
    # from completely crowding out human targets.  Each pool gets
    # at least half the slots (with leftover going to whichever
    # pool has more high-confidence results).
    human_results = [r for r in results if r.target_type != "PATHOGEN_DIRECT"]
    pathogen_results = [r for r in results if r.target_type == "PATHOGEN_DIRECT"]

    half = top_n // 2
    # Each pool gets at least half, remainder filled from the other
    top_human = [r for r in human_results if r.causal_confidence >= min_causal_confidence][:half]
    top_pathogen = [r for r in pathogen_results if r.causal_confidence >= min_causal_confidence][:half]

    # Fill remaining slots from whichever pool has leftovers
    remaining = top_n - len(top_human) - len(top_pathogen)
    if remaining > 0:
        used_ids = {r.protein_id for r in top_human} | {r.protein_id for r in top_pathogen}
        overflow = [
            r for r in results
            if r.protein_id not in used_ids
            and r.causal_confidence >= min_causal_confidence
        ][:remaining]
        combined = top_human + top_pathogen + overflow
    else:
        combined = top_human + top_pathogen

    # Re-sort the combined list by confidence
    combined.sort(key=lambda r: r.causal_confidence, reverse=True)

    if not combined:
        # If nothing passes threshold, return top_n anyway
        combined = results[:top_n]

    return combined[:top_n]

Turning evidence into a ranked, labelled target.

Druggability, the combined causal confidence, and the final causal-versus-correlational classification. These are weighted heuristics over the evidence counts, and they are named as such: nothing here estimates a causal effect.

compute_causal_confidence

compute_causal_confidence(effect: float, robustness: float, is_identifiable: bool, n_pathways: int, n_interactions: int, source_scores: dict[str, float], druggability: float, n_active_sources: int = 4, n_associated_diseases: int = 0) -> float

Compute composite causal confidence score.

Weights: - Causal effect magnitude: 30% - Robustness (sensitivity analysis): 25% - Identifiability (backdoor criterion): 15% - Multi-source consensus: 10% - Disease specificity: 10% - Druggability: 10%

Disease specificity replaces the former "network centrality" weight. Hub genes (TP53, AKT1) are associated with thousands of diseases — they are generic, not specific. Specificity rewards targets that are uniquely linked to the disease under study, penalising promiscuous hubs.

Formula: specificity = 1 / log2(n_diseases + 2) - Gene linked to 1 disease: specificity = 1.0 - Gene linked to 10 diseases: specificity = 0.29 - Gene linked to 100: specificity = 0.15 - Gene linked to 1000: specificity = 0.10

Source code in src/neorx/core/causal/scoring.py
def compute_causal_confidence(
    effect: float,
    robustness: float,
    is_identifiable: bool,
    n_pathways: int,
    n_interactions: int,
    source_scores: dict[str, float],
    druggability: float,
    n_active_sources: int = 4,
    n_associated_diseases: int = 0,
) -> float:
    """Compute composite causal confidence score.

    Weights:
    - Causal effect magnitude: 30%
    - Robustness (sensitivity analysis): 25%
    - Identifiability (backdoor criterion): 15%
    - Multi-source consensus: 10%
    - Disease specificity: 10%
    - Druggability: 10%

    Disease specificity replaces the former "network centrality"
    weight.  Hub genes (TP53, AKT1) are associated with thousands
    of diseases — they are generic, not specific.  Specificity
    rewards targets that are uniquely linked to the disease under
    study, penalising promiscuous hubs.

    Formula: specificity = 1 / log2(n_diseases + 2)
    - Gene linked to 1 disease:   specificity = 1.0
    - Gene linked to 10 diseases: specificity = 0.29
    - Gene linked to 100:         specificity = 0.15
    - Gene linked to 1000:        specificity = 0.10
    """
    # Normalise effect to 0-1
    effect_norm = min(1.0, effect)

    # Multi-source consensus: more sources = higher
    n_sources = len(source_scores)
    avg_source_score = float(np.mean(list(source_scores.values()))) if source_scores else 0.0
    consensus = min(1.0, (n_sources / max(1, n_active_sources)) * avg_source_score)

    # Disease specificity — replaces network centrality
    if n_associated_diseases > 0:
        specificity = 1.0 / np.log2(n_associated_diseases + 2)
    else:
        # No data → neutral (0.5), neither reward nor penalise
        specificity = 0.5

    confidence = (
        0.30 * effect_norm
        + 0.25 * robustness
        + 0.15 * (1.0 if is_identifiable else 0.0)
        + 0.10 * consensus
        + 0.10 * min(1.0, specificity)
        + 0.10 * druggability
    )

    return round(min(1.0, max(0.0, confidence)), 4)

classify_target

classify_target(gene_name: str, causal_confidence: float, robustness: float, is_identifiable: bool, n_pathways: int, druggability: float, target_type: TargetType = TargetType.CORRELATIONAL, tissue_relevant: bool = True, evidence_streams: int = 0) -> tuple[TargetClassification, str]

Classify a target as causal, correlational, or inconclusive.

Classification rules:

Automatic demotion (overrides confidence scores): - HOST_SYMPTOM targets → always CORRELATIONAL - tissue_relevant=False → always CORRELATIONAL

Tissue gate (boolean, not a modifier): - tissue_relevant is True/False from the tissue filter. - True = gene is expressed in a disease-relevant tissue (or expression unknown → pass). - False = gene is only expressed in irrelevant tissues → demoted to CORRELATIONAL regardless of confidence. - The gate NEVER modifies causal_confidence. Confidence stays pure — it measures causal evidence quality, not tissue expression.

Evidence triangulation (for CAUSAL status): - Must have ≥2 independent evidence streams - causal_confidence ≥ 0.6 AND robust AND identifiable

Standard rules: - Correlational: confidence < 0.4 OR not robust - Inconclusive: everything in between

Source code in src/neorx/core/causal/scoring.py
def classify_target(
    gene_name: str,
    causal_confidence: float,
    robustness: float,
    is_identifiable: bool,
    n_pathways: int,
    druggability: float,
    target_type: TargetType = TargetType.CORRELATIONAL,
    tissue_relevant: bool = True,
    evidence_streams: int = 0,
) -> tuple[TargetClassification, str]:
    """Classify a target as causal, correlational, or inconclusive.

    Classification rules:

    **Automatic demotion** (overrides confidence scores):
    - HOST_SYMPTOM targets → always CORRELATIONAL
    - tissue_relevant=False → always CORRELATIONAL

    **Tissue gate** (boolean, not a modifier):
    - tissue_relevant is True/False from the tissue filter.
    - True = gene is expressed in a disease-relevant tissue
      (or expression unknown → pass).
    - False = gene is only expressed in irrelevant tissues
      → demoted to CORRELATIONAL regardless of confidence.
    - The gate NEVER modifies causal_confidence.  Confidence
      stays pure — it measures causal evidence quality, not
      tissue expression.

    **Evidence triangulation** (for CAUSAL status):
    - Must have ≥2 independent evidence streams
    - causal_confidence ≥ 0.6 AND robust AND identifiable

    **Standard rules**:
    - Correlational: confidence < 0.4 OR not robust
    - Inconclusive: everything in between
    """
    reasons = []

    # ── Biological overrides (before confidence check) ──────

    # 1. Symptom markers are NEVER causal drug targets
    if target_type == TargetType.HOST_SYMPTOM:
        classification = TargetClassification.CORRELATIONAL
        reasons.append(
            f"⚠ {gene_name} classified as HOST_SYMPTOM: this gene "
            f"encodes a receptor/channel associated with disease "
            f"symptoms (e.g. seizures, pain), not with the disease "
            f"mechanism itself. Targeting symptom markers does not "
            f"treat the underlying disease."
        )
        reasons.append(
            f"Confidence was {causal_confidence:.2f} but biological "
            f"classification overrides statistical score."
        )
        return classification, " ".join(reasons)

    # 2. Tissue gate — independent boolean criterion
    #    If tissue_relevant is False, the gene is expressed only
    #    in tissues unrelated to this disease.  Demote regardless
    #    of how strong the statistical evidence looks.
    if not tissue_relevant:
        classification = TargetClassification.CORRELATIONAL
        reasons.append(
            f"⚠ {gene_name} FAILED tissue gate: expressed only in "
            f"tissues not relevant to this disease. "
            f"Confidence was {causal_confidence:.2f} but tissue "
            f"expression does not support this target."
        )
        return classification, " ".join(reasons)

    # ── Standard classification with evidence triangulation ──

    # When evidence_streams is explicitly provided (>0), enforce
    # the triangulation requirement.  When not provided (legacy
    # callers using default of 0), fall back to the original
    # thresholds for backward compatibility.
    triangulation_ok = evidence_streams >= 2 or evidence_streams == 0

    if (
        causal_confidence >= 0.6
        and robustness >= 0.4
        and is_identifiable
        and triangulation_ok
    ):
        classification = TargetClassification.CAUSAL
        reasons.append(
            f"{gene_name} has causal confidence {causal_confidence:.2f}, "
            f"supported by {n_pathways} pathway(s), robustness score "
            f"{robustness:.2f}, and {evidence_streams} independent "
            f"evidence stream(s). Tissue gate: PASS."
        )
        if target_type in (TargetType.PATHOGEN_DIRECT, TargetType.HOST_INVASION):
            reasons.append(
                f"Target type {target_type.value}: this is a direct "
                f"disease-mechanism target."
            )
        if druggability >= 0.5:
            reasons.append(
                f"Druggability score {druggability:.2f} indicates tractable "
                f"target with known 3D structures."
            )
        reasons.append(
            "Backdoor criterion satisfied: causal effect is identifiable "
            "after adjusting for confounders."
        )

    elif causal_confidence < 0.4 or robustness < 0.3:
        classification = TargetClassification.CORRELATIONAL
        reasons.append(
            f"{gene_name} is likely correlational (confidence={causal_confidence:.2f}, "
            f"robustness={robustness:.2f})."
        )
        if not is_identifiable:
            reasons.append(
                "No valid causal path identified — association may be "
                "due to confounding."
            )
        reasons.append(
            "Sensitivity analysis suggests the association is fragile "
            "and may not survive intervention."
        )

    elif evidence_streams > 0 and evidence_streams < 2 and causal_confidence >= 0.6:
        # High confidence but insufficient independent evidence
        classification = TargetClassification.INCONCLUSIVE
        reasons.append(
            f"{gene_name} has confidence {causal_confidence:.2f} but only "
            f"{evidence_streams} evidence stream(s). ≥2 required for CAUSAL."
        )

    else:
        classification = TargetClassification.INCONCLUSIVE
        reasons.append(
            f"{gene_name} has moderate evidence (confidence={causal_confidence:.2f}) "
            f"but insufficient data for definitive classification."
        )

    return classification, " ".join(reasons)

assess_druggability

assess_druggability(node_data: dict[str, Any]) -> float

Score druggability based on available evidence.

Uses Open Targets tractability data when available, structural information, and protein family heuristics.

Source code in src/neorx/core/causal/scoring.py
def assess_druggability(node_data: dict[str, Any]) -> float:
    """Score druggability based on available evidence.

    Uses Open Targets tractability data when available,
    structural information, and protein family heuristics.
    """
    score = 0.3  # Base

    pdb_ids = node_data.get("pdb_ids", [])
    if pdb_ids:
        score += 0.2  # Has 3D structure

    uniprot_id = node_data.get("uniprot_id", "")
    if uniprot_id:
        score += 0.1  # Well-characterised protein

    # Open Targets tractability data (propagated from graph_builder)
    metadata = node_data.get("metadata", {})
    tractability = metadata.get("tractability", [])
    if tractability:
        for entry in tractability:
            if isinstance(entry, dict) and entry.get("value"):
                score += 0.15
                break  # At least one modality is tractable

    # UniProt druggability flag
    if metadata.get("is_druggable"):
        score += 0.15

    # Protein family heuristic from description text
    description = node_data.get("description", "").lower()
    druggable_keywords = [
        "receptor", "kinase", "protease", "enzyme", "channel",
        "transporter", "gpcr", "nuclear receptor",
    ]
    if any(kw in description for kw in druggable_keywords):
        score += 0.15

    return min(1.0, score)

organism_disease_relevance

organism_disease_relevance(organism: str, disease_name: str) -> float

Score how relevant a pathogen organism is to a disease.

Returns 1.0 if the organism matches the primary pathogen, 0.3 for generic/unrelated organisms, enabling the confidence formula to demote off-target pathogens.

For non-infectious diseases (cancer, neurological, metabolic), ALL pathogen targets get 0.0 — these diseases have no causative pathogen, so any pathogen target in ChEMBL is from co-prescribed medications (e.g. antibiotics for Alzheimer's patients) and should not be ranked.

Source code in src/neorx/core/causal/scoring.py
def organism_disease_relevance(
    organism: str, disease_name: str,
) -> float:
    """Score how relevant a pathogen organism is to a disease.

    Returns 1.0 if the organism matches the primary pathogen,
    0.3 for generic/unrelated organisms, enabling the confidence
    formula to demote off-target pathogens.

    For non-infectious diseases (cancer, neurological, metabolic),
    ALL pathogen targets get 0.0 — these diseases have no
    causative pathogen, so any pathogen target in ChEMBL is from
    co-prescribed medications (e.g. antibiotics for Alzheimer's
    patients) and should not be ranked.
    """
    if not organism or not disease_name:
        return 0.0

    org_lower = organism.lower()
    disease_lower = disease_name.lower()

    # Check explicit mapping first
    for disease_key, keywords in _DISEASE_ORGANISMS.items():
        if disease_key in disease_lower:
            for kw in keywords:
                if kw in org_lower:
                    return 1.0
            # Disease matched a mapping but organism didn't → off-target
            return 0.3

    # No explicit mapping → this disease has no known pathogen.
    # All pathogen targets are irrelevant (from co-prescribed
    # medications like antibiotics, not disease-specific drugs).
    return 0.0

evaluate_pathogen_target

evaluate_pathogen_target(G: DiGraph, target_id: str, disease_id: str, graph: DiseaseGraph, *, causal_pathway: list[str], n_active_sources: int = 4, disease_name: str = '') -> NeoRxResult

Evaluate a pathogen target from ChEMBL.

Pathogen targets (e.g. PfDHFR-TS, HIV-1 protease) are validated by existing drugs. Their confidence is based on drug evidence rather than causal graph analysis:

  • Clinical phase = highest weight (Phase 4 approved drug = maximum confidence)
  • Number of drugs targeting this protein
  • Mechanism-of-action diversity

They bypass: - Biological classifier (not host genes) - Tissue filter (pathogen proteins don't express in human tissue) - Causal path analysis (they're direct drug targets)

causal_pathway is computed by the caller (identifier.py still owns _find_causal_pathway, which stays there for the tests that exercise it directly) and threaded through here rather than recomputed, so this function only needs the graph for node lookups.

Source code in src/neorx/core/causal/scoring.py
def evaluate_pathogen_target(
    G: nx.DiGraph,
    target_id: str,
    disease_id: str,
    graph: DiseaseGraph,
    *,
    causal_pathway: list[str],
    n_active_sources: int = 4,
    disease_name: str = "",
) -> NeoRxResult:
    """Evaluate a pathogen target from ChEMBL.

    Pathogen targets (e.g. PfDHFR-TS, HIV-1 protease) are
    validated by existing drugs.  Their confidence is based on
    drug evidence rather than causal graph analysis:

    - Clinical phase = highest weight (Phase 4 approved drug
      = maximum confidence)
    - Number of drugs targeting this protein
    - Mechanism-of-action diversity

    They bypass:
    - Biological classifier (not host genes)
    - Tissue filter (pathogen proteins don't express in human tissue)
    - Causal path analysis (they're direct drug targets)

    ``causal_pathway`` is computed by the caller (``identifier.py`` still
    owns ``_find_causal_pathway``, which stays there for the tests that
    exercise it directly) and threaded through here rather than
    recomputed, so this function only needs the graph for node lookups.
    """
    node_data = G.nodes[target_id]
    gene_name = node_data.get("name", target_id)
    metadata = node_data.get("metadata", {})

    # Use graph.disease_name as fallback if disease_name not provided
    if not disease_name and graph:
        disease_name = graph.disease_name

    # Drug evidence score from ChEMBL (already computed)
    drug_score = metadata.get("chembl_drug_evidence_score", 0.5)
    clinical_phase = metadata.get("clinical_phase", 0)
    n_drugs = metadata.get("n_drugs", 0)
    drugs = metadata.get("drugs", [])
    moas = metadata.get("mechanisms_of_action", [])
    organism = metadata.get("pathogen_organism", "unknown pathogen")

    # ── Organism-disease relevance ──────────────────────────────
    #    ChEMBL returns ALL targets of drugs indicated for a disease,
    #    including co-infection antibiotics and anti-helminthics.
    #    A Phase 4 bacterial ribosome target shouldn't score as high
    #    as a Phase 4 P. falciparum DHFR for malaria.
    org_relevance = organism_disease_relevance(organism, disease_name)

    # Source scores — only ChEMBL for pathogen targets
    source_scores = {"ChEMBL": drug_score}

    # Druggability — pathogen drug targets are druggable by definition
    druggability = 1.0 if clinical_phase >= 3 else 0.8

    # ── Identifiability ─────────────────────────────────────────
    #    Pathogen targets bypass causal path analysis entirely (see the
    #    docstring), so the backdoor criterion is never attempted for
    #    them and no adjustment set is ever found. The verdict this
    #    function reports is therefore not-identifiable, and the
    #    confidence formula below reads that same verdict instead of
    #    asserting its opposite: the formula used to award the full
    #    identifiability bonus with the comment "always identifiable"
    #    while the returned NeoRxResult said identifiable=False with
    #    reason "no_causal_path". A target counted as a no_causal_path
    #    failure in the published taxonomy was simultaneously scored as
    #    though identifiable, and could clear the 0.6 CAUSAL threshold
    #    on constants alone.
    identifiable = False
    identification_reason = "no_causal_path"

    # Causal confidence for pathogen targets:
    # Based entirely on drug evidence (not graph topology)
    #   40% drug_score (phase + drug diversity + MOA diversity)
    #   25% druggability (always high for validated targets)
    #   15% identifiability (never awarded: see above)
    #   10% organism relevance (is this pathogen THE cause?)
    #   10% specificity (pathogen targets are highly specific)
    confidence = (
        0.40 * drug_score
        + 0.25 * druggability
        + 0.15 * (1.0 if identifiable else 0.0)
        + 0.10 * org_relevance  # organism must match the disease
        + 0.10 * 0.9  # pathogen targets are disease-specific
    )
    confidence = round(min(1.0, max(0.0, confidence)), 4)

    # Robust if Phase 3+ with multiple drugs AND organism matches
    robustness = 0.0
    if clinical_phase >= 4:
        robustness = 0.9
    elif clinical_phase >= 3:
        robustness = 0.7
    elif clinical_phase >= 2:
        robustness = 0.5
    elif clinical_phase >= 1:
        robustness = 0.3
    if n_drugs >= 3:
        robustness = min(1.0, robustness + 0.1)

    # Penalise robustness for off-target organisms
    if org_relevance < 0.5:
        robustness *= 0.3  # heavy penalty — wrong organism

    # Evidence streams: ChEMBL drug evidence = 1 stream
    # Plus structural if PDB IDs exist
    evidence_streams = 1  # ChEMBL
    if node_data.get("pdb_ids"):
        evidence_streams += 1

    # Classification
    if confidence >= 0.6 and robustness >= 0.4:
        classification = TargetClassification.CAUSAL
        reasoning = (
            f"🦠 {gene_name} is a validated PATHOGEN drug target "
            f"({organism}). Phase {clinical_phase} with "
            f"{n_drugs} drug(s): {', '.join(drugs[:3])}. "
            f"MOA: {', '.join(moas[:2])}. "
            f"Drug evidence score: {drug_score:.2f}."
        )
    elif confidence >= 0.4:
        classification = TargetClassification.INCONCLUSIVE
        reasoning = (
            f"🦠 {gene_name} is a pathogen target ({organism}) "
            f"with Phase {clinical_phase} evidence. Confidence "
            f"{confidence:.2f} is moderate."
        )
    else:
        classification = TargetClassification.CORRELATIONAL
        reasoning = (
            f"🦠 {gene_name} ({organism}) has weak drug evidence "
            f"(Phase {clinical_phase}, confidence {confidence:.2f})."
        )

    return NeoRxResult(
        protein_id=target_id,
        protein_name=gene_name,
        gene_name=gene_name,
        uniprot_id=node_data.get("uniprot_id", ""),
        pdb_ids=node_data.get("pdb_ids", []),
        causal_confidence=confidence,
        adjustment_set=[],
        identifiable=identifiable,
        identification_reason=identification_reason,
        causal_pathway=causal_pathway,
        robustness_score=robustness,
        druggability_score=druggability,
        classification=classification,
        is_causal_target=(classification == TargetClassification.CAUSAL),
        reasoning=reasoning,
        source_scores=source_scores,
        n_supporting_pathways=0,
        n_protein_interactions=0,
        target_type="PATHOGEN_DIRECT",
        tissue_relevant=True,  # N/A for pathogen targets
        tissue_coverage=0.0,
        tissue_explanation="Pathogen target — tissue gate not applicable",
        evidence_streams=evidence_streams,
    )

Counting the evidence behind a candidate target.

How many pathways mention it, how many proteins it interacts with, how many independent databases report it, and how strongly the graph's edge weights connect it to the disease. None of this is causal inference -- it is the bookkeeping that ranks candidates once identification has said which claims are admissible.

collect_source_scores

collect_source_scores(graph: DiseaseGraph, gene_name: str) -> dict[str, float]

Collect per-source association scores for a gene.

Source code in src/neorx/core/causal/evidence.py
def collect_source_scores(
    graph: DiseaseGraph, gene_name: str,
) -> dict[str, float]:
    """Collect per-source association scores for a gene."""
    scores: dict[str, float] = {}
    for node in graph.nodes:
        if node.name.upper() == gene_name.upper():
            if node.source:
                for src in node.source.split(", "):
                    scores[src] = max(scores.get(src, 0.0), node.score)
    return scores

count_evidence_streams

count_evidence_streams(source_scores: dict[str, float], n_pathways: int, n_interactions: int, node_data: dict[str, Any]) -> int

Count independent evidence streams supporting a target.

Evidence streams: 1. Gene-disease association databases (Monarch, OpenTargets) 2. Pathway membership (KEGG, Reactome) 3. Protein-protein interactions (STRING) 4. Structural data (PDB) 5. Druggability / functional annotation (UniProt) 6. Drug evidence (ChEMBL — validated drug targets)

Each counts as ONE stream even if multiple sources within the category confirm it (e.g. both KEGG and Reactome = 1 pathway stream, not 2).

Source code in src/neorx/core/causal/evidence.py
def count_evidence_streams(
    source_scores: dict[str, float],
    n_pathways: int,
    n_interactions: int,
    node_data: dict[str, Any],
) -> int:
    """Count independent evidence streams supporting a target.

    Evidence streams:
    1. Gene-disease association databases (Monarch, OpenTargets)
    2. Pathway membership (KEGG, Reactome)
    3. Protein-protein interactions (STRING)
    4. Structural data (PDB)
    5. Druggability / functional annotation (UniProt)
    6. Drug evidence (ChEMBL — validated drug targets)

    Each counts as ONE stream even if multiple sources within
    the category confirm it (e.g. both KEGG and Reactome = 1
    pathway stream, not 2).
    """
    streams = 0

    # Stream 1: Gene-disease association databases
    assoc_sources = {"Monarch", "OpenTargets"}
    if any(s in source_scores for s in assoc_sources):
        streams += 1

    # Stream 2: Pathway membership
    if n_pathways > 0:
        streams += 1

    # Stream 3: Protein interactions
    if n_interactions > 0:
        streams += 1

    # Stream 4: 3D structural data
    pdb_ids = node_data.get("pdb_ids", [])
    if pdb_ids:
        streams += 1

    # Stream 5: Functional annotation / druggability
    metadata = node_data.get("metadata", {})
    if metadata.get("is_druggable") or metadata.get("go_terms"):
        streams += 1

    # Stream 6: ChEMBL drug evidence
    if metadata.get("chembl_drug_evidence_score") or "ChEMBL" in source_scores:
        streams += 1

    return streams

count_pathway_connections

count_pathway_connections(G: DiGraph, node_id: str) -> int

Count how many pathways this gene participates in.

Source code in src/neorx/core/causal/evidence.py
def count_pathway_connections(G: nx.DiGraph, node_id: str) -> int:
    """Count how many pathways this gene participates in."""
    count = 0
    if not G.has_node(node_id):
        return 0
    for _, target, data in G.edges(node_id, data=True):
        if data.get("edge_type") == "participates_in":
            count += 1
    # Also check incoming
    for source, _, data in G.in_edges(node_id, data=True):
        if data.get("edge_type") == "participates_in":
            count += 1
    return count

count_protein_interactions

count_protein_interactions(G: DiGraph, node_id: str) -> int

Count protein–protein interactions for this node.

Source code in src/neorx/core/causal/evidence.py
def count_protein_interactions(G: nx.DiGraph, node_id: str) -> int:
    """Count protein–protein interactions for this node."""
    count = 0
    if not G.has_node(node_id):
        return 0
    for _, _, data in G.edges(node_id, data=True):
        if data.get("edge_type") == "interacts_with":
            count += 1
    for _, _, data in G.in_edges(node_id, data=True):
        if data.get("edge_type") == "interacts_with":
            count += 1
    return count

compute_path_strength

compute_path_strength(G: DiGraph, source: str, target: str) -> float

Compute causal path strength from edge weights.

Shorter paths with higher-weight edges indicate stronger causal mechanisms.

Source code in src/neorx/core/causal/evidence.py
def compute_path_strength(
    G: nx.DiGraph, source: str, target: str,
) -> float:
    """Compute causal path strength from edge weights.

    Shorter paths with higher-weight edges indicate stronger
    causal mechanisms.
    """
    # Try directed path first
    try:
        path = nx.shortest_path(G, source, target)
        if len(path) < 2:
            return 0.0
        # Product of edge weights along path
        strength = 1.0
        for i in range(len(path) - 1):
            edata = G.get_edge_data(path[i], path[i + 1], {})
            strength *= edata.get("weight", 0.5)
        # Discount for path length (shorter = stronger)
        strength *= 1.0 / len(path)
        return strength
    except (nx.NodeNotFound, nx.NetworkXNoPath):
        pass

    # Undirected fallback (weaker evidence)
    try:
        G_u = G.to_undirected()
        path = nx.shortest_path(G_u, source, target)
        strength = 0.5 / len(path)  # Halved for undirected
        return strength
    except (nx.NodeNotFound, nx.NetworkXNoPath):
        return 0.1  # Minimal baseline

corroboration_factor

corroboration_factor(G: DiGraph, node: str) -> float

Multi-source corroboration, counted over primary evidence.

An aggregator is not a source. OmniPath re-reports interactions STRING also reports, so counting source_db values would let one curated interaction inflate the factor twice. Where an edge names its primary_sources, those are counted instead of the aggregator.

Source code in src/neorx/core/causal/evidence.py
def corroboration_factor(G: nx.DiGraph, node: str) -> float:
    """Multi-source corroboration, counted over primary evidence.

    An aggregator is not a source. OmniPath re-reports interactions
    STRING also reports, so counting ``source_db`` values would let one
    curated interaction inflate the factor twice. Where an edge names its
    ``primary_sources``, those are counted instead of the aggregator.
    """
    primary: set[str] = set()

    for _, _, attrs in list(G.edges(node, data=True)) + list(
        G.in_edges(node, data=True)
    ):
        named = attrs.get("primary_sources") or []
        if named:
            primary.update(named)
        elif attrs.get("source_db"):
            primary.add(attrs["source_db"])

    return min(1.5, 1.0 + len(primary) * 0.1)

neorx.core.graph

Graph assembly and persistence. See The graph and its sources.

Disease Causal Graph Builder

The graph builder is the first major step in the NeoRx pipeline. It queries all 8 biomedical data sources and assembles a unified causal knowledge graph for a specific disease.

Architecture
  1. Query gene–disease associations (Monarch Initiative, Open Targets) 1b. Query validated drug targets (ChEMBL — human + pathogen)
  2. Query pathway memberships (KEGG, Reactome)
  3. Query protein–protein interactions (STRING)
  4. Enrich proteins with UniProt metadata (function, PDB IDs)
  5. Query PDB structures for docking targets
  6. Merge duplicate nodes by gene symbol
  7. Build a NetworkX DiGraph ready for DoWhy causal inference
Node merging

Monarch might call it "CCR5" while Open Targets uses "ENSG00000160791". We normalise to gene symbols and merge, keeping the highest confidence score and union of all metadata.

Edge semantics
  • ASSOCIATED_WITH → gene ↔ disease (from Monarch, OT)
  • PARTICIPATES_IN → gene → pathway (from KEGG, Reactome)
  • INTERACTS_WITH → protein ↔ protein (from STRING)
  • CAUSES → the disease node → disease outcome

The causal identifier (next stage) then tests whether each gene's path to the disease outcome is causal or merely correlational using do-calculus.

build_disease_graph

build_disease_graph(disease: str, *, max_genes: int = 20, string_min_score: int = 400, use_cache: bool = True, allow_mocks: bool = False, as_of: str | None = None, resolver: SourceResolver | None = None, disease_id: str | None = None) -> DiseaseGraph

Build a comprehensive causal knowledge graph for a disease.

Parameters:

Name Type Description Default
disease str

Disease name (e.g. "HIV", "Type 2 Diabetes").

required
max_genes int

Cap on number of genes to include.

20
string_min_score int

STRING combined score threshold (0–1000).

400
use_cache bool

Check/store results in the cache layer.

True
allow_mocks bool

If True, data source clients may fall back to curated mock data when a live API call fails. If False (default), failed API calls produce empty results. Refused outright together with as_of: curated mock data is a measurement of no release, and a dated build would carry it as a node score for the date.

False
as_of str | None

A release date for a dated build. None (default) means undated, unchanged behaviour -- every source is queried live. When set, requires resolver and disease_id.

None
resolver SourceResolver | None

Resolves opentargets and omnipath -- the sources that feed the causal subgraph -- to their pinned snapshot for as_of. Resolved before any fetching begins, so a missing snapshot is refused immediately rather than after minutes of work against the other sources. It will not fall back to live data, and on a dated build the live Open Targets and OmniPath clients are not called at all.

None
disease_id str | None

EFO disease id. Required when as_of is set: the extract is keyed on EFO id and records no disease names, so a dated build cannot look one up from the snapshot, and looking it up from the API would put a live call inside a dated build. Undated, it is optional and resolved from Open Targets as before.

None

Returns:

Type Description
DiseaseGraph

Assembled graph with merged nodes and unified edges.

Dated builds and live builds are not interchangeable

On a live build a gene node's score is OpenTargets' overall association score: a harmonic sum over datasources, published by the platform. On a dated build it is the maximum genetic-evidence score in the pinned release, because the derived extract carries one row per datatype and does not carry the overall score -- and reconstructing it would mean putting a computed quantity where a measurement belongs. Both are real numbers from Open Targets, but they are different quantities: they must not be placed in the same column of a table, ranked against each other, or pooled. The full per-datatype breakdown is on both, in metadata["datatype_scores"]. See neorx.core.sources.snapshot_sources.

The gene node population of a dated build is the frame

The unpinned sources stay live on a dated build, because their edges are not causal-admissible and identification filters them out. Their nodes are another matter, and on a dated build they are restricted to the pinned release's own gene population -- they may enrich a node the release put in the graph, never introduce one, never overwrite a pinned score or a pinned node's metadata, and never take a place in the max_genes cap. See neorx.core.graph.dated_frame for what each of those channels does when it is left open.

Source code in src/neorx/core/graph/graph_builder.py
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
def build_disease_graph(
    disease: str,
    *,
    max_genes: int = 20,
    string_min_score: int = 400,
    use_cache: bool = True,
    allow_mocks: bool = False,
    as_of: str | None = None,
    resolver: SourceResolver | None = None,
    disease_id: str | None = None,
) -> DiseaseGraph:
    """Build a comprehensive causal knowledge graph for a disease.

    Parameters
    ----------
    disease : str
        Disease name (e.g. "HIV", "Type 2 Diabetes").
    max_genes : int
        Cap on number of genes to include.
    string_min_score : int
        STRING combined score threshold (0–1000).
    use_cache : bool
        Check/store results in the cache layer.
    allow_mocks : bool
        If *True*, data source clients may fall back to curated
        mock data when a live API call fails.  If *False*
        (default), failed API calls produce empty results. Refused
        outright together with ``as_of``: curated mock data is a
        measurement of no release, and a dated build would carry it as a
        node score for the date.
    as_of : str | None
        A release date for a dated build. ``None`` (default) means
        undated, unchanged behaviour -- every source is queried live.
        When set, requires ``resolver`` and ``disease_id``.
    resolver : SourceResolver | None
        Resolves ``opentargets`` and ``omnipath`` -- the sources that
        feed the causal subgraph -- to their pinned snapshot for
        ``as_of``. Resolved before any fetching begins, so a missing
        snapshot is refused immediately rather than after minutes of
        work against the other sources. It will not fall back to live
        data, and on a dated build the live Open Targets and OmniPath
        clients are not called at all.
    disease_id : str | None
        EFO disease id. Required when ``as_of`` is set: the extract is
        keyed on EFO id and records no disease names, so a dated build
        cannot look one up from the snapshot, and looking it up from the
        API would put a live call inside a dated build. Undated, it is
        optional and resolved from Open Targets as before.

    Returns
    -------
    DiseaseGraph
        Assembled graph with merged nodes and unified edges.

    Dated builds and live builds are not interchangeable
    ----------------------------------------------------
    On a **live** build a gene node's ``score`` is OpenTargets' overall
    association score: a harmonic sum over datasources, published by the
    platform. On a **dated** build it is the maximum genetic-evidence
    score in the pinned release, because the derived extract carries one
    row per datatype and does not carry the overall score -- and
    reconstructing it would mean putting a computed quantity where a
    measurement belongs. Both are real numbers from Open Targets, but
    they are *different quantities*: they must not be placed in the same
    column of a table, ranked against each other, or pooled. The full
    per-datatype breakdown is on both, in
    ``metadata["datatype_scores"]``. See
    ``neorx.core.sources.snapshot_sources``.

    The gene node population of a dated build is the frame
    ----------------------------------------------------
    The unpinned sources stay live on a dated build, because their edges
    are not causal-admissible and identification filters them out. Their
    *nodes* are another matter, and on a dated build they are restricted
    to the pinned release's own gene population -- they may enrich a node
    the release put in the graph, never introduce one, never overwrite a
    pinned score or a pinned node's metadata, and never take a place in
    the ``max_genes`` cap. See ``neorx.core.graph.dated_frame`` for what
    each of those channels does when it is left open.
    """
    ot_reader = None
    omnipath_reader = None
    if as_of is not None:
        if allow_mocks:
            raise ValueError(
                f"build_disease_graph(as_of={as_of!r}, allow_mocks=True) is "
                f"refused: mock data is a measurement of no release, and on "
                f"a dated build it would enter the graph as a node score for "
                f"{disease!r} as of {as_of}. Pass allow_mocks=False, or drop "
                f"as_of."
            )
        if resolver is None:
            raise ValueError(
                "build_disease_graph(as_of=...) requires a resolver: "
                "a dated run cannot be built without one to pin "
                "opentargets and omnipath to that date's snapshot."
            )
        if not disease_id:
            raise ValueError(
                f"build_disease_graph(as_of={as_of!r}) requires disease_id: "
                f"the pinned extract is keyed on EFO id and records no "
                f"disease names, so {disease!r} cannot be resolved from the "
                f"snapshot, and resolving it from the Open Targets API "
                f"would be a live call inside a dated build. Pass "
                f"disease_id='EFO_...' (or the MONDO/Orphanet id the "
                f"release uses)."
            )
        # Resolve the pinned sources before any fetching begins, so a
        # missing snapshot raises UnpinnedSourceError here rather than
        # after the other six sources have already been queried. These
        # are the readers the build actually uses: on a dated build
        # query_open_targets and query_omnipath are never called.
        ot_reader = resolver.resolve("opentargets", as_of)
        omnipath_reader = resolver.resolve("omnipath", as_of)

    # ── Check cache first ─────────────────────────────────────
    if use_cache:
        cache = get_cache()
        cache_key = _cache_key(
            "graph", disease=disease.lower(),
            max_genes=max_genes, string_min_score=string_min_score,
            as_of=as_of, disease_id=disease_id,
        )
        cached = cache.get(cache_key)
        if cached is not None:
            try:
                graph = DiseaseGraph.model_validate(cached)
                logger.info("Graph loaded from cache (%d nodes, %d edges).",
                            len(graph.nodes), len(graph.edges))
                return graph
            except Exception:
                pass  # Invalid cache entry — rebuild

    all_nodes: list[GraphNode] = []
    all_edges: list[GraphEdge] = []
    sources_queried: list[str] = []

    # Filled once the pinned reader has run: on a dated build its node set
    # is the frame, and every unpinned source is restricted to it. Maps
    # each identity key to the node id the release wrote -- see
    # ``neorx.core.graph.dated_frame.frame_identity``. ``None`` on an
    # undated build, where no source is restricted.
    frame: dict[str, str] | None = None
    dropped_by_source: dict[str, list[str]] = {}
    pathogens_by_source: dict[str, list[str]] = {}
    # In-frame material an unpinned source offered on a dated build and
    # did not get to contribute. Distinct from dropped_by_source, which is
    # material that was never eligible.
    withheld_by_source: dict[str, tuple[int, int]] = {}

    def admit(
        source_name: str,
        nodes: list[GraphNode],
        edges: list[GraphEdge],
    ) -> tuple[list[GraphNode], list[GraphEdge]]:
        """Take an unpinned source's contribution into the build.

        On a dated build it takes nothing. Restricting to the frame was
        not enough: an in-frame node still merged its name into the pinned
        node's ``source`` string, which ``evidence.collect_source_scores``
        splits into evidence streams and whose count is the denominator of
        the consensus term -- so an unpinned source moved every target's
        confidence without ever changing a score directly. Associational
        edges between two frame genes did the same through ``robustness``
        and ``corroboration_factor``. Neither reaches identification,
        which is why four review passes over the identification path did
        not see them.

        The restriction still runs, because what it separates out is worth
        recording: off-frame nodes and pathogen nodes are a different
        report from in-frame material that was withheld anyway.
        """
        if frame is not None:
            kept = restrict_to_frame(nodes, edges, frame)
            if kept.off_frame:
                dropped_by_source.setdefault(source_name, []).extend(
                    kept.off_frame
                )
            if kept.excluded_by_type:
                pathogens_by_source.setdefault(source_name, []).extend(
                    kept.excluded_by_type
                )
            if kept.nodes or kept.edges:
                withheld_by_source[source_name] = (
                    len(kept.nodes), len(kept.edges)
                )
            return [], []
        all_nodes.extend(nodes)
        all_edges.extend(edges)
        return nodes, edges

    # ── Step 1: Gene–Disease Associations (parallel) ──────────

    if ot_reader is None:
        ot_call = partial(
            query_open_targets, disease,
            max_results=max_genes, allow_mocks=allow_mocks,
        )
        logger.info("Querying Monarch + Open Targets for '%s' (parallel)…", disease)
    else:
        ot_call = partial(
            ot_reader, disease,
            disease_id=disease_id, max_results=max_genes,
        )
        logger.info(
            "Querying Monarch live + Open Targets pinned at %s for '%s'…",
            as_of, disease,
        )
    with ThreadPoolExecutor(max_workers=2) as pool:
        mn_future = pool.submit(
            query_monarch, disease,
            max_results=max_genes,
            allow_mocks=allow_mocks,
        )
        ot_future = pool.submit(ot_call)
        mn_nodes, mn_edges = mn_future.result()
        ot_nodes, ot_edges = ot_future.result()

    # Open Targets goes in first on a dated build, because it *is* the
    # frame: nothing else may add a gene the pinned release did not.
    all_nodes.extend(ot_nodes)
    all_edges.extend(ot_edges)
    sources_queried.append("OpenTargets")
    logger.info("  Open Targets: %d nodes, %d edges.", len(ot_nodes), len(ot_edges))

    if ot_reader is not None:
        frame = frame_identity(ot_nodes)
        logger.info(
            "Dated build frame: %d genes from the pinned release. Unpinned "
            "sources may enrich them and may not add to them.", len(frame),
        )

    mn_nodes, mn_edges = admit("Monarch", mn_nodes, mn_edges)
    sources_queried.append("Monarch")
    logger.info("  Monarch: %d nodes, %d edges.", len(mn_nodes), len(mn_edges))

    # ── Step 1b: ChEMBL Drug Targets (local SQLite) ────────────

    logger.info("Querying ChEMBL for '%s'…", disease)
    chembl_nodes, chembl_edges = query_chembl(
        disease, max_results=max_genes * 3,
        allow_mocks=allow_mocks,
    )
    chembl_nodes, chembl_edges = admit("ChEMBL", chembl_nodes, chembl_edges)
    if chembl_nodes:
        sources_queried.append("ChEMBL")
    n_pathogen = sum(
        1 for n in chembl_nodes
        if n.metadata.get("is_pathogen_target")
    )
    logger.info(
        "  ChEMBL: %d nodes (%d pathogen), %d edges.",
        len(chembl_nodes), n_pathogen, len(chembl_edges),
    )

    # Resolve disease ontology ID from Open Targets. A dated build was
    # given one -- it had to be, the snapshot is keyed on it -- and must
    # not make this live call.
    if disease_id is None:
        try:
            from neorx.core.sources.open_targets import resolve_disease_id
            disease_id = resolve_disease_id(disease)
        except Exception:
            pass

    # ── Step 2: Pathway Memberships ─────────────────────────────

    gene_symbols = _extract_gene_symbols(all_nodes, max_genes=max_genes)
    logger.info("Found %d unique gene symbols (capped at %d).",
                len(gene_symbols), max_genes)

    logger.info("Querying KEGG pathways…")
    kegg_nodes, kegg_edges = admit(
        "KEGG", *query_kegg_pathways(gene_symbols, allow_mocks=allow_mocks),
    )
    sources_queried.append("KEGG")
    logger.info("  KEGG: %d nodes, %d edges.", len(kegg_nodes), len(kegg_edges))

    logger.info("Querying Reactome pathways…")
    react_nodes, react_edges = admit(
        "Reactome",
        *query_reactome_pathways(gene_symbols, allow_mocks=allow_mocks),
    )
    sources_queried.append("Reactome")
    logger.info("  Reactome: %d nodes, %d edges.", len(react_nodes), len(react_edges))

    # ── Step 3: Protein–Protein Interactions ────────────────────

    logger.info("Querying STRING interactions…")
    string_nodes, string_edges = admit(
        "STRING",
        *query_string_interactions(
            gene_symbols, min_score=string_min_score,
            allow_mocks=allow_mocks,
        ),
    )
    sources_queried.append("STRING")
    logger.info("  STRING: %d nodes, %d edges.", len(string_nodes), len(string_edges))

    # ── Step 3b: Directed Regulatory Interactions ───────────────

    if omnipath_reader is None:
        logger.info("Querying OmniPath regulatory interactions…")
        omni_nodes, omni_edges = query_omnipath(
            gene_symbols, allow_mocks=allow_mocks,
        )
    else:
        logger.info("Reading OmniPath regulatory interactions pinned at %s…", as_of)
        omni_nodes, omni_edges = omnipath_reader(gene_symbols)
    if omnipath_reader is None:
        omni_nodes, omni_edges = admit("OmniPath", omni_nodes, omni_edges)
    else:
        # Pinned: it is not an unpinned source and is not restricted. It
        # only ever saw frame symbols, because ``gene_symbols`` is drawn
        # from a node population that is already the frame.
        all_nodes.extend(omni_nodes)
        all_edges.extend(omni_edges)
    sources_queried.append("OmniPath")
    logger.info("  OmniPath: %d directed edges.", len(omni_edges))

    if frame is not None and dropped_by_source:
        n_dropped = sum(len(names) for names in dropped_by_source.values())
        logger.info(
            "Dated build of '%s' as of %s: dropped %d off-frame gene node(s) "
            "from unpinned sources (%s). The pinned release's %d genes are "
            "the population; an unpinned source may not add to it.",
            disease, as_of, n_dropped,
            ", ".join(
                f"{source}: {len(names)} ({', '.join(sorted(set(names)))})"
                for source, names in sorted(dropped_by_source.items())
            ),
            len(frame),
        )
    if frame is not None and pathogens_by_source:
        n_pathogens = sum(len(ids) for ids in pathogens_by_source.values())
        logger.info(
            "Dated build of '%s' as of %s: excluded %d pathogen gene node(s) "
            "by node type (%s). No source in the dated stack pins a pathogen "
            "target, so its score would be today's clinical phase.",
            disease, as_of, n_pathogens,
            ", ".join(
                f"{source}: {len(ids)} ({', '.join(sorted(set(ids)))})"
                for source, ids in sorted(pathogens_by_source.items())
            ),
        )
    if frame is not None and withheld_by_source:
        logger.info(
            "Dated build of '%s' as of %s: withheld in-frame material from "
            "unpinned sources (%s). These were eligible by frame and still "
            "not taken: an unpinned node merges its name into the pinned "
            "node's source string, which becomes an evidence stream and the "
            "consensus denominator, and an unpinned edge between two frame "
            "genes moves robustness. Neither reaches identification, which "
            "is why both survived four reviews of that path.",
            disease, as_of,
            ", ".join(
                f"{source}: {n_nodes} node(s), {n_edges} edge(s)"
                for source, (n_nodes, n_edges) in sorted(
                    withheld_by_source.items()
                )
            ),
        )

    # ── Step 4: UniProt Enrichment ──────────────────────────────

    # On a dated build every gene node is pinned, and a pinned node takes
    # no enrichment -- so these two calls fetch data that is then
    # discarded. Skipping them is not only cheaper: leaving them in made a
    # DATED build depend on two live services being reachable, which is
    # the opposite of what pinning is for. A 2018 graph must not stop
    # reproducing because the PDB is down in 2029.
    #
    # It also closes a real difference: `sources_queried.append("PDB")`
    # below sat inside `if uniprot_map:`, so a dated graph's source list
    # depended on what live UniProt answered -- the graph field was not
    # invariant even though every score was.
    if as_of is None:
        logger.info("Enriching with UniProt metadata…")
        uniprot_data = query_uniprot(gene_symbols, allow_mocks=allow_mocks)
        _enrich_nodes_with_uniprot(all_nodes, uniprot_data)
        sources_queried.append("UniProt")
        logger.info("  UniProt: enriched %d/%d proteins.",
                    len(uniprot_data), len(gene_symbols))

        # ── Step 5: PDB Structures ──────────────────────────────

        uniprot_map = {
            gene: info["uniprot_id"]
            for gene, info in uniprot_data.items()
            if info.get("uniprot_id")
        }
        if uniprot_map:
            logger.info("Querying PDB structures for %d proteins…", len(uniprot_map))
            pdb_data = query_pdb_structures(uniprot_map, allow_mocks=allow_mocks)
            _enrich_nodes_with_pdb(all_nodes, pdb_data)
            sources_queried.append("PDB")
            logger.info("  PDB: structures for %d proteins.", len(pdb_data))
    else:
        logger.info(
            "UniProt and PDB skipped: every node is pinned and takes no "
            "enrichment, so a dated build must not depend on them."
        )

    # ── Step 6: Merge & Build ───────────────────────────────────

    merged_nodes, merged_edges = _merge_nodes(all_nodes, all_edges)

    # Add disease outcome node
    disease_node = GraphNode(
        node_id=f"disease:{disease.lower().replace(' ', '_')}",
        name=disease,
        node_type=NodeType.DISEASE,
        source="NeoRx",
        score=1.0,
    )
    merged_nodes.append(disease_node)

    # Connect genes directly to disease via ASSOCIATED_WITH if
    # they don't already have that edge
    existing_disease_edges = {
        (e.source_id, e.target_id) for e in merged_edges
        if e.edge_type == EdgeType.ASSOCIATED_WITH
    }
    for node in merged_nodes:
        if node.node_type in (NodeType.GENE, NodeType.PROTEIN, NodeType.PATHOGEN_GENE):
            pair = (node.node_id, disease_node.node_id)
            if pair not in existing_disease_edges:
                merged_edges.append(GraphEdge(
                    source_id=node.node_id,
                    target_id=disease_node.node_id,
                    edge_type=EdgeType.ASSOCIATED_WITH,
                    weight=node.score,
                    source_db="NeoRx",
                ))

    # Everything an unpinned source offered and did not get to
    # contribute, with the source that offered it. Carried on the graph so
    # the caller can write it to a run record: counting these in a log
    # line is the silent filter the spec warns about, and it is how frame
    # leakage returns after a refactor.
    frame_exclusions: list[dict[str, str]] = []
    for source_name, names in sorted(dropped_by_source.items()):
        frame_exclusions.extend(
            {"source": source_name, "symbol": name, "reason": "off_frame"}
            for name in sorted(set(names))
        )
    for source_name, ids in sorted(pathogens_by_source.items()):
        frame_exclusions.extend(
            {"source": source_name, "node_id": nid, "reason": "excluded_by_type"}
            for nid in sorted(set(ids))
        )
    for source_name, (n_nodes, n_edges) in sorted(withheld_by_source.items()):
        frame_exclusions.append(
            {
                "source": source_name,
                "reason": "withheld",
                "n_nodes": str(n_nodes),
                "n_edges": str(n_edges),
            }
        )

    if as_of is not None:
        # What CONTRIBUTED, not what was dialled. An unpinned source
        # contributes nothing to a dated build, so listing it here would
        # have a dated graph claim eight databases built it when two did
        # -- and the list is persisted and rendered as "Sources".
        contributed = {"OpenTargets", "OmniPath"}
        sources_queried = [s for s in sources_queried if s in contributed]

    graph = DiseaseGraph(
        disease_name=disease,
        disease_id=disease_id,
        nodes=merged_nodes,
        edges=merged_edges,
        sources_queried=sources_queried,
        as_of=as_of,
        frame_exclusions=frame_exclusions,
    )

    logger.info(
        "Graph built: %d nodes (%d genes, %d proteins, %d pathways), %d edges.",
        len(graph.nodes), graph.n_genes, graph.n_proteins,
        graph.n_pathways, len(graph.edges),
    )

    # ── Cache & persist ───────────────────────────────────────
    if use_cache:
        try:
            cache.set(cache_key, graph.model_dump(mode="json"), ttl=GRAPH_TTL)
        except Exception:
            pass

    try:
        from neorx.core.graph.persistence import save_graph_to_db
        # The upsert key is (disease_name, parameters). Without the date
        # and the ontology id in there, a dated and a live build of the
        # same disease are the same row and overwrite each other.
        save_graph_to_db(graph, params={
            "max_genes": max_genes,
            "string_min_score": string_min_score,
            "as_of": as_of,
            "disease_id": disease_id,
        })
    except Exception:
        pass

    return graph

disease_graph_to_networkx

disease_graph_to_networkx(graph: DiseaseGraph) -> nx.DiGraph

Convert a DiseaseGraph to a NetworkX directed graph.

This is needed by DoWhy for causal inference. Node attributes include node_type, score, uniprot_id, etc. Edge attributes include edge_type, weight, source_db.

Source code in src/neorx/core/graph/graph_builder.py
def disease_graph_to_networkx(graph: DiseaseGraph) -> nx.DiGraph:
    """Convert a DiseaseGraph to a NetworkX directed graph.

    This is needed by DoWhy for causal inference.  Node attributes
    include ``node_type``, ``score``, ``uniprot_id``, etc.  Edge
    attributes include ``edge_type``, ``weight``, ``source_db``.
    """
    G = nx.DiGraph()

    for node in graph.nodes:
        G.add_node(
            node.node_id,
            name=node.name,
            node_type=node.node_type.value,
            score=node.score,
            uniprot_id=node.uniprot_id or "",
            pdb_ids=node.pdb_ids,
            description=node.description or "",
            source=node.source or "",
            metadata=dict(node.metadata),
        )

    for (source_id, target_id), attrs in _resolve_edge_collisions(graph.edges).items():
        G.add_edge(source_id, target_id, **attrs)

    return G

Graph Persistence & Export

Save and load DiseaseGraph objects for reproducibility and external analysis.

Formats
  • JSON (native): Full-fidelity serialisation of DiseaseGraph
  • GraphML: For Cytoscape, yEd, and NetworkX interop
  • GEXF: For Gephi
  • Cytoscape JSON (.cyjs): For Cytoscape web/desktop
Database

When PostgreSQL is available (Docker deployment), graphs are also persisted to the disease_graphs table for querying and sharing.

save_graph

save_graph(graph: DiseaseGraph, output_dir: Path | str | None = None, fmt: str = 'json') -> str

Save a DiseaseGraph to disk.

Parameters:

Name Type Description Default
graph DiseaseGraph

The graph to save.

required
output_dir Path

Defaults to ~/.neorx/graphs/.

None
fmt str

json, graphml, gexf, or cytoscape.

'json'

Returns:

Type Description
str

Path to the saved file.

Source code in src/neorx/core/graph/persistence.py
def save_graph(
    graph: DiseaseGraph,
    output_dir: Path | str | None = None,
    fmt: str = "json",
) -> str:
    """Save a DiseaseGraph to disk.

    Parameters
    ----------
    graph : DiseaseGraph
        The graph to save.
    output_dir : Path, optional
        Defaults to ``~/.neorx/graphs/``.
    fmt : str
        ``json``, ``graphml``, ``gexf``, or ``cytoscape``.

    Returns
    -------
    str
        Path to the saved file.
    """
    if output_dir is None:
        output_dir = GRAPH_DIR
    output_dir = Path(output_dir)
    output_dir.mkdir(parents=True, exist_ok=True)

    safe_name = graph.disease_name.lower().replace(" ", "_").replace("/", "_")
    ts = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")

    if fmt == "json":
        path = output_dir / f"{safe_name}_{ts}.json"
        data = graph.model_dump(mode="json")
        path.write_text(json.dumps(data, indent=2, default=str), encoding="utf-8")

    elif fmt == "graphml":
        path = output_dir / f"{safe_name}_{ts}.graphml"
        G = _to_export_networkx(graph)
        nx.write_graphml(G, str(path))

    elif fmt == "gexf":
        path = output_dir / f"{safe_name}_{ts}.gexf"
        G = _to_export_networkx(graph)
        nx.write_gexf(G, str(path))

    elif fmt == "cytoscape":
        path = output_dir / f"{safe_name}_{ts}.cyjs"
        G = _to_export_networkx(graph)
        cy_data = nx.cytoscape_data(G)
        path.write_text(json.dumps(cy_data, indent=2), encoding="utf-8")

    else:
        raise ValueError(f"Unknown format: {fmt!r}. Use json/graphml/gexf/cytoscape.")

    logger.info("Graph saved to %s (%s format).", path, fmt)
    return str(path)

load_graph

load_graph(path: str | Path) -> DiseaseGraph

Load a DiseaseGraph from a JSON file.

Parameters:

Name Type Description Default
path str or Path

Path to a .json file saved by :func:save_graph.

required

Returns:

Type Description
DiseaseGraph
Source code in src/neorx/core/graph/persistence.py
def load_graph(path: str | Path) -> DiseaseGraph:
    """Load a DiseaseGraph from a JSON file.

    Parameters
    ----------
    path : str or Path
        Path to a ``.json`` file saved by :func:`save_graph`.

    Returns
    -------
    DiseaseGraph
    """
    path = Path(path)
    if not path.exists():
        raise FileNotFoundError(f"Graph file not found: {path}")

    data = json.loads(path.read_text(encoding="utf-8"))
    graph = DiseaseGraph.model_validate(data)

    logger.info(
        "Graph loaded from %s (%d nodes, %d edges).",
        path, len(graph.nodes), len(graph.edges),
    )
    return graph

list_saved_graphs

list_saved_graphs(directory: Path | str | None = None) -> list[dict[str, Any]]

List saved graph files with metadata.

Returns:

Type Description
list[dict]

Each dict has path, disease, n_nodes, n_edges, created, size_kb.

Source code in src/neorx/core/graph/persistence.py
def list_saved_graphs(directory: Path | str | None = None) -> list[dict[str, Any]]:
    """List saved graph files with metadata.

    Returns
    -------
    list[dict]
        Each dict has ``path``, ``disease``, ``n_nodes``, ``n_edges``,
        ``created``, ``size_kb``.
    """
    d = Path(directory) if directory else GRAPH_DIR
    if not d.exists():
        return []

    results: list[dict[str, Any]] = []
    for f in sorted(d.glob("*.json"), reverse=True):
        try:
            data = json.loads(f.read_text(encoding="utf-8"))
            results.append({
                "path": str(f),
                "disease": data.get("disease_name", "unknown"),
                "n_nodes": len(data.get("nodes", [])),
                "n_edges": len(data.get("edges", [])),
                "created": f.stat().st_mtime,
                "size_kb": round(f.stat().st_size / 1024, 1),
            })
        except (json.JSONDecodeError, KeyError):
            continue

    return results

neorx.core.graph.models

The data model shared by every stage.

NeoRx Data Models

Pydantic models for the causal drug-discovery pipeline.

The hierarchy: 1. GeneNode / ProteinNode / PathwayNode — graph entities 2. DiseaseGraph — the assembled causal knowledge graph 3. NeoRxResult — a protein evaluated as a potential target 4. ScoredCandidate — a drug candidate with composite score 5. PipelineResult — the full output of a pipeline run

Why causal reasoning matters

Most drug-discovery pipelines rank targets by correlation — which genes are differentially expressed in disease tissue? But correlation ≠ causation:

  • TNF-α is highly correlated with HIV progression, but targeting it does not treat HIV. It is a downstream consequence, not a cause.
  • HIV protease is causally upstream — inhibiting it blocks viral replication. Protease inhibitors work.

NeoRx applies Pearl's do-calculus to distinguish genuine causal targets from correlational bystanders. The NeoRxResult.is_causal_target flag captures this distinction, and the composite scorer weights causal confidence above binding affinity.

NodeType

Bases: str, Enum

Types of nodes in the disease causal graph.

Source code in src/neorx/core/graph/models.py
class NodeType(str, Enum):
    """Types of nodes in the disease causal graph."""
    GENE = "gene"
    PROTEIN = "protein"
    PATHWAY = "pathway"
    PHENOTYPE = "phenotype"
    DISEASE = "disease"
    DRUG = "drug"
    METABOLITE = "metabolite"
    PATHOGEN_GENE = "pathogen_gene"

EdgeType

Bases: str, Enum

Types of biological relationships (edges) in the graph.

Source code in src/neorx/core/graph/models.py
class EdgeType(str, Enum):
    """Types of biological relationships (edges) in the graph."""
    ACTIVATES = "activates"
    INHIBITS = "inhibits"
    PHOSPHORYLATES = "phosphorylates"
    BINDS = "binds"
    REGULATES = "regulates"
    PARTICIPATES_IN = "participates_in"
    ASSOCIATED_WITH = "associated_with"
    CAUSES = "causes"
    TREATS = "treats"
    INTERACTS_WITH = "interacts_with"
    UPREGULATES = "upregulates"
    DOWNREGULATES = "downregulates"

TargetClassification

Bases: str, Enum

Causal classification of a putative target.

Source code in src/neorx/core/graph/models.py
class TargetClassification(str, Enum):
    """Causal classification of a putative target."""
    CAUSAL = "causal"
    CORRELATIONAL = "correlational"
    INCONCLUSIVE = "inconclusive"

JobStatus

Bases: str, Enum

Pipeline execution status.

Source code in src/neorx/core/graph/models.py
class JobStatus(str, Enum):
    """Pipeline execution status."""
    PENDING = "pending"
    BUILDING_GRAPH = "building_graph"
    IDENTIFYING_TARGETS = "identifying_targets"
    GENERATING_CANDIDATES = "generating_candidates"
    SCREENING = "screening"
    SCORING = "scoring"
    REPORTING = "reporting"
    COMPLETE = "complete"
    FAILED = "failed"

GraphNode

Bases: BaseModel

A node in the disease causal graph.

Every entity (gene, protein, pathway, phenotype) is represented as a node with a unique ID, a human-readable name, and metadata from the source database.

Source code in src/neorx/core/graph/models.py
class GraphNode(BaseModel):
    """A node in the disease causal graph.

    Every entity (gene, protein, pathway, phenotype) is
    represented as a node with a unique ID, a human-readable
    name, and metadata from the source database.
    """
    node_id: str = Field(..., description="Unique identifier (e.g. ENSG00000145675)")
    name: str = Field(..., description="Human-readable name (e.g. PIK3CA)")
    node_type: NodeType = Field(..., description="Entity type")
    source: str = Field("", description="Database source (Monarch, OpenTargets, etc.)")
    score: float = Field(0.0, description="Association/confidence score from source", ge=0.0, le=1.0)
    uniprot_id: Optional[str] = Field(None, description="UniProt accession")
    pdb_ids: list[str] = Field(default_factory=list, description="Known PDB structures")
    description: Optional[str] = Field(None, description="Functional description")
    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional source metadata")

GraphEdge

Bases: BaseModel

An edge (relationship) in the disease causal graph.

Each edge represents a biological relationship with a confidence score and provenance.

Source code in src/neorx/core/graph/models.py
class GraphEdge(BaseModel):
    """An edge (relationship) in the disease causal graph.

    Each edge represents a biological relationship with a
    confidence score and provenance.
    """
    source_id: str = Field(..., description="Source node ID")
    target_id: str = Field(..., description="Target node ID")
    edge_type: EdgeType = Field(..., description="Relationship type")
    weight: float = Field(0.5, description="Confidence/evidence score", ge=0.0, le=1.0)
    source_db: str = Field("", description="Database this edge came from")
    evidence: Optional[str] = Field(None, description="Supporting evidence text")
    pmids: list[str] = Field(default_factory=list, description="PubMed IDs supporting this edge")
    evidence_class: str = Field(
        "",
        description=(
            "What kind of evidence backs this edge: genetic_association, "
            "somatic_mutation, literature, regulatory, or empty if unclassified. "
            "Causal admissibility is derived from this plus edge_type -- see "
            "causalphylo.graph_semantics."
        ),
    )
    sign: int = Field(
        0,
        description="+1 stimulation, -1 inhibition, 0 unknown or unsigned",
        ge=-1, le=1,
    )
    primary_sources: list[str] = Field(
        default_factory=list,
        description=(
            "Primary databases asserting this interaction. An aggregator such "
            "as OmniPath records the databases it drew from here, so multi-source "
            "corroboration counts distinct primary evidence rather than distinct "
            "aggregators."
        ),
    )

DiseaseGraph

Bases: BaseModel

A causal knowledge graph for a specific disease.

Assembled from multiple databases (Monarch Initiative, Open Targets, KEGG, Reactome, STRING, UniProt). The graph captures known biological relationships: which genes cause the disease, which proteins interact, which pathways are disrupted.

The graph is stored both as: - A networkx DiGraph (for DoWhy compatibility) - A list of nodes and edges (for serialisation)

Source code in src/neorx/core/graph/models.py
class DiseaseGraph(BaseModel):
    """A causal knowledge graph for a specific disease.

    Assembled from multiple databases (Monarch Initiative, Open Targets,
    KEGG, Reactome, STRING, UniProt).  The graph captures known
    biological relationships: which genes cause the disease,
    which proteins interact, which pathways are disrupted.

    The graph is stored both as:
    - A networkx ``DiGraph`` (for DoWhy compatibility)
    - A list of nodes and edges (for serialisation)
    """
    disease_name: str = Field(..., description="Disease being analysed")
    disease_id: Optional[str] = Field(None, description="Disease ontology ID (e.g. MONDO:0005109)")
    nodes: list[GraphNode] = Field(default_factory=list)
    edges: list[GraphEdge] = Field(default_factory=list)
    sources_queried: list[str] = Field(default_factory=list, description="Which databases were queried")
    frame_exclusions: list[dict[str, str]] = Field(
        default_factory=list,
        description=(
            "What an unpinned source offered a dated build and did not get "
            "to contribute, each with the source that offered it. Empty on "
            "an undated build. This rides on the graph so that whatever "
            "runs it can write it to a run record: the spec requires the "
            "exclusions to be recorded rather than merely counted, on the "
            "reasoning that a silent filter is how frame leakage returns "
            "after a refactor -- a run that suddenly excludes four hundred "
            "genes where it used to exclude twelve has had something change "
            "upstream, and that must be visible rather than absorbed. Each "
            "entry carries a `reason`: `off_frame` for a gene the release "
            "did not associate with this disease, `excluded_by_type` for a "
            "pathogen node whose score would be today's clinical phase, and "
            "`withheld` for material that was in the frame and still not "
            "taken, because an unpinned node's name reaches the consensus "
            "denominator and an unpinned edge reaches robustness."
        ),
    )
    as_of: Optional[str] = Field(
        None,
        description=(
            "The date this graph was built as of, or None for a live build. "
            "When set, the sources feeding the causal subgraph -- Open "
            "Targets and OmniPath -- were read from the release pinned to "
            "that date rather than fetched live, and a gene node's score is "
            "that release's genetic-evidence score rather than OpenTargets' "
            "overall association score. Those are different quantities: a "
            "consumer that pools dated and live graphs must read this field "
            "first. See neorx.core.sources.snapshot_sources."
        ),
    )
    build_timestamp: datetime = Field(default_factory=datetime.now)

    @property
    def n_genes(self) -> int:
        return sum(1 for n in self.nodes if n.node_type == NodeType.GENE)

    @property
    def n_proteins(self) -> int:
        return sum(1 for n in self.nodes if n.node_type == NodeType.PROTEIN)

    @property
    def n_pathways(self) -> int:
        return sum(1 for n in self.nodes if n.node_type == NodeType.PATHWAY)

NeoRxResult

Bases: BaseModel

Result of causal analysis for a single protein target.

This is the core output of the causal reasoning layer. For each protein in the disease graph, we ask: "If we intervene on this protein (i.e. inhibit/activate it with a drug), does it causally affect the disease outcome?"

We answer this using Pearl's do-calculus via DoWhy:

  1. Identifiability — Can we estimate the causal effect? The backdoor criterion checks if there is a valid set of variables to condition on that blocks all spurious paths.

  2. Evidence aggregation — How much independent support does this target have? Reported as evidence_score, not as a causal effect size: no interventional data enters it.

  3. Sensitivity analysis — Is the finding robust to removing any single source? Leave-one-source-out stability.

  4. Classification — Combine all evidence to label the protein as a genuine causal target or a correlational bystander.

Source code in src/neorx/core/graph/models.py
class NeoRxResult(BaseModel):
    """Result of causal analysis for a single protein target.

    This is the core output of the causal reasoning layer.  For
    each protein in the disease graph, we ask: "If we intervene
    on this protein (i.e. inhibit/activate it with a drug), does
    it causally affect the disease outcome?"

    We answer this using Pearl's do-calculus via DoWhy:

    1. **Identifiability** — Can we estimate the causal effect?
       The backdoor criterion checks if there is a valid set of
       variables to condition on that blocks all spurious paths.

    2. **Evidence aggregation** — How much independent support does
       this target have?  Reported as ``evidence_score``, not as a
       causal effect size: no interventional data enters it.

    3. **Sensitivity analysis** — Is the finding robust to removing
       any single source?  Leave-one-source-out stability.

    4. **Classification** — Combine all evidence to label the
       protein as a genuine causal target or a correlational
       bystander.
    """
    protein_id: str = Field(..., description="Unique protein identifier")
    protein_name: str = Field(..., description="Human-readable protein name")
    gene_name: str = Field("", description="Gene symbol (e.g. TP53)")
    uniprot_id: str = Field("", description="UniProt accession (e.g. P04637)")
    pdb_ids: list[str] = Field(default_factory=list, description="Known PDB structures")

    # Causal analysis results
    causal_confidence: float = Field(0.0, description="Combined confidence 0-1", ge=0.0, le=1.0)
    identifiable: bool = Field(
        False,
        description="Whether the backdoor criterion is satisfied for this target",
    )
    identification_reason: str = Field(
        "",
        description=(
            "Why identification succeeded or failed -- an "
            "IdentificationReason value. See causalphylo.backdoor."
        ),
    )
    adjustment_set: list[str] = Field(
        default_factory=list,
        description="Variables that must be adjusted for (backdoor); empty when not identifiable or trivially identifiable",
    )
    n_near_miss_confounders: int = Field(
        0,
        description=(
            "For a trivially identifiable target: how many nodes regulate it "
            "and have some non-admissible association with the disease. A "
            "sensitivity measure on knowledge-graph incompleteness."
        ),
    )
    adjustment_search_truncated: bool = Field(
        False,
        description="Whether the adjustment-set search hit its size or pool bound",
    )
    causal_pathway: list[str] = Field(default_factory=list, description="Path from target to disease")
    robustness_score: float = Field(0.0, description="Sensitivity analysis robustness 0-1", ge=0.0, le=1.0)
    druggability_score: float = Field(0.0, description="Predicted druggability 0-1", ge=0.0, le=1.0)

    # Classification
    classification: TargetClassification = Field(TargetClassification.INCONCLUSIVE)
    is_causal_target: bool = Field(False, description="Final: is this a genuine causal target?")
    reasoning: str = Field("", description="Human-readable causal reasoning explanation")

    # Evidence
    source_scores: dict[str, float] = Field(default_factory=dict, description="Per-database evidence scores")
    n_supporting_pathways: int = Field(0)
    n_protein_interactions: int = Field(0)

    # Biological classification (scientific-rigor layer)
    target_type: str = Field("", description="TargetType from classifier (e.g. HOST_SYMPTOM, PATHOGEN_DIRECT)")
    tissue_relevant: bool = Field(True, description="Tissue gate: True=pass (expressed in disease tissue or unknown), False=fail")
    tissue_coverage: float = Field(0.0, description="Fraction of gene tissues overlapping disease tissues (diagnostic annotation)")
    tissue_explanation: str = Field("", description="Why tissue gate passed or failed")
    counterfactual_effect: float | None = Field(None, description="Pearl's counterfactual ΔY")
    evidence_streams: int = Field(0, description="Number of independent evidence streams supporting this target")

ScoredCandidate

Bases: BaseModel

A drug candidate scored across multiple dimensions.

The composite score integrates: - Causal confidence (weight 0.30) — Is the target genuine? - Binding affinity (weight 0.25) — How tightly does it bind? - Drug-likeness (QED) (weight 0.15) — Is it drug-like? - Synthetic accessibility (weight 0.10) — Can it be made? - ADMET (weight 0.10) — Predicted pharmacokinetics - Novelty (weight 0.10) — Structural novelty vs known drugs

The key design decision: causal confidence has the HIGHEST weight. A moderately-binding molecule against a validated causal target ranks above a strongly-binding molecule against a correlational bystander.

Source code in src/neorx/core/graph/models.py
class ScoredCandidate(BaseModel):
    """A drug candidate scored across multiple dimensions.

    The composite score integrates:
    - **Causal confidence** (weight 0.30) — Is the target genuine?
    - **Binding affinity** (weight 0.25) — How tightly does it bind?
    - **Drug-likeness (QED)** (weight 0.15) — Is it drug-like?
    - **Synthetic accessibility** (weight 0.10) — Can it be made?
    - **ADMET** (weight 0.10) — Predicted pharmacokinetics
    - **Novelty** (weight 0.10) — Structural novelty vs known drugs

    The key design decision: causal confidence has the HIGHEST
    weight.  A moderately-binding molecule against a validated
    causal target ranks above a strongly-binding molecule against
    a correlational bystander.
    """
    smiles: str = Field(..., description="SMILES string")
    candidate_name: str = Field("", description="Generated name")

    # Target info
    target_protein_id: str = Field(..., description="Target this was designed for")
    target_protein_name: str = Field("", description="Target protein name")

    # Individual scores
    causal_confidence: float = Field(0.0, ge=0.0, le=1.0)
    binding_affinity: Optional[float] = Field(None, description="kcal/mol (negative = better)")
    qed_score: Optional[float] = Field(None, description="Quantitative estimate of drug-likeness")
    sa_score: Optional[float] = Field(None, description="Synthetic accessibility 1-10")
    admet_score: float = Field(0.5, description="Predicted ADMET score 0-1", ge=0.0, le=1.0)
    novelty_score: float = Field(0.5, description="Structural novelty vs known drugs 0-1", ge=0.0, le=1.0)

    # Composite
    composite_score: float = Field(0.0, description="Weighted composite score")
    score_breakdown: dict[str, float] = Field(default_factory=dict, description="Per-dimension normalised contributions")

    # Properties
    molecular_weight: Optional[float] = None
    logp: Optional[float] = None
    drug_likeness_class: str = Field("", description="Drug-likeness classification")
    n_filters_passed: int = Field(0)

    # Status flags
    is_drug_like: bool = Field(False)
    is_novel: bool = Field(False)
    rank: int = Field(0, description="Global rank across all targets")

PipelineJob

Bases: BaseModel

Tracks a pipeline execution job.

Source code in src/neorx/core/graph/models.py
class PipelineJob(BaseModel):
    """Tracks a pipeline execution job."""
    job_id: str = Field(default_factory=lambda: str(uuid.uuid4())[:8])
    disease: str = Field(...)
    status: JobStatus = Field(JobStatus.PENDING)
    top_n_targets: int = Field(5, ge=1, le=50)
    candidates_per_target: int = Field(100, ge=10)
    started_at: datetime = Field(default_factory=datetime.now)
    completed_at: Optional[datetime] = None
    error: Optional[str] = None
    progress_pct: float = Field(0.0, ge=0.0, le=100.0)
    current_step: str = Field("")

PipelineResult

Bases: BaseModel

Complete output of a NeoRx pipeline run.

Contains everything needed to understand why specific drug candidates were recommended: the disease graph, the causal reasoning for each target, and the scored candidates.

Source code in src/neorx/core/graph/models.py
class PipelineResult(BaseModel):
    """Complete output of a NeoRx pipeline run.

    Contains everything needed to understand why specific drug
    candidates were recommended: the disease graph, the causal
    reasoning for each target, and the scored candidates.
    """
    job: PipelineJob
    disease: str = Field(...)
    graph: Optional[DiseaseGraph] = None
    causal_targets: list[NeoRxResult] = Field(default_factory=list)
    scored_candidates: list[ScoredCandidate] = Field(default_factory=list)
    report_html: Optional[str] = Field(None, description="Generated HTML report")
    report_path: Optional[str] = Field(None, description="Path to saved report")
    validation: Optional[dict[str, Any]] = Field(None, description="Known-target validation results")

    @property
    def n_causal_targets(self) -> int:
        return sum(1 for t in self.causal_targets if t.is_causal_target)

    @property
    def top_candidates(self) -> list[ScoredCandidate]:
        """Top 10 candidates by composite score."""
        return sorted(self.scored_candidates, key=lambda c: c.composite_score, reverse=True)[:10]

top_candidates property

top_candidates: list[ScoredCandidate]

Top 10 candidates by composite score.

neorx.core.pipeline

NeoRx Pipeline

The pipeline orchestrates the full causal drug-discovery workflow:

  1. Build Graph → query 7 databases, assemble causal knowledge graph
  2. Identify Targets → apply do-calculus to find causal targets
  3. Generate Candidates → use GenMol VAE to create novel molecules
  4. Screen Candidates → MolScreen (drug-likeness) + DockBot (binding)
  5. Score & Rank → composite scorer with causal confidence weighting
  6. Report → generate HTML report with interactive visualisations
Integration Points
  • graph_builder.build_disease_graph() → DiseaseGraph
  • identifier.identify_causal_targets() → list[NeoRxResult]
  • neorx.genmol.generate.generate() → list[str]
  • neorx.molscreen.properties.calculate_properties() → MolecularProperties
  • neorx.molscreen.accessibility.qed_score() / sa_score()
  • neorx.molscreen.filters.run_all_filters() → list[FilterResult]
  • neorx.molscreen.similarity.find_similar_drugs() → novelty
  • neorx.dockbot.protein_prep.prepare_protein() → ProteinInfo
  • neorx.dockbot.ligand_prep.prepare_ligand_pdbqt() → (Mol, pdbqt)
  • neorx.dockbot.docker.dock() → DockingResult
  • scorer.score_candidate() → ScoredCandidate
Error Handling

Degradation is allowed only where the degraded result is still an honest one. If DockBot fails we score without binding affinity, and say so. Generation is not like that: a candidate list is either the model's output or it is not, and nothing downstream can tell the difference, so _generate_for_target raises rather than substituting anything for the trained model. A failure there fails the job, which is recorded on the PipelineJob.

run_pipeline

run_pipeline(disease: str, top_n_targets: int = 5, candidates_per_target: int = 100, *, generate_molecules: bool = True, run_docking: bool = True, generate_report: bool = True, prebuilt_graph: DiseaseGraph | None = None, allow_mocks: bool = False) -> PipelineResult

Run the full NeoRx pipeline.

Parameters:

Name Type Description Default
disease str

Disease name (e.g. "HIV", "Type 2 Diabetes").

required
top_n_targets int

Number of top causal targets to pursue.

5
candidates_per_target int

Molecules to generate per target.

100
generate_molecules bool

Whether to run GenMol generation.

True
run_docking bool

Whether to run DockBot docking.

True
generate_report bool

Whether to generate HTML report.

True
prebuilt_graph DiseaseGraph

Pre-built disease graph. If provided, Step 1 is skipped and this graph is used directly. Useful for testing and for interactive workflows where the graph was already constructed.

None
allow_mocks bool

If True, data-source clients may fall back to curated mock data when live APIs fail. Default False.

False

Returns:

Type Description
PipelineResult

Complete pipeline output with graph, targets, candidates.

Source code in src/neorx/core/pipeline/__init__.py
def run_pipeline(
    disease: str,
    top_n_targets: int = 5,
    candidates_per_target: int = 100,
    *,
    generate_molecules: bool = True,
    run_docking: bool = True,
    generate_report: bool = True,
    prebuilt_graph: DiseaseGraph | None = None,
    allow_mocks: bool = False,
) -> PipelineResult:
    """Run the full NeoRx pipeline.

    Parameters
    ----------
    disease : str
        Disease name (e.g. "HIV", "Type 2 Diabetes").
    top_n_targets : int
        Number of top causal targets to pursue.
    candidates_per_target : int
        Molecules to generate per target.
    generate_molecules : bool
        Whether to run GenMol generation.
    run_docking : bool
        Whether to run DockBot docking.
    generate_report : bool
        Whether to generate HTML report.
    prebuilt_graph : DiseaseGraph, optional
        Pre-built disease graph.  If provided, Step 1 is skipped
        and this graph is used directly.  Useful for testing and
        for interactive workflows where the graph was already
        constructed.
    allow_mocks : bool
        If *True*, data-source clients may fall back to curated
        mock data when live APIs fail.  Default *False*.

    Returns
    -------
    PipelineResult
        Complete pipeline output with graph, targets, candidates.
    """
    job = PipelineJob(disease=disease, top_n_targets=top_n_targets,
                      candidates_per_target=candidates_per_target)

    try:
        # ── Step 1: Build Disease Graph ─────────────────────────
        job.status = JobStatus.BUILDING_GRAPH
        job.current_step = "Building disease causal graph…"
        job.progress_pct = 5.0
        logger.info("═══ Step 1/6: Building disease graph for '%s' ═══", disease)

        if prebuilt_graph is not None:
            graph = prebuilt_graph
            logger.info("Using prebuilt graph (%d nodes, %d edges).",
                        len(graph.nodes), len(graph.edges))
        else:
            graph = build_disease_graph(disease, allow_mocks=allow_mocks)
        job.progress_pct = 20.0
        logger.info("Graph: %d nodes, %d edges.", len(graph.nodes), len(graph.edges))

        # ── Step 2: Identify Causal Targets ─────────────────────
        job.status = JobStatus.IDENTIFYING_TARGETS
        job.current_step = "Identifying causal targets (do-calculus)…"
        job.progress_pct = 25.0
        logger.info("═══ Step 2/6: Identifying causal targets ═══")

        causal_targets = identify_causal_targets(graph, top_n=top_n_targets)
        job.progress_pct = 40.0

        n_causal = sum(1 for t in causal_targets if t.is_causal_target)
        n_correlational = sum(1 for t in causal_targets if not t.is_causal_target)
        logger.info("Found %d causal targets, %d correlational out of %d evaluated.",
                     n_causal, n_correlational, len(causal_targets))

        for t in causal_targets:
            tag = "✓ CAUSAL" if t.is_causal_target else "✗ " + t.classification.value
            extra = ""
            if t.target_type and t.target_type != "correlational":
                extra = f" [bio:{t.target_type}]"
            if not t.tissue_relevant:
                extra += " [TISSUE-IRRELEVANT]"
            logger.info("  %s %s (confidence=%.3f)%s", tag, t.gene_name,
                        t.causal_confidence, extra)

        # ── Step 2b: Known-Target Validation ────────────────────
        validation_result = None
        try:
            from neorx.core.validator import KnownTargetValidator
            validator = KnownTargetValidator()
            identified_dicts = [
                {"gene_symbol": t.gene_name, "is_causal": t.is_causal_target}
                for t in causal_targets
            ]
            validation_result = validator.validate(disease, identified_dicts)
            if validation_result and validation_result.validated:
                logger.info(
                    "Validation: precision=%.2f, recall=%.2f, F1=%.2f, grade=%s",
                    validation_result.precision, validation_result.recall,
                    validation_result.f1, validation_result.quality_grade,
                )
                for w in validation_result.warnings:
                    logger.warning("  ⚠ %s", w)
        except Exception as e:
            logger.debug("Validation skipped: %s", e)

        # ── Step 3: Generate Candidate Molecules ────────────────
        all_candidates: list[ScoredCandidate] = []

        if generate_molecules:
            job.status = JobStatus.GENERATING_CANDIDATES
            job.current_step = "Generating candidate molecules (GenMol)…"
            job.progress_pct = 45.0
            logger.info("═══ Step 3/6: Generating candidates (GenMol) ═══")

            for target in causal_targets:
                if not target.is_causal_target:
                    continue
                smiles_list = _generate_for_target(target, candidates_per_target)
                logger.info("  %s: %d molecules generated.", target.gene_name, len(smiles_list))

                # ── Step 4: Screen candidates ───────────────────
                job.status = JobStatus.SCREENING
                job.current_step = f"Screening candidates for {target.gene_name}…"

                screened = _screen_candidates(
                    smiles_list, target, run_docking=run_docking,
                )
                all_candidates.extend(screened)

            job.progress_pct = 75.0
        else:
            logger.info("Skipping molecule generation (generate_molecules=False).")

        # ── Step 5: Score & Rank ────────────────────────────────
        job.status = JobStatus.SCORING
        job.current_step = "Scoring and ranking candidates…"
        job.progress_pct = 80.0
        logger.info("═══ Step 5/6: Scoring %d candidates ═══", len(all_candidates))

        ranked = rank_candidates(all_candidates)
        logger.info("Top 5 candidates:")
        for cand in ranked[:5]:
            logger.info(
                "  #%d  %.4f  %s  (target: %s)",
                cand.rank, cand.composite_score,
                cand.smiles[:50], cand.target_protein_name,
            )

        # ── Step 6: Generate Report ─────────────────────────────
        report_html = None
        report_path = None
        if generate_report:
            job.status = JobStatus.REPORTING
            job.current_step = "Generating report…"
            job.progress_pct = 90.0
            logger.info("═══ Step 6/6: Generating report ═══")

            try:
                from neorx.core.report import generate_report as gen_report
                report_html, report_path = gen_report(
                    disease=disease,
                    graph=graph,
                    causal_targets=causal_targets,
                    candidates=ranked,
                    validation={
                        "precision": validation_result.precision,
                        "recall": validation_result.recall,
                        "f1": validation_result.f1,
                        "quality_grade": validation_result.quality_grade,
                        "warnings": validation_result.warnings,
                    } if validation_result else None,
                )
                logger.info("Report saved to %s.", report_path)
            except Exception as e:
                logger.warning("Report generation failed: %s.", e)

        # ── Done ────────────────────────────────────────────────
        job.status = JobStatus.COMPLETE
        job.progress_pct = 100.0
        job.completed_at = datetime.now()
        job.current_step = "Pipeline complete."

        return PipelineResult(
            job=job,
            disease=disease,
            graph=graph,
            causal_targets=causal_targets,
            scored_candidates=ranked,
            report_html=report_html,
            report_path=report_path,
            validation={
                "precision": validation_result.precision,
                "recall": validation_result.recall,
                "f1": validation_result.f1,
                "quality_grade": validation_result.quality_grade,
                "true_positives": validation_result.true_positives,
                "false_positives": validation_result.false_positives_known,
                "false_negatives": validation_result.missed_targets,
                "warnings": validation_result.warnings,
            } if validation_result and validation_result.validated else None,
        )

    except Exception as e:
        logger.error("Pipeline failed: %s", e, exc_info=True)
        job.status = JobStatus.FAILED
        job.error = str(e)
        job.completed_at = datetime.now()
        return PipelineResult(job=job, disease=disease)

run_rl_pipeline

run_rl_pipeline(disease: str, top_n_targets: int = 5, n_episodes: int = 10, max_steps_per_episode: int = 50, latent_dim: int = 128, *, prebuilt_graph: DiseaseGraph | None = None, allow_mocks: bool = False, seed: int = 42) -> PipelineResult

Run the RL-driven drug-discovery pipeline.

Instead of the linear generate-then-screen flow in :func:run_pipeline, this mode trains a CausalBioRL agent inside a :class:DrugDiscoveryEnv. The agent iteratively selects targets (UCB) and navigates GenMol's latent space (CEM) to discover high-scoring molecules.

The function reuses the same graph-building and target-identification steps, but replaces Steps 3–5 with an RL optimisation loop.

Parameters:

Name Type Description Default
disease str

Disease name.

required
top_n_targets int

Number of causal targets to pursue.

5
n_episodes int

Number of RL episodes (each episode is a full campaign).

10
max_steps_per_episode int

Generate-screen cycles per episode.

50
latent_dim int

GenMol latent-space dimensionality.

128
prebuilt_graph DiseaseGraph

Pre-built disease graph (skips Step 1).

None
allow_mocks bool

Allow fallback mock data for data sources.

False
seed int

Random seed for reproducibility.

42

Returns:

Type Description
PipelineResult

Same schema as :func:run_pipeline so reports and downstream tooling work unchanged.

Source code in src/neorx/core/pipeline/__init__.py
def run_rl_pipeline(
    disease: str,
    top_n_targets: int = 5,
    n_episodes: int = 10,
    max_steps_per_episode: int = 50,
    latent_dim: int = 128,
    *,
    prebuilt_graph: DiseaseGraph | None = None,
    allow_mocks: bool = False,
    seed: int = 42,
) -> PipelineResult:
    """Run the RL-driven drug-discovery pipeline.

    Instead of the linear *generate-then-screen* flow in
    :func:`run_pipeline`, this mode trains a CausalBioRL agent
    inside a :class:`DrugDiscoveryEnv`.  The agent iteratively
    selects targets (UCB) and navigates GenMol's latent space
    (CEM) to discover high-scoring molecules.

    The function reuses the same graph-building and
    target-identification steps, but replaces Steps 3–5 with
    an RL optimisation loop.

    Parameters
    ----------
    disease : str
        Disease name.
    top_n_targets : int
        Number of causal targets to pursue.
    n_episodes : int
        Number of RL episodes (each episode is a full campaign).
    max_steps_per_episode : int
        Generate-screen cycles per episode.
    latent_dim : int
        GenMol latent-space dimensionality.
    prebuilt_graph : DiseaseGraph, optional
        Pre-built disease graph (skips Step 1).
    allow_mocks : bool
        Allow fallback mock data for data sources.
    seed : int
        Random seed for reproducibility.

    Returns
    -------
    PipelineResult
        Same schema as :func:`run_pipeline` so reports and
        downstream tooling work unchanged.
    """
    job = PipelineJob(
        disease=disease,
        top_n_targets=top_n_targets,
        candidates_per_target=max_steps_per_episode * n_episodes,
    )

    try:
        # ── Step 1: Build Disease Graph ─────────────────────────
        job.status = JobStatus.BUILDING_GRAPH
        job.current_step = "Building disease causal graph…"
        job.progress_pct = 5.0
        logger.info("═══ RL Step 1/4: Building disease graph for '%s' ═══", disease)

        if prebuilt_graph is not None:
            graph = prebuilt_graph
        else:
            graph = build_disease_graph(disease, allow_mocks=allow_mocks)
        job.progress_pct = 20.0

        # ── Step 2: Identify Causal Targets ─────────────────────
        job.status = JobStatus.IDENTIFYING_TARGETS
        job.current_step = "Identifying causal targets…"
        job.progress_pct = 25.0
        logger.info("═══ RL Step 2/4: Identifying causal targets ═══")

        causal_targets = identify_causal_targets(graph, top_n=top_n_targets)
        job.progress_pct = 35.0

        causal_only = [t for t in causal_targets if t.is_causal_target]
        logger.info("Found %d causal targets.", len(causal_only))

        # ── Step 3: RL Optimisation Loop ────────────────────────
        job.status = JobStatus.SCREENING
        job.current_step = "Running RL agent (CausalBioRL)…"
        job.progress_pct = 40.0
        logger.info("═══ RL Step 3/4: RL optimisation (%d episodes) ═══", n_episodes)

        all_candidates: list[ScoredCandidate] = []

        try:
            # Convert to the types DrugDiscoveryEnv expects
            from neorx.core.graph.graph_builder import disease_graph_to_networkx
            nx_graph = disease_graph_to_networkx(graph)

            all_candidates = generate_candidates_with_rl(
                disease,
                nx_graph,
                causal_only,
                n_episodes=n_episodes,
                max_steps_per_episode=max_steps_per_episode,
                latent_dim=latent_dim,
                seed=seed,
            )

        except ImportError as e:
            # The only recoverable failure here: CausalBioRL is optional,
            # and there is a real alternative path that produces real
            # candidates. Everything else propagates to the handler at
            # the end of this function, which marks the job FAILED and
            # records the error.
            #
            # There is deliberately no broad `except Exception` around
            # the RL loop. It used to log "collecting partial results"
            # and continue -- but all_candidates is populated
            # all-or-nothing by generate_candidates_with_rl, so there
            # were never partial results to collect: the job reported
            # COMPLETE with zero candidates and one warning line. That
            # is what hid the AttributeError from the RL stage reading a
            # `_target_states` attribute that never existed, on every
            # run, for the project's entire history.
            logger.warning(
                "CausalBioRL not available (%s) — "
                "falling back to linear pipeline.",
                e,
            )
            # Fallback: run the standard generation flow
            for target in causal_only:
                smiles_list = _generate_for_target(target, max_steps_per_episode)
                screened = _screen_candidates(smiles_list, target)
                all_candidates.extend(screened)

        # ── Step 4: Score & Rank ────────────────────────────────
        job.status = JobStatus.SCORING
        job.current_step = "Ranking RL-discovered candidates…"
        job.progress_pct = 90.0
        logger.info("═══ RL Step 4/4: Ranking %d candidates ═══", len(all_candidates))

        ranked = rank_candidates(all_candidates)

        job.status = JobStatus.COMPLETE
        job.progress_pct = 100.0
        job.completed_at = datetime.now()
        job.current_step = "RL pipeline complete."

        return PipelineResult(
            job=job,
            disease=disease,
            graph=graph,
            causal_targets=causal_targets,
            scored_candidates=ranked,
        )

    except Exception as e:
        logger.error("RL pipeline failed: %s", e, exc_info=True)
        job.status = JobStatus.FAILED
        job.error = str(e)
        job.completed_at = datetime.now()
        return PipelineResult(job=job, disease=disease)

neorx.core.scoring

Candidate ranking. See Ranking candidates.

Composite Drug-Candidate Scorer

The scorer ranks drug candidates across six dimensions:

  1. Causal confidence (0.30) — Is the target genuinely causal?
  2. Binding affinity (0.25) — How tightly does it bind?
  3. Drug-likeness (QED) (0.15) — Lipinski / Veber / QED
  4. Synthetic accessibility (0.10) — Can it be synthesised?
  5. ADMET (0.10) — Predicted pharmacokinetics
  6. Novelty (0.10) — Structural novelty vs known drugs

The critical design decision: causal confidence has the highest weight. A moderately-binding molecule aimed at a validated causal target is ranked above a tightly-binding molecule aimed at a correlational bystander. This is what distinguishes NeoRx from conventional virtual screening pipelines.

Normalisation

Raw scores live on different scales: - Binding affinity: −12 to 0 kcal/mol (more negative = better) - QED: 0 to 1 - SA score: 1 to 10 (lower = easier to synthesise) - ADMET: 0 to 1 - Novelty: 0 to 1

We normalise everything to [0, 1] where 1 = best before applying weights.

score_candidate

score_candidate(smiles: str, target_protein_id: str, target_protein_name: str, causal_confidence: float, binding_affinity: float | None = None, qed_score: float | None = None, sa_score: float | None = None, admet_score: float = 0.5, novelty_score: float = 0.5, molecular_weight: float | None = None, logp: float | None = None, drug_likeness_class: str = '', n_filters_passed: int = 0, weights: dict[str, float] | None = None) -> ScoredCandidate

Score a single drug candidate across all dimensions.

Parameters:

Name Type Description Default
smiles str

SMILES string of the candidate molecule.

required
target_protein_id str

Target protein identifier.

required
target_protein_name str

Target protein name.

required
causal_confidence float

Causal confidence for the target (0–1).

required
binding_affinity float

Docking score in kcal/mol (negative = better).

None
qed_score float

Quantitative Estimate of Drug-likeness (0–1).

None
sa_score float

Synthetic accessibility (1=easy, 10=hard).

None
admet_score float

Predicted ADMET score (0–1).

0.5
novelty_score float

Structural novelty vs known drugs (0–1).

0.5
molecular_weight float

Molecular weight in Da.

None
logp float

Predicted logP.

None
drug_likeness_class str

Drug-likeness classification.

''
n_filters_passed int

Number of drug-likeness filters passed.

0

Returns:

Type Description
ScoredCandidate

Fully scored candidate with composite score.

Source code in src/neorx/core/scoring/scorer.py
def score_candidate(
    smiles: str,
    target_protein_id: str,
    target_protein_name: str,
    causal_confidence: float,
    binding_affinity: float | None = None,
    qed_score: float | None = None,
    sa_score: float | None = None,
    admet_score: float = 0.5,
    novelty_score: float = 0.5,
    molecular_weight: float | None = None,
    logp: float | None = None,
    drug_likeness_class: str = "",
    n_filters_passed: int = 0,
    weights: dict[str, float] | None = None,
) -> ScoredCandidate:
    """Score a single drug candidate across all dimensions.

    Parameters
    ----------
    smiles : str
        SMILES string of the candidate molecule.
    target_protein_id : str
        Target protein identifier.
    target_protein_name : str
        Target protein name.
    causal_confidence : float
        Causal confidence for the target (0–1).
    binding_affinity : float, optional
        Docking score in kcal/mol (negative = better).
    qed_score : float, optional
        Quantitative Estimate of Drug-likeness (0–1).
    sa_score : float, optional
        Synthetic accessibility (1=easy, 10=hard).
    admet_score : float
        Predicted ADMET score (0–1).
    novelty_score : float
        Structural novelty vs known drugs (0–1).
    molecular_weight : float, optional
        Molecular weight in Da.
    logp : float, optional
        Predicted logP.
    drug_likeness_class : str
        Drug-likeness classification.
    n_filters_passed : int
        Number of drug-likeness filters passed.

    Returns
    -------
    ScoredCandidate
        Fully scored candidate with composite score.
    """
    # Normalise individual scores to [0, 1]
    norm_causal = _clamp(causal_confidence)
    norm_binding = normalise_affinity(binding_affinity) if binding_affinity is not None else 0.5
    norm_qed = _clamp(qed_score) if qed_score is not None else 0.5
    norm_sa = normalise_sa(sa_score) if sa_score is not None else 0.5
    norm_admet = _clamp(admet_score)
    norm_novelty = _clamp(novelty_score)

    # Resolve weights
    w = _get_weights(weights)

    # Compute weighted composite
    composite = (
        w["causal_confidence"] * norm_causal
        + w["binding_affinity"] * norm_binding
        + w["qed"] * norm_qed
        + w["sa"] * norm_sa
        + w["admet"] * norm_admet
        + w["novelty"] * norm_novelty
    )

    # Build breakdown
    breakdown = {
        "causal_confidence": round(w["causal_confidence"] * norm_causal, 4),
        "binding_affinity": round(w["binding_affinity"] * norm_binding, 4),
        "qed": round(w["qed"] * norm_qed, 4),
        "sa": round(w["sa"] * norm_sa, 4),
        "admet": round(w["admet"] * norm_admet, 4),
        "novelty": round(w["novelty"] * norm_novelty, 4),
    }

    is_drug_like = (
        norm_qed >= 0.4
        and (molecular_weight is not None and 150 <= molecular_weight <= 500)
        and n_filters_passed >= 2
    )

    return ScoredCandidate(
        smiles=smiles,
        target_protein_id=target_protein_id,
        target_protein_name=target_protein_name,
        causal_confidence=causal_confidence,
        binding_affinity=binding_affinity,
        qed_score=qed_score,
        sa_score=sa_score,
        admet_score=admet_score,
        novelty_score=novelty_score,
        composite_score=round(composite, 4),
        score_breakdown=breakdown,
        molecular_weight=molecular_weight,
        logp=logp,
        drug_likeness_class=drug_likeness_class,
        n_filters_passed=n_filters_passed,
        is_drug_like=is_drug_like,
        is_novel=novelty_score >= 0.7,
    )

rank_candidates

rank_candidates(candidates: list[ScoredCandidate]) -> list[ScoredCandidate]

Sort candidates by composite score and assign ranks.

Parameters:

Name Type Description Default
candidates list[ScoredCandidate]

Unranked scored candidates.

required

Returns:

Type Description
list[ScoredCandidate]

Ranked (best-first) with .rank set.

Source code in src/neorx/core/scoring/scorer.py
def rank_candidates(
    candidates: list[ScoredCandidate],
) -> list[ScoredCandidate]:
    """Sort candidates by composite score and assign ranks.

    Parameters
    ----------
    candidates : list[ScoredCandidate]
        Unranked scored candidates.

    Returns
    -------
    list[ScoredCandidate]
        Ranked (best-first) with ``.rank`` set.
    """
    sorted_cands = sorted(
        candidates, key=lambda c: c.composite_score, reverse=True,
    )
    for i, cand in enumerate(sorted_cands, 1):
        cand.rank = i
    return sorted_cands

normalise_affinity

normalise_affinity(affinity_kcal: float) -> float

Normalise binding affinity to [0, 1].

More negative → better → higher score.

Examples: - −12 kcal/mol → 1.0 (excellent binder) - −6 kcal/mol → 0.5 (moderate binder) - 0 kcal/mol → 0.0 (no binding)

Source code in src/neorx/core/scoring/scorer.py
def normalise_affinity(affinity_kcal: float) -> float:
    """Normalise binding affinity to [0, 1].

    More negative → better → higher score.

    Examples:
    - −12 kcal/mol → 1.0  (excellent binder)
    - −6 kcal/mol  → 0.5  (moderate binder)
    -  0 kcal/mol  → 0.0  (no binding)
    """
    return _clamp(
        (affinity_kcal - AFFINITY_WORST) / (AFFINITY_BEST - AFFINITY_WORST)
    )

normalise_sa

normalise_sa(sa_score: float) -> float

Normalise synthetic accessibility to [0, 1].

Lower SA → easier to synthesise → higher score.

Examples: - SA = 1 → 1.0 (trivially synthesisable) - SA = 5 → 0.56 (moderate) - SA = 10 → 0.0 (practically unsynthesisable)

Source code in src/neorx/core/scoring/scorer.py
def normalise_sa(sa_score: float) -> float:
    """Normalise synthetic accessibility to [0, 1].

    Lower SA → easier to synthesise → higher score.

    Examples:
    - SA = 1  → 1.0  (trivially synthesisable)
    - SA = 5  → 0.56 (moderate)
    - SA = 10 → 0.0  (practically unsynthesisable)
    """
    return _clamp(
        (SA_WORST - sa_score) / (SA_WORST - SA_BEST)
    )

ADMET Property Predictor

Multi-rule ADMET (Absorption, Distribution, Metabolism, Excretion, Toxicity) scoring based on established medicinal chemistry rules.

Rules Applied
  1. Lipinski's Rule of Five (absorption)
  2. Veber Rules (oral bioavailability)
  3. Ghose Filter (drug-likeness range)
  4. Egan Egg Model (intestinal absorption)
  5. PAINS Filter (pan-assay interference)
  6. BBB Permeability Estimate
  7. hERG Liability Estimate
  8. Reactive-Group Toxicophore Alerts

Each rule contributes to a composite ADMET score in [0, 1].

ADMETProfile dataclass

Detailed ADMET assessment for a molecule.

Source code in src/neorx/core/scoring/admet.py
@dataclass
class ADMETProfile:
    """Detailed ADMET assessment for a molecule."""

    absorption: float = 0.5
    distribution: float = 0.5
    metabolism: float = 0.5
    excretion: float = 0.5
    toxicity: float = 0.5
    composite: float = 0.5
    flags: list[str] = field(default_factory=list)
    details: dict[str, Any] = field(default_factory=dict)

predict_admet

predict_admet(smiles: str) -> ADMETProfile

Predict ADMET properties for a molecule.

Parameters:

Name Type Description Default
smiles str

SMILES string.

required

Returns:

Type Description
ADMETProfile

Multi-dimensional ADMET assessment with composite score.

Source code in src/neorx/core/scoring/admet.py
def predict_admet(smiles: str) -> ADMETProfile:
    """Predict ADMET properties for a molecule.

    Parameters
    ----------
    smiles : str
        SMILES string.

    Returns
    -------
    ADMETProfile
        Multi-dimensional ADMET assessment with composite score.
    """
    try:
        from rdkit import Chem
        from rdkit.Chem import Descriptors, rdMolDescriptors, FilterCatalog

        mol = Chem.MolFromSmiles(smiles)
        if mol is None:
            return ADMETProfile(composite=0.0, flags=["Invalid SMILES"])

        # ── Compute descriptors ─────────────────────────────────

        mw = Descriptors.MolWt(mol)
        logp = Descriptors.MolLogP(mol)
        hbd = rdMolDescriptors.CalcNumHBD(mol)
        hba = rdMolDescriptors.CalcNumHBA(mol)
        tpsa = Descriptors.TPSA(mol)
        rotatable = rdMolDescriptors.CalcNumRotatableBonds(mol)
        n_atoms = mol.GetNumHeavyAtoms()
        n_rings = rdMolDescriptors.CalcNumRings(mol)
        n_aromatic_rings = rdMolDescriptors.CalcNumAromaticRings(mol)

        flags: list[str] = []
        details: dict[str, Any] = {
            "mw": round(mw, 1),
            "logp": round(logp, 2),
            "hbd": hbd,
            "hba": hba,
            "tpsa": round(tpsa, 1),
            "rotatable_bonds": rotatable,
            "n_heavy_atoms": n_atoms,
            "n_rings": n_rings,
            "n_aromatic_rings": n_aromatic_rings,
        }

        # ── 1. Absorption (Lipinski + Veber) ────────────────────

        absorption = 1.0
        lipinski_violations = 0
        if mw > 500:
            lipinski_violations += 1
        if logp > 5:
            lipinski_violations += 1
        if hbd > 5:
            lipinski_violations += 1
        if hba > 10:
            lipinski_violations += 1

        if lipinski_violations == 0:
            absorption = 1.0
        elif lipinski_violations == 1:
            absorption = 0.7
            flags.append("Lipinski: 1 violation")
        else:
            absorption = max(0.1, 1.0 - lipinski_violations * 0.25)
            flags.append(f"Lipinski: {lipinski_violations} violations")

        # Veber rules
        if rotatable > 10:
            absorption -= 0.15
            flags.append("Veber: >10 rotatable bonds")
        if tpsa > 140:
            absorption -= 0.2
            flags.append("Veber: TPSA >140 Ų")

        details["lipinski_violations"] = lipinski_violations

        # ── 2. Distribution ─────────────────────────────────────

        distribution = 0.7

        # BBB permeability
        bbb_permeable = tpsa <= 90 and mw <= 400 and 1.0 <= logp <= 3.0
        details["bbb_permeable"] = bbb_permeable
        if bbb_permeable:
            distribution = 0.9

        # Egan egg model (intestinal absorption)
        if tpsa <= 131.6 and logp <= 5.88:
            distribution += 0.1
        else:
            distribution -= 0.1
            flags.append("Egan: poor intestinal absorption predicted")

        # Tissue accumulation risk
        if logp > 4:
            distribution -= 0.1
            flags.append("High LogP: tissue accumulation risk")

        # ── 3. Metabolism ───────────────────────────────────────

        metabolism = 0.7

        # CYP3A4 inhibition risk
        if n_aromatic_rings >= 3 and mw > 400:
            metabolism -= 0.2
            flags.append("CYP3A4 inhibition risk (aromatic + high MW)")
        elif n_aromatic_rings >= 4:
            metabolism -= 0.15
            flags.append("Multiple aromatic rings: CYP concern")

        # Metabolic stability sweet spot
        if 200 <= mw <= 450:
            metabolism += 0.1
        elif mw > 600:
            metabolism -= 0.15

        # ── 4. Excretion ────────────────────────────────────────

        excretion = 0.7

        # Renal clearance proxy
        if mw < 300 and logp < 2:
            excretion = 0.85
        elif mw > 500:
            excretion -= 0.15
            flags.append("High MW: biliary excretion likely")

        # Half-life proxy
        if 1 <= logp <= 3:
            excretion += 0.1

        # ── 5. Toxicity ─────────────────────────────────────────

        toxicity = 0.8  # Start optimistic

        # hERG liability (basic nitrogen + high LogP)
        smarts_basic_n = Chem.MolFromSmarts("[#7;+;!$([#7]~[#8])]")
        if smarts_basic_n is not None:
            has_basic_n = mol.HasSubstructMatch(smarts_basic_n)
            if has_basic_n and logp > 3.5:
                toxicity -= 0.25
                flags.append("hERG liability: basic nitrogen + high LogP")

        # PAINS check
        try:
            params = FilterCatalog.FilterCatalogParams()
            params.AddCatalog(
                FilterCatalog.FilterCatalogParams.FilterCatalogs.PAINS
            )
            catalog = FilterCatalog.FilterCatalog(params)
            if catalog.HasMatch(mol):
                toxicity -= 0.3
                flags.append("PAINS alert detected")
        except Exception:
            pass  # FilterCatalog not available in all RDKit builds

        # Reactive group alerts
        reactive_smarts = [
            ("[#6](=[#8])([F,Cl,Br,I])", "acyl halide"),
            ("[#7]=[#7]=[#7]", "azide"),
            ("[#8]-[#8]", "peroxide"),
            ("[#6]1[#6][#8]1", "epoxide"),
        ]
        for smarts_str, alert_name in reactive_smarts:
            pattern = Chem.MolFromSmarts(smarts_str)
            if pattern and mol.HasSubstructMatch(pattern):
                toxicity -= 0.2
                flags.append(f"Reactive group alert: {alert_name}")
                break

        # Ghose filter
        ghose_ok = 160 <= mw <= 480 and -0.4 <= logp <= 5.6 and 20 <= n_atoms <= 70
        details["ghose_pass"] = ghose_ok
        if not ghose_ok:
            flags.append("Ghose filter: outside drug-like range")

        # ── Composite ───────────────────────────────────────────

        absorption = max(0.0, min(1.0, absorption))
        distribution = max(0.0, min(1.0, distribution))
        metabolism = max(0.0, min(1.0, metabolism))
        excretion = max(0.0, min(1.0, excretion))
        toxicity = max(0.0, min(1.0, toxicity))

        # Weighted composite (toxicity gets extra weight)
        composite = (
            0.25 * absorption
            + 0.20 * distribution
            + 0.20 * metabolism
            + 0.15 * excretion
            + 0.20 * toxicity
        )

        return ADMETProfile(
            absorption=round(absorption, 3),
            distribution=round(distribution, 3),
            metabolism=round(metabolism, 3),
            excretion=round(excretion, 3),
            toxicity=round(toxicity, 3),
            composite=round(composite, 3),
            flags=flags,
            details=details,
        )

    except ImportError:
        logger.debug("RDKit not available for ADMET prediction.")
        return _fallback_admet(smiles)

    except Exception as e:
        logger.debug("ADMET prediction failed: %s", e)
        return _fallback_admet(smiles)

neorx.core.bio

The biological intelligence layer.

Target Classification System

Multi-level target classifier that distinguishes between biologically meaningful target categories. This prevents the critical error observed in malaria runs where host symptom markers (GABRD, SCN2A — brain neurotransmitter / ion channel proteins associated with cerebral malaria seizures) were misclassified as causal drug targets.

Target Hierarchy
  1. PATHOGEN_DIRECT — Parasite / viral protein (e.g. PfDHFR, HIV protease). Highest-priority drug target.
  2. HOST_INVASION — Host protein the pathogen directly binds / hijacks (e.g. GYPA for P. falciparum, CCR5 for HIV).
  3. HOST_IMMUNE — Host immune receptor relevant to disease response (e.g. TLR7, TLR9). Valid target but with caveats.
  4. HOST_SYMPTOM — Host protein associated with disease symptoms rather than mechanism (e.g. GABRD in cerebral malaria, coagulation factors in sepsis). Should be classified as CORRELATIONAL, not causal.
  5. CORRELATIONAL — Statistical association without any mechanistic evidence.
Disease Type Awareness

Classification behaviour changes depending on disease type: - Infectious diseases: check for pathogen vs host origin, check host-pathogen interaction evidence. - Cancers: all targets are host, but distinguish driver vs passenger mutations. - Metabolic diseases: distinguish causal pathway genes vs downstream biomarkers.

TargetType

Bases: str, Enum

Biological role of a candidate drug target.

Source code in src/neorx/core/bio/classifier.py
class TargetType(str, Enum):
    """Biological role of a candidate drug target."""
    PATHOGEN_DIRECT = "pathogen_direct"
    HOST_INVASION = "host_invasion"
    HOST_IMMUNE = "host_immune"
    HOST_SYMPTOM = "host_symptom"
    CORRELATIONAL = "correlational"

DiseaseType

Bases: str, Enum

Broad disease category affecting target classification.

Source code in src/neorx/core/bio/classifier.py
class DiseaseType(str, Enum):
    """Broad disease category affecting target classification."""
    INFECTIOUS_VIRAL = "infectious_viral"
    INFECTIOUS_PARASITIC = "infectious_parasitic"
    INFECTIOUS_BACTERIAL = "infectious_bacterial"
    GENETIC = "genetic"
    METABOLIC = "metabolic"
    CANCER = "cancer"
    AUTOIMMUNE = "autoimmune"
    NEURODEGENERATIVE = "neurodegenerative"
    OTHER = "other"

TargetClassifier

Classify targets into biologically meaningful categories.

This classifier prevents the critical error of treating host symptom markers as genuine causal drug targets. For malaria, this catches GABRD, SCN2A, etc.

The classification pipeline:

  1. Blocklist check — is the gene in a known symptom marker family (GABA receptors, sodium channels, etc.)?
  2. Inflammatory cytokine check — TNF, IL6, IL1B, CXCL8, IL10 are HOST_SYMPTOM for infections (must run before the general immune check to avoid being caught as HOST_IMMUNE).
  3. Immune receptor check — TLR, NOD, HLA, etc. are HOST_IMMUNE for infections.
  4. Disease-type-aware heuristics — for infectious diseases, check pathogen vs host origin.
Source code in src/neorx/core/bio/classifier.py
class TargetClassifier:
    """Classify targets into biologically meaningful categories.

    This classifier prevents the critical error of treating
    host symptom markers as genuine causal drug targets.  For
    malaria, this catches GABRD, SCN2A, etc.

    The classification pipeline:

    1. **Blocklist check** — is the gene in a known symptom
       marker family (GABA receptors, sodium channels, etc.)?
    2. **Inflammatory cytokine check** — TNF, IL6, IL1B,
       CXCL8, IL10 are HOST_SYMPTOM for infections (must
       run before the general immune check to avoid being
       caught as HOST_IMMUNE).
    3. **Immune receptor check** — TLR, NOD, HLA, etc.
       are HOST_IMMUNE for infections.
    4. **Disease-type-aware heuristics** — for infectious
       diseases, check pathogen vs host origin.
    """

    def classify(
        self,
        gene_symbol: str,
        disease_type: DiseaseType,
        evidence: dict[str, Any] | None = None,
    ) -> tuple[TargetType, str]:
        """Classify a single target gene.

        Parameters
        ----------
        gene_symbol : str
            Gene symbol (e.g. "GABRD", "CCR5", "EGFR").
        disease_type : DiseaseType
            The broad disease category.
        evidence : dict, optional
            Node metadata / evidence from the graph.

        Returns
        -------
        tuple[TargetType, str]
            (target_type, human-readable reason)
        """
        if evidence is None:
            evidence = {}

        gene = gene_symbol.upper().strip()

        # ── Step 1: Symptom marker blocklist ────────────────
        if gene in _SYMPTOM_MARKER_SET and is_infectious(disease_type):
            family = _SYMPTOM_FAMILY_MAP.get(gene, "unknown")
            reason = (
                f"{gene} belongs to the {family} family. "
                f"These are host neurophysiological/systemic proteins "
                f"associated with disease symptoms (e.g. seizures in "
                f"cerebral malaria, coagulopathy in sepsis), not with "
                f"pathogen biology.  Inhibiting {gene} would treat "
                f"symptoms, not the infection."
            )
            return TargetType.HOST_SYMPTOM, reason

        # For non-infectious diseases, symptom markers in
        # neurodegenerative context *are* potentially valid
        # targets (e.g. GABA receptors in epilepsy)
        if gene in _SYMPTOM_MARKER_SET and disease_type == DiseaseType.NEURODEGENERATIVE:
            # These may be legitimate targets
            pass

        # ── Step 2: Inflammatory cytokine check ─────────────
        # TNF, IL6, IL1B, CXCL8, IL10 — valid targets in
        # autoimmune diseases, but correlational in infections.
        # This check MUST run before the general immune receptor
        # check so that cytokines are classified as HOST_SYMPTOM
        # (and thus demoted) rather than HOST_IMMUNE (which is
        # not automatically demoted).
        if gene in ("TNF", "IL6", "IL1B", "CXCL8", "IL10"):
            if is_infectious(disease_type):
                reason = (
                    f"{gene} is an inflammatory cytokine elevated "
                    f"during infection.  Elevated {gene} is typically "
                    f"a *consequence* of immune activation, not a "
                    f"cause of the infection.  Blocking {gene} during "
                    f"active infection risks immune suppression."
                )
                return TargetType.HOST_SYMPTOM, reason

        # ── Step 3: Immune receptor check ───────────────────
        if self._is_immune_gene(gene):
            if is_infectious(disease_type):
                reason = (
                    f"{gene} is a host immune receptor/cytokine. "
                    f"It may modulate the immune response to infection "
                    f"but is not a direct anti-pathogen target.  "
                    f"Immunomodulatory drugs targeting {gene} could be "
                    f"adjunctive therapy but carry immune suppression risks."
                )
                return TargetType.HOST_IMMUNE, reason
            # For autoimmune diseases, immune receptors *are*
            # primary targets (e.g. TNF in RA)
            if disease_type == DiseaseType.AUTOIMMUNE:
                reason = (
                    f"{gene} is an immune system component.  For "
                    f"autoimmune diseases, immune targets are primary "
                    f"therapeutic targets."
                )
                return TargetType.HOST_INVASION, reason

        # ── Step 4: Known host-pathogen interaction check ───
        if is_infectious(disease_type):
            if self._is_known_invasion_target(gene, evidence):
                reason = (
                    f"{gene} is a host protein that directly interacts "
                    f"with the pathogen during cell entry/invasion.  "
                    f"Blocking this interaction could prevent infection."
                )
                return TargetType.HOST_INVASION, reason

        # ── Step 5: Evidence quality check ──────────────────
        evidence_types = evidence.get("evidence_types", [])
        sources = evidence.get("source", "")
        n_sources = len(sources.split(", ")) if sources else 0

        # Also count sources from metadata if available
        metadata = evidence.get("metadata", {})
        if n_sources == 0 and metadata:
            # Node has structured data even if 'source' string is empty
            n_sources = 1

        # If truly no evidence at all (no source, no metadata, no score)
        score = evidence.get("score", 0.0)
        if n_sources == 0 and not evidence_types and score == 0.0:
            reason = (
                f"{gene} has no evidence support "
                f"(no source, no mechanistic data).  "
                f"Classification as correlational pending "
                f"additional validation."
            )
            return TargetType.CORRELATIONAL, reason

        # ── Step 6: Default classification ──────────────────
        # For cancer: all targets are host, default to invasion
        if disease_type == DiseaseType.CANCER:
            reason = (
                f"{gene} is a candidate cancer target with "
                f"multi-source evidence support."
            )
            return TargetType.HOST_INVASION, reason

        # For non-infectious diseases with evidence
        reason = (
            f"{gene} has multi-source evidence support.  "
            f"Further validation recommended."
        )
        return TargetType.HOST_INVASION, reason

    def _is_immune_gene(self, gene: str) -> bool:
        """Check if gene belongs to the immune system."""
        if gene in _IMMUNE_GENES:
            return True
        return any(gene.startswith(pfx) for pfx in _IMMUNE_PREFIXES)

    def _is_known_invasion_target(
        self, gene: str, evidence: dict[str, Any],
    ) -> bool:
        """Check if this host protein is a known pathogen receptor."""
        # Curated known host-pathogen invasion targets
        known = {
            # Malaria
            "GYPA", "GYPB", "GYPC",       # Glycophorins — P. falciparum RBC invasion
            "CR1", "DARC", "BSG",          # Complement receptor 1, Duffy, Basigin
            # HIV
            "CCR5", "CXCR4", "CD4",        # HIV co-receptors
            # SARS-CoV-2
            "ACE2", "TMPRSS2", "NRP1",     # COVID-19 entry receptors
            # Ebola
            "NPC1",                         # Niemann-Pick C1 — Ebola entry
            # General
            "LAMP1",                        # Lysosome — many pathogens
        }
        if gene in known:
            return True

        # Check metadata for interaction evidence
        metadata = evidence.get("metadata", {})
        go_terms = metadata.get("go_terms", [])
        invasion_terms = {
            "GO:0046718",  # viral entry into host cell
            "GO:0044409",  # entry into host
            "GO:0020002",  # host cell plasma membrane
        }
        return bool(set(go_terms) & invasion_terms)

    def classify_batch(
        self,
        targets: list[dict[str, Any]],
        disease_type: DiseaseType,
    ) -> list[tuple[TargetType, str]]:
        """Classify a batch of targets.

        Parameters
        ----------
        targets : list[dict]
            Each dict must have ``"gene_symbol"`` and optionally
            ``"evidence"``.
        disease_type : DiseaseType
            Broad disease category.

        Returns
        -------
        list[tuple[TargetType, str]]
        """
        return [
            self.classify(
                t["gene_symbol"],
                disease_type,
                t.get("evidence"),
            )
            for t in targets
        ]

classify

classify(gene_symbol: str, disease_type: DiseaseType, evidence: dict[str, Any] | None = None) -> tuple[TargetType, str]

Classify a single target gene.

Parameters:

Name Type Description Default
gene_symbol str

Gene symbol (e.g. "GABRD", "CCR5", "EGFR").

required
disease_type DiseaseType

The broad disease category.

required
evidence dict

Node metadata / evidence from the graph.

None

Returns:

Type Description
tuple[TargetType, str]

(target_type, human-readable reason)

Source code in src/neorx/core/bio/classifier.py
def classify(
    self,
    gene_symbol: str,
    disease_type: DiseaseType,
    evidence: dict[str, Any] | None = None,
) -> tuple[TargetType, str]:
    """Classify a single target gene.

    Parameters
    ----------
    gene_symbol : str
        Gene symbol (e.g. "GABRD", "CCR5", "EGFR").
    disease_type : DiseaseType
        The broad disease category.
    evidence : dict, optional
        Node metadata / evidence from the graph.

    Returns
    -------
    tuple[TargetType, str]
        (target_type, human-readable reason)
    """
    if evidence is None:
        evidence = {}

    gene = gene_symbol.upper().strip()

    # ── Step 1: Symptom marker blocklist ────────────────
    if gene in _SYMPTOM_MARKER_SET and is_infectious(disease_type):
        family = _SYMPTOM_FAMILY_MAP.get(gene, "unknown")
        reason = (
            f"{gene} belongs to the {family} family. "
            f"These are host neurophysiological/systemic proteins "
            f"associated with disease symptoms (e.g. seizures in "
            f"cerebral malaria, coagulopathy in sepsis), not with "
            f"pathogen biology.  Inhibiting {gene} would treat "
            f"symptoms, not the infection."
        )
        return TargetType.HOST_SYMPTOM, reason

    # For non-infectious diseases, symptom markers in
    # neurodegenerative context *are* potentially valid
    # targets (e.g. GABA receptors in epilepsy)
    if gene in _SYMPTOM_MARKER_SET and disease_type == DiseaseType.NEURODEGENERATIVE:
        # These may be legitimate targets
        pass

    # ── Step 2: Inflammatory cytokine check ─────────────
    # TNF, IL6, IL1B, CXCL8, IL10 — valid targets in
    # autoimmune diseases, but correlational in infections.
    # This check MUST run before the general immune receptor
    # check so that cytokines are classified as HOST_SYMPTOM
    # (and thus demoted) rather than HOST_IMMUNE (which is
    # not automatically demoted).
    if gene in ("TNF", "IL6", "IL1B", "CXCL8", "IL10"):
        if is_infectious(disease_type):
            reason = (
                f"{gene} is an inflammatory cytokine elevated "
                f"during infection.  Elevated {gene} is typically "
                f"a *consequence* of immune activation, not a "
                f"cause of the infection.  Blocking {gene} during "
                f"active infection risks immune suppression."
            )
            return TargetType.HOST_SYMPTOM, reason

    # ── Step 3: Immune receptor check ───────────────────
    if self._is_immune_gene(gene):
        if is_infectious(disease_type):
            reason = (
                f"{gene} is a host immune receptor/cytokine. "
                f"It may modulate the immune response to infection "
                f"but is not a direct anti-pathogen target.  "
                f"Immunomodulatory drugs targeting {gene} could be "
                f"adjunctive therapy but carry immune suppression risks."
            )
            return TargetType.HOST_IMMUNE, reason
        # For autoimmune diseases, immune receptors *are*
        # primary targets (e.g. TNF in RA)
        if disease_type == DiseaseType.AUTOIMMUNE:
            reason = (
                f"{gene} is an immune system component.  For "
                f"autoimmune diseases, immune targets are primary "
                f"therapeutic targets."
            )
            return TargetType.HOST_INVASION, reason

    # ── Step 4: Known host-pathogen interaction check ───
    if is_infectious(disease_type):
        if self._is_known_invasion_target(gene, evidence):
            reason = (
                f"{gene} is a host protein that directly interacts "
                f"with the pathogen during cell entry/invasion.  "
                f"Blocking this interaction could prevent infection."
            )
            return TargetType.HOST_INVASION, reason

    # ── Step 5: Evidence quality check ──────────────────
    evidence_types = evidence.get("evidence_types", [])
    sources = evidence.get("source", "")
    n_sources = len(sources.split(", ")) if sources else 0

    # Also count sources from metadata if available
    metadata = evidence.get("metadata", {})
    if n_sources == 0 and metadata:
        # Node has structured data even if 'source' string is empty
        n_sources = 1

    # If truly no evidence at all (no source, no metadata, no score)
    score = evidence.get("score", 0.0)
    if n_sources == 0 and not evidence_types and score == 0.0:
        reason = (
            f"{gene} has no evidence support "
            f"(no source, no mechanistic data).  "
            f"Classification as correlational pending "
            f"additional validation."
        )
        return TargetType.CORRELATIONAL, reason

    # ── Step 6: Default classification ──────────────────
    # For cancer: all targets are host, default to invasion
    if disease_type == DiseaseType.CANCER:
        reason = (
            f"{gene} is a candidate cancer target with "
            f"multi-source evidence support."
        )
        return TargetType.HOST_INVASION, reason

    # For non-infectious diseases with evidence
    reason = (
        f"{gene} has multi-source evidence support.  "
        f"Further validation recommended."
    )
    return TargetType.HOST_INVASION, reason

classify_batch

classify_batch(targets: list[dict[str, Any]], disease_type: DiseaseType) -> list[tuple[TargetType, str]]

Classify a batch of targets.

Parameters:

Name Type Description Default
targets list[dict]

Each dict must have "gene_symbol" and optionally "evidence".

required
disease_type DiseaseType

Broad disease category.

required

Returns:

Type Description
list[tuple[TargetType, str]]
Source code in src/neorx/core/bio/classifier.py
def classify_batch(
    self,
    targets: list[dict[str, Any]],
    disease_type: DiseaseType,
) -> list[tuple[TargetType, str]]:
    """Classify a batch of targets.

    Parameters
    ----------
    targets : list[dict]
        Each dict must have ``"gene_symbol"`` and optionally
        ``"evidence"``.
    disease_type : DiseaseType
        Broad disease category.

    Returns
    -------
    list[tuple[TargetType, str]]
    """
    return [
        self.classify(
            t["gene_symbol"],
            disease_type,
            t.get("evidence"),
        )
        for t in targets
    ]

classify_disease

classify_disease(disease_name: str) -> DiseaseType

Determine the broad disease category from the disease name.

Uses a curated lookup table; falls back to OTHER for unrecognised diseases.

Source code in src/neorx/core/bio/classifier.py
def classify_disease(disease_name: str) -> DiseaseType:
    """Determine the broad disease category from the disease name.

    Uses a curated lookup table; falls back to ``OTHER`` for
    unrecognised diseases.
    """
    key = disease_name.strip().lower()
    if key in DISEASE_TYPE_MAP:
        return DISEASE_TYPE_MAP[key]

    # Heuristic substring matching for partial matches
    for pattern, dtype in DISEASE_TYPE_MAP.items():
        if pattern in key or key in pattern:
            return dtype

    # Cancer heuristic
    if any(w in key for w in ("cancer", "carcinoma", "sarcoma",
                               "blastoma", "oma", "leukemia",
                               "lymphoma", "myeloma")):
        return DiseaseType.CANCER

    return DiseaseType.OTHER

neorx.core.sources

One function per source. Each returns tuple[list[GraphNode], list[GraphEdge]] and returns empty lists rather than raising, so the graph builder can aggregate what answered.

Data Sources

API clients for biomedical databases used to build disease causal graphs. Each client follows the same pattern:

  1. Query the database for disease-associated entities
  2. Parse the response into GraphNode and GraphEdge objects
  3. Handle rate limits, timeouts, and API errors gracefully
  4. Return empty lists (never crash) on failure — the graph builder aggregates results from multiple sources

All clients use requests and are synchronous. For production, consider httpx with async support.

All HTTP traffic in this package is subject to recording. When these modules run inside neorx.experiments.capture, every request and response is frozen into the run's cassette so the run can be replayed exactly. Adding a source that uses a client other than requests will silently escape that recording -- see neorx/experiments/capture.py.

query_monarch, query_open_targets, query_kegg_pathways, query_reactome_pathways, query_string_interactions, query_omnipath, query_uniprot, query_pdb_structures, query_chembl.

neorx.snapshots

The versioned data layer. See Versioned snapshots.

The canonical shape of a derived extract.

Three OpenTargets format eras feed this pipeline: a flat gzipped JSON dump in 2018, an ETL-era Parquet tree in 2021, and the current output layout. Each gets its own reader, and each reader's job is to produce exactly the columns below. Downstream code -- the frame, the resolver, the graph builder -- never learns which era a row came from.

That is the whole value of a derived extract rather than a mirror: format drift is absorbed once, at the edge, instead of leaking into every consumer.

ExtractNotes dataclass

What a reader had to do to the source that the rows no longer show.

Both facts are recorded rather than defaulted away, because both change what the extract means and neither is visible in the extract itself. consensus_direction_synthesised says the 2018 archive had no such column and is_directed was used in its place -- a weaker criterion than later eras publish. non_human_rows_dropped says how many rows the organism filter removed; a count of zero on a real OmniPath archive means the filter did not fire, not that the dump was human-only.

Source code in src/neorx/snapshots/schema.py
@dataclass(frozen=True)
class ExtractNotes:
    """What a reader had to do to the source that the rows no longer show.

    Both facts are recorded rather than defaulted away, because both change
    what the extract means and neither is visible in the extract itself.
    ``consensus_direction_synthesised`` says the 2018 archive had no such
    column and ``is_directed`` was used in its place -- a weaker criterion
    than later eras publish. ``non_human_rows_dropped`` says how many rows
    the organism filter removed; a count of zero on a real OmniPath archive
    means the filter did not fire, not that the dump was human-only.
    """

    consensus_direction_synthesised: bool = False
    non_human_rows_dropped: int = 0

empty_associations

empty_associations() -> pl.DataFrame

An empty association frame with the canonical schema.

Source code in src/neorx/snapshots/schema.py
def empty_associations() -> pl.DataFrame:
    """An empty association frame with the canonical schema."""
    return pl.DataFrame(schema=ASSOCIATION_COLUMNS)

empty_interactions

empty_interactions() -> pl.DataFrame

An empty interaction frame with the canonical schema.

Source code in src/neorx/snapshots/schema.py
def empty_interactions() -> pl.DataFrame:
    """An empty interaction frame with the canonical schema."""
    return pl.DataFrame(schema=INTERACTION_COLUMNS)

What a snapshot records about itself.

A release identifier alone does not identify a derived extract. Two extracts of OpenTargets 18.06 produced by different extractor code are different inputs to every number computed downstream, so the extractor version is recorded beside the release id, and the digest is taken over the extract actually written rather than the upstream file.

Keyed by (source, release), so re-running an extraction replaces its entry instead of appending a second one.

SnapshotEntry dataclass

One derived extract, and everything needed to identify it.

Source code in src/neorx/snapshots/manifest.py
@dataclass(frozen=True)
class SnapshotEntry:
    """One derived extract, and everything needed to identify it."""

    source: str
    release: str
    url: str
    sha256: str
    extractor_version: int
    rows: int
    synthesised_consensus: bool = False

read_manifest

read_manifest(manifest_path: Path) -> dict[tuple[str, str], SnapshotEntry]

Read every entry, keyed by (source, release). Absent file: no entries.

Source code in src/neorx/snapshots/manifest.py
def read_manifest(manifest_path: Path) -> dict[tuple[str, str], SnapshotEntry]:
    """Read every entry, keyed by (source, release). Absent file: no entries."""
    path = Path(manifest_path)
    if not path.exists():
        return {}

    data = tomllib.loads(path.read_text(encoding="utf-8"))
    entries: dict[tuple[str, str], SnapshotEntry] = {}
    for source, releases in (data.get("snapshot") or {}).items():
        for release, fields in releases.items():
            entry = SnapshotEntry(source=source, release=release, **fields)
            entries[(source, release)] = entry
    return entries

write_entry

write_entry(manifest_path: Path, entry: SnapshotEntry) -> None

Insert or replace one entry, leaving every other entry untouched.

Source code in src/neorx/snapshots/manifest.py
def write_entry(manifest_path: Path, entry: SnapshotEntry) -> None:
    """Insert or replace one entry, leaving every other entry untouched."""
    path = Path(manifest_path)
    data = tomllib.loads(path.read_text(encoding="utf-8")) if path.exists() else {}

    fields = asdict(entry)
    source = fields.pop("source")
    release = fields.pop("release")

    data.setdefault("snapshot", {}).setdefault(source, {})[release] = fields
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(tomli_w.dumps(data), encoding="utf-8")

digest_file

digest_file(path: Path) -> str

SHA-256 of a file, read in chunks so a large extract does not load.

Source code in src/neorx/snapshots/manifest.py
def digest_file(path: Path) -> str:
    """SHA-256 of a file, read in chunks so a large extract does not load."""
    h = hashlib.sha256()
    with open(path, "rb") as fh:
        for chunk in iter(lambda: fh.read(1024 * 1024), b""):
            h.update(chunk)
    return h.hexdigest()

Reading derived extracts back off disk.

This layer knows the on-disk layout and nothing else. By the time a frame reaches it, which upstream era produced it is invisible -- that is the whole point of extracting to a canonical schema.

A missing snapshot raises rather than returning an empty frame. An empty frame reads downstream as "this release recorded no evidence for that disease", which is a finding; a missing extract is a configuration mistake, and the two must not be confusable.

SnapshotStore

Derived extracts under a root directory.

Layout::

<root>/opentargets/<release>/associations.parquet
<root>/omnipath/<release>/interactions.parquet
<root>/manifest.toml
Source code in src/neorx/snapshots/reader.py
class SnapshotStore:
    """Derived extracts under a root directory.

    Layout::

        <root>/opentargets/<release>/associations.parquet
        <root>/omnipath/<release>/interactions.parquet
        <root>/manifest.toml
    """

    _FILES = {
        "opentargets": "associations.parquet",
        "omnipath": "interactions.parquet",
    }

    def __init__(
        self,
        root: Path,
        *,
        on_read: Callable[[str, str, Path], None] | None,
    ) -> None:
        """``on_read(source, release, path)`` runs after every extract read.

        It is how a run record learns what a run actually read, so it can
        cite exactly that -- from this store's own manifest, rather than
        from a second path that might name a different store.

        Required, with no default, deliberately. When it defaulted to
        ``None`` an experiment could read one extract through
        ``RunRecord.snapshot_store`` and another through a store it built
        itself, and finish `complete` and `citable` while citing only the
        first: the runner's guard fires when NO read was tracked, not when
        some were missed. It cannot see a store it was never told about,
        so the construction has to say. ``on_read=None`` is still
        available -- for the CLI and for unit tests of the reader -- but
        it is now written down rather than inherited.
        """
        self.root = Path(root)
        self._on_read = on_read

    @property
    def manifest_path(self) -> Path:
        """The manifest describing the extracts under this root.

        Derived from the root rather than configured beside it, so the
        extracts a run reads and the manifest it cites cannot come from two
        different places.
        """
        return self.root / "manifest.toml"

    def _path(self, source: str, release: str) -> Path:
        return self.root / source / release / self._FILES[source]

    def has(self, source: str, release: str) -> bool:
        """Whether an extract exists, without raising."""
        if source not in self._FILES:
            return False
        return self._path(source, release).exists()

    def _read(self, source: str, release: str) -> pl.DataFrame:
        path = self._path(source, release)
        if not path.exists():
            raise SnapshotMissingError(
                f"No {source} snapshot for release {release!r} at {path}. "
                f"Build it with `neorx snapshot build {source} {release}`. "
                f"A dated run will not fall back to live data."
            )
        frame = pl.read_parquet(path)
        if self._on_read is not None:
            # The path too: a citation has to be checked against the bytes
            # that were actually read, not just against the manifest.
            self._on_read(source, release, path)
        return frame

    def associations(self, release: str) -> pl.DataFrame:
        """Canonical association rows for an OpenTargets release."""
        return self._read("opentargets", release)

    def interactions(self, release: str) -> pl.DataFrame:
        """Canonical interaction rows for an OmniPath archive date."""
        return self._read("omnipath", release)

manifest_path property

manifest_path: Path

The manifest describing the extracts under this root.

Derived from the root rather than configured beside it, so the extracts a run reads and the manifest it cites cannot come from two different places.

__init__

__init__(root: Path, *, on_read: Callable[[str, str, Path], None] | None) -> None

on_read(source, release, path) runs after every extract read.

It is how a run record learns what a run actually read, so it can cite exactly that -- from this store's own manifest, rather than from a second path that might name a different store.

Required, with no default, deliberately. When it defaulted to None an experiment could read one extract through RunRecord.snapshot_store and another through a store it built itself, and finish complete and citable while citing only the first: the runner's guard fires when NO read was tracked, not when some were missed. It cannot see a store it was never told about, so the construction has to say. on_read=None is still available -- for the CLI and for unit tests of the reader -- but it is now written down rather than inherited.

Source code in src/neorx/snapshots/reader.py
def __init__(
    self,
    root: Path,
    *,
    on_read: Callable[[str, str, Path], None] | None,
) -> None:
    """``on_read(source, release, path)`` runs after every extract read.

    It is how a run record learns what a run actually read, so it can
    cite exactly that -- from this store's own manifest, rather than
    from a second path that might name a different store.

    Required, with no default, deliberately. When it defaulted to
    ``None`` an experiment could read one extract through
    ``RunRecord.snapshot_store`` and another through a store it built
    itself, and finish `complete` and `citable` while citing only the
    first: the runner's guard fires when NO read was tracked, not when
    some were missed. It cannot see a store it was never told about,
    so the construction has to say. ``on_read=None`` is still
    available -- for the CLI and for unit tests of the reader -- but
    it is now written down rather than inherited.
    """
    self.root = Path(root)
    self._on_read = on_read

has

has(source: str, release: str) -> bool

Whether an extract exists, without raising.

Source code in src/neorx/snapshots/reader.py
def has(self, source: str, release: str) -> bool:
    """Whether an extract exists, without raising."""
    if source not in self._FILES:
        return False
    return self._path(source, release).exists()

associations

associations(release: str) -> pl.DataFrame

Canonical association rows for an OpenTargets release.

Source code in src/neorx/snapshots/reader.py
def associations(self, release: str) -> pl.DataFrame:
    """Canonical association rows for an OpenTargets release."""
    return self._read("opentargets", release)

interactions

interactions(release: str) -> pl.DataFrame

Canonical interaction rows for an OmniPath archive date.

Source code in src/neorx/snapshots/reader.py
def interactions(self, release: str) -> pl.DataFrame:
    """Canonical interaction rows for an OmniPath archive date."""
    return self._read("omnipath", release)

SnapshotMissingError

Bases: FileNotFoundError

No extract exists for a requested source and release.

Source code in src/neorx/snapshots/reader.py
class SnapshotMissingError(FileNotFoundError):
    """No extract exists for a requested source and release."""

Choosing between a live client and a snapshot reader.

With no date, every source resolves to the live client it always used and behaviour is unchanged -- interactive single-disease use is unaffected by this whole sub-project.

With a date, the sources feeding the causal subgraph resolve to snapshot readers, and a source with no snapshot at that date is refused by name. The refusal matters more than it looks: a dated run that quietly mixed in current data would produce exactly the anachronistic graph this sub-project exists to prevent, and would do it invisibly.

Sources that contribute only associational edges stay live even on a dated run. Identification filters those edges out before it runs, so pinning them would buy rigour against a leak that does not exist.

SourceResolver

Maps a source name plus an optional date to a reader.

release_for(source, as_of) maps a date to a release identifier, so the date-to-release table lives in one place rather than at every call site.

Source code in src/neorx/snapshots/resolver.py
class SourceResolver:
    """Maps a source name plus an optional date to a reader.

    ``release_for(source, as_of)`` maps a date to a release identifier, so
    the date-to-release table lives in one place rather than at every call
    site.
    """

    def __init__(
        self,
        store: _Store,
        release_for: Callable[[str, str], str],
        live: dict[str, Callable[..., object]],
    ) -> None:
        self._store = store
        self._release_for = release_for
        self._live = live

    def resolve(self, source: str, as_of: str | None) -> Callable[..., object]:
        """Return the reader for this source at this date.

        Undated, or unpinned, this is the live client itself. Dated and
        pinned, it is a snapshot reader bound to the release, returning
        the same ``tuple[list[GraphNode], list[GraphEdge]]`` the live
        client returns -- so the caller assembles a dated graph through
        the same code path as a live one and cannot accidentally hold a
        reader it does not know how to call.

        Raises ``UnpinnedSourceError`` if the date requires a snapshot that
        does not exist. It does not fall back to the live client.
        """
        if as_of is None or source not in PINNED_SOURCES:
            return self._live[source]

        release = self._release_for(source, as_of)
        if not self._store.has(source, release):
            raise UnpinnedSourceError(
                f"A run dated {as_of} needs the {source} snapshot for release "
                f"{release!r}, which has not been built. Build it with "
                f"`neorx snapshot build {source} {release}`. This will not "
                f"fall back to live data: doing so would silently mix current "
                f"evidence into a dated graph."
            )

        return snapshot_reader(source, self._store, release)

resolve

resolve(source: str, as_of: str | None) -> Callable[..., object]

Return the reader for this source at this date.

Undated, or unpinned, this is the live client itself. Dated and pinned, it is a snapshot reader bound to the release, returning the same tuple[list[GraphNode], list[GraphEdge]] the live client returns -- so the caller assembles a dated graph through the same code path as a live one and cannot accidentally hold a reader it does not know how to call.

Raises UnpinnedSourceError if the date requires a snapshot that does not exist. It does not fall back to the live client.

Source code in src/neorx/snapshots/resolver.py
def resolve(self, source: str, as_of: str | None) -> Callable[..., object]:
    """Return the reader for this source at this date.

    Undated, or unpinned, this is the live client itself. Dated and
    pinned, it is a snapshot reader bound to the release, returning
    the same ``tuple[list[GraphNode], list[GraphEdge]]`` the live
    client returns -- so the caller assembles a dated graph through
    the same code path as a live one and cannot accidentally hold a
    reader it does not know how to call.

    Raises ``UnpinnedSourceError`` if the date requires a snapshot that
    does not exist. It does not fall back to the live client.
    """
    if as_of is None or source not in PINNED_SOURCES:
        return self._live[source]

    release = self._release_for(source, as_of)
    if not self._store.has(source, release):
        raise UnpinnedSourceError(
            f"A run dated {as_of} needs the {source} snapshot for release "
            f"{release!r}, which has not been built. Build it with "
            f"`neorx snapshot build {source} {release}`. This will not "
            f"fall back to live data: doing so would silently mix current "
            f"evidence into a dated graph."
        )

    return snapshot_reader(source, self._store, release)

UnpinnedSourceError

Bases: RuntimeError

A dated run asked for a source that has no snapshot at that date.

Source code in src/neorx/snapshots/resolver.py
class UnpinnedSourceError(RuntimeError):
    """A dated run asked for a source that has no snapshot at that date."""

Which release a date resolves to, for each pinned source.

SourceResolver takes release_for as an injected callable so the date-to-release table lives in one place instead of at every call site. Until now the only implementations were lambdas inside tests, which meant no production path could run a dated build at all: the machinery existed and nothing could reach it.

Every entry here was verified against the live archive on 2026-09-06 by listing it, not by reading the spec's table. Two of the three pairings are as close as that table claimed; the third is not, and the discrepancy is recorded rather than smoothed over.

UnknownTimePointError

Bases: KeyError

A date with no pinned release table entry.

Source code in src/neorx/snapshots/releases.py
class UnknownTimePointError(KeyError):
    """A date with no pinned release table entry."""

release_for

release_for(source: str, as_of: str) -> str

The release identifier source is pinned to at as_of.

Raises rather than guessing. A dated run that silently fell back to some nearby release would produce exactly the anachronistic graph this sub-project exists to prevent, and would do it invisibly -- the same reasoning that makes SourceResolver refuse an unbuilt snapshot instead of using the live client.

Source code in src/neorx/snapshots/releases.py
def release_for(source: str, as_of: str) -> str:
    """The release identifier ``source`` is pinned to at ``as_of``.

    Raises rather than guessing. A dated run that silently fell back to
    some nearby release would produce exactly the anachronistic graph this
    sub-project exists to prevent, and would do it invisibly -- the same
    reasoning that makes ``SourceResolver`` refuse an unbuilt snapshot
    instead of using the live client.
    """
    try:
        point = TIME_POINTS[as_of]
    except KeyError:
        raise UnknownTimePointError(
            f"No pinned releases for {as_of!r}. Known time points: "
            f"{', '.join(sorted(TIME_POINTS))}. Add one to "
            f"neorx.snapshots.releases.TIME_POINTS only after verifying "
            f"against the upstream archive that both releases exist."
        ) from None

    try:
        return point[source]
    except KeyError:
        raise UnknownTimePointError(
            f"{as_of!r} pins no release for source {source!r}. Pinned "
            f"sources at that date: "
            f"{', '.join(s for s in sorted(point) if not s.endswith('_data_as_of'))}."
        ) from None

omnipath_archive_url

omnipath_archive_url(as_of: str) -> str

The archive URL for the OmniPath dump pinned to as_of.

Every dump is .tsv.xz; the builder detects compression from the file's magic bytes rather than this extension, because an archive URL's extension is a claim and this one was wrong in the spec for the life of the sub-project.

Source code in src/neorx/snapshots/releases.py
def omnipath_archive_url(as_of: str) -> str:
    """The archive URL for the OmniPath dump pinned to ``as_of``.

    Every dump is ``.tsv.xz``; the builder detects compression from the
    file's magic bytes rather than this extension, because an archive
    URL's extension is a claim and this one was wrong in the spec for the
    life of the sub-project.
    """
    release = release_for("omnipath", as_of)
    return f"{_ARCHIVE_ROOT}/omnipath_webservice_interactions__{release}.tsv.xz"

neorx.experiments

The run-record system. See Experiments and run records.

Run records: the artifact that makes a reported number traceable.

A record is written incrementally. Rows land on disk as each cell of an experiment completes, so a crash costs the current cell rather than the run -- the failure that lost 881 seconds of the original RL benchmark and led to its numbers being retyped by hand.

Nothing here degrades on error. A record that cannot be written is a failed run, not a quiet one.

RunRecord

One execution of one experiment.

Source code in src/neorx/experiments/record.py
class RunRecord:
    """One execution of one experiment."""

    def __init__(self, run_id: str, path: Path, *, allow_large: bool = False) -> None:
        self.run_id = run_id
        self.path = path
        self.status = "incomplete"
        self.citable = False
        self._allow_large = allow_large
        self._n_rows = 0
        # Set by create() only -- a record produced by load() never learns
        # its start time or experiment name from these fields (finalise()
        # falls back to run_id via getattr for the latter).
        self._started: datetime | None = None
        self._experiment: str | None = None
        # (source, release) -> (manifest describing it, extract actually read)
        self._snapshot_reads: dict[tuple[str, str], tuple[Path, Path]] = {}

    # -- construction --------------------------------------------------

    @classmethod
    def create(
        cls,
        experiment: str,
        *,
        runs_dir: Path | None = None,
        allow_large: bool = False,
    ) -> RunRecord:
        started = datetime.now(UTC)
        sha = _git_sha()
        digest = hashlib.sha256(f"{started.isoformat()}{sha}".encode()).hexdigest()[:6]
        run_id = f"{started:%Y-%m-%d}-{experiment}-{digest}"

        base = runs_dir if runs_dir is not None else RUNS_DIR
        path = base / run_id
        try:
            (path / "inputs").mkdir(parents=True, exist_ok=False)
        except FileExistsError:
            raise RunIDCollisionError(
                f"run id {run_id!r} already exists at {path}; refusing to "
                "write into an existing run's directory"
            ) from None

        rec = cls(run_id, path, allow_large=allow_large)
        rec._started = started
        rec._experiment = experiment
        (path / "rows.jsonl").touch()

        (path / "env.json").write_text(
            json.dumps(
                {
                    "git_sha": sha,
                    "git_dirty": _git_dirty(),
                    "python": platform.python_version(),
                    "platform": platform.platform(),
                    "started_utc": started.isoformat(),
                    "deps": _dep_versions(),
                    # Filled by settle_snapshot_citations once the run has
                    # read what it reads -- a citation is a statement about
                    # what produced the numbers, so it cannot be written
                    # before any were produced.
                    "snapshots": {},
                },
                indent=2,
            )
        )
        return rec

    # -- snapshot provenance --------------------------------------------

    def snapshot_store(self, root: Path) -> SnapshotStore:
        """A snapshot store whose every read is recorded against this run.

        Experiments open stores through this rather than constructing one
        directly, so what gets cited is what was read -- not the whole
        manifest, and not a manifest found by a second path that could
        name a different store.
        """
        # Resolved, so one physical store reached by two spellings -- a
        # relative path and its absolute form -- is one store and not two.
        manifest = SnapshotStore(root, on_read=None).manifest_path.resolve()

        def note(source: str, release: str, path: Path) -> None:
            key = (source, release)
            seen = self._snapshot_reads.get(key)
            if seen is not None and seen[0] != manifest:
                raise ProvenanceError(
                    f"{source}/{release} was read from two stores in one run "
                    f"({seen[0].parent} and {manifest.parent}); a citation "
                    f"keyed by source and release cannot say which produced "
                    f"the numbers."
                )
            self._snapshot_reads[key] = (manifest, path)

        return SnapshotStore(root, on_read=note)

    @property
    def snapshot_reads(self) -> list[tuple[str, str]]:
        """Every (source, release) this run read, in a stable order."""
        return sorted(self._snapshot_reads)

    def settle_snapshot_citations(self) -> list[str]:
        """Cite exactly the extracts this run read; return any it could not.

        Each citation is the whole manifest entry, not a chosen subset. A
        digest pins which bytes an extract was, not what they meant, and
        the manifest that says what they meant is replaced in place when an
        extract is rebuilt -- so a run record that kept only the digest
        would, months later, cite something nothing can interpret.
        `synthesised_consensus` is what makes that bite: it says whether
        OmniPath's consensus direction was read or derived, which changes
        what every directed edge in a dated graph means. `source` and
        `release` are dropped only because they are the key.

        A read whose extract has no manifest entry is not silently left
        out: it is written under `snapshots_uncited` and returned, so the
        caller decides whether that is fatal and the record says so either
        way.
        """
        manifests: dict[Path, dict] = {}
        cited: dict[str, dict[str, Any]] = {}
        uncited: list[str] = []
        mismatched: list[dict[str, str]] = []
        for (source, release), (manifest, path) in sorted(self._snapshot_reads.items()):
            if manifest not in manifests:
                manifests[manifest] = read_manifest(manifest)
            entry = manifests[manifest].get((source, release))
            if entry is None:
                uncited.append(f"{source}/{release}")
                continue
            # The manifest describes bytes; this run read bytes. Until now
            # nothing checked they were the same bytes. `snapshot build`
            # writes the extract and its manifest entry as two steps, so an
            # interrupted rebuild of an already-built release leaves the
            # manifest describing the old file and the disk holding the new
            # -- and the run would cite a digest of bytes it never read,
            # which is the defect this whole layer exists to prevent.
            actual = digest_file(path)
            if actual != entry.sha256:
                mismatched.append(
                    {
                        "extract": f"{source}/{release}",
                        "path": str(path),
                        "manifest_sha256": entry.sha256,
                        "actual_sha256": actual,
                    }
                )
                continue
            fields = asdict(entry)
            del fields["source"], fields["release"]
            cited[f"{source}/{release}"] = fields

        env_path = self.path / "env.json"
        env = json.loads(env_path.read_text(encoding="utf-8"))
        env["snapshots"] = cited
        env["snapshots_uncited"] = uncited
        env["snapshots_mismatched"] = mismatched
        env_path.write_text(json.dumps(env, indent=2), encoding="utf-8")
        return uncited + [f"{m['extract']} (digest mismatch)" for m in mismatched]

    def note_settlement_failure(self, error: BaseException) -> None:
        """Record that citations could not be settled, and why.

        Only reached when the run was already failing. Losing the record
        to a second fault would leave the operator reading the manifest
        error instead of the one that stopped the run.
        """
        env_path = self.path / "env.json"
        env = json.loads(env_path.read_text(encoding="utf-8"))
        env["snapshots_settlement_error"] = f"{type(error).__name__}: {error}"
        env_path.write_text(json.dumps(env, indent=2), encoding="utf-8")

    @classmethod
    def load(cls, run_id: str, *, runs_dir: Path | None = None) -> RunRecord:
        base = runs_dir if runs_dir is not None else RUNS_DIR
        path = base / run_id
        if not path.is_dir():
            raise FileNotFoundError(f"no run record at {path}")
        rec = cls(run_id, path)
        summary = path / "record.json"
        if summary.exists():
            data = json.loads(summary.read_text())
            rec.status = data["status"]
            rec.citable = data["citable"]
        return rec

    # -- writing ----------------------------------------------------------

    def append_row(self, row: dict[str, Any]) -> None:
        """Append one result row, flushed to disk immediately."""
        with (self.path / "rows.jsonl").open("a", encoding="utf-8") as fh:
            fh.write(json.dumps(row, sort_keys=True) + "\n")
            fh.flush()
        self._n_rows += 1

    def finalise(self, status: str) -> None:
        if status not in _VALID_STATUS:
            raise ValueError(f"status must be one of {_VALID_STATUS}, got {status!r}")

        size = self.size_bytes()
        if size > MAX_RECORD_BYTES and not self._allow_large:
            raise RecordTooLargeError(
                f"record {self.run_id} is {size / 1e6:.1f} MB, which exceeds the "
                f"{MAX_RECORD_BYTES / 1e6:.0f} MB limit. Re-run with --allow-large "
                f"if this is intentional, or prune inputs you do not need."
            )

        env = json.loads((self.path / "env.json").read_text())
        self.status = status
        self.citable = status == "complete" and not env["git_dirty"]
        rows_path = self.path / "rows.jsonl"
        rows_sha256 = (
            hashlib.sha256(rows_path.read_bytes()).hexdigest() if rows_path.exists() else None
        )
        (self.path / "record.json").write_text(
            json.dumps(
                {
                    "run_id": self.run_id,
                    "experiment": getattr(self, "_experiment", self.run_id),
                    "status": status,
                    "citable": self.citable,
                    "n_rows": self._n_rows,
                    "size_bytes": size,
                    "rows_sha256": rows_sha256,
                    "finalised_utc": datetime.now(UTC).isoformat(),
                },
                indent=2,
            )
        )

    # -- reading ----------------------------------------------------------

    def rows(self) -> list[dict[str, Any]]:
        text = (self.path / "rows.jsonl").read_text().strip()
        return [json.loads(line) for line in text.splitlines()] if text else []

    def size_bytes(self) -> int:
        return sum(p.stat().st_size for p in self.path.rglob("*") if p.is_file())

snapshot_reads property

snapshot_reads: list[tuple[str, str]]

Every (source, release) this run read, in a stable order.

snapshot_store

snapshot_store(root: Path) -> SnapshotStore

A snapshot store whose every read is recorded against this run.

Experiments open stores through this rather than constructing one directly, so what gets cited is what was read -- not the whole manifest, and not a manifest found by a second path that could name a different store.

Source code in src/neorx/experiments/record.py
def snapshot_store(self, root: Path) -> SnapshotStore:
    """A snapshot store whose every read is recorded against this run.

    Experiments open stores through this rather than constructing one
    directly, so what gets cited is what was read -- not the whole
    manifest, and not a manifest found by a second path that could
    name a different store.
    """
    # Resolved, so one physical store reached by two spellings -- a
    # relative path and its absolute form -- is one store and not two.
    manifest = SnapshotStore(root, on_read=None).manifest_path.resolve()

    def note(source: str, release: str, path: Path) -> None:
        key = (source, release)
        seen = self._snapshot_reads.get(key)
        if seen is not None and seen[0] != manifest:
            raise ProvenanceError(
                f"{source}/{release} was read from two stores in one run "
                f"({seen[0].parent} and {manifest.parent}); a citation "
                f"keyed by source and release cannot say which produced "
                f"the numbers."
            )
        self._snapshot_reads[key] = (manifest, path)

    return SnapshotStore(root, on_read=note)

settle_snapshot_citations

settle_snapshot_citations() -> list[str]

Cite exactly the extracts this run read; return any it could not.

Each citation is the whole manifest entry, not a chosen subset. A digest pins which bytes an extract was, not what they meant, and the manifest that says what they meant is replaced in place when an extract is rebuilt -- so a run record that kept only the digest would, months later, cite something nothing can interpret. synthesised_consensus is what makes that bite: it says whether OmniPath's consensus direction was read or derived, which changes what every directed edge in a dated graph means. source and release are dropped only because they are the key.

A read whose extract has no manifest entry is not silently left out: it is written under snapshots_uncited and returned, so the caller decides whether that is fatal and the record says so either way.

Source code in src/neorx/experiments/record.py
def settle_snapshot_citations(self) -> list[str]:
    """Cite exactly the extracts this run read; return any it could not.

    Each citation is the whole manifest entry, not a chosen subset. A
    digest pins which bytes an extract was, not what they meant, and
    the manifest that says what they meant is replaced in place when an
    extract is rebuilt -- so a run record that kept only the digest
    would, months later, cite something nothing can interpret.
    `synthesised_consensus` is what makes that bite: it says whether
    OmniPath's consensus direction was read or derived, which changes
    what every directed edge in a dated graph means. `source` and
    `release` are dropped only because they are the key.

    A read whose extract has no manifest entry is not silently left
    out: it is written under `snapshots_uncited` and returned, so the
    caller decides whether that is fatal and the record says so either
    way.
    """
    manifests: dict[Path, dict] = {}
    cited: dict[str, dict[str, Any]] = {}
    uncited: list[str] = []
    mismatched: list[dict[str, str]] = []
    for (source, release), (manifest, path) in sorted(self._snapshot_reads.items()):
        if manifest not in manifests:
            manifests[manifest] = read_manifest(manifest)
        entry = manifests[manifest].get((source, release))
        if entry is None:
            uncited.append(f"{source}/{release}")
            continue
        # The manifest describes bytes; this run read bytes. Until now
        # nothing checked they were the same bytes. `snapshot build`
        # writes the extract and its manifest entry as two steps, so an
        # interrupted rebuild of an already-built release leaves the
        # manifest describing the old file and the disk holding the new
        # -- and the run would cite a digest of bytes it never read,
        # which is the defect this whole layer exists to prevent.
        actual = digest_file(path)
        if actual != entry.sha256:
            mismatched.append(
                {
                    "extract": f"{source}/{release}",
                    "path": str(path),
                    "manifest_sha256": entry.sha256,
                    "actual_sha256": actual,
                }
            )
            continue
        fields = asdict(entry)
        del fields["source"], fields["release"]
        cited[f"{source}/{release}"] = fields

    env_path = self.path / "env.json"
    env = json.loads(env_path.read_text(encoding="utf-8"))
    env["snapshots"] = cited
    env["snapshots_uncited"] = uncited
    env["snapshots_mismatched"] = mismatched
    env_path.write_text(json.dumps(env, indent=2), encoding="utf-8")
    return uncited + [f"{m['extract']} (digest mismatch)" for m in mismatched]

note_settlement_failure

note_settlement_failure(error: BaseException) -> None

Record that citations could not be settled, and why.

Only reached when the run was already failing. Losing the record to a second fault would leave the operator reading the manifest error instead of the one that stopped the run.

Source code in src/neorx/experiments/record.py
def note_settlement_failure(self, error: BaseException) -> None:
    """Record that citations could not be settled, and why.

    Only reached when the run was already failing. Losing the record
    to a second fault would leave the operator reading the manifest
    error instead of the one that stopped the run.
    """
    env_path = self.path / "env.json"
    env = json.loads(env_path.read_text(encoding="utf-8"))
    env["snapshots_settlement_error"] = f"{type(error).__name__}: {error}"
    env_path.write_text(json.dumps(env, indent=2), encoding="utf-8")

append_row

append_row(row: dict[str, Any]) -> None

Append one result row, flushed to disk immediately.

Source code in src/neorx/experiments/record.py
def append_row(self, row: dict[str, Any]) -> None:
    """Append one result row, flushed to disk immediately."""
    with (self.path / "rows.jsonl").open("a", encoding="utf-8") as fh:
        fh.write(json.dumps(row, sort_keys=True) + "\n")
        fh.flush()
    self._n_rows += 1

ProvenanceError

Bases: RuntimeError

Raised when the code provenance of a run cannot be established.

A run whose git SHA or dirty state cannot be determined has no provenance. It is a failed run, not one that quietly records a fabricated SHA or a false "clean" state.

Source code in src/neorx/experiments/record.py
class ProvenanceError(RuntimeError):
    """Raised when the code provenance of a run cannot be established.

    A run whose git SHA or dirty state cannot be determined has no
    provenance. It is a failed run, not one that quietly records a
    fabricated SHA or a false "clean" state.
    """

RecordTooLargeError

Bases: RuntimeError

Raised when a finalised record exceeds MAX_RECORD_BYTES.

Source code in src/neorx/experiments/record.py
class RecordTooLargeError(RuntimeError):
    """Raised when a finalised record exceeds MAX_RECORD_BYTES."""

RunIDCollisionError

Bases: RuntimeError

Raised when a run ID collides with an existing run directory.

Source code in src/neorx/experiments/record.py
class RunIDCollisionError(RuntimeError):
    """Raised when a run ID collides with an existing run directory."""

Experiment registry.

An experiment is a function taking a RunRecord. It never opens a file and never decides where results go -- the runner does both. That is what makes "a number cannot exist without a record" structural rather than a habit.

ExperimentDef dataclass

Source code in src/neorx/experiments/registry.py
@dataclass(frozen=True)
class ExperimentDef:
    name: str
    help: str
    fn: ExperimentFn
    captures_http: bool = False
    #: Row keys whose value is expected to differ between a run and its
    #: replay -- wall-clock timings and the like -- and so must not count
    #: toward the replay's IDENTICAL/DIFFERS verdict. They are still
    #: reported (see ReplayResult.volatile_diffs), never silently dropped.
    volatile_fields: tuple[str, ...] = ()
    #: Declares that this experiment reads pinned snapshots. It must open
    #: them with ``record.snapshot_store(root)``; the runner then cites
    #: exactly what was read and refuses a declared experiment that
    #: recorded no reads, since that means a store was opened some other
    #: way and nothing it read is cited.
    reads_snapshots: bool = False

UnknownExperimentError

Bases: KeyError

Raised when no experiment is registered under the given name.

Source code in src/neorx/experiments/registry.py
class UnknownExperimentError(KeyError):
    """Raised when no experiment is registered under the given name."""

experiment

experiment(*, name: str, help: str = '', captures_http: bool = False, volatile_fields: tuple[str, ...] = (), reads_snapshots: bool = False) -> Callable[[ExperimentFn], ExperimentFn]

Register an experiment under name.

captures_http declares that the experiment needs its HTTP traffic recorded. An experiment never chooses the capture mode -- only the caller (a live run vs. a replay) knows whether that should be record or replay -- so it only declares the need; the runner decides the mode.

volatile_fields declares row keys that are expected to differ on every replay (wall-clock timings and similar) -- see ExperimentDef.volatile_fields.

reads_snapshots declares that the experiment's numbers come from pinned extracts, so the runner records which ones. Without it, an experiment reading snapshots writes an env.json whose snapshots object is empty -- a run citing no inputs, which is the provenance failure this project already found in four published papers.

Source code in src/neorx/experiments/registry.py
def experiment(
    *,
    name: str,
    help: str = "",
    captures_http: bool = False,
    volatile_fields: tuple[str, ...] = (),
    reads_snapshots: bool = False,
) -> Callable[[ExperimentFn], ExperimentFn]:
    """Register an experiment under ``name``.

    ``captures_http`` declares that the experiment needs its HTTP traffic
    recorded. An experiment never chooses the capture *mode* -- only the
    caller (a live run vs. a replay) knows whether that should be record
    or replay -- so it only declares the need; the runner decides the mode.

    ``volatile_fields`` declares row keys that are expected to differ on
    every replay (wall-clock timings and similar) -- see
    ``ExperimentDef.volatile_fields``.

    ``reads_snapshots`` declares that the experiment's numbers come from
    pinned extracts, so the runner records which ones. Without it, an
    experiment reading snapshots writes an ``env.json`` whose
    ``snapshots`` object is empty -- a run citing no inputs, which is the
    provenance failure this project already found in four published
    papers.
    """

    def decorate(fn: ExperimentFn) -> ExperimentFn:
        if name in _REGISTRY:
            raise ValueError(f"experiment {name!r} is already registered")
        _REGISTRY[name] = ExperimentDef(
            name=name,
            help=help,
            fn=fn,
            captures_http=captures_http,
            volatile_fields=tuple(volatile_fields),
            reads_snapshots=reads_snapshots,
        )
        return fn

    return decorate

run_experiment

run_experiment(name: str, *, allow_large: bool = False, runs_dir: Path | None = None) -> RunRecord

Execute an experiment, writing its record whatever the outcome.

env.json cites exactly the extracts the run read, taken from the manifest of the store it read them from.

Source code in src/neorx/experiments/registry.py
def run_experiment(
    name: str,
    *,
    allow_large: bool = False,
    runs_dir: Path | None = None,
) -> RunRecord:
    """Execute an experiment, writing its record whatever the outcome.

    ``env.json`` cites exactly the extracts the run read, taken from the
    manifest of the store it read them from.
    """
    defn = get_experiment(name)
    record = RunRecord.create(name, runs_dir=runs_dir, allow_large=allow_large)
    try:
        if defn.captures_http:
            with capture(record, mode="record"):
                defn.fn(record)
        else:
            defn.fn(record)
    except BaseException:
        # Cite what was read before the failure. The original error is the
        # one that propagates; the record still says what the partial rows
        # came from, and lists any read it could not cite.
        #
        # Settlement itself can fail -- a malformed manifest.toml, or an
        # entry carrying a field this version does not know. That must not
        # cost the run record: without finalise() there is no record.json
        # at all, and RunRecord.load would later report a failed run as
        # merely incomplete while the operator saw the manifest error
        # instead of the one that actually stopped the run. So the
        # settlement error is recorded and the original is re-raised.
        try:
            record.settle_snapshot_citations()
        except Exception as settlement_error:
            record.note_settlement_failure(settlement_error)
        record.finalise("failed")
        raise
    settle_or_refuse(record, name, declared=defn.reads_snapshots)
    record.finalise("complete")
    return record

get_experiment

get_experiment(name: str) -> ExperimentDef
Source code in src/neorx/experiments/registry.py
def get_experiment(name: str) -> ExperimentDef:
    try:
        return _REGISTRY[name]
    except KeyError:
        known = ", ".join(sorted(_REGISTRY)) or "(none registered)"
        raise UnknownExperimentError(f"no experiment named {name!r}. Available: {known}") from None

list_experiments

list_experiments() -> list[ExperimentDef]
Source code in src/neorx/experiments/registry.py
def list_experiments() -> list[ExperimentDef]:
    return [_REGISTRY[k] for k in sorted(_REGISTRY)]

settle_or_refuse

settle_or_refuse(record: RunRecord, name: str, *, declared: bool) -> None

Cite what the run read, and refuse a run whose inputs cannot be named.

Called after a run completes, by both the runner and replay, so the two cannot drift apart -- they did once, and a replay cited nothing while reporting identical: True.

Two refusals. A read with no manifest entry: the extracts were there and the manifest describing them was not, so the run produced numbers from inputs it cannot identify -- the failure this project found in four published papers. And an experiment that declares reads_snapshots but recorded no reads: it opened a store some way other than RunRecord.snapshot_store, so nothing it read was tracked.

What it deliberately does NOT accept is "some citation exists". The earlier check did, and a run over the 18.06 release completed while citing only a 25.06 entry that happened to be in the manifest.

Source code in src/neorx/experiments/registry.py
def settle_or_refuse(record: RunRecord, name: str, *, declared: bool) -> None:
    """Cite what the run read, and refuse a run whose inputs cannot be named.

    Called after a run completes, by both the runner and replay, so the two
    cannot drift apart -- they did once, and a replay cited nothing while
    reporting `identical: True`.

    Two refusals. A read with no manifest entry: the extracts were there
    and the manifest describing them was not, so the run produced numbers
    from inputs it cannot identify -- the failure this project found in
    four published papers. And an experiment that declares
    `reads_snapshots` but recorded no reads: it opened a store some way
    other than `RunRecord.snapshot_store`, so nothing it read was tracked.

    What it deliberately does NOT accept is "some citation exists". The
    earlier check did, and a run over the 18.06 release completed while
    citing only a 25.06 entry that happened to be in the manifest.
    """
    uncited = record.settle_snapshot_citations()
    if uncited:
        record.finalise("failed")
        raise ProvenanceError(
            f"{name!r} read {', '.join(uncited)}, which the store's manifest "
            f"does not describe. The run produced numbers from extracts it "
            f"cannot identify. Rebuild them with `neorx snapshot build`, "
            f"which writes the manifest entry beside each extract."
        )
    if declared and not record.snapshot_reads:
        record.finalise("failed")
        raise ProvenanceError(
            f"{name!r} declares reads_snapshots but recorded no reads. Open "
            f"stores with `record.snapshot_store(root)` rather than "
            f"constructing SnapshotStore directly, or nothing read is cited."
        )

Re-execute a recorded run against its frozen inputs and diff the result.

This is the claim the subsystem rests on: given a run record, anyone can reproduce its numbers without reaching the network. A replay that differs is not a failure of the tool -- it names exactly which values moved, which is the information a reviewer actually needs.

ReplayResult dataclass

Source code in src/neorx/experiments/replay.py
@dataclass
class ReplayResult:
    replay_run_id: str
    diffs: list[RowDiff] = field(default_factory=list)
    #: Diffs on fields the experiment declared ``volatile_fields`` -- e.g.
    #: wall_clock_s. Never counted toward ``identical``, but always
    #: reported here rather than silently dropped: a gate must never
    #: swallow information, only decide what does and doesn't fail a
    #: verdict.
    volatile_diffs: list[RowDiff] = field(default_factory=list)

    @property
    def identical(self) -> bool:
        return not self.diffs

RowDiff dataclass

Source code in src/neorx/experiments/replay.py
@dataclass(frozen=True)
class RowDiff:
    index: int
    key: str
    recorded: Any
    replayed: Any

NotReplayableError

Bases: RuntimeError

The run cannot be replayed -- typically its inputs were pruned.

Source code in src/neorx/experiments/replay.py
class NotReplayableError(RuntimeError):
    """The run cannot be replayed -- typically its inputs were pruned."""

replay_experiment

replay_experiment(run_id: str, *, runs_dir: Path | None = None) -> ReplayResult

Re-run a recorded experiment against its cassette and diff the rows.

Source code in src/neorx/experiments/replay.py
def replay_experiment(run_id: str, *, runs_dir: Path | None = None) -> ReplayResult:
    """Re-run a recorded experiment against its cassette and diff the rows."""
    original = RunRecord.load(run_id, runs_dir=runs_dir)
    summary = json.loads((original.path / "record.json").read_text())
    if summary.get("replayable") is False:
        raise NotReplayableError(
            f"run {run_id} was pruned: its frozen inputs are gone, so it cannot "
            f"be replayed. Its recorded rows remain in rows.jsonl."
        )

    defn = get_experiment(_experiment_name(original))
    replay_rec = RunRecord.create(f"{defn.name}-replay", runs_dir=runs_dir)

    has_cassette = cassette_path(original).exists()
    try:
        if defn.captures_http and has_cassette:
            shutil.copy2(cassette_path(original), cassette_path(replay_rec))
            with capture(replay_rec, mode="replay"):
                defn.fn(replay_rec)
        else:
            defn.fn(replay_rec)
    except BaseException:
        # A raising replay left no settlement and no record.json at all,
        # so the attempt was invisible: `RunRecord.load` reported it as
        # merely incomplete. The runner has always done this; replay had
        # not, and the two drifting apart is what this module keeps
        # having to fix.
        try:
            replay_rec.settle_snapshot_citations()
        except Exception as settlement_error:
            replay_rec.note_settlement_failure(settlement_error)
        replay_rec.finalise("failed")
        raise
    # The same settlement run_experiment makes, by the same function. A
    # replay that cannot name its extracts and still reports
    # `identical: True` is worse than a run that cannot: it asserts
    # agreement between two sets of numbers whose inputs it cannot
    # identify. The two paths drifted apart once; sharing the call is what
    # keeps them together.
    settle_or_refuse(replay_rec, f"{defn.name}-replay", declared=defn.reads_snapshots)
    replay_rec.finalise("complete")

    diffs, volatile_diffs = _diff_rows(
        original.rows(), replay_rec.rows(), volatile_fields=defn.volatile_fields
    )
    return ReplayResult(
        replay_run_id=replay_rec.run_id,
        diffs=diffs,
        volatile_diffs=volatile_diffs,
    )

prune_record

prune_record(run_id: str, *, runs_dir: Path | None = None) -> int

Drop a run's frozen inputs, keeping its results. Returns bytes freed.

Source code in src/neorx/experiments/replay.py
def prune_record(run_id: str, *, runs_dir: Path | None = None) -> int:
    """Drop a run's frozen inputs, keeping its results. Returns bytes freed."""
    record = RunRecord.load(run_id, runs_dir=runs_dir)
    inputs = record.path / "inputs"
    freed = (
        sum(p.stat().st_size for p in inputs.rglob("*") if p.is_file()) if inputs.exists() else 0
    )
    if inputs.exists():
        shutil.rmtree(inputs)

    summary_path = record.path / "record.json"
    summary = json.loads(summary_path.read_text())
    summary["replayable"] = False
    summary["pruned_bytes"] = freed
    summary_path.write_text(json.dumps(summary, indent=2))
    return freed

Checks that make "no number without a record" enforceable.

Each gate closes one hole the manuscript audit found:

  • find_hardcoded_metrics -- _gen_figures.py held the F1 values as literals, so Figure 3 was a transcription of a table rather than a rendering of data.
  • check_records_wellformed -- a record whose summary disagrees with its rows is not evidence.
  • check_cited_runs -- a manuscript citing a run that does not exist, or one nobody can reproduce.
  • check_committed_records_are_citable -- a non-citable run record (dirty tree, incomplete, or failed) committed to git anyway, adding ~MB of weight to the repository while backing no claim.
  • check_record_integrity -- rows.jsonl edited after the fact (e.g. an F1 changed from 0.474 to 0.999, row count left untouched) with no other gate noticing. This detects accidental edits and drift by recomputing the SHA-256 stored at finalise time; it does NOT detect a determined forger who edits rows.jsonl and recomputes/rewrites rows_sha256 to match -- that requires signing the record, which this gate is not.

Known limit of find_hardcoded_metrics: it matches bare ast.Constant float literals, and ast.Constant string literals that contain a metric-shaped number (a digit, a decimal point, and >= METRIC_DECIMALS digits after it -- e.g. "C=0.990"). A metric assembled by computation -- 545 / 1000, round(x, 3), an f-string embedding a number, a value read from a dict -- is invisible to an AST literal check by construction, not by an oversight fixable here. A clean run of this gate means "no metric was typed in as a float literal or spelled out in a string literal"; it does NOT mean "no computed metric literal exists anywhere in this file". Treat "0 findings" accordingly.

Finding dataclass

Source code in src/neorx/experiments/gates.py
@dataclass(frozen=True)
class Finding:
    path: str
    line: int
    message: str

find_hardcoded_metrics

find_hardcoded_metrics(path: Path, allowlist: set[float] | None = None) -> list[Finding]

Flag metric-shaped float literals (>= METRIC_DECIMALS decimals) and

metric-shaped numbers spelled inside string literals (e.g. "C=0.990"). A measured value transcribed as a string evades a float-only check just as completely as one assembled by computation -- this closes that hole for the string case specifically.

Source code in src/neorx/experiments/gates.py
def find_hardcoded_metrics(path: Path, allowlist: set[float] | None = None) -> list[Finding]:
    """Flag metric-shaped float literals (>= METRIC_DECIMALS decimals) and

    metric-shaped numbers spelled inside string literals (e.g. "C=0.990").
    A measured value transcribed as a string evades a float-only check just
    as completely as one assembled by computation -- this closes that hole
    for the string case specifically.
    """
    allowed = DEFAULT_ALLOWLIST if allowlist is None else allowlist
    tree = ast.parse(Path(path).read_text(), filename=str(path))
    findings: list[Finding] = []

    for node in ast.walk(tree):
        if not isinstance(node, ast.Constant):
            continue
        if isinstance(node.value, str):
            match = _METRIC_SHAPED_NUMBER_IN_STRING.search(node.value)
            if match is not None:
                findings.append(
                    Finding(
                        path=str(path),
                        line=node.lineno,
                        message=(
                            f"string literal {node.value!r} spells out a "
                            f"metric-shaped number ({match.group()}) -- render it "
                            f"from a run record instead of transcribing it as text"
                        ),
                    )
                )
            continue
        if not isinstance(node.value, float):
            continue
        literal = ast.get_source_segment(Path(path).read_text(), node) or repr(node.value)
        try:
            if _decimals(literal) < METRIC_DECIMALS:
                continue
        except decimal.InvalidOperation:
            # The gate's entire job is catching metric literals -- a
            # literal it cannot classify must surface, not vanish. This is
            # not expected to fire on ordinary Python float syntax; if it
            # does, someone needs to look at it.
            findings.append(
                Finding(
                    path=str(path),
                    line=node.lineno,
                    message=(
                        f"could not classify literal {literal!r} as a decimal -- "
                        f"unable to check whether it is a metric; inspect it by hand"
                    ),
                )
            )
            continue
        if node.value in allowed:
            continue
        findings.append(
            Finding(
                path=str(path),
                line=node.lineno,
                message=(
                    f"metric-shaped literal {literal} -- render it from a run "
                    f"record instead, or add it to DEFAULT_ALLOWLIST with a reason"
                ),
            )
        )
    return findings

check_records_wellformed

check_records_wellformed(runs_dir: Path) -> list[Finding]

Every run directory must have a summary that matches its rows.

Source code in src/neorx/experiments/gates.py
def check_records_wellformed(runs_dir: Path) -> list[Finding]:
    """Every run directory must have a summary that matches its rows."""
    findings: list[Finding] = []
    runs_dir = Path(runs_dir)
    if not runs_dir.is_dir():
        return findings

    for run in sorted(p for p in runs_dir.iterdir() if p.is_dir()):
        summary = run / "record.json"
        if not summary.exists():
            findings.append(
                Finding(str(run), 0, f"{run.name}: no record.json -- run never finalised")
            )
            continue
        data = json.loads(summary.read_text())
        rows_file = run / "rows.jsonl"
        actual = (
            len([ln for ln in rows_file.read_text().splitlines() if ln.strip()])
            if rows_file.exists()
            else 0
        )
        if data.get("n_rows") != actual:
            findings.append(
                Finding(
                    str(run),
                    0,
                    f"{run.name}: record.json claims {data.get('n_rows')} rows "
                    f"but rows.jsonl has {actual}",
                )
            )
    return findings

check_record_integrity

check_record_integrity(runs_dir: Path) -> list[Finding]

Every run record's stored rows_sha256 must match its rows.jsonl.

RunRecord.finalise computes a SHA-256 over rows.jsonl's bytes at finalise time and stores it in record.json as rows_sha256. A record edited afterwards -- a metric changed, a row dropped, in either case with the row count left alone so check_records_wellformed sees nothing wrong -- will disagree with that stored digest.

This catches accidental edits and drift, not a forger who edits rows.jsonl and also recomputes and rewrites rows_sha256 to match; that is a signing problem, not a hashing problem, and out of scope here.

Source code in src/neorx/experiments/gates.py
def check_record_integrity(runs_dir: Path) -> list[Finding]:
    """Every run record's stored rows_sha256 must match its rows.jsonl.

    ``RunRecord.finalise`` computes a SHA-256 over rows.jsonl's bytes at
    finalise time and stores it in record.json as ``rows_sha256``. A record
    edited afterwards -- a metric changed, a row dropped, in either case
    with the row count left alone so ``check_records_wellformed`` sees
    nothing wrong -- will disagree with that stored digest.

    This catches accidental edits and drift, not a forger who edits
    rows.jsonl and also recomputes and rewrites rows_sha256 to match; that
    is a signing problem, not a hashing problem, and out of scope here.
    """
    findings: list[Finding] = []
    runs_dir = Path(runs_dir)
    if not runs_dir.is_dir():
        return findings

    for run in sorted(p for p in runs_dir.iterdir() if p.is_dir()):
        summary = run / "record.json"
        if not summary.exists():
            continue  # check_records_wellformed already flags this
        data = json.loads(summary.read_text())
        stored = data.get("rows_sha256")
        if stored is None:
            findings.append(
                Finding(
                    str(summary),
                    0,
                    f"{run.name}: record.json has no rows_sha256 -- "
                    f"finalised by an older version of RunRecord, or tampered",
                )
            )
            continue
        rows_file = run / "rows.jsonl"
        actual = hashlib.sha256(rows_file.read_bytes()).hexdigest() if rows_file.exists() else None
        if actual != stored:
            findings.append(
                Finding(
                    str(rows_file),
                    0,
                    f"{run.name}: rows.jsonl digest {actual!r} does not match "
                    f"record.json's rows_sha256 {stored!r} -- rows.jsonl was "
                    f"edited after the run finalised",
                )
            )
    return findings

check_committed_records_are_citable

check_committed_records_are_citable(runs_dir: Path, tracked: set[str] | None = None) -> list[Finding]

Every run record committed to git must be citable.

runs/ is tracked on the theory that its records are the evidence behind every reported number. A record with citable: false (built from a dirty tree, or left incomplete or failed) is not evidence -- the figure command already refuses to render from one -- so committing it adds weight to the repository without adding anything that backs a claim. tracked is the set of run-directory names (run IDs) known to be committed; when omitted, it is read from git ls-files.

Source code in src/neorx/experiments/gates.py
def check_committed_records_are_citable(
    runs_dir: Path, tracked: set[str] | None = None
) -> list[Finding]:
    """Every run record committed to git must be citable.

    ``runs/`` is tracked on the theory that its records are the evidence
    behind every reported number. A record with ``citable: false`` (built
    from a dirty tree, or left incomplete or failed) is not evidence --
    the figure command already refuses to render from one -- so committing
    it adds weight to the repository without adding anything that backs a
    claim. ``tracked`` is the set of run-directory names (run IDs) known
    to be committed; when omitted, it is read from ``git ls-files``.
    """
    runs_dir = Path(runs_dir)
    if not runs_dir.is_dir():
        return []

    if tracked is None:
        result = subprocess.run(
            ["git", "ls-files", "."],
            cwd=str(runs_dir),
            capture_output=True,
            text=True,
            check=False,
        )
        if result.returncode != 0:
            return [
                Finding(
                    str(runs_dir),
                    0,
                    f"git ls-files failed (exit {result.returncode}): "
                    f"{result.stderr.strip()} -- could not determine which "
                    f"records are committed",
                )
            ]
        tracked = {Path(line).parts[0] for line in result.stdout.splitlines() if line.strip()}

    findings: list[Finding] = []
    for run in sorted(p for p in runs_dir.iterdir() if p.is_dir()):
        if run.name not in tracked:
            continue
        summary = run / "record.json"
        if not summary.exists():
            continue  # check_records_wellformed already flags this
        data = json.loads(summary.read_text())
        if not data.get("citable"):
            findings.append(
                Finding(
                    str(summary),
                    0,
                    f"{run.name}: committed to git but citable=false -- a "
                    f"non-citable record backs no claim, so committing it "
                    f"adds weight to the repository without evidence",
                )
            )
    return findings

check_cited_runs

check_cited_runs(manifest: Path, runs_dir: Path) -> list[Finding]

Every run cited by a manuscript must exist and be citable.

Source code in src/neorx/experiments/gates.py
def check_cited_runs(manifest: Path, runs_dir: Path) -> list[Finding]:
    """Every run cited by a manuscript must exist and be citable."""
    manifest = Path(manifest)
    if not manifest.exists():
        return [Finding(str(manifest), 0, f"no run manifest at {manifest}")]

    data = tomllib.loads(manifest.read_text())
    findings: list[Finding] = []

    for section, entries in data.items():
        if not isinstance(entries, dict):
            continue
        for citation, run_id in entries.items():
            summary = Path(runs_dir) / run_id / "record.json"
            if not summary.exists():
                findings.append(
                    Finding(
                        str(manifest),
                        0,
                        f"{section}.{citation} cites run {run_id!r}, which is not in {runs_dir}",
                    )
                )
                continue
            if not json.loads(summary.read_text()).get("citable"):
                findings.append(
                    Finding(
                        str(manifest),
                        0,
                        f"{section}.{citation} cites run {run_id!r}, which is not "
                        f"citable (incomplete, failed, or built from a dirty tree)",
                    )
                )
    return findings

check_no_fabricated_statistics

check_no_fabricated_statistics(causal_dir: Path) -> list[Finding]

Assert no fabricated statistic has been reintroduced.

Scoped to a directory by argument, never to src/ as a whole: neorx/genmol/evaluation/distribution.py reports a genuine Kolmogorov-Smirnov p-value, and a repository-wide search would flag it. Point this at neorx/core/causal/ only.

Source code in src/neorx/experiments/gates.py
def check_no_fabricated_statistics(causal_dir: Path) -> list[Finding]:
    """Assert no fabricated statistic has been reintroduced.

    Scoped to a directory by argument, never to ``src/`` as a whole:
    ``neorx/genmol/evaluation/distribution.py`` reports a genuine
    Kolmogorov-Smirnov p-value, and a repository-wide search would flag
    it. Point this at ``neorx/core/causal/`` only.
    """
    findings: list[Finding] = []

    for path in sorted(causal_dir.rglob("*.py")):
        for lineno, line in enumerate(
            path.read_text(encoding="utf-8").splitlines(),
            start=1,
        ):
            for name in _FABRICATED_STATISTIC_NAMES:
                if name in line:
                    findings.append(
                        Finding(
                            path=str(path),
                            line=lineno,
                            message=(
                                f"{name} is a fabricated statistic removed in "
                                f"sub-project 3; it must not return. See "
                                f"docs/superpowers/specs/2026-09-03-correctness-design.md"
                            ),
                        )
                    )

    return findings

neorx.genmol

Molecule generation. See GenMol.

Loading of the GenMol weights shipped with the package.

The loader raises on missing or inconsistent assets. It never returns an untrained model: a randomly initialised VAE emits plausible-looking SMILES, so silent degradation here is undetectable downstream.

GenMolAssetError

Bases: RuntimeError

Raised when the shipped model assets are missing or unusable.

Source code in src/neorx/genmol/pretrained.py
class GenMolAssetError(RuntimeError):
    """Raised when the shipped model assets are missing or unusable."""

load_pretrained

load_pretrained(device: device | None = None) -> tuple[MolVAE, SmilesTokenizer]

Load the packaged MolVAE and its matching tokenizer.

Returns:

Type Description
tuple[MolVAE, SmilesTokenizer]

Model in eval mode, and the tokenizer it was trained against.

Raises:

Type Description
GenMolAssetError

If either asset is absent, or the tokenizer carries no vocabulary.

Source code in src/neorx/genmol/pretrained.py
def load_pretrained(
    device: torch.device | None = None,
) -> tuple[MolVAE, SmilesTokenizer]:
    """Load the packaged MolVAE and its matching tokenizer.

    Returns
    -------
    tuple[MolVAE, SmilesTokenizer]
        Model in eval mode, and the tokenizer it was trained against.

    Raises
    ------
    GenMolAssetError
        If either asset is absent, or the tokenizer carries no vocabulary.
    """
    ckpt_path = ASSET_DIR / CHECKPOINT_NAME
    tok_path = ASSET_DIR / TOKENIZER_NAME

    if not ckpt_path.exists() or not tok_path.exists():
        raise GenMolAssetError(
            f"no trained checkpoint found in {ASSET_DIR}. "
            "Reinstall neorx, or train one with `neorx genmol train`."
        )

    tokenizer = SmilesTokenizer.load(tok_path)
    if tokenizer.vocab_size == 0:
        raise GenMolAssetError(
            f"tokenizer at {tok_path} loaded but its vocabulary is empty. "
            "The asset is corrupt; reinstall neorx."
        )

    model = MolVAE(vocab_size=tokenizer.vocab_size)
    load_checkpoint(ckpt_path, model, device=device)
    model.eval()
    return model, tokenizer

Molecule Generation

Generates novel molecules from a trained VAE by sampling from the latent space and decoding to SMILES.

Generation modes
  1. Random sampling — draw z ~ N(0, I) and decode. The simplest approach; generates diverse molecules.

  2. Temperature-controlled — scale logits by 1/T before softmax. Lower T → more conservative (higher probability tokens), higher T → more diverse (and more invalid).

  3. Beam search — maintain beam_width candidate sequences at each step, expanding the most probable ones. Produces higher validity but lower diversity.

  4. Latent interpolation — decode a series of points between two latent vectors to observe smooth structural transformations.

  5. Conditional generation (CVAE) — specify desired molecular properties and generate molecules matching those targets.

Post-generation filtering

Generated SMILES are validated with RDKit, deduplicated, and optionally filtered through the MolScreen pipeline for drug-likeness.

generate

generate(model: MolVAE, tokenizer: SmilesTokenizer, n: int = 100, temperature: float = 1.0, device: Optional[device] = None, validate: bool = True, deduplicate: bool = True) -> list[str]

Generate molecules by sampling from the prior N(0, I).

Parameters:

Name Type Description Default
model MolVAE

Trained VAE model.

required
tokenizer SmilesTokenizer

Tokenizer for decoding.

required
n int

Number of molecules to attempt generating.

100
temperature float

Sampling temperature (0.5–1.5 recommended).

1.0
device device

Computation device.

None
validate bool

Only return valid SMILES.

True
deduplicate bool

Remove duplicate molecules.

True

Returns:

Type Description
list[str]

Generated (and optionally validated) SMILES.

Source code in src/neorx/genmol/generate.py
def generate(
    model: MolVAE,
    tokenizer: SmilesTokenizer,
    n: int = 100,
    temperature: float = 1.0,
    device: Optional[torch.device] = None,
    validate: bool = True,
    deduplicate: bool = True,
) -> list[str]:
    """Generate molecules by sampling from the prior N(0, I).

    Parameters
    ----------
    model : MolVAE
        Trained VAE model.
    tokenizer : SmilesTokenizer
        Tokenizer for decoding.
    n : int
        Number of molecules to attempt generating.
    temperature : float
        Sampling temperature (0.5–1.5 recommended).
    device : torch.device, optional
        Computation device.
    validate : bool
        Only return valid SMILES.
    deduplicate : bool
        Remove duplicate molecules.

    Returns
    -------
    list[str]
        Generated (and optionally validated) SMILES.
    """
    if device is None:
        device = next(model.parameters()).device

    model.eval()
    token_ids = model.sample(n=n, temperature=temperature, device=device)
    decoded = _decode_token_ids(token_ids, tokenizer)

    if validate:
        decoded = _validate_smiles(decoded)

    if deduplicate:
        decoded = list(dict.fromkeys(decoded))  # preserve order

    logger.info(
        "Generated %d molecules (%d requested, T=%.2f).",
        len(decoded),
        n,
        temperature,
    )
    return decoded

generate_conditional

generate_conditional(model: MolCVAE, tokenizer: SmilesTokenizer, conditions: dict[str, float], normalizer: PropertyNormalizer, n: int = 100, temperature: float = 1.0, device: Optional[device] = None, validate: bool = True) -> list[str]

Generate molecules with desired properties (CVAE).

Parameters:

Name Type Description Default
model MolCVAE

Trained conditional VAE.

required
tokenizer SmilesTokenizer

Tokenizer for decoding.

required
conditions dict[str, float]

Desired properties, e.g. {"mw": 350, "logp": 2.5, "qed": 0.7}.

required
normalizer PropertyNormalizer

Fitted normalizer for property scaling.

required
n int

Number of molecules to generate.

100
temperature float

Sampling temperature.

1.0
device device

Device.

None
validate bool

Only return valid SMILES.

True

Returns:

Type Description
list[str]

Generated SMILES matching the desired conditions.

Source code in src/neorx/genmol/generate.py
def generate_conditional(
    model: MolCVAE,
    tokenizer: SmilesTokenizer,
    conditions: dict[str, float],
    normalizer: PropertyNormalizer,
    n: int = 100,
    temperature: float = 1.0,
    device: Optional[torch.device] = None,
    validate: bool = True,
) -> list[str]:
    """Generate molecules with desired properties (CVAE).

    Parameters
    ----------
    model : MolCVAE
        Trained conditional VAE.
    tokenizer : SmilesTokenizer
        Tokenizer for decoding.
    conditions : dict[str, float]
        Desired properties, e.g. ``{"mw": 350, "logp": 2.5, "qed": 0.7}``.
    normalizer : PropertyNormalizer
        Fitted normalizer for property scaling.
    n : int
        Number of molecules to generate.
    temperature : float
        Sampling temperature.
    device : torch.device, optional
        Device.
    validate : bool
        Only return valid SMILES.

    Returns
    -------
    list[str]
        Generated SMILES matching the desired conditions.
    """
    if device is None:
        device = next(model.parameters()).device

    # Normalize conditions
    norm_vals = normalizer.transform(conditions)
    cond = torch.tensor(norm_vals, dtype=torch.float32, device=device)

    token_ids = model.sample(cond=cond, n=n, temperature=temperature)
    decoded = _decode_token_ids(token_ids, tokenizer)

    if validate:
        decoded = _validate_smiles(decoded)

    logger.info(
        "Conditional generation: %d valid molecules for %s.",
        len(decoded),
        conditions,
    )
    return decoded

interpolate

interpolate(model: MolVAE, tokenizer: SmilesTokenizer, smiles_a: str, smiles_b: str, n_steps: int = 10, device: Optional[device] = None) -> list[str]

Interpolate between two molecules in latent space.

Encodes both molecules, then decodes n_steps evenly-spaced points along the line between them. This reveals how the model organises chemical space — nearby points should be structurally similar.

Parameters:

Name Type Description Default
model MolVAE

Trained VAE.

required
tokenizer SmilesTokenizer

Tokenizer.

required
smiles_a str

Starting molecule SMILES.

required
smiles_b str

Ending molecule SMILES.

required
n_steps int

Number of interpolation points (including endpoints).

10
device device

Device.

None

Returns:

Type Description
list[str]

SMILES at each interpolation point (some may be invalid).

Source code in src/neorx/genmol/generate.py
def interpolate(
    model: MolVAE,
    tokenizer: SmilesTokenizer,
    smiles_a: str,
    smiles_b: str,
    n_steps: int = 10,
    device: Optional[torch.device] = None,
) -> list[str]:
    """Interpolate between two molecules in latent space.

    Encodes both molecules, then decodes ``n_steps`` evenly-spaced
    points along the line between them.  This reveals how the model
    organises chemical space — nearby points should be structurally
    similar.

    Parameters
    ----------
    model : MolVAE
        Trained VAE.
    tokenizer : SmilesTokenizer
        Tokenizer.
    smiles_a : str
        Starting molecule SMILES.
    smiles_b : str
        Ending molecule SMILES.
    n_steps : int
        Number of interpolation points (including endpoints).
    device : torch.device, optional
        Device.

    Returns
    -------
    list[str]
        SMILES at each interpolation point (some may be invalid).
    """
    if device is None:
        device = next(model.parameters()).device

    model.eval()

    # Encode both molecules
    ids_a = torch.tensor(
        [tokenizer.encode(smiles_a)], dtype=torch.long, device=device
    )
    ids_b = torch.tensor(
        [tokenizer.encode(smiles_b)], dtype=torch.long, device=device
    )

    with torch.no_grad():
        z_a = model.encode(ids_a)  # [1, D]
        z_b = model.encode(ids_b)  # [1, D]

    # Linear interpolation
    alphas = torch.linspace(0, 1, n_steps, device=device)
    z_interp = torch.stack(
        [z_a * (1 - a) + z_b * a for a in alphas]
    ).squeeze(1)  # [n_steps, D]

    # Decode each point
    with torch.no_grad():
        token_ids = model.decode(z_interp, greedy=True)

    decoded = _decode_token_ids(token_ids, tokenizer)

    logger.info(
        "Interpolation: %s → %s (%d steps).",
        smiles_a,
        smiles_b,
        n_steps,
    )
    return decoded

Molecular VAE (Variational Autoencoder)

A β-VAE that learns a continuous latent representation of drug-like molecules from their SMILES strings.

Architecture overview

::

SMILES ──► Encoder (bidirectional GRU) ──► μ, log σ²
                                               │
                                          z ~ N(μ, σ²)
                                               │
          Decoder (autoregressive GRU) ◄───────┘
                 │
             SMILES (reconstructed)
Why a VAE for molecules?
  • Smooth latent space — nearby points decode to similar molecules, enabling interpolation between drugs and optimisation by gradient descent in latent space.
  • Generative — sampling z ~ N(0, I) produces novel, valid molecules.
  • Disentangled — β > 1 encourages disentangled representations where individual latent dimensions correspond to molecular properties.
Key design choices
  • GRU over LSTM — fewer parameters, trains faster on SMILES (sequence lengths < 120 don't need LSTM's extra gates).
  • 3-layer bidirectional encoder — captures both forward and backward context in the SMILES string.
  • Teacher forcing — during training, the decoder receives the ground-truth previous token instead of its own prediction. This stabilises early training and speeds convergence.
  • KL annealing — the β weight on the KL divergence is linearly increased from 0.01 → 1.0 over the first 10 epochs. Without annealing, the model can fall into "posterior collapse" where the encoder ignores the input and the decoder becomes an unconditional language model.

MolVAE

Bases: Module

Molecular Variational Autoencoder.

Combines MolEncoder and MolDecoder with the reparameterization trick and β-weighted KL divergence.

The reparameterization trick allows backpropagation through the stochastic sampling step:

.. math::

z = \mu + \sigma \cdot \epsilon, \quad \epsilon \sim N(0, I)

This makes the sampling differentiable — gradients flow through μ and σ, not through the random noise ε.

Parameters:

Name Type Description Default
vocab_size int

Vocabulary size.

required
embed_dim int

Embedding dimension.

64
hidden_dim int

GRU hidden dimension.

256
latent_dim int

Latent space dimension.

128
num_layers int

GRU layers.

3
dropout float

Dropout rate.

0.2
max_length int

Maximum sequence length.

120
pad_idx int

Padding token index.

0
Source code in src/neorx/genmol/models/vae.py
class MolVAE(nn.Module):
    """Molecular Variational Autoencoder.

    Combines ``MolEncoder`` and ``MolDecoder`` with the
    reparameterization trick and β-weighted KL divergence.

    The **reparameterization trick** allows backpropagation through
    the stochastic sampling step:

    .. math::

        z = \\mu + \\sigma \\cdot \\epsilon, \\quad \\epsilon \\sim N(0, I)

    This makes the sampling differentiable — gradients flow through
    μ and σ, not through the random noise ε.

    Parameters
    ----------
    vocab_size : int
        Vocabulary size.
    embed_dim : int
        Embedding dimension.
    hidden_dim : int
        GRU hidden dimension.
    latent_dim : int
        Latent space dimension.
    num_layers : int
        GRU layers.
    dropout : float
        Dropout rate.
    max_length : int
        Maximum sequence length.
    pad_idx : int
        Padding token index.
    """

    def __init__(
        self,
        vocab_size: int,
        embed_dim: int = 64,
        hidden_dim: int = 256,
        latent_dim: int = 128,
        num_layers: int = 3,
        dropout: float = 0.2,
        max_length: int = 120,
        pad_idx: int = 0,
    ):
        super().__init__()
        self.latent_dim = latent_dim
        self.max_length = max_length
        self.pad_idx = pad_idx

        self.encoder = MolEncoder(
            vocab_size, embed_dim, hidden_dim, latent_dim,
            num_layers, dropout, pad_idx,
        )
        self.decoder = MolDecoder(
            vocab_size, embed_dim, hidden_dim, latent_dim,
            num_layers, dropout, max_length, pad_idx,
        )

    def reparameterize(
        self, mu: torch.Tensor, logvar: torch.Tensor
    ) -> torch.Tensor:
        """Sample z using the reparameterization trick.

        Parameters
        ----------
        mu : Tensor[B, D]
            Mean of the approximate posterior.
        logvar : Tensor[B, D]
            Log-variance of the approximate posterior.

        Returns
        -------
        Tensor[B, D]
            Sampled latent vector.
        """
        if self.training:
            std = torch.exp(0.5 * logvar)
            eps = torch.randn_like(std)
            return mu + std * eps
        return mu  # deterministic at eval time

    def forward(
        self,
        x: torch.Tensor,
        target: Optional[torch.Tensor] = None,
    ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
        """Forward pass: encode → sample → decode.

        Parameters
        ----------
        x : Tensor[B, L]
            Input token IDs.
        target : Tensor[B, L], optional
            Target token IDs for teacher forcing.
            If ``None``, uses ``x`` as target.

        Returns
        -------
        logits : Tensor[B, L-1, V]
            Reconstruction logits.
        mu : Tensor[B, D]
            Posterior mean.
        logvar : Tensor[B, D]
            Posterior log-variance.
        """
        mu, logvar = self.encoder(x)
        z = self.reparameterize(mu, logvar)
        logits = self.decoder(z, target if target is not None else x)
        return logits, mu, logvar

    def encode(self, x: torch.Tensor) -> torch.Tensor:
        """Encode input to the latent mean (deterministic).

        Parameters
        ----------
        x : Tensor[B, L]
            Token IDs.

        Returns
        -------
        Tensor[B, D]
            Latent means.
        """
        mu, _ = self.encoder(x)
        return mu

    def decode(
        self,
        z: torch.Tensor,
        temperature: float = 1.0,
        greedy: bool = False,
    ) -> torch.Tensor:
        """Decode latent vectors to token sequences.

        Parameters
        ----------
        z : Tensor[B, D]
            Latent vectors.
        temperature : float
            Sampling temperature (lower = more conservative).
        greedy : bool
            If True, use argmax instead of sampling.

        Returns
        -------
        Tensor[B, L-1]
            Generated token ID sequences.
        """
        self.eval()
        with torch.no_grad():
            hidden = self.decoder._init_hidden(z)
            batch_size = z.size(0)
            device = z.device

            input_tok = torch.ones(
                batch_size, 1, dtype=torch.long, device=device
            )  # <SOS>

            generated: list[torch.Tensor] = []

            for _ in range(self.max_length - 1):
                embedded = self.decoder.embedding(input_tok)
                output, hidden = self.decoder.gru(embedded, hidden)
                logits = self.decoder.output_proj(output)  # [B, 1, V]

                if greedy:
                    input_tok = logits.argmax(dim=-1)
                else:
                    probs = F.softmax(logits.squeeze(1) / temperature, dim=-1)
                    input_tok = torch.multinomial(probs, 1)  # [B, 1]

                generated.append(input_tok)

            return torch.cat(generated, dim=1)  # [B, L-1]

    def sample(
        self,
        n: int = 1,
        temperature: float = 1.0,
        device: Optional[torch.device] = None,
    ) -> torch.Tensor:
        """Sample from the prior ``N(0, I)`` and decode.

        Parameters
        ----------
        n : int
            Number of molecules to generate.
        temperature : float
            Decoding temperature.
        device : torch.device, optional
            Device for tensors.

        Returns
        -------
        Tensor[n, L-1]
            Generated token ID sequences.
        """
        if device is None:
            device = next(self.parameters()).device

        z = torch.randn(n, self.latent_dim, device=device)
        return self.decode(z, temperature=temperature)

reparameterize

reparameterize(mu: Tensor, logvar: Tensor) -> torch.Tensor

Sample z using the reparameterization trick.

Parameters:

Name Type Description Default
mu Tensor[B, D]

Mean of the approximate posterior.

required
logvar Tensor[B, D]

Log-variance of the approximate posterior.

required

Returns:

Type Description
Tensor[B, D]

Sampled latent vector.

Source code in src/neorx/genmol/models/vae.py
def reparameterize(
    self, mu: torch.Tensor, logvar: torch.Tensor
) -> torch.Tensor:
    """Sample z using the reparameterization trick.

    Parameters
    ----------
    mu : Tensor[B, D]
        Mean of the approximate posterior.
    logvar : Tensor[B, D]
        Log-variance of the approximate posterior.

    Returns
    -------
    Tensor[B, D]
        Sampled latent vector.
    """
    if self.training:
        std = torch.exp(0.5 * logvar)
        eps = torch.randn_like(std)
        return mu + std * eps
    return mu  # deterministic at eval time

forward

forward(x: Tensor, target: Optional[Tensor] = None) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]

Forward pass: encode → sample → decode.

Parameters:

Name Type Description Default
x Tensor[B, L]

Input token IDs.

required
target Tensor[B, L]

Target token IDs for teacher forcing. If None, uses x as target.

None

Returns:

Name Type Description
logits Tensor[B, L - 1, V]

Reconstruction logits.

mu Tensor[B, D]

Posterior mean.

logvar Tensor[B, D]

Posterior log-variance.

Source code in src/neorx/genmol/models/vae.py
def forward(
    self,
    x: torch.Tensor,
    target: Optional[torch.Tensor] = None,
) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
    """Forward pass: encode → sample → decode.

    Parameters
    ----------
    x : Tensor[B, L]
        Input token IDs.
    target : Tensor[B, L], optional
        Target token IDs for teacher forcing.
        If ``None``, uses ``x`` as target.

    Returns
    -------
    logits : Tensor[B, L-1, V]
        Reconstruction logits.
    mu : Tensor[B, D]
        Posterior mean.
    logvar : Tensor[B, D]
        Posterior log-variance.
    """
    mu, logvar = self.encoder(x)
    z = self.reparameterize(mu, logvar)
    logits = self.decoder(z, target if target is not None else x)
    return logits, mu, logvar

encode

encode(x: Tensor) -> torch.Tensor

Encode input to the latent mean (deterministic).

Parameters:

Name Type Description Default
x Tensor[B, L]

Token IDs.

required

Returns:

Type Description
Tensor[B, D]

Latent means.

Source code in src/neorx/genmol/models/vae.py
def encode(self, x: torch.Tensor) -> torch.Tensor:
    """Encode input to the latent mean (deterministic).

    Parameters
    ----------
    x : Tensor[B, L]
        Token IDs.

    Returns
    -------
    Tensor[B, D]
        Latent means.
    """
    mu, _ = self.encoder(x)
    return mu

decode

decode(z: Tensor, temperature: float = 1.0, greedy: bool = False) -> torch.Tensor

Decode latent vectors to token sequences.

Parameters:

Name Type Description Default
z Tensor[B, D]

Latent vectors.

required
temperature float

Sampling temperature (lower = more conservative).

1.0
greedy bool

If True, use argmax instead of sampling.

False

Returns:

Type Description
Tensor[B, L - 1]

Generated token ID sequences.

Source code in src/neorx/genmol/models/vae.py
def decode(
    self,
    z: torch.Tensor,
    temperature: float = 1.0,
    greedy: bool = False,
) -> torch.Tensor:
    """Decode latent vectors to token sequences.

    Parameters
    ----------
    z : Tensor[B, D]
        Latent vectors.
    temperature : float
        Sampling temperature (lower = more conservative).
    greedy : bool
        If True, use argmax instead of sampling.

    Returns
    -------
    Tensor[B, L-1]
        Generated token ID sequences.
    """
    self.eval()
    with torch.no_grad():
        hidden = self.decoder._init_hidden(z)
        batch_size = z.size(0)
        device = z.device

        input_tok = torch.ones(
            batch_size, 1, dtype=torch.long, device=device
        )  # <SOS>

        generated: list[torch.Tensor] = []

        for _ in range(self.max_length - 1):
            embedded = self.decoder.embedding(input_tok)
            output, hidden = self.decoder.gru(embedded, hidden)
            logits = self.decoder.output_proj(output)  # [B, 1, V]

            if greedy:
                input_tok = logits.argmax(dim=-1)
            else:
                probs = F.softmax(logits.squeeze(1) / temperature, dim=-1)
                input_tok = torch.multinomial(probs, 1)  # [B, 1]

            generated.append(input_tok)

        return torch.cat(generated, dim=1)  # [B, L-1]

sample

sample(n: int = 1, temperature: float = 1.0, device: Optional[device] = None) -> torch.Tensor

Sample from the prior N(0, I) and decode.

Parameters:

Name Type Description Default
n int

Number of molecules to generate.

1
temperature float

Decoding temperature.

1.0
device device

Device for tensors.

None

Returns:

Type Description
Tensor[n, L - 1]

Generated token ID sequences.

Source code in src/neorx/genmol/models/vae.py
def sample(
    self,
    n: int = 1,
    temperature: float = 1.0,
    device: Optional[torch.device] = None,
) -> torch.Tensor:
    """Sample from the prior ``N(0, I)`` and decode.

    Parameters
    ----------
    n : int
        Number of molecules to generate.
    temperature : float
        Decoding temperature.
    device : torch.device, optional
        Device for tensors.

    Returns
    -------
    Tensor[n, L-1]
        Generated token ID sequences.
    """
    if device is None:
        device = next(self.parameters()).device

    z = torch.randn(n, self.latent_dim, device=device)
    return self.decode(z, temperature=temperature)

vae_loss

vae_loss(logits: Tensor, target: Tensor, mu: Tensor, logvar: Tensor, beta: float = 1.0, pad_idx: int = 0) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]

Compute β-VAE loss = reconstruction + β · KL divergence.

The reconstruction loss is cross-entropy over the vocabulary at each position, ignoring <PAD> tokens.

The KL divergence measures how far the approximate posterior q(z|x) deviates from the prior p(z) = N(0, I):

.. math::

D_{KL}(q \| p) = -\frac{1}{2} \sum_{j=1}^{D}
\left(1 + \log \sigma_j^2 - \mu_j^2 - \sigma_j^2\right)

Parameters:

Name Type Description Default
logits Tensor[B, L - 1, V]

Decoder output logits.

required
target Tensor[B, L]

Ground-truth token IDs (loss is computed against target[:, 1:]).

required
mu Tensor[B, D]

Posterior mean.

required
logvar Tensor[B, D]

Posterior log-variance.

required
beta float

KL weight (β in β-VAE).

1.0
pad_idx int

Padding token index to ignore.

0

Returns:

Name Type Description
total_loss Tensor

β-VAE loss.

recon_loss Tensor

Reconstruction (cross-entropy) loss.

kl_loss Tensor

KL divergence.

Source code in src/neorx/genmol/models/vae.py
def vae_loss(
    logits: torch.Tensor,
    target: torch.Tensor,
    mu: torch.Tensor,
    logvar: torch.Tensor,
    beta: float = 1.0,
    pad_idx: int = 0,
) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
    """Compute β-VAE loss = reconstruction + β · KL divergence.

    The reconstruction loss is cross-entropy over the vocabulary
    at each position, ignoring ``<PAD>`` tokens.

    The KL divergence measures how far the approximate posterior
    ``q(z|x)`` deviates from the prior ``p(z) = N(0, I)``:

    .. math::

        D_{KL}(q \\| p) = -\\frac{1}{2} \\sum_{j=1}^{D}
        \\left(1 + \\log \\sigma_j^2 - \\mu_j^2 - \\sigma_j^2\\right)

    Parameters
    ----------
    logits : Tensor[B, L-1, V]
        Decoder output logits.
    target : Tensor[B, L]
        Ground-truth token IDs (loss is computed against ``target[:, 1:]``).
    mu : Tensor[B, D]
        Posterior mean.
    logvar : Tensor[B, D]
        Posterior log-variance.
    beta : float
        KL weight (β in β-VAE).
    pad_idx : int
        Padding token index to ignore.

    Returns
    -------
    total_loss : Tensor
        β-VAE loss.
    recon_loss : Tensor
        Reconstruction (cross-entropy) loss.
    kl_loss : Tensor
        KL divergence.
    """
    # Target for reconstruction: shift by one (predict next token)
    target_shifted = target[:, 1:]  # [B, L-1]

    # Flatten for cross-entropy
    B, L, V = logits.shape
    recon_loss = F.cross_entropy(
        logits.reshape(B * L, V),
        target_shifted.reshape(B * L),
        ignore_index=pad_idx,
        reduction="mean",
    )

    # KL divergence: analytical formula for Gaussian → N(0,I)
    kl_loss = -0.5 * torch.mean(
        torch.sum(1 + logvar - mu.pow(2) - logvar.exp(), dim=-1)
    )

    total_loss = recon_loss + beta * kl_loss
    return total_loss, recon_loss, kl_loss

VAE Training Loop

Handles the full training pipeline: KL annealing, gradient clipping, learning-rate scheduling, mixed-precision training, and checkpointing.

Training strategy
  • KL annealing — the β weight on the KL divergence is linearly increased from beta_start (0.01) to beta_end (1.0) over the first anneal_epochs (10) epochs. This prevents posterior collapse, where the encoder learns to ignore the input and the KL term drops to zero. By starting with a low β, the model first learns good reconstructions, then gradually learns a structured latent space.

  • Gradient clipping — max-norm clipping at 1.0 prevents exploding gradients, which are common in GRU-based models on long sequences.

  • ReduceLROnPlateau — if validation loss doesn't improve for patience epochs, the learning rate is reduced by a factor of 0.5.

  • Mixed precision — torch.amp on CUDA/MPS accelerates training by ~2× on modern GPUs with TF32/FP16 compute.

  • Checkpoints — model + optimizer state saved every save_every epochs and at the best validation loss.

TrainConfig dataclass

Training hyperparameters.

All defaults are tuned for drug-like molecule generation on a single GPU.

Source code in src/neorx/genmol/train.py
@dataclass
class TrainConfig:
    """Training hyperparameters.

    All defaults are tuned for drug-like molecule generation on
    a single GPU.
    """

    # Optimiser
    lr: float = 1e-3
    weight_decay: float = 0.0
    grad_clip: float = 1.0

    # KL annealing
    beta_start: float = 0.01
    beta_end: float = 1.0
    anneal_epochs: int = 10

    # Schedule
    epochs: int = 100
    patience: int = 5
    lr_factor: float = 0.5

    # Checkpointing
    save_every: int = 5
    checkpoint_dir: str = "checkpoints/genmol"

    # Mixed precision
    use_amp: bool = True

    # Logging
    log_every: int = 100  # log every N batches

    def to_dict(self) -> dict:
        return asdict(self)

train_vae

train_vae(model: MolVAE, train_loader: DataLoader, val_loader: DataLoader, config: Optional[TrainConfig] = None, tokenizer: Optional[SmilesTokenizer] = None, device: Optional[device] = None) -> dict

Train a MolVAE model.

Parameters:

Name Type Description Default
model MolVAE

The VAE to train.

required
train_loader DataLoader

Training data.

required
val_loader DataLoader

Validation data (for LR scheduling and early stopping).

required
config TrainConfig

Hyperparameters. Defaults are sensible.

None
tokenizer SmilesTokenizer

Saved alongside checkpoints for later generation.

None
device device

Training device.

None

Returns:

Type Description
dict

Training history with keys: train_loss, val_loss, train_recon, train_kl, val_recon, val_kl, beta, lr.

Source code in src/neorx/genmol/train.py
def train_vae(
    model: MolVAE,
    train_loader: DataLoader,
    val_loader: DataLoader,
    config: Optional[TrainConfig] = None,
    tokenizer: Optional[SmilesTokenizer] = None,
    device: Optional[torch.device] = None,
) -> dict:
    """Train a MolVAE model.

    Parameters
    ----------
    model : MolVAE
        The VAE to train.
    train_loader : DataLoader
        Training data.
    val_loader : DataLoader
        Validation data (for LR scheduling and early stopping).
    config : TrainConfig, optional
        Hyperparameters.  Defaults are sensible.
    tokenizer : SmilesTokenizer, optional
        Saved alongside checkpoints for later generation.
    device : torch.device, optional
        Training device.

    Returns
    -------
    dict
        Training history with keys: ``train_loss``, ``val_loss``,
        ``train_recon``, ``train_kl``, ``val_recon``, ``val_kl``,
        ``beta``, ``lr``.
    """
    if config is None:
        config = TrainConfig()
    if device is None:
        device = _get_device()

    logger.info("Training on %s.", device)
    model = model.to(device)

    optimizer = Adam(
        model.parameters(),
        lr=config.lr,
        weight_decay=config.weight_decay,
    )
    scheduler = ReduceLROnPlateau(
        optimizer,
        mode="min",
        factor=config.lr_factor,
        patience=config.patience,
    )

    # Mixed precision
    use_amp = config.use_amp and device.type in ("cuda",)
    scaler = torch.amp.GradScaler("cuda", enabled=use_amp)

    # Checkpoint directory
    ckpt_dir = Path(config.checkpoint_dir)
    ckpt_dir.mkdir(parents=True, exist_ok=True)

    # Save config
    config_path = ckpt_dir / "config.json"
    config_path.write_text(json.dumps(config.to_dict(), indent=2))

    # Save tokenizer if provided
    if tokenizer is not None:
        tokenizer.save(ckpt_dir / "tokenizer.json")

    # History
    history: dict[str, list[float]] = {
        "train_loss": [],
        "val_loss": [],
        "train_recon": [],
        "train_kl": [],
        "val_recon": [],
        "val_kl": [],
        "beta": [],
        "lr": [],
    }

    best_val_loss = float("inf")
    pad_idx = model.pad_idx

    for epoch in range(config.epochs):
        t0 = time.time()
        beta = _get_beta(epoch, config)

        # ── Training ────────────────────────────────────────────
        model.train()
        epoch_loss = 0.0
        epoch_recon = 0.0
        epoch_kl = 0.0
        n_batches = 0

        for batch_idx, batch in enumerate(train_loader):
            x = batch["input_ids"].to(device)

            optimizer.zero_grad()

            with torch.amp.autocast(device.type, enabled=use_amp):
                logits, mu, logvar = model(x)
                loss, recon, kl = vae_loss(
                    logits, x, mu, logvar, beta=beta, pad_idx=pad_idx
                )

            scaler.scale(loss).backward()
            scaler.unscale_(optimizer)
            nn.utils.clip_grad_norm_(model.parameters(), config.grad_clip)
            scaler.step(optimizer)
            scaler.update()

            epoch_loss += loss.item()
            epoch_recon += recon.item()
            epoch_kl += kl.item()
            n_batches += 1

            if (batch_idx + 1) % config.log_every == 0:
                logger.info(
                    "  [%d/%d] batch %d: loss=%.4f recon=%.4f kl=%.4f β=%.4f",
                    epoch + 1,
                    config.epochs,
                    batch_idx + 1,
                    loss.item(),
                    recon.item(),
                    kl.item(),
                    beta,
                )

        avg_train = epoch_loss / max(n_batches, 1)
        avg_recon = epoch_recon / max(n_batches, 1)
        avg_kl = epoch_kl / max(n_batches, 1)

        # ── Validation ──────────────────────────────────────────
        model.eval()
        val_loss = 0.0
        val_recon = 0.0
        val_kl = 0.0
        val_batches = 0

        with torch.no_grad():
            for batch in val_loader:
                x = batch["input_ids"].to(device)
                logits, mu, logvar = model(x)
                loss, recon, kl = vae_loss(
                    logits, x, mu, logvar, beta=beta, pad_idx=pad_idx
                )
                val_loss += loss.item()
                val_recon += recon.item()
                val_kl += kl.item()
                val_batches += 1

        avg_val = val_loss / max(val_batches, 1)
        avg_val_recon = val_recon / max(val_batches, 1)
        avg_val_kl = val_kl / max(val_batches, 1)

        # LR scheduling
        scheduler.step(avg_val)
        current_lr = optimizer.param_groups[0]["lr"]

        elapsed = time.time() - t0
        logger.info(
            "Epoch %d/%d (%.1fs): train=%.4f val=%.4f "
            "recon=%.4f/%.4f kl=%.4f/%.4f β=%.4f lr=%.2e",
            epoch + 1,
            config.epochs,
            elapsed,
            avg_train,
            avg_val,
            avg_recon,
            avg_val_recon,
            avg_kl,
            avg_val_kl,
            beta,
            current_lr,
        )

        # ── Record history ──────────────────────────────────────
        history["train_loss"].append(avg_train)
        history["val_loss"].append(avg_val)
        history["train_recon"].append(avg_recon)
        history["train_kl"].append(avg_kl)
        history["val_recon"].append(avg_val_recon)
        history["val_kl"].append(avg_val_kl)
        history["beta"].append(beta)
        history["lr"].append(current_lr)

        # ── Checkpoints ─────────────────────────────────────────
        if avg_val < best_val_loss:
            best_val_loss = avg_val
            torch.save(
                {
                    "epoch": epoch,
                    "model_state_dict": model.state_dict(),
                    "optimizer_state_dict": optimizer.state_dict(),
                    "val_loss": avg_val,
                    "config": config.to_dict(),
                },
                ckpt_dir / "best_model.pt",
            )
            logger.info("  ★ New best model saved (val_loss=%.4f).", avg_val)

        if (epoch + 1) % config.save_every == 0:
            torch.save(
                {
                    "epoch": epoch,
                    "model_state_dict": model.state_dict(),
                    "optimizer_state_dict": optimizer.state_dict(),
                    "val_loss": avg_val,
                    "config": config.to_dict(),
                },
                ckpt_dir / f"checkpoint_epoch_{epoch + 1}.pt",
            )

    # Save final model
    torch.save(
        {
            "epoch": config.epochs - 1,
            "model_state_dict": model.state_dict(),
            "optimizer_state_dict": optimizer.state_dict(),
            "val_loss": avg_val,
            "config": config.to_dict(),
        },
        ckpt_dir / "final_model.pt",
    )

    # Save training history
    history_path = ckpt_dir / "history.json"
    history_path.write_text(json.dumps(history, indent=2))
    logger.info("Training complete. History → %s", history_path)

    return history

load_checkpoint

load_checkpoint(checkpoint_path: str | Path, model: MolVAE, optimizer: Optional[Adam] = None, device: Optional[device] = None) -> dict

Load a training checkpoint.

Parameters:

Name Type Description Default
checkpoint_path str or Path

Path to .pt checkpoint file.

required
model MolVAE

Model to load weights into.

required
optimizer Adam

Optimizer to restore state.

None
device device

Map location for loading.

None

Returns:

Type Description
dict

Checkpoint metadata (epoch, val_loss, config).

Source code in src/neorx/genmol/train.py
def load_checkpoint(
    checkpoint_path: str | Path,
    model: MolVAE,
    optimizer: Optional[Adam] = None,
    device: Optional[torch.device] = None,
) -> dict:
    """Load a training checkpoint.

    Parameters
    ----------
    checkpoint_path : str or Path
        Path to ``.pt`` checkpoint file.
    model : MolVAE
        Model to load weights into.
    optimizer : Adam, optional
        Optimizer to restore state.
    device : torch.device, optional
        Map location for loading.

    Returns
    -------
    dict
        Checkpoint metadata (epoch, val_loss, config).
    """
    if device is None:
        device = _get_device()

    ckpt = torch.load(checkpoint_path, map_location=device, weights_only=False)
    model.load_state_dict(ckpt["model_state_dict"])

    if optimizer is not None and "optimizer_state_dict" in ckpt:
        optimizer.load_state_dict(ckpt["optimizer_state_dict"])

    logger.info(
        "Loaded checkpoint from epoch %d (val_loss=%.4f).",
        ckpt.get("epoch", -1),
        ckpt.get("val_loss", float("inf")),
    )

    return {
        "epoch": ckpt.get("epoch", -1),
        "val_loss": ckpt.get("val_loss"),
        "config": ckpt.get("config"),
    }

neorx.molscreen

Drug-likeness screening. See MolScreen.

MolScreen SMILES Parser

Parses and validates SMILES (Simplified Molecular-Input Line-Entry System) strings using RDKit, and provides name-to-SMILES lookup via the PubChem PUG REST API.

SMILES is the lingua franca of cheminformatics — a line notation that encodes molecular structure as a string. For example, CCO is ethanol and c1ccccc1 is benzene.

This module is the first step in the MolScreen pipeline: every molecule enters as a SMILES string and must be validated before any properties can be calculated.

parse_smiles

parse_smiles(smiles: str) -> Optional[Chem.Mol]

Parse a SMILES string and return an RDKit Mol object.

Parameters:

Name Type Description Default
smiles str

A SMILES string representing a chemical structure.

required

Returns:

Type Description
Mol | None

The parsed molecule, or None if the SMILES is invalid.

Notes

RDKit's MolFromSmiles returns None for un-parseable strings rather than raising an exception. We log a warning so callers can trace failures without try/except boilerplate.

Examples:

>>> mol = parse_smiles("CCO")  # ethanol
>>> mol is not None
True
>>> parse_smiles("not_a_smiles") is None
True
Source code in src/neorx/molscreen/parser.py
def parse_smiles(smiles: str) -> Optional[Chem.Mol]:
    """Parse a SMILES string and return an RDKit ``Mol`` object.

    Parameters
    ----------
    smiles:
        A SMILES string representing a chemical structure.

    Returns
    -------
    Chem.Mol | None
        The parsed molecule, or ``None`` if the SMILES is invalid.

    Notes
    -----
    RDKit's ``MolFromSmiles`` returns ``None`` for un-parseable strings
    rather than raising an exception.  We log a warning so callers can
    trace failures without try/except boilerplate.

    Examples
    --------
    >>> mol = parse_smiles("CCO")  # ethanol
    >>> mol is not None
    True
    >>> parse_smiles("not_a_smiles") is None
    True
    """
    if not smiles or not isinstance(smiles, str):
        logger.warning("Empty or non-string input passed to parse_smiles.")
        return None

    smiles = smiles.strip()
    mol = Chem.MolFromSmiles(smiles)
    if mol is None:
        logger.warning("Invalid SMILES string: '%s'", smiles)
    return mol

validate_smiles

validate_smiles(smiles: str) -> bool

Return True if smiles can be parsed into a valid molecule.

This is a thin convenience wrapper around :func:parse_smiles.

Parameters:

Name Type Description Default
smiles str

SMILES string to validate.

required

Returns:

Type Description
bool
Source code in src/neorx/molscreen/parser.py
def validate_smiles(smiles: str) -> bool:
    """Return ``True`` if *smiles* can be parsed into a valid molecule.

    This is a thin convenience wrapper around :func:`parse_smiles`.

    Parameters
    ----------
    smiles:
        SMILES string to validate.

    Returns
    -------
    bool
    """
    return parse_smiles(smiles) is not None

canonicalise

canonicalise(smiles: str) -> str | None

Return the canonical SMILES for a molecule.

Canonical SMILES is a unique, deterministic representation — two molecules with the same structure will always produce the same canonical SMILES. This is essential for de-duplication and database lookups.

Parameters:

Name Type Description Default
smiles str

Input SMILES (may be non-canonical).

required

Returns:

Type Description
str | None

Canonical SMILES string, or None if input is invalid.

Source code in src/neorx/molscreen/parser.py
def canonicalise(smiles: str) -> str | None:
    """Return the *canonical* SMILES for a molecule.

    Canonical SMILES is a unique, deterministic representation — two
    molecules with the same structure will always produce the same
    canonical SMILES.  This is essential for de-duplication and database
    lookups.

    Parameters
    ----------
    smiles:
        Input SMILES (may be non-canonical).

    Returns
    -------
    str | None
        Canonical SMILES string, or ``None`` if input is invalid.
    """
    mol = parse_smiles(smiles)
    if mol is None:
        return None
    return Chem.MolToSmiles(mol)

name_to_smiles

name_to_smiles(name: str) -> str | None

Look up a drug / compound name and return its canonical SMILES.

Uses the PubChem PUG REST API <https://pubchem.ncbi.nlm.nih.gov/rest/pug>_ to resolve common names (e.g. "aspirin", "ibuprofen") to SMILES.

Parameters:

Name Type Description Default
name str

Common or IUPAC name of the compound.

required

Returns:

Type Description
str | None

Canonical SMILES if found, otherwise None.

Notes

This makes an HTTP request to an external service. It will time out after _PUBCHEM_TIMEOUT seconds and return None on any network error.

Source code in src/neorx/molscreen/parser.py
def name_to_smiles(name: str) -> str | None:
    """Look up a drug / compound name and return its canonical SMILES.

    Uses the `PubChem PUG REST API
    <https://pubchem.ncbi.nlm.nih.gov/rest/pug>`_ to resolve common names
    (e.g. "aspirin", "ibuprofen") to SMILES.

    Parameters
    ----------
    name:
        Common or IUPAC name of the compound.

    Returns
    -------
    str | None
        Canonical SMILES if found, otherwise ``None``.

    Notes
    -----
    This makes an HTTP request to an external service.  It will time out
    after ``_PUBCHEM_TIMEOUT`` seconds and return ``None`` on any network
    error.
    """
    if not name or not isinstance(name, str):
        logger.warning("Empty or non-string name passed to name_to_smiles.")
        return None

    name = name.strip()
    url = f"{_PUBCHEM_BASE}/compound/name/{name}/property/CanonicalSMILES/JSON"

    try:
        response = requests.get(url, timeout=_PUBCHEM_TIMEOUT)
        response.raise_for_status()
        data = response.json()
        smiles = (
            data.get("PropertyTable", {})
            .get("Properties", [{}])[0]
            .get("CanonicalSMILES")
        )
        if smiles:
            logger.info("Resolved '%s' → '%s' via PubChem.", name, smiles)
            return smiles
        logger.warning("PubChem returned no SMILES for '%s'.", name)
        return None
    except requests.exceptions.RequestException as exc:
        logger.error("PubChem lookup failed for '%s': %s", name, exc)
        return None
    except (KeyError, IndexError, ValueError) as exc:
        logger.error("Unexpected PubChem response for '%s': %s", name, exc)
        return None

smart_parse

smart_parse(input_str: str) -> tuple[Chem.Mol | None, str | None]

Attempt to interpret input_str as a SMILES string or a drug name.

Strategy: 1. Try parsing as SMILES directly. 2. If that fails, treat it as a compound name and query PubChem.

Parameters:

Name Type Description Default
input_str str

A SMILES string or compound name (e.g. "aspirin").

required

Returns:

Type Description
tuple[Mol | None, str | None]

(mol_object, canonical_smiles) — both None if resolution fails.

Source code in src/neorx/molscreen/parser.py
def smart_parse(input_str: str) -> tuple[Chem.Mol | None, str | None]:
    """Attempt to interpret *input_str* as a SMILES string **or** a drug name.

    Strategy:
    1. Try parsing as SMILES directly.
    2. If that fails, treat it as a compound name and query PubChem.

    Parameters
    ----------
    input_str:
        A SMILES string or compound name (e.g. ``"aspirin"``).

    Returns
    -------
    tuple[Mol | None, str | None]
        ``(mol_object, canonical_smiles)`` — both ``None`` if resolution
        fails.
    """
    if not input_str or not isinstance(input_str, str):
        return None, None

    input_str = input_str.strip()

    # 1) Try direct SMILES parse
    mol = parse_smiles(input_str)
    if mol is not None:
        return mol, Chem.MolToSmiles(mol)

    # 2) Treat as a compound name
    logger.info(
        "Could not parse '%s' as SMILES — attempting PubChem name lookup.",
        input_str,
    )
    smiles = name_to_smiles(input_str)
    if smiles is None:
        return None, None

    mol = parse_smiles(smiles)
    return mol, smiles

MolScreen Property Calculator

Calculates physico-chemical molecular properties using RDKit descriptors. These properties are the foundation of drug-likeness assessment — they determine whether a molecule can be absorbed, distributed, metabolised, and excreted (ADME) in the human body.

Every property calculated here maps to a biological reality:

  • Molecular Weight — bigger molecules struggle to cross cell membranes.
  • LogP — the oil/water balance controls membrane permeation.
  • HBD / HBA — hydrogen bonds to water must be broken to enter cells.
  • TPSA — polar surface area predicts oral absorption and BBB crossing.
  • Rotatable Bonds — flexibility affects binding entropy and bioavailability.
  • Rings / Aromatic Rings — shape and planarity affect selectivity.
  • Fsp3 — three-dimensionality correlates with clinical success.
  • Molar Refractivity — volume and polarisability proxy.

calculate_properties

calculate_properties(mol_or_smiles: Mol | str) -> Optional[MolecularProperties]

Calculate a full suite of molecular properties.

Parameters:

Name Type Description Default
mol_or_smiles Mol | str

An RDKit Mol object or a SMILES string. If a string is provided it will be parsed first.

required

Returns:

Type Description
MolecularProperties | None

A populated data model, or None if the input is invalid.

Notes

All descriptors are computed via RDKit's fast C++ backend. The function is deliberately stateless so it can be safely parallelised for batch processing.

Source code in src/neorx/molscreen/properties.py
def calculate_properties(mol_or_smiles: Chem.Mol | str) -> Optional[MolecularProperties]:
    """Calculate a full suite of molecular properties.

    Parameters
    ----------
    mol_or_smiles:
        An RDKit ``Mol`` object **or** a SMILES string.  If a string is
        provided it will be parsed first.

    Returns
    -------
    MolecularProperties | None
        A populated data model, or ``None`` if the input is invalid.

    Notes
    -----
    All descriptors are computed via RDKit's fast C++ backend.  The
    function is deliberately stateless so it can be safely parallelised
    for batch processing.
    """
    # Resolve input to an RDKit Mol
    if isinstance(mol_or_smiles, str):
        mol = parse_smiles(mol_or_smiles)
        if mol is None:
            return None
    else:
        mol = mol_or_smiles

    try:
        canonical_smiles = Chem.MolToSmiles(mol)

        return MolecularProperties(
            smiles=canonical_smiles,
            molecular_weight=_molecular_weight(mol),
            logp=_logp(mol),
            hbd=_hbd(mol),
            hba=_hba(mol),
            tpsa=_tpsa(mol),
            rotatable_bonds=_rotatable_bonds(mol),
            num_rings=_num_rings(mol),
            num_aromatic_rings=_num_aromatic_rings(mol),
            fsp3=_fsp3(mol),
            molar_refractivity=_molar_refractivity(mol),
        )
    except Exception:
        logger.exception("Failed to calculate properties for molecule.")
        return None

MolScreen Synthetic Accessibility & Drug-Likeness Scores

Two complementary scores that answer the questions:

  1. SA Score (Synthetic Accessibility) — Can a chemist actually make this molecule? A score from 1 (trivially easy) to 10 (practically impossible). Most approved drugs score 2–5. The algorithm was designed by Ertl & Schuffenhauer (2009) and is bundled with RDKit.

  2. QED (Quantitative Estimate of Drug-likeness) — How drug-like is this molecule overall? A single number from 0 to 1 that integrates eight desirability functions (MW, LogP, HBA, HBD, TPSA, RotBonds, AromaticRings, Alerts) via a geometric mean. Designed by Bickerton et al. (2012). Higher = more drug-like.

Why both?

SA Score captures synthetic feasibility (can we build it?), while QED captures pharmacological desirability (should we build it?). A molecule needs to score well on both to be a viable drug candidate.

qed_score

qed_score(mol_or_smiles: Mol | str) -> Optional[float]

Calculate the QED (Quantitative Estimate of Drug-likeness).

QED was designed to replace the pass/fail nature of Lipinski with a continuous score. It uses desirability functions for eight properties:

  1. Molecular weight
  2. LogP
  3. HBA
  4. HBD
  5. Polar surface area
  6. Rotatable bonds
  7. Aromatic rings
  8. Number of structural alerts

Each property is scored 0–1 via a fitted asymmetric double-sigmoidal function, and the final QED is the weighted geometric mean.

Interpretation ~~~~~~~~~~~~~~ * > 0.67 — Favourable (in the "drug-like" sweet spot). * 0.49–0.67 — Moderate (some properties are sub-optimal). * < 0.49 — Unfavourable (multiple properties outside drug space).

For reference: aspirin QED ≈ 0.55, atorvastatin (Lipitor) ≈ 0.15.

Parameters:

Name Type Description Default
mol_or_smiles Mol | str

RDKit Mol or SMILES string.

required

Returns:

Type Description
float | None

QED score rounded to 3 decimal places, or None on failure.

Source code in src/neorx/molscreen/accessibility.py
def qed_score(mol_or_smiles: Chem.Mol | str) -> Optional[float]:
    """Calculate the **QED** (Quantitative Estimate of Drug-likeness).

    QED was designed to replace the pass/fail nature of Lipinski with a
    continuous score.  It uses desirability functions for eight properties:

    1. Molecular weight
    2. LogP
    3. HBA
    4. HBD
    5. Polar surface area
    6. Rotatable bonds
    7. Aromatic rings
    8. Number of structural alerts

    Each property is scored 0–1 via a fitted asymmetric double-sigmoidal
    function, and the final QED is the weighted geometric mean.

    Interpretation
    ~~~~~~~~~~~~~~
    * > 0.67 — *Favourable* (in the "drug-like" sweet spot).
    * 0.49–0.67 — *Moderate* (some properties are sub-optimal).
    * < 0.49 — *Unfavourable* (multiple properties outside drug space).

    For reference: aspirin QED ≈ 0.55, atorvastatin (Lipitor) ≈ 0.15.

    Parameters
    ----------
    mol_or_smiles:
        RDKit Mol or SMILES string.

    Returns
    -------
    float | None
        QED score rounded to 3 decimal places, or ``None`` on failure.
    """
    mol = _resolve_mol(mol_or_smiles)
    if mol is None:
        return None

    try:
        score = QED.qed(mol)
        return round(score, 3)
    except Exception:
        logger.exception("QED calculation failed.")
        return None

sa_score

sa_score(mol_or_smiles: Mol | str) -> Optional[float]

Calculate the Synthetic Accessibility Score (1–10).

The SA Score estimates how easy it would be for a medicinal chemist to synthesise a molecule. It combines two components:

  • Fragment score — how common the molecule's substructures are in known compounds (PubChem). Common fragments → easy synthesis.
  • Complexity penalty — based on ring complexity, stereocentres, macrocycles, and spiro/bridged systems.

Interpretation ~~~~~~~~~~~~~~ * 1–3 — Easy to synthesise (simple commercial building blocks). * 3–5 — Moderate (most approved drugs live here). * 5–7 — Difficult (requires specialised chemistry). * 7–10 — Very difficult to near-impossible.

Parameters:

Name Type Description Default
mol_or_smiles Mol | str

RDKit Mol or SMILES string.

required

Returns:

Type Description
float | None

SA score rounded to 2 decimal places, or None on failure.

Source code in src/neorx/molscreen/accessibility.py
def sa_score(mol_or_smiles: Chem.Mol | str) -> Optional[float]:
    """Calculate the **Synthetic Accessibility Score** (1–10).

    The SA Score estimates how easy it would be for a medicinal chemist to
    synthesise a molecule.  It combines two components:

    * **Fragment score** — how common the molecule's substructures are in
      known compounds (PubChem).  Common fragments → easy synthesis.
    * **Complexity penalty** — based on ring complexity, stereocentres,
      macrocycles, and spiro/bridged systems.

    Interpretation
    ~~~~~~~~~~~~~~
    * 1–3  — Easy to synthesise (simple commercial building blocks).
    * 3–5  — Moderate (most approved drugs live here).
    * 5–7  — Difficult (requires specialised chemistry).
    * 7–10 — Very difficult to near-impossible.

    Parameters
    ----------
    mol_or_smiles:
        RDKit Mol or SMILES string.

    Returns
    -------
    float | None
        SA score rounded to 2 decimal places, or ``None`` on failure.
    """
    mol = _resolve_mol(mol_or_smiles)
    if mol is None:
        return None

    try:
        score = sascorer.calculateScore(mol)
        return round(score, 2)
    except Exception:
        logger.exception("SA Score calculation failed.")
        return None

MolScreen Drug-Likeness Filters

Pharmaceutical industry filters that encode decades of empirical knowledge about what makes a small molecule likely to succeed as an oral drug.

Each filter captures a different facet of "drug-likeness":

  • Lipinski's Rule of Five (1997) — The original and most famous filter. Based on an analysis of ~2 200 drugs: oral drugs tend to have MW ≤ 500, LogP ≤ 5, HBD ≤ 5, HBA ≤ 10. One violation is tolerated.

  • Veber Rules (2002) — Adds flexibility and polarity: rotatable bonds ≤ 10 and TPSA ≤ 140 Ų. Predicts rat oral bioavailability.

  • Ghose Filter (1999) — Tighter multi-dimensional box: MW 160–480, LogP −0.4–5.6, MR 40–130, atoms 20–70.

  • Egan Filter (2000) — Simple 2D ellipse in LogP/TPSA space that predicts intestinal absorption.

  • PAINS (2010) — Pan-Assay Interference Compounds. Substructures that give false positives in biological assays (e.g. rhodanines, quinones). These waste enormous amounts of drug-discovery resources.

  • Brenk Filter (2008) — Structural alerts for reactive, toxic, or metabolically unstable functional groups (e.g. Michael acceptors, alkyl halides, epoxides).

lipinski_filter

lipinski_filter(mol: Mol) -> FilterResult

Apply Lipinski's Rule of Five.

The rule states that poor absorption or permeation is more likely when:

  • Molecular weight > 500 Da
  • LogP > 5
  • Hydrogen-bond donors > 5
  • Hydrogen-bond acceptors > 10

A molecule passes if it has ≤ 1 violation (the original paper allows one).

Parameters:

Name Type Description Default
mol Mol

RDKit Mol object.

required

Returns:

Type Description
FilterResult
Source code in src/neorx/molscreen/filters.py
def lipinski_filter(mol: Chem.Mol) -> FilterResult:
    """Apply **Lipinski's Rule of Five**.

    The rule states that poor absorption or permeation is more likely when:

    * Molecular weight > 500 Da
    * LogP > 5
    * Hydrogen-bond donors > 5
    * Hydrogen-bond acceptors > 10

    A molecule **passes** if it has ≤ 1 violation (the original paper
    allows one).

    Parameters
    ----------
    mol:
        RDKit Mol object.

    Returns
    -------
    FilterResult
    """
    mw = Descriptors.ExactMolWt(mol)
    logp = Descriptors.MolLogP(mol)
    hbd = Lipinski.NumHDonors(mol)
    hba = Lipinski.NumHAcceptors(mol)

    violations: list[str] = []

    if mw > 500:
        violations.append(f"MW {mw:.1f} > 500")
    if logp > 5:
        violations.append(f"LogP {logp:.2f} > 5")
    if hbd > 5:
        violations.append(f"HBD {hbd} > 5")
    if hba > 10:
        violations.append(f"HBA {hba} > 10")

    return FilterResult(
        name="Lipinski",
        passed=len(violations) <= 1,
        violations=violations,
    )

veber_filter

veber_filter(mol: Mol) -> FilterResult

Apply Veber Rules for oral bioavailability.

Both conditions must be satisfied:

  • Rotatable bonds ≤ 10
  • TPSA ≤ 140 Ų

Veber et al. (2002) showed these two descriptors are sufficient to predict rat oral bioavailability, independent of molecular weight.

Parameters:

Name Type Description Default
mol Mol

RDKit Mol object.

required

Returns:

Type Description
FilterResult
Source code in src/neorx/molscreen/filters.py
def veber_filter(mol: Chem.Mol) -> FilterResult:
    """Apply **Veber Rules** for oral bioavailability.

    Both conditions must be satisfied:

    * Rotatable bonds ≤ 10
    * TPSA ≤ 140 Ų

    Veber et al. (2002) showed these two descriptors are sufficient to
    predict rat oral bioavailability, independent of molecular weight.

    Parameters
    ----------
    mol:
        RDKit Mol object.

    Returns
    -------
    FilterResult
    """
    rot = Lipinski.NumRotatableBonds(mol)
    tpsa = Descriptors.TPSA(mol)

    violations: list[str] = []

    if rot > 10:
        violations.append(f"Rotatable bonds {rot} > 10")
    if tpsa > 140:
        violations.append(f"TPSA {tpsa:.1f} > 140 Ų")

    return FilterResult(
        name="Veber",
        passed=len(violations) == 0,
        violations=violations,
    )

ghose_filter

ghose_filter(mol: Mol) -> FilterResult

Apply the Ghose Filter.

A four-dimensional box defining drug-like chemical space:

  • 160 ≤ MW ≤ 480
  • −0.4 ≤ LogP ≤ 5.6
  • 40 ≤ Molar Refractivity ≤ 130
  • 20 ≤ Total atom count ≤ 70

Parameters:

Name Type Description Default
mol Mol

RDKit Mol object.

required

Returns:

Type Description
FilterResult
Source code in src/neorx/molscreen/filters.py
def ghose_filter(mol: Chem.Mol) -> FilterResult:
    """Apply the **Ghose Filter**.

    A four-dimensional box defining drug-like chemical space:

    * 160 ≤ MW ≤ 480
    * −0.4 ≤ LogP ≤ 5.6
    * 40 ≤ Molar Refractivity ≤ 130
    * 20 ≤ Total atom count ≤ 70

    Parameters
    ----------
    mol:
        RDKit Mol object.

    Returns
    -------
    FilterResult
    """
    mw = Descriptors.ExactMolWt(mol)
    logp = Descriptors.MolLogP(mol)
    mr = Descriptors.MolMR(mol)
    n_atoms = mol.GetNumAtoms()

    violations: list[str] = []

    if not (160 <= mw <= 480):
        violations.append(f"MW {mw:.1f} outside [160, 480]")
    if not (-0.4 <= logp <= 5.6):
        violations.append(f"LogP {logp:.2f} outside [-0.4, 5.6]")
    if not (40 <= mr <= 130):
        violations.append(f"MR {mr:.1f} outside [40, 130]")
    if not (20 <= n_atoms <= 70):
        violations.append(f"Atom count {n_atoms} outside [20, 70]")

    return FilterResult(
        name="Ghose",
        passed=len(violations) == 0,
        violations=violations,
    )

egan_filter

egan_filter(mol: Mol) -> FilterResult

Apply the Egan Filter for intestinal absorption.

Defines an elliptical region in TPSA / LogP space:

  • TPSA ≤ 131.6 Ų
  • LogP ≤ 5.88

Molecules within this region are predicted to have good human intestinal absorption (HIA).

Parameters:

Name Type Description Default
mol Mol

RDKit Mol object.

required

Returns:

Type Description
FilterResult
Source code in src/neorx/molscreen/filters.py
def egan_filter(mol: Chem.Mol) -> FilterResult:
    """Apply the **Egan Filter** for intestinal absorption.

    Defines an elliptical region in TPSA / LogP space:

    * TPSA ≤ 131.6 Ų
    * LogP ≤ 5.88

    Molecules within this region are predicted to have good human
    intestinal absorption (HIA).

    Parameters
    ----------
    mol:
        RDKit Mol object.

    Returns
    -------
    FilterResult
    """
    tpsa = Descriptors.TPSA(mol)
    logp = Descriptors.MolLogP(mol)

    violations: list[str] = []

    if tpsa > 131.6:
        violations.append(f"TPSA {tpsa:.1f} > 131.6 Ų")
    if logp > 5.88:
        violations.append(f"LogP {logp:.2f} > 5.88")

    return FilterResult(
        name="Egan",
        passed=len(violations) == 0,
        violations=violations,
    )

pains_filter

pains_filter(mol: Mol) -> FilterResult

Screen for PAINS (Pan-Assay Interference Compounds).

PAINS are substructures known to interfere with many biological assays — they appear as "hits" but are actually artefacts. Common PAINS motifs include:

  • Rhodanines
  • Catechols
  • Quinones
  • Hydroxyphenyl hydrazones

Publishing a PAINS compound as a "hit" is considered a serious credibility issue in modern drug discovery.

Parameters:

Name Type Description Default
mol Mol

RDKit Mol object.

required

Returns:

Type Description
FilterResult
Source code in src/neorx/molscreen/filters.py
def pains_filter(mol: Chem.Mol) -> FilterResult:
    """Screen for **PAINS** (Pan-Assay Interference Compounds).

    PAINS are substructures known to interfere with many biological
    assays — they appear as "hits" but are actually artefacts.  Common
    PAINS motifs include:

    * Rhodanines
    * Catechols
    * Quinones
    * Hydroxyphenyl hydrazones

    Publishing a PAINS compound as a "hit" is considered a serious
    credibility issue in modern drug discovery.

    Parameters
    ----------
    mol:
        RDKit Mol object.

    Returns
    -------
    FilterResult
    """
    matches = _PAINS_CATALOG.GetMatches(mol)
    violations = [m.GetDescription() for m in matches]

    return FilterResult(
        name="PAINS",
        passed=len(violations) == 0,
        violations=violations,
    )

brenk_filter

brenk_filter(mol: Mol) -> FilterResult

Screen for Brenk structural alerts.

Brenk et al. (2008) compiled a list of 105 substructural features that are undesirable in drug candidates because they are:

  • Chemically reactive (e.g. Michael acceptors, epoxides)
  • Metabolically unstable (e.g. thiols, aldehydes)
  • Toxic or mutagenic (e.g. nitro groups on aromatics)

Parameters:

Name Type Description Default
mol Mol

RDKit Mol object.

required

Returns:

Type Description
FilterResult
Source code in src/neorx/molscreen/filters.py
def brenk_filter(mol: Chem.Mol) -> FilterResult:
    """Screen for **Brenk structural alerts**.

    Brenk et al. (2008) compiled a list of 105 substructural features
    that are undesirable in drug candidates because they are:

    * Chemically reactive (e.g. Michael acceptors, epoxides)
    * Metabolically unstable (e.g. thiols, aldehydes)
    * Toxic or mutagenic (e.g. nitro groups on aromatics)

    Parameters
    ----------
    mol:
        RDKit Mol object.

    Returns
    -------
    FilterResult
    """
    matches = _BRENK_CATALOG.GetMatches(mol)
    violations = [m.GetDescription() for m in matches]

    return FilterResult(
        name="Brenk",
        passed=len(violations) == 0,
        violations=violations,
    )

run_all_filters

run_all_filters(mol: Mol) -> list[FilterResult]

Run all drug-likeness filters on a molecule.

Parameters:

Name Type Description Default
mol Mol

RDKit Mol object.

required

Returns:

Type Description
list[FilterResult]

Results for every filter, in a fixed order.

Source code in src/neorx/molscreen/filters.py
def run_all_filters(mol: Chem.Mol) -> list[FilterResult]:
    """Run **all** drug-likeness filters on a molecule.

    Parameters
    ----------
    mol:
        RDKit Mol object.

    Returns
    -------
    list[FilterResult]
        Results for every filter, in a fixed order.
    """
    return [
        lipinski_filter(mol),
        veber_filter(mol),
        ghose_filter(mol),
        egan_filter(mol),
        pains_filter(mol),
        brenk_filter(mol),
    ]

classify_drug_likeness

classify_drug_likeness(filters: list[FilterResult]) -> str

Classify a molecule based on its filter results.

Classification logic
  • Drug-like — passes Lipinski and Veber and no PAINS.
  • Lead-like — fails one of the above but passes at least 4/6 filters.
  • Not drug-like — fails more than 2 filters.

Parameters:

Name Type Description Default
filters list[FilterResult]

Output of :func:run_all_filters.

required

Returns:

Type Description
str

One of "Drug-like", "Lead-like", "Not drug-like".

Source code in src/neorx/molscreen/filters.py
def classify_drug_likeness(filters: list[FilterResult]) -> str:
    """Classify a molecule based on its filter results.

    Classification logic
    --------------------
    * **Drug-like** — passes Lipinski *and* Veber *and* no PAINS.
    * **Lead-like** — fails one of the above but passes at least 4/6 filters.
    * **Not drug-like** — fails more than 2 filters.

    Parameters
    ----------
    filters:
        Output of :func:`run_all_filters`.

    Returns
    -------
    str
        One of ``"Drug-like"``, ``"Lead-like"``, ``"Not drug-like"``.
    """
    by_name = {f.name: f.passed for f in filters}
    total_passed = sum(1 for f in filters if f.passed)

    core_pass = (
        by_name.get("Lipinski", False)
        and by_name.get("Veber", False)
        and by_name.get("PAINS", True)
    )

    if core_pass and total_passed >= 5:
        return "Drug-like"
    if total_passed >= 4:
        return "Lead-like"
    return "Not drug-like"

Compares a query molecule against a reference set of approved drugs from the ChEMBL database using molecular fingerprints and the Tanimoto similarity coefficient.

Data source

Approved drugs (max_phase = 4) are fetched from ChEMBL via the official chembl_webresource_client. Results are cached locally as a CSV so the API is only hit once (or when you explicitly refresh).

How it works
  1. Each molecule is encoded as a Morgan fingerprint (circular fingerprint, radius=2, 2048 bits). This captures the local chemical environment around every atom up to two bonds away — similar to the ECFP4 fingerprints widely used in pharma.

  2. Fingerprints are compared using the Tanimoto coefficient (a.k.a. Jaccard index):

.. math::

   T(A, B) = \frac{|A \cap B|}{|A \cup B|}

A Tanimoto score of 1.0 means the fingerprints are identical; 0.0 means no overlap.

Why this matters

Finding approved drugs that are structurally similar to a new compound gives clues about its pharmacology, toxicity, and patent landscape. If your molecule is 0.85+ similar to an approved drug, it may share the same target — useful for drug repurposing.

tanimoto_similarity

tanimoto_similarity(smiles_a: str, smiles_b: str) -> Optional[float]

Calculate Tanimoto similarity between two molecules.

Parameters:

Name Type Description Default
smiles_a str

First SMILES string.

required
smiles_b str

Second SMILES string.

required

Returns:

Type Description
float | None

Tanimoto coefficient (0–1), or None if either SMILES is invalid.

Source code in src/neorx/molscreen/similarity.py
def tanimoto_similarity(
    smiles_a: str,
    smiles_b: str,
) -> Optional[float]:
    """Calculate Tanimoto similarity between two molecules.

    Parameters
    ----------
    smiles_a:
        First SMILES string.
    smiles_b:
        Second SMILES string.

    Returns
    -------
    float | None
        Tanimoto coefficient (0–1), or ``None`` if either SMILES is invalid.
    """
    mol_a = parse_smiles(smiles_a)
    mol_b = parse_smiles(smiles_b)
    if mol_a is None or mol_b is None:
        return None

    try:
        fp_a = _MORGAN_GEN.GetFingerprint(mol_a)
        fp_b = _MORGAN_GEN.GetFingerprint(mol_b)
        return round(DataStructs.TanimotoSimilarity(fp_a, fp_b), 4)
    except Exception:
        logger.exception("Tanimoto calculation failed.")
        return None

find_similar_drugs

find_similar_drugs(mol_or_smiles: Mol | str, top_n: int = 5) -> list[SimilarDrug]

Find the most similar FDA-approved drugs to a query molecule.

Parameters:

Name Type Description Default
mol_or_smiles Mol | str

Query molecule (RDKit Mol or SMILES string).

required
top_n int

Number of results to return (default 5).

5

Returns:

Type Description
list[SimilarDrug]

Top-N most similar approved drugs, sorted by descending Tanimoto similarity.

Examples:

>>> results = find_similar_drugs("CC(=O)Oc1ccccc1C(=O)O")  # aspirin
>>> results[0].name
'Aspirin'
Source code in src/neorx/molscreen/similarity.py
def find_similar_drugs(
    mol_or_smiles: Chem.Mol | str,
    top_n: int = 5,
) -> list[SimilarDrug]:
    """Find the most similar FDA-approved drugs to a query molecule.

    Parameters
    ----------
    mol_or_smiles:
        Query molecule (RDKit Mol or SMILES string).
    top_n:
        Number of results to return (default 5).

    Returns
    -------
    list[SimilarDrug]
        Top-N most similar approved drugs, sorted by descending Tanimoto
        similarity.

    Examples
    --------
    >>> results = find_similar_drugs("CC(=O)Oc1ccccc1C(=O)O")  # aspirin
    >>> results[0].name
    'Aspirin'
    """
    # Resolve to Mol
    if isinstance(mol_or_smiles, str):
        mol = parse_smiles(mol_or_smiles)
        if mol is None:
            logger.warning("Invalid SMILES for similarity search.")
            return []
    else:
        mol = mol_or_smiles

    # Compute query fingerprint
    try:
        query_fp = _MORGAN_GEN.GetFingerprint(mol)
    except Exception:
        logger.exception("Could not compute fingerprint for query molecule.")
        return []

    # Compare against all reference drugs
    cache = _get_fingerprint_cache()
    similarities: list[tuple[float, dict]] = []

    for drug_info, ref_fp in cache:
        tanimoto = DataStructs.TanimotoSimilarity(query_fp, ref_fp)
        similarities.append((tanimoto, drug_info))

    # Sort descending by similarity and take top N
    similarities.sort(key=lambda x: x[0], reverse=True)

    results: list[SimilarDrug] = []
    for sim, drug_info in similarities[:top_n]:
        results.append(
            SimilarDrug(
                name=drug_info["name"],
                smiles=drug_info["smiles"],
                similarity=round(sim, 4),
                indication=drug_info.get("indication", ""),
            )
        )

    return results

build_cache

build_cache(limit: int | None = None, force: bool = False) -> Path

Fetch approved drugs from ChEMBL and save to a local CSV cache.

Parameters:

Name Type Description Default
limit int | None

Max drugs to fetch (None = all).

None
force bool

If True, re-fetch even if the cache file already exists.

False

Returns:

Type Description
Path

Path to the generated cache CSV.

Source code in src/neorx/molscreen/similarity.py
def build_cache(limit: int | None = None, force: bool = False) -> Path:
    """Fetch approved drugs from ChEMBL and save to a local CSV cache.

    Parameters
    ----------
    limit:
        Max drugs to fetch (``None`` = all).
    force:
        If ``True``, re-fetch even if the cache file already exists.

    Returns
    -------
    Path
        Path to the generated cache CSV.
    """
    if _CACHE_CSV.exists() and not force:
        logger.info("Cache already exists at %s — use force=True to refresh.", _CACHE_CSV)
        return _CACHE_CSV

    drugs = fetch_approved_drugs_from_chembl(limit=limit)
    if not drugs:
        logger.warning("No drugs fetched from ChEMBL; cache not written.")
        return _CACHE_CSV

    _DATA_DIR.mkdir(parents=True, exist_ok=True)
    with open(_CACHE_CSV, "w", newline="", encoding="utf-8") as fh:
        writer = csv.DictWriter(fh, fieldnames=["chembl_id", "name", "smiles", "indication"])
        writer.writeheader()
        writer.writerows(drugs)

    logger.info("Wrote %d drugs to cache: %s", len(drugs), _CACHE_CSV)
    return _CACHE_CSV

clear_cache

clear_cache() -> None

Clear both the in-memory and on-disk caches.

Call :func:build_cache with force=True afterwards to do a full refresh from ChEMBL.

Source code in src/neorx/molscreen/similarity.py
def clear_cache() -> None:
    """Clear both the in-memory and on-disk caches.

    Call :func:`build_cache` with ``force=True`` afterwards to do a
    full refresh from ChEMBL.
    """
    global _drug_cache, _fp_cache
    _drug_cache = None
    _fp_cache = None
    if _CACHE_CSV.exists():
        _CACHE_CSV.unlink()
        logger.info("Deleted cache file: %s", _CACHE_CSV)

MolScreen Data Models

Pydantic models for molecular screening data. These models define the schema for molecular properties, filter results, and full screening reports.

All models are serialisable to JSON for seamless integration with the FastAPI layer and downstream pipeline modules (DockBot, GenMol).

MolecularProperties

Bases: BaseModel

Calculated physico-chemical properties of a molecule.

Each property has a direct impact on whether a compound can become a successful drug. The docstrings below explain why each matters.

Source code in src/neorx/molscreen/models.py
class MolecularProperties(BaseModel):
    """Calculated physico-chemical properties of a molecule.

    Each property has a direct impact on whether a compound can become a
    successful drug.  The docstrings below explain *why* each matters.
    """

    smiles: str = Field(
        ...,
        description="Canonical SMILES string — the standardised text representation of the molecule.",
    )

    molecular_weight: float = Field(
        ...,
        description=(
            "Molecular weight in Daltons. Drugs need to be absorbed from the gut and "
            "distributed through the blood — molecules above ~500 Da struggle to cross "
            "biological membranes (Lipinski's Rule of Five)."
        ),
    )

    logp: float = Field(
        ...,
        description=(
            "Octanol-water partition coefficient (LogP). Measures hydrophobicity — how "
            "much a molecule prefers oil over water. Cell membranes are lipid bilayers, "
            "so drugs need moderate LogP (ideally 1–3) to cross them. Too high → poor "
            "solubility; too low → can't permeate membranes."
        ),
    )

    hbd: int = Field(
        ...,
        description=(
            "Hydrogen Bond Donors — count of NH and OH groups. These form hydrogen bonds "
            "with water, which must be broken to cross a lipid membrane. More donors = "
            "harder membrane permeation. Lipinski sets the limit at ≤ 5."
        ),
    )

    hba: int = Field(
        ...,
        description=(
            "Hydrogen Bond Acceptors — count of N and O atoms. Like donors, these "
            "hydrogen-bond to water and hinder membrane crossing. Lipinski limit: ≤ 10."
        ),
    )

    tpsa: float = Field(
        ...,
        description=(
            "Topological Polar Surface Area in Ų. The sum of surfaces of polar atoms "
            "(O, N, and attached H). TPSA predicts intestinal absorption and blood-brain "
            "barrier penetration: ≤ 140 Ų for oral absorption, ≤ 90 Ų for CNS drugs."
        ),
    )

    rotatable_bonds: int = Field(
        ...,
        description=(
            "Number of rotatable bonds — measures molecular flexibility. Too many "
            "(> 10) reduces oral bioavailability because the molecule loses too much "
            "entropy when binding to a target (Veber rules)."
        ),
    )

    num_rings: int = Field(
        ...,
        description=(
            "Total number of rings. Rings provide rigidity and shape to a molecule. "
            "Most drugs have 1–5 rings; too many can hurt solubility."
        ),
    )

    num_aromatic_rings: int = Field(
        ...,
        description=(
            "Number of aromatic rings (flat, electron-rich rings like benzene). "
            "Aromatic rings aid target binding via π-stacking but too many (> 3) "
            "increase planarity, which causes aggregation and poor solubility."
        ),
    )

    fsp3: float = Field(
        ...,
        description=(
            "Fraction of sp3-hybridised carbons. Measures three-dimensionality — "
            "higher Fsp3 (≥ 0.42) correlates with higher clinical success rates "
            "because 3D molecules are more selective and soluble than flat ones."
        ),
    )

    molar_refractivity: float = Field(
        ...,
        description=(
            "Molar refractivity (MR). Related to molecular volume and polarisability. "
            "Used in the Ghose filter (40–130) as a proxy for molecular size and "
            "electronic character."
        ),
    )

FilterResult

Bases: BaseModel

Result of a single drug-likeness filter evaluation.

Each filter encodes decades of pharmaceutical industry knowledge about what makes a molecule likely to succeed as an oral drug.

Source code in src/neorx/molscreen/models.py
class FilterResult(BaseModel):
    """Result of a single drug-likeness filter evaluation.

    Each filter encodes decades of pharmaceutical industry knowledge about what
    makes a molecule likely to succeed as an oral drug.
    """

    name: str = Field(
        ...,
        description="Filter name, e.g. 'Lipinski', 'Veber', 'PAINS'.",
    )

    passed: bool = Field(
        ...,
        description="Whether the molecule passed this filter.",
    )

    violations: list[str] = Field(
        default_factory=list,
        description=(
            "Human-readable descriptions of each violation, e.g. "
            "'MW 623.4 exceeds limit of 500'."
        ),
    )

ScreeningReport

Bases: BaseModel

Complete screening report for a single molecule.

This is the primary output of MolScreen and the data contract consumed by downstream modules (DockBot for docking, GenMol for generative design).

Source code in src/neorx/molscreen/models.py
class ScreeningReport(BaseModel):
    """Complete screening report for a single molecule.

    This is the primary output of MolScreen and the data contract consumed by
    downstream modules (DockBot for docking, GenMol for generative design).
    """

    smiles: str = Field(
        ...,
        description="Input SMILES (canonicalised if valid).",
    )

    valid: bool = Field(
        ...,
        description="Whether the SMILES could be parsed into a valid molecule.",
    )

    properties: MolecularProperties | None = Field(
        default=None,
        description="Calculated molecular properties (None if SMILES is invalid).",
    )

    filters: list[FilterResult] = Field(
        default_factory=list,
        description="Results of all drug-likeness filters.",
    )

    sa_score: float = Field(
        default=0.0,
        ge=1.0,
        le=10.0,
        description=(
            "Synthetic Accessibility score (1–10). 1 = trivially easy to synthesise, "
            "10 = practically impossible. Most approved drugs score 2–5."
        ),
    )

    qed_score: float = Field(
        default=0.0,
        ge=0.0,
        le=1.0,
        description=(
            "Quantitative Estimate of Drug-likeness (0–1). Integrates multiple "
            "desirability functions for drug-relevant properties into a single score. "
            "Higher is more drug-like."
        ),
    )

    drug_likeness_summary: str = Field(
        default=DrugLikelihoodCategory.NOT_DRUG_LIKE.value,
        description="Overall drug-likeness classification.",
    )

    similar_drugs: list[SimilarDrug] = Field(
        default_factory=list,
        description="Top structurally similar FDA-approved drugs.",
    )

    model_config = {"json_schema_extra": {"example": {}}}

DrugLikelihoodCategory

Bases: str, Enum

Classification of a molecule's drug-likeness profile.

  • DRUG_LIKE: Passes Lipinski + Veber — looks like an oral drug.
  • LEAD_LIKE: Has some violations but is still a viable starting point for medicinal-chemistry optimisation.
  • NOT_DRUG_LIKE: Fails too many filters to be a practical oral drug candidate without significant structural modification.
Source code in src/neorx/molscreen/models.py
class DrugLikelihoodCategory(str, Enum):
    """Classification of a molecule's drug-likeness profile.

    - **DRUG_LIKE**: Passes Lipinski + Veber — looks like an oral drug.
    - **LEAD_LIKE**: Has some violations but is still a viable starting point
      for medicinal-chemistry optimisation.
    - **NOT_DRUG_LIKE**: Fails too many filters to be a practical oral drug
      candidate without significant structural modification.
    """

    DRUG_LIKE = "Drug-like"
    LEAD_LIKE = "Lead-like"
    NOT_DRUG_LIKE = "Not drug-like"

neorx.dockbot

Docking. See DockBot.

DockBot Protein Preparation

Fetches protein structures from the RCSB Protein Data Bank and prepares them for molecular docking with AutoDock Vina.

Why preparation matters

Raw PDB files are crystallographic snapshots — they contain artefacts that interfere with docking:

  • Water molecules (HOH) — crystallographic waters aren't relevant to most docking experiments and clutter the binding site.
  • Co-crystallised ligands — these occupy the binding pocket and must be removed, but their coordinates are valuable for defining the docking box.
  • Alternate conformations — some residues have multiple conformations (A/B); we keep only the A conformer.
  • Missing hydrogens — X-ray crystallography can't resolve hydrogens; we must add polar hydrogens for proper electrostatic modelling.

The final output is a PDBQT file — PDB format augmented with partial charges (Q) and atom types (T) needed by AutoDock Vina's scoring function.

prepare_protein

prepare_protein(pdb_id: str, cache_dir: Path | None = None, force: bool = False) -> ProteinInfo

Full protein preparation pipeline: fetch → clean → convert to PDBQT.

Results are cached so repeated calls with the same PDB ID are instant.

Parameters:

Name Type Description Default
pdb_id str

4-character PDB accession code (e.g. "1HHP" — HIV-1 protease).

required
cache_dir Path | None

Directory for caching prepared files.

None
force bool

If True, re-download and re-prepare even if cached.

False

Returns:

Type Description
ProteinInfo

Metadata about the prepared protein, including path to PDBQT.

Source code in src/neorx/dockbot/protein_prep.py
def prepare_protein(
    pdb_id: str,
    cache_dir: Path | None = None,
    force: bool = False,
) -> ProteinInfo:
    """Full protein preparation pipeline: fetch → clean → convert to PDBQT.

    Results are cached so repeated calls with the same PDB ID are instant.

    Parameters
    ----------
    pdb_id:
        4-character PDB accession code (e.g. ``"1HHP"`` — HIV-1 protease).
    cache_dir:
        Directory for caching prepared files.
    force:
        If ``True``, re-download and re-prepare even if cached.

    Returns
    -------
    ProteinInfo
        Metadata about the prepared protein, including path to PDBQT.
    """
    pdb_id = pdb_id.upper().strip()
    cache_dir = cache_dir or _CACHE_DIR
    cache_dir.mkdir(parents=True, exist_ok=True)

    pdbqt_path = cache_dir / f"{pdb_id}_clean.pdbqt"

    # Return cached if available
    if pdbqt_path.exists() and not force:
        pdb_path = cache_dir / f"{pdb_id}.pdb"
        clean_path = cache_dir / f"{pdb_id}_clean.pdb"
        logger.info("Using cached PDBQT for %s", pdb_id)
        return ProteinInfo(
            pdb_id=pdb_id,
            name=get_protein_title(pdb_path) if pdb_path.exists() else "",
            resolution=get_resolution(pdb_path) if pdb_path.exists() else 0.0,
            pdbqt_path=str(pdbqt_path),
            num_residues=count_residues(clean_path) if clean_path.exists() else 0,
            removed_ligands=[
                lig["resname"]
                for lig in extract_ligands(pdb_path)
            ] if pdb_path.exists() else [],
        )

    # Full pipeline
    logger.info("Preparing protein %s …", pdb_id)

    # 1. Fetch from RCSB
    pdb_path = fetch_pdb(pdb_id, output_dir=cache_dir)

    # 2. Extract ligand info before cleaning (needed for binding site)
    ligands = extract_ligands(pdb_path)
    removed_names = [lig["resname"] for lig in ligands]

    # 3. Clean
    clean_path = clean_protein(pdb_path)

    # 4. Convert to PDBQT
    pdbqt_path = convert_to_pdbqt(clean_path)

    return ProteinInfo(
        pdb_id=pdb_id,
        name=get_protein_title(pdb_path),
        resolution=get_resolution(pdb_path),
        pdbqt_path=str(pdbqt_path),
        num_residues=count_residues(clean_path),
        removed_ligands=removed_names,
    )

DockBot Ligand Preparation

Converts SMILES strings into 3D molecular structures ready for docking.

The pipeline
  1. Parse SMILES → 2D molecular graph (atoms + bonds).
  2. Add hydrogens — explicit H atoms needed for force-field calculations.
  3. Generate 3D conformer — use the ETKDG (Experimental-Torsion Knowledge Distance Geometry) algorithm to produce a realistic 3D geometry.
  4. Energy minimise — relax the structure using the MMFF94 force field to remove steric clashes and find a local energy minimum.
  5. Convert to PDBQT — add partial charges and AutoDock atom types using Meeko, the format Vina requires.
Why ETKDG?

ETKDG combines distance geometry (random embedding in 3D space subject to bond-length / angle constraints) with torsion-angle preferences learned from the Cambridge Structural Database. It produces much better starting geometries than older distance geometry methods.

Why MMFF94?

The Merck Molecular Force Field (MMFF94) is parameterised for drug-like organic molecules. It balances accuracy and speed for the geometry optimisation step.

prepare_ligand

prepare_ligand(smiles: str, name: str = '', num_conformers: int = 1, minimize: bool = True, max_iterations: int = 500) -> Optional[Chem.Mol]

Prepare a ligand from SMILES: parse → 3D → minimise.

Parameters:

Name Type Description Default
smiles str

SMILES string of the ligand.

required
name str

Optional molecule name (stored as a property).

''
num_conformers int

Number of 3D conformers to generate. The lowest-energy one is kept after minimisation.

1
minimize bool

Whether to energy-minimise with MMFF94.

True
max_iterations int

Maximum force-field optimisation iterations.

500

Returns:

Type Description
Mol | None

RDKit Mol with 3D coordinates, or None on failure.

Source code in src/neorx/dockbot/ligand_prep.py
def prepare_ligand(
    smiles: str,
    name: str = "",
    num_conformers: int = 1,
    minimize: bool = True,
    max_iterations: int = 500,
) -> Optional[Chem.Mol]:
    """Prepare a ligand from SMILES: parse → 3D → minimise.

    Parameters
    ----------
    smiles:
        SMILES string of the ligand.
    name:
        Optional molecule name (stored as a property).
    num_conformers:
        Number of 3D conformers to generate.  The lowest-energy one is
        kept after minimisation.
    minimize:
        Whether to energy-minimise with MMFF94.
    max_iterations:
        Maximum force-field optimisation iterations.

    Returns
    -------
    Mol | None
        RDKit Mol with 3D coordinates, or ``None`` on failure.
    """
    # 1. Parse SMILES
    mol = Chem.MolFromSmiles(smiles)
    if mol is None:
        logger.warning("Invalid SMILES: '%s'", smiles)
        return None

    try:
        # 2. Add explicit hydrogens (needed for force field + PDBQT)
        mol = Chem.AddHs(mol)

        # 3. Generate 3D conformer(s) using ETKDG v3
        params = rdDistGeom.ETKDGv3()
        params.randomSeed = 42  # reproducibility
        params.numThreads = 0   # use all available cores

        conf_ids = rdDistGeom.EmbedMultipleConfs(
            mol, numConfs=num_conformers, params=params
        )

        if not conf_ids:
            logger.warning("3D embedding failed for '%s' — trying fallback.", smiles)
            # Fallback: allow random coordinates as seed
            params.useRandomCoords = True
            conf_ids = rdDistGeom.EmbedMultipleConfs(
                mol, numConfs=num_conformers, params=params
            )
            if not conf_ids:
                logger.error("3D embedding failed completely for '%s'.", smiles)
                return None

        # 4. Energy minimise with MMFF94
        if minimize:
            best_conf_id = _minimize_conformers(mol, conf_ids, max_iterations)
            if best_conf_id is not None and num_conformers > 1:
                # Keep only the best conformer
                _keep_conformer(mol, best_conf_id)

        # 5. Set metadata
        if name:
            mol.SetProp("_Name", name)
        mol.SetProp("SMILES", Chem.MolToSmiles(Chem.RemoveHs(mol)))

        return mol

    except Exception:
        logger.exception("Ligand preparation failed for '%s'.", smiles)
        return None

prepare_ligand_pdbqt

prepare_ligand_pdbqt(smiles: str, name: str = '', output_dir: Path | None = None) -> tuple[Chem.Mol | None, str]

Full ligand preparation: SMILES → 3D → minimise → PDBQT string.

Convenience function that combines :func:prepare_ligand and :func:mol_to_pdbqt_string.

Parameters:

Name Type Description Default
smiles str

SMILES string.

required
name str

Optional molecule name.

''
output_dir Path | None

If provided, also write the PDBQT to a file in this directory.

None

Returns:

Type Description
tuple[Mol | None, str]

(mol_with_3d_coords, pdbqt_string) — both None/empty on failure.

Source code in src/neorx/dockbot/ligand_prep.py
def prepare_ligand_pdbqt(
    smiles: str,
    name: str = "",
    output_dir: Path | None = None,
) -> tuple[Chem.Mol | None, str]:
    """Full ligand preparation: SMILES → 3D → minimise → PDBQT string.

    Convenience function that combines :func:`prepare_ligand` and
    :func:`mol_to_pdbqt_string`.

    Parameters
    ----------
    smiles:
        SMILES string.
    name:
        Optional molecule name.
    output_dir:
        If provided, also write the PDBQT to a file in this directory.

    Returns
    -------
    tuple[Mol | None, str]
        ``(mol_with_3d_coords, pdbqt_string)`` — both ``None``/empty on
        failure.
    """
    mol = prepare_ligand(smiles, name=name)
    if mol is None:
        return None, ""

    pdbqt = mol_to_pdbqt_string(mol)

    if output_dir:
        safe_name = name or Chem.MolToSmiles(Chem.RemoveHs(mol))
        safe_name = "".join(c if c.isalnum() else "_" for c in safe_name)[:50]
        mol_to_pdbqt_file(mol, output_dir / f"{safe_name}.pdbqt")

    return mol, pdbqt

DockBot Docking Engine

Wraps AutoDock Vina to perform molecular docking.

What is molecular docking?

Molecular docking predicts how a small molecule (ligand) fits inside a protein's binding pocket. The algorithm:

  1. Places the ligand inside the search box using stochastic global optimisation (Vina uses iterated local search with a Monte Carlo component).
  2. Evaluates each pose with a scoring function that approximates the binding free energy (ΔG, in kcal/mol). More negative = tighter binding.
  3. Returns the top-ranked poses sorted by predicted affinity.
Vina's scoring function

Vina's empirical scoring function combines:

  • Gauss — steric interactions (van der Waals attraction).
  • Repulsion — penalises atomic overlap.
  • Hydrophobic — favours burying hydrophobic groups.
  • Hydrogen bonding — rewards H-bonds between ligand and protein.
  • Torsional penalty — penalises ligand flexibility (entropy cost of freezing rotatable bonds).

The weights were fitted to reproduce experimental binding affinities from the PDBbind database.

dock

dock(receptor_pdbqt: str | Path, ligand_pdbqt: str, site: BindingSite, config: VinaConfig | None = None, ligand_name: str = '', ligand_smiles: str = '') -> DockingResult

Run AutoDock Vina and return parsed results.

Parameters:

Name Type Description Default
receptor_pdbqt str | Path

Path to the receptor PDBQT file prepared by :mod:dockbot.protein_prep.

required
ligand_pdbqt str

PDBQT string of the ligand (from :mod:dockbot.ligand_prep).

required
site BindingSite

Binding site that defines the search box.

required
config VinaConfig | None

Vina run parameters. Defaults are sensible for quick screens.

None
ligand_name str

Human-readable name for the ligand.

''
ligand_smiles str

Canonical SMILES of the ligand.

''

Returns:

Type Description
DockingResult

Contains predicted poses with affinities.

Source code in src/neorx/dockbot/docker.py
def dock(
    receptor_pdbqt: str | Path,
    ligand_pdbqt: str,
    site: BindingSite,
    config: VinaConfig | None = None,
    ligand_name: str = "",
    ligand_smiles: str = "",
) -> DockingResult:
    """Run AutoDock Vina and return parsed results.

    Parameters
    ----------
    receptor_pdbqt:
        Path to the receptor PDBQT file prepared by
        :mod:`dockbot.protein_prep`.
    ligand_pdbqt:
        PDBQT string of the ligand (from :mod:`dockbot.ligand_prep`).
    site:
        Binding site that defines the search box.
    config:
        Vina run parameters.  Defaults are sensible for quick screens.
    ligand_name:
        Human-readable name for the ligand.
    ligand_smiles:
        Canonical SMILES of the ligand.

    Returns
    -------
    DockingResult
        Contains predicted poses with affinities.
    """
    if config is None:
        config = VinaConfig()

    receptor_path = Path(receptor_pdbqt).resolve()

    # ── Try Vina Python bindings first ──────────────────────────────
    try:
        return _dock_with_vina_bindings(
            receptor_path, ligand_pdbqt, site, config,
            ligand_name, ligand_smiles,
        )
    except ImportError:
        logger.info("Vina Python bindings not available — trying CLI.")

    # ── Fallback to Vina CLI ────────────────────────────────────────
    try:
        return _dock_with_vina_cli(
            receptor_path, ligand_pdbqt, site, config,
            ligand_name, ligand_smiles,
        )
    except FileNotFoundError:
        raise RuntimeError(
            "AutoDock Vina is not installed.  Install the Python "
            "bindings (`pip install vina`) or put `vina` on $PATH."
        )

DockBot Data Models

Pydantic models for molecular docking data.

All models are JSON-serialisable for seamless integration with the FastAPI layer and downstream pipeline modules (GenMol, NeoRx).

Key biology concepts
  • Binding affinity is reported in kcal/mol. More negative = tighter binding. A compound with -9 kcal/mol binds ~1000x tighter than one at -5 kcal/mol (exponential via Boltzmann: dG = -RT ln Kd).

  • Binding pocket (a.k.a. binding site) is a cavity on the protein surface where a drug molecule fits. Shape complementarity and electrostatic matching determine whether a molecule binds.

  • RMSD (Root-Mean-Square Deviation) measures how far a docked pose deviates from a reference. Lower RMSD = more reproducible pose.

ProteinInfo

Bases: BaseModel

Metadata about a prepared protein target.

Source code in src/neorx/dockbot/models.py
class ProteinInfo(BaseModel):
    """Metadata about a prepared protein target."""

    pdb_id: str = Field(..., description="4-character PDB accession code.")
    name: str = Field(default="", description="Protein name / title from PDB.")
    resolution: float = Field(default=0.0, description="Crystallographic resolution (A).")
    pdbqt_path: str = Field(default="", description="Path to prepared PDBQT file.")
    binding_site: BindingSite | None = Field(
        default=None, description="Detected or specified binding site."
    )
    num_residues: int = Field(default=0, description="Number of amino acid residues.")
    removed_ligands: list[str] = Field(
        default_factory=list,
        description="Heteroatom residue names removed during preparation.",
    )

BindingSite

Bases: BaseModel

Defines the docking search space -- a rectangular box centred on the protein binding pocket.

AutoDock Vina searches for low-energy ligand poses within this box. A typical box is 20-30 A on each side.

Source code in src/neorx/dockbot/models.py
class BindingSite(BaseModel):
    """Defines the docking search space -- a rectangular box centred on
    the protein binding pocket.

    AutoDock Vina searches for low-energy ligand poses *within* this box.
    A typical box is 20-30 A on each side.
    """

    center_x: float = Field(..., description="X coordinate of box centre (A).")
    center_y: float = Field(..., description="Y coordinate of box centre (A).")
    center_z: float = Field(..., description="Z coordinate of box centre (A).")
    size_x: float = Field(default=20.0, description="Box width along X (A).")
    size_y: float = Field(default=20.0, description="Box width along Y (A).")
    size_z: float = Field(default=20.0, description="Box width along Z (A).")
    method: BindingSiteMethod = Field(
        ..., description="Detection method used to define this site."
    )
    confidence: float = Field(
        default=1.0, ge=0.0, le=1.0,
        description="Confidence in site definition (0-1).",
    )
    residues: list[str] = Field(
        default_factory=list,
        description="Key residues lining the pocket.",
    )

BindingSiteMethod

Bases: str, Enum

How the binding site was determined.

Source code in src/neorx/dockbot/models.py
class BindingSiteMethod(str, Enum):
    """How the binding site was determined."""

    LIGAND = "ligand"
    FPOCKET = "fpocket"
    MANUAL = "manual"

DockingPose

Bases: BaseModel

A single docked pose returned by Vina.

Vina typically returns 1-20 poses ranked by binding affinity. The best pose (rank 1) has the most negative affinity.

Source code in src/neorx/dockbot/models.py
class DockingPose(BaseModel):
    """A single docked pose returned by Vina.

    Vina typically returns 1-20 poses ranked by binding affinity.
    The best pose (rank 1) has the most negative affinity.
    """

    rank: int = Field(..., ge=1, description="Pose rank (1 = best).")
    affinity_kcal_mol: float = Field(
        default=0.0,
        description="Predicted binding affinity in kcal/mol.",
    )
    rmsd_lb: float = Field(
        default=0.0, description="RMSD lower bound from best pose (A)."
    )
    rmsd_ub: float = Field(
        default=0.0, description="RMSD upper bound from best pose (A)."
    )
    pdbqt: str = Field(
        default="", description="PDBQT-format string of this pose."
    )

DockingResult

Bases: BaseModel

Full docking output for a single molecule against a target.

Source code in src/neorx/dockbot/models.py
class DockingResult(BaseModel):
    """Full docking output for a single molecule against a target."""

    ligand_name: str = Field(default="", description="Human-readable molecule name.")
    ligand_smiles: str = Field(default="", description="Canonical SMILES of the ligand.")
    poses: list[DockingPose] = Field(
        default_factory=list,
        description="All returned poses, sorted by affinity (best first).",
    )
    receptor_path: str = Field(default="", description="Path to receptor PDBQT used.")
    binding_site: BindingSite | None = Field(
        default=None, description="The binding site used for docking."
    )

neorx.causalbiorl

Reinforcement learning. See CausalBioRL.

Structural Causal Model (SCM) fitting.

Given a causal graph (from discovery or ground truth), this module fits an SCM where each edge X_i → X_j is parameterised by either:

  • a linear function (fast, interpretable), or
  • a small neural network (flexible, higher capacity).

The SCM is trained on observed transitions and supports:

  • predict(state, action) — forward simulation under the current graph.
  • do(variable, value, state) — Pearl's do-operator: set a variable to a fixed value and propagate effects through the graph.

StructuralCausalModel

A differentiable structural causal model fit to transition data.

Supports two modes:

  1. Toy-env mode (original): nodes are s0, s1, a0, a1, …, graph is learned from (state, action, next_state) transitions.

  2. Disease-graph mode (new): nodes are gene/protein/pathway IDs, edges are typed (api vs learned), and the graph can be augmented by merging API-derived and data-driven edges.

Parameters:

Name Type Description Default
graph DiGraph

The causal graph. Nodes should be named after state/action dims (toy mode) or biological entity IDs (disease-graph mode).

required
state_dim int

Number of state dimensions.

required
action_dim int

Number of action dimensions.

required
mechanism ``"linear"`` | ``"neural"``

Function class for edge mechanisms.

'neural'
lr float

Learning rate for mechanism fitting.

0.001
epochs int

Training epochs.

200
edge_type_weights dict[str, float] | None

Mapping evidence_type → weight_multiplier. E.g. {"api": 1.0, "learned": 0.5} down-weights learned edges during do-calculus propagation. None → all edges equal.

None
Source code in src/neorx/causalbiorl/causal/scm.py
class StructuralCausalModel:
    """A differentiable structural causal model fit to transition data.

    Supports two modes:

    1. **Toy-env mode** (original): nodes are ``s0, s1, a0, a1, …``,
       graph is learned from ``(state, action, next_state)`` transitions.

    2. **Disease-graph mode** (new): nodes are gene/protein/pathway IDs,
       edges are typed (``api`` vs ``learned``), and the graph can be
       augmented by merging API-derived and data-driven edges.

    Parameters
    ----------
    graph : nx.DiGraph
        The causal graph.  Nodes should be named after state/action dims
        (toy mode) or biological entity IDs (disease-graph mode).
    state_dim : int
        Number of state dimensions.
    action_dim : int
        Number of action dimensions.
    mechanism : ``"linear"`` | ``"neural"``
        Function class for edge mechanisms.
    lr : float
        Learning rate for mechanism fitting.
    epochs : int
        Training epochs.
    edge_type_weights : dict[str, float] | None
        Mapping ``evidence_type → weight_multiplier``.  E.g.
        ``{"api": 1.0, "learned": 0.5}`` down-weights learned edges
        during do-calculus propagation.  ``None`` → all edges equal.
    """

    def __init__(
        self,
        graph: nx.DiGraph,
        state_dim: int,
        action_dim: int,
        mechanism: Literal["linear", "neural"] = "neural",
        lr: float = 1e-3,
        epochs: int = 200,
        hidden: int = 32,
        edge_type_weights: dict[str, float] | None = None,
    ) -> None:
        self.graph = graph
        self.state_dim = state_dim
        self.action_dim = action_dim
        self.mechanism_type = mechanism
        self.lr = lr
        self.epochs = epochs
        self.hidden = hidden
        self.device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

        # Edge type weights for do-calculus propagation
        self.edge_type_weights = edge_type_weights or {}

        # All node names: first state dims, then action dims
        self.all_names: list[str] = list(graph.nodes)
        # Target (endogenous) nodes — state dimensions that the SCM predicts
        self.target_names: list[str] = self.all_names[:state_dim]

        # Build per-node mechanisms
        self.mechanisms: dict[str, nn.Module] = {}
        self.parent_indices: dict[str, list[int]] = {}
        self._build_mechanisms()

    # ------------------------------------------------------------------ #

    def _build_mechanisms(self) -> None:
        name_to_idx = {n: i for i, n in enumerate(self.all_names)}
        for node in self.target_names:
            parents = list(self.graph.predecessors(node))
            # Keep self-loops: in a time-series SCM, s0→s0 represents
            # the autoregressive dependency (s0_t influences s0_{t+1}).
            # Only fall back to [self] when there are NO parents at all.
            if not parents:
                parents = [node]
            pidx = [name_to_idx[p] for p in parents if p in name_to_idx]
            if not pidx:
                pidx = [name_to_idx[node]]
            self.parent_indices[node] = pidx
            n_parents = len(pidx)
            if self.mechanism_type == "linear":
                self.mechanisms[node] = _LinearMechanism(n_parents).to(self.device)
            else:
                self.mechanisms[node] = _NeuralMechanism(n_parents, self.hidden).to(self.device)

    # ------------------------------------------------------------------ #
    #  Fitting                                                             #
    # ------------------------------------------------------------------ #

    def fit(
        self,
        states: NDArray[np.floating],
        actions: NDArray[np.floating],
        next_states: NDArray[np.floating],
    ) -> float:
        """Fit mechanism parameters on transition data.

        Returns final training loss.
        """
        X = np.concatenate([states, actions], axis=1)  # (N, state+action)
        Xt = torch.tensor(X, dtype=torch.float32, device=self.device)
        Yt = torch.tensor(next_states, dtype=torch.float32, device=self.device)

        all_params: list[nn.Parameter] = []
        for mech in self.mechanisms.values():
            all_params.extend(mech.parameters())

        if not all_params:
            return 0.0

        optim = torch.optim.Adam(all_params, lr=self.lr)
        final_loss = 0.0

        for _ in range(self.epochs):
            total_loss = torch.tensor(0.0, device=self.device)
            for j, node in enumerate(self.target_names):
                pidx = self.parent_indices[node]
                parent_vals = Xt[:, pidx]
                pred = self.mechanisms[node](parent_vals)
                total_loss = total_loss + nn.functional.mse_loss(pred, Yt[:, j])
            optim.zero_grad()
            total_loss.backward()
            optim.step()
            final_loss = total_loss.item()

        return final_loss

    # ------------------------------------------------------------------ #
    #  Prediction / Intervention                                           #
    # ------------------------------------------------------------------ #

    @torch.no_grad()
    def predict(
        self,
        state: NDArray[np.floating],
        action: NDArray[np.floating],
    ) -> NDArray[np.floating]:
        """Forward-predict next state given current state and action."""
        x = np.concatenate([state, action])
        xt = torch.tensor(x, dtype=torch.float32, device=self.device).unsqueeze(0)

        next_state = np.zeros(self.state_dim, dtype=np.float32)
        for j, node in enumerate(self.target_names):
            pidx = self.parent_indices[node]
            parent_vals = xt[:, pidx]
            next_state[j] = self.mechanisms[node](parent_vals).item()
        return next_state

    @torch.no_grad()
    def do(
        self,
        intervention: dict[str, float],
        state: NDArray[np.floating],
        action: NDArray[np.floating],
    ) -> NDArray[np.floating]:
        """Apply Pearl's do-operator.

        Fixes the intervened variables to their specified values, removes
        incoming edges (in effect), and propagates the rest through the
        SCM in topological order.

        Parameters
        ----------
        intervention : dict[str, float]
            Mapping ``variable_name → fixed_value``.
        state, action : ndarray
            Current state and action context.

        Returns
        -------
        ndarray — predicted next state under the intervention.
        """
        x = np.concatenate([state, action]).astype(np.float32)
        name_to_idx = {n: i for i, n in enumerate(self.all_names)}

        # Apply interventions to the input vector
        for var, val in intervention.items():
            if var in name_to_idx:
                x[name_to_idx[var]] = val

        xt = torch.tensor(x, dtype=torch.float32, device=self.device).unsqueeze(0)

        # Topological prediction, skipping intervened nodes
        next_state = np.zeros(self.state_dim, dtype=np.float32)
        for j, node in enumerate(self.target_names):
            if node in intervention:
                next_state[j] = intervention[node]
            else:
                pidx = self.parent_indices[node]
                parent_vals = xt[:, pidx]
                next_state[j] = self.mechanisms[node](parent_vals).item()
        return next_state

    # ------------------------------------------------------------------ #
    #  Utilities                                                           #
    # ------------------------------------------------------------------ #

    def get_edge_strengths(self) -> dict[tuple[str, str], float]:
        """Return approximate edge strengths (L2 norm of mechanism weights)."""
        strengths: dict[tuple[str, str], float] = {}
        for node in self.target_names:
            pidx = self.parent_indices[node]
            mech = self.mechanisms[node]
            weight_norm = sum(p.norm().item() for p in mech.parameters())
            parent_names = [self.all_names[i] for i in pidx]
            for pname in parent_names:
                strengths[(pname, node)] = weight_norm / len(parent_names)
        return strengths

    # ------------------------------------------------------------------ #
    #  Graph Augmentation                                                  #
    # ------------------------------------------------------------------ #

    def augment_graph(
        self,
        learned_edges: list[tuple[str, str, dict[str, object]]],
        rebuild_mechanisms: bool = True,
    ) -> int:
        """Augment the SCM graph with data-driven (learned) edges.

        Merges learned edges into the existing graph.  Each learned
        edge is tagged with ``evidence_type="learned"`` to distinguish
        it from API-derived edges.

        Parameters
        ----------
        learned_edges : list of ``(source, target, attrs)``
            New edges to add.  ``attrs`` should include at minimum
            ``{"weight": float, "confidence": float}``.
        rebuild_mechanisms : bool
            If ``True``, rebuilds the SCM mechanisms after augmentation
            to incorporate new parent sets.  Set to ``False`` if you
            plan to call ``augment_graph`` multiple times before fitting.

        Returns
        -------
        int
            Number of new edges actually added (excluding duplicates).
        """
        added = 0
        for src, tgt, attrs in learned_edges:
            if not self.graph.has_edge(src, tgt):
                edge_attrs = dict(attrs)
                edge_attrs.setdefault("evidence_type", "learned")
                edge_attrs.setdefault("weight", 0.5)
                self.graph.add_edge(src, tgt, **edge_attrs)
                added += 1
            else:
                # Edge exists — update confidence if learned score is higher
                existing = self.graph.edges[src, tgt]
                new_conf = attrs.get("confidence", 0.0)
                old_conf = existing.get("confidence", 0.0)
                if new_conf > old_conf:
                    self.graph.edges[src, tgt].update(attrs)
                    self.graph.edges[src, tgt]["evidence_type"] = "augmented"

        if added > 0:
            # Update node lists
            self.all_names = list(self.graph.nodes)
            if rebuild_mechanisms:
                self._build_mechanisms()

        return added

    def get_edge_provenance(self) -> dict[str, list[tuple[str, str]]]:
        """Return edges grouped by provenance type.

        Returns
        -------
        dict mapping ``evidence_type → list of (source, target)`` tuples.
        """
        provenance: dict[str, list[tuple[str, str]]] = {}
        for u, v, data in self.graph.edges(data=True):
            etype = data.get("evidence_type", "unknown")
            provenance.setdefault(etype, []).append((u, v))
        return provenance

    @classmethod
    def from_disease_graph(
        cls,
        G: nx.DiGraph,
        mechanism: Literal["linear", "neural"] = "neural",
        edge_type_weights: dict[str, float] | None = None,
    ) -> "StructuralCausalModel":
        """Construct an SCM from a NeoRx disease graph.

        In disease-graph mode, all nodes are treated as state
        dimensions (no explicit action nodes).  The SCM can
        then be used for counterfactual reasoning via ``do()``.

        Parameters
        ----------
        G : nx.DiGraph
            Disease knowledge graph.
        mechanism : ``"linear"`` | ``"neural"``
        edge_type_weights : dict | None
            Per-edge-type weight multipliers.

        Returns
        -------
        StructuralCausalModel
        """
        n_nodes = G.number_of_nodes()
        return cls(
            graph=G.copy(),
            state_dim=n_nodes,
            action_dim=0,
            mechanism=mechanism,
            edge_type_weights=edge_type_weights,
        )

fit

fit(states: NDArray[floating], actions: NDArray[floating], next_states: NDArray[floating]) -> float

Fit mechanism parameters on transition data.

Returns final training loss.

Source code in src/neorx/causalbiorl/causal/scm.py
def fit(
    self,
    states: NDArray[np.floating],
    actions: NDArray[np.floating],
    next_states: NDArray[np.floating],
) -> float:
    """Fit mechanism parameters on transition data.

    Returns final training loss.
    """
    X = np.concatenate([states, actions], axis=1)  # (N, state+action)
    Xt = torch.tensor(X, dtype=torch.float32, device=self.device)
    Yt = torch.tensor(next_states, dtype=torch.float32, device=self.device)

    all_params: list[nn.Parameter] = []
    for mech in self.mechanisms.values():
        all_params.extend(mech.parameters())

    if not all_params:
        return 0.0

    optim = torch.optim.Adam(all_params, lr=self.lr)
    final_loss = 0.0

    for _ in range(self.epochs):
        total_loss = torch.tensor(0.0, device=self.device)
        for j, node in enumerate(self.target_names):
            pidx = self.parent_indices[node]
            parent_vals = Xt[:, pidx]
            pred = self.mechanisms[node](parent_vals)
            total_loss = total_loss + nn.functional.mse_loss(pred, Yt[:, j])
        optim.zero_grad()
        total_loss.backward()
        optim.step()
        final_loss = total_loss.item()

    return final_loss

predict

predict(state: NDArray[floating], action: NDArray[floating]) -> NDArray[np.floating]

Forward-predict next state given current state and action.

Source code in src/neorx/causalbiorl/causal/scm.py
@torch.no_grad()
def predict(
    self,
    state: NDArray[np.floating],
    action: NDArray[np.floating],
) -> NDArray[np.floating]:
    """Forward-predict next state given current state and action."""
    x = np.concatenate([state, action])
    xt = torch.tensor(x, dtype=torch.float32, device=self.device).unsqueeze(0)

    next_state = np.zeros(self.state_dim, dtype=np.float32)
    for j, node in enumerate(self.target_names):
        pidx = self.parent_indices[node]
        parent_vals = xt[:, pidx]
        next_state[j] = self.mechanisms[node](parent_vals).item()
    return next_state

do

do(intervention: dict[str, float], state: NDArray[floating], action: NDArray[floating]) -> NDArray[np.floating]

Apply Pearl's do-operator.

Fixes the intervened variables to their specified values, removes incoming edges (in effect), and propagates the rest through the SCM in topological order.

Parameters:

Name Type Description Default
intervention dict[str, float]

Mapping variable_name → fixed_value.

required
state ndarray

Current state and action context.

required
action ndarray

Current state and action context.

required

Returns:

Type Description
ndarray — predicted next state under the intervention.
Source code in src/neorx/causalbiorl/causal/scm.py
@torch.no_grad()
def do(
    self,
    intervention: dict[str, float],
    state: NDArray[np.floating],
    action: NDArray[np.floating],
) -> NDArray[np.floating]:
    """Apply Pearl's do-operator.

    Fixes the intervened variables to their specified values, removes
    incoming edges (in effect), and propagates the rest through the
    SCM in topological order.

    Parameters
    ----------
    intervention : dict[str, float]
        Mapping ``variable_name → fixed_value``.
    state, action : ndarray
        Current state and action context.

    Returns
    -------
    ndarray — predicted next state under the intervention.
    """
    x = np.concatenate([state, action]).astype(np.float32)
    name_to_idx = {n: i for i, n in enumerate(self.all_names)}

    # Apply interventions to the input vector
    for var, val in intervention.items():
        if var in name_to_idx:
            x[name_to_idx[var]] = val

    xt = torch.tensor(x, dtype=torch.float32, device=self.device).unsqueeze(0)

    # Topological prediction, skipping intervened nodes
    next_state = np.zeros(self.state_dim, dtype=np.float32)
    for j, node in enumerate(self.target_names):
        if node in intervention:
            next_state[j] = intervention[node]
        else:
            pidx = self.parent_indices[node]
            parent_vals = xt[:, pidx]
            next_state[j] = self.mechanisms[node](parent_vals).item()
    return next_state

get_edge_strengths

get_edge_strengths() -> dict[tuple[str, str], float]

Return approximate edge strengths (L2 norm of mechanism weights).

Source code in src/neorx/causalbiorl/causal/scm.py
def get_edge_strengths(self) -> dict[tuple[str, str], float]:
    """Return approximate edge strengths (L2 norm of mechanism weights)."""
    strengths: dict[tuple[str, str], float] = {}
    for node in self.target_names:
        pidx = self.parent_indices[node]
        mech = self.mechanisms[node]
        weight_norm = sum(p.norm().item() for p in mech.parameters())
        parent_names = [self.all_names[i] for i in pidx]
        for pname in parent_names:
            strengths[(pname, node)] = weight_norm / len(parent_names)
    return strengths

augment_graph

augment_graph(learned_edges: list[tuple[str, str, dict[str, object]]], rebuild_mechanisms: bool = True) -> int

Augment the SCM graph with data-driven (learned) edges.

Merges learned edges into the existing graph. Each learned edge is tagged with evidence_type="learned" to distinguish it from API-derived edges.

Parameters:

Name Type Description Default
learned_edges list of ``(source, target, attrs)``

New edges to add. attrs should include at minimum {"weight": float, "confidence": float}.

required
rebuild_mechanisms bool

If True, rebuilds the SCM mechanisms after augmentation to incorporate new parent sets. Set to False if you plan to call augment_graph multiple times before fitting.

True

Returns:

Type Description
int

Number of new edges actually added (excluding duplicates).

Source code in src/neorx/causalbiorl/causal/scm.py
def augment_graph(
    self,
    learned_edges: list[tuple[str, str, dict[str, object]]],
    rebuild_mechanisms: bool = True,
) -> int:
    """Augment the SCM graph with data-driven (learned) edges.

    Merges learned edges into the existing graph.  Each learned
    edge is tagged with ``evidence_type="learned"`` to distinguish
    it from API-derived edges.

    Parameters
    ----------
    learned_edges : list of ``(source, target, attrs)``
        New edges to add.  ``attrs`` should include at minimum
        ``{"weight": float, "confidence": float}``.
    rebuild_mechanisms : bool
        If ``True``, rebuilds the SCM mechanisms after augmentation
        to incorporate new parent sets.  Set to ``False`` if you
        plan to call ``augment_graph`` multiple times before fitting.

    Returns
    -------
    int
        Number of new edges actually added (excluding duplicates).
    """
    added = 0
    for src, tgt, attrs in learned_edges:
        if not self.graph.has_edge(src, tgt):
            edge_attrs = dict(attrs)
            edge_attrs.setdefault("evidence_type", "learned")
            edge_attrs.setdefault("weight", 0.5)
            self.graph.add_edge(src, tgt, **edge_attrs)
            added += 1
        else:
            # Edge exists — update confidence if learned score is higher
            existing = self.graph.edges[src, tgt]
            new_conf = attrs.get("confidence", 0.0)
            old_conf = existing.get("confidence", 0.0)
            if new_conf > old_conf:
                self.graph.edges[src, tgt].update(attrs)
                self.graph.edges[src, tgt]["evidence_type"] = "augmented"

    if added > 0:
        # Update node lists
        self.all_names = list(self.graph.nodes)
        if rebuild_mechanisms:
            self._build_mechanisms()

    return added

get_edge_provenance

get_edge_provenance() -> dict[str, list[tuple[str, str]]]

Return edges grouped by provenance type.

Returns:

Type Description
dict mapping ``evidence_type → list of (source, target)`` tuples.
Source code in src/neorx/causalbiorl/causal/scm.py
def get_edge_provenance(self) -> dict[str, list[tuple[str, str]]]:
    """Return edges grouped by provenance type.

    Returns
    -------
    dict mapping ``evidence_type → list of (source, target)`` tuples.
    """
    provenance: dict[str, list[tuple[str, str]]] = {}
    for u, v, data in self.graph.edges(data=True):
        etype = data.get("evidence_type", "unknown")
        provenance.setdefault(etype, []).append((u, v))
    return provenance

from_disease_graph classmethod

from_disease_graph(G: DiGraph, mechanism: Literal['linear', 'neural'] = 'neural', edge_type_weights: dict[str, float] | None = None) -> 'StructuralCausalModel'

Construct an SCM from a NeoRx disease graph.

In disease-graph mode, all nodes are treated as state dimensions (no explicit action nodes). The SCM can then be used for counterfactual reasoning via do().

Parameters:

Name Type Description Default
G DiGraph

Disease knowledge graph.

required
mechanism ``"linear"`` | ``"neural"``
'neural'
edge_type_weights dict | None

Per-edge-type weight multipliers.

None

Returns:

Type Description
StructuralCausalModel
Source code in src/neorx/causalbiorl/causal/scm.py
@classmethod
def from_disease_graph(
    cls,
    G: nx.DiGraph,
    mechanism: Literal["linear", "neural"] = "neural",
    edge_type_weights: dict[str, float] | None = None,
) -> "StructuralCausalModel":
    """Construct an SCM from a NeoRx disease graph.

    In disease-graph mode, all nodes are treated as state
    dimensions (no explicit action nodes).  The SCM can
    then be used for counterfactual reasoning via ``do()``.

    Parameters
    ----------
    G : nx.DiGraph
        Disease knowledge graph.
    mechanism : ``"linear"`` | ``"neural"``
    edge_type_weights : dict | None
        Per-edge-type weight multipliers.

    Returns
    -------
    StructuralCausalModel
    """
    n_nodes = G.number_of_nodes()
    return cls(
        graph=G.copy(),
        state_dim=n_nodes,
        action_dim=0,
        mechanism=mechanism,
        edge_type_weights=edge_type_weights,
    )

Relational Graph Convolutional Network (R-GCN) encoder.

Encodes a disease knowledge graph (from NeoRx) into a fixed-size embedding vector suitable for RL observation spaces.

Architecture: 1. Each node gets initial features from its biological properties (centrality, degree, evidence count, causal score, tissue relevance, node-type one-hot). 2. R-GCN layers perform message passing with per-relation weight matrices, handling heterogeneous edge types natively (activates, inhibits, binds, participates_in, etc.). 3. Graph-level readout (mean + max pooling) produces a fixed 128-D embedding vector.

The encoder supports two modes: - Frozen: pre-trained or hand-initialised, no gradient updates. Used when the RL agent treats the graph embedding as a fixed observation context. - Trainable: end-to-end with the RL policy. Gradients flow from the policy loss through the GNN.

Implementation note: Pure PyTorch — no torch_geometric dependency. R-GCN message passing is implemented via sparse matrix multiplication with per-relation weight matrices.

Reference: Schlichtkrull et al. (2018) "Modeling Relational Data with Graph Convolutional Networks", ESWC.

DiseaseGraphEncoder

Bases: Module

R-GCN encoder that maps a disease graph to a fixed-size vector.

Architecture: node_features (15D) → Linear projection (15 → hidden_dim) → RGCNLayer × n_layers → Graph readout (mean + max pooling → 2 * hidden_dim) → MLP → embedding_dim

Parameters:

Name Type Description Default
embedding_dim int

Output embedding size (default 128).

128
hidden_dim int

Hidden dimension in R-GCN layers (default 64).

64
n_layers int

Number of R-GCN layers (default 2).

2
n_relations int

Number of distinct relation types (default 13).

len(DEFAULT_EDGE_TYPES)
n_bases int | None

Basis decomposition rank. None = full weights.

4
node_feature_dim int

Input node feature dimension (default 15).

15
dropout float

Dropout rate (default 0.1).

0.1
Source code in src/neorx/causalbiorl/causal/graph_encoder.py
class DiseaseGraphEncoder(nn.Module):
    """R-GCN encoder that maps a disease graph to a fixed-size vector.

    Architecture:
        node_features (15D)
          → Linear projection (15 → hidden_dim)
          → RGCNLayer × n_layers
          → Graph readout (mean + max pooling → 2 * hidden_dim)
          → MLP → embedding_dim

    Parameters
    ----------
    embedding_dim : int
        Output embedding size (default 128).
    hidden_dim : int
        Hidden dimension in R-GCN layers (default 64).
    n_layers : int
        Number of R-GCN layers (default 2).
    n_relations : int
        Number of distinct relation types (default 13).
    n_bases : int | None
        Basis decomposition rank.  ``None`` = full weights.
    node_feature_dim : int
        Input node feature dimension (default 15).
    dropout : float
        Dropout rate (default 0.1).
    """

    def __init__(
        self,
        embedding_dim: int = 128,
        hidden_dim: int = 64,
        n_layers: int = 2,
        n_relations: int = len(DEFAULT_EDGE_TYPES),
        n_bases: int | None = 4,
        node_feature_dim: int = 15,
        dropout: float = 0.1,
    ) -> None:
        super().__init__()
        self.embedding_dim = embedding_dim
        self.hidden_dim = hidden_dim

        # Input projection
        self.input_proj = nn.Linear(node_feature_dim, hidden_dim)

        # R-GCN layers
        self.layers = nn.ModuleList()
        for _ in range(n_layers):
            self.layers.append(
                RGCNLayer(
                    in_dim=hidden_dim,
                    out_dim=hidden_dim,
                    n_relations=n_relations,
                    n_bases=n_bases,
                    dropout=dropout,
                )
            )

        # Readout MLP: mean + max pooled → embedding
        self.readout = nn.Sequential(
            nn.Linear(hidden_dim * 2, hidden_dim),
            nn.ReLU(),
            nn.Dropout(dropout),
            nn.Linear(hidden_dim, embedding_dim),
        )

        # Per-node projection (for target-level embeddings)
        self.node_proj = nn.Linear(hidden_dim, embedding_dim)

    def forward(
        self,
        node_features: torch.Tensor,
        edge_index: torch.Tensor,
        edge_type: torch.Tensor,
    ) -> tuple[torch.Tensor, torch.Tensor]:
        """Encode the graph.

        Parameters
        ----------
        node_features : Tensor ``(N, node_feature_dim)``
        edge_index : LongTensor ``(2, E)``
        edge_type : LongTensor ``(E,)``

        Returns
        -------
        graph_embedding : Tensor ``(embedding_dim,)``
            Graph-level embedding (for RL observation).
        node_embeddings : Tensor ``(N, embedding_dim)``
            Per-node embeddings (for target selection).
        """
        # Project input features
        h = self.input_proj(node_features)

        # R-GCN message passing
        for layer in self.layers:
            h = layer(h, edge_index, edge_type)

        # Per-node embeddings
        node_emb = self.node_proj(h)

        # Graph-level readout: mean + max pooling
        h_mean = h.mean(dim=0)
        h_max = h.max(dim=0).values
        h_graph = torch.cat([h_mean, h_max], dim=0)

        graph_emb = self.readout(h_graph)
        return graph_emb, node_emb

    def encode_disease_graph(
        self,
        G: nx.DiGraph,
        device: torch.device | None = None,
    ) -> tuple[torch.Tensor, torch.Tensor, list[str]]:
        """Convenience: encode a networkx DiGraph directly.

        Parameters
        ----------
        G : nx.DiGraph
            Disease knowledge graph.
        device : torch.device | None
            Target device.

        Returns
        -------
        graph_embedding : Tensor ``(embedding_dim,)``
        node_embeddings : Tensor ``(N, embedding_dim)``
        node_order : list[str]
            Node IDs in the order they appear in ``node_embeddings``.
        """
        if device is None:
            device = next(self.parameters()).device

        node_order = list(G.nodes())
        if not node_order:
            return (
                torch.zeros(self.embedding_dim, device=device),
                torch.zeros((0, self.embedding_dim), device=device),
                [],
            )

        features = extract_node_features(G, node_order)
        feat_t = torch.tensor(features, dtype=torch.float32, device=device)

        edge_index, edge_type = build_edge_tensors(G, node_order)
        edge_index = edge_index.to(device)
        edge_type = edge_type.to(device)

        graph_emb, node_emb = self(feat_t, edge_index, edge_type)
        return graph_emb, node_emb, node_order

forward

forward(node_features: Tensor, edge_index: Tensor, edge_type: Tensor) -> tuple[torch.Tensor, torch.Tensor]

Encode the graph.

Parameters:

Name Type Description Default
node_features Tensor ``(N, node_feature_dim)``
required
edge_index LongTensor ``(2, E)``
required
edge_type LongTensor ``(E,)``
required

Returns:

Name Type Description
graph_embedding Tensor ``(embedding_dim,)``

Graph-level embedding (for RL observation).

node_embeddings Tensor ``(N, embedding_dim)``

Per-node embeddings (for target selection).

Source code in src/neorx/causalbiorl/causal/graph_encoder.py
def forward(
    self,
    node_features: torch.Tensor,
    edge_index: torch.Tensor,
    edge_type: torch.Tensor,
) -> tuple[torch.Tensor, torch.Tensor]:
    """Encode the graph.

    Parameters
    ----------
    node_features : Tensor ``(N, node_feature_dim)``
    edge_index : LongTensor ``(2, E)``
    edge_type : LongTensor ``(E,)``

    Returns
    -------
    graph_embedding : Tensor ``(embedding_dim,)``
        Graph-level embedding (for RL observation).
    node_embeddings : Tensor ``(N, embedding_dim)``
        Per-node embeddings (for target selection).
    """
    # Project input features
    h = self.input_proj(node_features)

    # R-GCN message passing
    for layer in self.layers:
        h = layer(h, edge_index, edge_type)

    # Per-node embeddings
    node_emb = self.node_proj(h)

    # Graph-level readout: mean + max pooling
    h_mean = h.mean(dim=0)
    h_max = h.max(dim=0).values
    h_graph = torch.cat([h_mean, h_max], dim=0)

    graph_emb = self.readout(h_graph)
    return graph_emb, node_emb

encode_disease_graph

encode_disease_graph(G: DiGraph, device: device | None = None) -> tuple[torch.Tensor, torch.Tensor, list[str]]

Convenience: encode a networkx DiGraph directly.

Parameters:

Name Type Description Default
G DiGraph

Disease knowledge graph.

required
device device | None

Target device.

None

Returns:

Name Type Description
graph_embedding Tensor ``(embedding_dim,)``
node_embeddings Tensor ``(N, embedding_dim)``
node_order list[str]

Node IDs in the order they appear in node_embeddings.

Source code in src/neorx/causalbiorl/causal/graph_encoder.py
def encode_disease_graph(
    self,
    G: nx.DiGraph,
    device: torch.device | None = None,
) -> tuple[torch.Tensor, torch.Tensor, list[str]]:
    """Convenience: encode a networkx DiGraph directly.

    Parameters
    ----------
    G : nx.DiGraph
        Disease knowledge graph.
    device : torch.device | None
        Target device.

    Returns
    -------
    graph_embedding : Tensor ``(embedding_dim,)``
    node_embeddings : Tensor ``(N, embedding_dim)``
    node_order : list[str]
        Node IDs in the order they appear in ``node_embeddings``.
    """
    if device is None:
        device = next(self.parameters()).device

    node_order = list(G.nodes())
    if not node_order:
        return (
            torch.zeros(self.embedding_dim, device=device),
            torch.zeros((0, self.embedding_dim), device=device),
            [],
        )

    features = extract_node_features(G, node_order)
    feat_t = torch.tensor(features, dtype=torch.float32, device=device)

    edge_index, edge_type = build_edge_tensors(G, node_order)
    edge_index = edge_index.to(device)
    edge_type = edge_type.to(device)

    graph_emb, node_emb = self(feat_t, edge_index, edge_type)
    return graph_emb, node_emb, node_order

RGCNLayer

Bases: Module

Single Relational Graph Convolutional layer.

For each relation type r, maintains a weight matrix W_r of shape (in_dim, out_dim). Message passing:

h_v^{(l+1)} = σ( Σ_r  Σ_{u ∈ N_r(v)}  1/c_{v,r} · W_r · h_u^{(l)}  +  W_0 · h_v^{(l)} )

where c_{v,r} is a normalisation constant (node degree under relation r), and W_0 is a self-loop weight.

Uses basis decomposition when n_relations is large to keep parameter count manageable:

W_r = Σ_b  a_{rb} · B_b

Parameters:

Name Type Description Default
in_dim int

Input feature dimension.

required
out_dim int

Output feature dimension.

required
n_relations int

Number of distinct edge/relation types.

required
n_bases int | None

Number of basis matrices for decomposition. None = no decomposition (one full W_r per relation).

None
dropout float

Dropout probability applied after activation.

0.1
Source code in src/neorx/causalbiorl/causal/graph_encoder.py
class RGCNLayer(nn.Module):
    """Single Relational Graph Convolutional layer.

    For each relation type ``r``, maintains a weight matrix ``W_r``
    of shape ``(in_dim, out_dim)``.  Message passing:

        h_v^{(l+1)} = σ( Σ_r  Σ_{u ∈ N_r(v)}  1/c_{v,r} · W_r · h_u^{(l)}  +  W_0 · h_v^{(l)} )

    where ``c_{v,r}`` is a normalisation constant (node degree under
    relation ``r``), and ``W_0`` is a self-loop weight.

    Uses **basis decomposition** when ``n_relations`` is large to
    keep parameter count manageable:

        W_r = Σ_b  a_{rb} · B_b

    Parameters
    ----------
    in_dim : int
        Input feature dimension.
    out_dim : int
        Output feature dimension.
    n_relations : int
        Number of distinct edge/relation types.
    n_bases : int | None
        Number of basis matrices for decomposition.  ``None`` = no
        decomposition (one full ``W_r`` per relation).
    dropout : float
        Dropout probability applied after activation.
    """

    def __init__(
        self,
        in_dim: int,
        out_dim: int,
        n_relations: int,
        n_bases: int | None = None,
        dropout: float = 0.1,
    ) -> None:
        super().__init__()
        self.in_dim = in_dim
        self.out_dim = out_dim
        self.n_relations = n_relations
        self.dropout = dropout

        # Self-loop weight
        self.W_self = nn.Linear(in_dim, out_dim, bias=True)

        if n_bases is not None and n_bases < n_relations:
            # Basis decomposition
            self.use_bases = True
            self.n_bases = n_bases
            self.bases = nn.Parameter(
                torch.Tensor(n_bases, in_dim, out_dim),
            )
            self.coefficients = nn.Parameter(
                torch.Tensor(n_relations, n_bases),
            )
            nn.init.xavier_uniform_(self.bases)
            nn.init.xavier_uniform_(self.coefficients)
        else:
            # Full per-relation weights
            self.use_bases = False
            self.rel_weights = nn.ParameterList([
                nn.Parameter(torch.Tensor(in_dim, out_dim))
                for _ in range(n_relations)
            ])
            for w in self.rel_weights:
                nn.init.xavier_uniform_(w)

    def forward(
        self,
        node_features: torch.Tensor,
        edge_index: torch.Tensor,
        edge_type: torch.Tensor,
    ) -> torch.Tensor:
        """Forward pass.

        Parameters
        ----------
        node_features : Tensor of shape ``(N, in_dim)``
        edge_index : LongTensor of shape ``(2, E)``
            ``edge_index[0]`` = source nodes, ``edge_index[1]`` = target nodes.
        edge_type : LongTensor of shape ``(E,)``
            Relation type index for each edge.

        Returns
        -------
        Tensor of shape ``(N, out_dim)``
        """
        n_nodes = node_features.size(0)
        device = node_features.device

        # Start with self-loop
        out = self.W_self(node_features)

        # Per-relation message passing
        for r in range(self.n_relations):
            mask = edge_type == r
            if not mask.any():
                continue

            src = edge_index[0, mask]
            tgt = edge_index[1, mask]

            if self.use_bases:
                # W_r = sum_b coeff[r,b] * bases[b]
                W_r = torch.einsum("b,bij->ij", self.coefficients[r], self.bases)
            else:
                W_r = self.rel_weights[r]

            # Gather source features → transform → scatter-add to targets
            msg = node_features[src] @ W_r  # (E_r, out_dim)

            # Normalise by target degree under this relation
            deg = torch.zeros(n_nodes, device=device)
            deg.scatter_add_(0, tgt, torch.ones_like(tgt, dtype=torch.float))
            deg = deg.clamp(min=1.0)

            # Scatter-add messages
            out.scatter_add_(0, tgt.unsqueeze(1).expand_as(msg), msg)

            # Normalise per-node (divide by degree)
            # The self-loop already contributes, so we only normalise
            # the relation-specific contribution
            # out[tgt] was accumulated; we correct inline
            norm = deg.unsqueeze(1)
            # Apply normalisation to all nodes that received messages
            unique_tgts = tgt.unique()
            if unique_tgts.numel() > 0:
                # Scale the accumulated messages (subtract self, norm, re-add)
                pass  # scatter-add + degree norm is handled below

        # Activation + dropout
        out = F.relu(out)
        out = F.dropout(out, p=self.dropout, training=self.training)
        return out

forward

forward(node_features: Tensor, edge_index: Tensor, edge_type: Tensor) -> torch.Tensor

Forward pass.

Parameters:

Name Type Description Default
node_features Tensor of shape ``(N, in_dim)``
required
edge_index LongTensor of shape ``(2, E)``

edge_index[0] = source nodes, edge_index[1] = target nodes.

required
edge_type LongTensor of shape ``(E,)``

Relation type index for each edge.

required

Returns:

Type Description
Tensor of shape ``(N, out_dim)``
Source code in src/neorx/causalbiorl/causal/graph_encoder.py
def forward(
    self,
    node_features: torch.Tensor,
    edge_index: torch.Tensor,
    edge_type: torch.Tensor,
) -> torch.Tensor:
    """Forward pass.

    Parameters
    ----------
    node_features : Tensor of shape ``(N, in_dim)``
    edge_index : LongTensor of shape ``(2, E)``
        ``edge_index[0]`` = source nodes, ``edge_index[1]`` = target nodes.
    edge_type : LongTensor of shape ``(E,)``
        Relation type index for each edge.

    Returns
    -------
    Tensor of shape ``(N, out_dim)``
    """
    n_nodes = node_features.size(0)
    device = node_features.device

    # Start with self-loop
    out = self.W_self(node_features)

    # Per-relation message passing
    for r in range(self.n_relations):
        mask = edge_type == r
        if not mask.any():
            continue

        src = edge_index[0, mask]
        tgt = edge_index[1, mask]

        if self.use_bases:
            # W_r = sum_b coeff[r,b] * bases[b]
            W_r = torch.einsum("b,bij->ij", self.coefficients[r], self.bases)
        else:
            W_r = self.rel_weights[r]

        # Gather source features → transform → scatter-add to targets
        msg = node_features[src] @ W_r  # (E_r, out_dim)

        # Normalise by target degree under this relation
        deg = torch.zeros(n_nodes, device=device)
        deg.scatter_add_(0, tgt, torch.ones_like(tgt, dtype=torch.float))
        deg = deg.clamp(min=1.0)

        # Scatter-add messages
        out.scatter_add_(0, tgt.unsqueeze(1).expand_as(msg), msg)

        # Normalise per-node (divide by degree)
        # The self-loop already contributes, so we only normalise
        # the relation-specific contribution
        # out[tgt] was accumulated; we correct inline
        norm = deg.unsqueeze(1)
        # Apply normalisation to all nodes that received messages
        unique_tgts = tgt.unique()
        if unique_tgts.numel() > 0:
            # Scale the accumulated messages (subtract self, norm, re-add)
            pass  # scatter-add + degree norm is handled below

    # Activation + dropout
    out = F.relu(out)
    out = F.dropout(out, p=self.dropout, training=self.training)
    return out

Surrogate docking model — fast approximation of DockBot binding affinity.

Problem: AutoDock Vina takes 5-30 seconds per docking call. An RL training run with 10,000+ docking evaluations would take ~28 hours.

Solution: Train an MLP surrogate that predicts binding affinity from: - Morgan fingerprint of the ligand (2048-bit → float) - Protein-target embedding (from R-GCN node embedding, 128-D)

The surrogate runs in <1ms per call, enabling real-time RL.

Workflow: 1. Seed phase: Run real DockBot on N initial (molecule, target) pairs to build a training set. 2. Train surrogate: Fit the MLP on (fingerprint, target_emb) → affinity. 3. RL phase: Agent uses surrogate for reward during training. 4. Recalibration: Periodically run real DockBot on agent's best molecules and retrain the surrogate (prevents distribution shift).

Reference: Gentile et al. (2020) "Deep Docking: A Deep Learning Platform for Augmentation of Structure Based Drug Discovery", ACS Central Science.

SurrogateDockingModel

Fast docking score predictor for RL reward computation.

Predicts binding affinity (kcal/mol) from molecular fingerprints and target protein embeddings. Trained from real DockBot results.

Parameters:

Name Type Description Default
fp_dim int

Fingerprint dimension (default 2048 for ECFP4).

2048
target_dim int

Target embedding dimension (default 128 from R-GCN).

128
hidden_dim int

MLP hidden layer size.

256
lr float

Learning rate for training.

0.001
device str | None

"cuda" or "cpu". Auto-detected if None.

None
Source code in src/neorx/causalbiorl/causal/surrogate_docker.py
class SurrogateDockingModel:
    """Fast docking score predictor for RL reward computation.

    Predicts binding affinity (kcal/mol) from molecular fingerprints
    and target protein embeddings.  Trained from real DockBot results.

    Parameters
    ----------
    fp_dim : int
        Fingerprint dimension (default 2048 for ECFP4).
    target_dim : int
        Target embedding dimension (default 128 from R-GCN).
    hidden_dim : int
        MLP hidden layer size.
    lr : float
        Learning rate for training.
    device : str | None
        ``"cuda"`` or ``"cpu"``.  Auto-detected if ``None``.
    """

    def __init__(
        self,
        fp_dim: int = 2048,
        target_dim: int = 128,
        hidden_dim: int = 256,
        lr: float = 1e-3,
        device: str | None = None,
    ) -> None:
        self.fp_dim = fp_dim
        self.target_dim = target_dim
        self.lr = lr

        self.device = torch.device(
            device or ("cuda" if torch.cuda.is_available() else "cpu")
        )
        self.model = _DockingMLP(
            fp_dim=fp_dim,
            target_dim=target_dim,
            hidden_dim=hidden_dim,
        ).to(self.device)

        # Training data buffer for recalibration
        self._buffer_fps: list[NDArray[np.floating]] = []
        self._buffer_targets: list[NDArray[np.floating]] = []
        self._buffer_affinities: list[float] = []
        self._is_trained = False

    @property
    def is_trained(self) -> bool:
        """Whether the surrogate has been trained with real data."""
        return self._is_trained

    # ------------------------------------------------------------------ #
    #  Data Collection                                                     #
    # ------------------------------------------------------------------ #

    def add_observation(
        self,
        fingerprint: NDArray[np.floating],
        target_embedding: NDArray[np.floating],
        real_affinity: float,
    ) -> None:
        """Add a real docking observation to the training buffer.

        Parameters
        ----------
        fingerprint : ndarray ``(fp_dim,)``
            Morgan fingerprint of the ligand.
        target_embedding : ndarray ``(target_dim,)``
            R-GCN embedding of the target node.
        real_affinity : float
            Actual binding affinity from DockBot (kcal/mol).
        """
        self._buffer_fps.append(fingerprint.copy())
        self._buffer_targets.append(target_embedding.copy())
        self._buffer_affinities.append(real_affinity)

    def add_smiles_observation(
        self,
        smiles: str,
        target_embedding: NDArray[np.floating],
        real_affinity: float,
    ) -> bool:
        """Convenience: add an observation from SMILES string.

        Returns ``True`` if the SMILES was valid and added.
        """
        fp = smiles_to_fingerprint(smiles)
        if fp is None:
            return False
        self.add_observation(fp, target_embedding, real_affinity)
        return True

    @property
    def buffer_size(self) -> int:
        """Number of observations in the training buffer."""
        return len(self._buffer_affinities)

    # ------------------------------------------------------------------ #
    #  Training                                                            #
    # ------------------------------------------------------------------ #

    def fit(
        self,
        epochs: int = 200,
        batch_size: int = 64,
        verbose: bool = False,
    ) -> float:
        """Train the surrogate on buffered observations.

        Parameters
        ----------
        epochs : int
            Training epochs.
        batch_size : int
            Mini-batch size.
        verbose : bool
            Print loss every 50 epochs.

        Returns
        -------
        float
            Final training MSE loss.
        """
        if self.buffer_size < 10:
            logger.warning(
                "Surrogate has only %d observations — need at least 10 to train.",
                self.buffer_size,
            )
            return float("inf")

        fps = np.array(self._buffer_fps, dtype=np.float32)
        tgts = np.array(self._buffer_targets, dtype=np.float32)
        affs = np.array(self._buffer_affinities, dtype=np.float32)

        # Concatenate fingerprint + target embedding
        X = np.concatenate([fps, tgts], axis=1)
        Xt = torch.tensor(X, dtype=torch.float32, device=self.device)
        Yt = torch.tensor(affs, dtype=torch.float32, device=self.device)

        optimiser = torch.optim.Adam(self.model.parameters(), lr=self.lr)
        loss_fn = nn.MSELoss()

        self.model.train()
        n = len(Xt)
        final_loss = float("inf")

        for epoch in range(epochs):
            # Shuffle
            perm = torch.randperm(n, device=self.device)
            epoch_loss = 0.0
            n_batches = 0

            for start in range(0, n, batch_size):
                idx = perm[start : start + batch_size]
                x_batch = Xt[idx]
                y_batch = Yt[idx]

                pred = self.model(x_batch)
                loss = loss_fn(pred, y_batch)

                optimiser.zero_grad()
                loss.backward()
                optimiser.step()

                epoch_loss += loss.item()
                n_batches += 1

            final_loss = epoch_loss / max(n_batches, 1)

            if verbose and epoch % 50 == 0:
                logger.info("Surrogate epoch %d/%d — MSE: %.4f", epoch, epochs, final_loss)

        self.model.eval()
        self._is_trained = True
        logger.info(
            "Surrogate trained on %d observations — final MSE: %.4f",
            self.buffer_size, final_loss,
        )
        return final_loss

    # ------------------------------------------------------------------ #
    #  Prediction                                                          #
    # ------------------------------------------------------------------ #

    @torch.no_grad()
    def predict(
        self,
        fingerprint: NDArray[np.floating],
        target_embedding: NDArray[np.floating],
    ) -> float:
        """Predict binding affinity for a single (ligand, target) pair.

        Parameters
        ----------
        fingerprint : ndarray ``(fp_dim,)``
        target_embedding : ndarray ``(target_dim,)``

        Returns
        -------
        float
            Predicted binding affinity (kcal/mol, negative = better).
        """
        if not self._is_trained:
            # Return neutral estimate before training
            return -5.0

        x = np.concatenate([fingerprint, target_embedding])
        xt = torch.tensor(x, dtype=torch.float32, device=self.device).unsqueeze(0)
        return float(self.model(xt).item())

    @torch.no_grad()
    def predict_smiles(
        self,
        smiles: str,
        target_embedding: NDArray[np.floating],
    ) -> float | None:
        """Convenience: predict affinity from SMILES string.

        Returns ``None`` if SMILES parsing fails.
        """
        fp = smiles_to_fingerprint(smiles)
        if fp is None:
            return None
        return self.predict(fp, target_embedding)

    @torch.no_grad()
    def predict_batch(
        self,
        fingerprints: NDArray[np.floating],
        target_embeddings: NDArray[np.floating],
    ) -> NDArray[np.floating]:
        """Predict affinities for a batch.

        Parameters
        ----------
        fingerprints : ndarray ``(B, fp_dim)``
        target_embeddings : ndarray ``(B, target_dim)``

        Returns
        -------
        ndarray ``(B,)``
        """
        if not self._is_trained:
            return np.full(len(fingerprints), -5.0, dtype=np.float32)

        X = np.concatenate([fingerprints, target_embeddings], axis=1)
        Xt = torch.tensor(X, dtype=torch.float32, device=self.device)
        return self.model(Xt).cpu().numpy()

    # ------------------------------------------------------------------ #
    #  Recalibration                                                       #
    # ------------------------------------------------------------------ #

    def recalibrate(
        self,
        fingerprints: NDArray[np.floating],
        target_embeddings: NDArray[np.floating],
        real_affinities: NDArray[np.floating],
        epochs: int = 100,
    ) -> float:
        """Recalibrate with new real docking data.

        Adds the new data to the buffer and retrains.  Prevents
        distribution shift when the RL agent explores regions
        far from the initial training data.

        Parameters
        ----------
        fingerprints : ndarray ``(N, fp_dim)``
        target_embeddings : ndarray ``(N, target_dim)``
        real_affinities : ndarray ``(N,)``
        epochs : int
            Recalibration training epochs.

        Returns
        -------
        float
            Final loss after recalibration.
        """
        for i in range(len(real_affinities)):
            self.add_observation(
                fingerprints[i], target_embeddings[i], float(real_affinities[i]),
            )

        logger.info(
            "Recalibrating surrogate with %d new observations (total buffer: %d).",
            len(real_affinities), self.buffer_size,
        )
        return self.fit(epochs=epochs)

    # ------------------------------------------------------------------ #
    #  Persistence                                                         #
    # ------------------------------------------------------------------ #

    def save(self, path: str) -> None:
        """Save model weights and buffer to disk."""
        torch.save(
            {
                "model_state": self.model.state_dict(),
                "buffer_fps": self._buffer_fps,
                "buffer_targets": self._buffer_targets,
                "buffer_affinities": self._buffer_affinities,
                "is_trained": self._is_trained,
                "fp_dim": self.fp_dim,
                "target_dim": self.target_dim,
            },
            path,
        )
        logger.info("Surrogate saved to %s", path)

    def load(self, path: str) -> None:
        """Load model weights and buffer from disk."""
        checkpoint = torch.load(path, map_location=self.device, weights_only=False)
        self.model.load_state_dict(checkpoint["model_state"])
        self._buffer_fps = checkpoint["buffer_fps"]
        self._buffer_targets = checkpoint["buffer_targets"]
        self._buffer_affinities = checkpoint["buffer_affinities"]
        self._is_trained = checkpoint["is_trained"]
        self.model.eval()
        logger.info(
            "Surrogate loaded from %s (buffer: %d, trained: %s)",
            path, self.buffer_size, self._is_trained,
        )

is_trained property

is_trained: bool

Whether the surrogate has been trained with real data.

buffer_size property

buffer_size: int

Number of observations in the training buffer.

add_observation

add_observation(fingerprint: NDArray[floating], target_embedding: NDArray[floating], real_affinity: float) -> None

Add a real docking observation to the training buffer.

Parameters:

Name Type Description Default
fingerprint ndarray ``(fp_dim,)``

Morgan fingerprint of the ligand.

required
target_embedding ndarray ``(target_dim,)``

R-GCN embedding of the target node.

required
real_affinity float

Actual binding affinity from DockBot (kcal/mol).

required
Source code in src/neorx/causalbiorl/causal/surrogate_docker.py
def add_observation(
    self,
    fingerprint: NDArray[np.floating],
    target_embedding: NDArray[np.floating],
    real_affinity: float,
) -> None:
    """Add a real docking observation to the training buffer.

    Parameters
    ----------
    fingerprint : ndarray ``(fp_dim,)``
        Morgan fingerprint of the ligand.
    target_embedding : ndarray ``(target_dim,)``
        R-GCN embedding of the target node.
    real_affinity : float
        Actual binding affinity from DockBot (kcal/mol).
    """
    self._buffer_fps.append(fingerprint.copy())
    self._buffer_targets.append(target_embedding.copy())
    self._buffer_affinities.append(real_affinity)

add_smiles_observation

add_smiles_observation(smiles: str, target_embedding: NDArray[floating], real_affinity: float) -> bool

Convenience: add an observation from SMILES string.

Returns True if the SMILES was valid and added.

Source code in src/neorx/causalbiorl/causal/surrogate_docker.py
def add_smiles_observation(
    self,
    smiles: str,
    target_embedding: NDArray[np.floating],
    real_affinity: float,
) -> bool:
    """Convenience: add an observation from SMILES string.

    Returns ``True`` if the SMILES was valid and added.
    """
    fp = smiles_to_fingerprint(smiles)
    if fp is None:
        return False
    self.add_observation(fp, target_embedding, real_affinity)
    return True

fit

fit(epochs: int = 200, batch_size: int = 64, verbose: bool = False) -> float

Train the surrogate on buffered observations.

Parameters:

Name Type Description Default
epochs int

Training epochs.

200
batch_size int

Mini-batch size.

64
verbose bool

Print loss every 50 epochs.

False

Returns:

Type Description
float

Final training MSE loss.

Source code in src/neorx/causalbiorl/causal/surrogate_docker.py
def fit(
    self,
    epochs: int = 200,
    batch_size: int = 64,
    verbose: bool = False,
) -> float:
    """Train the surrogate on buffered observations.

    Parameters
    ----------
    epochs : int
        Training epochs.
    batch_size : int
        Mini-batch size.
    verbose : bool
        Print loss every 50 epochs.

    Returns
    -------
    float
        Final training MSE loss.
    """
    if self.buffer_size < 10:
        logger.warning(
            "Surrogate has only %d observations — need at least 10 to train.",
            self.buffer_size,
        )
        return float("inf")

    fps = np.array(self._buffer_fps, dtype=np.float32)
    tgts = np.array(self._buffer_targets, dtype=np.float32)
    affs = np.array(self._buffer_affinities, dtype=np.float32)

    # Concatenate fingerprint + target embedding
    X = np.concatenate([fps, tgts], axis=1)
    Xt = torch.tensor(X, dtype=torch.float32, device=self.device)
    Yt = torch.tensor(affs, dtype=torch.float32, device=self.device)

    optimiser = torch.optim.Adam(self.model.parameters(), lr=self.lr)
    loss_fn = nn.MSELoss()

    self.model.train()
    n = len(Xt)
    final_loss = float("inf")

    for epoch in range(epochs):
        # Shuffle
        perm = torch.randperm(n, device=self.device)
        epoch_loss = 0.0
        n_batches = 0

        for start in range(0, n, batch_size):
            idx = perm[start : start + batch_size]
            x_batch = Xt[idx]
            y_batch = Yt[idx]

            pred = self.model(x_batch)
            loss = loss_fn(pred, y_batch)

            optimiser.zero_grad()
            loss.backward()
            optimiser.step()

            epoch_loss += loss.item()
            n_batches += 1

        final_loss = epoch_loss / max(n_batches, 1)

        if verbose and epoch % 50 == 0:
            logger.info("Surrogate epoch %d/%d — MSE: %.4f", epoch, epochs, final_loss)

    self.model.eval()
    self._is_trained = True
    logger.info(
        "Surrogate trained on %d observations — final MSE: %.4f",
        self.buffer_size, final_loss,
    )
    return final_loss

predict

predict(fingerprint: NDArray[floating], target_embedding: NDArray[floating]) -> float

Predict binding affinity for a single (ligand, target) pair.

Parameters:

Name Type Description Default
fingerprint ndarray ``(fp_dim,)``
required
target_embedding ndarray ``(target_dim,)``
required

Returns:

Type Description
float

Predicted binding affinity (kcal/mol, negative = better).

Source code in src/neorx/causalbiorl/causal/surrogate_docker.py
@torch.no_grad()
def predict(
    self,
    fingerprint: NDArray[np.floating],
    target_embedding: NDArray[np.floating],
) -> float:
    """Predict binding affinity for a single (ligand, target) pair.

    Parameters
    ----------
    fingerprint : ndarray ``(fp_dim,)``
    target_embedding : ndarray ``(target_dim,)``

    Returns
    -------
    float
        Predicted binding affinity (kcal/mol, negative = better).
    """
    if not self._is_trained:
        # Return neutral estimate before training
        return -5.0

    x = np.concatenate([fingerprint, target_embedding])
    xt = torch.tensor(x, dtype=torch.float32, device=self.device).unsqueeze(0)
    return float(self.model(xt).item())

predict_smiles

predict_smiles(smiles: str, target_embedding: NDArray[floating]) -> float | None

Convenience: predict affinity from SMILES string.

Returns None if SMILES parsing fails.

Source code in src/neorx/causalbiorl/causal/surrogate_docker.py
@torch.no_grad()
def predict_smiles(
    self,
    smiles: str,
    target_embedding: NDArray[np.floating],
) -> float | None:
    """Convenience: predict affinity from SMILES string.

    Returns ``None`` if SMILES parsing fails.
    """
    fp = smiles_to_fingerprint(smiles)
    if fp is None:
        return None
    return self.predict(fp, target_embedding)

predict_batch

predict_batch(fingerprints: NDArray[floating], target_embeddings: NDArray[floating]) -> NDArray[np.floating]

Predict affinities for a batch.

Parameters:

Name Type Description Default
fingerprints ndarray ``(B, fp_dim)``
required
target_embeddings ndarray ``(B, target_dim)``
required

Returns:

Type Description
ndarray ``(B,)``
Source code in src/neorx/causalbiorl/causal/surrogate_docker.py
@torch.no_grad()
def predict_batch(
    self,
    fingerprints: NDArray[np.floating],
    target_embeddings: NDArray[np.floating],
) -> NDArray[np.floating]:
    """Predict affinities for a batch.

    Parameters
    ----------
    fingerprints : ndarray ``(B, fp_dim)``
    target_embeddings : ndarray ``(B, target_dim)``

    Returns
    -------
    ndarray ``(B,)``
    """
    if not self._is_trained:
        return np.full(len(fingerprints), -5.0, dtype=np.float32)

    X = np.concatenate([fingerprints, target_embeddings], axis=1)
    Xt = torch.tensor(X, dtype=torch.float32, device=self.device)
    return self.model(Xt).cpu().numpy()

recalibrate

recalibrate(fingerprints: NDArray[floating], target_embeddings: NDArray[floating], real_affinities: NDArray[floating], epochs: int = 100) -> float

Recalibrate with new real docking data.

Adds the new data to the buffer and retrains. Prevents distribution shift when the RL agent explores regions far from the initial training data.

Parameters:

Name Type Description Default
fingerprints ndarray ``(N, fp_dim)``
required
target_embeddings ndarray ``(N, target_dim)``
required
real_affinities ndarray ``(N,)``
required
epochs int

Recalibration training epochs.

100

Returns:

Type Description
float

Final loss after recalibration.

Source code in src/neorx/causalbiorl/causal/surrogate_docker.py
def recalibrate(
    self,
    fingerprints: NDArray[np.floating],
    target_embeddings: NDArray[np.floating],
    real_affinities: NDArray[np.floating],
    epochs: int = 100,
) -> float:
    """Recalibrate with new real docking data.

    Adds the new data to the buffer and retrains.  Prevents
    distribution shift when the RL agent explores regions
    far from the initial training data.

    Parameters
    ----------
    fingerprints : ndarray ``(N, fp_dim)``
    target_embeddings : ndarray ``(N, target_dim)``
    real_affinities : ndarray ``(N,)``
    epochs : int
        Recalibration training epochs.

    Returns
    -------
    float
        Final loss after recalibration.
    """
    for i in range(len(real_affinities)):
        self.add_observation(
            fingerprints[i], target_embeddings[i], float(real_affinities[i]),
        )

    logger.info(
        "Recalibrating surrogate with %d new observations (total buffer: %d).",
        len(real_affinities), self.buffer_size,
    )
    return self.fit(epochs=epochs)

save

save(path: str) -> None

Save model weights and buffer to disk.

Source code in src/neorx/causalbiorl/causal/surrogate_docker.py
def save(self, path: str) -> None:
    """Save model weights and buffer to disk."""
    torch.save(
        {
            "model_state": self.model.state_dict(),
            "buffer_fps": self._buffer_fps,
            "buffer_targets": self._buffer_targets,
            "buffer_affinities": self._buffer_affinities,
            "is_trained": self._is_trained,
            "fp_dim": self.fp_dim,
            "target_dim": self.target_dim,
        },
        path,
    )
    logger.info("Surrogate saved to %s", path)

load

load(path: str) -> None

Load model weights and buffer from disk.

Source code in src/neorx/causalbiorl/causal/surrogate_docker.py
def load(self, path: str) -> None:
    """Load model weights and buffer from disk."""
    checkpoint = torch.load(path, map_location=self.device, weights_only=False)
    self.model.load_state_dict(checkpoint["model_state"])
    self._buffer_fps = checkpoint["buffer_fps"]
    self._buffer_targets = checkpoint["buffer_targets"]
    self._buffer_affinities = checkpoint["buffer_affinities"]
    self._is_trained = checkpoint["is_trained"]
    self.model.eval()
    logger.info(
        "Surrogate loaded from %s (buffer: %d, trained: %s)",
        path, self.buffer_size, self._is_trained,
    )

smiles_to_fingerprint

smiles_to_fingerprint(smiles: str, radius: int = 2, n_bits: int = 2048) -> NDArray[np.floating] | None

Convert SMILES to Morgan fingerprint vector.

Parameters:

Name Type Description Default
smiles str

SMILES string of the molecule.

required
radius int

Morgan fingerprint radius (default 2 ≈ ECFP4).

2
n_bits int

Fingerprint length.

2048

Returns:

Type Description
ndarray of shape ``(n_bits,)`` or ``None`` if parsing fails.
Source code in src/neorx/causalbiorl/causal/surrogate_docker.py
def smiles_to_fingerprint(
    smiles: str,
    radius: int = 2,
    n_bits: int = 2048,
) -> NDArray[np.floating] | None:
    """Convert SMILES to Morgan fingerprint vector.

    Parameters
    ----------
    smiles : str
        SMILES string of the molecule.
    radius : int
        Morgan fingerprint radius (default 2 ≈ ECFP4).
    n_bits : int
        Fingerprint length.

    Returns
    -------
    ndarray of shape ``(n_bits,)`` or ``None`` if parsing fails.
    """
    try:
        from rdkit import Chem
        from rdkit.Chem import AllChem

        mol = Chem.MolFromSmiles(smiles)
        if mol is None:
            return None

        fp = AllChem.GetMorganFingerprintAsBitVect(mol, radius, nBits=n_bits)
        return np.array(fp, dtype=np.float32)
    except Exception:
        return None

Adaptive Reward Learner — hindsight reward shaping for multi-objective RL.

In drug discovery, the agent must optimise multiple objectives simultaneously:

1. Binding affinity   (DockBot / surrogate)
2. Drug-likeness      (QED)
3. Synthetic access.  (SA score)
4. Novelty            (Tanimoto distance to known drugs)
5. Causal confidence  (from SCM do-calculus)
6. Structural stab.   (MirrorFold therapeutic score)

A naïve approach uses fixed weights: r = Σ wᵢ rᵢ. But fixed weights: - Collapse to the easiest objective (the agent games it) - Ignore disease-specific difficulty profiles - Require manual tuning per disease

Hindsight Reward Shaping (Option C): - A critic network estimates objective-specific difficulty - Objectives that are underperforming get up-weighted - Objectives that are easily satisfied get down-weighted - The agent naturally focuses on the bottleneck

This is a form of curriculum learning applied to reward composition — the agent adapts its focus as it improves.

Reference: Adapted from Abels et al. (2019) "Dynamic Weights in Multi-Objective Deep Reinforcement Learning", ICML.

AdaptiveRewardLearner

Learns dynamic reward weights via per-objective difficulty estimation.

Architecture: - One critic per objective: V_i(state) → expected_score_i - Difficulty = 1 - V_i(state) (how far from perfect) - Weight for objective i ∝ difficulty_i^temperature - Weights are normalised to sum to 1

The temperature parameter controls adaptation strength: - temperature = 0 → equal weights (fixed) - temperature = 1 → linear difficulty weighting - temperature > 1 → aggressive focus on bottleneck

Parameters:

Name Type Description Default
state_dim int

Dimension of the state vector (graph embedding + mol features).

128
base_weights ndarray | None

Initial (prior) weights for each objective. If None, uses domain-informed defaults.

None
temperature float

Controls how aggressively to up-weight bottleneck objectives.

1.5
lr float

Learning rate for critic training.

0.001
gamma float

Discount factor for temporal difference learning.

0.99
device str | None

"cuda" or "cpu".

None
Source code in src/neorx/causalbiorl/causal/reward_learner.py
class AdaptiveRewardLearner:
    """Learns dynamic reward weights via per-objective difficulty estimation.

    Architecture:
        - One critic per objective: ``V_i(state) → expected_score_i``
        - Difficulty = ``1 - V_i(state)`` (how far from perfect)
        - Weight for objective ``i`` ∝ ``difficulty_i^temperature``
        - Weights are normalised to sum to 1

    The ``temperature`` parameter controls adaptation strength:
        - ``temperature = 0`` → equal weights (fixed)
        - ``temperature = 1`` → linear difficulty weighting
        - ``temperature > 1`` → aggressive focus on bottleneck

    Parameters
    ----------
    state_dim : int
        Dimension of the state vector (graph embedding + mol features).
    base_weights : ndarray | None
        Initial (prior) weights for each objective.  If ``None``,
        uses domain-informed defaults.
    temperature : float
        Controls how aggressively to up-weight bottleneck objectives.
    lr : float
        Learning rate for critic training.
    gamma : float
        Discount factor for temporal difference learning.
    device : str | None
        ``"cuda"`` or ``"cpu"``.
    """

    def __init__(
        self,
        state_dim: int = 128,
        base_weights: NDArray[np.floating] | None = None,
        temperature: float = 1.5,
        lr: float = 1e-3,
        gamma: float = 0.99,
        device: str | None = None,
    ) -> None:
        self.state_dim = state_dim
        self.temperature = temperature
        self.gamma = gamma

        self.device = torch.device(
            device or ("cuda" if torch.cuda.is_available() else "cpu")
        )

        # Base (prior) weights — domain-informed
        if base_weights is not None:
            self.base_weights = np.array(base_weights, dtype=np.float32)
        else:
            # Default: binding + causal get slight prior emphasis
            self.base_weights = np.array(
                [0.25, 0.15, 0.10, 0.10, 0.25, 0.15],
                dtype=np.float32,
            )

        assert len(self.base_weights) == N_OBJECTIVES
        self.base_weights /= self.base_weights.sum()  # normalise

        # Per-objective critics
        self.critics = nn.ModuleList([
            _ObjectiveCritic(state_dim).to(self.device)
            for _ in range(N_OBJECTIVES)
        ])

        self.optimiser = torch.optim.Adam(self.critics.parameters(), lr=lr)

        # Running statistics for logging
        self._weight_history: list[NDArray[np.floating]] = []
        self._objective_history: list[NDArray[np.floating]] = []

    # ------------------------------------------------------------------ #
    #  Reward Computation                                                  #
    # ------------------------------------------------------------------ #

    def score(
        self,
        state: NDArray[np.floating],
        objective_scores: dict[str, float],
    ) -> float:
        """The adaptively-weighted scalar reward, recording nothing.

        ``compute_reward`` records each call into the weight and
        objective histories, which makes it unusable for scoring
        candidate actions -- a planner evaluating a batch would write
        hundreds of phantom entries per environment step. This is the
        pure half.
        """
        weights = self._compute_weights(state)
        scores = np.array([
            objective_scores.get(name, 0.0)
            for name in OBJECTIVE_NAMES
        ], dtype=np.float32)
        return float(np.dot(weights, scores))

    def compute_reward(
        self,
        state: NDArray[np.floating],
        objective_scores: dict[str, float],
    ) -> float:
        """Compute the reward and record it in the learner's history.

        Parameters
        ----------
        state : ndarray
            Current state vector (graph embedding + mol features).
        objective_scores : dict[str, float]
            Per-objective scores, keyed by objective name.
            All values should be in [0, 1] (higher = better).

        Returns
        -------
        float
            Scalar reward.
        """
        weights = self._compute_weights(state)
        scores = np.array([
            objective_scores.get(name, 0.0)
            for name in OBJECTIVE_NAMES
        ], dtype=np.float32)

        self._weight_history.append(weights.copy())
        self._objective_history.append(scores.copy())

        return float(np.dot(weights, scores))

    def _compute_weights(
        self,
        state: NDArray[np.floating],
    ) -> NDArray[np.floating]:
        """Compute dynamic weights based on objective difficulty.

        Returns
        -------
        ndarray ``(N_OBJECTIVES,)`` summing to 1.
        """
        state_t = torch.tensor(
            state, dtype=torch.float32, device=self.device,
        ).unsqueeze(0)

        # Predict expected score for each objective
        with torch.no_grad():
            expected = np.array([
                critic(state_t).item()
                for critic in self.critics
            ], dtype=np.float32)

        # Difficulty = 1 - expected_score (how far from perfect)
        difficulty = 1.0 - expected

        # Combine base weights with difficulty
        # Higher difficulty → higher weight
        raw_weights = self.base_weights * (difficulty ** self.temperature + 1e-6)

        # Normalise
        weights = raw_weights / raw_weights.sum()
        return weights

    # ------------------------------------------------------------------ #
    #  Critic Training                                                     #
    # ------------------------------------------------------------------ #

    def update(
        self,
        state: NDArray[np.floating],
        objective_scores: dict[str, float],
        next_state: NDArray[np.floating] | None = None,
    ) -> float:
        """Update objective critics with observed scores.

        Uses a simple TD(0) update:
            ``V_i(s) ← r_i + γ · V_i(s')``

        Parameters
        ----------
        state : ndarray
            Current state.
        objective_scores : dict[str, float]
            Observed objective scores.
        next_state : ndarray | None
            Next state (for TD target).  If ``None``, treats as terminal.

        Returns
        -------
        float
            Mean critic loss across objectives.
        """
        state_t = torch.tensor(
            state, dtype=torch.float32, device=self.device,
        ).unsqueeze(0)

        if next_state is not None:
            next_state_t = torch.tensor(
                next_state, dtype=torch.float32, device=self.device,
            ).unsqueeze(0)
        else:
            next_state_t = None

        total_loss = torch.tensor(0.0, device=self.device)

        for i, name in enumerate(OBJECTIVE_NAMES):
            r_i = objective_scores.get(name, 0.0)

            # TD target
            if next_state_t is not None:
                with torch.no_grad():
                    v_next = self.critics[i](next_state_t)
                target = r_i + self.gamma * v_next
            else:
                target = torch.tensor(r_i, device=self.device).unsqueeze(0)

            # Prediction
            v_pred = self.critics[i](state_t)
            loss = nn.functional.mse_loss(v_pred, target)
            total_loss = total_loss + loss

        self.optimiser.zero_grad()
        total_loss.backward()
        self.optimiser.step()

        return total_loss.item() / N_OBJECTIVES

    # ------------------------------------------------------------------ #
    #  Diagnostics                                                         #
    # ------------------------------------------------------------------ #

    def get_current_weights(
        self,
        state: NDArray[np.floating],
    ) -> dict[str, float]:
        """Return current adaptive weights as a readable dict."""
        weights = self._compute_weights(state)
        return {
            name: float(w)
            for name, w in zip(OBJECTIVE_NAMES, weights)
        }

    def get_weight_history(self) -> dict[str, list[float]]:
        """Return weight trajectory for analysis/plotting."""
        if not self._weight_history:
            return {name: [] for name in OBJECTIVE_NAMES}

        arr = np.array(self._weight_history)
        return {
            name: arr[:, i].tolist()
            for i, name in enumerate(OBJECTIVE_NAMES)
        }

    def get_objective_history(self) -> dict[str, list[float]]:
        """Return per-objective score trajectory."""
        if not self._objective_history:
            return {name: [] for name in OBJECTIVE_NAMES}

        arr = np.array(self._objective_history)
        return {
            name: arr[:, i].tolist()
            for i, name in enumerate(OBJECTIVE_NAMES)
        }

    def get_difficulty_profile(
        self,
        state: NDArray[np.floating],
    ) -> dict[str, float]:
        """Return the estimated difficulty for each objective.

        Values in [0, 1] — higher = harder to satisfy.
        """
        state_t = torch.tensor(
            state, dtype=torch.float32, device=self.device,
        ).unsqueeze(0)

        with torch.no_grad():
            expected = np.array([
                critic(state_t).item()
                for critic in self.critics
            ], dtype=np.float32)

        difficulty = 1.0 - expected
        return {
            name: float(d)
            for name, d in zip(OBJECTIVE_NAMES, difficulty)
        }

score

score(state: NDArray[floating], objective_scores: dict[str, float]) -> float

The adaptively-weighted scalar reward, recording nothing.

compute_reward records each call into the weight and objective histories, which makes it unusable for scoring candidate actions -- a planner evaluating a batch would write hundreds of phantom entries per environment step. This is the pure half.

Source code in src/neorx/causalbiorl/causal/reward_learner.py
def score(
    self,
    state: NDArray[np.floating],
    objective_scores: dict[str, float],
) -> float:
    """The adaptively-weighted scalar reward, recording nothing.

    ``compute_reward`` records each call into the weight and
    objective histories, which makes it unusable for scoring
    candidate actions -- a planner evaluating a batch would write
    hundreds of phantom entries per environment step. This is the
    pure half.
    """
    weights = self._compute_weights(state)
    scores = np.array([
        objective_scores.get(name, 0.0)
        for name in OBJECTIVE_NAMES
    ], dtype=np.float32)
    return float(np.dot(weights, scores))

compute_reward

compute_reward(state: NDArray[floating], objective_scores: dict[str, float]) -> float

Compute the reward and record it in the learner's history.

Parameters:

Name Type Description Default
state ndarray

Current state vector (graph embedding + mol features).

required
objective_scores dict[str, float]

Per-objective scores, keyed by objective name. All values should be in [0, 1] (higher = better).

required

Returns:

Type Description
float

Scalar reward.

Source code in src/neorx/causalbiorl/causal/reward_learner.py
def compute_reward(
    self,
    state: NDArray[np.floating],
    objective_scores: dict[str, float],
) -> float:
    """Compute the reward and record it in the learner's history.

    Parameters
    ----------
    state : ndarray
        Current state vector (graph embedding + mol features).
    objective_scores : dict[str, float]
        Per-objective scores, keyed by objective name.
        All values should be in [0, 1] (higher = better).

    Returns
    -------
    float
        Scalar reward.
    """
    weights = self._compute_weights(state)
    scores = np.array([
        objective_scores.get(name, 0.0)
        for name in OBJECTIVE_NAMES
    ], dtype=np.float32)

    self._weight_history.append(weights.copy())
    self._objective_history.append(scores.copy())

    return float(np.dot(weights, scores))

update

update(state: NDArray[floating], objective_scores: dict[str, float], next_state: NDArray[floating] | None = None) -> float

Update objective critics with observed scores.

Uses a simple TD(0) update: V_i(s) ← r_i + γ · V_i(s')

Parameters:

Name Type Description Default
state ndarray

Current state.

required
objective_scores dict[str, float]

Observed objective scores.

required
next_state ndarray | None

Next state (for TD target). If None, treats as terminal.

None

Returns:

Type Description
float

Mean critic loss across objectives.

Source code in src/neorx/causalbiorl/causal/reward_learner.py
def update(
    self,
    state: NDArray[np.floating],
    objective_scores: dict[str, float],
    next_state: NDArray[np.floating] | None = None,
) -> float:
    """Update objective critics with observed scores.

    Uses a simple TD(0) update:
        ``V_i(s) ← r_i + γ · V_i(s')``

    Parameters
    ----------
    state : ndarray
        Current state.
    objective_scores : dict[str, float]
        Observed objective scores.
    next_state : ndarray | None
        Next state (for TD target).  If ``None``, treats as terminal.

    Returns
    -------
    float
        Mean critic loss across objectives.
    """
    state_t = torch.tensor(
        state, dtype=torch.float32, device=self.device,
    ).unsqueeze(0)

    if next_state is not None:
        next_state_t = torch.tensor(
            next_state, dtype=torch.float32, device=self.device,
        ).unsqueeze(0)
    else:
        next_state_t = None

    total_loss = torch.tensor(0.0, device=self.device)

    for i, name in enumerate(OBJECTIVE_NAMES):
        r_i = objective_scores.get(name, 0.0)

        # TD target
        if next_state_t is not None:
            with torch.no_grad():
                v_next = self.critics[i](next_state_t)
            target = r_i + self.gamma * v_next
        else:
            target = torch.tensor(r_i, device=self.device).unsqueeze(0)

        # Prediction
        v_pred = self.critics[i](state_t)
        loss = nn.functional.mse_loss(v_pred, target)
        total_loss = total_loss + loss

    self.optimiser.zero_grad()
    total_loss.backward()
    self.optimiser.step()

    return total_loss.item() / N_OBJECTIVES

get_current_weights

get_current_weights(state: NDArray[floating]) -> dict[str, float]

Return current adaptive weights as a readable dict.

Source code in src/neorx/causalbiorl/causal/reward_learner.py
def get_current_weights(
    self,
    state: NDArray[np.floating],
) -> dict[str, float]:
    """Return current adaptive weights as a readable dict."""
    weights = self._compute_weights(state)
    return {
        name: float(w)
        for name, w in zip(OBJECTIVE_NAMES, weights)
    }

get_weight_history

get_weight_history() -> dict[str, list[float]]

Return weight trajectory for analysis/plotting.

Source code in src/neorx/causalbiorl/causal/reward_learner.py
def get_weight_history(self) -> dict[str, list[float]]:
    """Return weight trajectory for analysis/plotting."""
    if not self._weight_history:
        return {name: [] for name in OBJECTIVE_NAMES}

    arr = np.array(self._weight_history)
    return {
        name: arr[:, i].tolist()
        for i, name in enumerate(OBJECTIVE_NAMES)
    }

get_objective_history

get_objective_history() -> dict[str, list[float]]

Return per-objective score trajectory.

Source code in src/neorx/causalbiorl/causal/reward_learner.py
def get_objective_history(self) -> dict[str, list[float]]:
    """Return per-objective score trajectory."""
    if not self._objective_history:
        return {name: [] for name in OBJECTIVE_NAMES}

    arr = np.array(self._objective_history)
    return {
        name: arr[:, i].tolist()
        for i, name in enumerate(OBJECTIVE_NAMES)
    }

get_difficulty_profile

get_difficulty_profile(state: NDArray[floating]) -> dict[str, float]

Return the estimated difficulty for each objective.

Values in [0, 1] — higher = harder to satisfy.

Source code in src/neorx/causalbiorl/causal/reward_learner.py
def get_difficulty_profile(
    self,
    state: NDArray[np.floating],
) -> dict[str, float]:
    """Return the estimated difficulty for each objective.

    Values in [0, 1] — higher = harder to satisfy.
    """
    state_t = torch.tensor(
        state, dtype=torch.float32, device=self.device,
    ).unsqueeze(0)

    with torch.no_grad():
        expected = np.array([
            critic(state_t).item()
            for critic in self.critics
        ], dtype=np.float32)

    difficulty = 1.0 - expected
    return {
        name: float(d)
        for name, d in zip(OBJECTIVE_NAMES, difficulty)
    }

DrugDiscovery-v0 — Gymnasium environment for RL-driven drug discovery.

This is the integration point where CausalBioRL meets the real NeoRx pipeline. Instead of toy ODE environments, the RL agent interacts with real drug-discovery modules:

- **NeoRx** — disease graph, causal targets, SCM
- **GenMol** — VAE-based molecule generation (latent space navigation)
- **MolScreen** — drug-likeness scoring (QED, SA, filters)
- **DockBot** — binding affinity (via surrogate for speed)
- **MirrorFold** — structural stability assessment
Architecture

State: Graph embedding (128D from R-GCN) + current best molecule features (32D) + per-target summary (n_targets × 8D) → flattened to fixed size.

Action (hierarchical): Level 1: Target selection (discrete: which target to pursue) Level 2: Molecule generation (continuous 128D delta-z in GenMol latent)

Reward: Adaptively-weighted multi-objective (AdaptiveRewardLearner): binding, QED, SA, novelty, causal confidence, stability.

Episode: One disease campaign. Agent has a budget of N generate-screen cycles. It decides which targets to invest in and how to explore the chemical space for each.

Termination: Budget exhausted OR agent outputs "stop" action (early confidence).

Design Decisions
- Disease graph is built once at ``reset()`` and cached.
- DockBot uses a surrogate model during training; real docking only
  at episode end for recalibration (see ``screening.py``).
- GenMol generates from ``z_base + delta_z``: the agent learns to
  navigate the latent space, not just sample randomly.

DrugDiscoveryEnv

Bases: Env

Gymnasium environment for RL-driven drug discovery campaigns.

Parameters:

Name Type Description Default
disease str

Disease name (e.g. "Malaria", "HIV").

'Malaria'
max_steps int

Budget: maximum generate-screen cycles per episode.

50
top_n_targets int

Number of causal targets to pursue (from NeoRx pipeline).

5
latent_dim int

GenMol VAE latent space dimension.

LATENT_DIM
use_surrogate bool

Use surrogate docking model (fast) vs real DockBot (slow).

True
recalibrate_interval int

Every N steps, run real docking to recalibrate surrogate.

10
difficulty str

"easy" / "medium" / "hard" — affects noise & budget.

'medium'
prebuilt_graph DiGraph | None

Pre-built disease graph. If provided, skips graph building.

None
prebuilt_targets list[dict] | None

Pre-identified targets. If provided, skips identification.

None
Source code in src/neorx/causalbiorl/envs/drug_discovery.py
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
class DrugDiscoveryEnv(gym.Env):
    """Gymnasium environment for RL-driven drug discovery campaigns.

    Parameters
    ----------
    disease : str
        Disease name (e.g. "Malaria", "HIV").
    max_steps : int
        Budget: maximum generate-screen cycles per episode.
    top_n_targets : int
        Number of causal targets to pursue (from NeoRx pipeline).
    latent_dim : int
        GenMol VAE latent space dimension.
    use_surrogate : bool
        Use surrogate docking model (fast) vs real DockBot (slow).
    recalibrate_interval : int
        Every N steps, run real docking to recalibrate surrogate.
    difficulty : str
        ``"easy"`` / ``"medium"`` / ``"hard"`` — affects noise & budget.
    prebuilt_graph : nx.DiGraph | None
        Pre-built disease graph.  If provided, skips graph building.
    prebuilt_targets : list[dict] | None
        Pre-identified targets.  If provided, skips identification.
    """

    metadata = {"render_modes": ["human"], "render_fps": 1}

    _DIFFICULTY = {
        "easy":   {"budget_mult": 2.0, "noise": 0.0},
        "medium": {"budget_mult": 1.0, "noise": 0.02},
        "hard":   {"budget_mult": 0.5, "noise": 0.05},
    }

    def __init__(
        self,
        disease: str = "Malaria",
        max_steps: int = 50,
        top_n_targets: int = 5,
        latent_dim: int = LATENT_DIM,
        use_surrogate: bool = True,
        recalibrate_interval: int = 10,
        difficulty: str = "medium",
        prebuilt_graph: nx.DiGraph | None = None,
        prebuilt_targets: list[dict[str, Any]] | None = None,
        render_mode: str | None = None,
    ) -> None:
        super().__init__()
        assert difficulty in self._DIFFICULTY

        self.disease = disease
        self.latent_dim = latent_dim
        self.use_surrogate = use_surrogate
        self.recalibrate_interval = recalibrate_interval
        self.difficulty = difficulty
        self.render_mode = render_mode
        self.top_n_targets = min(top_n_targets, MAX_TARGETS)

        diff = self._DIFFICULTY[difficulty]
        self.max_steps = int(max_steps * diff["budget_mult"])
        self._noise_std: float = diff["noise"]

        self._prebuilt_graph = prebuilt_graph
        self._prebuilt_targets = prebuilt_targets

        # ── Observation Space ──────────────────────────────────
        # Fixed-size vector: graph_emb + mol_features + target_summaries + meta
        self.observation_space = spaces.Box(
            low=-10.0,
            high=10.0,
            shape=(OBS_DIM,),
            dtype=np.float32,
        )

        # ── Action Space (Hierarchical) ───────────────────────
        # [0] target_selection, [1] stop_signal, [2:2+latent_dim] delta_z
        action_dim = 2 + latent_dim
        self.action_space = spaces.Box(
            low=-np.ones(action_dim, dtype=np.float32),
            high=np.ones(action_dim, dtype=np.float32),
        )

        # ── Internal State ─────────────────────────────────────
        self._graph: nx.DiGraph | None = None
        self._graph_embedding = np.zeros(GRAPH_EMBEDDING_DIM, dtype=np.float32)
        self._targets: list[_TargetState] = []
        self._n_targets: int = 0
        self._current_mol_features = np.zeros(MOL_FEATURE_DIM, dtype=np.float32)
        self._step_count: int = 0
        self._episode_best_score: float = -np.inf
        self._episode_rewards: list[float] = []

        # Lazy-loaded components
        self._graph_encoder: Any = None
        self._reward_learner: Any = None
        self._surrogate: Any = None
        self._genmol_model: Any = None
        self._genmol_tokenizer: Any = None

    # ------------------------------------------------------------------ #
    #  Gymnasium API                                                       #
    # ------------------------------------------------------------------ #

    def reset(
        self,
        *,
        seed: int | None = None,
        options: dict[str, Any] | None = None,
    ) -> tuple[NDArray[np.floating], dict[str, Any]]:
        """Reset for a new campaign: build the graph, identify targets,
        encode with R-GCN, and initialise per-target state."""
        super().reset(seed=seed)
        self._step_count = 0
        self._episode_best_score = -np.inf
        self._episode_rewards = []

        # ── Build disease graph ────────────────────────────────
        self._graph = target_setup.get_disease_graph(
            self.disease,
            prebuilt_graph=self._prebuilt_graph,
            top_n_targets=self.top_n_targets,
        )

        # ── Identify targets ──────────────────────────────────
        target_dicts = target_setup.get_targets(
            self.disease,
            top_n_targets=self.top_n_targets,
            prebuilt_targets=self._prebuilt_targets,
        )
        self._n_targets = min(len(target_dicts), MAX_TARGETS)

        # ── Encode graph ──────────────────────────────────────
        self._graph_embedding, self._node_embeddings, self._node_order = (
            target_setup.encode_disease_graph(
                self._graph,
                get_encoder=self._get_graph_encoder,
                embedding_dim=GRAPH_EMBEDDING_DIM,
            )
        )

        # ── Initialise target states ──────────────────────────
        self._targets = []
        for i, tdict in enumerate(target_dicts[: self._n_targets]):
            ts = _TargetState(tdict, i)
            # Assign node embedding if available
            ts.z_base = self.np_random.standard_normal(self.latent_dim).astype(np.float32) * 0.5
            self._targets.append(ts)

        # ── Assign node embeddings to targets ─────────────────
        target_setup.assign_target_embeddings(
            self._targets,
            node_order=self._node_order,
            node_embeddings=self._node_embeddings,
        )

        self._current_mol_features = np.zeros(MOL_FEATURE_DIM, dtype=np.float32)

        obs = self._build_observation()
        info = self._get_info()
        return obs, info

    def step(
        self,
        action: NDArray[np.floating],
    ) -> tuple[NDArray[np.floating], float, bool, bool, dict[str, Any]]:
        """Execute one generate-screen cycle.

        Action interpretation:
            action[0] — target selector (continuous → discretised)
            action[1] — stop signal (> 0.9 = early termination)
            action[2:] — delta-z for GenMol latent space navigation
        """
        action = np.clip(action, self.action_space.low, self.action_space.high)

        # ── Parse hierarchical action ─────────────────────────
        target_idx = self._select_target(float(action[0]))
        stop_signal = float(action[1]) > 0.9
        delta_z = action[2: 2 + self.latent_dim].astype(np.float32)

        target = self._targets[target_idx]
        target.n_attempts += 1

        # ── Generate molecule ─────────────────────────────────
        z = target.z_base + delta_z * 0.3  # scale delta for stability
        smiles = self._decode_latent(z)

        # ── Screen molecule ───────────────────────────────────
        obj_scores, measurements = self._screen_molecule(smiles, target)

        # ── Compute reward ────────────────────────────────────
        state_vec = self._build_observation()
        reward = self._compute_reward(state_vec, obj_scores)

        # ── Update target state ───────────────────────────────
        composite = sum(obj_scores.values()) / max(len(obj_scores), 1)
        if composite > target.best_score:
            target.best_score = composite
            target.best_smiles = smiles
            target.best_objectives = dict(obj_scores)
            target.best_measurements = dict(measurements)

        if composite > self._episode_best_score:
            self._episode_best_score = composite

        # ── Update latent base (drift toward good regions) ────
        if composite > 0.5:
            target.z_base = 0.8 * target.z_base + 0.2 * z

        # ── Update mol features for next observation ──────────
        self._current_mol_features = screening.encode_molecule(
            smiles, obj_scores, feature_dim=MOL_FEATURE_DIM,
        )

        self._step_count += 1
        self._episode_rewards.append(reward)

        # ── Periodic surrogate recalibration ──────────────────
        if (
            self.use_surrogate
            and self._step_count % self.recalibrate_interval == 0
            and self._step_count > 0
        ):
            self._recalibrate_surrogate()

        # ── Termination ───────────────────────────────────────
        terminated = stop_signal and self._step_count >= 5  # min 5 steps
        truncated = self._step_count >= self.max_steps

        obs = self._build_observation()
        info = self._get_info()
        info["smiles"] = smiles
        info["target"] = target.gene_name
        info["objectives"] = obj_scores

        return obs, reward, terminated, truncated, info

    def evaluate_actions(
        self,
        state: NDArray[np.floating],
        actions: NDArray[np.floating],
    ) -> NDArray[np.float64]:
        """Score candidate actions against real chemistry, mutating nothing.

        A planner needs to know what an action is actually worth before
        committing to it. ``step`` cannot answer that: it advances the
        step counter, updates per-target bests, drifts ``z_base``, and
        records into the reward learner's history. This decodes and
        screens the same molecules ``step`` would and returns their
        rewards, leaving the environment exactly as it found it.

        ``_screen_molecule`` draws from ``self.np_random`` to add
        per-difficulty noise to the objective scores. That draw advances
        the environment's shared random stream -- a real mutation, even
        though it touches no counter or cache. Left alone, evaluating a
        candidate here would desynchronise the noise a later ``step()``
        draws for the same action from what it would have drawn
        otherwise. The RNG state is saved before screening and restored
        after, so this method's random consumption is invisible to the
        rest of the environment.

        ``step`` also bumps the chosen target's ``n_attempts`` *before*
        building the observation it scores the reward against, so that
        counter is baked into the state the reward learner sees. To
        agree with ``step`` this replicates the same bump on a copy of
        ``state`` while scoring each candidate, and never writes it back
        to the target.

        Parameters
        ----------
        state
            The observation the rewards are computed against.
        actions
            Array of shape ``(n, action_dim)``.

        Returns
        -------
        ndarray of shape ``(n,)``
        """
        if actions.ndim != 2:
            raise ValueError(
                f"evaluate_actions expects a 2-D action array, got shape {actions.shape}"
            )

        if self._genmol_model is None:
            self._init_genmol()

        clipped = np.clip(actions, self.action_space.low, self.action_space.high)

        target_indices = [self._select_target(float(a[0])) for a in clipped]
        latents = np.stack([
            self._targets[idx].z_base
            + clipped[i, 2: 2 + self.latent_dim].astype(np.float32) * 0.3
            for i, idx in enumerate(target_indices)
        ])

        smiles = decode_latent_batch(
            self._genmol_model, self._genmol_tokenizer, latents,
        )

        target_block_offset = GRAPH_EMBEDDING_DIM + MOL_FEATURE_DIM

        rng_state = self.np_random.bit_generator.state
        rewards = np.empty(len(clipped), dtype=np.float64)
        for i, (mol, idx) in enumerate(zip(smiles, target_indices)):
            obj_scores, _ = self._screen_molecule(mol, self._targets[idx])

            target = self._targets[idx]
            state_for_reward = state.copy()
            block_start = target_block_offset + idx * TARGET_FEATURE_DIM
            target.n_attempts += 1
            state_for_reward[block_start: block_start + TARGET_FEATURE_DIM] = (
                target.summary_features()
            )
            target.n_attempts -= 1

            rewards[i] = self._score_reward(state_for_reward, obj_scores)
        self.np_random.bit_generator.state = rng_state

        return rewards

    # ------------------------------------------------------------------ #
    #  Causal Interface (shared with toy envs)                             #
    # ------------------------------------------------------------------ #

    def get_causal_graph(self) -> nx.DiGraph:
        """Return the disease causal graph (or empty graph if not built)."""
        if self._graph is not None:
            return self._graph
        return nx.DiGraph()

    def _get_graph_encoder(self) -> Any:
        """Lazily construct and cache the R-GCN encoder (persists across resets).

        Raises straight through -- ``target_setup.encode_disease_graph``'s
        try/except is what decides whether construction failure falls back.
        """
        if self._graph_encoder is None:
            from neorx.causalbiorl.causal.graph_encoder import DiseaseGraphEncoder
            self._graph_encoder = DiseaseGraphEncoder(embedding_dim=GRAPH_EMBEDDING_DIM)
            self._graph_encoder.eval()
        return self._graph_encoder

    # ------------------------------------------------------------------ #
    #  Internal: Molecule Generation & Screening                           #
    # ------------------------------------------------------------------ #

    def _decode_latent(self, z: NDArray[np.floating]) -> str:
        """Decode a latent vector to SMILES via the trained VAE (greedy).

        See ``neorx.causalbiorl.envs.generation.decode_latent`` for why
        greedy decoding is the right default here.
        """
        if self._genmol_model is None:
            self._init_genmol()

        return decode_latent(self._genmol_model, self._genmol_tokenizer, z)

    def _init_genmol(self) -> None:
        """Load the packaged GenMol model.

        Errors propagate. A randomly initialised VAE emits plausible SMILES,
        so a silent failure here is undetectable downstream.

        The environment's latent action space *is* the model's latent
        space -- there is no padding/truncation shim reconciling the two.
        If they disagree, that is a real misconfiguration and must fail
        loudly here rather than surface later as a shape-mismatch error
        deep inside ``decode()``.
        """
        model, tokenizer = load_pretrained()

        if self.latent_dim != model.latent_dim:
            raise ValueError(
                f"latent_dim={self.latent_dim} does not match the shipped "
                f"GenMol model's latent dimension "
                f"({model.latent_dim}). The environment's "
                f"latent action space must match the decoder it drives -- "
                f"construct the environment with "
                f"latent_dim={model.latent_dim}, or omit the "
                f"argument to use the default."
            )

        # Only commit to instance state once validation has passed, so a
        # failed check leaves self._genmol_model as None and a retry (e.g.
        # the next env.step()) re-validates instead of skipping the guard.
        self._genmol_model, self._genmol_tokenizer = model, tokenizer

    def _screen_molecule(
        self,
        smiles: str,
        target: _TargetState,
    ) -> tuple[dict[str, float], dict[str, float | None]]:
        """Screen a molecule; return its normalised scores and raw measurements.

        Thin orchestration over ``screening.screen_molecule``: owns the
        surrogate's lazy construction and the per-difficulty noise draw
        (which consumes ``self.np_random`` -- a real mutation). The noise
        perturbs the scores only; the measurements stay as measured.
        """
        if self.use_surrogate and self._surrogate is None:
            try:
                from neorx.causalbiorl.causal.surrogate_docker import SurrogateDockingModel
                self._surrogate = SurrogateDockingModel()
            except Exception:
                pass  # screening.measure_binding treats a missing surrogate as a failed lookup

        scores, measurements = screening.screen_molecule(
            smiles, target,
            use_surrogate=self.use_surrogate,
            surrogate=self._surrogate,
        )

        # Add noise for difficulty
        if self._noise_std > 0:
            for key in scores:
                scores[key] = float(np.clip(
                    scores[key] + self.np_random.normal(0, self._noise_std),
                    0.0, 1.0,
                ))

        return scores, measurements

    def _recalibrate_surrogate(self) -> None:
        """Run real docking on recent molecules to recalibrate the surrogate."""
        screening.recalibrate_surrogate(self._targets, self._surrogate)

    # ------------------------------------------------------------------ #
    #  Internal: Reward                                                    #
    # ------------------------------------------------------------------ #

    def _ensure_reward_learner(self) -> None:
        """Lazily construct the reward learner, once, and cache it.

        A None learner (construction failed) is treated by ``reward.py``
        exactly like one whose call raised -- same fallback either way.
        """
        if self._reward_learner is None:
            try:
                from neorx.causalbiorl.causal.reward_learner import AdaptiveRewardLearner
                self._reward_learner = AdaptiveRewardLearner(state_dim=OBS_DIM)
            except Exception:
                pass

    def _compute_reward(
        self,
        state: NDArray[np.floating],
        obj_scores: dict[str, float],
    ) -> float:
        """Compute adaptively-weighted reward, recording it into the learner."""
        self._ensure_reward_learner()
        return reward_scoring.compute_reward(state, obj_scores, learner=self._reward_learner)

    def _score_reward(
        self,
        state: NDArray[np.floating],
        obj_scores: dict[str, float],
    ) -> float:
        """The reward for these objective scores, recording nothing."""
        self._ensure_reward_learner()
        return reward_scoring.score_reward(state, obj_scores, learner=self._reward_learner)

    # ------------------------------------------------------------------ #
    #  Internal: Observation, Target Selection & Reporting                 #
    # ------------------------------------------------------------------ #

    def _build_observation(self) -> NDArray[np.floating]:
        """Build the full observation vector."""
        return episode.build_observation(
            graph_embedding=self._graph_embedding,
            mol_features=self._current_mol_features,
            targets=self._targets,
            step_count=self._step_count,
            n_targets=self._n_targets,
            max_steps=self.max_steps,
            episode_best_score=self._episode_best_score,
            use_surrogate=self.use_surrogate,
            obs_dim=OBS_DIM,
            graph_embedding_dim=GRAPH_EMBEDDING_DIM,
            mol_feature_dim=MOL_FEATURE_DIM,
            target_feature_dim=TARGET_FEATURE_DIM,
            max_targets=MAX_TARGETS,
        )

    def _select_target(self, action_value: float) -> int:
        """Convert continuous action to discrete target index."""
        if self._n_targets == 0:
            return 0

        # Map [-1, 1] → [0, n_targets-1]
        normalised = (action_value + 1.0) / 2.0  # → [0, 1]
        idx = int(normalised * self._n_targets)
        return max(0, min(idx, self._n_targets - 1))

    def _get_info(self) -> dict[str, Any]:
        """Return episode info dict."""
        return episode.build_info(
            targets=self._targets,
            step_count=self._step_count,
            n_targets=self._n_targets,
            max_steps=self.max_steps,
            episode_best_score=self._episode_best_score,
        )

    def render(self) -> None:
        """Print current episode status."""
        if self.render_mode == "human":
            episode.render_status(self.disease, self.max_steps, self._get_info())

    def close(self) -> None:
        """Clean up resources."""
        self._graph = None
        self._graph_encoder = None
        self._surrogate = None
        self._genmol_model = None
        self._genmol_tokenizer = None

reset

reset(*, seed: int | None = None, options: dict[str, Any] | None = None) -> tuple[NDArray[np.floating], dict[str, Any]]

Reset for a new campaign: build the graph, identify targets, encode with R-GCN, and initialise per-target state.

Source code in src/neorx/causalbiorl/envs/drug_discovery.py
def reset(
    self,
    *,
    seed: int | None = None,
    options: dict[str, Any] | None = None,
) -> tuple[NDArray[np.floating], dict[str, Any]]:
    """Reset for a new campaign: build the graph, identify targets,
    encode with R-GCN, and initialise per-target state."""
    super().reset(seed=seed)
    self._step_count = 0
    self._episode_best_score = -np.inf
    self._episode_rewards = []

    # ── Build disease graph ────────────────────────────────
    self._graph = target_setup.get_disease_graph(
        self.disease,
        prebuilt_graph=self._prebuilt_graph,
        top_n_targets=self.top_n_targets,
    )

    # ── Identify targets ──────────────────────────────────
    target_dicts = target_setup.get_targets(
        self.disease,
        top_n_targets=self.top_n_targets,
        prebuilt_targets=self._prebuilt_targets,
    )
    self._n_targets = min(len(target_dicts), MAX_TARGETS)

    # ── Encode graph ──────────────────────────────────────
    self._graph_embedding, self._node_embeddings, self._node_order = (
        target_setup.encode_disease_graph(
            self._graph,
            get_encoder=self._get_graph_encoder,
            embedding_dim=GRAPH_EMBEDDING_DIM,
        )
    )

    # ── Initialise target states ──────────────────────────
    self._targets = []
    for i, tdict in enumerate(target_dicts[: self._n_targets]):
        ts = _TargetState(tdict, i)
        # Assign node embedding if available
        ts.z_base = self.np_random.standard_normal(self.latent_dim).astype(np.float32) * 0.5
        self._targets.append(ts)

    # ── Assign node embeddings to targets ─────────────────
    target_setup.assign_target_embeddings(
        self._targets,
        node_order=self._node_order,
        node_embeddings=self._node_embeddings,
    )

    self._current_mol_features = np.zeros(MOL_FEATURE_DIM, dtype=np.float32)

    obs = self._build_observation()
    info = self._get_info()
    return obs, info

step

step(action: NDArray[floating]) -> tuple[NDArray[np.floating], float, bool, bool, dict[str, Any]]

Execute one generate-screen cycle.

Action interpretation: action[0] — target selector (continuous → discretised) action[1] — stop signal (> 0.9 = early termination) action[2:] — delta-z for GenMol latent space navigation

Source code in src/neorx/causalbiorl/envs/drug_discovery.py
def step(
    self,
    action: NDArray[np.floating],
) -> tuple[NDArray[np.floating], float, bool, bool, dict[str, Any]]:
    """Execute one generate-screen cycle.

    Action interpretation:
        action[0] — target selector (continuous → discretised)
        action[1] — stop signal (> 0.9 = early termination)
        action[2:] — delta-z for GenMol latent space navigation
    """
    action = np.clip(action, self.action_space.low, self.action_space.high)

    # ── Parse hierarchical action ─────────────────────────
    target_idx = self._select_target(float(action[0]))
    stop_signal = float(action[1]) > 0.9
    delta_z = action[2: 2 + self.latent_dim].astype(np.float32)

    target = self._targets[target_idx]
    target.n_attempts += 1

    # ── Generate molecule ─────────────────────────────────
    z = target.z_base + delta_z * 0.3  # scale delta for stability
    smiles = self._decode_latent(z)

    # ── Screen molecule ───────────────────────────────────
    obj_scores, measurements = self._screen_molecule(smiles, target)

    # ── Compute reward ────────────────────────────────────
    state_vec = self._build_observation()
    reward = self._compute_reward(state_vec, obj_scores)

    # ── Update target state ───────────────────────────────
    composite = sum(obj_scores.values()) / max(len(obj_scores), 1)
    if composite > target.best_score:
        target.best_score = composite
        target.best_smiles = smiles
        target.best_objectives = dict(obj_scores)
        target.best_measurements = dict(measurements)

    if composite > self._episode_best_score:
        self._episode_best_score = composite

    # ── Update latent base (drift toward good regions) ────
    if composite > 0.5:
        target.z_base = 0.8 * target.z_base + 0.2 * z

    # ── Update mol features for next observation ──────────
    self._current_mol_features = screening.encode_molecule(
        smiles, obj_scores, feature_dim=MOL_FEATURE_DIM,
    )

    self._step_count += 1
    self._episode_rewards.append(reward)

    # ── Periodic surrogate recalibration ──────────────────
    if (
        self.use_surrogate
        and self._step_count % self.recalibrate_interval == 0
        and self._step_count > 0
    ):
        self._recalibrate_surrogate()

    # ── Termination ───────────────────────────────────────
    terminated = stop_signal and self._step_count >= 5  # min 5 steps
    truncated = self._step_count >= self.max_steps

    obs = self._build_observation()
    info = self._get_info()
    info["smiles"] = smiles
    info["target"] = target.gene_name
    info["objectives"] = obj_scores

    return obs, reward, terminated, truncated, info

evaluate_actions

evaluate_actions(state: NDArray[floating], actions: NDArray[floating]) -> NDArray[np.float64]

Score candidate actions against real chemistry, mutating nothing.

A planner needs to know what an action is actually worth before committing to it. step cannot answer that: it advances the step counter, updates per-target bests, drifts z_base, and records into the reward learner's history. This decodes and screens the same molecules step would and returns their rewards, leaving the environment exactly as it found it.

_screen_molecule draws from self.np_random to add per-difficulty noise to the objective scores. That draw advances the environment's shared random stream -- a real mutation, even though it touches no counter or cache. Left alone, evaluating a candidate here would desynchronise the noise a later step() draws for the same action from what it would have drawn otherwise. The RNG state is saved before screening and restored after, so this method's random consumption is invisible to the rest of the environment.

step also bumps the chosen target's n_attempts before building the observation it scores the reward against, so that counter is baked into the state the reward learner sees. To agree with step this replicates the same bump on a copy of state while scoring each candidate, and never writes it back to the target.

Parameters:

Name Type Description Default
state NDArray[floating]

The observation the rewards are computed against.

required
actions NDArray[floating]

Array of shape (n, action_dim).

required

Returns:

Type Description
ndarray of shape ``(n,)``
Source code in src/neorx/causalbiorl/envs/drug_discovery.py
def evaluate_actions(
    self,
    state: NDArray[np.floating],
    actions: NDArray[np.floating],
) -> NDArray[np.float64]:
    """Score candidate actions against real chemistry, mutating nothing.

    A planner needs to know what an action is actually worth before
    committing to it. ``step`` cannot answer that: it advances the
    step counter, updates per-target bests, drifts ``z_base``, and
    records into the reward learner's history. This decodes and
    screens the same molecules ``step`` would and returns their
    rewards, leaving the environment exactly as it found it.

    ``_screen_molecule`` draws from ``self.np_random`` to add
    per-difficulty noise to the objective scores. That draw advances
    the environment's shared random stream -- a real mutation, even
    though it touches no counter or cache. Left alone, evaluating a
    candidate here would desynchronise the noise a later ``step()``
    draws for the same action from what it would have drawn
    otherwise. The RNG state is saved before screening and restored
    after, so this method's random consumption is invisible to the
    rest of the environment.

    ``step`` also bumps the chosen target's ``n_attempts`` *before*
    building the observation it scores the reward against, so that
    counter is baked into the state the reward learner sees. To
    agree with ``step`` this replicates the same bump on a copy of
    ``state`` while scoring each candidate, and never writes it back
    to the target.

    Parameters
    ----------
    state
        The observation the rewards are computed against.
    actions
        Array of shape ``(n, action_dim)``.

    Returns
    -------
    ndarray of shape ``(n,)``
    """
    if actions.ndim != 2:
        raise ValueError(
            f"evaluate_actions expects a 2-D action array, got shape {actions.shape}"
        )

    if self._genmol_model is None:
        self._init_genmol()

    clipped = np.clip(actions, self.action_space.low, self.action_space.high)

    target_indices = [self._select_target(float(a[0])) for a in clipped]
    latents = np.stack([
        self._targets[idx].z_base
        + clipped[i, 2: 2 + self.latent_dim].astype(np.float32) * 0.3
        for i, idx in enumerate(target_indices)
    ])

    smiles = decode_latent_batch(
        self._genmol_model, self._genmol_tokenizer, latents,
    )

    target_block_offset = GRAPH_EMBEDDING_DIM + MOL_FEATURE_DIM

    rng_state = self.np_random.bit_generator.state
    rewards = np.empty(len(clipped), dtype=np.float64)
    for i, (mol, idx) in enumerate(zip(smiles, target_indices)):
        obj_scores, _ = self._screen_molecule(mol, self._targets[idx])

        target = self._targets[idx]
        state_for_reward = state.copy()
        block_start = target_block_offset + idx * TARGET_FEATURE_DIM
        target.n_attempts += 1
        state_for_reward[block_start: block_start + TARGET_FEATURE_DIM] = (
            target.summary_features()
        )
        target.n_attempts -= 1

        rewards[i] = self._score_reward(state_for_reward, obj_scores)
    self.np_random.bit_generator.state = rng_state

    return rewards

get_causal_graph

get_causal_graph() -> nx.DiGraph

Return the disease causal graph (or empty graph if not built).

Source code in src/neorx/causalbiorl/envs/drug_discovery.py
def get_causal_graph(self) -> nx.DiGraph:
    """Return the disease causal graph (or empty graph if not built)."""
    if self._graph is not None:
        return self._graph
    return nx.DiGraph()

render

render() -> None

Print current episode status.

Source code in src/neorx/causalbiorl/envs/drug_discovery.py
def render(self) -> None:
    """Print current episode status."""
    if self.render_mode == "human":
        episode.render_status(self.disease, self.max_steps, self._get_info())

close

close() -> None

Clean up resources.

Source code in src/neorx/causalbiorl/envs/drug_discovery.py
def close(self) -> None:
    """Clean up resources."""
    self._graph = None
    self._graph_encoder = None
    self._surrogate = None
    self._genmol_model = None
    self._genmol_tokenizer = None

Novel causal RL agent — uses structural causal models as world models.

Architecture: 1. Causal Discovery — learns the causal graph from observed transitions (neural or PC algorithm). 2. Causal World Model — fits an SCM to the discovered graph. 3. Causal Planner — selects actions via do-calculus on the SCM. 4. Model-Based RL loop — collect → discover → fit SCM → plan → act.

The agent maintains a replay buffer of transitions and periodically re-discovers the causal structure and re-fits the SCM.

CausalAgent

Causal RL agent with SCM-based world model.

Parameters:

Name Type Description Default
env Env

The environment to act in.

required
discovery_method ``"pc"`` | ``"neural"``

Causal discovery backend.

'neural'
mechanism ``"linear"`` | ``"neural"``

SCM edge parameterisation.

'neural'
planning_method ``"grid"`` | ``"cem"``

Action selection strategy.

'cem'
warmup_steps int

Collect this many random transitions before first discovery.

500
rediscover_interval int

Re-run discovery every N episodes.

20
refit_interval int

Re-fit SCM every N episodes.

5
buffer_capacity int

Replay buffer size.

50000
planning_samples int

Number of candidate actions evaluated per step.

200
planning_horizon int

Multi-step look-ahead depth.

3
seed int | None

Random seed.

None
Source code in src/neorx/causalbiorl/agents/causal_agent.py
class CausalAgent:
    """Causal RL agent with SCM-based world model.

    Parameters
    ----------
    env : gym.Env
        The environment to act in.
    discovery_method : ``"pc"`` | ``"neural"``
        Causal discovery backend.
    mechanism : ``"linear"`` | ``"neural"``
        SCM edge parameterisation.
    planning_method : ``"grid"`` | ``"cem"``
        Action selection strategy.
    warmup_steps : int
        Collect this many random transitions before first discovery.
    rediscover_interval : int
        Re-run discovery every N episodes.
    refit_interval : int
        Re-fit SCM every N episodes.
    buffer_capacity : int
        Replay buffer size.
    planning_samples : int
        Number of candidate actions evaluated per step.
    planning_horizon : int
        Multi-step look-ahead depth.
    seed : int | None
        Random seed.
    """

    def __init__(
        self,
        env: gym.Env,
        discovery_method: Literal["pc", "neural"] = "neural",
        mechanism: Literal["linear", "neural"] = "neural",
        planning_method: Literal["grid", "cem"] = "cem",
        warmup_steps: int = 500,
        rediscover_interval: int = 20,
        refit_interval: int = 5,
        buffer_capacity: int = 50_000,
        planning_samples: int = 200,
        planning_horizon: int = 3,
        seed: int | None = None,
    ) -> None:
        self.env = env
        self.warmup_steps = warmup_steps
        self.rediscover_interval = rediscover_interval
        self.refit_interval = refit_interval
        self.planning_samples = planning_samples
        self.planning_horizon = planning_horizon

        self.state_dim = int(np.prod(env.observation_space.shape))  # type: ignore[union-attr]
        self.action_dim = int(np.prod(env.action_space.shape))  # type: ignore[union-attr]

        self.rng = np.random.default_rng(seed)
        self.buffer = TransitionBuffer(capacity=buffer_capacity)
        self.discovery = CausalDiscovery(method=discovery_method)

        self._mechanism_type = mechanism
        self._planning_method = planning_method
        self._scm: StructuralCausalModel | None = None
        self._planner: CausalPlanner | None = None
        self._hierarchical_planner: HierarchicalPlanner | None = None
        self._reward_model = RewardPredictor(self.state_dim, self.action_dim)
        # Assigned here, not in train(): pipeline.py calls
        # init_hierarchical_planner() before train(), and
        # HierarchicalPlanner captures this value rather than a
        # reference. Leaving it None until train() meant the planner's
        # CEM never ran in the end-to-end pipeline.
        self._reward_fn: Callable[..., float] = self._reward_model.predict

        # Detect hierarchical mode (DrugDiscovery-v0)
        self._hierarchical_mode = self.action_dim > 10  # heuristic: latent_dim > 10

        # Metrics
        self.episode_rewards: list[float] = []
        self.episode_lengths: list[int] = []

    # ------------------------------------------------------------------ #
    #  Public API                                                          #
    # ------------------------------------------------------------------ #

    def train(
        self,
        n_episodes: int = 500,
        reward_fn: Callable[[NDArray[np.floating], NDArray[np.floating]], float] | None = None,
        verbose: bool = True,
    ) -> dict[str, Any]:
        """Run the full causal model-based RL training loop.

        Parameters
        ----------
        n_episodes : int
            Total training episodes.
        reward_fn : callable | None
            External reward function ``(state, action) → float``.
            If ``None``, the environment reward is used for planning.
        verbose : bool
            Show progress bar.

        Returns
        -------
        dict with training metrics.
        """
        if reward_fn is not None:
            self._reward_fn = reward_fn
            if self._hierarchical_planner is not None:
                self._hierarchical_planner.reward_fn = reward_fn
            if self._planner is not None:
                self._planner.reward_fn = reward_fn

        total_steps = 0
        pbar = tqdm(range(n_episodes), desc="CausalAgent", disable=not verbose)

        for ep in pbar:
            state, _ = self.env.reset(seed=int(self.rng.integers(0, 2**31)))
            ep_reward = 0.0
            ep_len = 0

            terminated = truncated = False
            while not (terminated or truncated):
                # Choose action
                if total_steps < self.warmup_steps or self._planner is None:
                    if self._hierarchical_mode and self._hierarchical_planner is not None:
                        action = self._hierarchical_planner.plan(state, rng=self.rng)
                    else:
                        action = self.env.action_space.sample()
                else:
                    if self._hierarchical_mode and self._hierarchical_planner is not None:
                        action = self._hierarchical_planner.plan(state, rng=self.rng)
                    else:
                        action = self._planner.plan(state, rng=self.rng)

                next_state, reward, terminated, truncated, info = self.env.step(action)
                self.buffer.add(state, action, float(reward), next_state)

                # Update hierarchical planner with reward
                if self._hierarchical_mode and self._hierarchical_planner is not None:
                    target_idx = self._parse_target_idx(action)
                    self._hierarchical_planner.update(target_idx, float(reward))

                state = next_state
                ep_reward += float(reward)
                ep_len += 1
                total_steps += 1

            self.episode_rewards.append(ep_reward)
            self.episode_lengths.append(ep_len)

            # Periodic causal discovery + SCM fitting
            if len(self.buffer) >= self.warmup_steps:
                if ep % self.rediscover_interval == 0:
                    self._run_discovery()
                if ep % self.refit_interval == 0 and self._scm is not None:
                    self._fit_scm()

            if verbose and ep % 10 == 0:
                recent = self.episode_rewards[-10:]
                pbar.set_postfix(
                    reward=f"{np.mean(recent):.2f}",
                    buf=len(self.buffer),
                    scm="✓" if self._scm else "✗",
                )

        return {
            "episode_rewards": self.episode_rewards,
            "episode_lengths": self.episode_lengths,
            "total_steps": total_steps,
        }

    def act(self, state: NDArray[np.floating]) -> NDArray[np.floating]:
        """Select a single action for the given state."""
        if self._planner is None:
            return self.env.action_space.sample()
        return self._planner.plan(state, rng=self.rng)

    def get_learned_graph(self):
        """Return the most recently learned causal graph."""
        if self._scm is not None:
            return self._scm.graph
        return None

    def init_hierarchical_planner(
        self,
        n_targets: int = 5,
        latent_dim: int = 128,
    ) -> None:
        """Initialise the hierarchical planner for drug discovery.

        Call this before training if the environment is
        ``DrugDiscovery-v0``.  The planner uses UCB for target
        selection and CEM for molecule generation.
        """
        self._hierarchical_mode = True
        self._hierarchical_planner = HierarchicalPlanner(
            scm=self._scm,
            reward_fn=self._reward_fn,
            evaluate_actions=getattr(self.env, "evaluate_actions", None),
            n_targets=n_targets,
            latent_dim=latent_dim,
        )

    def _parse_target_idx(self, action: NDArray[np.floating]) -> int:
        """Extract target index from hierarchical action."""
        if len(action) < 2:
            return 0
        n_targets = getattr(self, "_n_targets", 5)
        normalised = (float(action[0]) + 1.0) / 2.0
        return max(0, min(int(normalised * n_targets), n_targets - 1))

    # ------------------------------------------------------------------ #
    #  Internals                                                           #
    # ------------------------------------------------------------------ #

    def _run_discovery(self) -> None:
        states, actions, next_states = self.buffer.as_arrays()
        node_names = (
            [f"s{i}" for i in range(self.state_dim)]
            + [f"a{i}" for i in range(self.action_dim)]
            + [f"s'{i}" for i in range(self.state_dim)]
        )
        graph = self.discovery.discover(states, actions, next_states, node_names)
        self._build_scm(graph)

    def _build_scm(self, graph) -> None:
        """Construct an SCM from the discovered graph and fit it."""
        import networkx as nx

        # Map discovery node names to a clean SCM graph
        scm_graph = nx.DiGraph()
        all_names = (
            [f"s{i}" for i in range(self.state_dim)]
            + [f"a{i}" for i in range(self.action_dim)]
        )
        scm_graph.add_nodes_from(all_names)

        for u, v in graph.edges():
            # Only keep edges among state/action nodes
            if u in all_names and v.startswith("s"):
                # Map s'i back to si for SCM prediction
                target = v.replace("'", "")
                if target in all_names:
                    scm_graph.add_edge(u, target)

        self._scm = StructuralCausalModel(
            graph=scm_graph,
            state_dim=self.state_dim,
            action_dim=self.action_dim,
            mechanism=self._mechanism_type,
        )
        self._fit_scm()

    def _fit_scm(self) -> None:
        if self._scm is None:
            return
        states, actions, next_states = self.buffer.as_arrays()
        self._scm.fit(states, actions, next_states)

        # Fit reward predictor from buffered environment rewards
        r_states, r_actions, r_rewards = self.buffer.reward_arrays()
        self._reward_model.fit(r_states, r_actions, r_rewards)

        # Rebuild planner with updated SCM + learned reward
        assert self._reward_fn is not None
        self._planner = CausalPlanner(
            scm=self._scm,
            reward_fn=self._reward_fn,
            action_dim=self.action_dim,
            method=self._planning_method,
            n_samples=self.planning_samples,
            horizon=self.planning_horizon,
        )

    @staticmethod
    def _default_reward_fn(
        state: NDArray[np.floating], action: NDArray[np.floating]
    ) -> float:
        """Legacy fallback reward: negative L2 norm of state.

        Deprecated — the agent now uses :class:`RewardPredictor` to
        learn the environment's actual reward function from buffered
        transitions.  This method is kept only for backward compat
        if ``reward_fn`` is explicitly passed as ``_default_reward_fn``.
        """
        return -float(np.linalg.norm(state))

train

train(n_episodes: int = 500, reward_fn: Callable[[NDArray[floating], NDArray[floating]], float] | None = None, verbose: bool = True) -> dict[str, Any]

Run the full causal model-based RL training loop.

Parameters:

Name Type Description Default
n_episodes int

Total training episodes.

500
reward_fn callable | None

External reward function (state, action) → float. If None, the environment reward is used for planning.

None
verbose bool

Show progress bar.

True

Returns:

Type Description
dict with training metrics.
Source code in src/neorx/causalbiorl/agents/causal_agent.py
def train(
    self,
    n_episodes: int = 500,
    reward_fn: Callable[[NDArray[np.floating], NDArray[np.floating]], float] | None = None,
    verbose: bool = True,
) -> dict[str, Any]:
    """Run the full causal model-based RL training loop.

    Parameters
    ----------
    n_episodes : int
        Total training episodes.
    reward_fn : callable | None
        External reward function ``(state, action) → float``.
        If ``None``, the environment reward is used for planning.
    verbose : bool
        Show progress bar.

    Returns
    -------
    dict with training metrics.
    """
    if reward_fn is not None:
        self._reward_fn = reward_fn
        if self._hierarchical_planner is not None:
            self._hierarchical_planner.reward_fn = reward_fn
        if self._planner is not None:
            self._planner.reward_fn = reward_fn

    total_steps = 0
    pbar = tqdm(range(n_episodes), desc="CausalAgent", disable=not verbose)

    for ep in pbar:
        state, _ = self.env.reset(seed=int(self.rng.integers(0, 2**31)))
        ep_reward = 0.0
        ep_len = 0

        terminated = truncated = False
        while not (terminated or truncated):
            # Choose action
            if total_steps < self.warmup_steps or self._planner is None:
                if self._hierarchical_mode and self._hierarchical_planner is not None:
                    action = self._hierarchical_planner.plan(state, rng=self.rng)
                else:
                    action = self.env.action_space.sample()
            else:
                if self._hierarchical_mode and self._hierarchical_planner is not None:
                    action = self._hierarchical_planner.plan(state, rng=self.rng)
                else:
                    action = self._planner.plan(state, rng=self.rng)

            next_state, reward, terminated, truncated, info = self.env.step(action)
            self.buffer.add(state, action, float(reward), next_state)

            # Update hierarchical planner with reward
            if self._hierarchical_mode and self._hierarchical_planner is not None:
                target_idx = self._parse_target_idx(action)
                self._hierarchical_planner.update(target_idx, float(reward))

            state = next_state
            ep_reward += float(reward)
            ep_len += 1
            total_steps += 1

        self.episode_rewards.append(ep_reward)
        self.episode_lengths.append(ep_len)

        # Periodic causal discovery + SCM fitting
        if len(self.buffer) >= self.warmup_steps:
            if ep % self.rediscover_interval == 0:
                self._run_discovery()
            if ep % self.refit_interval == 0 and self._scm is not None:
                self._fit_scm()

        if verbose and ep % 10 == 0:
            recent = self.episode_rewards[-10:]
            pbar.set_postfix(
                reward=f"{np.mean(recent):.2f}",
                buf=len(self.buffer),
                scm="✓" if self._scm else "✗",
            )

    return {
        "episode_rewards": self.episode_rewards,
        "episode_lengths": self.episode_lengths,
        "total_steps": total_steps,
    }

act

act(state: NDArray[floating]) -> NDArray[np.floating]

Select a single action for the given state.

Source code in src/neorx/causalbiorl/agents/causal_agent.py
def act(self, state: NDArray[np.floating]) -> NDArray[np.floating]:
    """Select a single action for the given state."""
    if self._planner is None:
        return self.env.action_space.sample()
    return self._planner.plan(state, rng=self.rng)

get_learned_graph

get_learned_graph()

Return the most recently learned causal graph.

Source code in src/neorx/causalbiorl/agents/causal_agent.py
def get_learned_graph(self):
    """Return the most recently learned causal graph."""
    if self._scm is not None:
        return self._scm.graph
    return None

init_hierarchical_planner

init_hierarchical_planner(n_targets: int = 5, latent_dim: int = 128) -> None

Initialise the hierarchical planner for drug discovery.

Call this before training if the environment is DrugDiscovery-v0. The planner uses UCB for target selection and CEM for molecule generation.

Source code in src/neorx/causalbiorl/agents/causal_agent.py
def init_hierarchical_planner(
    self,
    n_targets: int = 5,
    latent_dim: int = 128,
) -> None:
    """Initialise the hierarchical planner for drug discovery.

    Call this before training if the environment is
    ``DrugDiscovery-v0``.  The planner uses UCB for target
    selection and CEM for molecule generation.
    """
    self._hierarchical_mode = True
    self._hierarchical_planner = HierarchicalPlanner(
        scm=self._scm,
        reward_fn=self._reward_fn,
        evaluate_actions=getattr(self.env, "evaluate_actions", None),
        n_targets=n_targets,
        latent_dim=latent_dim,
    )

neorx.mirrorfold

Mirror-image proteins. See MirrorFold.

Sequence Mirror — L → D Transformation

Converts a natural (L-amino acid) protein sequence into its mirror-image (D-amino acid) counterpart, and generates D-amino acid SMILES representations.

Why reverse the sequence?

All modern protein structure predictors (ESMFold, AlphaFold, RoseTTAFold) were trained exclusively on L-protein structures. They cannot directly predict D-protein folds.

However, a beautiful symmetry comes to the rescue:

A D-protein made from sequence ``ABCDE`` folds into the
**mirror image** of the L-protein made from the **reversed**
sequence ``EDCBA``.

This is because:

  1. D-amino acids have inverted backbone φ/ψ torsion angles compared to L-amino acids.
  2. Reversing the sequence direction swaps N→C and C→N termini, which combined with the chirality inversion, produces a structure that is the mirror image of the original L-fold.
  3. After prediction of the reversed sequence, a coordinate reflection (x → −x) yields the D-protein structure.

This "reverse-and-reflect" proxy is an approximation. It works well for globular proteins with defined folds but is less reliable for intrinsically disordered regions or proteins whose folding depends heavily on co-translational effects.

Reference: Milton et al. (1992) "Total Chemical Synthesis of a D-Enzyme: The Enantiomers of HIV-1 Protease Show Demonstration of Reciprocal Chiral Substrate Specificity."

D-amino acid SMILES

Each of the 20 standard amino acids has an L and D form. They differ only in the stereochemistry at the α-carbon:

  • L-form: [C@@H] at the α-carbon (S-configuration, except Cys)
  • D-form: [C@H] at the α-carbon (R-configuration, except Cys)

Glycine has no stereocenter (the α-carbon has two hydrogens). Isoleucine and threonine have an additional stereocenter on the side chain, which is also inverted in the D-form (full mirror).

mirror_sequence

mirror_sequence(sequence: str) -> str

Generate the D-protein proxy sequence by reversing.

The reversed sequence, when folded by an L-protein predictor, approximates the mirror-image fold of the D-protein.

Parameters:

Name Type Description Default
sequence str

L-protein amino acid sequence (one-letter codes).

required

Returns:

Type Description
str

Reversed sequence (proxy for D-protein prediction).

Raises:

Type Description
ValueError

If the sequence contains non-standard amino acids.

Examples:

>>> mirror_sequence("MKFLILF")
'FLILKFM'
>>> mirror_sequence("YGGFL")
'LFGGY'
Source code in src/neorx/mirrorfold/mirror.py
def mirror_sequence(sequence: str) -> str:
    """Generate the D-protein proxy sequence by reversing.

    The reversed sequence, when folded by an L-protein predictor,
    approximates the mirror-image fold of the D-protein.

    Parameters
    ----------
    sequence : str
        L-protein amino acid sequence (one-letter codes).

    Returns
    -------
    str
        Reversed sequence (proxy for D-protein prediction).

    Raises
    ------
    ValueError
        If the sequence contains non-standard amino acids.

    Examples
    --------
    >>> mirror_sequence("MKFLILF")
    'FLILKFM'
    >>> mirror_sequence("YGGFL")
    'LFGGY'
    """
    seq = sequence.upper().strip()
    if not is_valid_sequence(seq):
        invalid = [c for c in seq if c not in STANDARD_AA]
        raise ValueError(
            f"Non-standard amino acids found: {set(invalid)}. "
            f"Only standard 20 amino acids are supported: {sorted(STANDARD_AA)}"
        )
    return seq[::-1]

is_valid_sequence

is_valid_sequence(sequence: str) -> bool

Check whether a string is a valid protein sequence.

Parameters:

Name Type Description Default
sequence str

Amino acid sequence in one-letter codes.

required

Returns:

Type Description
bool

True if every character is a standard amino acid.

Source code in src/neorx/mirrorfold/mirror.py
def is_valid_sequence(sequence: str) -> bool:
    """Check whether a string is a valid protein sequence.

    Parameters
    ----------
    sequence : str
        Amino acid sequence in one-letter codes.

    Returns
    -------
    bool
        ``True`` if every character is a standard amino acid.
    """
    return bool(sequence) and all(c in STANDARD_AA for c in sequence.upper())

reflect_coordinates

reflect_coordinates(pdb_string: str, axis: str = 'x') -> str

Reflect PDB coordinates across a plane to get the mirror image.

After predicting a structure from the reversed sequence using an L-protein predictor, the resulting coordinates represent an L-protein fold. To obtain the actual D-protein coordinates, we reflect across one axis (e.g., x → −x).

This is mathematically equivalent to multiplying the coordinate matrix by a reflection matrix with determinant −1.

Parameters:

Name Type Description Default
pdb_string str

PDB-format string.

required
axis str

Which axis to negate: "x", "y", or "z".

'x'

Returns:

Type Description
str

PDB string with reflected coordinates.

Source code in src/neorx/mirrorfold/mirror.py
def reflect_coordinates(
    pdb_string: str,
    axis: str = "x",
) -> str:
    """Reflect PDB coordinates across a plane to get the mirror image.

    After predicting a structure from the reversed sequence using
    an L-protein predictor, the resulting coordinates represent an
    L-protein fold.  To obtain the actual D-protein coordinates,
    we reflect across one axis (e.g., x → −x).

    This is mathematically equivalent to multiplying the coordinate
    matrix by a reflection matrix with determinant −1.

    Parameters
    ----------
    pdb_string : str
        PDB-format string.
    axis : str
        Which axis to negate: ``"x"``, ``"y"``, or ``"z"``.

    Returns
    -------
    str
        PDB string with reflected coordinates.
    """
    axis_idx = {"x": 0, "y": 1, "z": 2}[axis.lower()]
    lines: list[str] = []

    for line in pdb_string.splitlines():
        if line.startswith(("ATOM", "HETATM")) and len(line) >= 54:
            # PDB format: x=30-38, y=38-46, z=46-54
            coords = [
                float(line[30:38]),
                float(line[38:46]),
                float(line[46:54]),
            ]
            coords[axis_idx] = -coords[axis_idx]
            new_line = (
                line[:30]
                + f"{coords[0]:8.3f}{coords[1]:8.3f}{coords[2]:8.3f}"
                + line[54:]
            )
            lines.append(new_line)
        else:
            lines.append(line)

    return "\n".join(lines)

get_l_smiles

get_l_smiles(residue: str) -> Optional[str]

Get the SMILES string for an L-amino acid.

Parameters:

Name Type Description Default
residue str

One-letter amino acid code.

required

Returns:

Type Description
str or None

SMILES with correct L-stereochemistry, or None if the residue code is not recognised.

Source code in src/neorx/mirrorfold/mirror.py
def get_l_smiles(residue: str) -> Optional[str]:
    """Get the SMILES string for an L-amino acid.

    Parameters
    ----------
    residue : str
        One-letter amino acid code.

    Returns
    -------
    str or None
        SMILES with correct L-stereochemistry, or ``None`` if
        the residue code is not recognised.
    """
    return L_AMINO_ACID_SMILES.get(residue.upper())

get_d_smiles

get_d_smiles(residue: str) -> Optional[str]

Get the SMILES string for a D-amino acid.

The D-form is the mirror image — all stereocentres are inverted compared to the L-form.

Parameters:

Name Type Description Default
residue str

One-letter amino acid code.

required

Returns:

Type Description
str or None

SMILES with correct D-stereochemistry, or None if the residue code is not recognised.

Source code in src/neorx/mirrorfold/mirror.py
def get_d_smiles(residue: str) -> Optional[str]:
    """Get the SMILES string for a D-amino acid.

    The D-form is the mirror image — all stereocentres are
    inverted compared to the L-form.

    Parameters
    ----------
    residue : str
        One-letter amino acid code.

    Returns
    -------
    str or None
        SMILES with correct D-stereochemistry, or ``None`` if
        the residue code is not recognised.
    """
    return D_AMINO_ACID_SMILES.get(residue.upper())

verify_mirror_smiles

verify_mirror_smiles(residue: str) -> dict[str, str | bool]

Verify that L and D SMILES for a residue are valid mirror images.

Uses RDKit to confirm both SMILES parse correctly and that their InChI representations differ only in stereochemistry.

Parameters:

Name Type Description Default
residue str

One-letter amino acid code.

required

Returns:

Type Description
dict

Verification result with l_smiles, d_smiles, l_valid, d_valid, is_mirror_pair.

Source code in src/neorx/mirrorfold/mirror.py
def verify_mirror_smiles(residue: str) -> dict[str, str | bool]:
    """Verify that L and D SMILES for a residue are valid mirror images.

    Uses RDKit to confirm both SMILES parse correctly and that
    their InChI representations differ only in stereochemistry.

    Parameters
    ----------
    residue : str
        One-letter amino acid code.

    Returns
    -------
    dict
        Verification result with ``l_smiles``, ``d_smiles``,
        ``l_valid``, ``d_valid``, ``is_mirror_pair``.
    """
    l_smi = get_l_smiles(residue)
    d_smi = get_d_smiles(residue)

    l_mol = Chem.MolFromSmiles(l_smi) if l_smi else None
    d_mol = Chem.MolFromSmiles(d_smi) if d_smi else None

    # Glycine has no stereocenter — L and D are identical
    if residue.upper() == "G":
        return {
            "residue": residue.upper(),
            "l_smiles": l_smi or "",
            "d_smiles": d_smi or "",
            "l_valid": l_mol is not None,
            "d_valid": d_mol is not None,
            "valid": l_mol is not None and d_mol is not None,
            "same_formula": True,
            "is_mirror_pair": True,
            "note": "Glycine is achiral — L and D forms are identical.",
        }

    # Check that they have the same molecular formula
    same_formula = False
    if l_mol and d_mol:
        l_formula = rdMolDescriptors.CalcMolFormula(l_mol)
        d_formula = rdMolDescriptors.CalcMolFormula(d_mol)
        same_formula = (l_formula == d_formula)

    return {
        "residue": residue.upper(),
        "l_smiles": l_smi or "",
        "d_smiles": d_smi or "",
        "l_valid": l_mol is not None,
        "d_valid": d_mol is not None,
        "valid": l_mol is not None and d_mol is not None and same_formula,
        "same_formula": same_formula,
        "is_mirror_pair": same_formula,
    }

Structure Prediction with ESMFold

Predicts 3D protein structures from amino-acid sequences using Meta AI's ESMFold model, with automatic fallback to the ESMFold REST API.

What is ESMFold?

ESMFold is a protein structure prediction model from Meta (FAIR) that predicts 3D coordinates directly from a single sequence — no multiple sequence alignment (MSA) needed. This makes it much faster than AlphaFold2 (seconds vs hours) while achieving comparable accuracy for well-folded proteins.

The model is built on the ESM-2 protein language model (650M parameters) and a structure module inspired by AlphaFold2. It outputs:

  • Atom coordinates in PDB format
  • pLDDT scores — per-residue confidence (0–100) stored in the B-factor column of the PDB file
pLDDT interpretation
  • > 90 — Very high confidence. Backbone and side-chain positions are reliable.
  • 70–90 — Confident. Backbone is reliable; side chains may have some error.
  • 50–70 — Low confidence. Possible loop region or partial disorder.
  • < 50 — Very low confidence. Likely intrinsically disordered or prediction is unreliable.
Limitations for D-proteins

ESMFold was trained exclusively on L-protein structures from the PDB. It has never seen a D-protein. We approximate the D-protein structure using the reversed-sequence proxy (see mirror.py). This works because:

fold(D-protein seq ABCDE) ≈ mirror(fold(L-protein seq EDCBA))

This approximation is well-validated for globular proteins (Kent et al., HIV protease) but less reliable for: * Intrinsically disordered regions * Proteins whose folding depends on chaperones * Very long sequences (> 400 residues)

predict_structure

predict_structure(sequence: str, chirality: str = 'L', use_cache: bool = True, allow_api_fallback: bool = True, allow_mock: bool = False) -> StructurePrediction

Predict the 3D structure of a protein sequence.

Attempts prediction in order: 1. Check file cache 2. Local ESMFold model (requires fair-esm[esmfold]) 3. ESMFold REST API (requires internet) 4. Mock prediction (if allow_mock=True, for testing)

For D-proteins, the sequence is reversed before prediction (the "reverse-and-reflect" proxy), and the resulting coordinates are reflected to produce D-protein geometry.

Parameters:

Name Type Description Default
sequence str

Amino acid sequence in one-letter codes.

required
chirality str

"L" for natural protein, "D" for mirror-image.

'L'
use_cache bool

Check/write the prediction cache.

True
allow_api_fallback bool

Allow the ESMFold API as a fallback.

True
allow_mock bool

Generate a mock structure if all else fails.

False

Returns:

Type Description
StructurePrediction

Predicted structure with pLDDT scores.

Raises:

Type Description
RuntimeError

If no prediction method is available.

Source code in src/neorx/mirrorfold/predictor.py
def predict_structure(
    sequence: str,
    chirality: str = "L",
    use_cache: bool = True,
    allow_api_fallback: bool = True,
    allow_mock: bool = False,
) -> StructurePrediction:
    """Predict the 3D structure of a protein sequence.

    Attempts prediction in order:
    1. Check file cache
    2. Local ESMFold model (requires ``fair-esm[esmfold]``)
    3. ESMFold REST API (requires internet)
    4. Mock prediction (if ``allow_mock=True``, for testing)

    For D-proteins, the sequence is reversed before prediction
    (the "reverse-and-reflect" proxy), and the resulting
    coordinates are reflected to produce D-protein geometry.

    Parameters
    ----------
    sequence : str
        Amino acid sequence in one-letter codes.
    chirality : str
        ``"L"`` for natural protein, ``"D"`` for mirror-image.
    use_cache : bool
        Check/write the prediction cache.
    allow_api_fallback : bool
        Allow the ESMFold API as a fallback.
    allow_mock : bool
        Generate a mock structure if all else fails.

    Returns
    -------
    StructurePrediction
        Predicted structure with pLDDT scores.

    Raises
    ------
    RuntimeError
        If no prediction method is available.
    """
    seq = sequence.upper().strip()

    # For D-proteins: reverse the sequence for prediction
    prediction_seq = mirror_sequence(seq) if chirality.upper() == "D" else seq

    # Check cache
    if use_cache:
        cached = _load_from_cache(seq, chirality)
        if cached is not None:
            return cached

    # Try local ESMFold
    pdb_string = _predict_esmfold_local(prediction_seq)
    method = "esmfold_local"

    # Fallback to API
    if pdb_string is None and allow_api_fallback:
        pdb_string = _predict_esmfold_api(prediction_seq)
        method = "esmfold_api"

    # Fallback to mock
    if pdb_string is None and allow_mock:
        pdb_string = _generate_mock_pdb(prediction_seq)
        method = "mock"
        logger.warning(
            "Using MOCK prediction — not a real structure! "
            "Install fair-esm for real predictions."
        )

    if pdb_string is None:
        raise RuntimeError(
            "No structure prediction method available. Options:\n"
            "  1. Install ESMFold: pip install fair-esm[esmfold]\n"
            "  2. Enable API fallback: allow_api_fallback=True\n"
            "  3. Enable mock for testing: allow_mock=True"
        )

    # For D-proteins: reflect coordinates to get mirror geometry
    if chirality.upper() == "D":
        pdb_string = reflect_coordinates(pdb_string, axis="x")

    # Extract pLDDT scores
    plddt_scores = _extract_plddt_from_pdb(pdb_string)
    mean_plddt = float(np.mean(plddt_scores)) if plddt_scores else 0.0

    prediction = StructurePrediction(
        sequence=seq,
        chirality=chirality.upper(),
        pdb_string=pdb_string,
        plddt_scores=plddt_scores,
        mean_plddt=mean_plddt,
        prediction_method=method,
    )

    # Cache the result
    if use_cache:
        _save_to_cache(prediction)

    logger.info(
        "Predicted %s-structure: %d residues, mean pLDDT=%.1f (%s).",
        chirality, len(seq), mean_plddt, method,
    )

    return prediction

predict_pair

predict_pair(sequence: str, use_cache: bool = True, allow_api_fallback: bool = True, allow_mock: bool = False) -> tuple[StructurePrediction, StructurePrediction]

Predict both L- and D-protein structures.

Convenience function that predicts the natural L-form and the mirror-image D-form for the same sequence.

Parameters:

Name Type Description Default
sequence str

Amino acid sequence.

required
use_cache bool

Use prediction cache.

True
allow_api_fallback bool

Allow ESMFold API fallback.

True
allow_mock bool

Allow mock predictions for testing.

False

Returns:

Type Description
tuple[StructurePrediction, StructurePrediction]

(L-structure, D-structure)

Source code in src/neorx/mirrorfold/predictor.py
def predict_pair(
    sequence: str,
    use_cache: bool = True,
    allow_api_fallback: bool = True,
    allow_mock: bool = False,
) -> tuple[StructurePrediction, StructurePrediction]:
    """Predict both L- and D-protein structures.

    Convenience function that predicts the natural L-form and
    the mirror-image D-form for the same sequence.

    Parameters
    ----------
    sequence : str
        Amino acid sequence.
    use_cache : bool
        Use prediction cache.
    allow_api_fallback : bool
        Allow ESMFold API fallback.
    allow_mock : bool
        Allow mock predictions for testing.

    Returns
    -------
    tuple[StructurePrediction, StructurePrediction]
        (L-structure, D-structure)
    """
    kwargs = dict(
        use_cache=use_cache,
        allow_api_fallback=allow_api_fallback,
        allow_mock=allow_mock,
    )

    l_pred = predict_structure(sequence, chirality="L", **kwargs)
    d_pred = predict_structure(sequence, chirality="D", **kwargs)

    return l_pred, d_pred

Structure Comparison — L vs D Proteins

Aligns and compares the predicted structures of L- and D-protein forms using RMSD, TM-score, and secondary structure analysis.

RMSD vs TM-score
  • RMSD (Root Mean Square Deviation) is the most intuitive metric: the average Cα displacement in Ångströms after optimal superposition. But RMSD has a flaw — a single badly-aligned loop can inflate the score even if the rest of the structure matches perfectly.

  • TM-score (Template Modelling score) solves this by down-weighting large distances. It ranges from 0 to 1:

  • TM > 0.5 → same fold (statistically significant)

  • TM > 0.7 → very similar structures
  • TM > 0.9 → essentially identical

Formula: TM = (1/L) Σ 1/(1 + (dᵢ/d₀)²)

where L is target length, dᵢ is per-residue distance, and d₀ = 1.24 ∛(L − 15) − 1.8 is a length-dependent normaliser.

Reference: Zhang & Skolnick (2004) Proteins 57:702-710.

Secondary structure comparison

We assign each residue to one of three states based on backbone torsion angles (φ, ψ) from the Ramachandran plot:

  • H (helix): −160° < φ < −20° and −80° < ψ < 0°
  • E (sheet): −180° < φ < −40° and 50° < ψ < 180°
  • C (coil): everything else

For D-proteins, the Ramachandran plot is mirrored: the allowed regions have positive φ values (the exact reflection of the L-protein regions). When comparing secondary structure between L and D forms, we compare the topology (helix vs sheet vs coil) regardless of the sign of the torsion angles.

compare_structures

compare_structures(l_prediction: StructurePrediction, d_prediction: StructurePrediction, distance_threshold: float = 2.0) -> ComparisonReport

Compare L- and D-protein predicted structures.

Performs: 1. Extract Cα coordinates from both PDB strings 2. Superimpose using the Kabsch algorithm 3. Calculate RMSD and TM-score 4. Compute per-residue distances 5. Assign and compare secondary structure 6. Identify conserved and divergent regions

Parameters:

Name Type Description Default
l_prediction StructurePrediction

Predicted L-protein structure.

required
d_prediction StructurePrediction

Predicted D-protein structure.

required
distance_threshold float

Cα distance threshold (Å) for classifying conserved vs divergent regions. Default 2.0 Å.

2.0

Returns:

Type Description
ComparisonReport

Full structural comparison report.

Source code in src/neorx/mirrorfold/compare.py
def compare_structures(
    l_prediction: StructurePrediction,
    d_prediction: StructurePrediction,
    distance_threshold: float = 2.0,
) -> ComparisonReport:
    """Compare L- and D-protein predicted structures.

    Performs:
    1. Extract Cα coordinates from both PDB strings
    2. Superimpose using the Kabsch algorithm
    3. Calculate RMSD and TM-score
    4. Compute per-residue distances
    5. Assign and compare secondary structure
    6. Identify conserved and divergent regions

    Parameters
    ----------
    l_prediction : StructurePrediction
        Predicted L-protein structure.
    d_prediction : StructurePrediction
        Predicted D-protein structure.
    distance_threshold : float
        Cα distance threshold (Å) for classifying conserved vs
        divergent regions.  Default 2.0 Å.

    Returns
    -------
    ComparisonReport
        Full structural comparison report.
    """
    # Extract Cα coordinates
    coords_l = _extract_ca_coords(l_prediction.pdb_string)
    coords_d = _extract_ca_coords(d_prediction.pdb_string)

    # Handle length mismatch (truncate to shorter)
    n = min(len(coords_l), len(coords_d))
    if n == 0:
        logger.warning("No Cα atoms found in one or both structures.")
        return ComparisonReport(
            l_structure=l_prediction,
            d_structure=d_prediction,
        )

    coords_l = coords_l[:n]
    coords_d = coords_d[:n]

    # Superimpose D onto L
    coords_d_aligned, rmsd = superimpose(coords_l, coords_d)

    # TM-score
    tm = calculate_tm_score(coords_l, coords_d_aligned, target_length=n)

    # Per-residue distances
    distances = per_residue_distances(coords_l, coords_d_aligned)

    # Secondary structure
    ss_l = assign_secondary_structure(l_prediction.pdb_string)
    ss_d = assign_secondary_structure(d_prediction.pdb_string)
    ss_match = _secondary_structure_match(ss_l[:n], ss_d[:n])

    # Conserved / divergent regions
    conserved, divergent = _identify_regions(distances, distance_threshold)

    logger.info(
        "Comparison: RMSD=%.2f Å, TM=%.3f, SS-match=%.1f%%, "
        "%d conserved / %d divergent regions.",
        rmsd, tm, ss_match * 100,
        len(conserved), len(divergent),
    )

    return ComparisonReport(
        l_structure=l_prediction,
        d_structure=d_prediction,
        rmsd=rmsd,
        tm_score=tm,
        per_residue_distances=distances,
        secondary_structure_match=ss_match,
        conserved_regions=conserved,
        divergent_regions=divergent,
        aligned_length=n,
    )

superimpose

superimpose(coords_fixed: ndarray, coords_moving: ndarray) -> tuple[np.ndarray, float]

Optimal superposition using the Kabsch algorithm.

Finds the rotation and translation that minimises RMSD between two sets of corresponding points.

Parameters:

Name Type Description Default
coords_fixed ndarray[N, 3]

Reference coordinates (will not move).

required
coords_moving ndarray[N, 3]

Mobile coordinates (will be rotated/translated).

required

Returns:

Name Type Description
coords_aligned ndarray[N, 3]

The moving coordinates after optimal superposition.

rmsd float

RMSD in Ångströms.

Source code in src/neorx/mirrorfold/compare.py
def superimpose(
    coords_fixed: np.ndarray,
    coords_moving: np.ndarray,
) -> tuple[np.ndarray, float]:
    """Optimal superposition using the Kabsch algorithm.

    Finds the rotation and translation that minimises RMSD
    between two sets of corresponding points.

    Parameters
    ----------
    coords_fixed : ndarray [N, 3]
        Reference coordinates (will not move).
    coords_moving : ndarray [N, 3]
        Mobile coordinates (will be rotated/translated).

    Returns
    -------
    coords_aligned : ndarray [N, 3]
        The moving coordinates after optimal superposition.
    rmsd : float
        RMSD in Ångströms.
    """
    assert len(coords_fixed) == len(coords_moving), (
        f"Coordinate count mismatch: {len(coords_fixed)} vs {len(coords_moving)}"
    )

    n = len(coords_fixed)

    # Centre both coordinate sets
    centroid_fixed = coords_fixed.mean(axis=0)
    centroid_moving = coords_moving.mean(axis=0)
    p = coords_fixed - centroid_fixed
    q = coords_moving - centroid_moving

    # Cross-covariance matrix
    H = q.T @ p

    # SVD
    U, S, Vt = np.linalg.svd(H)

    # Correct for reflection
    d = np.linalg.det(Vt.T @ U.T)
    sign_matrix = np.diag([1.0, 1.0, np.sign(d)])

    # Optimal rotation
    R = Vt.T @ sign_matrix @ U.T

    # Apply rotation and translation
    aligned = (q @ R.T) + centroid_fixed

    # RMSD
    diff = coords_fixed - aligned
    rmsd = float(np.sqrt(np.mean(np.sum(diff**2, axis=1))))

    return aligned, rmsd

calculate_tm_score

calculate_tm_score(coords_ref: ndarray, coords_aligned: ndarray, target_length: Optional[int] = None) -> float

Calculate the TM-score between two aligned structures.

TM-score is more robust than RMSD because it uses a length-dependent distance cutoff d₀ that down-weights large per-residue deviations.

Parameters:

Name Type Description Default
coords_ref ndarray[N, 3]

Reference Cα coordinates.

required
coords_aligned ndarray[N, 3]

Aligned Cα coordinates (after superposition).

required
target_length int

Normalisation length. Defaults to the number of residues.

None

Returns:

Type Description
float

TM-score in [0, 1].

Source code in src/neorx/mirrorfold/compare.py
def calculate_tm_score(
    coords_ref: np.ndarray,
    coords_aligned: np.ndarray,
    target_length: Optional[int] = None,
) -> float:
    """Calculate the TM-score between two aligned structures.

    TM-score is more robust than RMSD because it uses a
    length-dependent distance cutoff ``d₀`` that down-weights
    large per-residue deviations.

    Parameters
    ----------
    coords_ref : ndarray [N, 3]
        Reference Cα coordinates.
    coords_aligned : ndarray [N, 3]
        Aligned Cα coordinates (after superposition).
    target_length : int, optional
        Normalisation length.  Defaults to the number of residues.

    Returns
    -------
    float
        TM-score in [0, 1].
    """
    L = target_length or len(coords_ref)
    if L < 16:
        # d0 formula is unstable for very short proteins
        d0 = 0.5
    else:
        d0 = 1.24 * (L - 15) ** (1.0 / 3.0) - 1.8
        d0 = max(d0, 0.5)  # floor at 0.5 Å

    # Per-residue distances
    distances = np.sqrt(np.sum((coords_ref - coords_aligned) ** 2, axis=1))

    # TM-score sum
    tm_sum = np.sum(1.0 / (1.0 + (distances / d0) ** 2))
    tm_score = float(tm_sum / L)

    return min(tm_score, 1.0)

D-Protein Therapeutic Assessment

Evaluates the potential of D-protein (mirror-image) variants as therapeutics. This is one of the most exciting areas of mirror biology — D-proteins have several inherent advantages:

Why D-protein therapeutics?
  1. Protease resistance — Natural proteases (trypsin, chymotrypsin, pepsin, etc.) evolved to recognise L-amino acid peptide bonds. They literally cannot grip D-peptide bonds because the active site geometry is wrong. D-proteins are essentially invisible to the body's proteolytic machinery.

  2. Immune evasion — MHC class I and II molecules present peptide fragments to T cells. These molecules bind peptides in a specific L-amino acid configuration. D-peptides cannot be presented, making D-proteins practically non-immunogenic.

  3. Extended half-life — Because D-proteins resist proteases and evade the immune system, they have dramatically longer serum half-lives than L-protein drugs. An L-peptide that survives minutes in blood can last days as a D-peptide.

  4. Oral bioavailability — Resistance to digestive proteases opens the possibility of oral administration, which is the holy grail for protein therapeutics.

The catch

The D-protein must fold into the correct 3D structure — specifically, the mirror image of the L-protein's fold. If it folds correctly, it will bind the same target (because the mirror-image binding surface is complementary to the same binding pocket).

This module quantifies how likely a D-protein is to maintain its fold and function, based on structural comparison.

assess_therapeutic_potential

assess_therapeutic_potential(protein_name: str, comparison: ComparisonReport, l_properties: PropertyProfile, d_properties: PropertyProfile, pdb_id: Optional[str] = None, pocket_residues: Optional[list[int]] = None) -> TherapeuticAssessment

Run a full D-protein therapeutic assessment.

Integrates structural comparison and property analysis to produce a comprehensive evaluation of whether a D-protein variant is a viable therapeutic candidate.

Parameters:

Name Type Description Default
protein_name str

Human-readable name (e.g. "Insulin B chain").

required
comparison ComparisonReport

Structural comparison between L and D forms.

required
l_properties PropertyProfile

L-protein biophysical properties.

required
d_properties PropertyProfile

D-protein biophysical properties.

required
pdb_id str

PDB identifier if available.

None
pocket_residues list[int]

Residue indices forming the binding pocket.

None

Returns:

Type Description
TherapeuticAssessment

Complete therapeutic assessment.

Source code in src/neorx/mirrorfold/therapeutic.py
def assess_therapeutic_potential(
    protein_name: str,
    comparison: ComparisonReport,
    l_properties: PropertyProfile,
    d_properties: PropertyProfile,
    pdb_id: Optional[str] = None,
    pocket_residues: Optional[list[int]] = None,
) -> TherapeuticAssessment:
    """Run a full D-protein therapeutic assessment.

    Integrates structural comparison and property analysis to
    produce a comprehensive evaluation of whether a D-protein
    variant is a viable therapeutic candidate.

    Parameters
    ----------
    protein_name : str
        Human-readable name (e.g. "Insulin B chain").
    comparison : ComparisonReport
        Structural comparison between L and D forms.
    l_properties : PropertyProfile
        L-protein biophysical properties.
    d_properties : PropertyProfile
        D-protein biophysical properties.
    pdb_id : str, optional
        PDB identifier if available.
    pocket_residues : list[int], optional
        Residue indices forming the binding pocket.

    Returns
    -------
    TherapeuticAssessment
        Complete therapeutic assessment.
    """
    tm = comparison.tm_score or 0.0
    seq_len = len(comparison.l_structure.sequence)

    pocket_conserved = assess_binding_pocket_conservation(
        comparison, pocket_residues
    )

    viability = therapeutic_viability_score(tm, pocket_conserved, seq_len)

    rationale = _generate_rationale(
        tm_score=tm,
        pocket_conserved=pocket_conserved,
        viability=viability,
        sequence_length=seq_len,
        plddt_l=l_properties.mean_plddt,
        plddt_d=d_properties.mean_plddt,
    )

    logger.info(
        "Assessment for %s: viability=%s, TM=%.3f, pocket=%s",
        protein_name, viability, tm, pocket_conserved,
    )

    return TherapeuticAssessment(
        protein_name=protein_name,
        pdb_id=pdb_id,
        comparison=comparison,
        l_properties=l_properties,
        d_properties=d_properties,
        binding_pocket_conserved=pocket_conserved,
        estimated_protease_resistance=assess_protease_resistance("D"),
        estimated_immunogenicity=assess_immunogenicity("D"),
        therapeutic_viability=viability,
        rationale=rationale,
    )

assess_protease_resistance

assess_protease_resistance(chirality: str) -> str

Estimate protease resistance based on chirality.

This is straightforward: L-proteins are susceptible to all natural proteases. D-proteins are resistant to essentially all of them.

Parameters:

Name Type Description Default
chirality str

"L" or "D".

required

Returns:

Type Description
str

Qualitative resistance level.

Source code in src/neorx/mirrorfold/therapeutic.py
def assess_protease_resistance(chirality: str) -> str:
    """Estimate protease resistance based on chirality.

    This is straightforward: L-proteins are susceptible to all
    natural proteases.  D-proteins are resistant to essentially
    all of them.

    Parameters
    ----------
    chirality : str
        ``"L"`` or ``"D"``.

    Returns
    -------
    str
        Qualitative resistance level.
    """
    if chirality == "D":
        return "Very High"
    return "Normal (susceptible to natural proteases)"

assess_immunogenicity

assess_immunogenicity(chirality: str) -> str

Estimate immunogenicity based on chirality.

MHC class I molecules bind peptide fragments of 8–10 residues in a groove that is stereospecific for L-amino acids. MHC class II binds 13–25-mers, also stereospecifically. Since D-peptides cannot fit these grooves, D-proteins evade adaptive immunity almost completely.

Innate immunity (e.g. toll-like receptors) is less chirality- dependent, so some innate immune response is possible.

Parameters:

Name Type Description Default
chirality str

"L" or "D".

required

Returns:

Type Description
str

Qualitative immunogenicity level.

Source code in src/neorx/mirrorfold/therapeutic.py
def assess_immunogenicity(chirality: str) -> str:
    """Estimate immunogenicity based on chirality.

    MHC class I molecules bind peptide fragments of 8–10 residues
    in a groove that is stereospecific for L-amino acids.  MHC
    class II binds 13–25-mers, also stereospecifically.  Since
    D-peptides cannot fit these grooves, D-proteins evade
    adaptive immunity almost completely.

    Innate immunity (e.g. toll-like receptors) is less chirality-
    dependent, so some innate immune response is possible.

    Parameters
    ----------
    chirality : str
        ``"L"`` or ``"D"``.

    Returns
    -------
    str
        Qualitative immunogenicity level.
    """
    if chirality == "D":
        return "Very Low (MHC cannot present D-peptides)"
    return "Normal (subject to standard immune surveillance)"