README.md

---
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/SIreBcl__WU

---

## 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).