An intelligent multi-agent itinerary planner — a LangGraph-orchestrated pipeline of specialist agents that plans, enriches, validates and revises full day-by-day trips from a single set of preferences.
🔗 Built with FastAPI · LangGraph · React · TypeScript · Gemini/Groq
TravelGenie turns a destination, a date range, a budget level and a handful of interests into a complete, day-by-day itinerary — enriched with weather-aware packing notes and estimated travel times between activities, checked for quality, retried if it falls short, and revisable afterward with a plain-English follow-up message.
Unlike a single giant prompt, TravelGenie is built as a pipeline of narrow, single-purpose agents (Feasibility → Research → Planner → Logistics → Validation), coordinated by a rule-based Supervisor that owns all sequencing and retry decisions.
📖 Full system design, the agent pipeline in detail, and every deliberate deviation from the original blueprint (with reasoning) live in docs/architecture.md.
| Feature | Description |
|---|---|
| Destination Feasibility Gate | Verifies the destination is real before Research or Planning spend any effort on it |
| Interest-Driven Research | Runs one search per stated interest to ground the plan in real context |
| Day-by-Day Itinerary Generation | LLM-generated plan structured as nested Itinerary → Day → Activity, not flat text |
| Weather-Aware Logistics | Attaches daily forecast, packing notes and travel advisories (Open-Meteo) |
| Travel-Time Estimation | Geocodes activity locations and computes travel time between activities (Nominatim + OSRM) |
| Two-Tier Validation | Construction-time domain rules plus post-construction quality checks, with automatic retry on failure |
| Best-Effort Fallback | If retries are exhausted, returns the best itinerary produced so far with visible warnings |
| Plain-English Revisions | PATCH a completed itinerary with a free-text request; only the days it concerns are changed |
| PDF & Calendar Export | Export any completed itinerary as a formatted PDF or an .ics file |
| Swappable LLM Provider | Backed by Gemini or Groq behind one interface — a config change, not a code change |
git clone https://github.com/<your-username>/TravelGenie.git
cd TravelGenie/backend
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env # then set your LLM + search API keys
uvicorn app.main:app --reloadThe API is now live at http://localhost:8000 (interactive docs at /docs).
cd frontend
npm install
cp .env.example .env
npm run devOpen http://localhost:5173 in your browser.
docker compose up --build| Service | URL |
|---|---|
| Backend | http://localhost:8000 |
| Frontend | http://localhost:5173 |
📖 Full prerequisites, environment variables and troubleshooting are in docs/setup.md.
curl -X POST http://localhost:8000/itinerary \
-H "Content-Type: application/json" \
-d '{
"destination": "Lisbon, Portugal",
"start_date": "2026-09-01",
"end_date": "2026-09-04",
"budget_level": "moderate",
"interests": ["food", "history"],
"traveler_count": 2
}'Runs the full pipeline and returns an itinerary, any quality warnings, and a session_id for later use.
curl -X PATCH http://localhost:8000/itinerary/<session_id> \
-H "Content-Type: application/json" \
-d '{"message": "Replace the museum visit on day 2 with something more relaxed"}'Only the day(s) the message concerns are changed. Requests to change trip duration or destination are rejected outright.
curl -O -J http://localhost:8000/itinerary/<session_id>/export/pdf
curl -O -J http://localhost:8000/itinerary/<session_id>/export/calendar
⚠️ Sessions are stored in-process and expire after 1 hour, and do not persist across a backend restart.
📖 Full endpoint reference, request/response schemas and error codes are in docs/api.md.
TravelGenie/
├── backend/
│ └── app/
│ ├── api/ # FastAPI routes, request/response schemas
│ ├── orchestration/ # GraphState + the LangGraph pipeline
│ ├── agents/ # Feasibility, Research, Planner, Logistics,
│ │ # Supervisor, Reviser, Validation
│ ├── tools/ # Weather, Maps, Search, PDF export, Calendar export
│ ├── domain/ # TripPreferences, Itinerary (the core data model)
│ ├── config/ # Settings, per-agent LLM config, prompts
│ └── memory/ # Session storage for revisions
├── frontend/
│ └── src/ # React + TypeScript SPA — forms, itinerary view, refine flow
└── docs/
├── architecture.md # Full design writeup + blueprint deviations
├── agents.md # Per-agent contract reference
├── api.md # Full endpoint + data model reference
└── setup.md # Detailed local + Docker setup guide
| Technology | Role |
|---|---|
| FastAPI | HTTP API layer |
| LangGraph | Agent pipeline orchestration |
| Gemini / Groq | LLM completions, behind a single LLMClient interface |
| Pydantic | Domain models and settings validation |
| Open-Meteo | Free, keyless weather forecasts |
| Nominatim + OSRM | Free, keyless geocoding and routing |
| ReportLab | PDF itinerary export |
| React + TypeScript + Vite | Frontend single-page application |
- Multi-Agent Orchestration — LangGraph-coordinated pipeline of single-responsibility agents, no direct agent-to-agent calls
- Supervisor Pattern — a dedicated, rule-based component owning all sequencing and retry logic
- Two-Tier Validation — construction-time domain rules vs. post-construction quality checks
- Provider-Agnostic Integrations — LLM, weather and maps providers each swappable behind one interface
- Graceful Degradation — enhancement failures are logged and skipped; core failures raise explicit, typed errors
- Scoped, Guarded Revisions — free-text edits constrained to what a revision can safely change
If you found this project useful or interesting, consider giving it a ⭐ on GitHub.