---
title: Qiddiya Smart Guide
emoji: 🎢
colorFrom: blue
colorTo: purple
sdk: docker
app_file: app.py
pinned: false
---

## Qiddiya Smart Guide

Multi-agent, offline-first LangGraph application that plans an optimal day inside Qiddiya City by minimizing queue time, reducing walking distance, and maximizing enjoyment and ride coverage. Built for the Agentic AI Bootcamp multi-agent homework and deployable on Hugging Face Spaces.

### Features

- **Multi-agent LangGraph workflow**: Orchestrator, Wait-Time Predictor, Route & Schedule Optimizer, Experience Writer, and Critic/Verifier.
- **Offline dataset**: JSON/CSV describing park nodes, walking paths, attractions, and historical wait times.
- **Deterministic core planning**: Pure-Python heuristic agents for routing, waits, and constraints.
- **Optional Groq LLM**: Experience Writer can call Groq to generate richer natural-language guidance if `GROQ_API_KEY` is set.
- **Guardrails**: Pydantic validation, tool argument checks, error handling, and step-by-step logging.
- **Persistence**: SQLite database for plans and evaluation results.
- **UI + API**: FastAPI backend with a custom HTML/CSS/JS UI at the root path (no Gradio). Itinerary shows only your selected attractions unless the system adds **suggestions** (marked in the UI) when enjoyment is low. Route order is **geographic** (nearest-neighbor from the hub). Collapsible **System response** shows logs, reflection round, and critique.

### Repository Structure

- `app.py` – FastAPI app, serves UI from `templates/` and static assets from `static/`.
- `templates/index.html` – Single-page UI markup.
- `static/css/style.css` – Styles for the UI.
- `static/js/app.js` – Front-end logic (plan form, timeline, map).
- `requirements.txt` – Python dependencies.
- `.env.example` – Example configuration (no secrets).
- `src/` – Application code:
  - `models.py` – Pydantic models (`UserRequest`, `Attraction`, `ItineraryStop` with `is_suggested`, `ItineraryPlan`, `EvaluationResult`, `PlanResponse`, `SystemResponse`).
  - `data_loader.py` – Load offline JSON/CSV datasets.
  - `routing.py` – Dijkstra-based walking distance, nearest-neighbor ordering, and greedy scheduler.
  - `agents.py` – All agent node implementations.
  - `graph.py` – LangGraph `StateGraph` wiring the multi-agent workflow.
  - `db.py` – SQLite initialization and persistence helpers.
  - `evaluation.py` – Evaluation prompts and heuristic metrics.
  - `llm.py` – Optional Groq client for narrative guide generation.
- `data/` – Offline datasets:
  - `park_nodes.json`, `park_edges.json`, `attractions.json`, `wait_time_history.csv`.
- `architecture/` – AISA engineering pack: workflow diagram, reflection criteria, and full assignment answers (`ASSIGNMENT_ANSWERS.md`).

### Installation

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements.txt
```

### Running Locally

```bash
python app.py
```

Then open **`http://localhost:7860/`** (or `http://127.0.0.1:7860/`) in your browser to access the Qiddiya Smart Guide UI. The FastAPI OpenAPI docs are at `http://localhost:7860/docs`.

### Groq configuration (optional)

1. Copy `.env.example` to `.env`.
2. Put your Groq key in `GROQ_API_KEY`.
3. Restart the app. The Experience Writer agent will now call Groq to generate a richer step‑by‑step guide; if the key is missing, it falls back to deterministic text.