Create README.md

README.md

@@ -0,0 +1,71 @@
+---
+license: mit
+tags:
+  - finance
+  - retrieval
+  - candlestick
+  - k-line
+  - vicreg
+  - contrastive-learning
+  - RAG
+---
+
+# FinAlogy — VICReg Morphology-Aware Encoder
+
+This repository contains the pretrained visual encoder and demo data for **FinAlogy**, a visual analogy retrieval system for financial K-line analysis.
+
+- 💻 Code: [https://github.com/nice-zzy/FinAlogy](https://github.com/nice-zzy/FinAlogy)
+- ▶️ Demo Video: [https://youtu.be/oq1_hxYAE9M](https://youtu.be/oq1_hxYAE9M)
+
+---
+
+## Files
+
+| File | Description |
+|---|---|
+| `checkpoint_best.pth` | Pretrained VICReg encoder checkpoint (CLIP-ViT-B/32 backbone, 675 MB) |
+| `finalogy_demo_instances.zip` | Demo K-line instances for quick inference testing |
+
+---
+
+## Model Description
+
+The encoder is a **CLIP-ViT-B/32** backbone fine-tuned with **VICReg** self-supervised learning on DOW30 historical K-line data (2010–2021). It maps candlestick chart images into a 512-dimensional morphology-aware embedding space, capturing shape-level properties (body size, shadow structure, local trend direction) while remaining invariant to absolute price scales.
+
+**Training details:**
+- Backbone: CLIP-ViT-B/32
+- Loss: VICReg (λ = µ = 5)
+- Data: DOW30 components, 2010–2020 (train), 2021 (test)
+- Window size: W = 5 trading days
+- Silver-pair threshold: τ = 0.98
+
+**Evaluation (test set, 2,075 unique anchors):**
+
+| Method | 52D Alignment |
+|---|---|
+| Barlow Twins | 0.785 |
+| SimSiam | 0.814 |
+| **VICReg (ours)** | **0.910** |
+
+> 52D Alignment measures cosine similarity between retrieved results and the query in the 52-dimensional morphological feature space — higher is better. VICReg achieves the best morphological alignment among all compared methods.
+
+---
+
+## Usage
+
+```python
+import torch
+from huggingface_hub import hf_hub_download
+
+# Download checkpoint
+ckpt_path = hf_hub_download(
+    repo_id="ZiyaZhao/FinAlogy",
+    filename="checkpoint_best.pth"
+)
+
+# Load encoder
+checkpoint = torch.load(ckpt_path, map_location="cpu")
+# See https://github.com/nice-zzy/FinAlogy for full inference pipeline
+```
+
+For the full retrieval and report generation pipeline, see the [GitHub repository](https://github.com/nice-zzy/FinAlogy).