Abstract:

Planning a holiday has always been a time consuming activity. HolidayPlanner was developed to simplify this process by using an agent based architecture powered by LangGraph, Groq, and FastAPI. The goal of this system is to generate complete, tailored itineraries based on user preferences while remaining robust, explainable, and resilient in real production environments.

Problem Statement:

Travel planning is tedious users juggle weather checks, cost estimates, activities, and hotel searches. Existing tools are either generic or static.

Goal:

Build a fully automated, intelligent planner that adapts to user goals, budgets, and recommended places to visit in real-time through a network of autonomous agents.

Prerequisites:

Before running HolidayPlanner locally or in Docker, ensure the following:
Python 3.12+
Valid API keys for GROQ
(stored securely in .env and never hardcoded)
Docker Desktop (if using the container build)
Git (optional for cloning the repo)
Basic familiarity with command-line execution

Environment variables required:

GROQ_API_KEY=""
DEFAULT_CITY="Dubai"
DEFAULT_BUDGET="1500"
DEFAULT_DURATION="3"
DEFAULT_PREFERENCES="food, adventure"

System Architecture:

HolidayPlanner is built as a multi-agent system using LangGraph for orchestration. Each agent performs a specialized task and passes data downstream.

Core Components:

Agents:

🧍‍♀️ UserInputAgent: Gathers user preferences such as budget, duration, and interests.

🌍 DestinationAgent: Suggests travel destinations based on user input and external APIs (Yelp/OpenWeather).

☁️ WeatherAgent: Retrieves real-time weather forecasts using the OpenWeather API.

📅 ItineraryAgent: Builds a detailed itinerary from destination and weather data.

💰 BudgetAgent: Calculates expected travel costs and ensures they stay within the user’s budget.

🧾 ResultAggregator: Combines all outputs into a final summary report.

Orchestration Layer:

The agents are connected in a LangGraph workflow (orchestration/langgraph_flow.py).
Data flows sequentially across agents.
Execution is logged and monitored using MetricsTracker.

Related Work:

Workflow Orchestration:

1.Implemented via LangGraph, connecting agents as nodes in a directed flow.
2.Data and decisions propagate forward automatically.
3.Execution metadata logged through a centralized 4.MetricsTracker.
Visualization is stored by

# using NetworkX + Mtplotlib

flow diagram in data/graphs/holiday_planner_flow.png 

Technical Stack:

Backend uses FastAPI, LangGraph
UI uses Streamlit
Deployment by Railway
Monitoring & Logging performed by Python logging, custom metrics_tool.py
APIs are monitored by OpenWeather, Yelp (via MCPClient)

Production-Ready Enhancements:

Dockerized setup with Dockerfile.
Modular directory structure for agents, tools, and orchestration
Metrics & Logs stored in /data/metrics and /logs
Custom error handling in each agent
Secure API key management via .env
FastAPI backend with /plan endpoint for programmatic access
Streamlit UI for user-friendly interaction
Railway deployment-ready configuration

Guardrails & Safety Layer:

HolidayPlanner is built with several safety checks to keep the system stable, secure, and respectful of user data.

Input Checks:

Every user entry (budget, dates, locations) is cleaned and validated before the system uses it.

Safe API Keys:

All sensitive keys are stored in environment variables through .env, so nothing is hard-coded.

Timeouts & Retries:

External API calls are protected with timeouts and automatic retries to avoid failures.

Error Protection:

Each agent runs inside a try/except wrapper, making sure errors are logged instead of crashing the app.

Safe Responses:

Generated itineraries are reviewed for clarity, factual accuracy, and safe language.

Data Privacy:

The system doesn’t save any personally identifiable information.

Continuous Monitoring:

Logs and custom metrics track how the workflow runs from start to finish.

Evaluation

Test Setup

The system was evaluated using real travel scenarios including Tokyo, Jeddah, and Paris across different budgets and trip durations.

Evaluation Summary

Visual References

• LangGraph Flow Diagram: LangGraph Flow Diagram.png
  
• Logs (Streamlit → Backend):

``
logs-asmarahman82-holidayplanner---production-ready-system-main-ui-app_streamlit.py-2025-11-13T15_28_09.225Z.txt

• Output Report:

