FlyMind is an intelligent flight data platform that combines AI-driven search, real-time Google Flights scraping, price analytics, and automation tools for developers, travelers, and enterprises.

With FastAPI, Streamlit, and Playwright, FlyMind delivers the performance of an API with the interactivity of a dashboard — perfect for n8n workflows, AI chatbots, and real-time travel data pipelines.

• 🤖 n8n Workflows - HTTP Request nodes with optimized JSON responses
• 💬 Chatbots - Natural language flight queries and booking
• 🔄 Automation - Scheduled searches and price monitoring
• 🏢 Enterprise - Multi-tenant APIs with comprehensive logging
• 🧪 Testing - Professional Streamlit interface for API testing

# Clone the repository
git clone https://github.com/AbdirahmanNomad/flymind.git
cd flymind

# Install dependencies
pip install -r api/requirements.txt

# Install Playwright browsers
playwright install chromium

# Terminal 1: Start the API server
export PYTHONPATH=/Users/maanowork/flightstestgoogle:$PYTHONPATH
cd /Users/maanowork/flightstestgoogle
PORT=8001 uvicorn api.api:app --host 0.0.0.0 --port 8001 --reload

# Terminal 2: Start the Streamlit interface
export PYTHONPATH=/Users/maanowork/flightstestgoogle:$PYTHONPATH
cd /Users/maanowork/flightstestgoogle
streamlit run streamlit_app.py --server.port 8501

Note: Replace /Users/maanowork/flightstestgoogle with your actual project path.

• 🌐 API Server: http://localhost:8001
• 🎨 Streamlit App: http://localhost:8501
• 📖 API Docs: http://localhost:8001/docs

Run the comprehensive test suite:

python3 test_all_features.py

✅ Test Results: 12/12 tests passing (100%)

This will test:

• ✅ API health and endpoints
• ✅ Single, round-trip, and multi-city searches
• ✅ Progress indicators and exports
• ✅ Flight comparison and history
• ✅ Price alerts and webhooks
• ✅ Input validation and AI search

Latest Test Run:

✅ PASSED: 1. API Health Check
✅ PASSED: 2. Single Flight Search
✅ PASSED: 3. Round-Trip Search
✅ PASSED: 4. Multi-City Search
✅ PASSED: 5. Progress Indicators
✅ PASSED: 6. Export Format (CSV/JSON)
✅ PASSED: 7. Flight Comparison
✅ PASSED: 8. Search History
✅ PASSED: 9. Price Alerts
✅ PASSED: 10. Webhooks
✅ PASSED: 11. Input Validation
✅ PASSED: 12. AI-Powered Search

Total: 12/12 tests passed (100%)
🎉 All features working correctly!

POST /search
Content-Type: application/json

{
  "origin": "New York",
  "destination": "London",
  "depart_date": "2025-12-25",
  "return_date": "2025-12-30",
  "adults": 1,
  "seat_class": "economy",
  "fetch_mode": "local"
}

✨ Smart Features:

• City Name Support: "New York" → JFK, "London" → LHR
• Flexible Dates: "weekend", "+3 days", "december"
• Multi-city Support: Full support for complex itineraries (2-5 segments) - ✅ Tested and working
• Real-time Pricing: Live Google Flights data
• Caching: Redis caching for faster repeated searches
• Async Performance: Non-blocking async/await architecture
• Search History: Automatic tracking with search_id for all searches
• Error Handling: Proper validation with 400 status codes

{
  "success": true,
  "total_flights": 25,
  "flights": [
    {
      "name": "British Airways",
      "departure": "8:00 AM on Wed, Dec 25",
      "arrival": "11:30 AM on Wed, Dec 25",
      "duration": "7 hr 30 min",
      "stops": 0,
      "price": "SEK 8,450",
      "delay": null
    }
  ],
  "search_url": "https://www.google.com/travel/flights?...",
  "timestamp": "2025-11-03T20:13:02"
}

POST /webhooks
Content-Type: application/json

{
  "webhook_url": "https://your-app.com/webhook/flight-alerts"
}

POST /ai/search
Content-Type: application/json

{
  "query": "Find me the cheapest flight from Paris to Tokyo next weekend",
  "api_key": "sk-your-openai-key" // optional, can set OPENAI_API_KEY env var
}

✨ AI Features:

• Natural Language Processing: Parse complex flight queries
• Intelligent Parameter Extraction: Origin, destination, dates, preferences
• Smart Defaults: Fills in missing parameters automatically
• Real-time Search: Executes actual flight search after parsing

Example Queries:

• "Find cheap flights from Paris to Tokyo next weekend"
• "Show me round-trip flights to London in December"
• "Find business class flights from NYC to LA for next month"

POST /alerts
Content-Type: application/json

