Add GTFS-based Transit Edge Provider for Public Transit Routing

[Copilot]

This PR implements a new "transit" edge provider in the Python extensions that enables pathfinding on public transit networks using GTFS (General Transit Feed Specification) data.

Overview

The transit provider implements the exact edge expansion specification requested:

1. [lat/lon/time] → nearby stops with stop_id and arrival time
2. [stop_id] → boarding vertices for vehicle departures in next X hours
3. [boarding vertex] → alright vertex at next stop on trip
4. [alright vertex] → boarding vertex (transfers) + stop vertex (exits)

Implementation Details

Core Components

• GTFSParser: Parses GTFS files (stops.txt, routes.txt, trips.txt, stop_times.txt) with robust error handling
• TransitProvider: Main edge provider implementing the EdgeProvider protocol
• Vertex state machine: Implements the 4-state transition system (coordinates → stops → boarding → alright → transfers)

Key Features

• Time-based scheduling: Uses seconds-since-midnight representation for precise timing
• Spatial queries: Efficient nearby stop finding with configurable search radius
• Multi-modal support: Handles different transit modes (bus, rail, subway, etc.)
• Transfer planning: Supports seamless transfers between routes
• Configurable parameters: Search radius, departure windows, walking speed, etc.

Usage Example

from graphserver.core import Engine, Vertex
from graphserver.providers.transit import TransitProvider

# Initialize with GTFS data
transit = TransitProvider("/path/to/gtfs/directory")

# Register with planning engine
engine = Engine()
engine.register_provider("transit", transit)

# Plan journey from coordinates to transit stop
start = Vertex({
    "lat": 40.7589,
    "lon": -73.9851, 
    "time": 8 * 3600  # 08:00:00
})

goal = Vertex({"stop_id": "destination_station"})
result = engine.plan(start=start, goal=goal)

Testing & Validation

• Comprehensive test suite: Full coverage of all vertex types and edge cases
• Integration demos: Working examples showing real transit pathfinding
• Edge case handling: Midnight rollovers, end-of-trip scenarios, invalid data
• Performance tested: Efficient parsing and lookup for large GTFS datasets

Files Added

• python/src/graphserver/providers/transit/ - New transit provider module
• python/src/graphserver/providers/transit/gtfs_parser.py - GTFS parsing functionality
• python/src/graphserver/providers/transit/provider.py - Main transit provider class
• python/tests/test_transit_provider.py - Comprehensive test suite
• python/examples/transit_demo.py - Usage demonstration
• Documentation and integration with existing provider system

The implementation follows the existing code patterns and integrates seamlessly with the Graphserver architecture while providing powerful new transit routing capabilities.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.