tabullm 1.0.0__tar.gz

tabullm-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Alireza S. Mahani and Mansour T.A. Sharabiani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tabullm-1.0.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: tabullm
+Version: 1.0.0
+Summary: Seamless Feature Extraction and Interpretation of Text Columns in Tabular Data Using Large Language Models
+Author-email: "Alireza S. Mahani, Mansour T.A. Sharabiani" <alireza.s.mahani@gmail.com>
+License-Expression: MIT
+Keywords: text embedding,large language models,feature engineering,cross-validation
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: scipy>=1.10
+Requires-Dist: pydantic>=2.0
+Requires-Dist: langchain>=0.1
+Requires-Dist: langchain-core>=0.1
+Requires-Dist: langchain-community>=0.1
+Requires-Dist: pillow>=12.1.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Provides-Extra: kaggle
+Requires-Dist: kaggle>=1.6; extra == "kaggle"
+Dynamic: license-file
+
+# TabuLLM
+
+Python package for feature extraction and interpretation of text columns in tabular data using large language models.
+
+## Overview
+
+TabuLLM integrates LLM-based text embeddings into scikit-learn pipelines for tabular datasets containing text columns. Built on LangChain and scikit-learn, it provides sklearn-compatible transformers for embedding, dimensionality reduction, and cluster interpretation.
+
+## Installation
+
+```bash
+pip install tabullm
+```
+
+Optional dependency groups provide extended functionality:
+
+```bash
+pip install tabullm[huggingface]   # HuggingFace embedding models
+pip install tabullm[aws]           # AWS Bedrock / Cohere
+pip install tabullm[kaggle]        # Kaggle dataset download (load_fraud)
+pip install tabullm[viz]           # Visualization utilities
+```
+
+## Core Components
+
+**TextColumnTransformer** - Wraps LangChain embedding models (OpenAI, Anthropic, HuggingFace, etc.) with a sklearn interface. Handles multiple text columns with configurable concatenation and optional L2 normalization (`normalize=True`). Use `estimate_tokens()` to preview API cost before embedding.
+
+**GMMFeatureExtractor** - Extends sklearn's `GaussianMixture` with a `transform()` method that returns per-cluster log-joint features $\log p(\mathbf{x}, c_k)$ — the quantity the GMM maximises for hard assignment — enabling use in sklearn pipelines. An optional `include_log_density` parameter appends the marginal log-density as an explicit outlier score. A companion `assignment_confidence_stats()` method returns per-observation cluster quality diagnostics (`max_posterior`, `entropy`, `log_joint_margin`, `log_density`).
+
+**SphericalKMeans** - K-means clustering with cosine distance for L2-normalized embeddings. For normalized embeddings, mathematically equivalent to sklearn's `KMeans`. Available as an alternative hard-clustering option when GMM-based features are not needed.
+
+**ClusterExplainer** - Generates natural language cluster descriptions using LLMs with automatic recursive summarization that scales to arbitrarily large datasets. Supports:
+- Cost preview (`preview=True`) before LLM calls
+- Optional outcome-based statistical testing (`y`) to characterize which clusters associate with a target variable
+- Per-observation covariates (`observation_stats`) — e.g., from `assignment_confidence_stats()` — appended to the association table
+- A synthesis step (`synthesize=True`) that produces a coherent interpretive narrative across all cluster results
+- An outcome label (`y_label`) used only in the synthesis prompt; cluster descriptions are generated without knowledge of `y` (*blind labeling* principle)
+
+**load_fraud()** - Data utility that downloads and caches the fraud detection dataset from Kaggle (requires `tabullm[kaggle]`), returning features, labels, and metadata.
+
+## Quick Example
+
+```python
+from tabullm import TextColumnTransformer, GMMFeatureExtractor, ClusterExplainer
+from langchain_huggingface import HuggingFaceEmbeddings
+from langchain_openai import ChatOpenAI
+from sklearn.pipeline import Pipeline
+from sklearn.ensemble import RandomForestClassifier
+
+# Embed text columns
+embedding_model = HuggingFaceEmbeddings(
+    model_name='sentence-transformers/all-MiniLM-L6-v2'
+)
+text_transformer = TextColumnTransformer(
+    model=embedding_model,
+    colnames={'title': 'Title', 'description': 'Description'}
+)
+
+# Build pipeline: Embed → Reduce → Classify
+pipeline = Pipeline([
+    ('embed', text_transformer),
+    ('reduce', GMMFeatureExtractor(n_components=10)),
+    ('classify', RandomForestClassifier(n_estimators=100))
+])
+
+# Fit and predict
+pipeline.fit(df[['title', 'description']], y)
+predictions = pipeline.predict(df_new[['title', 'description']])
+
+# Interpret clusters
+explainer = ClusterExplainer(
+    llm=ChatOpenAI(model='gpt-4o-mini'),
+    text_transformer=text_transformer,
+    observations='job postings',
+    text_fields='titles and descriptions'
+)
+
+gmm = pipeline.named_steps['reduce']
+cluster_labels = gmm.labels_
+
+# Cluster descriptions only
+result_df = explainer.explain(df, cluster_labels)
+
+# With outcome association + synthesis narrative
+result_df, global_stats, synthesis = explainer.explain(
+    df, cluster_labels,
+    y=y,
+    y_label='fraudulent posting (1=fraud, 0=legitimate)',
+    synthesize=True
+)
+
+# Include GMM cluster quality diagnostics in the association table
+obs_stats = gmm.assignment_confidence_stats(
+    pipeline.named_steps['embed'].transform(df)
+)
+result_df, global_stats, stat_assoc_df, synthesis = explainer.explain(
+    df, cluster_labels,
+    y=y,
+    y_label='fraudulent posting (1=fraud, 0=legitimate)',
+    observation_stats=obs_stats,
+    synthesize=True
+)
+```
+
+## Key Features
+
+- sklearn-compatible API (Pipeline, ColumnTransformer, GridSearchCV)
+- Access to 50+ embedding models via LangChain
+- Multi-column text handling with flexible concatenation
+- Optional L2 normalization of embedding vectors
+- Token and cost estimation before embedding API calls
+- GMM-based dimensionality reduction with per-cluster log-joint features
+- Optional marginal log-density feature for explicit outlier scoring
+- Per-observation cluster quality diagnostics (max posterior, entropy, log-joint margin, log density)
+- Automatic recursive summarization for arbitrarily large datasets
+- Cost estimation for LLM explanation calls
+- Outcome-based cluster characterization (binary and continuous outcomes)
+- User-supplied per-observation covariates in the association table
+- Synthesis narrative connecting cluster descriptions to outcome patterns
+- Blind labeling: cluster descriptions generated without knowledge of outcome vector
+
+## Citation
+
+Sharabiani, M.T.A., Mahani, A.S., Bottle, A. et al. (2025). GenAI exceeds clinical experts in predicting acute kidney injury following paediatric cardiopulmonary bypass. Scientific Reports, 15, 20847. https://doi.org/10.1038/s41598-025-04651-8