{
  "trip_type": "round-trip",
  "origin": "New York",
  "destination": "London",
  "depart_date": "2025-12-25",
  "return_date": "2025-12-30",
  "target_price": 5000.0,
  "currency": "SEK",
  "email": "[email protected]",
  "notification_channels": ["email", "webhook"]
}

✨ Enhanced Features:

• Trip Types: one-way, round-trip, multi-city
• Multi-Currency: SEK, USD, EUR, GBP
• Flexible Dates: Return date for round-trip alerts
• Notification Channels: Email and webhook support

The professional Streamlit interface provides comprehensive flight search and analytics capabilities:

• 🔍 Advanced Flight Search:

  • Single, round-trip, and multi-city search support
  • City name recognition (e.g., "New York" → JFK)
  • Flexible date parsing ("weekend", "+3 days")
  • Advanced filters (stops, class, airlines)

• ⚡ Real-Time Progress Indicators:

  • Live progress bars during searches
  • Status updates with completion percentage
  • Estimated time remaining
  • Search duration tracking

• 📊 Flight Comparison:

  • Side-by-side comparison of multiple searches
  • Price trend charts and visualizations
  • Best time to book recommendations
  • Comparison tables with key metrics

• 📚 Search History:

  • Automatic saving of all searches (last 50)
  • Favorite routes with quick access
  • Quick re-search from history
  • Filter and sort options

• 📥 Export Functionality:

  • CSV Export: Download results as CSV
  • JSON Export: Download as JSON
  • Print View: Print-friendly JSON format
  • Share Links: Shareable search result links

• 💰 Price Alerts:

  • Create price monitoring alerts
  • View and manage all alerts
  • Multi-currency support
  • Email and webhook notifications

• 📊 Real-time Metrics: Flight counts, price averages, statistics

• 💰 Smart Pricing: Color-coded price indicators (🟢 cheap, 🟡 average, 🔴 expensive)

• 🔗 Direct Links: One-click access to Google Flights

• ⚙️ API Health: Real-time connection monitoring

Plan complex itineraries with multiple stops:

• Add 2-5 flight segments
• Each segment with origin, destination, and date
• Automatic city-to-airport code conversion
• Segment-specific flight results
• ✅ Fully tested and working (10 flights found in test)

See exactly what's happening during searches:

• Progress bar (0-100%)
• Status text updates
• Estimated time remaining
• Actual completion time
• ✅ Tested: Average search time ~8.5 seconds

Compare multiple searches side-by-side:

• Select multiple searches to compare
• Comparison table with metrics
• Price trend bar charts
• Best time to book recommendations
• Smart tips (e.g., "Book 2-3 months in advance")
• ✅ Tested with 137 vs 35 flights comparison

Never lose your searches:

• Automatic history saving with search_id
• Favorite routes (⭐)
• Quick re-search button
• View results from history
• Filter by favorites
• Sort by newest/oldest
• ✅ API endpoint tested: /search/{search_id} working

Download and share your results:

• CSV Export: Open in Excel, Google Sheets - ✅ Tested (7.5KB+ files)
• JSON Export: For developers and APIs - ✅ Tested (20KB+ files)
• Print View: Print-friendly formatted JSON (checkbox-enabled)
• Share Links: Shareable search URLs with search_id

• Automatic History: All searches saved with unique search_id
• History Endpoint: Retrieve past searches via /search/{search_id}
• Multi-City Support: History works for all trip types
• Favorites: Save favorite routes for quick access

┌─────────────────────────────────────────────────────────┐
│  🧠 FlyMind - AI-Powered Flight Analytics                │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  Trip Type: [○ One Way] [○ Round Trip] [● Multi City]   │
│                                                          │
│  🌍 Multi-City Route                                     │
│  ┌──────────────────────────────────────────────┐      │
│  │ Segment 1: [NYC] → [LAX] [📅 Dec 7]         │      │
│  │ Segment 2: [LAX] → [SFO] [📅 Dec 14]        │      │
│  └──────────────────────────────────────────────┘      │
│                                                          │
│  [🔍 Search Multi-City Flights]                         │
│                                                          │
│  🔄 Searching flights... 45% complete                    │
│  ████████████████░░░░░░░░░░░░░░░░                       │
│  ⏱️ Estimated time remaining: 12s                        │
│                                                          │
│  ✅ Found 137 flights in 8.2s                           │
│                                                          │
│  📊 Results & Export                                     │
│  [📥 Download CSV] [📥 Download JSON] [🔗 Share] [📄 Print]│
│                                                          │
│  📊 Enable Flight Comparison ☑                          │
│  ┌──────────────────────────────────────────────┐      │
│  │ Search 1: 137 flights | Lowest: SEK 4,200   │      │
│  │ Search 2: 35 flights  | Lowest: SEK 5,100   │      │
│  │ 💡 Best price: Search 1 (SEK 4,200)          │      │
│  └──────────────────────────────────────────────┘      │
│                                                          │
│  📚 Search History                                       │
│  ⭐ NYC → LAX (2025-11-04) [🔍 Re-search] [👁️ View]    │
│     LAX → SFO (2025-11-04) [⭐ Favorite] [🔍 Re-search] │
└─────────────────────────────────────────────────────────┘

