Improve model card: Add metadata, description, project page, and usage example

README.md

@@ -2,10 +2,76 @@
 tags:
 - model_hub_mixin
 - pytorch_model_hub_mixin
+license: mit
+pipeline_tag: visual-document-retrieval
+library_name: aionsearch
 ---
 
-This model has been pushed to the Hub using the [PytorchModelHubMixin](https://huggingface.co/docs/huggingface_hub/package_reference/mixins#huggingface_hub.PyTorchModelHubMixin) integration:
+# AION-Search: Semantic search for 100M+ galaxy images using AI-generated captions
 
-[![GitHub Repo](https://img.shields.io/badge/github-repo-blue?logo=github)](https://github.com/NolanKoblischke/AION-Search) [![arXiv](https://img.shields.io/badge/arXiv-2512.11982-b31b1b.svg)](https://arxiv.org/abs/2512.11982)
-- Code: [Github](https://github.com/NolanKoblischke/AION-Search)
-- Paper: [ArXiv](https://arxiv.org/abs/2512.11982)
+AION-Search is a novel text-based search engine for galaxy images, developed to find scientifically interesting phenomena using natural language queries from completely unlabeled image data. As presented in the paper [Semantic search for 100M+ galaxy images using AI-generated captions](https://huggingface.co/papers/2512.11982), this method leverages Vision-Language Models (VLMs) to generate descriptions for galaxy images, then contrastively aligns a pre-trained multimodal astronomy foundation model to produce searchable embeddings at scale. It was trained on 300k captions generated by GPT-4.1-mini.
+
+This model has been pushed to the Hub using the [PytorchModelHubMixin](https://huggingface.co/docs/huggingface_hub/package_reference/mixins#huggingface_hub.PyTorchModelHubMixin) integration.
+
+-   **Paper:** [Semantic search for 100M+ galaxy images using AI-generated captions](https://huggingface.co/papers/2512.11982)
+-   **Code:** [GitHub Repository](https://github.com/NolanKoblischke/AION-Search)
+-   **Project Page:** [AION-Search Project Page](https://aion-search.github.io)
+-   **Demo:** [AION-Search App](https://astronolan-aion-search.hf.space/)
+-   **Datasets:** [HuggingFace Datasets Collection](https://huggingface.co/collections/astronolan/aion-search)
+
+## Quick Start
+
+### Installation
+
+```bash
+git clone https://github.com/astronolan/aion-search.git
+cd aion-search
+pip install -e . # or uv pip install -e .
+```
+
+### Requirements
+
+This package requires an **OpenAI API key** for generating text embeddings.
+
+1. Get your API key at [platform.openai.com](https://platform.openai.com)
+2. Create a `.env` file in the project root:
+   ```bash
+   OPENAI_API_KEY=sk-your-key-here
+   ```
+
+### Usage
+
+```python
+from aionsearch import AIONSearchClipModel
+
+# Load pretrained model from HuggingFace
+model = AIONSearchClipModel.from_pretrained()
+
+# Project AION image embeddings into shared space
+aion_embedding = # Embedding of an image using github.com/PolymathicAI/AION
+projected_image = model.image_projector(aion_embedding)  # (batch, 768) -> (batch, 1024)
+
+# Project OpenAI text embeddings into shared space  
+text_embedding = # Embedding of text using text-embedding-3-large
+projected_text = model.text_projector(text_embedding)    # (batch, 3072) -> (batch, 1024)
+
+# Compute similarity for semantic search
+similarity = projected_image @ projected_text.T
+```
+
+See [`examples/quick_start.ipynb`](https://github.com/NolanKoblischke/AION-Search/blob/main/examples/quick_start.ipynb) for a complete walkthrough that downloads a galaxy image, generates embeddings with AION, and performs text-to-image similarity search.
+
+## Citation
+
+If you find this work useful, please cite:
+
+```bibtex
+@misc{koblischke2025semantic,
+      title={Semantic search for 100M+ galaxy images using AI-generated captions}, 
+      author={Nolan Koblischke and Liam Parker and Francois Lanusse and Irina Espejo Morales and Jo Bovy and Shirley Ho},
+      year={2025},
+      eprint={2512.11982},
+      archivePrefix={arXiv},
+      primaryClass={astro-ph.IM},
+      url={https://arxiv.org/abs/2512.11982}, 
+}