hfs-score 0.1.0

Historical Fidelity Score for evaluating AI-generated cultural heritage reconstructions.

hfs-score

Historical Fidelity Score (HFS) is a Python starter library for evaluating the historical fidelity of AI-generated cultural heritage images.

This project implements the methodological scoring framework proposed in:

A Mathematical Scoring Model for Historical Fidelity in Text-to-Image Reconstruction of Cultural Heritage Scenes

The goal is not to train a new AI model.
The goal is to provide a reusable scoring toolkit for researchers, museums, heritage experts, and AI practitioners.

---

What HFS measures

HFS combines five positive dimensions:

Symbol	Meaning
TIA	Text-Image Alignment
VSS	Visual Similarity Score
ACS	Architectural Consistency Score
CHP	Cultural and Historical Plausibility
EVS	Expert Validation Score

And two penalties:

Symbol	Meaning
UP	Uncertainty Penalty
BP	Bias and Hallucination Penalty

The global score is:

HFS(I) = 100 × clip(
w1*TIA + w2*VSS + w3*ACS + w4*CHP + w5*EVS
- w6*UP - w7*BP,
0, 1
)

Default illustrative weights:

(w1, w2, w3, w4, w5, w6, w7)
=
(0.20, 0.18, 0.17, 0.20, 0.15, 0.05, 0.05)

These weights are initial values and should be validated using expert elicitation and sensitivity analysis.

---

Installation for development

Clone or unzip this project, then run:

cd hfs-score
python -m pip install -e .

For tests:

python -m pip install -e ".[dev]"
pytest

---

Basic usage

from hfs_score import (
    compute_hfs,
    compute_tia,
    compute_vss,
    compute_acs,
    compute_chp,
    compute_evs,
    compute_up,
    compute_bp,
)

TIA = compute_tia(clip_score=0.84, tifa_score=0.78)
VSS = compute_vss(ssim_score=0.72, lpips_distance=0.30)
ACS = compute_acs(layout=0.80, proportions=0.70, structure=0.65)
CHP = compute_chp(
    temporal=0.90,
    artifacts=0.75,
    materials=0.80,
    anachronism_absence=0.70
)
EVS = compute_evs([0.85, 0.90, 0.80])
UP = compute_up(seed_variance=0.20, expert_disagreement=0.15)
BP = compute_bp(hallucination_rate=0.10, bias_rate=0.15)

score = compute_hfs(
    TIA=TIA,
    VSS=VSS,
    ACS=ACS,
    CHP=CHP,
    EVS=EVS,
    UP=UP,
    BP=BP,
)

print(f"HFS = {score:.2f}/100")

---

CLI usage

After installation:

hfs-score --tia 0.80 --vss 0.70 --acs 0.60 --chp 0.75 --evs 0.90 --up 0.20 --bp 0.10

Expected output:

HFS = 65.80/100

---

Project roadmap

Version 0.1

• Core HFS formula
• Criteria formulas
• Basic CLI
• Tests
• Example usage

Version 0.2

• Batch CSV evaluation
• Export JSON/CSV reports
• Weight sensitivity analysis

Version 0.3

• Integration with CLIPScore, SSIM, LPIPS
• Expert rubric forms

Version 1.0

• Full research-ready toolkit
• Benchmark comparison
• Automatic report generation

---

Scientific note

This package implements a methodological framework.
It does not claim that an HFS score is an absolute historical truth.
The score should be interpreted as a transparent decision-support measure combining automatic metrics, expert rubrics, and explicit risk penalties.

---

Publishing on PyPI

For detailed instructions, see:

• PUBLISHING_PYPI_FR.md
• PUBLISHING_PYPI_EN.md

Quick commands:

python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*
python -m twine upload --repository testpypi dist/*
python -m twine upload dist/*