README.md

metadata

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

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

Running Locally

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.