Skip to content

AsutoshaNanda/AirMate

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

5 Commits
LICENSE
LICENSE
 
 
README.md
README.md
 
 
Ultimate Flight AI Assistant.ipynb
Ultimate Flight AI Assistant.ipynb
 
 
flight_bookings.db
flight_bookings.db
 
 

Repository files navigation

✈️ AirMate - AI-Powered Flight Assistant

Python License Gradio OpenAI

A sophisticated multimodal AI airline assistant that combines LLM intelligence with real-time flight booking capabilities

Features • Demo • Installation • Usage • Architecture • API Reference

📋 Table of Contents

🎯 Overview

AirMate is an advanced demonstration of a multimodal airline assistant prototype that showcases the power of Large Language Models (LLMs) combined with deterministic business logic. Built as a comprehensive Jupyter Notebook, it integrates multiple AI APIs, programmatic tools, persistent storage, and a modern web interface to deliver a seamless flight booking experience.

What Makes AirMate Unique?

  • 🤖 Multi-LLM Integration: Leverages OpenAI GPT-4, Anthropic Claude, and Google Gemini APIs
  • 🛠️ Tool-Calling Architecture: Implements function calling for dynamic, context-aware responses
  • 🎨 Multimodal Capabilities: Generates travel images and converts text responses to speech
  • 💾 Persistent Bookings: SQLite database for storing confirmed flight reservations
  • 🌐 Translation Engine: Built-in multilingual support for global accessibility
  • 🎭 Interactive UI: Beautiful Gradio interface for intuitive user interactions

✨ Features

Core Capabilities

Feature Description
💰 Real-time Pricing Fetch ticket prices for multiple destinations with dynamic discount calculations
✈️ Flight Search Browse 100+ synthetic flights per city with real-time availability status
📝 Booking Management Complete booking workflow with PNR generation and SQLite persistence
🎨 AI-Generated Travel Art DALL-E 3 powered destination artwork in pop-art style
🔊 Text-to-Speech Natural voice responses using OpenAI's TTS-1 model
🌍 Multi-Language Support Translate conversations to 100+ languages with validation
🧠 Context-Aware Assistance Maintains conversation history for coherent multi-turn dialogues

Advanced Features

  • Tool Orchestration: LLM dynamically selects and chains function calls based on user intent
  • Booking State Management: Tracks booking requests across conversation turns
  • Data Validation: Integrated pycountry for language validation
  • Concise Responses: System-level prompt engineering for brief, accurate answers
  • Error Handling: Robust error management across API calls and tool executions

🎬 Demo

User Interaction Flow

User: "How much is a ticket to Moscow?"
├─> LLM analyzes query
├─> Calls get_ticket_prices("Moscow")
├─> Returns: "$363"
└─> Assistant: "A ticket to Moscow costs $363."

User: "What about with discounts?"
├─> LLM calls get_discounted_ticket_prices("Moscow")
├─> Calculates: $363 - 12% = $319
└─> Assistant: "Discounted price for Moscow is $319."

User: "Show me available flights"
├─> LLM calls get_flight_tickets("Moscow")
├─> Returns: 100 synthetic flights with details
├─> Generates travel artwork for Moscow
└─> Assistant: [Displays flights + travel image]

User: "Book flight AA1234 for John Doe"
├─> LLM calls confirm_and_save_booking(...)
├─> Saves to SQLite with PNR generation
└─> Assistant: "Booking confirmed! Your PNR is: X7K9M2L4"

Screenshots

(Add screenshots of your Gradio interface here)

🏗️ Architecture

System Design

