hfs-score 0.1.0__tar.gz

hfs_score-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The HFS Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files, to deal in the Software
+without restriction, including without limitation the rights to use, copy,
+modify, merge, publish, distribute, sublicense, and/or sell copies of the
+Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hfs_score-0.1.0/PKG-INFO

@@ -0,0 +1,202 @@
+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/*
+```

hfs_score-0.1.0/README.md

@@ -0,0 +1,181 @@
+# 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/*
+```

hfs_score-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hfs-score"
+version = "0.1.0"
+description = "Historical Fidelity Score for evaluating AI-generated cultural heritage reconstructions."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Oussama Kaich" },
+    { name = "Zakaria El Fakir" },
+    { name = "Sanaa El Filali" },
+    { name = "Omar Zahour" },
+    { name = "El Habib Benlahmar" }
+]
+keywords = [
+    "historical fidelity",
+    "cultural heritage",
+    "text-to-image",
+    "evaluation",
+    "trustworthy AI",
+    "diffusion models"
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Image Processing"
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "build>=1.0", "twine>=4.0"]
+
+[project.scripts]
+hfs-score = "hfs_score.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

hfs_score-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hfs_score-0.1.0/src/hfs_score/__init__.py

@@ -0,0 +1,40 @@
+"""
+hfs_score
+
+A lightweight Python library for computing the Historical Fidelity Score (HFS)
+for AI-generated cultural heritage reconstructions.
+"""
+
+from .core import HFSWeights, HFSBreakdown, compute_hfs, compute_hfs_breakdown
+from .criteria import (
+    normalize_benefit,
+    normalize_cost,
+    compute_tia,
+    compute_vss,
+    compute_acs,
+    compute_chp,
+    compute_evs,
+    compute_up,
+    compute_bp,
+)
+from .validation import validate_score, validate_weights
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "HFSWeights",
+    "HFSBreakdown",
+    "compute_hfs",
+    "compute_hfs_breakdown",
+    "normalize_benefit",
+    "normalize_cost",
+    "compute_tia",
+    "compute_vss",
+    "compute_acs",
+    "compute_chp",
+    "compute_evs",
+    "compute_up",
+    "compute_bp",
+    "validate_score",
+    "validate_weights",
+]

hfs_score-0.1.0/src/hfs_score/cli.py

@@ -0,0 +1,60 @@
+"""Command-line interface for hfs-score."""
+
+import argparse
+
+from .core import HFSWeights, compute_hfs_breakdown
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Compute Historical Fidelity Score (HFS)."
+    )
+
+    parser.add_argument("--tia", type=float, required=True, help="Text-Image Alignment score [0,1].")
+    parser.add_argument("--vss", type=float, required=True, help="Visual Similarity Score [0,1].")
+    parser.add_argument("--acs", type=float, required=True, help="Architectural Consistency Score [0,1].")
+    parser.add_argument("--chp", type=float, required=True, help="Cultural and Historical Plausibility [0,1].")
+    parser.add_argument("--evs", type=float, required=True, help="Expert Validation Score [0,1].")
+    parser.add_argument("--up", type=float, required=True, help="Uncertainty Penalty [0,1].")
+    parser.add_argument("--bp", type=float, required=True, help="Bias and Hallucination Penalty [0,1].")
+
+    parser.add_argument("--w1", type=float, default=0.20, help="Weight for TIA.")
+    parser.add_argument("--w2", type=float, default=0.18, help="Weight for VSS.")
+    parser.add_argument("--w3", type=float, default=0.17, help="Weight for ACS.")
+    parser.add_argument("--w4", type=float, default=0.20, help="Weight for CHP.")
+    parser.add_argument("--w5", type=float, default=0.15, help="Weight for EVS.")
+    parser.add_argument("--w6", type=float, default=0.05, help="Weight for UP.")
+    parser.add_argument("--w7", type=float, default=0.05, help="Weight for BP.")
+
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    weights = HFSWeights(
+        w1=args.w1,
+        w2=args.w2,
+        w3=args.w3,
+        w4=args.w4,
+        w5=args.w5,
+        w6=args.w6,
+        w7=args.w7,
+    )
+
+    result = compute_hfs_breakdown(
+        TIA=args.tia,
+        VSS=args.vss,
+        ACS=args.acs,
+        CHP=args.chp,
+        EVS=args.evs,
+        UP=args.up,
+        BP=args.bp,
+        weights=weights,
+    )
+
+    print(f"HFS = {result.hfs_0_100:.2f}/100")
+    print(f"Positive component = {result.positive_component:.4f}")
+    print(f"Penalty component  = {result.penalty_component:.4f}")
+    print(f"Raw score          = {result.raw_score_0_1:.4f}")

hfs_score-0.1.0/src/hfs_score/core.py

@@ -0,0 +1,144 @@
+"""Core implementation of the Historical Fidelity Score."""
+
+from dataclasses import dataclass
+
+from .validation import validate_score, validate_weights
+
+
+@dataclass(frozen=True)
+class HFSWeights:
+    """
+    Weights used in the Historical Fidelity Score.
+
+    These default values are illustrative and should be validated through
+    expert elicitation, AHP, and sensitivity analysis in future studies.
+    """
+
+    w1: float = 0.20  # TIA: Text-Image Alignment
+    w2: float = 0.18  # VSS: Visual Similarity Score
+    w3: float = 0.17  # ACS: Architectural Consistency Score
+    w4: float = 0.20  # CHP: Cultural and Historical Plausibility
+    w5: float = 0.15  # EVS: Expert Validation Score
+    w6: float = 0.05  # UP: Uncertainty Penalty
+    w7: float = 0.05  # BP: Bias and Hallucination Penalty
+
+
+@dataclass(frozen=True)
+class HFSBreakdown:
+    """
+    Detailed result of the HFS computation.
+    """
+
+    raw_score_0_1: float
+    clipped_score_0_1: float
+    hfs_0_100: float
+    positive_component: float
+    penalty_component: float
+
+
+def clip(value: float, lower: float = 0.0, upper: float = 1.0) -> float:
+    """Clip a value between lower and upper bounds."""
+    return max(lower, min(value, upper))
+
+
+def compute_hfs_breakdown(
+    TIA: float,
+    VSS: float,
+    ACS: float,
+    CHP: float,
+    EVS: float,
+    UP: float,
+    BP: float,
+    weights: HFSWeights = HFSWeights(),
+) -> HFSBreakdown:
+    """
+    Compute the Historical Fidelity Score and return a detailed breakdown.
+
+    Parameters
+    ----------
+    TIA:
+        Text-Image Alignment score in [0, 1].
+    VSS:
+        Visual Similarity Score in [0, 1].
+    ACS:
+        Architectural Consistency Score in [0, 1].
+    CHP:
+        Cultural and Historical Plausibility score in [0, 1].
+    EVS:
+        Expert Validation Score in [0, 1].
+    UP:
+        Uncertainty Penalty in [0, 1]. Higher value means higher risk.
+    BP:
+        Bias and Hallucination Penalty in [0, 1]. Higher value means higher risk.
+    weights:
+        HFSWeights object.
+
+    Returns
+    -------
+    HFSBreakdown
+        Detailed score result.
+    """
+    validate_weights(weights)
+
+    values = {
+        "TIA": TIA,
+        "VSS": VSS,
+        "ACS": ACS,
+        "CHP": CHP,
+        "EVS": EVS,
+        "UP": UP,
+        "BP": BP,
+    }
+
+    for name, value in values.items():
+        validate_score(name, value)
+
+    positive_component = (
+        weights.w1 * TIA
+        + weights.w2 * VSS
+        + weights.w3 * ACS
+        + weights.w4 * CHP
+        + weights.w5 * EVS
+    )
+
+    penalty_component = weights.w6 * UP + weights.w7 * BP
+    raw_score = positive_component - penalty_component
+    clipped_score = clip(raw_score, 0.0, 1.0)
+
+    return HFSBreakdown(
+        raw_score_0_1=raw_score,
+        clipped_score_0_1=clipped_score,
+        hfs_0_100=100.0 * clipped_score,
+        positive_component=positive_component,
+        penalty_component=penalty_component,
+    )
+
+
+def compute_hfs(
+    TIA: float,
+    VSS: float,
+    ACS: float,
+    CHP: float,
+    EVS: float,
+    UP: float,
+    BP: float,
+    weights: HFSWeights = HFSWeights(),
+) -> float:
+    """
+    Compute the Historical Fidelity Score.
+
+    Returns
+    -------
+    float
+        HFS score between 0 and 100.
+    """
+    return compute_hfs_breakdown(
+        TIA=TIA,
+        VSS=VSS,
+        ACS=ACS,
+        CHP=CHP,
+        EVS=EVS,
+        UP=UP,
+        BP=BP,
+        weights=weights,
+    ).hfs_0_100

hfs_score-0.1.0/src/hfs_score/criteria.py

@@ -0,0 +1,147 @@
+"""Criterion-level formulas for the Historical Fidelity Score."""
+
+from typing import Sequence
+
+from .validation import validate_score
+
+
+def normalize_benefit(value: float, minimum: float, maximum: float, epsilon: float = 1e-8) -> float:
+    """
+    Normalize a benefit metric where higher is better.
+
+    Formula:
+        (value - minimum) / (maximum - minimum + epsilon)
+    """
+    normalized = (value - minimum) / (maximum - minimum + epsilon)
+    return max(0.0, min(1.0, normalized))
+
+
+def normalize_cost(value: float, minimum: float, maximum: float, epsilon: float = 1e-8) -> float:
+    """
+    Normalize a cost metric where lower is better.
+
+    Formula:
+        1 - (value - minimum) / (maximum - minimum + epsilon)
+    """
+    normalized = 1.0 - (value - minimum) / (maximum - minimum + epsilon)
+    return max(0.0, min(1.0, normalized))
+
+
+def compute_tia(clip_score: float, tifa_score: float, alpha1: float = 0.5) -> float:
+    """
+    Compute Text-Image Alignment.
+
+    Formula:
+        TIA = alpha1 * CLIPScore + alpha2 * TIFA
+
+    All input scores must be normalized in [0, 1].
+    """
+    validate_score("clip_score", clip_score)
+    validate_score("tifa_score", tifa_score)
+
+    if alpha1 < 0 or alpha1 > 1:
+        raise ValueError("alpha1 must be between 0 and 1.")
+
+    alpha2 = 1.0 - alpha1
+    return alpha1 * clip_score + alpha2 * tifa_score
+
+
+def compute_vss(ssim_score: float, lpips_distance: float, beta1: float = 0.5) -> float:
+    """
+    Compute Visual Similarity Score.
+
+    Formula:
+        VSS = beta1 * SSIM + beta2 * (1 - LPIPS)
+
+    Both SSIM and LPIPS must be normalized in [0, 1].
+    For LPIPS, lower is better, therefore the formula uses (1 - LPIPS).
+    """
+    validate_score("ssim_score", ssim_score)
+    validate_score("lpips_distance", lpips_distance)
+
+    if beta1 < 0 or beta1 > 1:
+        raise ValueError("beta1 must be between 0 and 1.")
+
+    beta2 = 1.0 - beta1
+    return beta1 * ssim_score + beta2 * (1.0 - lpips_distance)
+
+
+def compute_acs(layout: float, proportions: float, structure: float) -> float:
+    """
+    Compute Architectural Consistency Score.
+
+    Formula:
+        ACS = (layout + proportions + structure) / 3
+
+    The three values should be obtained from an expert rubric or
+    architecture-focused checklist and normalized in [0, 1].
+    """
+    validate_score("layout", layout)
+    validate_score("proportions", proportions)
+    validate_score("structure", structure)
+
+    return (layout + proportions + structure) / 3.0
+
+
+def compute_chp(
+    temporal: float,
+    artifacts: float,
+    materials: float,
+    anachronism_absence: float,
+) -> float:
+    """
+    Compute Cultural and Historical Plausibility.
+
+    Formula:
+        CHP = (temporal + artifacts + materials + anachronism_absence) / 4
+    """
+    validate_score("temporal", temporal)
+    validate_score("artifacts", artifacts)
+    validate_score("materials", materials)
+    validate_score("anachronism_absence", anachronism_absence)
+
+    return (temporal + artifacts + materials + anachronism_absence) / 4.0
+
+
+def compute_evs(expert_scores: Sequence[float]) -> float:
+    """
+    Compute Expert Validation Score.
+
+    Formula:
+        EVS = average expert score
+
+    expert_scores must contain values normalized in [0, 1].
+    """
+    if len(expert_scores) == 0:
+        raise ValueError("expert_scores cannot be empty.")
+
+    for index, score in enumerate(expert_scores):
+        validate_score(f"expert_scores[{index}]", score)
+
+    return sum(expert_scores) / len(expert_scores)
+
+
+def compute_up(seed_variance: float, expert_disagreement: float) -> float:
+    """
+    Compute Uncertainty Penalty.
+
+    Formula:
+        UP = (seed_variance + expert_disagreement) / 2
+    """
+    validate_score("seed_variance", seed_variance)
+    validate_score("expert_disagreement", expert_disagreement)
+
+    return (seed_variance + expert_disagreement) / 2.0
+
+
+def compute_bp(hallucination_rate: float, bias_rate: float) -> float:
+    """
+    Compute Bias and Hallucination Penalty.
+
+    Formula:
+        BP = (hallucination_rate + bias_rate) / 2
+    """
+    validate_score("hallucination_rate", hallucination_rate)
+    validate_score("bias_rate", bias_rate)
+
+    return (hallucination_rate + bias_rate) / 2.0

hfs_score-0.1.0/src/hfs_score/rubric.py

@@ -0,0 +1,42 @@
+"""Simple helper utilities for rubric-based scoring."""
+
+from .validation import validate_score
+
+
+RUBRIC_LEVELS = {
+    0.00: "Incorrect or unsupported",
+    0.25: "Weak fidelity",
+    0.50: "Moderate fidelity",
+    0.75: "Good fidelity",
+    1.00: "Excellent fidelity",
+}
+
+
+def rubric_score(level: float) -> float:
+    """
+    Return a validated rubric score.
+
+    Recommended levels are:
+    0.00, 0.25, 0.50, 0.75, 1.00
+
+    Continuous values between 0 and 1 are also accepted.
+    """
+    validate_score("level", level)
+    return float(level)
+
+
+def describe_score(score: float) -> str:
+    """
+    Provide a simple textual interpretation of a normalized score.
+    """
+    validate_score("score", score)
+
+    if score < 0.20:
+        return "Very low fidelity"
+    if score < 0.40:
+        return "Low fidelity"
+    if score < 0.60:
+        return "Moderate fidelity"
+    if score < 0.80:
+        return "Good fidelity"
+    return "High fidelity"

hfs_score-0.1.0/src/hfs_score/validation.py

@@ -0,0 +1,50 @@
+"""Validation utilities for hfs_score."""
+
+
+def validate_score(name: str, value: float) -> None:
+    """
+    Validate that a score is numeric and between 0 and 1.
+
+    Parameters
+    ----------
+    name:
+        Name of the score.
+    value:
+        Score value.
+
+    Raises
+    ------
+    TypeError
+        If the value is not numeric.
+    ValueError
+        If the value is outside [0, 1].
+    """
+    if not isinstance(value, (int, float)):
+        raise TypeError(f"{name} must be a number.")
+    if value < 0 or value > 1:
+        raise ValueError(f"{name} must be between 0 and 1. Got {value}.")
+
+
+def validate_weights(weights) -> None:
+    """
+    Validate HFS weights.
+
+    The sum of all weights should be approximately 1.0.
+    """
+    values = [
+        weights.w1,
+        weights.w2,
+        weights.w3,
+        weights.w4,
+        weights.w5,
+        weights.w6,
+        weights.w7,
+    ]
+
+    for index, value in enumerate(values, start=1):
+        if value < 0:
+            raise ValueError(f"w{index} must be non-negative.")
+
+    total = sum(values)
+    if abs(total - 1.0) > 1e-8:
+        raise ValueError(f"Weights must sum to 1. Current sum = {total}.")

hfs_score-0.1.0/src/hfs_score.egg-info/PKG-INFO

@@ -0,0 +1,202 @@
+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/*
+```

hfs_score-0.1.0/src/hfs_score.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/hfs_score/__init__.py
+src/hfs_score/cli.py
+src/hfs_score/core.py
+src/hfs_score/criteria.py
+src/hfs_score/rubric.py
+src/hfs_score/validation.py
+src/hfs_score.egg-info/PKG-INFO
+src/hfs_score.egg-info/SOURCES.txt
+src/hfs_score.egg-info/dependency_links.txt
+src/hfs_score.egg-info/entry_points.txt
+src/hfs_score.egg-info/requires.txt
+src/hfs_score.egg-info/top_level.txt
+tests/test_core.py
+tests/test_criteria.py

hfs_score-0.1.0/src/hfs_score.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hfs_score-0.1.0/src/hfs_score.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hfs-score = hfs_score.cli:main

hfs_score-0.1.0/src/hfs_score.egg-info/requires.txt

@@ -0,0 +1,5 @@
+
+[dev]
+pytest>=7.0
+build>=1.0
+twine>=4.0

hfs_score-0.1.0/src/hfs_score.egg-info/top_level.txt

@@ -0,0 +1 @@
+hfs_score

hfs_score-0.1.0/tests/test_core.py

@@ -0,0 +1,58 @@
+import pytest
+
+from hfs_score import HFSWeights, compute_hfs, compute_hfs_breakdown
+
+
+def test_compute_hfs_range():
+    score = compute_hfs(
+        TIA=0.8,
+        VSS=0.7,
+        ACS=0.6,
+        CHP=0.75,
+        EVS=0.9,
+        UP=0.2,
+        BP=0.1,
+    )
+    assert 0 <= score <= 100
+
+
+def test_compute_hfs_expected_value():
+    score = compute_hfs(
+        TIA=0.8,
+        VSS=0.7,
+        ACS=0.6,
+        CHP=0.75,
+        EVS=0.9,
+        UP=0.2,
+        BP=0.1,
+    )
+    assert score == pytest.approx(65.8)
+
+
+def test_breakdown():
+    result = compute_hfs_breakdown(
+        TIA=0.8,
+        VSS=0.7,
+        ACS=0.6,
+        CHP=0.75,
+        EVS=0.9,
+        UP=0.2,
+        BP=0.1,
+    )
+    assert result.hfs_0_100 == pytest.approx(65.8)
+    assert result.positive_component > result.penalty_component
+
+
+def test_invalid_weights_sum():
+    bad_weights = HFSWeights(w1=0.5, w2=0.5, w3=0.5, w4=0, w5=0, w6=0, w7=0)
+    with pytest.raises(ValueError):
+        compute_hfs(
+            TIA=0.8,
+            VSS=0.7,
+            ACS=0.6,
+            CHP=0.75,
+            EVS=0.9,
+            UP=0.2,
+            BP=0.1,
+            weights=bad_weights,
+        )

hfs_score-0.1.0/tests/test_criteria.py

@@ -0,0 +1,54 @@
+import pytest
+
+from hfs_score import (
+    compute_tia,
+    compute_vss,
+    compute_acs,
+    compute_chp,
+    compute_evs,
+    compute_up,
+    compute_bp,
+    normalize_benefit,
+    normalize_cost,
+)
+
+
+def test_compute_tia():
+    assert compute_tia(0.8, 0.6, alpha1=0.5) == pytest.approx(0.7)
+
+
+def test_compute_vss():
+    assert compute_vss(0.7, 0.3, beta1=0.5) == pytest.approx(0.7)
+
+
+def test_compute_acs():
+    assert compute_acs(0.8, 0.7, 0.6) == pytest.approx(0.7)
+
+
+def test_compute_chp():
+    assert compute_chp(0.9, 0.7, 0.8, 0.6) == pytest.approx(0.75)
+
+
+def test_compute_evs():
+    assert compute_evs([0.8, 0.7, 0.9]) == pytest.approx(0.8)
+
+
+def test_compute_up():
+    assert compute_up(0.2, 0.3) == pytest.approx(0.25)
+
+
+def test_compute_bp():
+    assert compute_bp(0.3, 0.2) == pytest.approx(0.25)
+
+
+def test_normalize_benefit():
+    assert normalize_benefit(5, 0, 10) == pytest.approx(0.5)
+
+
+def test_normalize_cost():
+    assert normalize_cost(5, 0, 10) == pytest.approx(0.5)
+
+
+def test_invalid_score_raises():
+    with pytest.raises(ValueError):
+        compute_acs(1.2, 0.7, 0.6)