Merge pull request #24 from OBA-Research/dev

implement v0.1.9: Introduce model-variant API, branch-based HF loading, and integration test layer

Author: opeyemibami

CONTRIBUTING.md

@@ -1,11 +1,10 @@
 # Contributing to VAAS
 
 Thank you for your interest in improving **VAAS (Vision-Attention Anomaly Scoring)**.
-This document defines the **rules and expectations** for contributing to the VAAS codebase.
 
 ---
 
-## Important Design Constraints (Read First)
+## Few Important Design Constraints (Read First)
 
 - **PyTorch must NOT be imported at import-time of public APIs**
   - Public entry points (e.g. `vaas.inference.pipeline` and other modules imported by users)
@@ -64,7 +63,7 @@ make build         # build wheel + sdist
 
 Formatting and linting are enforced with **ruff**.
 
-Before submitting any change, ensure:
+Before submitting any change, please ensure:
 
 ```bash
 make format
@@ -82,7 +81,7 @@ pre-commit run --all-files
 
 ## 4. Testing Requirements
 
-All contributions must pass:
+Tests are passing:
 
 ```bash
 make test-smoke

Makefile

@@ -32,11 +32,9 @@ test-integration:
 	uv venv .venv_test
 	. .venv_test/bin/activate && \
 		uv sync && \
