README.md

---
title: SatQuery AI
emoji: "🛰️"
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 6.16.0
python_version: 3.10.13
app_file: app.py
startup_duration_timeout: 1h
pinned: false
---

# SatQuery AI — ZeroGPU bridge

This Space is the deployment bridge for the existing SatQuery AI Vercel interface. It does not replace the product UI and it does not reimplement SatQuery's scientific pipeline.

The Space uses Python 3.10.13, Gradio 6.16.0, and PyTorch 2.8.0. Gradio 6.16.0 is the newest compatible release before Gradio's Hugging Face Hub 1.x requirement conflicts with SatQuery's pinned Transformers 4.48.3 / Hub 0.36.2 model runtime; upgrading that scientific dependency stack is intentionally outside this deployment-only package.

## Runtime contract

The named Gradio APIs are:

- `/single_image` — one optical, multispectral, or SAR image plus a natural-language query.
- `/optical_sar` — paired optical and SAR observations plus a query.
- `/bitemporal` — earlier/later observations, dates, modality, and a query.
- `/health` — CPU-only readiness and model lifecycle state.
- `/contract` — CPU-only bridge metadata.

Each inference API returns three outputs: a result envelope containing the unchanged SatQuery `AgentResponse`, an artifact manifest, and a Gradio file list. The manifest's zero-based `index` maps an original `/api/agent/previews/...` reference to the corresponding file result.

Model construction and CUDA placement occur once during module initialization, as required by ZeroGPU CUDA emulation. Only the three inference handlers use `@spaces.GPU`; health and contract calls never request a GPU. The requested maximum durations are 90 seconds for single-image, 75 seconds for optical + SAR, and 90 seconds for bi-temporal. Requests are serialized per replica so process-wide model singletons and bounded caches are reused safely.

## Model artifacts

The public Grounding DINO Tiny bundle and ChangerEx checkpoint are committed to this Space. The six SatQuery-owned/adapted weights are deliberately absent. On a missing private artifact, the existing resolver:

1. accepts only an allowlisted path in `AnirudhShashikumar/SatQuery_AI_Models`;
2. requires the `HF_TOKEN` Space secret;
3. downloads into the running Space's local model tree;
4. verifies the pinned SHA-256 before publishing the file; and
5. reuses the verified file and process-wide model singleton for that live replica.

Space storage is ephemeral unless persistent storage is separately enabled. A cold rebuild or replacement replica can therefore download the private and public upstream artifacts again. No access token is written to logs or returned by an API.

Required Space setting: select **ZeroGPU** hardware and add a private `HF_TOKEN` secret with read access to `AnirudhShashikumar/SatQuery_AI_Models`.

## Vercel integration boundary

The existing frontend posts multipart data to `/api/agent/query`; that is not the Gradio queue protocol. Preserve the frontend by adding a Vercel server-side proxy that:

1. accepts the existing `/health` and `/api/agent/query` contracts;
2. uploads image files to the Space and invokes the matching named endpoint;
3. polls the Gradio event result;
4. unwraps `result_envelope.response`; and
5. rewrites preview references using `artifact_manifest` and `artifact_files`.

Authenticated ZeroGPU quota attribution requires the Hugging Face token to remain in the Vercel server environment. Never expose it through a `NEXT_PUBLIC_*` variable or browser bundle. Anonymous public calls are possible but receive the smaller unauthenticated ZeroGPU quota and lower scheduling priority.

## Push this staging directory

After local validation, clone the existing Space, replace its working-tree contents with this directory—not the parent repository—and push normally. Large committed model files require Git LFS.

```bash
hf auth login
git lfs install
git clone https://huggingface.co/spaces/AnirudhShashikumar/SatQuery-AI SatQuery-AI-space
rsync -a --delete --exclude .git hf_space/ SatQuery-AI-space/
cd SatQuery-AI-space
git add .
git commit -m "Deploy SatQuery AI ZeroGPU bridge"
git push origin main
```

Run the `rsync` command from the parent repository directory, or substitute absolute paths. Inspect `git status` in the clone before committing. Do not use a browser-visible token in the remote URL; authenticate through the Hugging Face CLI or Git credential helper.