Metadata-Version: 2.1
Name: fair-rec-sys
Version: 0.2.1
Summary: Trust-Aware Recommender System based on TBL & Fairness
Home-page: https://github.com/your-id/fair-rec-sys
Author: Habin Kim
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: license.txt
Requires-Dist: torch>=1.10.0
Requires-Dist: transformers>=4.0.0
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: tqdm

# ⚖️ FairRecSys: Trust-Aware Fashion Recommender

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/release/python-380/)

> **Bridging Behavioral Science and AI Engineering:** A Trust-Aware Recommendation Framework for the Fashion Domain.

This library is the official implementation of the paper **"Trust-Aware Fashion Recommendation System via Non-Linear Review Helpfulness Analysis"** (presented at **2026 ICCT**).

Unlike traditional systems that optimize for simple engagement, `fair-rec-sys` integrates **behavioral insights** directly into the learning process. By operationalizing the "J-Curve" of trust, it distinguishes **"substantiated validation"** from "hollow positivity," ensuring recommendations are both accurate and trustworthy.

---

## 🌟 Key Features

### 1. Trust-Weighted Loss (J-Curve Implementation)
* **Scientific Basis:** Implements the **"Conditional Extremity Bias"** found in our empirical study (Study 1).
* **Mechanism:** Contrary to the traditional Veracity Effect, our model prioritizes **substantiated extremity**. It dynamically assigns higher trust weights to **5-star (Decisive Validation)** and **1-star (Clear Warnings)** reviews, recognizing them as significantly more diagnostic than ambiguous moderate ratings (e.g., 2-star/4-star).

### 2. Cold-Start Mitigation for Rapid Trends
* **Domain Specificity:** Designed for the fashion industry's rapid trend cycles where immediate user feedback is essential.
* **Solution:** By utilizing a **"2-core strategy"** and a **DistilBERT-based regressor**, the system effectively handles data sparsity. It extracts trust signals from review text content even for new items with minimal interaction history, addressing the cold-start problem without relying on massive interaction logs.

### 3. Easy-to-Use Interface
* **Bridging Science & Engineering:** Provides a seamless interface to train `TrustAwareBERT` models with just a few lines of code. The library handles the complex operationalization of behavioral metrics into a `TrustWeightedMSELoss` function automatically.


---

## 🚀 Installation 

```bash
# Download from Hugging Face 
git clone [https://huggingface.co/HabinKim/trust-aware-bert-fashion](https://huggingface.co/HabinKim/trust-aware-bert-fashion)
cd trust-aware-bert-fashion
pip install .
```

---

## 💻 Usage 

You can train the TrustAwareBERT model with just a few lines of code. No complex preprocessing is required.

```python
import torch
from fair_rec import TrustAwareBERT, TrustWeightedMSELoss, Trainer
from torch.utils.data import DataLoader

# 1. Initialize Model (Loads Pre-trained BERT)
model = TrustAwareBERT(pretrained_model='distilbert-base-uncased')

# 2. Define Trust-Weighted Loss (Applying J-Curve)
# This operationalizes the "Conditional Extremity Bias" (5 > 4 star trust)
criterion = TrustWeightedMSELoss(use_j_curve=True) 

# 3. Prepare DataLoader (Insert your dataset here)
# train_loader = DataLoader(...)

# 4. Start Training
# The Trainer class automatically handles the training loop
trainer = Trainer(
    model=model,
    train_loader=train_loader,   # Your actual data loader
    val_loader=None,             # Optional validation loader
    criterion=criterion,
    optimizer=torch.optim.AdamW(model.parameters(), lr=2e-5),
    device='cuda' if torch.cuda.is_available() else 'cpu'
)

# Run training for 3 epochs
trainer.train(epochs=3)
```

---

## 📊 Performance

| Model | NDCG@10 | Fairness (Gini) | Sustainability CTR |
| :--- | :---: | :---: | :---: |
| Standard BERT | 0.42 | 0.65 (High Bias) | 2.1% |
| **FairRecSys (Ours)** | **0.45** | **0.48 (Balanced)** | **5.4%** |

Note: Lower Gini index indicates better fairness distribution among small and large brands.The following table shows the expected performance improvements based on our internal benchmark tests.
---

## 📜 Citation

This project is licensed under the MIT License - see the LICENSE file for details.

```bibtex
@inproceedings{kim2026trust,
  title={Trust-Aware Fashion Recommendation: Bridging the Gap between Behavioral Helpfulness and Deep Learning},
  author={Kim, Habin},
  booktitle={Proceedings of the International Conference on Convergence Technology (ICCT)},
  year={2026}
}
```

---

## 📧 Contact

* **Author:** Habin Kim (Ph.D.)
* **Email:** with.habin@gmail.com
