Skip to content

Embedding

matchminer_ai.embedding.embed

Embedding step for trial/patient matching.

embed_for_matching 

embed_for_matching(df: DataFrame, *, entity_type: Literal['patient', 'trial'], config: MMAIConfig | None = None, return_metadata: bool = False) -> pd.DataFrame | tuple[pd.DataFrame, dict]

Convert trial or patient summaries into embedding vectors for semantic matching.

Parameters:

Name Type Description Default
df DataFrame

Input summaries to embed.

For entity_type="patient" One row per patient.

Expected columns
----------------
cancer_history_summary : str
    Summary text to embed for each patient.

For entity_type="trial" One row per clinical space.

Expected columns
----------------
clinical_space_summary : str
    Summary text to embed for each clinical space.
space_trial_id : str
    Unique identifier for the clinical space.
required
entity_type ('patient', 'trial')

Controls which summary column is used as the text to embed.

 "patient"
config MMAIConfig

MMAI configuration containing embedding settings (model_path, device, prompt_file/query_prompt). 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

DataFrame containing the embedding plus identifier columns for matching.

Columns

For entity_type="patient" patient_id : str embedding : array-like Vector representation of the summary text in a shared semantic space.

For entity_type="trial" space_trial_id : str embedding : array-like Vector representation of the summary text in a shared semantic space.
tuple[DataFrame, dict]

When return_metadata is True, returns the DataFrame plus a metadata dict.
Source code in src/matchminer_ai/embedding/embed.py 
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 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
def embed_for_matching(
    df: pd.DataFrame,
    *,
    entity_type: Literal["patient", "trial"],
    config: MMAIConfig | None = None,
    return_metadata: bool = False,
) -> pd.DataFrame | tuple[pd.DataFrame, dict]:
    """
    Convert trial or patient summaries into embedding vectors for semantic matching.

    Parameters
    ----------
    df : pd.DataFrame
        Input summaries to embed.

        For entity_type="patient"
            One row per patient.

            Expected columns
            ----------------
            cancer_history_summary : str
                Summary text to embed for each patient.

        For entity_type="trial"
            One row per clinical space.

            Expected columns
            ----------------
            clinical_space_summary : str
                Summary text to embed for each clinical space.
            space_trial_id : str
                Unique identifier for the clinical space.
    entity_type : {"patient", "trial"}
        Controls which summary column is used as the text to embed.
    config : MMAIConfig, optional
        MMAI configuration containing embedding settings
        (model_path, device, prompt_file/query_prompt). Uses default preset
        when omitted.
    return_metadata : bool, optional
        When True, also return a metadata dict containing the config snapshot
        and model metadata for this run.

    Returns
    -------
    pd.DataFrame
        DataFrame containing the embedding plus identifier columns for matching.

        Columns
        -------
        For entity_type="patient"
            patient_id : str
            embedding : array-like
                Vector representation of the summary text in a shared semantic space.

        For entity_type="trial"
            space_trial_id : str
            embedding : array-like
                Vector representation of the summary text in a shared semantic space.
    tuple[pd.DataFrame, dict]
        When return_metadata is True, returns the DataFrame plus a metadata dict.
    """
    text_col = _resolve_text_column(entity_type)
    if text_col not in df.columns:
        raise ValueError(f"df is missing required column for {entity_type}: {text_col}")

    id_cols = _resolve_id_columns(entity_type)
    missing = [col for col in id_cols if col not in df.columns]
    if missing:
        raise ValueError(f"df is missing required columns for {entity_type}: {missing}")

    resolved_config = config or load_default_preset()
    embedding_config = dict(getattr(resolved_config, "embedding", {}))

    output = df.copy()

    summaries = output[text_col].fillna("").astype(str).tolist()
    embeddings, model_metadata = generate_embeddings(
        summaries,
        embedding_config=embedding_config,
        model_metadata_cache_dir=resolved_config.model_metadata_cache_dir,
    )
    output["embedding"] = embeddings
    result = output[id_cols + ["embedding"]].copy()
    if return_metadata:
        metadata_payload = {
            "package": package_metadata(),
            "config_snapshot": config_snapshot(resolved_config),
            "model_metadata": {
                "embedding_model": model_metadata,
            },
        }
        return result, metadata_payload
    return result