A sophisticated AI-powered travel planning system built with multiple specialized agents that collaborate to create comprehensive, personalized travel experiences.
This system implements a multi-agent architecture following AI Rule 20 compliance, featuring:
- Coordinating Agent: Orchestrates all specialized agents using structured messaging
- Culture & Destinations Expert: Provides cultural insights, local customs, and respectful travel guidelines
- Gastronomy Specialist: Recommends local cuisine, restaurants, and dining experiences with dietary accommodation
- Travel Logistics Planner: Handles transportation, accommodation, and booking management (Coming Soon)
- Itinerary Assembler: Creates optimized daily plans and schedules (Coming Soon)
- Travel Story Writer: Transforms itineraries into engaging travel narratives (Coming Soon)
- Planner-Executor-Critic Pattern: Structured decision-making process
- Bounded Execution: Timeout controls and resource limits per agent
- Observable Communication: All inter-agent messages are structured and logged
- Concurrent Processing: Agents execute in parallel where possible
- Error Resilience: Graceful handling of individual agent failures
- Framework: FastAPI for async HTTP APIs
- AI Orchestration: LangGraph for state machine coordination
- AI Providers: OpenAI, Anthropic, Google (configurable)
- RAG System: ChromaDB + OpenAI embeddings for knowledge retrieval
- Memory: SQLite for persistent chat history
- Validation: Pydantic for strict schema enforcement
- Python 3.12+
- Mamba/Conda environment manager
# Setup environment
mamba env create -f environment.yml
conda activate py-foundy
# Install development dependencies (optional)
pip install -e ".[dev]"
# Setup pre-commit hooks
pre-commit install
# Configure environment variables
# Create .env file with your API keys:
# OPENAI_API_KEY=your-key-here
# ANTHROPIC_API_KEY=your-key-here
# GOOGLE_API_KEY=your-key-here# Start the FastAPI server
uvicorn src.app:app --reload --port 8000
# Available endpoints:
# - API: http://localhost:8000
# - Interactive docs: http://localhost:8000/docs
# - Health check: http://localhost:8000/health# Plan a trip using coordinated agents
curl -X POST http://localhost:8000/travel/plan \\
-H 'Content-Type: application/json' \\
-d '{
"session_id": "user123",
"message": "Plan a 5-day cultural trip to Tokyo with vegetarian food options",
"provider": "openai"
}'# Basic health check
curl http://localhost:8000/health
# Detailed health including all agents
curl http://localhost:8000/health/detailed
# System capabilities
curl http://localhost:8000/capabilities# Original chat endpoint (backwards compatibility)
curl -X POST http://localhost:8000/chat \\
-H 'Content-Type: application/json' \\
-d '{
"session_id": "demo",
"message": "calc(2+2*10)",
"provider": "openai"
}'# Run all quality checks
make check
# Individual operations
make format # Black code formatting
make lint # Ruff linting with auto-fix
make type # MyPy type checking
make test # Pytest execution with coverage
make sec # Security scanning (Bandit + Safety)
# RAG knowledge ingestion
mkdir -p data && echo "Travel guides..." > data/travel_guide.md
python src/rag/ingest.py --path data- 🏺 Historical Context: Deep cultural insights and background
- 🎭 Local Customs: Social etiquette and respectful practices
- 🎪 Events & Festivals: Seasonal celebrations and cultural events
- 🗣️ Language Tips: Essential phrases and communication guidance
- ⛪ Sacred Sites: Cultural sensitivity for religious locations
- 🍝 Local Cuisine: Signature dishes and regional specialties
- 🏪 Restaurant Curation: From street food to fine dining across budgets
- 🥬 Dietary Accommodation: Vegetarian, vegan, gluten-free, halal options
- 👨🍳 Food Experiences: Cooking classes, food tours, market visits
- 🍷 Beverage Pairings: Local wines, beers, and traditional drinks
- Logistics Planner: Transportation, accommodation, bookings, documents
- Itinerary Assembler: Optimized daily schedules and activity coordination
- Story Writer: Engaging travel narratives and personalized storytelling
# Run full test suite
pytest
# Run with coverage reporting
pytest --cov=src --cov-report=html
# Test specific components
pytest tests/test_multi_agent_travel.py -v
pytest tests/test_calculator.py -v{
"session_id": "user123",
"message": "Plan a budget cultural trip to Rome for 2 vegetarians, 4 days",
"provider": "openai"
}{
"session_id": "user123",
"status": "completed",
"completed_agents": ["culture", "gastronomy"],
"execution_time": 12.5,
"final_recommendations": "# Rome Cultural Experience...\n\n## Cultural Highlights...\n\n## Culinary Journey...",
"individual_agent_responses": {
"culture": {
"culture_insight": {
"cultural_highlights": ["Vatican Museums", "Colosseum"],
"local_customs": ["Dress modestly in churches"]
}
},
"gastronomy": {
"gastronomy_recommendation": {
"signature_dishes": ["Cacio e Pepe", "Maritozzi"],
"restaurant_recommendations": [...]
}
}
}
}This system implements:
- AI Rules: Multi-agent orchestration (Rule 20), safety guardrails, structured outputs
- Python Standards: PEP 8, type annotations, proper packaging, comprehensive testing
- Security: No eval() usage, input validation, secrets management
- Quality: Pre-commit hooks, linting, type checking, 80%+ test coverage
- Agent communication schemas and messaging
- Travel coordinator with structured orchestration
- Culture & Destinations expert agent
- Gastronomy specialist agent
- Multi-agent API endpoints and integration
- Travel Logistics Planner agent
- Itinerary Assembler agent
- Travel Story Writer agent
- Enhanced natural language parsing
- OpenTelemetry observability
- Safety validation and content filtering
- Comprehensive evaluation framework
- Real-time streaming responses
Built with ❤️ using FastAPI, LangGraph, and modern AI orchestration patterns