pubmlp 0.1.0__tar.gz

pubmlp-0.1.0/CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+title: "pubmlp: Multimodal publication classifier with LLM and deep learning"
+authors:
+  - family-names: Shin
+    given-names: Mikyung
+    email: shin.mikyung@gmail.com
+    orcid: "https://orcid.org/0000-0001-7907-9193"
+version: "0.1.0"
+date-released: "2026-02-22"
+license: MIT
+url: "https://github.com/mshin77/pubmlp"
+repository-code: "https://github.com/mshin77/pubmlp"
+keywords:
+  - systematic review
+  - screening
+  - transformer
+  - classification
+  - Python

pubmlp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikyung Shin
+
+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.

pubmlp-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include CITATION.cff
+include LICENSE
+include README.md

pubmlp-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: pubmlp
+Version: 0.1.0
+Summary: Multimodal publication classifier with LLM and deep learning
+Author-email: Mikyung Shin <shin.mikyung@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://mshin77.github.io/pubmlp
+Project-URL: Repository, https://github.com/mshin77/pubmlp
+Project-URL: Documentation, https://mshin77.github.io/pubmlp
+Project-URL: Issues, https://github.com/mshin77/pubmlp/issues
+Keywords: systematic-review,screening,transformer,classification,bibliometrics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.3.0
+Requires-Dist: transformers>=4.30.0
+Requires-Dist: sentence-transformers>=2.2.0
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: tqdm>=4.65.0
+Requires-Dist: matplotlib>=3.7.0
+Requires-Dist: seaborn>=0.12.0
+Provides-Extra: screening
+Requires-Dist: openpyxl>=3.1.0; extra == "screening"
+Requires-Dist: nltk>=3.8.0; extra == "screening"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=8.2; extra == "docs"
+Requires-Dist: pydata-sphinx-theme>=0.16; extra == "docs"
+Requires-Dist: myst-parser>=3.0; extra == "docs"
+Dynamic: license-file
+
+[![PyPI version](https://img.shields.io/pypi/v/pubmlp)](https://pypi.org/project/pubmlp/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pubmlp)](https://pypi.org/project/pubmlp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Multimodal publication classifier with LLM and deep learning. Fuses transformer embeddings with tabular features through a multilayer perceptron (MLP) for human-in-the-loop screening workflows.
+
+## Installation
+
+```bash
+pip install pubmlp
+```
+
+With optional dependencies:
+
+```bash
+pip install pubmlp[screening]  # screening tools (openpyxl, nltk)
+pip install pubmlp[dev]        # development (pytest, ruff)
+pip install pubmlp[docs]       # documentation (sphinx)
+```
+
+From GitHub:
+
+```bash
+pip install git+https://github.com/mshin77/pubmlp.git
+```
+
+## Getting Started
+
+See [Quick Start](https://mshin77.github.io/pubmlp/getting-started.html) and [Screening Workflow](https://mshin77.github.io/pubmlp/vignettes/screening-workflow.html) for tutorials.
+
+## Citation
+
+- Shin, M. (2026). *pubmlp: Multimodal publication classifier with LLM and deep learning* (Python package version 0.1.0) [Computer software]. <https://github.com/mshin77/pubmlp>

pubmlp-0.1.0/README.md

@@ -0,0 +1,33 @@
+[![PyPI version](https://img.shields.io/pypi/v/pubmlp)](https://pypi.org/project/pubmlp/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pubmlp)](https://pypi.org/project/pubmlp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Multimodal publication classifier with LLM and deep learning. Fuses transformer embeddings with tabular features through a multilayer perceptron (MLP) for human-in-the-loop screening workflows.
+
+## Installation
+
+```bash
+pip install pubmlp
+```
+
+With optional dependencies:
+
+```bash
+pip install pubmlp[screening]  # screening tools (openpyxl, nltk)
+pip install pubmlp[dev]        # development (pytest, ruff)
+pip install pubmlp[docs]       # documentation (sphinx)
+```
+
+From GitHub:
+
+```bash
+pip install git+https://github.com/mshin77/pubmlp.git
+```
+
+## Getting Started
+
+See [Quick Start](https://mshin77.github.io/pubmlp/getting-started.html) and [Screening Workflow](https://mshin77.github.io/pubmlp/vignettes/screening-workflow.html) for tutorials.
+
+## Citation
+
+- Shin, M. (2026). *pubmlp: Multimodal publication classifier with LLM and deep learning* (Python package version 0.1.0) [Computer software]. <https://github.com/mshin77/pubmlp>

pubmlp-0.1.0/pubmlp/__init__.py

@@ -0,0 +1,47 @@
+"""
+PubMLP: Multimodal publication classifier with LLM and deep learning.
+
+Fuses transformer embeddings with tabular features through a multilayer
+perceptron (MLP) for human-in-the-loop screening workflows.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Mikyung Shin"
+__license__ = "MIT"
+
+from .config import Config, default_config, fast_config, robust_config, hitl_config, domain_configs, sentence_transformer_models
+from .model import PubMLP
+from .train import train_evaluate_model, calculate_loss, calculate_accuracy, calculate_pos_weight
+from .predict import predict_model, get_predictions_and_labels, flag_uncertain
+from .metrics import calculate_evaluation_metrics
+from .preprocess import preprocess_dataset, create_dataloader, split_data, CustomDataset, collate_fn, FittedTransforms
+from .plotting import plot_results
+from .utils import get_device, auto_batch_size, load_data, unpack_batch
+from .cv import cross_validate
+from .calibration import TemperatureScaling, collect_logits, calibrate_model
+from .audit import AuditTrail, AuditEntry, interpret_kappa, summarize_human_decisions, generate_prisma_report
+from .active_learning import ALState, select_query_batch, create_review_batch, compare_reviewers, merge_human_labels
+from .stopping import StoppingState, should_stop, update_stopping_state, generate_stopping_report, calculate_wss, transition_phase, estimate_recall
+from .screening import regex_screen, extract_window_evidence, extract_sentence_evidence, extract_all_evidence, format_evidence_display, calculate_semantic_scores
+from .sample import create_stratified_sample, save_sample_excel, apply_conditional_formatting, count_pattern_matches, highlight_pattern_matches
+
+__all__ = [
+    'Config', 'default_config', 'fast_config', 'robust_config', 'hitl_config', 'domain_configs', 'sentence_transformer_models',
+    'PubMLP',
+    'train_evaluate_model', 'calculate_loss', 'calculate_accuracy', 'calculate_pos_weight',
+    'predict_model', 'get_predictions_and_labels', 'flag_uncertain',
+    'calculate_evaluation_metrics',
+    'preprocess_dataset', 'create_dataloader', 'split_data', 'CustomDataset', 'collate_fn', 'FittedTransforms',
+    'plot_results',
+    'get_device', 'auto_batch_size', 'load_data', 'unpack_batch',
+    'cross_validate',
+    'TemperatureScaling', 'collect_logits', 'calibrate_model',
+    'AuditTrail', 'AuditEntry', 'interpret_kappa', 'summarize_human_decisions', 'generate_prisma_report',
+    'ALState', 'select_query_batch', 'create_review_batch', 'compare_reviewers', 'merge_human_labels',
+    'StoppingState', 'should_stop', 'update_stopping_state', 'generate_stopping_report', 'calculate_wss',
+    'transition_phase', 'estimate_recall',
+    'regex_screen', 'extract_window_evidence', 'extract_sentence_evidence', 'extract_all_evidence',
+    'format_evidence_display', 'calculate_semantic_scores',
+    'create_stratified_sample', 'save_sample_excel', 'apply_conditional_formatting',
+    'count_pattern_matches', 'highlight_pattern_matches',
+]

pubmlp-0.1.0/pubmlp/active_learning.py

@@ -0,0 +1,78 @@
+import numpy as np
+from dataclasses import dataclass, field, asdict
+from sklearn.metrics import cohen_kappa_score
+
+
+@dataclass
+class ALState:
+    labeled_indices: list = field(default_factory=list)
+    unlabeled_indices: list = field(default_factory=list)
+    iteration: int = 0
+    history: list = field(default_factory=list)
+
+    def to_dict(self):
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d):
+        return cls(**d)
+
+
+def rank_by_uncertainty(probabilities):
+    """Most uncertain (closest to 0.5) first."""
+    probs = np.asarray(probabilities)
+    return np.argsort(np.abs(probs - 0.5))
+
+
+def rank_by_random(n, seed=42):
+    rng = np.random.RandomState(seed)
+    indices = np.arange(n)
+    rng.shuffle(indices)
+    return indices
+
+
+def rank_by_max_relevance(probabilities):
+    """Highest probability (most likely relevant) first."""
+    return np.argsort(-np.asarray(probabilities))
+
+
+def select_query_batch(probabilities, strategy='uncertainty', batch_size=20, seed=42):
+    probs = np.asarray(probabilities)
+    ranked = {
+        'uncertainty': lambda: rank_by_uncertainty(probs),
+        'random': lambda: rank_by_random(len(probs), seed),
+        'max_relevance': lambda: rank_by_max_relevance(probs),
+    }[strategy]()
+    return ranked[:batch_size]
+
+
+def create_review_batch(df, indices, probabilities):
+    """Subset df for human review, adding model probability and prediction columns."""
+    probs = np.asarray(probabilities)
+    batch = df.iloc[indices].copy()
+    batch['model_probability'] = probs[indices]
+    batch['model_prediction'] = (probs[indices] >= 0.5).astype(int)
+    return batch
+
+
+def merge_human_labels(df, review_batch, label_col='human_label'):
+    """Merge human decisions from review batch back into main df."""
+    df = df.copy()
+    if label_col not in df.columns:
+        df[label_col] = np.nan
+    df.loc[review_batch.index, label_col] = review_batch[label_col]
+    return df
+
+
+def compare_reviewers(model_predictions, human_labels):
+    """Compare model vs human reviewer decisions."""
+    model_preds = np.asarray(model_predictions)
+    human = np.asarray(human_labels)
+    agreed = np.sum(model_preds == human)
+    kappa = cohen_kappa_score(model_preds, human) if len(set(model_preds) | set(human)) > 1 else 1.0
+    disagreement_indices = np.where(model_preds != human)[0]
+    return {
+        'agreement_rate': agreed / len(human),
+        'kappa': kappa,
+        'disagreement_indices': disagreement_indices.tolist(),
+    }

pubmlp-0.1.0/pubmlp/audit.py

@@ -0,0 +1,168 @@
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+
+import pandas as pd
+
+from .active_learning import compare_reviewers
+
+
+@dataclass
+class AuditEntry:
+    record_id: str
+    model_prediction: int
+    model_probability: float
+    human_label: int = None
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    reviewer_id: str = None
+    phase: str = 'screening'
+    notes: str = ''
+
+
+class AuditTrail:
+    def __init__(self):
+        self.entries = []
+
+    def log_decision(self, record_id, prediction, probability, phase='screening',
+                     reviewer_id=None):
+        self.entries.append(AuditEntry(
+            record_id=str(record_id),
+            model_prediction=int(prediction),
+            model_probability=float(probability),
+            phase=phase,
+            reviewer_id=reviewer_id,
+        ))
+
+    def log_batch(self, record_ids, predictions, probabilities, phase='screening',
+                  reviewer_id=None):
+        for rid, pred, prob in zip(record_ids, predictions, probabilities):
+            self.log_decision(rid, pred, prob, phase, reviewer_id)
+
+    def update_human_label(self, record_id, human_label, reviewer_id=None, notes=''):
+        for entry in self.entries:
+            if entry.record_id == str(record_id):
+                entry.human_label = int(human_label)
+                entry.reviewer_id = reviewer_id
+                entry.notes = notes
+                entry.timestamp = datetime.now(timezone.utc).isoformat()
+                return
+        raise KeyError(f"Record {record_id} not found in audit trail")
+
+    def get_disagreements(self):
+        return [e for e in self.entries
+                if e.human_label is not None and e.model_prediction != e.human_label]
+
+    def calculate_agreement(self):
+        reviewed = [e for e in self.entries if e.human_label is not None]
+        if not reviewed:
+            return {'total': 0, 'agreed': 0, 'disagreed': 0, 'kappa': None}
+        model_preds = [e.model_prediction for e in reviewed]
+        human_labels = [e.human_label for e in reviewed]
+        result = compare_reviewers(model_preds, human_labels)
+        agreed = int(result['agreement_rate'] * len(reviewed))
+        return {
+            'total': len(reviewed),
+            'agreed': agreed,
+            'disagreed': len(reviewed) - agreed,
+            'kappa': result['kappa'],
+        }
+
+    def to_dataframe(self):
+        return pd.DataFrame([asdict(e) for e in self.entries])
+
+    def export_csv(self, path):
+        self.to_dataframe().to_csv(path, index=False)
+
+    def to_dict(self):
+        return {'entries': [asdict(e) for e in self.entries]}
+
+    @classmethod
+    def from_dict(cls, d):
+        obj = cls()
+        obj.entries = [AuditEntry(**e) for e in d['entries']]
+        return obj
+
+
+def interpret_kappa(kappa):
+    if kappa < 0:
+        return 'poor'
+    if kappa <= 0.20:
+        return 'slight'
+    if kappa <= 0.40:
+        return 'fair'
+    if kappa <= 0.60:
+        return 'moderate'
+    if kappa <= 0.80:
+        return 'substantial'
+    return 'almost perfect'
+
+
+def summarize_human_decisions(audit_trail, uncertainty_low=0.3, uncertainty_high=0.7):
+    """Summarize human reviewer decisions against model predictions."""
+    entries = audit_trail.entries
+    reviewed = [e for e in entries if e.human_label is not None]
+    overrides = [e for e in reviewed if e.model_prediction != e.human_label]
+    return {
+        'total': len(entries),
+        'included': sum(1 for e in entries if e.model_prediction == 1),
+        'excluded': sum(1 for e in entries if e.model_prediction == 0),
+        'uncertain': sum(1 for e in entries if uncertainty_low < e.model_probability < uncertainty_high),
+        'human_reviewed': len(reviewed),
+        'human_overrides': len(overrides),
+    }
+
+
+# PRISMA 2020 Item 8 + trAIce M3/M8/M9/R1/R2 (screening-scoped)
+prisma_screening_items = {
+    'item_8': 'Selection process: automation tools used',
+    'M3': 'Purpose/Stage: AI applied at title/abstract screening',
+    'M8': 'Human-AI Interaction: human reviewer validation process',
+    'M9': 'Performance Evaluation: screening model metrics',
+    'R1': 'Study Selection: AI vs human exclusion counts in flow',
+    'R2': 'Performance Metrics: AI screening performance results',
+}
+
+
+def generate_prisma_report(audit_trail, config=None):
+    """Populate PRISMA Item 8 + screening-relevant trAIce items from audit data."""
+    uncertainty_low = getattr(config, 'uncertainty_low', 0.3) if config else 0.3
+    uncertainty_high = getattr(config, 'uncertainty_high', 0.7) if config else 0.7
+    summary = summarize_human_decisions(audit_trail, uncertainty_low, uncertainty_high)
+    agreement = audit_trail.calculate_agreement()
+
+    report = {
+        'item_8': {
+            'description': prisma_screening_items['item_8'],
+            'tool': 'pubmlp',
+            'stage': 'title/abstract screening',
+            'model': getattr(config, 'embedding_model', None) if config else None,
+            'calibration': getattr(config, 'calibration_method', None) if config else None,
+        },
+        'M3': {
+            'description': prisma_screening_items['M3'],
+            'stage': 'title/abstract screening',
+            'strategy': getattr(config, 'al_query_strategy', None) if config else None,
+        },
+        'M8': {
+            'description': prisma_screening_items['M8'],
+            'human_reviewed': summary['human_reviewed'],
+            'human_overrides': summary['human_overrides'],
+            'agreement_kappa': agreement['kappa'],
+            'kappa_interpretation': interpret_kappa(agreement['kappa']) if agreement['kappa'] is not None else None,
+        },
+        'M9': {
+            'description': prisma_screening_items['M9'],
+            'total_screened': summary['total'],
+            'uncertain_flagged': summary['uncertain'],
+        },
+        'R1': {
+            'description': prisma_screening_items['R1'],
+            'model_included': summary['included'],
+            'model_excluded': summary['excluded'],
+            'human_overrides': summary['human_overrides'],
+        },
+        'R2': {
+            'description': prisma_screening_items['R2'],
+            'agreement': agreement,
+        },
+    }
+    return report

pubmlp-0.1.0/pubmlp/calibration.py

@@ -0,0 +1,88 @@
+import torch
+import torch.nn as nn
+import torch.optim as optim
+
+from .utils import unpack_batch
+
+
+def collect_logits(model, dataloader, device):
+    """Run model in eval mode and collect raw logits + labels."""
+    model.eval()
+    all_logits, all_labels = [], []
+    with torch.no_grad():
+        for batch in dataloader:
+            input_ids, attention_mask, categorical_tensor, numeric_tensor, labels, texts = unpack_batch(batch, device)
+            logits = model(input_ids, attention_mask, categorical_tensor, numeric_tensor, texts)
+            all_logits.append(logits)
+            all_labels.append(labels)
+    return torch.cat(all_logits), torch.cat(all_labels)
+
+
+class TemperatureScaling:
+    """Per-label temperature scaling. Works for single and multi-label."""
+
+    def __init__(self):
+        self.temperature = None
+
+    def fit(self, logits, labels, lr=0.01, max_iter=50):
+        """Optimize temperature via NLL loss using LBFGS."""
+        num_labels = logits.shape[-1] if logits.dim() > 1 else 1
+
+        if num_labels == 1:
+            logits_flat = logits.view(-1)
+            labels_flat = labels.view(-1).float()
+            log_temp = nn.Parameter(torch.zeros(1, device=logits.device))
+            criterion = nn.BCEWithLogitsLoss()
+            optimizer = optim.LBFGS([log_temp], lr=lr, max_iter=max_iter)
+
+            def closure():
+                optimizer.zero_grad()
+                loss = criterion(logits_flat / log_temp.exp(), labels_flat)
+                loss.backward()
+                return loss
+
+            optimizer.step(closure)
+            self.temperature = log_temp.exp().item()
+        else:
+            # Per-label temperature
+            temps = []
+            criterion = nn.BCEWithLogitsLoss()
+            for i in range(num_labels):
+                log_temp = nn.Parameter(torch.zeros(1, device=logits.device))
+                optimizer = optim.LBFGS([log_temp], lr=lr, max_iter=max_iter)
+                col_logits = logits[:, i]
+                col_labels = labels[:, i].float()
+
+                def closure(lt=log_temp, l=col_logits, lb=col_labels, opt=optimizer):
+                    opt.zero_grad()
+                    loss = criterion(l / lt.exp(), lb)
+                    loss.backward()
+                    return loss
+
+                optimizer.step(closure)
+                temps.append(log_temp.exp().item())
+            self.temperature = temps
+        return self
+
+    def transform(self, logits):
+        if isinstance(self.temperature, list):
+            temp_tensor = torch.tensor(self.temperature, device=logits.device).unsqueeze(0)
+            return logits / temp_tensor
+        return logits / self.temperature
+
+    def to_dict(self):
+        return {'temperature': self.temperature}
+
+    @classmethod
+    def from_dict(cls, d):
+        obj = cls()
+        obj.temperature = d['temperature']
+        return obj
+
+
+def calibrate_model(model, dataloader, device):
+    """Collect logits and fit temperature scaling."""
+    logits, labels = collect_logits(model, dataloader, device)
+    scaler = TemperatureScaling()
+    scaler.fit(logits, labels)
+    return scaler

pubmlp-0.1.0/pubmlp/config.py

@@ -0,0 +1,124 @@
+import random
+import numpy as np
+import torch
+
+
+# Models that use the SentenceTransformer encoder (frozen, no fine-tuning)
+sentence_transformer_models = {'sentence-transformer', 'bge-small'}
+
+
+class Config:
+    """Configuration for PubMLP training and inference."""
+
+    def __init__(self, **kwargs):
+        # Random seed
+        self.random_seed = kwargs.get('random_seed', 42)
+
+        # Training hyperparameters
+        self.batch_size = kwargs.get('batch_size', 16)
+        self.eval_batch_size = kwargs.get('eval_batch_size', 32)
+        self.epochs = kwargs.get('epochs', 10)
+        self.learning_rate = kwargs.get('learning_rate', 2e-5)
+        self.early_stopping_patience = kwargs.get('early_stopping_patience', 3)
+
+        # Model architecture
+        self.dropout_rate = kwargs.get('dropout_rate', 0.2)
+        self.mlp_hidden_size = kwargs.get('mlp_hidden_size', 64)
+        self.n_hidden_layers = kwargs.get('n_hidden_layers', 1)
+        self.max_length = kwargs.get('max_length', 512)
+
+        # Optimization
+        self.gradient_clip_norm = kwargs.get('gradient_clip_norm', 1.0)
+        self.warmup_steps = kwargs.get('warmup_steps', 0)
+
+        # Embedding model
+        self.embedding_model = kwargs.get('embedding_model', 'bert')
+        self.model_name = kwargs.get('model_name', None)
+        self.pooling_strategy = kwargs.get('pooling_strategy', 'auto')
+
+        # Uncertainty thresholds
+        self.uncertainty_low = kwargs.get('uncertainty_low', 0.3)
+        self.uncertainty_high = kwargs.get('uncertainty_high', 0.7)
+
+        # Cross-validation
+        self.n_folds = kwargs.get('n_folds', 5)
+
+        # Calibration
+        self.calibration_method = kwargs.get('calibration_method', 'temperature')
+
+        # Active learning
+        self.al_query_strategy = kwargs.get('al_query_strategy', 'uncertainty')
+        self.al_batch_size = kwargs.get('al_batch_size', 20)
+        self.al_initial_sample_pct = kwargs.get('al_initial_sample_pct', 0.1)
+
+        # Categorical encoding
+        self.rare_threshold = kwargs.get('rare_threshold', 5)
+
+        # Class weighting
+        self.pos_weight = kwargs.get('pos_weight', 'auto')
+
+        # SAFE stopping
+        self.safe_consecutive_irrelevant = kwargs.get('safe_consecutive_irrelevant', 50)
+        self.safe_min_screened_pct = kwargs.get('safe_min_screened_pct', 0.5)
+        self.safe_random_sample_pct = kwargs.get('safe_random_sample_pct', 0.1)
+        self.safe_switch_model = kwargs.get('safe_switch_model', False)
+
+        if self.model_name is None:
+            self.model_name = self._get_default_model_name()
+
+    def _get_default_model_name(self):
+        defaults = {
+            'bert': 'bert-base-uncased',
+            'modernbert': 'answerdotai/ModernBERT-base',
+            'scibert': 'allenai/scibert_scivocab_uncased',
+            'pubmedbert': 'microsoft/BiomedNLP-PubMedBERT-base-uncased-abstract-fulltext',
+            'sentence-transformer': 'all-MiniLM-L6-v2',
+            'bge-small': 'BAAI/bge-small-en-v1.5',
+        }
+        return defaults.get(self.embedding_model, 'bert-base-uncased')
+
+    def set_random_seeds(self):
+        random.seed(self.random_seed)
+        np.random.seed(self.random_seed)
+        torch.manual_seed(self.random_seed)
+        if torch.cuda.is_available():
+            torch.cuda.manual_seed(self.random_seed)
+            torch.cuda.manual_seed_all(self.random_seed)
+
+    def to_dict(self):
+        return {k: v for k, v in self.__dict__.items() if not k.startswith('_')}
+
+    def __repr__(self):
+        items = [f"{k}={repr(v)}" for k, v in self.to_dict().items()]
+        return f"Config({', '.join(items)})"
+
+
+default_config = Config()
+
+fast_config = Config(
+    epochs=5,
+    batch_size=32,
+    embedding_model='sentence-transformer',
+    model_name='all-MiniLM-L6-v2'
+)
+
+robust_config = Config(
+    epochs=20,
+    early_stopping_patience=5,
+    dropout_rate=0.3,
+    mlp_hidden_size=128
+)
+
+hitl_config = Config(
+    al_query_strategy='uncertainty',
+    al_batch_size=20,
+    safe_consecutive_irrelevant=50,
+    safe_min_screened_pct=0.5,
+)
+
+domain_configs = {
+    'science': Config(embedding_model='scibert'),
+    'medicine': Config(embedding_model='pubmedbert'),
+    'general': Config(embedding_model='bert'),
+    'modernbert': Config(embedding_model='modernbert'),
+}