Exclusion Criteria

matchminer_ai.matching.exclusion_check

Exclusion criteria check helpers.

exclusion_criteria_check

exclusion_criteria_check(matches: DataFrame, *, config: MMAIConfig | None = None, filter_excluded: bool = False, return_metadata: bool = False) -> pd.DataFrame | tuple[pd.DataFrame, dict]

Evaluate whether each candidate patient-trial pair passes exclusion criteria.

Parameters:

Name	Type	Description	Default
matches	DataFrame	DataFrame of candidate patient-trial pairs to evaluate for exclusion checks. Expected columns patient_id : str Patient identifier. trial_id : str Trial identifier. general_exclusion_criteria : str Trial-level exclusion criteria text. general_exclusion_criteria_evidence : str Patient-level evidence related to exclusion criteria.	required
config	MMAIConfig	MMAI configuration containing exclusion checker settings. Uses default preset when omitted.	None
filter_excluded	bool	If True, return only rows where exclusion_criteria_pass is True.	False
return_metadata	bool	When True, also return a metadata dict containing the config snapshot and model metadata for this run.	False

Returns:

Type	Description
DataFrame	Derived output table containing: Columns patient_id : str Patient identifier. trial_id : str Trial identifier. exclusion_score : float Model-generated confidence score associated with exclusion-check label. exclusion_criteria_pass : bool True when the patient is predicted to pass exclusion criteria for this trial; False otherwise.
tuple[DataFrame, dict]	When return_metadata is True, returns the DataFrame plus metadata.

Source code in src/matchminer_ai/matching/exclusion_check.py

def exclusion_criteria_check(
    matches: pd.DataFrame,
    *,
    config: MMAIConfig | None = None,
    filter_excluded: bool = False,
    return_metadata: bool = False,
) -> pd.DataFrame | tuple[pd.DataFrame, dict]:
    """
    Evaluate whether each candidate patient-trial pair passes exclusion criteria.

    Parameters
    ----------
    matches : pd.DataFrame
        DataFrame of candidate patient-trial pairs to evaluate for exclusion checks.

        Expected columns
        ----------------
        patient_id : str
            Patient identifier.
        trial_id : str
            Trial identifier.
        general_exclusion_criteria : str
            Trial-level exclusion criteria text.
        general_exclusion_criteria_evidence : str
            Patient-level evidence related to exclusion criteria.

    config : MMAIConfig, optional
        MMAI configuration containing exclusion checker settings.
        Uses default preset when omitted.
    filter_excluded : bool, default False
        If True, return only rows where ``exclusion_criteria_pass`` is True.
    return_metadata : bool, default False
        When True, also return a metadata dict containing the config snapshot
        and model metadata for this run.

    Returns
    -------
    pd.DataFrame
        Derived output table containing:

        Columns
        -------
        patient_id : str
            Patient identifier.
        trial_id : str
            Trial identifier.
        exclusion_score : float
            Model-generated confidence score associated with exclusion-check label.
        exclusion_criteria_pass : bool
            True when the patient is predicted to pass exclusion criteria for
            this trial; False otherwise.
    tuple[pd.DataFrame, dict]
        When return_metadata is True, returns the DataFrame plus metadata.
    """
    # Validate that rows contain the text + ids needed for exclusion checker prompts.
    required = [
        "patient_id",
        "trial_id",
        "general_exclusion_criteria",
        "general_exclusion_criteria_evidence",
    ]
    missing = [col for col in required if col not in matches.columns]
    if missing:
        raise ValueError(f"matches is missing required columns: {', '.join(missing)}")

    # Resolve run config and build checker prompts from the configured template.
    resolved_config = config or load_default_preset()
    checker_config = dict(resolved_config.raw.get("exclusion_criteria", {}))
    prompt_file = str(checker_config["prompt_file"]).strip()

    template = _load_exclusion_criteria_template(prompt_file)
    prompts = _build_exclusion_criteria_prompts(matches, template=template)

    # Run the backend text-classification model over all prompts.
    predictions, model_metadata = run_checker(
        prompts,
        checker_config=checker_config,
        model_metadata_cache_dir=resolved_config.model_metadata_cache_dir,
    )

    if len(predictions) != len(matches):
        raise ValueError(
            "Checker returned a different number of predictions than input rows."
        )

    # Convert model outputs into a compact, derived result table.
    output = matches[["patient_id", "trial_id"]].copy()
    output["exclusion_score"] = [
        float(prediction["score"]) for prediction in predictions
    ]
    output["exclusion_criteria_pass"] = [
        str(prediction["label"]).strip().upper() == "NEGATIVE"
        for prediction in predictions
    ]

    # Optionally keep only rows that passed exclusion criteria.
    if filter_excluded:
        keep_rows = output["exclusion_criteria_pass"]
        output = output.loc[keep_rows].copy()
    output = output.reset_index(drop=True)

    # Optionally return metadata for reproducibility/debugging.
    if return_metadata:
        metadata_payload = {
            "package": package_metadata(),
            "config_snapshot": config_snapshot(resolved_config),
            "model_metadata": {
                "exclusion_criteria_checker": model_metadata,
            },
        }
        return output, metadata_payload
    return output

matchminer_ai.matching.llm_checks

LLM-based match quality and exclusion screening helpers.

exclusion_criteria_check_with_llm

