# PEARL (`pearl-H`)

PEARL (**P**rototype-**E**nhanced **A**lignment for **L**abel-efficient **R**epresentation **L**earning) 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

```bash
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.

```python
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:

```bibtex
@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`.