HolidayPlanner.pdf

Testing & Validation:

All core components of the HolidayPlanner – Production Ready System were tested using pytest under Python 3.12.7. The goal was to ensure robustness, correctness, fairness, and consistent orchestration across agents, APIs, and tools.

1. End-to-End Tests:

Command:

pytest tests/test_end_to_end.py

Result: test_api_plan_endpoint — PASSED in 2.81s
Confirms that the full itinerary pipeline executes successfully from user input → API → itinerary generation → output storage.

2. API Layer Tests:

Command:

pytest tests/test_api.py

Results: test_health_check — PASSED
test_plan_route — PASSED
Ensures that the FastAPI backend endpoints respond correctly and return valid structured JSON.
Execution Time: 3.64s

3. Tool Utility Tests:

Command:

pytest tests/test_tools.py

Results: test_mcp_client_call — PASSED
test_metrics_tracker — PASSED
Validates that internal utilities (MetricsTracker, MCP client, etc.) are logging, saving, and returning values as expected.
Execution Time: 0.12s

4. Integration Tests:

Command:

pytest tests/test_integration.py

Result: test_integration_agent_metrics — PASSED in 3.09s
Confirms seamless interaction between agents, ensuring that metrics tracking and LangGraph orchestration work end-to-end.

5. Fairness and Diversity Tests:

Command:

pytest tests/test_fairness.py

Results: test_budget_fairness[1000-budget] — PASSED
test_budget_fairness[5000-mixed] — PASSED
test_budget_fairness[10000-luxury] — PASSED
test_destination_diversity — PASSED
Confirms the AI agents produce balanced, unbiased itineraries across varying budgets and locations.
Execution Time: 15.38s

6. Agent Workflow Tests:

Command:

pytest tests/test_agents.py -v

Results: test_run_holiday_planner_valid — PASSED
test_run_holiday_planner_invalid_budget — PASSED
test_run_holiday_planner_zero_budget — PASSED
Confirms that agent logic gracefully handles both valid and invalid input scenarios without breaking orchestration.
Execution Time: 3.01s

Outcome:

All 13 tests passed successfully with zero critical issues.
The project demonstrates:
Full API and orchestration stability
Reliable metrics logging and fairness evaluation
Agent-level fault tolerance
End-to-end reproducibility

#Deployment & Usage:

Local Setup:

1.Clone the repository.
2.Create a .env file with your API keys and defaults.
3.Install dependencies:

pip install -r requirements.txt

4.Run the API (running separately):

uvicorn api.main:app --host 0.0.0.0 --port 8000

5.Run the UI:

streamlit run ui/app_streamlit.py

Docker Deployment:

1.Build: docker build -t holidayplanner.

2.Run UI:

docker run -p 8501:8501 -e MODE=streamlit holidayplanner

Cloud deployment:

For cloud deployment follow these simple steps
1.Push the repo to GitHub

2.Go to Railway.app
Click “New Project” → “Deploy from GitHub”
Add environment variables from .env
Railway auto-builds your Docker image
Access UI via Railway-generated URL
push the repo to GitHub and connect it to Railway.app.

User Interface:

Streamlit UI features:
Input fields for destination, budget, and duration
Displays itinerary, weather, and cost summary
Integrated metrics summary and logs viewer

Results Summary:

Component Status:
✅ Agents pipeline execution Complete
✅ Graph visualization Generated
✅ Logs & metrics Stored
✅ Docker containerization Successful
✅ Railway deployment Ready
🚀 Overall system stability 100 % verified

Conclusion:

The HolidayPlanner project is a production-ready AI system that demonstrates:

Modular Agent-Based Design:

Each agent handles a specific task, allowing flexible and maintainable workflows.

Real-Time Data Integration:

Live weather, destination, and cost data are incorporated for accurate planning.

Robust Guardrails:

Input validation, error handling, retries, and data privacy ensure safe and reliable operation.

Seamless Observability:

Logs and metrics provide full transparency into the system’s execution.
Fully Containerized

Deployment:

The system can be deployed easily in cloud environments using Docker.
This project showcases how LangGraph, FastAPI, and Streamlit can work together to build scalable, transparent, and safe AI automation systems for real-world travel planning.