tabullm-1.0.0/README.md

@@ -0,0 +1,124 @@
+# TabuLLM
+
+Python package for feature extraction and interpretation of text columns in tabular data using large language models.
+
+## Overview
+
+TabuLLM integrates LLM-based text embeddings into scikit-learn pipelines for tabular datasets containing text columns. Built on LangChain and scikit-learn, it provides sklearn-compatible transformers for embedding, dimensionality reduction, and cluster interpretation.
+
+## Installation
+
+```bash
+pip install tabullm
+```
+
+Optional dependency groups provide extended functionality:
+
+```bash
+pip install tabullm[huggingface]   # HuggingFace embedding models
+pip install tabullm[aws]           # AWS Bedrock / Cohere
+pip install tabullm[kaggle]        # Kaggle dataset download (load_fraud)
+pip install tabullm[viz]           # Visualization utilities
+```
+
+## Core Components
+
+**TextColumnTransformer** - Wraps LangChain embedding models (OpenAI, Anthropic, HuggingFace, etc.) with a sklearn interface. Handles multiple text columns with configurable concatenation and optional L2 normalization (`normalize=True`). Use `estimate_tokens()` to preview API cost before embedding.
+
+**GMMFeatureExtractor** - Extends sklearn's `GaussianMixture` with a `transform()` method that returns per-cluster log-joint features $\log p(\mathbf{x}, c_k)$ — the quantity the GMM maximises for hard assignment — enabling use in sklearn pipelines. An optional `include_log_density` parameter appends the marginal log-density as an explicit outlier score. A companion `assignment_confidence_stats()` method returns per-observation cluster quality diagnostics (`max_posterior`, `entropy`, `log_joint_margin`, `log_density`).
+
+**SphericalKMeans** - K-means clustering with cosine distance for L2-normalized embeddings. For normalized embeddings, mathematically equivalent to sklearn's `KMeans`. Available as an alternative hard-clustering option when GMM-based features are not needed.
+
+**ClusterExplainer** - Generates natural language cluster descriptions using LLMs with automatic recursive summarization that scales to arbitrarily large datasets. Supports:
+- Cost preview (`preview=True`) before LLM calls
+- Optional outcome-based statistical testing (`y`) to characterize which clusters associate with a target variable
+- Per-observation covariates (`observation_stats`) — e.g., from `assignment_confidence_stats()` — appended to the association table
+- A synthesis step (`synthesize=True`) that produces a coherent interpretive narrative across all cluster results
+- An outcome label (`y_label`) used only in the synthesis prompt; cluster descriptions are generated without knowledge of `y` (*blind labeling* principle)
+
+**load_fraud()** - Data utility that downloads and caches the fraud detection dataset from Kaggle (requires `tabullm[kaggle]`), returning features, labels, and metadata.
+
+## Quick Example
+
+```python
+from tabullm import TextColumnTransformer, GMMFeatureExtractor, ClusterExplainer
+from langchain_huggingface import HuggingFaceEmbeddings
+from langchain_openai import ChatOpenAI
+from sklearn.pipeline import Pipeline
+from sklearn.ensemble import RandomForestClassifier
+
+# Embed text columns
+embedding_model = HuggingFaceEmbeddings(
+    model_name='sentence-transformers/all-MiniLM-L6-v2'
+)
+text_transformer = TextColumnTransformer(
+    model=embedding_model,
+    colnames={'title': 'Title', 'description': 'Description'}
+)
+
+# Build pipeline: Embed → Reduce → Classify
+pipeline = Pipeline([
+    ('embed', text_transformer),
+    ('reduce', GMMFeatureExtractor(n_components=10)),
+    ('classify', RandomForestClassifier(n_estimators=100))
+])
+
+# Fit and predict
+pipeline.fit(df[['title', 'description']], y)
+predictions = pipeline.predict(df_new[['title', 'description']])
+
+# Interpret clusters
+explainer = ClusterExplainer(
+    llm=ChatOpenAI(model='gpt-4o-mini'),
+    text_transformer=text_transformer,
+    observations='job postings',
+    text_fields='titles and descriptions'
+)
+
+gmm = pipeline.named_steps['reduce']
+cluster_labels = gmm.labels_
+
+# Cluster descriptions only
+result_df = explainer.explain(df, cluster_labels)
+
+# With outcome association + synthesis narrative
+result_df, global_stats, synthesis = explainer.explain(
+    df, cluster_labels,
+    y=y,
+    y_label='fraudulent posting (1=fraud, 0=legitimate)',
+    synthesize=True
+)
+
+# Include GMM cluster quality diagnostics in the association table
+obs_stats = gmm.assignment_confidence_stats(
+    pipeline.named_steps['embed'].transform(df)
+)
+result_df, global_stats, stat_assoc_df, synthesis = explainer.explain(
+    df, cluster_labels,
+    y=y,
+    y_label='fraudulent posting (1=fraud, 0=legitimate)',
+    observation_stats=obs_stats,
+    synthesize=True
+)
+```
+
+## Key Features
+
+- sklearn-compatible API (Pipeline, ColumnTransformer, GridSearchCV)
+- Access to 50+ embedding models via LangChain
+- Multi-column text handling with flexible concatenation
+- Optional L2 normalization of embedding vectors
+- Token and cost estimation before embedding API calls
+- GMM-based dimensionality reduction with per-cluster log-joint features
+- Optional marginal log-density feature for explicit outlier scoring
+- Per-observation cluster quality diagnostics (max posterior, entropy, log-joint margin, log density)
+- Automatic recursive summarization for arbitrarily large datasets
+- Cost estimation for LLM explanation calls
+- Outcome-based cluster characterization (binary and continuous outcomes)
+- User-supplied per-observation covariates in the association table
+- Synthesis narrative connecting cluster descriptions to outcome patterns
+- Blind labeling: cluster descriptions generated without knowledge of outcome vector
+
+## Citation
+
+Sharabiani, M.T.A., Mahani, A.S., Bottle, A. et al. (2025). GenAI exceeds clinical experts in predicting acute kidney injury following paediatric cardiopulmonary bypass. Scientific Reports, 15, 20847. https://doi.org/10.1038/s41598-025-04651-8

