WanderGuide

A personal AI travel guide. Type a destination and it researches YouTube videos, travel blogs and social posts, then presents the results as cards: top attractions, hidden gems, food, places to stay, activities and festivals — each with a photo (Wikimedia Commons) and links to the sources it came from.

Built with a CrewAI Flow orchestrator and a Groq-powered LLM. Research is gathered by plain Python search calls (no LLM) and synthesized by a single Groq JSON-mode call, which avoids the fragile server-side function-call validation seen with multi-agent tool use. 100% free-tier stack, no payment required.

Project layout

backend/   FastAPI + CrewAI (Python)
frontend/  React + Vite (JS)

Setup

1. Backend

cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

2. Set your Groq API key

The only key required to run the app is Groq (free at https://console.groq.com):

Copy-Item .env.example .env

Then open backend/.env and set:

GROQ_API_KEY=your_groq_api_key_here

Optional keys (skip them and the app still works with fallbacks):

Variable	What it enables	If empty
TAVILY_API_KEY	Better web search (free, 1,000/mo at https://tavily.com)	Falls back to DuckDuckGo
YOUTUBE_API_KEY	YouTube video search + transcripts	YouTube research skipped gracefully
GROQ_MODEL	Override model	Defaults to groq/openai/gpt-oss-20b

3. Frontend

cd frontend
npm install

Run

Two terminals, from the project root.

Terminal 1 — backend (http://127.0.0.1:8000):

cd backend
.\.venv\Scripts\Activate.ps1
python run.py

Terminal 2 — frontend (http://localhost:5173):

cd frontend
npm run dev

Open http://localhost:5173, type a destination, and hit Build guide. A run takes 1–2 minutes; progress is shown live.

API

Method	Path	Description
GET	/health	Service + key status
POST	/api/guide	{"query": "Bali"} → starts research, returns {"guide_id": "..."}
GET	/api/guide/{id}	Poll status/steps/result
GET	/api/images?q=...	Look up a Wikimedia image for a name

How it works

GuideFlow (CrewAI Flow) is the orchestrator:

1. query_parser — one Groq JSON-mode call extracts destination + focus
2. research — plain Python, no LLM: DuckDuckGo/Tavily web searches, Reddit search, and (if a key is set) YouTube transcripts; each hit keeps its real source URL
3. aggregate — a single Groq JSON-mode call builds the categorized GuideResponse from the raw research text (never invents places or URLs)
4. images — Wikimedia Commons resolution per place (no LLM)

Notes

• All services used are free tier: Groq (free plan), Tavily (1,000/mo) or DuckDuckGo (keyless), YouTube Data API (daily quota), Wikimedia Commons (free).
• Results are stored in-memory per run (no database).
• Set GROQ_MODEL if you want a different model. The model must support JSON mode (response_format json_object). Verified models: groq/openai/gpt-oss-20b (8k tokens/min, 200k tokens/day) and groq/llama-3.3-70b-versatile (12k tokens/min, 100k tokens/day — higher quality, faster daily budget). The app retries throttled calls with backoff, so it also works when a minute budget is briefly exceeded.