https://github.com/ahmadluay9/hotel-mcp-bigquery-postgresql
AI-powered Hotel Management Assistant built with Streamlit and Google's ADK. Connects to PostgreSQL for operations and BigQuery for analytics.
https://github.com/ahmadluay9/hotel-mcp-bigquery-postgresql
adk adk-python agentic-ai bigquery mcp postgresql streamlit
Last synced: 2 months ago
JSON representation
AI-powered Hotel Management Assistant built with Streamlit and Google's ADK. Connects to PostgreSQL for operations and BigQuery for analytics.
- Host: GitHub
- URL: https://github.com/ahmadluay9/hotel-mcp-bigquery-postgresql
- Owner: ahmadluay9
- Created: 2025-09-18T07:27:21.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-10-02T22:46:53.000Z (9 months ago)
- Last Synced: 2025-10-03T00:19:08.477Z (9 months ago)
- Topics: adk, adk-python, agentic-ai, bigquery, mcp, postgresql, streamlit
- Language: Python
- Homepage:
- Size: 44.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Hotel Management AI Assistant
This project is a sophisticated AI-powered chatbot designed to act as a Hotel Management Assistant. It provides a conversational interface for both operational tasks (like checking room availability) and analytical queries (like reviewing monthly revenue).
The application is built using **Streamlit** for the user interface, Google's **Agent Development Kit (ADK)** for the core agent logic, and connects to a dual-database backend: **PostgreSQL** for real-time transactional data and **Google BigQuery** for business intelligence and analytics.
## Features
- **Conversational Interface**: An intuitive chat application built with Streamlit.
- **Hierarchical Agent System**: A multi-agent architecture where a root agent delegates tasks to specialized agents for operations, analytics, and data visualization.
- **Operational Capabilities**:
- Find available rooms based on dates and room types.
- Create new guest bookings.
- **Analytical Capabilities**:
- Calculate and report total monthly revenue for a given year.
- Analyze the top-performing booking channels over a specific period.
- **Dynamic Chart Generation**: Automatically generates and displays charts (e.g., bar charts for revenue) using a dedicated visualization agent.
- **Persistent Sessions & Artifacts**:
- Uses a **PostgreSQL** database to store and manage user chat sessions, allowing for stateful conversations.
- Leverages **Google Cloud Storage (GCS)** via the `GcsArtifactService` to handle file artifacts (like generated charts) in a scalable, production-ready manner.
- **Containerized & Deployable**: Includes a Dockerfile and `cloudbuild.yaml` for easy containerization and deployment to Google Cloud.
## Project Structure
This repository is organized to separate concerns, making it modular and scalable. Each file and directory has a distinct role:
```
hotel-mcp-bigquery-postgresql/
├── hotel_agent_app/
│ ├── sub_agents
│ │ ├── data_visualization
│ │ │ ├──__init__.py
│ │ │ └──agent.py
│ │ ├── hotel_analytics
│ │ │ ├──__init__.py
│ │ │ └──agent.py
│ │ └── hotel_operation
│ │ ├──__init__.py
│ │ └──agent.py
│ ├──__init__.py
│ ├── agent.py
│ └── tools.py
├── mcp-toolbox/
│ └── tools.yaml
├── README.md
├── .gitignore
├── cloudbuild.yaml
├── Dockerfile
├── app.py
├── notebook.ipynb
└── requirements.txt
```
- `hotel_agent_app/`: The main Python package for the AI agent.
- `sub_agents/`: Contains the specialized "worker" agents for specific tasks.
- `agent.py`: Defines the main "root" agent which acts as a router, delegating tasks to the appropriate sub-agent.
- `tools.py`: A utility script that initializes and configures the MCP Toolbox client.
- `mcp-toolbox/tools.yaml`: Defines the agent's database skills. It uses the Model Context Protocol (MCP) to map natural language descriptions to specific SQL queries.
- `app.py`: The user-facing frontend built with Streamlit. It creates the chat UI, manages the conversation flow, and handles the display of text and image artifacts returned by the agent.
- `Dockerfile` & `cloudbuild.yaml`: Files for DevOps. Dockerfile packages the application into a container, and cloudbuild.yaml automates the build/deployment process on Google Cloud.
- `requirements.txt`: Lists all Python libraries the project depends on.
- `notebook.ipynb`: A Jupyter Notebook for interactive development and testing.
## Architecture
### System Architecture
### AI Agentic Workflow
### MCP Server - Database Toolbox
The application uses a modern, decoupled architecture:
1. **Data Sources**: PostgreSQL (`hotel_db`) is the OLTP database for live operational data, while BigQuery (`hotel_dataset`) is the OLAP data warehouse for analytics.
2. **Tooling Ecosystem**: The MCP Server (on Cloud Run) acts as a secure API gateway to the databases.
3. **Orchestration Layer**: The Hotel Agent (on Cloud Run) manages the conversation, deciding which tool or sub-agent to use.
4. Session & Artifact Management:
- A PostgreSQL database (`hotel_session_db`) stores conversation history.
- Google Cloud Storage is used by the `GcsArtifactService` to manage file artifacts (like charts) generated during code execution.
5. DevOps & AI: The system is automated via a CI/CD pipeline (Cloud Build), with containers in Artifact Registry. The core intelligence is a Gemini model on Vertex AI.
## Reference
[1. Deploy MCP to Cloud Run](https://googleapis.github.io/genai-toolbox/how-to/deploy_toolbox/)
[2. Quickstart (MCP with BigQuery)](https://googleapis.github.io/genai-toolbox/samples/bigquery/mcp_quickstart/)
[3. Build a Travel Agent using MCP Toolbox for Databases and Agent Development Kit (ADK)](https://codelabs.developers.google.com/travel-agent-mcp-toolbox-adk?hl=en)