tabullm-1.0.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = { find = { include = ["tabullm*"] } }
+
+[project]
+name = "tabullm"
+version = "1.0.0"
+description = "Seamless Feature Extraction and Interpretation of Text Columns in Tabular Data Using Large Language Models"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Alireza S. Mahani, Mansour T.A. Sharabiani", email = "alireza.s.mahani@gmail.com" }
+]
+keywords = ["text embedding", "large language models", "feature engineering", "cross-validation"]
+dependencies = [
+    "numpy>=1.24",
+    "pandas>=2.0",
+    "scikit-learn>=1.3",
+    "scipy>=1.10",
+    "pydantic>=2.0",
+    "langchain>=0.1",
+    "langchain-core>=0.1",
+    "langchain-community>=0.1",
+    "pillow>=12.1.1",  # Security: CVE fix
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0"
+]
+kaggle = [
+    "kaggle>=1.6"
+]

tabullm-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tabullm-1.0.0/tabullm/__init__.py

@@ -0,0 +1,25 @@
+"""
+TabuLLM: Feature Extraction and Interpretation of Text Columns in Tabular Data Using LLMs
+
+A Python package for seamless integration of text embeddings into tabular ML pipelines,
+with tools for clustering and LLM-based interpretation.
+"""
+
+__version__ = "1.0.0"
+
+# Core components
+from .embed import TextColumnTransformer
+from .cluster import SphericalKMeans, GMMFeatureExtractor
+from .explain import ClusterExplainer
+
+# Data utilities
+from .data import load_fraud
+
+__all__ = [
+    "TextColumnTransformer",
+    "SphericalKMeans",
+    "GMMFeatureExtractor",
+    "ClusterExplainer",
+    "load_fraud",
+    "__version__",
+]