┌─────────────────────────────────────────────────────────────┐
│                      Gradio Web Interface                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────────┐             │
│  │ Chat UI  │  │  Image   │  │ Translation  │             │
│  └──────────┘  └──────────┘  └──────────────┘             │
└───────────────────────┬─────────────────────────────────────┘
                        │
         ┌──────────────▼──────────────┐
         │   Chat Controller (chat())   │
         │  - Message routing           │
         │  - History management        │
         │  - Tool orchestration        │
         └──────────────┬──────────────┘
                        │
         ┌──────────────▼──────────────┐
         │    LLM Inference Layer      │
         │  ┌────────────────────────┐ │
         │  │ OpenAI GPT-4-mini      │ │
         │  │ + Tool Calling Support │ │
         │  └────────────────────────┘ │
         └──────────────┬──────────────┘
                        │
         ┌──────────────▼──────────────┐
         │  Tool Execution Engine      │
         │  (handle_all_tools())       │
         └──┬─────────┬─────────┬──────┘
            │         │         │
    ┌───────▼──┐  ┌──▼─────┐  ┌▼────────────┐
    │ Pricing  │  │ Flight │  │  Booking    │
    │ Tools    │  │ Search │  │  Tools      │
    └──────────┘  └────────┘  └──┬──────────┘
                                  │
                          ┌───────▼────────┐
                          │ SQLite Database │
                          │ (bookings)      │
                          └────────────────┘
         ┌────────────────────────────────────┐
         │    Multimodal Enhancement Layer    │
         │  ┌──────────┐    ┌──────────────┐ │
         │  │ DALL-E 3 │    │  TTS-1       │ │
         │  │ (Images) │    │  (Voice)     │ │
         │  └──────────┘    └──────────────┘ │
         └────────────────────────────────────┘

Data Flow

  1. User Input → Gradio Interface
  2. Message Routing → Chat controller with conversation history
  3. LLM Processing → GPT-4-mini with tool definitions
  4. Tool Invocation → Function execution based on LLM decision
  5. Response Generation → LLM synthesizes final answer
  6. Multimodal Enhancement → TTS + Image generation
  7. UI Update → Display text, audio, and visuals

📦 Installation

Prerequisites

  • Python: 3.8 or higher
  • FFmpeg: Required for audio processing (TTS playback)
  • API Keys: OpenAI, Anthropic, and Google AI

Step 1: Clone the Repository

git clone https://github.com/AsutoshaNanda/AirMate.git
cd AirMate

Step 2: Create Virtual Environment

# Using venv
python -m venv venv

# Activate on Windows
venv\Scripts\activate

# Activate on macOS/Linux
source venv/bin/activate

Step 3: Install Dependencies

pip install -r requirements.txt

Required packages:

gradio
requests
beautifulsoup4
python-dotenv
anthropic
openai
google-generativeai
pillow
pydub
pycountry

Step 4: Install FFmpeg

Windows (using Chocolatey):

choco install ffmpeg

macOS (using Homebrew):

brew install ffmpeg

Linux (Ubuntu/Debian):

sudo apt-get install ffmpeg

⚙️ Configuration

Environment Setup

Create a .env file in the project root:

# .env
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
GOOGLE_API_KEY=AIzaxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Security Best Practices

⚠️ CRITICAL: Never commit API keys to version control!

  1. Add .env to your .gitignore:

    .env
*.env

  2. Use environment-specific configuration:

    # For production
import os
OPENAI_API_KEY = os.environ.get('OPENAI_API_KEY')

  3. Consider using secret management tools:

    • AWS Secrets Manager
    • Azure Key Vault
    • HashiCorp Vault

🚀 Usage

Method 1: Jupyter Notebook (Recommended for Development)

# Install Jupyter if not already installed
pip install jupyter

# Launch notebook
jupyter notebook "Ultimate Flight AI Assistant.ipynb"

Execution Steps:

  1. Run cells sequentially from top to bottom
  2. Ensure all API keys are loaded successfully
  3. Execute until the Gradio interface launches
  4. Interface will open at http://127.0.0.1:7869

Method 2: Python Script

# Convert notebook to script
jupyter nbconvert --to script "Ultimate Flight AI Assistant.ipynb"

# Run the script
python "Ultimate Flight AI Assistant.py"

Method 3: Public Sharing (Gradio)

Modify the last cell in the notebook:

ui.launch(share=True)  # Creates a public URL for 72 hours

📁 Project Structure

AirMate/
│
├── 📓 Ultimate Flight AI Assistant.ipynb    # Main implementation
├── 📄 README.md                              # Project documentation
├── 📜 LICENSE                                # MIT License
├── 🔐 .env                                   # Environment variables (not in repo)
├── 📋 requirements.txt                       # Python dependencies
├── 💾 flight_bookings.db                     # SQLite database (auto-generated)
│
└── 📚 Notebook Sections:
    ├── Section 1: Environment & API Setup
    ├── Section 2: Data & Tool Definitions
    ├── Section 3: Multimodal Capabilities
    ├── Section 4: Booking Persistence
    ├── Section 5: Chat Controller & Tool Orchestration
    ├── Section 6: Translation Engine
    └── Section 7: Gradio UI Implementation

