Metadata-Version: 2.4
Name: hfs-score
Version: 0.1.0
Summary: Historical Fidelity Score for evaluating AI-generated cultural heritage reconstructions.
Author: Oussama Kaich, Zakaria El Fakir, Sanaa El Filali, Omar Zahour, El Habib Benlahmar
License: MIT
Keywords: historical fidelity,cultural heritage,text-to-image,evaluation,trustworthy AI,diffusion models
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# 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:

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

Default illustrative weights:

```text
(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:

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

For tests:

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

---

## Basic usage

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

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

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

```bash
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/*
```
