feat: stage1 — domain schemas, SSE events, pydantic-settings config

src/gps_denied/config.py

@@ -0,0 +1,121 @@
+"""Application configuration loaded from environment / YAML."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class DatabaseConfig(BaseSettings):
+    """Database connection settings."""
+
+    model_config = SettingsConfigDict(env_prefix="DB_")
+
+    url: str = Field(
+        default="sqlite+aiosqlite:///./flight_data.db",
+        description="SQLAlchemy async connection URL",
+    )
+    echo: bool = False
+
+
+class APIConfig(BaseSettings):
+    """API server settings."""
+
+    model_config = SettingsConfigDict(env_prefix="API_")
+
+    host: str = "127.0.0.1"
+    port: int = 8000
+    reload: bool = True
+    cors_origins: list[str] = Field(default_factory=lambda: ["*"])
+
+
+class TileProviderConfig(BaseSettings):
+    """Satellite tile provider settings (Google Maps by default)."""
+
+    model_config = SettingsConfigDict(env_prefix="TILES_")
+
+    provider: str = "google"
+    api_key: str = ""
+    cache_dir: Path = Path("tile_cache")
+    zoom_level: int = 18
+    max_concurrent_requests: int = 4
+
+
+class ModelPaths(BaseSettings):
+    """Paths to ML model weights."""
+
+    model_config = SettingsConfigDict(env_prefix="MODEL_")
+
+    weights_dir: Path = Path("weights")
+    superpoint_path: str = "superpoint.pt"
+    lightglue_path: str = "lightglue.pt"
+    litesam_path: str = "litesam.pt"
+
+
+class OperationalArea(BaseSettings):
+    """Default operational boundaries."""
+
+    model_config = SettingsConfigDict(env_prefix="AREA_")
+
+    name: str = "Eastern Ukraine"
+    min_lat: float = 45.0
+    max_lat: float = 52.0
+    min_lon: float = 22.0
+    max_lon: float = 40.0
+
+
+class RecoveryConfig(BaseSettings):
+    """Failure recovery and progressive search settings."""
+
+    model_config = SettingsConfigDict(env_prefix="RECOVERY_")
+
+    search_grid_sizes: list[int] = Field(default_factory=lambda: [1, 4, 9, 16, 25])
+    min_chunk_frames: int = 5
+    max_chunk_frames: int = 20
+    user_input_threshold_tiles: int = 25
+    confidence_threshold_good: float = 0.7
+    confidence_threshold_degraded: float = 0.5
+    min_inlier_count_good: int = 50
+    min_inlier_count_tracking: int = 20
+
+
+class RotationConfig(BaseSettings):
+    """Image rotation and heading tracking settings."""
+
+    model_config = SettingsConfigDict(env_prefix="ROTATION_")
+
+    step_degrees: float = 30.0
+    litesam_max_tolerance: float = 45.0
+    sharp_turn_threshold: float = 45.0
+    heading_history_size: int = 10
+    confidence_threshold: float = 0.7
+
+    @property
+    def rotation_iterations(self) -> int:
+        return int(360 / self.step_degrees)
+
+
+class AppSettings(BaseSettings):
+    """Root settings — aggregates all sub-configs."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        env_nested_delimiter="__",
+        extra="ignore",
+    )
+
+    db: DatabaseConfig = Field(default_factory=DatabaseConfig)
+    api: APIConfig = Field(default_factory=APIConfig)
+    tiles: TileProviderConfig = Field(default_factory=TileProviderConfig)
+    models: ModelPaths = Field(default_factory=ModelPaths)
+    area: OperationalArea = Field(default_factory=OperationalArea)
+    recovery: RecoveryConfig = Field(default_factory=RecoveryConfig)
+    rotation: RotationConfig = Field(default_factory=RotationConfig)
+
+
+def get_settings() -> AppSettings:
+    """Singleton-like factory for application settings."""
+    return AppSettings()

src/gps_denied/schemas/__init__.py

@@ -0,0 +1,39 @@
+"""Domain models — GPS, Camera, Geometry."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class GPSPoint(BaseModel):
+    """WGS-84 coordinate."""
+
+    lat: float = Field(..., ge=-90, le=90, description="Latitude")
+    lon: float = Field(..., ge=-180, le=180, description="Longitude")
+
+
+class CameraParameters(BaseModel):
+    """Intrinsic camera parameters."""
+
+    focal_length: float = Field(..., gt=0, description="Focal length in mm")
+    sensor_width: float = Field(..., gt=0, description="Sensor width in mm")
+    sensor_height: float = Field(..., gt=0, description="Sensor height in mm")
+    resolution_width: int = Field(..., gt=0, description="Image width in pixels")
+    resolution_height: int = Field(..., gt=0, description="Image height in pixels")
+    principal_point: tuple[float, float] | None = None
+    distortion_coefficients: list[float] | None = None
+
+
+class Polygon(BaseModel):
+    """Bounding box defined by NW and SE corners."""
+
+    north_west: GPSPoint
+    south_east: GPSPoint
+
+
+class Geofences(BaseModel):
+    """Collection of geofence polygons."""
+
+    polygons: list[Polygon] = Field(default_factory=list)

src/gps_denied/schemas/events.py

@@ -0,0 +1,66 @@
+"""SSE event schemas."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel
+
+from gps_denied.schemas import GPSPoint
+
+
+class SSEEventType(str, Enum):
+    """Server-Sent Event types emitted during flight processing."""
+
+    FRAME_PROCESSED = "frame_processed"
+    FRAME_REFINED = "frame_refined"
+    SEARCH_EXPANDED = "search_expanded"
+    USER_INPUT_NEEDED = "user_input_needed"
+    PROCESSING_BLOCKED = "processing_blocked"
+    FLIGHT_COMPLETED = "flight_completed"
+
+
+class FrameProcessedEvent(BaseModel):
+    """Payload for frame_processed / frame_refined events."""
+
+    frame_id: int
+    gps: GPSPoint
+    altitude: float | None = None
+    confidence: float
+    heading: float | None = None
+    timestamp: datetime
+
+
+class SearchExpandedEvent(BaseModel):
+    """Payload for search_expanded event."""
+
+    frame_id: int
+    grid_size: int
+    message: str | None = None
+
+
+class UserInputNeededEvent(BaseModel):
+    """Payload for user_input_needed event."""
+
+    frame_id: int
+    reason: str
+    consecutive_failures: int = 0
+
+
+class FlightCompletedEvent(BaseModel):
+    """Payload for flight_completed event."""
+
+    frames_total: int
+    frames_processed: int
+    duration_seconds: float | None = None
+
+
+class SSEMessage(BaseModel):
+    """Generic SSE message wrapper."""
+
+    event: SSEEventType
+    data: dict[str, Any]
+    id: str | None = None
+    retry: int | None = None

