{"id":37858067,"url":"https://github.com/a20r/dirtgenie","last_synced_at":"2026-01-16T16:29:26.199Z","repository":{"id":297817649,"uuid":"997976709","full_name":"a20r/dirtgenie","owner":"a20r","description":"🚵‍♀️ An \"AI powered\" (🤣) bikepacking trip planner made with vibes","archived":false,"fork":false,"pushed_at":"2025-06-23T15:44:31.000Z","size":740,"stargazers_count":0,"open_issues_count":5,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-23T15:47:29.021Z","etag":null,"topics":["ai","bikepacking","camping","cycling","streamlit","trip-planning"],"latest_commit_sha":null,"homepage":"https://dirtgenie.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/a20r.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-07T15:52:54.000Z","updated_at":"2025-06-23T15:11:01.000Z","dependencies_parsed_at":"2025-06-23T15:44:38.062Z","dependency_job_id":null,"html_url":"https://github.com/a20r/dirtgenie","commit_stats":null,"previous_names":["a20r/dirtgenie"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/a20r/dirtgenie","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a20r%2Fdirtgenie","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a20r%2Fdirtgenie/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a20r%2Fdirtgenie/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a20r%2Fdirtgenie/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/a20r","download_url":"https://codeload.github.com/a20r/dirtgenie/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a20r%2Fdirtgenie/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28479890,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","bikepacking","camping","cycling","streamlit","trip-planning"],"created_at":"2026-01-16T16:29:25.611Z","updated_at":"2026-01-16T16:29:26.187Z","avatar_url":"https://github.com/a20r.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚴‍♀️ DirtGenie\n[![Pull image](https://img.shields.io/badge/ghcr.io/a20r/dirtgenie-pull-blue?logo=docker)](https://ghcr.io/a20r/dirtgenie)\n\nAn intelligent trip planner that creates detailed bikepacking itineraries using OpenAI's GPT models and Google Maps routing data. DirtGenie features both a powerful CLI tool and a modern web application built with React and FastAPI.\n\nCreated purely with vibes.\n\n## ✨ Features\n\n### 🧠 Intelligent Planning\n- **AI-Powered Tour Planning**: Uses OpenAI to intelligently plan waypoints and overnight stops\n- **3-Step Methodology**: Plan → Route → Generate for optimized experiences\n- **Personalized Recommendations**: Tailors trips to your preferences and fitness level\n- **Iterative Feedback**: Revise plans with natural language feedback until perfect\n\n### 🗺️ Advanced Routing\n- **Bicycle-Specific Routing**: Uses Google Maps API for bike-optimized directions\n- **Multi-Waypoint Support**: Plans complex routes with multiple strategic stops\n- **Rich Output Formats**: Detailed markdown plans + GeoJSON for mapping apps\n\n### �️ Dual Interface\n- **🖥️ Web App**: Modern React interface with FastAPI backend, interactive maps and real-time feedback\n- **⌨️ CLI Tool**: Powerful command-line interface for automation and scripting\n- **📱 Mobile-Friendly**: Web interface works great on tablets and phones\n\n### 🎯 Smart Customization\n- **Accommodation Types**: Camping, hotels, or mixed options\n- **Fitness Levels**: Beginner to advanced with appropriate daily distances\n- **Terrain Preferences**: Paved roads, gravel, mixed, or challenging routes\n- **Budget Options**: Budget-conscious to luxury experiences\n- **Special Interests**: Nature, food, photography, history, and more\n\n## 🚀 Quick Start\n\n### Web Application (Recommended)\n\nThe easiest way to get started is with our web application:\n\n```bash\n# Clone the repository\ngit clone https://github.com/a20r/dirtgenie.git\ncd dirtgenie/web\n\n# Start the application (installs dependencies automatically)\n./start.sh\n```\n\nThis will start both the backend and frontend servers, and open your browser to http://localhost:3000.\n\n**API Keys**: You'll be prompted to enter your OpenAI and Google Maps API keys in the web interface.\n\n### CLI Tool\n\n```bash\n# Clone the repository\ngit clone https://github.com/a20r/dirtgenie.git\ncd dirtgenie\n\n# Create virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# Install dependencies\npip install -r requirements.txt\n\n# Install in development mode\npip install -e .\n```\n\nFor CLI usage, you'll need to set up API keys. Create a `.env` file in the project root:\n\n```bash\nOPENAI_API_KEY=your-openai-api-key-here\nGOOGLE_MAPS_API_KEY=your-google-maps-api-key-here\n```\n\nOr set environment variables:\n```bash\nexport OPENAI_API_KEY=\"your-openai-api-key-here\"\nexport GOOGLE_MAPS_API_KEY=\"your-google-maps-api-key-here\"\n```\n\n### CLI Usage\n\n```bash\n# Plan a trip from command line\npython src/dirtgenie/planner.py --start \"San Francisco, CA\" --end \"Los Angeles, CA\" --nights 7\n\n# Or use the convenience script\n./scripts/dirtgenie --start \"Portland, OR\" --end \"Seattle, WA\" --nights 5\n```\n\n## 🐳 Docker Deployment\n\n### Docker Deployment\n\nThe web application can be deployed using Docker:\n\n```bash\n# Build and run locally\ndocker build -t dirtgenie-web .\ndocker run -p 80:80 dirtgenie-web\n\n# The app will be available at http://localhost\n```\n\n### Railway Deployment\n\nDeploy to Railway using the included configuration:\n\n1. Connect your GitHub repository to Railway\n2. The `railway.json` config will automatically deploy the web app\n3. Set environment variables in Railway dashboard (optional - users provide their own API keys)\n\n## 📖 Usage Examples\n\n### Web Interface\n1. **Open the web app**: Navigate to http://localhost:3000 (or your deployed URL)\n2. **Enter your API keys**: Securely provide your OpenAI and Google Maps API keys\n3. **Plan your trip**: Fill in start/end locations, nights, and preferences\n4. **Get your plan**: View detailed itinerary with interactive elements\n5. **Revise your trip**: Use the revision feature to refine your plan\n6. **Export**: Download trip packages and export to Notion\n\n### Command Line Examples\n\n```bash\n# Weekend wine country tour\n./scripts/dirtgenie --start \"Sonoma, CA\" --end \"Napa, CA\" --nights 2\n\n# Cross-state adventure\n./scripts/dirtgenie --start \"Denver, CO\" --end \"Moab, UT\" --nights 10\n\n# Pacific Coast classic\n./scripts/dirtgenie --start \"San Francisco, CA\" --end \"Los Angeles, CA\" --nights 14\n```\n\n## 🏗️ Project Structure\n\n```\ndirtgenie/\n├── web/                     # Modern web application\n│   ├── backend/             # FastAPI backend\n│   │   ├── main.py          # API server\n│   │   └── requirements.txt # Backend dependencies  \n│   ├── frontend/            # React frontend\n│   │   ├── src/             # React source code\n│   │   ├── package.json     # Frontend dependencies\n│   │   └── public/          # Static assets\n│   ├── start.sh             # Development startup script\n│   └── README.md            # Web app documentation\n├── src/dirtgenie/           # Core package\n│   ├── __init__.py          # Package initialization\n│   ├── planner.py           # Core planning logic (CLI)\n│   └── web_app.py           # Legacy Streamlit interface (deprecated)\n├── scripts/                 # CLI convenience scripts\n│   ├── dirtgenie            # CLI entry point\n│   └── dirtgenie-web        # Legacy web entry (deprecated)\n├── tests/                   # Test suite\n├── docs/                    # Documentation\n├── Dockerfile              # Docker configuration\n├── nginx.conf              # Nginx configuration\n├── railway.json            # Railway deployment config\n├── requirements.txt        # Core dependencies\n├── setup.py               # Package setup\n└── README.md              # This file\n```\n\n## 🧠 How It Works\n\nDirtGenie uses a sophisticated 3-step planning methodology that creates better bikepacking experiences:\n\n### 1. 🎯 Plan Tour Itinerary\n- AI analyzes your preferences, fitness level, and trip duration\n- Determines optimal waypoints and overnight locations\n- Plans realistic daily distances and strategic stops\n- Considers terrain, interests, and accommodation preferences\n\n### 2. 🗺️ Get Multi-Waypoint Directions  \n- Uses Google Maps to get bicycle-specific directions\n- Connects all planned waypoints with bike-optimized routes\n- Calculates precise distances and elevation profiles\n- Ensures route quality while hitting desired destinations\n\n### 3. 📝 Generate Detailed Plan\n- Creates comprehensive day-by-day itineraries\n- Searches for current accommodation availability and pricing\n- Adds points of interest, food stops, and practical advice\n- Incorporates real-time weather and local conditions\n\n### 💬 Iterative Feedback (Web App Only)\n- Review your generated plan\n- Provide natural language feedback (\"more camping\", \"shorter days\", etc.)\n- AI revises the plan based on your input\n- Repeat until you're completely satisfied\n\n## 📱 Web App Features\n\nThe modern React/FastAPI web interface provides a complete planning experience:\n\n- **🎨 Modern UI**: Clean, responsive interface built with React and Tailwind CSS\n- **🗺️ Trip Planning**: Complete bikepacking trip planning with AI assistance\n- **� Tire Size Integration**: Smart route recommendations based on bike setup\n- **� Departure Date Planning**: Weather and seasonal planning capabilities\n- **✏️ Trip Revisions**: Easy plan modifications with AI assistance\n- **📱 Mobile Friendly**: Responsive design that works on all devices\n- **� Export Options**: Download trip packages and export to Notion\n- **� API Key Management**: User-provided API keys for secure, cost-controlled usage\n- **� Real-time Status**: Live backend health monitoring and feedback\n\n## 🎯 Smart Features\n\n### Accommodation Intelligence\n- **Mixed Options**: Combines camping, hotels, and unique stays\n- **Budget Awareness**: Finds options matching your budget range\n- **Availability Checking**: Searches for current availability and pricing\n- **Backup Options**: Provides multiple accommodation choices per location\n\n### Route Optimization  \n- **Fitness-Appropriate**: Distances tailored to your cycling level\n- **Terrain-Aware**: Considers your preference for paved vs. gravel vs. challenging routes\n- **Interest-Based**: Incorporates stops for photography, food, history, nature\n- **Weather-Informed**: Accounts for seasonal conditions and forecasts\n\n### Safety \u0026 Practicality\n- **Emergency Planning**: Includes backup plans and emergency contacts\n- **Resupply Points**: Identifies food and water sources along the route\n- **Bike Shops**: Locates repair services and bike shops\n- **Local Tips**: Provides region-specific advice and considerations\n\n## 🛠️ API Requirements\n\n### Google Maps APIs (Required)\nEnable these APIs in [Google Cloud Console](https://console.cloud.google.com/):\n- **Directions API**: For bicycle routing\n- **Geocoding API**: For location lookup\n- **Places API**: For accommodation and POI search (optional)\n\n### OpenAI API (Required)\n- GPT-4 or GPT-3.5-turbo access\n- Sufficient quota for trip planning (typically 2000-4000 tokens per plan)\n\n## 📊 Output Formats\n\n### 1. Detailed Markdown Report\n```markdown\n# Your Bikepacking Adventure: San Francisco to Los Angeles\n\n## Trip Overview\n- Duration: 7 nights, 8 days\n- Total Distance: 542 km\n- Daily Average: 77 km\n\n## Day 1: San Francisco to Santa Cruz (89 km)\n### Route\n- Start: Golden Gate Park, San Francisco\n- Highlights: Pacific Coast Highway, Half Moon Bay\n- End: Santa Cruz Beach Boardwalk\n\n### Accommodation\n- **Primary**: Santa Cruz KOA Kampground ($45/night)\n- **Backup**: Dream Inn Santa Cruz ($180/night)\n...\n```\n\n### 2. GeoJSON Route Data\n```json\n{\n  \"type\": \"FeatureCollection\",\n  \"features\": [\n    {\n      \"type\": \"Feature\",\n      \"geometry\": {\n        \"type\": \"LineString\",\n        \"coordinates\": [[-122.4194, 37.7749], ...]\n      },\n      \"properties\": {\n        \"name\": \"Main Route\",\n        \"distance_km\": 542.1,\n        \"type\": \"route\"\n      }\n    },\n    {\n      \"type\": \"Feature\", \n      \"geometry\": {\n        \"type\": \"Point\",\n        \"coordinates\": [-121.9018, 36.9741]\n      },\n      \"properties\": {\n        \"name\": \"Santa Cruz KOA\",\n        \"type\": \"overnight_accommodation\",\n        \"day\": 1\n      }\n    }\n  ]\n}\n```\n\n## 🔧 Development\n\n### Running Tests\n```bash\n# Run the test suite\npython -m pytest tests/\n\n# Run with coverage\npython -m pytest tests/ --cov=src/dirtgenie\n```\n\n### Contributing\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make changes and add tests\n4. Run tests: `python -m pytest`\n5. Submit a pull request\n\n### Code Quality\n```bash\n# Format code\nblack src/ tests/\n\n# Lint code  \nflake8 src/ tests/\n\n# Type checking\nmypy src/\n```\n\n## 💡 Tips \u0026 Best Practices\n\n### Planning Your Trip\n- **Be specific with locations**: Include city/state for better routing\n- **Start small**: Try a 2-3 night trip first to test the system\n- **Check seasonal conditions**: AI provides seasonal advice, but verify current conditions\n- **Review generated routes**: Always verify routes and accommodations before departure\n\n### Using the Tools\n- **Web App**: Best for interactive planning and iterative refinement\n- **CLI Tool**: Great for batch processing or scripting multiple trips\n- **API Quotas**: Monitor your OpenAI and Google Maps API usage\n- **Offline Backup**: Download offline maps as backup for remote areas\n\n### Route Quality\n- Google Maps bicycle routing is generally excellent but may occasionally suggest roads unsuitable for loaded touring\n- Cross-reference with local cycling resources and recent rider reports\n- Use the route as a starting point and refine based on local knowledge\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**\"No route found\"**\n- Check location spelling and try more specific addresses\n- Ensure locations are bicycle-accessible (not across oceans!)\n- Try alternative nearby locations if remote areas cause issues\n\n**API Key errors**\n- Verify keys are set correctly in `.env` file or environment variables\n- Check API quotas and billing status in respective consoles\n- Ensure required APIs are enabled in Google Cloud Console\n\n**Poor route suggestions**\n- Provide more specific preferences (terrain type, fitness level)\n- Use the feedback system in the web app to refine results\n- Consider the route as a starting point for manual refinement\n\n**Web app issues**\n- Check that the backend is running (port 8000) and frontend (port 3000)\n- Verify all dependencies are installed by running `./web/start.sh`\n- Clear browser cache and try refreshing the page\n- Check browser console for any JavaScript errors\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- **OpenAI** for providing the GPT models that power the intelligent planning\n- **Google Maps** for comprehensive bicycle routing data\n- **React \u0026 FastAPI** for the modern web application framework\n- **The bikepacking community** for inspiration and real-world testing\n\n## 🚀 Roadmap\n\n### Upcoming Features\n- **GPX Export**: Direct export to GPX format for GPS devices\n- **Elevation Profiles**: Visual elevation charts and climbing analysis\n- **Weather Integration**: Real-time weather forecasts and alerts\n- **Community Features**: Share and discover routes from other users\n- **Mobile App**: Native mobile application for on-the-go planning\n\n### Long-term Vision\n- **Multi-modal Planning**: Integrate train/bus connections for point-to-point trips\n- **Group Planning**: Plan trips for multiple riders with different preferences\n- **Real-time Updates**: Live route updates based on conditions and closures\n- **AI Learning**: Improve recommendations based on user feedback and trip reports\n\n---\n\n**Happy bikepacking! 🏕️🚴‍♀️**\n\n*DirtGenie - Where AI meets adventure*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa20r%2Fdirtgenie","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fa20r%2Fdirtgenie","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa20r%2Fdirtgenie/lists"}