AGENTS.md

# Cross-Modal Satellite Image Retrieval

## Project Context

A multi-modal satellite image retrieval system that finds semantically similar remote sensing images across different sensor modalities (optical, SAR, multispectral). Users query with an image from one modality and receive ranked results from the same or different modalities.

**Core Value:** Retrieve semantically similar satellite images across sensor modalities with measurable accuracy (F1@5, F1@10) and acceptable query latency.

## Workflow

This project uses GSD (Get Shit Done) workflow. Key commands:

- `/gsd-discuss-phase N` — Gather context for phase N
- `/gsd-plan-phase N` — Create detailed plan for phase N
- `/gsd-execute-phase N` — Execute plans in phase N
- `/gsd-verify-work` — Validate built features

## Tech Stack

- **Framework:** PyTorch 2.x
- **Pre-trained Models:** CLOSP / DOFA-CLIP / SARCLIP (HuggingFace)
- **Vector Search:** FAISS (faiss-cpu)
- **UI:** Gradio 4.x
- **Deployment:** HuggingFace Spaces

## Key Files

- `.planning/PROJECT.md` — Project context and goals
- `.planning/REQUIREMENTS.md` — v1 requirements (27 total)
- `.planning/ROADMAP.md` — Phase structure (7 phases)
- `.planning/config.json` — Workflow preferences
- `.planning/research/` — Domain research

## Phase Overview

| Phase | Goal | Requirements |
|-------|------|--------------|
| 1 | Data & Preprocessing | DATA-01 to DATA-04 |
| 2 | Feature Extraction | FEAT-01 to FEAT-04 |
| 3 | Retrieval Engine | RETR-01 to RETR-05 |
| 4 | Same/Cross-Modal Retrieval | SAME-01 to SAME-03, CROSS-01 to CROSS-04 |
| 5 | Evaluation Metrics | EVAL-01 to EVAL-06 |
| 6 | Gradio UI | UI-01 to UI-04 |
| 7 | HuggingFace Deployment | UI-05 |

## Evaluation Metrics

- F1-score@5 (same-modal)
- F1-score@10 (same-modal)
- F1-score@5 (cross-modal)
- F1-score@10 (cross-modal)
- Average retrieval time per query

## Notes

- Use pre-trained models, don't train from scratch
- Pre-compute all gallery embeddings (don't extract on-the-fly)
- Per-modality preprocessing is critical (different channel counts)
- Cross-modal retrieval is harder than same-modal — focus there