fair-rec-sys 0.2.0

Trust-Aware Recommender System based on TBL & Fairness

⚖️ FairRecSys: Trust-Aware Fashion Recommender

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 (설치 방법)

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

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

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 (인용)

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

@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: [e-mail]