pearl-H 0.1.3

PEARL: Prototype-guided Embedding Refinement via Adaptive Representation Learning

PEARL (pearl-H)

PEARL (Prototype-Enhanced Alignment for Label-efficient Representation Learning) is a lightweight, label-efficient post-processing method for refining fixed embeddings (e.g., sentence/document embeddings) to improve local neighborhood geometry for similarity-driven systems such as kNN retrieval, case-based routing, and embedding-based classifiers.

This package implements a practical PEARL workflow:

• Signal extraction: learns a small refinement network to separate class-discriminative signal from residual variation while preserving the original embedding dimensionality.
• Prototype-augmented features (PAF): fits per-class prototypes (KMeans) and augments embeddings with prototype/centroid similarity features (useful for downstream lightweight models).

Installation

pip install pearl-H

Quickstart (recommended)

PEARL assumes you already have embeddings X from a fixed encoder. You provide a small labeled subset (X_train, y_train) to fit the refinement, then transform any embeddings for retrieval/classification.

import numpy as np
from pearl import PEARLPipeline

# X_train: [N, D] numpy array of embeddings
# y_train: [N] integer labels in [0, n_classes)
pipeline = PEARLPipeline(n_classes=10, device="auto")

pipeline.fit(X_train, y_train, X_val=X_val, y_val=y_val, epochs=100, patience=20)

# Choose the output you want:
X_enhanced = pipeline.transform(X_test, mode="enhanced")  # same dim as input
X_paf = pipeline.transform(X_test, mode="paf")            # augmented with prototype features

Core API

• PEARLPipeline: end-to-end training + transformation (fit, transform, fit_transform).
• SignalExtractorTrainer: trains the refinement model; produces same-dimensional enhanced embeddings.
• PAFAugmentor: appends prototype/centroid similarity features to embeddings.
• RAGClassifierWrapper: retrieval-augmented classifier over embeddings (kNN retrieval + cross-attention).

Input conventions

• Embeddings: numpy.ndarray of shape [N, D] (float32/float64).
• Labels: numpy.ndarray of shape [N] with integer class ids 0..n_classes-1.
• Device: "auto", "cuda", "mps", "cpu" (or a torch.device).

Paper & citation

If you use PEARL in academic work, please cite the paper:

@misc{zhang2026pearlprototypeenhancedalignmentlabelefficient,
      title={PEARL: Prototype-Enhanced Alignment for Label-Efficient Representation Learning with Deployment-Driven Insights from Digital Governance Communication Systems},
      author={Ruiyu Zhang and Lin Nie and Wai-Fung Lam and Qihao Wang and Xin Zhao},
      year={2026},
      eprint={2601.17495},
      archivePrefix={arXiv},
      primaryClass={cs.LG},
      url={https://arxiv.org/abs/2601.17495},
}

License

MIT License. See LICENSE.