A Gradio-based chat application powered by a fine-tuned LLM (Llama-3.2-1B-Instruct with QLoRA adapter) for booking domestic flights across Nigeria.
- Nigerian Language Support: Understands Nigerian English, Pidgin, and standard English
- Flight Search: Search for available flights between Nigerian cities
- Live Price Lookup: Get real-time flight prices via SERPER web search + GPT-4-mini extraction (no mock data)
- User Registration: Register users and persist in SQLite database
- Flight Booking: Book flights and generate beautiful boarding passes
- Conversation History: Maintains context across the conversation
- Truthful Data: All prices and flight information come from live web sources
Lagos, Abuja, Port Harcourt, Kano, Enugu, Calabar, Benin, Warri, Kaduna, Ibadan
- Air Peace
- Arik Air
- Ibom Air
- Azman Air
- Dana Air
flowchart TD
A[🙋 User Starts Chat] --> B{Intent Detection}
B -->|Greeting| C[👋 Welcome Message]
C --> D[User States Travel Request]
B -->|Booking Intent| E{User Registered?}
B -->|Price Inquiry| P[💰 Get Live Flight Prices]
P --> P1[SERPER Web Search]
P1 --> P2[GPT-4-mini Price Extraction]
P2 --> P3[Display Live Prices]
P3 --> D
E -->|No| F[📝 Show Registration Form]
F --> G[User Enters Details]
G --> H[Save to SQLite]
H --> I[✅ Registration Complete]
E -->|Yes| J[🛫 Show Airline Selection]
I --> J
J --> K[User Selects Airline]
K --> L[Fetch Available Flights]
L --> M[⏰ Show Flight Options]
M --> N[User Selects Flight]
N --> O[Book Flight]
O --> Q[Save Booking to SQLite]
Q --> R[Generate Booking Reference]
R --> S[🎫 Display Boarding Pass]
S --> T{Book Another?}
T -->|Yes| U[🔄 Reset State]
U --> D
T -->|No| V[👋 End Session]
flowchart TB
subgraph UI["🖥️ Gradio UI (app.py)"]
Chat[Chat Interface]
RegForm[Registration Form]
AirlineSelect[Airline Radio Buttons]
FlightSelect[Flight Radio Buttons]
BoardingPass[Boarding Pass Display]
end
subgraph Orchestrator["🧠 LLM Orchestrator (orchestrator.py)"]
LLM[Fine-tuned Llama 3.2-1B]
Adapter[QLoRA Adapter]
IntentDetect[Intent Detection]
EntityExtract[Entity Extraction]
ToolParser[Tool Call Parser]
end
subgraph Tools["🔧 Tools (tools.py)"]
SearchFlights[search_flights]
GetAirlineFlights[get_airline_flights]
CheckUser[check_user_registration]
RegisterUser[register_new_user]
BookFlight[book_flight]
GetPrices[get_flight_prices]
GetHistory[get_user_booking_history]
end
subgraph External["🌐 External APIs"]
SERPER[SERPER API]
OpenAI[OpenAI GPT-4-mini]
end
subgraph Database["💾 SQLite (database.py)"]
Users[(Users Table)]
Bookings[(Bookings Table)]
end
Chat --> Orchestrator
RegForm --> RegisterUser
AirlineSelect --> GetAirlineFlights
FlightSelect --> BookFlight
LLM --> Adapter
IntentDetect --> ToolParser
EntityExtract --> ToolParser
ToolParser --> Tools
GetPrices --> SERPER
SERPER --> OpenAI
RegisterUser --> Users
CheckUser --> Users
BookFlight --> Bookings
GetHistory --> Bookings
Tools --> BoardingPass
sequenceDiagram
autonumber
participant U as 👤 User
participant G as 🖥️ Gradio UI
participant O as 🧠 Orchestrator
participant T as 🔧 Tools
participant S as 🌐 SERPER API
participant AI as 🤖 GPT-4-mini
participant DB as 💾 SQLite
U->>G: "I wan book flight Lagos to Abuja"
G->>O: Process message
O->>O: Detect booking intent
O->>O: Extract cities & date
O->>T: check_user_registration(email)
T->>DB: Query users table
DB-->>T: User not found
T-->>O: Not registered
O-->>G: Show registration form
G-->>U: Display inline form
U->>G: Submit registration
G->>T: register_new_user(name, email, phone)
T->>DB: INSERT into users
DB-->>T: User ID
T-->>G: Registration success
G-->>U: Show airline selection
U->>G: Select "Air Peace"
G->>T: get_airline_flights(airpeace, Lagos, Abuja, date)
T-->>G: Return available flights
G-->>U: Show flight options
U->>G: Select 09:30 flight
G->>T: book_flight(user_id, flight_details)
T->>DB: INSERT into bookings
DB-->>T: Booking ID
T-->>G: Booking confirmed + ref
G->>G: Generate boarding pass
G-->>U: Display boarding pass 🎫
sequenceDiagram
autonumber
participant U as 👤 User
participant G as 🖥️ Gradio UI
participant T as 🔧 Tools
participant S as 🌐 SERPER API
participant AI as 🤖 GPT-4-mini
U->>G: "How much be flight to Abuja?"
G->>T: get_flight_prices(Lagos, Abuja, date)
T->>S: Search "flight prices Lagos to Abuja Nigeria"
S-->>T: Return search results (10 results)
T->>AI: Extract structured prices from results
AI-->>T: Return JSON with airlines, prices, sources
T-->>G: Live price data
G-->>U: Display prices with sources ✅
Note over T,AI: No mock data - if no prices found,<br/>user is informed truthfully
SkyAgent/
├── app.py # Main Gradio application
├── orchestrator.py # LLM orchestrator with tool calling
├── tools.py # Tool definitions and implementations
├── database.py # SQLite database helpers
├── adapter/ # Fine-tuned QLoRA adapter
│ └── final/ # Final adapter weights
├── requirements.txt # Python dependencies
└── skyagent.db # SQLite database (auto-created)
Both API keys are REQUIRED - SkyAgent uses live data only, no estimates or mock data.
| Variable | Description | Required |
|---|---|---|
OPENAI_API_KEY |
OpenAI API key for GPT-4-mini price extraction | Required |
SERPER_API_KEY |
SERPER API key for web search | Required |
Get your API keys:
- OpenAI: https://platform.openai.com/api-keys
- SERPER: https://serper.dev/
Note: The app will not start without valid API keys. All flight prices are sourced from live web searches.
# Linux/macOS
export OPENAI_API_KEY="your_openai_api_key"
export SERPER_API_KEY="your_serper_api_key"
# Windows (PowerShell)
$env:OPENAI_API_KEY="your_openai_api_key"
$env:SERPER_API_KEY="your_serper_api_key"Or create a .env file:
OPENAI_API_KEY=your_openai_api_key
SERPER_API_KEY=your_serper_api_key-
Clone the repository
cd SkyAgent -
Create a virtual environment
python -m venv venv source venv/bin/activate # Linux/macOS # or .\venv\Scripts\activate # Windows
-
Install dependencies
pip install -r requirements.txt
-
Set environment variables (required)
export OPENAI_API_KEY="your_key" export SERPER_API_KEY="your_key"
-
Run the application
python app.py
- Start a conversation with a greeting or directly state your travel needs
- Example messages:
- "Hello, I wan book flight from Lagos to Abuja"
- "Abeg check flight to Port Harcourt for next week"
- "How much be flight from Enugu to Lagos?"
- Follow the inline prompts to:
- Register (if not registered)
- Select an airline
- Choose a flight
- Receive your boarding pass
User registrations and bookings are stored in skyagent.db (SQLite).
users table
- id, email, full_name, phone, created_at
bookings table
- id, booking_ref, user_id, airline, flight_no, origin, destination
- departure_date, departure_time, arrival_time, price, gate, seat, status, created_at
Searches the web for real-time flight prices from Nigerian airlines. Returns search results from airline websites, booking platforms, and travel aggregators.
Extracts structured price data from SERPER search results. Ensures accurate parsing of:
- Airline names
- Prices in Nigerian Naira (₦)
- Source URLs for verification
- Any restrictions or notes
No mock data: If APIs fail or no prices are found, the user is informed truthfully and directed to airline websites.
- Add tool definition to
TOOL_DEFINITIONSintools.py - Implement the tool function in
tools.py - Register in
execute_tool()function
See the QLoRA/ directory for:
- Dataset generation (
generate_dataset.py) - Fine-tuning notebook (
fine-tuning.ipynb) - Evaluation notebook (
evaluation.ipynb)
MIT License