-		uv sync --group torch && \
-		uv sync --group dev && \
-		uv pip install dist/*.whl pytest && \
+		uv sync --group torch --group dev
+		uv pip install -e . && \
 		uv run --active pytest -m integration -v ; \
-	deactivate
 	rm -rf .venv_test
 
 

README.md

@@ -81,12 +81,17 @@ from PIL import Image
 import requests
 from io import BytesIO
 
+repo_id = "OBA-Research/vaas"
+model_variant = "v1-base-df2023" # v1-medium-df2023 and v1-large-df2023 are other model variants you can use.
+
 pipeline = VAASPipeline.from_pretrained(
-    "OBA-Research/vaas-v1-df2023",
+    repo_id,
     device="cpu",
-    alpha=0.5
+    alpha=0.5,
+    model_variant=model_variant,
 )
 
+
 # # Option A: Using a local image
 # image = Image.open("example.jpg").convert("RGB")
 # result = pipeline(image)
@@ -171,12 +176,12 @@ If you would like to contribute a notebook, see  **[CONTRIBUTING.md](CONTRIBUTIN
 
 ## Model Variants (Planned & Released)
 
-| Version | Training Data | Description | Reported Evaluation (Paper) | Hugging Face Model |
+| Models | Training Data | Description | Reported Evaluation (Paper) | Hugging Face Model |
 |--------|----------------|-------------|-----------------------------|--------------------|
-| v1     | DF2023 (10%)   | Initial public inference release | F1 / IoU reported on DF2023 & CASIA v2.0 | [vaas-v1-df2023](https://huggingface.co/OBA-Research/vaas-v1-df2023) |
-| v2     | DF2023 (≈50%)  | Planned scale-up experiment | Planned | TBD |
-| v3     | DF2023 (100%)  | Full-dataset training (planned) | Planned | TBD |
-| v4     | DF2023 + CASIA2.0 | Cross-dataset study (planned) | Cross-dataset eval planned | TBD |
+| vaas-v1-base-df2023     | DF2023 (10%)   | Initial public inference release | [F1 & IoU are reported in research paper](https://arxiv.org/pdf/2512.15512) | [vaas-v1-base-df2023](https://huggingface.co/OBA-Research/vaas) |
+| vaas-v1-medium-df2023     | DF2023 (≈50%)  | Scale-up experiment | 5% better than base | [vaas-v1-medium-df2023](https://huggingface.co/OBA-Research/vaas/tree/v1-medium-df2023) |
+| vaas-v1-large-df2023     | DF2023 (100%)  | Full-dataset training | 9% better than medium | [vaas-v1-large-df2023](https://huggingface.co/OBA-Research/vaas/tree/v1-large-df2023) |
+| v4     | DF2023 + Others | Cross-dataset study (planned) | Cross-dataset eval planned | TBD |
 | v5     | Other datasets | Exploratory generalisation study | TBD | TBD |
 
 
@@ -193,27 +198,6 @@ differ in training data composition and calibration depending on the target
 integrity focus.
 
 
-## Reported Quantitative Performance
-
-Quantitative detection and localisation metrics for VAAS are
-reported in the accompanying [paper](https://arxiv.org/abs/2512.15512) under a defined evaluation
-protocol.
-
-Under the experimental setup described in the [paper](https://arxiv.org/abs/2512.15512):
-
-- **DF2023 (10% subset)**  
-  F1: 94.9%  
-  IoU: 91.1%
-
-- **CASIA v2.0**  
-  F1: 94.1%  
-  IoU: 89.0%
-
-These metrics are dataset- and protocol-specific and should be
-interpreted in conjunction with the methodology described in
-the paper.
-
-
 ## Roadmap (Inference-Focused)
 
 - Batch inference and folder-level CLI  
@@ -224,7 +208,7 @@ the paper.
 - Model compression  
 - Extended anomaly-map visualisation  
 - ONNX / TorchScript export  
-- Use cases with Streamlit / Gradio
+- Use cases and extentions
 
 ---
 
@@ -242,6 +226,8 @@ Please see the full guidelines in **[CONTRIBUTING.md](CONTRIBUTING.md)**.
 
 If you use VAAS in your research, please cite both the software and the associated paper as appropriate.
 
+### Software Citation
+
 ```python
 @software{vaas,
   title        = {VAAS: Vision-Attention Anomaly Scoring},
@@ -254,6 +240,8 @@ If you use VAAS in your research, please cite both the software and the associat
 
 ```
 
+### Paper Citation
+
 ```python
 @article{bamigbade2025vaas,
   title={VAAS: Vision-Attention Anomaly Scoring for Image Manipulation Detection in Digital Forensics},

pyproject.toml

@@ -11,6 +11,29 @@ authors = [
     { name = "John Sheppard" },
 ]
 
+keywords = [
+    "anomaly detection",
+    "computer vision",
+    "vision transformers",
+    "deep learning",
+    "image forensics",
+    "representation learning",
+]
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Image Processing",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+]
+
 dependencies = [
   "transformers>=4.40",
   "numpy",
@@ -73,4 +96,9 @@ lint.select = [
 quote-style = "double"
 indent-style = "space"
 
-
+[project.urls]
+Homepage = "https://github.com/OBA-Research/VAAS"
+Repository = "https://github.com/OBA-Research/VAAS"
+Documentation = "https://github.com/OBA-Research/VAAS#readme"
+Issues = "https://github.com/OBA-Research/VAAS/issues"
+HuggingFace = "https://huggingface.co/OBA-Research/vaas"

scripts/publish_hf.py

@@ -11,20 +11,42 @@
 
 def main():
     parser = argparse.ArgumentParser("Publish VAAS model to Hugging Face")
+
     parser.add_argument("--checkpoint-dir", type=str, required=True)
     parser.add_argument("--repo-id", type=str, required=True)
     parser.add_argument("--private", action="store_true")
     parser.add_argument("--alpha", type=float, default=0.5)
     parser.add_argument("--device", type=str, default="cpu")
+
+    parser.add_argument("--variant-name", type=str, required=True)
+    parser.add_argument("--dataset-name", type=str, required=True)
+    parser.add_argument("--dataset-fraction", type=str, required=True)
+    parser.add_argument("--architecture-version", type=str, default="v1")
+
     args = parser.parse_args()
 
+    # Deterministic revision generation
+    revision = (
+        f"{args.architecture_version}-{args.variant_name}-{args.dataset_name.lower()}"
+    )
+
     output_dir = "hf_artifact"
-    os.makedirs(output_dir, exist_ok=True)
+
+    if os.path.exists(output_dir):
+        shutil.rmtree(output_dir)
+
+    os.makedirs(output_dir)
 
     pipeline = VAASPipeline.from_checkpoint(
         checkpoint_dir=args.checkpoint_dir,
         device=args.device,
         alpha=args.alpha,
+        variant=args.variant_name,
+        metadata={
+            "architecture_version": args.architecture_version,
+            "dataset": args.dataset_name,
+            "dataset_fraction": args.dataset_fraction,
+        },
     )
 
     model_path = os.path.join(output_dir, "model")
@@ -45,7 +67,11 @@ def main():
 
     config = {
         "architecture": "VAAS",
-        "version": "v1",
+        "architecture_version": args.architecture_version,
+        "revision": revision,
+        "variant": args.variant_name,
+        "dataset": args.dataset_name,
+        "dataset_fraction": args.dataset_fraction,
         "alpha": args.alpha,
         "input_size": [224, 224],
         "px_checkpoint": "px_model.pth",
@@ -57,56 +83,29 @@ def main():
         json.dump(config, f, indent=2)
 
     api = HfApi()
-    try:
-        create_repo(args.repo_id, private=args.private, exist_ok=True)
-    except Exception as e:
-        print(f"Repository creation skipped or failed: {e}")
-
-    src_pipeline_dir = os.path.join("vaas", "inference")
-    dst_pipeline_dir = os.path.join(output_dir, "vaas", "inference")
 
-    os.makedirs(dst_pipeline_dir, exist_ok=True)
-    vaas_root = os.path.join(output_dir, "vaas")
-    os.makedirs(vaas_root, exist_ok=True)
+    # Create revision branch if it does not exist
+    create_repo(args.repo_id, private=args.private, exist_ok=True)
 
-    open(os.path.join(vaas_root, "__init__.py"), "w").close()
-    open(os.path.join(dst_pipeline_dir, "__init__.py"), "w").close()
-
-    shutil.copy(
-        os.path.join(src_pipeline_dir, "pipeline.py"),
-        os.path.join(dst_pipeline_dir, "pipeline.py"),
-    )
-
-    shutil.copy(
-        os.path.join(src_pipeline_dir, "utils.py"),
-        os.path.join(dst_pipeline_dir, "utils.py"),
-    )
-
-    shutil.copy(
-        os.path.join(src_pipeline_dir, "visualize.py"),
-        os.path.join(dst_pipeline_dir, "visualize.py"),
-    )
-
-    src_doc_dir = os.path.join("docs")
-    dst_doc_dir = os.path.join(output_dir, "docs")
-
-    if os.path.exists(dst_doc_dir):
-        shutil.rmtree(dst_doc_dir)
-
-    shutil.copytree(src_doc_dir, dst_doc_dir)
-
-    shutil.copy(
-        "hfREADME.md",
-        os.path.join(output_dir, "README.md"),
+    api.create_branch(
+        repo_id=args.repo_id,
+        branch=revision,
+        exist_ok=True,
     )
 
     api.upload_folder(
         folder_path=output_dir,
         repo_id=args.repo_id,
         repo_type="model",
+        revision=revision,
+        create_pr=False,
     )
 
-    print(f"Published VAAS model to https://huggingface.co/{args.repo_id}")
+    print(
+        f"Published VAAS {args.variant_name} "
+        f"(revision={revision}) "
+        f"to https://huggingface.co/{args.repo_id}"
+    )
 
 
 if __name__ == "__main__":

tests/test_integration_pipeline.py

@@ -0,0 +1,43 @@
+import numpy as np
+import pytest
+from PIL import Image
+
+from vaas.inference.pipeline import VAASPipeline
+
+
+@pytest.mark.integration
+def test_hf_model_loading_and_inference():
+    pipe = VAASPipeline.from_pretrained(
+        repo_id="OBA-Research/vaas",
+        model_variant="v1-base-df2023",
+        device="cpu",
+    )
+
+    img = Image.new("RGB", (224, 224), color="white")
+
+    result = pipe(img)
+
+    assert "S_H" in result
+    assert isinstance(result["S_H"], float)
+    assert isinstance(result["anomaly_map"], np.ndarray)
+    assert result["anomaly_map"].shape == (224, 224)
+
+
+@pytest.mark.integration
+def test_visualization_pipeline(tmp_path):
+    pipe = VAASPipeline.from_pretrained(
+        repo_id="OBA-Research/vaas",
+        model_variant="v1-base-df2023",
+        device="cpu",
+    )
+
+    img = Image.new("RGB", (224, 224), color="white")
+    output_path = tmp_path / "viz.png"
+
+    pipe.visualize(
+        image=img,
+        save_path=str(output_path),
+    )
+
+    assert output_path.exists()
+    assert output_path.stat().st_size > 0

tests/test_local_pipeline.py

@@ -32,3 +32,8 @@ def test_local_pipeline():
 
     assert isinstance(result, dict)
     assert {"S_F", "S_P", "S_H", "anomaly_map"} <= result.keys()
+    print(pipeline.variant)
+    print(pipeline.metadata)
+
+
+test_local_pipeline()

tests/test_pipeline.py

@@ -10,12 +10,14 @@ def test_vaas_pipeline_smoke():
 
     from vaas.inference.pipeline import VAASPipeline
 
-    repo_id = "OBA-Research/vaas-v1-df2023"
+    repo_id = "OBA-Research/vaas"
+    model_variant = "v1-base-df2023"
 
     pipeline = VAASPipeline.from_pretrained(
         repo_id,
         device="cpu",
         alpha=0.5,
+        model_variant=model_variant,
     )
 
     img = Image.fromarray(
@@ -35,3 +37,7 @@ def test_vaas_pipeline_smoke():
     anomaly_map = result["anomaly_map"]
     assert isinstance(anomaly_map, np.ndarray)
     assert anomaly_map.ndim == 2
+    print(pipeline.metadata)
+
+
+test_vaas_pipeline_smoke()

vaas/_version.py

@@ -1 +1 @@
-__version__ = "0.1.7"
+__version__ = "0.1.8"

vaas/fx/fx_utils.py

@@ -19,8 +19,7 @@ def compute_reference_stats(dataset, vit_model, device, transform, max_samples=2
     # Case 1: Authentic samples available
     if len(authentic_indices) > 0:
         print(
-            f"Found {len(authentic_indices)}"
-            "authentic samples for reference statistics."
+            f"Found {len(authentic_indices)}authentic samples for reference statistics."
         )
         selected_indices = random.sample(
             authentic_indices, min(len(authentic_indices), max_samples)