📚 API Reference

Core Functions

chat(message: str, history: list) -> tuple

Main conversation handler

Parameters:

  • message (str): User's input message
  • history (list): List of (user_msg, assistant_msg) tuples

Returns:

  • tuple: (assistant_response, generated_image)

Example:

response, image = chat("Find flights to Tokyo", [])

get_ticket_prices(destination_city: str) -> str

Fetches base ticket price for a destination

Parameters:

  • destination_city (str): City name (case-insensitive)

Returns:

  • str: Price string (e.g., "$363") or "Unknown"

Supported Cities: Moscow, Paris, Tokyo, Berlin, London, Sydney, Rome, Dubai, Singapore, Mumbai

get_discounted_ticket_prices(destination_city: str) -> str

Calculates and returns discounted price

Parameters:

  • destination_city (str): City name

Returns:

  • str: Formatted message with discounted price

Example Response:

"Discounted price for Tokyo is $337"

get_flight_tickets(destination_city: str) -> list

Retrieves available flights for a destination

Parameters:

  • destination_city (str): Target city

Returns:

  • list: List of flight dictionaries

Flight Object Structure:

{
    'flight_number': 'AA1234',
    'departure_time': '08:30 AM',
    'gate': 'A12',
    'availability': 'Available'  # or 'Not Available'
}

confirm_and_save_booking(...) -> dict

Persists booking to database and generates PNR

Parameters:

  • destination_city (str): Destination
  • flight_number (str): Selected flight
  • passenger_names (list): List of passenger names
  • seat_type (str): Economy/Business/First
  • passenger_type (str): Adult/Child/Senior
  • fare_type (str): Regular/Flexible
  • date_of_travel (str): YYYY-MM-DD format
  • num_passengers (int): Number of passengers

Returns:

{
    'status': 'success',
    'pnr': 'X7K9M2L4',
    'booking_summary': {...}
}

artist(cities: list) -> PIL.Image

Generates travel-themed artwork

Parameters:

  • cities (list): List of city names

Returns:

  • PIL.Image: Generated artwork

Model: DALL-E 3
Style: Pop art travel poster

talker(message: str) -> None

Converts text to speech and plays audio

Parameters:

  • message (str): Text to vocalize

Model: OpenAI TTS-1
Voice: Alloy
Output: Plays audio directly (local only)

translate(message: str, history: list, target_language: str) -> str

Translates conversation to target language

Parameters:

  • message (str): Current message
  • history (list): Conversation history
  • target_language (str): Target language (validated via pycountry)

Returns:

  • str: Translated text

Supported Languages: 100+ via pycountry validation

🔬 Technical Deep Dive

Tool-Calling Mechanism

AirMate implements OpenAI's function calling specification:

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_ticket_prices",
            "description": "Fetch ticket price for a destination",
            "parameters": {
                "type": "object",
                "properties": {
                    "destination_city": {
                        "type": "string",
                        "description": "The destination city"
                    }
                },
                "required": ["destination_city"]
            }
        }
    }
    # ... more tools
]

Execution Flow:

  1. LLM receives user query + tool definitions
  2. If tool needed, LLM returns tool_calls instead of text
  3. handle_all_tools() executes Python functions
  4. Tool results appended to message history
  5. LLM generates final natural language response

Database Schema

Table: bookings

Column Type Description
booking_id INTEGER PRIMARY KEY Auto-increment ID
pnr TEXT 8-character alphanumeric PNR
passenger_name TEXT Full name
destination_city TEXT Destination
flight_number TEXT Flight identifier
ticket_price TEXT Price with currency
seat_type TEXT Economy/Business/First
passenger_type TEXT Adult/Child/Senior
fare_type TEXT Regular/Flexible
date_of_travel TEXT ISO 8601 date
num_passengers INTEGER Total passengers

PNR Generation:

import random, string
pnr = ''.join(random.choices(string.ascii_uppercase + string.digits, k=8))
# Example: "X7K9M2L4"

System Prompt Engineering

system_message = """
You are a helpful AI assistant for an airline. 
Provide short, courteous answers, no more than 1 sentence. 
Always be accurate. If you don't know the answer, say so.
"""

Design Rationale:

  • Brevity: Reduces token usage and response time
  • Accuracy: Prevents hallucinations
  • Honesty: Admits uncertainty rather than fabricating answers

