README.md

metadata

title: Satquery Backend
emoji: 🛰️
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 4.44.1
app_file: app.py
pinned: false

SatQuery-AI Backend - Complete Setup Guide

Overview

SatQuery-AI is a satellite image analysis platform that combines multiple specialized components:

• Sai's Grounding Pipeline: Analyzes satellite images and classifies them into a 3x3 grid with land cover classes
• Sid's Gemini Integration: Answers natural language questions based on the grounding data
• Change Detection: Compares before/after images to identify changes

This backend provides a complete FastAPI implementation with a full mock pipeline for development and testing.

---

Project Structure

SatQuery-AI/
├── backend/
│   ├── main.py                 # FastAPI application entry point
│   ├── config.py               # Configuration and settings management
│   ├── requirements.txt         # Python dependencies
│   ├── .env.example            # Environment variables template
│   ├── .gitignore              # Git ignore rules
│   ├── routes/
│   │   ├── __init__.py
│   │   ├── health.py           # GET /api/health endpoint
│   │   └── query.py            # POST /api/query and /api/query/change
│   ├── models/
│   │   ├── __init__.py
│   │   └── request.py          # Pydantic request models
│   └── services/
│       ├── __init__.py
│       └── mock_service.py     # Complete mock pipeline implementation
├── day1-final.html             # Day 1 completion summary
└── README.md                   # This file

---

Quick Start

1. Install Dependencies

cd backend
pip install -r requirements.txt

2. Set Up Environment Variables

# Copy the example
cp .env.example .env

# Edit .env with your settings (optional for development)

3. Run the Backend

python -m uvicorn main:app --reload

The backend will start at http://localhost:8000

---

API Documentation

Interactive Documentation

Once running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Endpoints

1. Health Check

GET /api/health

Response:

{
  "status": "healthy",
  "message": "SatQuery-AI backend is running"
}

---

2. Single Image Query

POST /api/query

Parameters:

• question (form data): Natural language question about the image
• file (form data): Satellite image file (any image format)

Example:

curl -X POST http://localhost:8000/api/query \
  -F "file=@satellite_image.png" \
  -F "question=What agricultural areas are visible in this satellite image?"

Response:

{
  "query_id": "a1b2c3d4",
  "filename": "satellite_image.png",
  "question": "What agricultural areas are visible?",
  "grounding": {
    "image_name": "satellite_image.png",
    "timestamp": "2024-01-15T10:30:45.123456",
    "grid_size": "3x3",
    "tiles": [
      {
        "tile_id": 0,
        "class": "Agriculture",
        "confidence": 0.95
      },
      {
        "tile_id": 1,
        "class": "Water",
        "confidence": 0.87
      },
      // ... 7 more tiles
    ],
    "summary": "Grid analysis: 2 tiles of Agriculture, 1 tiles of Barren, 2 tiles of Built-up, 2 tiles of Vegetation, 2 tiles of Water"
  },
  "answer": "Based on satellite analysis, Grid analysis: 2 tiles of Agriculture, 1 tiles of Barren, 2 tiles of Built-up, 2 tiles of Vegetation, 2 tiles of Water. The area shows significant agricultural presence with several tiles classified as Agriculture.",
  "timestamp": "2024-01-15T10:30:45.123456"
}

---

3. Before/After Change Detection

POST /api/query/change

Parameters:

• before_question (form data): Question about the before image
• after_question (form data): Question about the after image
• before_file (form data): Before satellite image
• after_file (form data): After satellite image

Example:

curl -X POST http://localhost:8000/api/query/change \
  -F "before_file=@before.png" \
  -F "after_file=@after.png" \
  -F "before_question=What was the land cover before?" \
  -F "after_question=What is the land cover now?"

Response:

{
  "change_id": "x9y8z7w6",
  "before": {
    "filename": "before.png",
    "question": "What was the land cover before?",
    "grounding": {
      "image_name": "before.png",
      "timestamp": "2024-01-15T10:30:45.123456",
      "grid_size": "3x3",
      "tiles": [
        {"tile_id": 0, "class": "Agriculture", "confidence": 0.92},
        {"tile_id": 1, "class": "Agriculture", "confidence": 0.88},
        // ... more tiles
      ],
      "summary": "Grid analysis: 4 tiles of Agriculture, 3 tiles of Vegetation, 2 tiles of Water"
    }
  },
  "after": {
    "filename": "after.png",
    "question": "What is the land cover now?",
    "grounding": {
      "image_name": "after.png",
      "timestamp": "2024-01-15T10:30:45.123456",
      "grid_size": "3x3",
      "tiles": [
        {"tile_id": 0, "class": "Water", "confidence": 0.91},
        {"tile_id": 1, "class": "Agriculture", "confidence": 0.89},
        // ... more tiles
      ],
      "summary": "Grid analysis: 2 tiles of Agriculture, 1 tiles of Built-up, 2 tiles of Vegetation, 4 tiles of Water"
    }
  },
  "change_detection": {
    "change_count": 2,
    "unchanged_count": 7,
    "changes": [
      {
        "tile_id": 0,
        "before_class": "Agriculture",
        "after_class": "Water",
        "confidence_change": -0.01
      },
      {
        "tile_id": 4,
        "before_class": "Vegetation",
        "after_class": "Built-up",
        "confidence_change": 0.03
      }
    ],
    "summary": "Detected 2 tile changes out of 9 tiles. 7 tiles remained unchanged. Changes: Tile 1: Agriculture → Water; Tile 5: Vegetation → Built-up"
  },
  "timestamp": "2024-01-15T10:30:45.123456"
}

---

Configuration

CORS Settings

The backend is pre-configured to accept requests from:

• http://localhost:5173 (Vite dev server)
• http://localhost:3000 (Alternative frontend port)

To add more origins, edit backend/config.py:

cors_origins: list = [
    "http://localhost:5173",
    "http://localhost:3000",
    "https://yourdomain.com",  # Add your domain here
]

Environment Variables

Create a .env file (from .env.example) for additional configuration:

DEBUG=True
APP_VERSION=1.0.0
CORS_ORIGINS=http://localhost:5173,http://localhost:3000

---

Mock Pipeline Architecture

1. Grounding Pipeline (Sai)

The grounding pipeline simulates satellite image analysis:

• Input: Satellite image
• Process: Analyzes image and creates a 3x3 grid (9 tiles)
• Classification: Each tile is classified into one of 5 land cover classes:
  • Agriculture
  • Water
  • Vegetation
  • Built-up
  • Barren
• Confidence: Each classification includes a confidence score (0.75-0.99)
• Output: Grid analysis with tiles and summary

Key Classes:

• GroundingTile: Represents a single tile with class and confidence
• GroundingResult: Represents the complete 3x3 grid analysis

2. Gemini Integration (Sid)

The Gemini simulator answers questions based on grounding data:

• Input: Question + Grounding data
• Process: Analyzes question keywords and grounding summary
• Intelligence: Context-aware responses based on question type
• Output: Natural language answer

Key Class:

• GeminiSimulator: Simulates Gemini API for question answering

3. Change Detection

Compares two grounding results to identify changes:

• Input: Before and after grounding results
• Process:
  • Compares each tile's classification
  • Calculates confidence changes
  • Identifies unchanged tiles
• Output: Detailed change report with tile-by-tile breakdown

Key Class:

• ChangeDetector: Detects and reports changes between images

4. Pipeline Orchestration

The MockPipeline class orchestrates all three components:

pipeline = MockPipeline()

# Process single image
result = pipeline.process_query(
    image_data=image_bytes,
    question="What agricultural areas are visible?",
    filename="image.png"
)

# Detect changes
changes = pipeline.detect_changes(
    before_image=before_bytes,
    after_image=after_bytes,
    before_question="What was here?",
    after_question="What is here now?",
    before_filename="before.png",
    after_filename="after.png"
)

---

File Descriptions

main.py

FastAPI application entry point. Sets up the app with CORS middleware and includes all route modules.

config.py

Configuration management using Pydantic Settings. Loads from environment variables and .env file. Centralized settings for CORS origins, API keys, and app settings.

routes/health.py

Simple health check endpoint that returns the backend status for monitoring and debugging.

routes/query.py

Core query endpoints:

• POST /api/query: Single image query with question
• POST /api/query/change: Before/after change detection

Handles file uploads and routes requests to the mock pipeline.

models/request.py