tabullm-1.0.0/tabullm/cluster/__init__.py

@@ -0,0 +1,32 @@
+"""
+Clustering and feature extraction for text embeddings
+
+This module provides clustering algorithms optimized for text embeddings,
+including spherical k-means (cosine distance) and GMM-based feature extraction.
+
+Classes
+-------
+SphericalKMeans : Clustering with cosine distance for normalized embeddings
+GMMFeatureExtractor : Transform embeddings to Mahalanobis distances for ML pipelines
+
+Examples
+--------
+>>> from tabullm.cluster import SphericalKMeans, GMMFeatureExtractor
+>>> from sklearn.pipeline import Pipeline
+>>>
+>>> # Spherical k-means clustering
+>>> kmeans = SphericalKMeans(n_clusters=5)
+>>> labels = kmeans.fit_predict(embeddings)
+>>>
+>>> # GMM feature extraction in pipeline
+>>> pipeline = Pipeline([
+...     ('gmm', GMMFeatureExtractor(n_components=10)),
+...     ('clf', RandomForestClassifier())
+... ])
+"""
+
+# Cluster submodule exports
+from .spherical_kmeans import SphericalKMeans
+from .gmm_features import GMMFeatureExtractor
+
+__all__ = ['SphericalKMeans', 'GMMFeatureExtractor']

tabullm-1.0.0/tabullm/cluster/gmm_features.py

