System Requirements Document for golden-jatayu

Introduction

This document outlines the system requirements for the JATAYU project, an interactive vision-language assistant designed for multimodal remote sensing image analysis through text queries. The project aims to address challenges in remote-sensing imagery analysis, such as complex GIS tools, cloud cover limitations, fragmented analysis, slow damage assessment, and lack of natural language access.

System Overview

JATAYU is a multi-agent framework that allows users to interact with satellite imagery using a conversational interface. It integrates various AI agents to perform tasks such as image validation, optical and SAR fusion, change detection, and geospatial reasoning. The system is designed to be explainable and auditable, providing outputs in JSON format with detailed execution traces.

Product Interpretation and Delivery Boundary

The JATAYU system is delivered as a web-based application with a backend powered by Python FastAPI. It supports user interactions through a conversational interface, allowing for natural language queries. The system is intended for use by remote sensing analysts, field officers, and data scientists. Access to the system requires user authentication to ensure secure handling of sensitive data and mission continuity. The application is designed to be scalable and capable of processing large datasets, subject to available computational resources.

Page Content and Component Coverage

Landing

• Information/State: Introduction to golden-jatayu, its purpose, and capabilities.
• Primary Actions: Navigate to Login.
• Components: Overview of features, benefits, and use cases.

Login

• Information/State: User authentication.
• Primary Actions: Log in to access the system.
• Components: Username and password fields, login button.

Dashboard

• Information/State: Summary of active missions.
• Primary Actions: Access mission details, start new analysis.
• Components: Mission list, quick access buttons.

Missions

• Information/State: List of all missions with identifiers and status.
• Primary Actions: Browse and resume missions.
• Components: Mission table, search and filter options.

Upload

• Information/State: Image upload interface.
• Primary Actions: Upload images to start a new mission.
• Components: File upload controls, metadata input fields.

Mission Details

• Information/State: Detailed view of a specific mission.
• Primary Actions: View progress, access stored data.
• Components: Metadata display, progress indicators.

Chat

• Information/State: Conversational interface for queries.
• Primary Actions: Submit natural language queries.
• Components: Chat input field, conversation history.

Analysis

• Information/State: Analysis workflow interface.
• Primary Actions: Initiate analysis based on uploaded data.
• Components: Workflow selection, execution progress.

Results

• Information/State: Display of analysis results.
• Primary Actions: Review JSON outputs.
• Components: Results summary, detailed data view.

Map

• Information/State: Geospatial visualization of results.
• Primary Actions: Explore map overlays and annotations.
• Components: Interactive map, overlay controls.

Reports

• Information/State: Compiled analysis reports.
• Primary Actions: Download and review reports.
• Components: Report list, download buttons.

Functional Requirements

APIs

• As a user, I want to upload images via the POST /upload API so that they can be processed for analysis.
• As a user, I want to analyze uploaded images via the POST /analyze API to receive actionable insights.
• As a user, I want to interact with the system using the POST /chat API to submit natural language queries.
• As a user, I want to retrieve mission details using the GET /mission/{id} API to track the progress and results of specific analyses.
• As a user, I want to access detailed reports using the GET /report/{id} API to review the findings of the analysis.

AI Agents

• As a user, I want the Intent Agent to understand my natural-language queries and map them to specific workflows.
• As a user, I want the Metadata Agent to validate GeoTIFF metadata, including CRS and timestamps.
• As a user, I want the Router Agent to select and execute the appropriate AI models based on my query and input modality.
• As a user, I want the Fusion Agent to perform optical and SAR image fusion for reliable flood detection.
• As a user, I want the RSVQA Agent to execute visual question answering on single images.
• As a user, I want the CDVQA Agent to conduct change analysis on before-and-after image pairs.
• As a user, I want the GeoReason Agent to convert image pixels into GPS coordinates and generate GeoJSON polygons.
• As a user, I want the SITREP Agent to compile analytical results, including maps, confidence scores, and damage statistics, into professional PDF and GeoJSON reports.

Context Engine

• As a user, I want each mission to generate a unique Mission ID for tracking and auditability.
• As a user, I want the system to store image paths, metadata, CRS, timestamps, previous queries, GeoJSON, and flood masks for each mission.

