An AI-powered concierge service for restaurant discovery, recommendations, and bookings built for the D.C. AI Hackathon.

• Natural Language Chat Interface - Conversational AI powered by GPT-4/Claude
• Restaurant Discovery - Search and filter restaurants using Yelp & Google Places APIs
• AI Recommendations - Personalized suggestions based on preferences and context
• Restaurant Bookings - Create, modify, and cancel reservations
• User Preferences - Save dietary restrictions, favorite cuisines, and more
• SMS Notifications - Booking confirmations via Twilio

• FastAPI backend with async/await support
• OpenAI GPT-4 & Anthropic Claude integration
• Yelp Fusion API & Google Places API
• JWT authentication
• Mock booking system (production-ready architecture for real APIs)
• Comprehensive API documentation (Swagger/OpenAPI)

• Python 3.9+
• PostgreSQL (optional - using in-memory storage for demo)
• Redis (optional - for production caching)

1. Clone the repository

cd cursathon

2. Create virtual environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

4. Set up environment variables

cp env.example .env
# Edit .env with your API keys

5. Run the application

python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

The API will be available at http://localhost:8000

Once the server is running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• Health Check: http://localhost:8000/health

• OpenAI API Key or Anthropic API Key - For AI conversation
• Yelp API Key - For restaurant search (free tier available)

• Google Places API Key - Fallback restaurant data
• Twilio Credentials - SMS notifications
• Pinecone API Key - Vector search for semantic restaurant discovery

1. Visit https://platform.openai.com/
2. Sign up and navigate to API keys
3. Create new key and add to .env

1. Visit https://www.yelp.com/developers
2. Create an app
3. Copy API key to .env

1. Visit https://www.twilio.com/
2. Sign up for free trial
3. Get Account SID, Auth Token, and Phone Number

• POST /api/v1/auth/register - Register new user
• POST /api/v1/auth/login - Login and get JWT token

• POST /api/v1/chat - Send message to AI concierge
• GET /api/v1/chat/history/{conversation_id} - Get conversation history
• POST /api/v1/chat/recommendations - Get AI recommendations

• GET /api/v1/restaurants/search - Search restaurants
• GET /api/v1/restaurants/{id} - Get restaurant details

• POST /api/v1/bookings - Create booking
• GET /api/v1/bookings - List user bookings
• GET /api/v1/bookings/{id} - Get booking details
• PUT /api/v1/bookings/{id} - Update booking
• DELETE /api/v1/bookings/{id} - Cancel booking

• GET /api/v1/users/me - Get current user
• PUT /api/v1/users/me - Update profile
• GET /api/v1/users/preferences - Get preferences
• PUT /api/v1/users/preferences - Update preferences

User: "I need a romantic Italian restaurant for tomorrow at 7 PM"

AI: "I'd love to help you find the perfect romantic Italian restaurant! Let me search for some great options..."

System:

1. Extracts intent: booking
2. Extracts entities: cuisine=Italian, occasion=romantic, time=tomorrow 7 PM
3. Searches Yelp/Google for matching restaurants
4. AI analyzes and recommends top 3 options

AI: "I found 3 wonderful options:

1. Bella Italia - Intimate setting, candlelit tables, highly rated ⭐ 4.5
2. Trattoria Roma - Authentic, great ambiance ⭐ 4.7
3. Il Forno - Cozy, perfect for couples ⭐ 4.6

Which would you prefer?"

User: "Book Bella Italia"

System:

1. Creates booking
2. Generates confirmation code
3. Sends SMS notification (if configured)

AI: "Perfect! Your reservation at Bella Italia is confirmed for tomorrow at 7 PM. Confirmation code: ABC12345 I've sent the details to your phone. Have a wonderful evening! 🎉"

cursathon/
├── app/
│   ├── main.py                 # FastAPI application
│   ├── core/
│   │   ├── config.py          # Configuration
│   │   └── security.py        # Auth & JWT
│   ├── models/
│   │   └── database.py        # SQLAlchemy models
│   ├── schemas/
│   │   ├── user.py            # Pydantic schemas
│   │   ├── restaurant.py
│   │   ├── booking.py
│   │   └── chat.py
│   ├── services/
│   │   ├── llm_service.py     # OpenAI/Claude integration
│   │   ├── restaurant_service.py  # Yelp/Google Places
│   │   ├── booking_service.py     # Booking logic
│   │   └── notification_service.py # Twilio SMS
│   └── api/
│       └── v1/
│           ├── router.py
│           └── endpoints/
│               ├── auth.py
│               ├── chat.py
│               ├── restaurants.py
│               ├── bookings.py
│               └── users.py
├── requirements.txt
├── env.example
├── README.md
└── TECHNICAL_ROADMAP.md

For demo purposes without API keys, the system can run in mock mode:

• Set MOCK_RESTAURANT_API=True to use mock restaurant data
• Set MOCK_BOOKING_API=True to simulate bookings (default)
• LLM will use fallback responses if no API key is provided

1. Set all API keys in .env
2. Configure PostgreSQL database
3. Set up Redis for caching
4. Deploy to Vercel, Railway, or similar platform

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

# Install Railway CLI
npm i -g railway

# Login and deploy
railway login
railway init
railway up

docker build -t ai-concierge .
docker run -p 8000:8000 ai-concierge

• ✅ OpenAI GPT-4 - Primary LLM for conversations
• ✅ Anthropic Claude - Alternative LLM option

• ✅ Yelp Fusion API - Restaurant data and reviews
• ✅ Google Places API - Location and restaurant info

• ✅ Twilio - SMS notifications and confirmations

• ✅ FastAPI - Modern Python web framework
• ✅ PostgreSQL - Relational database
• ✅ Redis - Caching and session management

• Pinecone - Vector database for semantic search
• Supabase - Alternative to PostgreSQL + Auth
• Stripe - Payment processing (future feature)
• Sentry - Error monitoring

Use the Swagger UI at /docs to test endpoints interactively.

Search Restaurants:

curl -X GET "http://localhost:8000/api/v1/restaurants/search?cuisine=Italian&location=Washington%2C%20DC"

Chat with AI:

curl -X POST "http://localhost:8000/api/v1/chat" \
  -H "Content-Type: application/json" \
  -d '{"message": "Find me a romantic Italian restaurant"}'

Create Booking:

curl -X POST "http://localhost:8000/api/v1/bookings" \
  -H "Content-Type: application/json" \
  -d '{
    "restaurant_id": "mock-1",
    "booking_date": "2024-02-01T19:00:00",
    "party_size": 2,
    "occasion": "anniversary"
  }'

This backend is designed to work with a V0-generated frontend. Key integration points:

Real-time chat updates via WebSocket connection

All endpoints return JSON and follow RESTful conventions

Use JWT tokens in Authorization header:

Authorization: Bearer <token>

This is a hackathon project. Feel free to:

• Report issues
• Suggest features
• Submit pull requests

MIT License - feel free to use this for your projects!

Project: AI Concierge Service Hackathon: D.C. AI Hackathon 2026 Category: AI Applications / Consumer Services

• Practical Use Case - Real-world problem with AI solution
• Multiple API Integrations - Demonstrates technical breadth
• Production-Ready Architecture - Can scale to real users
• AI-First Design - Natural language as primary interface
• Demo-Friendly - Works with or without real API keys

For questions or issues:

• Check the /docs endpoint for API documentation
• Review TECHNICAL_ROADMAP.md for architecture details
• Test in mock mode if APIs are not working

Built with ❤️ for the D.C. AI Hackathon