src/gps_denied/schemas/flight.py

@@ -0,0 +1,162 @@
+"""Schemas for Flight API requests and responses."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from gps_denied.schemas import CameraParameters, Geofences, GPSPoint
+
+
+# ---------------------------------------------------------------------------
+# Waypoint
+# ---------------------------------------------------------------------------
+
+class Waypoint(BaseModel):
+    """Single waypoint with optional refinement flag."""
+
+    id: str
+    lat: float = Field(..., ge=-90, le=90)
+    lon: float = Field(..., ge=-180, le=180)
+    altitude: float | None = None
+    confidence: float = Field(..., ge=0, le=1)
+    timestamp: datetime
+    refined: bool = False
+
+
+# ---------------------------------------------------------------------------
+# Flight — Requests
+# ---------------------------------------------------------------------------
+
+class FlightCreateRequest(BaseModel):
+    """POST /flights body."""
+
+    name: str = Field(..., min_length=1, max_length=255)
+    description: str = ""
+    start_gps: GPSPoint
+    rough_waypoints: list[GPSPoint] = Field(default_factory=list)
+    geofences: Geofences = Field(default_factory=Geofences)
+    camera_params: CameraParameters
+    altitude: float = Field(..., gt=0)
+
+
+class UserFixRequest(BaseModel):
+    """POST /flights/{flightId}/user-fix body."""
+
+    frame_id: int = Field(..., ge=0)
+    uav_pixel: tuple[float, float]
+    satellite_gps: GPSPoint
+
+
+class ObjectToGPSRequest(BaseModel):
+    """POST /flights/{flightId}/frames/{frameId}/object-to-gps body."""
+
+    pixel_x: float = Field(..., ge=0)
+    pixel_y: float = Field(..., ge=0)
+
+
+# ---------------------------------------------------------------------------
+# Flight — Responses
+# ---------------------------------------------------------------------------
+
+class FlightResponse(BaseModel):
+    """Response after flight creation."""
+
+    flight_id: str
+    status: str
+    message: str | None = None
+    created_at: datetime
+
+
+class FlightDetailResponse(BaseModel):
+    """GET /flights/{flightId} response."""
+
+    flight_id: str
+    name: str
+    description: str
+    start_gps: GPSPoint
+    waypoints: list[Waypoint] = Field(default_factory=list)
+    geofences: Geofences
+    camera_params: CameraParameters
+    altitude: float
+    status: str
+    frames_processed: int = 0
+    frames_total: int = 0
+    created_at: datetime
+    updated_at: datetime
+
+
+class FlightStatusResponse(BaseModel):
+    """GET /flights/{flightId}/status response."""
+
+    status: str
+    frames_processed: int = 0
+    frames_total: int = 0
+    current_frame: int | None = None
+    current_heading: float | None = None
+    blocked: bool = False
+    search_grid_size: int | None = None
+    message: str | None = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class DeleteResponse(BaseModel):
+    deleted: bool
+    flight_id: str
+
+
+class UpdateResponse(BaseModel):
+    updated: bool
+    waypoint_id: str
+
+
+class BatchUpdateResponse(BaseModel):
+    success: bool
+    updated_count: int
+    failed_ids: list[str] = Field(default_factory=list)
+    errors: dict[str, str] | None = None
+
+
+# ---------------------------------------------------------------------------
+# Image Batch
+# ---------------------------------------------------------------------------
+
+class BatchMetadata(BaseModel):
+    """Metadata accompanying an image batch upload."""
+
+    start_sequence: int = Field(..., ge=0)
+    end_sequence: int = Field(..., ge=0)
+    batch_number: int = Field(..., ge=0)
+
+
+class BatchResponse(BaseModel):
+    """Response after batch upload."""
+
+    accepted: bool
+    sequences: list[int] = Field(default_factory=list)
+    next_expected: int = 0
+    message: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# User Fix
+# ---------------------------------------------------------------------------
+
+class UserFixResponse(BaseModel):
+    accepted: bool
+    processing_resumed: bool = False
+    message: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Object → GPS
+# ---------------------------------------------------------------------------
+
+class ObjectGPSResponse(BaseModel):
+    gps: GPSPoint
+    accuracy_meters: float
+    frame_id: int
+    pixel: tuple[float, float]