exclusion_criteria_check_with_llm(matches: DataFrame, *, config: 'MMAIConfig | None' = None, return_metadata: bool = False) -> pd.DataFrame | tuple[pd.DataFrame, dict]

Evaluate trial-level exclusion criteria with the configured LLM prompt.

Parameters:

Name	Type	Description	Default
matches	DataFrame	DataFrame of candidate patient-trial pairs to evaluate for exclusion checks. Expected columns patient_id : str Patient identifier. trial_id : str Trial identifier. general_exclusion_criteria : str Trial-level exclusion criteria text. general_exclusion_criteria_evidence : str Patient-level evidence related to exclusion criteria.	required
config	MMAIConfig	MMAI configuration containing LLM exclusion checker settings. Uses default preset when omitted.	None
return_metadata	bool	When True, also return a metadata dict containing the config snapshot and model metadata for this run.	False

Returns:

Type	Description
DataFrame	Derived output table containing: Columns patient_id : str Patient identifier. trial_id : str Trial identifier. llm_exclusion_criteria_pass : bool | None Whether the LLM judged that the patient passes exclusion criteria, or None when parsing failed. Debug Columns llm_exclusion_criteria_answer_text : str Text the package treated as the LLM answer and used for parsing. Included only when debug_mode is true. llm_exclusion_criteria_reasoning_text : str Optional separate reasoning trace returned by the backend or extracted by the configured reasoning parser. Included only when debug_mode is true. llm_exclusion_criteria_parse_status : str Whether the package could parse the answer text. Values are parsed, parsed_fallback, or parse_failed. Included only when debug_mode is true.
tuple[DataFrame, dict]	When return_metadata is True, returns the DataFrame plus metadata.

Source code in src/matchminer_ai/matching/llm_checks.py

def exclusion_criteria_check_with_llm(
    matches: pd.DataFrame,
    *,
    config: "MMAIConfig | None" = None,
    return_metadata: bool = False,
) -> pd.DataFrame | tuple[pd.DataFrame, dict]:
    """
    Evaluate trial-level exclusion criteria with the configured LLM prompt.

    Parameters
    ----------
    matches : pd.DataFrame
        DataFrame of candidate patient-trial pairs to evaluate for exclusion
        checks.

        Expected columns
        ----------------
        patient_id : str
            Patient identifier.
        trial_id : str
            Trial identifier.
        general_exclusion_criteria : str
            Trial-level exclusion criteria text.
        general_exclusion_criteria_evidence : str
            Patient-level evidence related to exclusion criteria.

    config : MMAIConfig, optional
        MMAI configuration containing LLM exclusion checker settings.
        Uses default preset when omitted.
    return_metadata : bool, default False
        When True, also return a metadata dict containing the config snapshot
        and model metadata for this run.

    Returns
    -------
    pd.DataFrame
        Derived output table containing:

        Columns
        -------
        patient_id : str
            Patient identifier.
        trial_id : str
            Trial identifier.
        llm_exclusion_criteria_pass : bool | None
            Whether the LLM judged that the patient passes exclusion criteria,
            or None when parsing failed.
        Debug Columns
        -------------
        llm_exclusion_criteria_answer_text : str
            Text the package treated as the LLM answer and used for parsing.
            Included only when debug_mode is true.
        llm_exclusion_criteria_reasoning_text : str
            Optional separate reasoning trace returned by the backend or
            extracted by the configured reasoning parser. Included only when
            debug_mode is true.
        llm_exclusion_criteria_parse_status : str
            Whether the package could parse the answer text. Values are
            ``parsed``, ``parsed_fallback``, or ``parse_failed``. Included only
            when debug_mode is true.
    tuple[pd.DataFrame, dict]
        When return_metadata is True, returns the DataFrame plus metadata.
    """
    required = [
        "patient_id",
        "trial_id",
        "general_exclusion_criteria",
        "general_exclusion_criteria_evidence",
    ]
    missing = [col for col in required if col not in matches.columns]
    if missing:
        raise ValueError(f"matches is missing required columns: {', '.join(missing)}")

    resolved_config = config or load_default_preset()
    llm_config = dict(resolved_config.llm_exclusion_criteria)
    prompt_template = _load_prompt_template(str(llm_config["prompt_file"]).strip())
    messages_list = [
        _build_messages(
            prompt_template.format(
                patient_boilerplate=str(row["general_exclusion_criteria_evidence"]),
                trial_boilerplate=str(row["general_exclusion_criteria"]),
            )
        )
        for _, row in matches.iterrows()
    ]
    responses, reasonings, model_metadata = _run_llm_check(
        matches,
        config=resolved_config,
        section_name="llm_exclusion_criteria",
        messages_list=messages_list,
    )
    parsed = [_parse_exclusion_result(response) for response in responses]

    output = matches[["patient_id", "trial_id"]].copy()
    output["llm_exclusion_criteria_pass"] = [passed for passed, _ in parsed]
    if resolved_config.debug_mode:
        output["llm_exclusion_criteria_answer_text"] = responses
        output["llm_exclusion_criteria_reasoning_text"] = reasonings
        output["llm_exclusion_criteria_parse_status"] = [
            parse_status for _, parse_status in parsed
        ]
    output = output.reset_index(drop=True)

    if return_metadata:
        metadata_payload = {
            "package": package_metadata(),
            "config_snapshot": config_snapshot(resolved_config),
            "model_metadata": {
                "llm_exclusion_criteria_checker": model_metadata,
            },
        }
        return output, metadata_payload
    return output