Layover Legend API

AI-powered layover planning system with CrewAI orchestration and ArcGIS routing integration.

Architecture

• Backend: FastAPI with async request handling
• AI Engine: CrewAI agents with OpenAI GPT-4
• Vector Search: LanceDB with OpenAI embeddings
• Routing: ArcGIS World Routing Service
• Geocoding: ArcGIS World Geocoding Service

Quick Start

# Install dependencies
pip install -r requirements.txt requirements_api.txt

# Set environment variables
export OPENAI_API_KEY="your_key"
export ARCGIS_API_KEY="your_key"

# Start API server
python -m uvicorn src.api.main:app --reload --host 0.0.0.0 --port 8000

API Endpoints

Endpoint	Method	Purpose
/	GET	Health check
/airports	GET	Available airports
/pois	GET	All POIs with coordinates
/search-places	POST	Semantic POI search
/calculate-route	POST	Point-to-point routing
/plan-multi-stop-route	POST	Multi-stop optimization
/plan-layover	POST	AI-powered planning

Core Features

Semantic Search

• OpenAI text-embedding-ada-002 embeddings
• LanceDB vector similarity search
• 22 NYC POIs with ArcGIS geocoded coordinates

Route Planning

• ArcGIS World Routing Service integration
• Multi-modal transport (walking, driving)
• Real-time traffic consideration
• Complete route geometry for mapping

AI Agent System

• CrewAI orchestration with specialized tools
• Natural language preference extraction
• TIMECAT-based visit duration calculation
• Airport logistics and buffer time management

Request/Response Format

Plan Layover Request

{
  "query": "I love to walk and I love bars",
  "user_preferences": {},
  "airport": "LGA",
  "layover_hours": 6
}

Response Structure

{
  "success": true,
  "text_response": "Complete itinerary text...",
  "locations": [
    {
      "name": "LGA Airport",
      "address": "LaGuardia Airport",
      "category": "Airport",
      "latitude": 40.7769,
      "longitude": -73.8740
    }
  ],
  "routes": [...],
  "arcgis_route_data": {...},
  "frontend_ready": {...}
}

Data Models

POI Structure

{
  "name": str,
  "address": str,
  "category": str,
  "description": str,
  "latitude": float,
  "longitude": float,
  "visit_time": int,
  "time_category": int  # TIMECAT 1-3
}

TIMECAT System

• 1: 30 minutes (quick stops)
• 2: 60 minutes (standard visits)
• 3: 180 minutes (extended experiences)

Development

Project Structure

src/
├── api/main.py           # FastAPI endpoints
├── core/layover_system.py # CrewAI agents & tools
└── config/settings.py    # Environment config

Testing

# Run API tests
python tests/test_api.py

# Test production system
python tests/test_production_system.py

# Generate system diagrams
python scripts/generate_crewai_diagram.py

Environment Variables

OPENAI_API_KEY=sk-...
ARCGIS_API_KEY=...

Performance

• Search Response: 200-400ms
• Route Calculation: 500-1000ms
• Complete Planning: 2-5 seconds
• Geocoding Success Rate: >95%

Integration

Frontend Mapping

• ArcGIS-compatible route geometry
• WGS84 coordinate system
• Turn-by-turn directions
• Complete stop sequence

API Clients

• Swagger UI: http://localhost:8000/docs
• OpenAPI JSON: http://localhost:8000/openapi.json
• CORS enabled for frontend development

Production Deployment

Requirements

• Python 3.8+
• OpenAI API access
• ArcGIS Developer account
• 512MB+ RAM
• Internet connectivity

Scaling Considerations

• OpenAI rate limits: 3,500 RPM
• ArcGIS rate limits: 50,000 requests/day
• LanceDB: Handles 1000s of vectors efficiently
• Memory usage: ~50MB for current dataset

Troubleshooting

Common Issues

• Missing API keys: Check .env file
• Geocoding failures: Uses NYC center fallback
• Route calculation errors: Verify coordinates
• Memory issues: Increase Python heap size

Debug Mode

from src.core.layover_system import test_system
test_system()  # Comprehensive system check

API Documentation

• Complete API Reference
• Embedding System Details
• System Architecture
• Swagger UI

---

Author: Said Lfagrouche
License: MIT