Pydantic request models for validation and API documentation:

• QueryRequest: Single image query model
• QueryChangeRequest: Before/after change detection model

services/mock_service.py

Complete mock pipeline implementation with:

• GroundingTile: Individual tile in the 3x3 grid
• GroundingResult: Complete grounding analysis
• GeminiSimulator: Question answering based on grounding
• ChangeDetector: Change detection logic
• MockPipeline: Orchestration of all components

---

Development Workflow

Adding New Endpoints

1. Create a new router file in routes/
2. Define your endpoint functions with proper docstrings
3. Include the router in main.py:

   app.include_router(new_router.router, prefix=settings.api_prefix, tags=["tag_name"])
   

Integrating Real Models

Replace the mock implementations in services/mock_service.py:

1. Replace Grounding: Integrate actual GeoRSCLIP model
2. Replace Gemini: Call real Google Gemini API
3. Update Change Detection: Use actual comparison logic

Testing

The endpoints can be tested using:

Swagger UI: http://localhost:8000/docs (interactive testing)

cURL (command line):

# Health check
curl http://localhost:8000/api/health

# Single image query
curl -X POST http://localhost:8000/api/query \
  -F "file=@image.png" \
  -F "question=What do you see?"

# Change detection
curl -X POST http://localhost:8000/api/query/change \
  -F "before_file=@before.png" \
  -F "after_file=@after.png" \
  -F "before_question=What?" \
  -F "after_question=What now?"

Python:

import requests

# Health check
response = requests.get("http://localhost:8000/api/health")
print(response.json())

# Single image query
files = {
    "file": open("image.png", "rb"),
}
data = {
    "question": "What agricultural areas are visible?"
}
response = requests.post("http://localhost:8000/api/query", files=files, data=data)
print(response.json())

---

Dependencies

Package	Version	Purpose
FastAPI	0.104.1	Modern web framework
Uvicorn	0.24.0	ASGI server
Pydantic	2.5.0	Data validation
pydantic-settings	2.1.0	Settings management
python-dotenv	1.0.0	Environment variable loading
python-multipart	0.0.6	File upload handling
httpx	0.25.2	Async HTTP client

---

Next Steps

Phase 1: Integration

• Connect frontend to /api/query endpoint
• Connect frontend to /api/query/change endpoint
• Test with actual satellite images

Phase 2: Real Models

• Replace mock grounding with GeoRSCLIP model
• Integrate Google Gemini API
• Add model loading and caching

Phase 3: Infrastructure

• Add database layer (PostgreSQL/MongoDB)
• Implement authentication (API keys/OAuth)
• Add rate limiting
• Set up error logging and monitoring

Phase 4: Production

• Write comprehensive test suite (pytest)
• Create Docker configuration
• Set up CI/CD pipeline
• Deploy to cloud platform

---

Troubleshooting

Backend won't start

# Check if port 8000 is already in use
lsof -i :8000

# Use a different port
python -m uvicorn main:app --port 8001 --reload

CORS errors in frontend

Check that your frontend origin is in config.py:

cors_origins: list = ["http://localhost:5173", "http://localhost:3000"]

File upload issues

Ensure python-multipart is installed:

pip install python-multipart

Import errors

Make sure you're running from the backend directory and dependencies are installed:

cd backend
pip install -r requirements.txt

---

Architecture Diagram

Frontend (localhost:5173)
        ↓
    CORS Middleware
        ↓
    FastAPI Router
    ├── /api/health → Health Check
    ├── /api/query → Query Handler
    │   └── MockPipeline
    │       ├── GroundingResult (3x3 grid analysis)
    │       ├── GeminiSimulator (Q&A)
    │       └── Query History
    └── /api/query/change → Change Detection Handler
        └── MockPipeline
            ├── Before Grounding
            ├── After Grounding
            ├── ChangeDetector (comparison)
            └── Query History

---

Support

For issues, questions, or feature requests, refer to:

• Interactive API docs: http://localhost:8000/docs
• Day 1 summary: day1-final.html
• Backend README: backend/README.md

---

Team

• Lakshya: Backend development
• Sai: Grounding pipeline
• Sid: Gemini integration

---

Build Date: 2024-01-15
Status: Ready for frontend integration
Version: 1.0.0