Skip to content

Embedding

embed_for_matching is the notebook layer: DataFrame in, DataFrame out, for interactive analysis. embed_texts is the service layer it's built on: plain text list in, vectors plus metadata out, for callers already working in their own data types (e.g. a live matching service).

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 
 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
126
127
128
129
130
131
132
133
134
135
136
137
138
139
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()

    output = df.copy()

    summaries = output[text_col].fillna("").astype(str).tolist()
    embeddings, model_metadata = embed_texts(summaries, config=resolved_config)
    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": {
                "embed_for_matching": model_metadata,
            },
        }
        return result, metadata_payload
    return result

embed_texts 

embed_texts(texts: list[str], *, config: MMAIConfig | None = None) -> tuple[list[list[float]], dict]

Embed summary strings in input order and return vectors plus model metadata.

Accepts patient or trial text without identifiers or DataFrames. Uses the default preset when config is omitted and reuses the cached inference model. Model metadata includes model_name and model_sha.

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
def embed_texts(
    texts: list[str],
    *,
    config: MMAIConfig | None = None,
) -> tuple[list[list[float]], dict]:
    """Embed summary strings in input order and return vectors plus model metadata.

    Accepts patient or trial text without identifiers or DataFrames. Uses the
    default preset when config is omitted and reuses the cached inference model.
    Model metadata includes model_name and model_sha.
    """
    resolved_config = config or load_default_preset()
    return generate_embeddings(
        texts,
        embedding_config=dict(getattr(resolved_config, "embedding", {})),
        model_metadata_cache_dir=resolved_config.model_metadata_cache_dir,
    )