1. Add HTTP Request Node to your n8n workflow
2. Method: POST
3. URL: http://localhost:8001/search
4. Body Content Type: JSON
5. Body:

{
  "origin": "{{ $json.origin }}",
  "destination": "{{ $json.destination }}",
  "depart_date": "{{ $json.depart_date }}",
  "adults": "{{ $json.adults || 1 }}",
  "seat_class": "economy"
}

Webhook → HTTP Request → Function → Email/Slack
    ↓           ↓           ↓         ↓
Trigger   Search API   Process    Notify
          Flights     Results

# Build and run
docker build -t flymind-api api/
docker run -p 8001:8001 flymind-api

# Or use docker-compose
docker-compose -f api/docker-compose.yml up

version: '3.8'
services:
  api:
    build: ./api
    ports:
      - "8001:8001"
    environment:
      - ENVIRONMENT=production
    restart: unless-stopped

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Streamlit     │    │     FastAPI     │    │   Google        │
│   Interface     │◄──►│     Server      │◄──►│   Flights       │
│                 │    │                 │    │                 │
│ • User Forms    │    │ • REST API      │    │ • Real-time     │
│ • Results       │    │ • Webhooks      │    │ • Data          │
│ • Analytics     │    │ • Validation    │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌─────────────────┐
                       │   Playwright    │
                       │   Browser       │
                       │   Automation    │
                       └─────────────────┘

• 🎨 Streamlit App: Professional testing interface
• 🚀 FastAPI Server: High-performance REST API
• 🌐 Playwright Engine: Anti-detection browser automation
• 🤖 City Parser: Intelligent location recognition
• 💰 Price Monitor: Alert system for fare changes

# API Configuration
PORT=8001
ENVIRONMENT=development
APP_NAME=FlyMind

# CORS Configuration
ALLOWED_ORIGINS=*  # or comma-separated list: http://localhost:3000,https://app.example.com

# Security
REQUIRE_API_KEY=false  # Set to true to enable API key authentication
API_KEY=your-super-secret-api-key
API_KEY_HEADER=X-API-Key

# Rate Limiting
RATE_LIMIT_ENABLED=false  # Set to true to enable rate limiting
RATE_LIMIT_REQUESTS=100  # Requests per window
RATE_LIMIT_WINDOW=60  # Window in seconds

# Database
DATABASE_URL=sqlite:///./flymind.db  # SQLite by default

# Browser Automation
PLAYWRIGHT_BROWSERS_PATH=/opt/playwright

# Optional: Redis for caching
REDIS_ENABLED=false  # Set to true to enable Redis caching
REDIS_URL=redis://localhost:6379/0

# Optional: CAPTCHA Solving
CAPTCHA_API_KEY=your_2captcha_key

# Optional: AI API Keys
OPENAI_API_KEY=sk-your-openai-key
GOOGLE_AI_API_KEY=your-google-ai-key
DEEPSEEK_API_KEY=sk-your-deepseek-key

If any files import from the old package names, update them:

# Old imports (update these)
from flightstestgoogle import flights
from google-flights-api import search_flights

# New imports
from flymind import flights
from flymind.api import search_flights

# Custom browser configuration
BROWSER_CONFIG = {
    "headless": True,
    "viewport": {"width": 1920, "height": 1080},
    "user_agent": "Mozilla/5.0...",
    "locale": "en-US"
}

# Run all feature tests
python3 test_all_features.py

# Test specific features
python3 test_features.py

# API unit tests
cd api && python -m pytest tests/ -v

# Integration tests
python -m pytest tests/test_integration.py

✅ All 12 features tested and verified working (100% pass rate)

All features are tested systematically:

• ✅ API Health Check - Server status and version info
• ✅ Single Flight Search - One-way flight searches with city name recognition
• ✅ Round-Trip Search - Return flight searches with date validation
• ✅ Multi-City Search - Complex itineraries with 2-5 segments
• ✅ Progress Indicators - Real-time search progress (UI feature)
• ✅ Export Format (CSV/JSON) - Data export functionality
• ✅ Flight Comparison - Side-by-side comparison with charts
• ✅ Search History - Persistent search tracking with search_id
• ✅ Price Alerts - Alert creation and management
• ✅ Webhooks - Webhook registration (JSON and Form support)
• ✅ Input Validation - Comprehensive input sanitization and validation
• ✅ AI-Powered Search - Natural language flight queries

Test Coverage:

• API endpoints: 100% tested
• Input validation: Comprehensive error handling
• Database operations: All CRUD operations verified
• Multi-city support: Fully functional with segment tracking
• Error handling: Proper HTTP status codes (400, 404, 500)

# Linting and formatting
black api/ streamlit_app.py
flake8 api/ streamlit_app.py
mypy api/

# Security scanning
bandit -r api/
safety check

• 🔍 Search Analytics: Popular routes and patterns
• ⚡ Performance: Response times and success rates
• 💰 Price Tracking: Historical fare data
• 🌍 Geographic: Origin/destination insights
• 📈 Usage Stats: API call volumes and patterns

# API Health
curl http://localhost:8001/health

# Version Info
curl http://localhost:8001/version

# Metrics (future)
curl http://localhost:8001/metrics

• ✅ Input Validation: Comprehensive request sanitization and validation
• ✅ CORS Protection: Environment-based configurable origin restrictions
• ✅ Rate Limiting: Built-in IP-based throttling mechanisms
• ✅ API Key Authentication: Optional API key middleware
• ✅ Security Headers: XSS protection, content type options, frame options
• ✅ Error Handling: Secure error responses with structured logging
• ✅ Data Privacy: SQLite database for persistent storage (no external services)
• ✅ Non-root Docker: Runs as non-root user for enhanced security
• ✅ Async Architecture: Non-blocking async/await for better performance

We welcome contributions! Please see our Contributing Guide for details.

# Install development dependencies
pip install -r requirements-dev.txt

# Install pre-commit hooks
pre-commit install

# Run development server
make dev

# Run tests
make test

• Python: PEP 8 with Black formatting
• API: RESTful design principles
• Testing: 90%+ coverage required
• Documentation: All public APIs documented

MIT License - Open source and free to use commercially.

Copyright (c) 2025 Abdirahman Ahmed

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

• 📖 Documentation: API Docs
• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: Contact via GitHub Issues

• 🌟 Star us on GitHub if you find this useful!
• 🔗 Share with fellow developers and automation enthusiasts
• 💝 Contribute features, bug fixes, or documentation

Core Functionality:

• ✅ Single flight search
• ✅ Round-trip search
• ✅ Multi-city search (2-5 segments) - Fully tested and working
• ✅ Real-time Google Flights scraping
• ✅ City name to airport code conversion
• ✅ Flexible date parsing
• ✅ Search ID tracking for history

User Experience (Streamlit):

• ✅ Multi-city search UI with dynamic segments
• ✅ Real-time progress indicators with time estimates
• ✅ Flight comparison (side-by-side, charts, recommendations)
• ✅ Search history with favorites and quick re-search
• ✅ Export to CSV/JSON
• ✅ Print-friendly view (checkbox-enabled)
• ✅ Shareable links

Performance & Architecture:

• ✅ Async/await architecture
• ✅ Redis caching (optional)
• ✅ Response caching with TTL
• ✅ Non-blocking operations

Security:

• ✅ Environment-based configuration
• ✅ API key authentication (optional)
• ✅ Rate limiting per IP
• ✅ Input validation and sanitization
• ✅ Security headers middleware
• ✅ Non-root Docker user
• ✅ Proper HTTP status codes (400 for validation errors)

Database & Persistence:

• ✅ SQLite database integration
• ✅ Search history persistence (with search_id)
• ✅ Price alerts storage
• ✅ Webhook management
• ✅ Multi-city search history support

Testing:

• ✅ Comprehensive pytest test suite
• ✅ Feature testing script (test_all_features.py)
• ✅ API endpoint validation
• ✅ 100% test pass rate (12/12 tests)

All Features Tested and Verified: 12/12 (100%)

✅ API Health Check          - Server responding correctly
✅ Single Flight Search      - 137 flights found in test
✅ Round-Trip Search        - 151 flights found in test
✅ Multi-City Search        - 10 flights found in test
✅ Progress Indicators       - UI feature working
✅ Export Format (CSV/JSON) - Export functionality verified
✅ Flight Comparison        - Comparison ready (2+ searches)
✅ Search History           - search_id tracking working
✅ Price Alerts             - Alert creation successful
✅ Webhooks                 - Registration working (JSON/Form)
✅ Input Validation         - Proper error handling (400 codes)
✅ AI-Powered Search        - AI endpoint functional

Test Results: All tests passing with comprehensive coverage of:

• API endpoints
• Database operations
• Input validation
• Error handling
• Multi-city support
• Search history tracking

Built with ❤️ using:

• FastAPI - Modern async web framework
• Playwright - Cross-browser automation
• Streamlit - Data app framework
• n8n - Workflow automation platform
• Google Flights - Flight data source
• SQLAlchemy - Database ORM
• Pydantic - Data validation
• Redis - Caching (optional)

Special thanks to the open-source community!