Metadata-Version: 2.1
Name: fair-rec-sys
Version: 0.1.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/)

> **Beyond Popularity Bias:** A TBL-Fair Recommendation Framework based on LLM-GNN Hybrid Architecture.

이 라이브러리는 **2026 ICCT**에서 발표예정인 *"Trust-Aware Fashion Recommendation"* 논문의 공식 구현체입니다.  
단순 클릭 데이터가 아닌 **리뷰의 내재적 가치(Intrinsic Value)**와 **신뢰도(Trustworthiness)**를 학습하여, 스몰 브랜드와 상생하는 윤리적 추천 시스템을 구축할 수 있습니다.

---

## 🌟 Key Features (핵심 기능)

1. **Trust-Weighted Loss (신뢰도 가중 손실 함수):**
   * 통계적으로 입증된 '진실성 효과(4점 > 5점)'와 '부정성 편향(1점 > 2점)'을 딥러닝 학습 과정(Loss Function)에 반영합니다.
2. **Cold-Start Solved via LLM:**
   * 데이터가 없는 상품에 대해 LLM이 추론한 내재적 가치를 활용합니다.
3. **Easy-to-Use Interface:**
   * 복잡한 전처리 없이 몇 줄의 코드로 `TrustAwareBERT` 모델을 학습시킬 수 있습니다.

---

## 🚀 Installation (설치 방법)

```bash
# 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 (사용 방법)

이 라이브러리는 복잡한 전처리 없이 간단하게 모델을 불러와 학습시킬 수 있습니다.

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

# 1. 모델 초기화 (Pre-trained BERT 로드)
model = TrustAwareBERT(pretrained_model='bert-base-uncased')

# 2. 가중 손실 함수 설정 (Study 1의 회귀분석 결과 반영)
# 신뢰도 점수(Trust Score)를 기반으로 오차를 계산합니다.
criterion = TrustWeightedLoss() 

# 3. 데이터 로더 준비 (사용자의 데이터를 여기에 넣으세요)
# train_loader = DataLoader(...)

# 4. 학습 시작
# Trainer 클래스가 학습 루프를 자동으로 관리합니다.
trainer = Trainer(
    model=model,
    train_loader=train_loader, # 실제 데이터 로더
    val_loader=None,           # 검증 데이터 로더 (선택)
    criterion=criterion,
    optimizer=torch.optim.AdamW(model.parameters(), lr=2e-5),
    device='cuda' if torch.cuda.is_available() else 'cpu'
)

# 에폭(Epoch) 수 설정 후 학습 실행
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%** |

---

## 📜 Citation (인용)

본 라이브러리를 연구에 활용하실 경우 아래 논문을 인용해 주세요.

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