Customization: Remove the "1 sentence" constraint for more detailed responses:

system_message = """
You are a professional airline customer service assistant.
Provide comprehensive, accurate information about flights, bookings, and travel.
Use a friendly, helpful tone and structure complex responses clearly.
"""

Multimodal Integration

Image Generation Pipeline

def artist(cities: list) -> PIL.Image:
    city = cities[0] if cities else "generic destination"
    
    response = openai.images.generate(
        model="dall-e-3",
        prompt=f"A vibrant pop art travel poster for {city}...",
        size="1024x1024",
        response_format="b64_json"
    )
    
    image_data = base64.b64decode(response.data[0].b64_json)
    return Image.open(io.BytesIO(image_data))

TTS Audio Pipeline

def talker(message: str) -> None:
    response = openai.audio.speech.create(
        model="tts-1",
        voice="alloy",
        input=message
    )
    
    audio_data = io.BytesIO(response.content)
    audio = AudioSegment.from_file(audio_data, format="mp3")
    play(audio)  # Requires ffmpeg

⚠️ Limitations & Future Work

Current Limitations

Issue Impact Priority
Synthetic Flight Data No real-time inventory 🔴 High
Local SQLite Storage No multi-user support 🟡 Medium
No Authentication Security risk for production 🔴 High
TTS Local Playback Doesn't work in server deployments 🟡 Medium
No Payment Gateway Can't process real transactions 🔴 High
Limited Error Handling API failures may crash the app 🟠 Medium-High
No Rate Limiting Vulnerable to API quota exhaustion 🟡 Medium

Planned Enhancements

Phase 1: Production Readiness

  • Real Flight API Integration: Amadeus/Skyscanner API
  • PostgreSQL Migration: Replace SQLite with production DB
  • User Authentication: JWT-based auth system
  • Payment Integration: Stripe/PayPal gateway
  • Comprehensive Logging: ELK stack integration

Phase 2: Feature Expansion

  • Booking Modifications: Cancel/reschedule functionality
  • PNR Retrieval System: Lookup existing bookings
  • Email Notifications: Booking confirmations via SendGrid
  • Mobile App: React Native companion app
  • Admin Dashboard: Analytics and booking management

Phase 3: Scalability

  • Async API Calls: FastAPI backend with asyncio
  • Caching Layer: Redis for flight data caching
  • Load Balancing: Docker + Kubernetes deployment
  • CDN Integration: Cloudflare for static assets
  • Monitoring: Prometheus + Grafana dashboards

Phase 4: Advanced AI

  • Multi-Agent System: Specialized agents for search/booking/support
  • RAG Integration: Vector DB for policy/FAQ retrieval
  • Sentiment Analysis: Detect frustrated users and escalate
  • Voice Interface: Real-time voice booking via Whisper API
  • Predictive Pricing: ML models for price forecasting

🤝 Contributing

We welcome contributions! Here's how you can help:

Development Setup

# Fork and clone
git clone https://github.com/YOUR_USERNAME/AirMate.git
cd AirMate

# Create feature branch
git checkout -b feature/amazing-feature

# Make changes and test
python -m pytest tests/

# Commit with conventional commits
git commit -m "feat: add multi-city search"

# Push and create PR
git push origin feature/amazing-feature

Contribution Guidelines

  • Follow PEP 8 style guide
  • Add unit tests for new features
  • Update documentation for API changes
  • Keep commits atomic and well-described
  • Test on Python 3.8, 3.9, 3.10, 3.11

Areas Needing Help

  • 🐛 Bug fixes and error handling
  • 📚 Documentation improvements
  • 🧪 Unit test coverage
  • 🎨 UI/UX enhancements
  • 🌐 Internationalization (i18n)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2025 Asutosha Nanda

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.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

📞 Contact & Support

Author: Asutosha Nanda
GitHub: @AsutoshaNanda
Repository: AirMate

Get Help

🙏 Acknowledgments

  • OpenAI - GPT-4 and DALL-E 3 APIs
  • Anthropic - Claude API integration
  • Google - Gemini API support
  • Gradio Team - Exceptional UI framework
  • Open Source Community - All the amazing libraries used

📊 Project Stats

GitHub stars GitHub forks GitHub issues GitHub pull requests

⭐ Star this repository if you find it helpful! ⭐

Made with ❤️ by Asutosha Nanda

Back to Top

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages