Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+onnx/saga_awareness_v1.onnx.data filter=lfs diff=lfs merge=lfs -text
+paper.pdf filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,121 @@
+---
+language: en
+tags:
+  - object-detection
+  - self-awareness
+  - degradation-manifold
+  - image-quality
+  - perception
+  - anima
+  - robotflow
+license: apache-2.0
+library_name: pytorch
+pipeline_tag: image-classification
+datasets:
+  - coco
+metrics:
+  - auroc
+model-index:
+  - name: project_saga
+    results:
+      - task:
+          type: image-classification
+          name: Degradation Detection
+        dataset:
+          type: coco
+          name: COCO val2017
+        metrics:
+          - type: auroc
+            value: 0.7991
+            name: Pristine vs Degraded AUROC
+---
+
+# ANIMA Saga — Self-Aware Object Detection via Degradation Manifolds
+
+**Paper**: [arXiv:2602.18394](https://arxiv.org/abs/2602.18394) (Becker et al., 2026)
+
+**Implementation by**: [RobotFlow Labs / AIFLOW Labs](https://github.com/RobotFlow-Labs)
+
+## Overview
+
+Saga adds **degradation-aware self-awareness** to any object detector. A lightweight embedding
+head trained via multi-layer contrastive learning detects when input quality degrades
+(blur, noise, rain, fog, compression) — enabling safety-critical systems to flag unreliable
+perception rather than trusting silent failures.
+
+## Results
+
+| Metric | Value |
+|--------|-------|
+| **AUROC** (pristine vs degraded) | **0.7991** |
+| Detector backbone | yolov10m |
+| Training epochs | 7 |
+| Embedding dimension | 128 |
+
+### Paper Table 1 Reference (YOLOv10-m, COCO mixed degradation)
+
+| Severity | 1 | 2 | 3 | 4 | 5 |
+|----------|---|---|---|---|---|
+| **Paper** | 88.64 | 89.70 | 89.75 | 95.28 | 97.14 |
+| **Ours** | TBD | TBD | TBD | TBD | TBD |
+
+## Usage
+
+```python
+import torch
+from anima_saga.wrappers.detector_registry import PaperDetectorWrapper
+from anima_saga.core.prototype import PristinePrototype
+
+# Load model
+model = PaperDetectorWrapper("yolov10m", embedding_dim=128, freeze_backbone=True)
+model.load_state_dict(torch.load("pytorch/saga_awareness_v1.pth")["model_state_dict"])
+model.eval().cuda()
+
+# Load prototype
+prototype = PristinePrototype.load("checkpoints/pristine_prototype.pkl")
+
+# Inference
+image = torch.randn(1, 3, 640, 640).cuda()  # Your image here
+with torch.no_grad():
+    embedding = model(image)
+    score = prototype.score_cosine(embedding)
+    # score ~ 0: pristine, score > 0.5: degraded
+    print(f"Degradation score: {score.item():.4f}")
+```
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `pytorch/saga_awareness_v1.pth` | PyTorch checkpoint (resume training) |
+| `pytorch/saga_awareness_v1.safetensors` | SafeTensors (fast loading) |
+| `onnx/saga_awareness_v1.onnx` | ONNX (cross-platform) |
+| `tensorrt/saga_awareness_v1_fp16.trt` | TensorRT FP16 (Jetson/L4) |
+| `tensorrt/saga_awareness_v1_fp32.trt` | TensorRT FP32 |
+| `checkpoints/pristine_prototype.pkl` | Pristine prototype for scoring |
+| `configs/paper_cuda.toml` | Training config (reproducibility) |
+| `logs/training_history.json` | Loss curves + metrics |
+
+## Architecture
+
+```
+Input (640x640) → YOLOv10-m backbone → Multi-layer features
+  → 1x1 conv + attention pooling per layer
+  → Concatenate → MLP projection → L2 normalize
+  → Cosine distance from pristine prototype = degradation score
+```
+
+## Citation
+
+```bibtex
+@article{becker2026selfaware,
+  title={Self-Aware Object Detection via Degradation Manifolds},
+  author={Becker, Stefan and Weiss, Simon and H\"ubner, Wolfgang and Arens, Michael},
+  journal={arXiv preprint arXiv:2602.18394},
+  year={2026}
+}
+```
+
+## License
+
+Apache 2.0

checkpoints/best_checkpoint.pth

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:18a1e81a6f9b51bfae7c5285b60f2bdaeafcf9b5a0fa5d6b62367900faeb8a40
+size 78125243

checkpoints/pristine_prototype.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ecc1a1d34a716ff6ec481ae1b29d0705b03825d32b3912438ce0f8869318fa51
+size 788

configs/paper_cuda.toml

@@ -0,0 +1,59 @@
+# Paper-faithful training config for CUDA (arXiv:2602.18394)
+# Server: 8x NVIDIA L4 (23GB each)
+
+[detector]
+backbone = "yolov10m"          # Paper primary: YOLOv10-m (Table 1, best AUROC)
+input_size = 640               # Paper: "input size of 640"
+freeze_backbone = false        # Paper: "fine-tuned jointly" (Section 4.2)
+
+[model]
+proj_dim = 128                 # Per-layer projection dimension d
+embedding_dim = 128            # Final embedding dimension D
+max_degradation_ops = 4        # Max ops per composition N_deg
+
+[training]
+batch_size = 48                # ~21GB on L4 (23GB), 90% util — verified live on GPU 5
+epochs = 50                    # Paper-aligned
+learning_rate = 1e-3           # Base LR
+lr_backbone_scale = 0.1       # Backbone LR = base * scale
+lr_min = 1e-6                 # Cosine annealing min
+weight_decay = 1e-4
+optimizer = "adamw"
+scheduler = "cosine"           # Cosine annealing
+warmup_fraction = 0.05         # 5% warmup steps
+seed = 42
+num_workers = 12               # More workers to keep 3-4 GPUs fed
+gradient_clip_max_norm = 1.0
+mixed_precision = true         # bf16 on CUDA
+
+[contrastive]
+temperature = 0.1              # NT-Xent temperature τ_c
+hard_negatives = true          # Resolution perturbation
+
+[prototype]
+momentum = 0.999               # EMA α (Eq 7)
+warmup_fraction = 0.5          # Start updating after half of training
+
+[data]
+train_dir = "/mnt/forge-data/datasets/grounding_data/coco/train2017"
+val_dir = "/mnt/forge-data/datasets/grounding_data/coco/val2017"
+split_seed = 42
+train_ratio = 0.9
+val_ratio = 0.05
+test_ratio = 0.05
+
+[checkpoint]
+output_dir = "/mnt/artifacts-datai/checkpoints/project_saga"
+keep_best_n = 2
+save_every_steps = 500         # Save checkpoint every N steps (resume-safe)
+
+[logging]
+log_dir = "/mnt/artifacts-datai/logs/project_saga"
+tensorboard_dir = "/mnt/artifacts-datai/tensorboard/project_saga"
+
+[early_stopping]
+patience = 10
+min_delta = 1e-4
+
+[evaluation]
+confidence_threshold = 0.001   # Paper: "confidence threshold to 0.001"

onnx/saga_awareness_v1.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a64f50b96f5fccd7a9b5742b564fafc02b12cd76e0b894cc0bf62dda9ab96bca
+size 429484

onnx/saga_awareness_v1.onnx.data

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d81c8a933ebe0cbebdcc103319009ddff39cd147a116d4d68673c76beeaea102
+size 38109184

paper.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e4f823dc5c8f5373e3b5b7999e08b05292d45e802d484d5c6a0252ae176695c8
+size 17829954

pytorch/saga_awareness_v1.pth

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c4d94f124fc39dfad75a5e54a5ed9519392c349bb7a346d215bf16969add1e24
+size 70639187

pytorch/saga_awareness_v1.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:993403c20fd2d04968a4ea25df28cbaae3889d77608212d5884db8c65d001740
+size 70398448