Router Logic

• As a user, I want the router to direct single images to the RSVQA Agent.
• As a user, I want the router to direct optical and SAR image pairs to the Fusion Agent.
• As a user, I want the router to direct before-and-after image pairs to the CDVQA Agent.

Outputs

• As a user, I want the system to return JSON outputs containing summary, confidence, area_km2, GPS coordinates, geojson_path, and execution_trace.

User Personas

Remote Sensing Analyst

• Context: Uses the interactive JATAYU assistant to upload and analyze satellite imagery.
• Primary Goal: To derive actionable insights for disaster management and urban planning.
• Responsibilities: Upload images, submit queries, review results and reports.
• Interactions: Engages with the system to perform detailed analyses and generate reports.

Field Officer

• Context: Utilizes natural language queries for field decision-making.
• Primary Goal: To obtain rapid, actionable insights from satellite data.
• Responsibilities: Submit queries, review analysis outputs, make field decisions.
• Interactions: Uses the system to quickly access and interpret data for immediate action.

Data Scientist

• Context: Integrates and validates data for accurate analysis.
• Primary Goal: To ensure the accuracy and reliability of the analysis.
• Responsibilities: Validate metadata, ensure data integrity, support analysis processes.
• Interactions: Works with the system to maintain data quality and support analytical accuracy.

Core User Flows

1. Image Upload and Analysis

   • Starting Context: User accesses the Upload page.
   • Action: User uploads images via the POST /upload API.
   • Result: System generates a unique Mission ID and stores relevant metadata.
   • Continuation: User submits a query via the POST /chat API.
   • Outcome: Router Agent selects the appropriate AI models based on the query.
   • Completion: Specialist AI models execute the analysis, and results are delivered in JSON format.

2. Report Generation and Retrieval

   • Starting Context: User accesses the Reports page.
   • Action: User requests a report via the GET /report/{id} API.
   • Result: SITREP Agent compiles the analysis results into a PDF report.
   • Completion: User downloads and reviews the report.

Visuals Colors and Theme

• Color Theme: Earth tones to reflect the geospatial nature of the application.
• Design Style: Clean and professional with a focus on usability and clarity.
• Palette: Background #F4F4F4, Surface #FFFFFF, Text #333333, Primary #FF8C00, Accent #008080, Muted #CCCCCC.

Signature Design Concept

• Interactive Chat Interface: Allows users to submit queries and receive responses in a conversational format.
• Map Visualization: Provides a visual representation of analysis results with overlays and annotations.

Interaction Model & Motion Direction

• Interaction Model: Conversational and intuitive, allowing users to interact with the system using natural language.
• Motion Tempo: Restrained; Hero Dimensionality: Flat.
• Hero Direction: A structured, modular hero with a diagrammatic representation of the multi-agent workflow on a warm grey background, using orange and teal accents for interactive highlights.

Non-Functional Requirements

• Performance: The system should process and return results within a reasonable timeframe to support real-time decision-making.
• Scalability: Capable of handling multiple concurrent users and large datasets.
• Security: Ensure secure access and data protection throughout the system.

Tech Stack

• Frontend: React, TypeScript, Tailwind CSS, Stitch UI Design, Framer Motion
• Backend: FastAPI, LangGraph, GPT-5 (LLM), PyTorch
• Geospatial & Database: PostgreSQL, PostGIS, Rasterio, GDAL
• AI Models & Datasets: BigEarthNet (Adaptation), RSVQA, VRSBench, CDVQA

Assumptions and Constraints

• The system assumes access to high-quality satellite imagery and metadata.
• The system is constrained by the availability of computational resources for processing large datasets.

Glossary

• GeoTIFF: A public domain metadata standard which allows georeferencing information to be embedded within a TIFF file.
• CRS: Coordinate Reference System, a coordinate-based local, regional or global system used to locate geographical entities.
• SAR: Synthetic Aperture Radar, a form of radar used to create two-dimensional images or three-dimensional reconstructions of objects.
• VQA: Visual Question Answering, a task that involves answering questions about images.