⚽ WorldCupGo - AI World Cup Travel Agent

Your autonomous AI assistant for the 2026 FIFA World Cup in USA, Canada & Mexico

Built with React Native + Expo | English README with Chinese translation available.

Chinese version available in README.zh.md

🎯 What is WorldCupGo?

WorldCupGo is an AI-powered travel agent that plans your entire World Cup trip. Just tell it what you want:

You: "帮我规划看决赛的行程，预算2万"
Agent: "好的！我来安排..."
  → 查找决赛门票
  → 推荐附近酒店  
  → 规划交通路线
  → 生成完整行程单
  → 一键添加到日历 📅

✨ Features

🤖 AI Agent (Core)

• Natural Language Planning: Tell the AI what you want in plain English or Chinese
• Autonomous Actions: Automatically searches matches, books hotels, creates itineraries
• Real-time Data: Weather forecasts, venue info, team schedules
• Interactive Cards: Tap to add matches to your trip, book hotels, create checklists

📊 World Cup Data

• 48 Group Stage Matches + Knockout Rounds
• 16 Stadiums across USA, Canada & Mexico
• 32 Teams with full schedules
• Real-time Weather for each venue

🏨 Travel Planning

• Hotel recommendations near each stadium
• Transportation guidance
• Trip timeline view
• Todo checklists

🌐 Bilingual

• Full Chinese & English support
• Switch languages instantly

🚀 Quick Start

# Clone the project
git clone https://github.com/yourusername/WorldCupGo.git
cd WorldCupGo

# Install dependencies
npm install

# Start development
npm run web

🔑 Configure API Keys (Required)

WorldCupGo supports real external APIs and uses environment variables to load keys. Copy .env.example to .env and fill in your keys.

cp .env.example .env

Supported keys:

• API_FOOTBALL_KEY or EXPO_PUBLIC_API_FOOTBALL_KEY
• GOOGLE_PLACES_KEY or EXPO_PUBLIC_GOOGLE_PLACES_KEY
• OPENWEATHER_KEY or EXPO_PUBLIC_OPENWEATHER_KEY
• RAPIDAPI_KEY or EXPO_PUBLIC_RAPIDAPI_KEY
• BOOKING_KEY or EXPO_PUBLIC_BOOKING_KEY

For AI agent configuration, WorldCupGo can also auto-load LLM settings from .env:

• OPENAI_KEY or EXPO_PUBLIC_OPENAI_KEY
• ANTHROPIC_KEY or EXPO_PUBLIC_ANTHROPIC_KEY
• GEMINI_KEY or EXPO_PUBLIC_GEMINI_KEY
• EXPO_PUBLIC_OLLAMA_BASE_URL or OLLAMA_BASE_URL

WorldCupGo also requires an LLM provider for the AI agent. Get one free:

Provider	Sign Up	Models
OpenAI	api.openai.com	GPT-4o, GPT-4o-mini
Anthropic	console.anthropic.com	Claude Sonnet, Claude Opus
Ollama	ollama.com (local, free)	Llama3, Mistral
Gemini	aistudio.google.com	Gemini 2.0 Flash

The app works with any of these. For local development, Ollama is completely free and the app supports configuring a local Ollama base URL.

If you choose Ollama, set EXPO_PUBLIC_OLLAMA_BASE_URL to your local endpoint (for example http://localhost:11434).

📱 Screenshots

Home	Agent Chat	Trip Planner

🏗️ Architecture

WorldCupGo/
├── app/                    # Expo Router screens
│   ├── (tabs)/            # Tab navigation
│   │   ├── index.tsx      # AI Agent (main screen)
│   │   └── my-trip.tsx    # Trip planner
│   └── matches/[id].tsx   # Match details
├── src/
│   ├── agent/             # AI Agent core
│   │   ├── agent.ts       # Agent service
│   │   ├── llmService.ts  # LLM providers
│   │   └── tools.ts       # Available tools
│   ├── api/               # Data APIs
│   ├── components/       # Reusable UI
│   └── context/           # State management
└── docs/                  # Documentation

🛠️ Tech Stack

• Framework: React Native + Expo
• Navigation: Expo Router
• UI: React Native Paper (Material Design 3)
• AI: OpenAI / Anthropic / Ollama / Gemini
• i18n: i18next (Chinese + English)
• State: React Context + AsyncStorage

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

📄 License

MIT License - see LICENSE

⭐ If This Helped You

Star this repo and share with fellow football fans!

---

Built with ❤️ for the 2026 FIFA World Cup 🇺🇸🇨🇦🇲🇽