@@ -0,0 +1,237 @@
+"""
+Gaussian Mixture Model feature extraction for embeddings.
+
+Provides GMMFeatureExtractor, which adds transform() to sklearn's GaussianMixture
+for feature extraction. Returns per-cluster log-joint features log p(x, c_k),
+the quantity the GMM maximises for hard assignment.
+
+Key contribution: sklearn's GaussianMixture lacks transform() - only has predict()
+and predict_proba(). This fills that gap for ML pipelines.
+"""
+
+import numpy as np
+import pandas as pd
+from sklearn.base import BaseEstimator, TransformerMixin
+from sklearn.mixture import GaussianMixture
+from sklearn.utils.validation import check_array, check_is_fitted
+
+
+class GMMFeatureExtractor(BaseEstimator, TransformerMixin):
+    """
+    Extract features using Gaussian Mixture Model log-joint probabilities.
+
+    ``transform()`` returns an (n_samples, K) array of per-cluster log-joints
+
+        ℓ_k(x) = log p(x, c_k) = log π_k + log p(x | c_k)
+
+    where log p(x | c_k) is the Gaussian log-likelihood under component k.
+    This is the quantity the GMM maximises for hard assignment
+    (k* = argmax_k ℓ_k), so features are in exact correspondence with the
+    model's own criterion.  Posterior probabilities are a softmax of these
+    features.
+
+    Adds transform() method that sklearn's GaussianMixture lacks, enabling
+    use in feature extraction pipelines.
+
+    Parameters
+    ----------
+    n_components : int, default=10
+        Number of mixture components.
+
+    covariance_type : {'full', 'tied', 'diag', 'spherical'}, default='full'
+        Type of covariance parameters.
+
+    n_init : int, default=3
+        Number of initializations to perform.
+
+    random_state : int, default=None
+        Random seed for reproducibility.
+
+    include_log_density : bool, default=False
+        If True, append log p(x) = log Σ_k exp(ℓ_k(x)) as a (K+1)-th column.
+        This is the log marginal likelihood — how well the overall mixture
+        explains x.  It is a deterministic function of the K log-joints
+        (log-sum-exp), so it adds no information for expressive nonlinear
+        models but provides an explicit outlier score for linear ones.
+
+    **gmm_kwargs
+        Additional parameters for GaussianMixture.
+
+    Attributes
+    ----------
+    gmm_ : GaussianMixture
+        Fitted Gaussian Mixture Model.
+
+    means_ : array, shape (n_components, n_features)
+        Component means.
+
+    covariances_ : array
+        Component covariances.
+
+    labels_ : array, shape (n_samples,)
+        Cluster labels for each sample from the training set.
+
+    Examples
+    --------
+    >>> from tabullm import TextColumnTransformer, GMMFeatureExtractor
+    >>> from sklearn.pipeline import Pipeline
+    >>>
+    >>> pipeline = Pipeline([
+    ...     ('embed', TextColumnTransformer(model=model, text_columns=['text'])),
+    ...     ('gmm', GMMFeatureExtractor(n_components=10)),
+    ...     ('clf', RandomForestClassifier())
+    ... ])
+    """
+
+    def __init__(self, n_components=10, covariance_type='full',
+                 n_init=3, random_state=None, include_log_density=False,
+                 **gmm_kwargs):
+        self.n_components = n_components
+        self.covariance_type = covariance_type
+        self.n_init = n_init
+        self.random_state = random_state
+        self.include_log_density = include_log_density
+        self.gmm_kwargs = gmm_kwargs
+
+    def fit(self, X, y=None):
+        """Fit GMM to data."""
+        X = check_array(X)
+
+        self.gmm_ = GaussianMixture(
+            n_components=self.n_components,
+            covariance_type=self.covariance_type,
+            n_init=self.n_init,
+            random_state=self.random_state,
+            **self.gmm_kwargs
+        )
+        self.gmm_.fit(X)
+
+        self.means_ = self.gmm_.means_
+        self.covariances_ = self.gmm_.covariances_
+        self.n_components_ = self.n_components
+        self.labels_ = self.gmm_.predict(X)
+
+        return self
+
+    def transform(self, X):
+        """
+        Transform X to per-cluster log-joint features.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_samples, n_features)
+
+        Returns
+        -------
+        ndarray of shape (n_samples, K) or (n_samples, K+1)
+            Per-cluster log p(x, c_k) for k = 0 … K-1, plus log p(x) as
+            the final column when ``include_log_density=True``.
+        """
+        check_is_fitted(self, 'gmm_')
+        X = check_array(X)
+        log_joints = self.gmm_._estimate_weighted_log_prob(X)   # (n_samples, K)
+        if self.include_log_density:
+            log_density = self.gmm_.score_samples(X).reshape(-1, 1)
+            return np.hstack([log_joints, log_density])
+        return log_joints
+
+    def get_feature_names_out(self, input_features=None):
+        """
+        Feature names: ``lj_0 … lj_{K-1}``, plus ``log_density`` when
+        ``include_log_density=True``.
+        """
+        check_is_fitted(self, 'gmm_')
+        names = [f'lj_{k}' for k in range(self.n_components_)]
+        if self.include_log_density:
+            names.append('log_density')
+        return np.array(names)
+
+    def predict(self, X):
+        """Predict cluster labels."""
+        check_is_fitted(self, 'gmm_')
+        return self.gmm_.predict(check_array(X))
+
+    def assignment_confidence_stats(self, X):
+        """
+        Compute per-observation assignment confidence statistics.
+
+        Returns four metrics that characterise how confidently and
+        unambiguously the fitted GMM assigns each observation to a cluster,
+        plus the marginal log-density as an outlier score.
+        All four are scalars per observation and can be aggregated to
+        cluster-level summaries via ``groupby(cluster_labels).mean()``.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_samples, n_features)
+            Data to score. Must have the same number of features as the
+            training data.
+
+        Returns
+        -------
+        pd.DataFrame of shape (n_samples, 4)
+            Columns:
+
+            ``max_posterior``
+                Maximum posterior probability :math:`\\max_k p(k \\mid x)`.
+                Range :math:`(1/K, 1]`. Higher means the model is more
+                certain about the cluster assignment.
+
+            ``entropy``
+                Shannon entropy :math:`-\\sum_k p(k \\mid x) \\log p(k \\mid x)`
+                of the posterior distribution.
+                Range :math:`[0, \\log K]`. Lower means the probability mass
+                is concentrated on fewer clusters.
+
+            ``log_joint_margin``
+                Difference between the top-1 and top-2 per-cluster log joints
+                :math:`\\ell_{k^*}(x) - \\max_{j \\neq k^*} \\ell_j(x)`.
+                Range :math:`[0, \\infty)`. Larger means the assigned cluster
+                is more decisively preferred over its nearest rival.
+
+            ``log_density``
+                Log marginal likelihood :math:`\\log p(x) = \\log \\sum_k e^{\\ell_k(x)}`.
+                Range :math:`(-\\infty, 0]`. Captures how well the overall GMM
+                explains this observation; large negative values flag outliers.
+                Orthogonal to the three assignment metrics above: two observations
+                can share the same ``max_posterior`` yet have very different
+                ``log_density``.
+
+        Examples
+        --------
+        >>> stats = gmm.assignment_confidence_stats(X_embeddings)
+        >>> stats.describe()
+
+        >>> # Per-cluster rollup
+        >>> stats.groupby(cluster_labels).mean()
+
+        >>> # Feed into ClusterExplainer
+        >>> explainer.explain(X, cluster_labels, y=y, observation_stats=stats)
+        """
+        check_is_fitted(self, 'gmm_')
+        X = check_array(X)
+
+        # (n_samples, K) posterior probabilities
+        posteriors = self.gmm_.predict_proba(X)
+
+        # 1. Assignment confidence: max posterior per observation
+        assignment_confidence = posteriors.max(axis=1)
+
+        # 2. Entropy: -sum_k p(k|x) log p(k|x)
+        log_posteriors = np.log(np.clip(posteriors, 1e-10, 1.0))
+        entropy = -(posteriors * log_posteriors).sum(axis=1)
+
+        # 3. Log-joint margin: top-1 minus top-2 log joint
+        log_joints = self.gmm_._estimate_weighted_log_prob(X)  # (n_samples, K)
+        sorted_lj = np.sort(log_joints, axis=1)[:, ::-1]
+        log_joint_margin = sorted_lj[:, 0] - sorted_lj[:, 1]
+
+        # 4. Log density: log p(x) = log-sum-exp of log joints
+        log_density = self.gmm_.score_samples(X)
+
+        return pd.DataFrame({
+            'max_posterior': assignment_confidence,
+            'entropy': entropy,
+            'log_joint_margin': log_joint_margin,
+            'log_density': log_density,
+        })