Ruta Viva AI is an AI-powered outdoor adventure platform that transforms everyday walks into interactive missions. Discover your surroundings, complete real-world challenges, earn XP, and explore the world beyond your screen.
Built for the Hacktoberfest Open-Source AI Challenge โ Week 1: Touch Grass.
Live Demo ยท Source Code ยท API Documentation
We spend so much time looking at screens that we sometimes forget to explore the world around us.
Ruta Viva AI turns going outside into a small adventure. Instead of endlessly scrolling, users receive missions that encourage them to walk, observe nature, discover local culture, and pay attention to the places they visit.
The goal is simple:
Make the screen the shortest part of the adventure.
- ๐ค AI-Powered Adventure Selection โ AI interprets adventure preferences and selects a suitable adventure from a structured catalog.
- ๐บ๏ธ Outdoor Missions โ Complete real-world challenges focused on walking, observation, nature, and culture.
- ๐ฏ Personalized Preferences โ Choose an adventure type, difficulty level, and duration.
- โญ XP and Rewards โ Earn experience points by completing missions.
- ๐ณ Nature Exploration โ Discover colors, shapes, sounds, patterns, and other details in your surroundings.
- ๐๏ธ Cultural Discovery โ Observe architecture, public art, and the character of your community.
- โก JSON Adventure Catalog โ Reuse predefined adventures instead of generating every mission from scratch.
- ๐ก๏ธ Fallback Selection โ If the AI provider fails or times out, the backend can select a compatible adventure locally.
- ๐ฑ Responsive Interface โ Explore adventures from desktop or mobile devices.
Choose your preferred adventure type, difficulty, and duration to find an experience that fits your plans.
Every adventure contains a set of missions designed to encourage real-world exploration.
Turn a regular walk into an opportunity to discover something new.
Complete your missions, collect XP, and celebrate the experience.
Ruta Viva AI uses a hybrid architecture that combines AI-assisted selection with a structured JSON adventure catalog.
Instead of asking a language model to generate every mission from scratch, the application provides a set of predefined adventures and lets the AI choose the most appropriate option.
flowchart TD
A[User preferences] --> B[FastAPI backend]
B --> C[JSON adventure catalog]
C --> D[Filter by type and difficulty]
D --> E[AI selects a candidate]
E --> F{Valid selection?}
F -->|Yes| G[Return selected adventure]
F -->|No or timeout| H[Python fallback selection]
H --> G
G --> I[Angular displays the adventure]
I --> J[User explores the real world]
- Less generation work: the model selects existing content rather than writing every mission from scratch.
- Structured output: predefined missions, XP values, and adventure metadata make responses more consistent.
- Graceful degradation: Python can provide an alternative when the AI provider is unavailable.
- Flexible catalog: new adventures can be added without rewriting the selection logic.
The AI remains part of the decision-making process, while the catalog provides a reliable source of adventure content.
Open innovation makes it possible to experiment with AI systems, change models, inspect application logic, and build tools around individual needs.
For Ruta Viva AI, a model-based selection layer separates the adventure experience from the content catalog. This makes the project easier to extend, evaluate, and adapt to different AI providers and models.
The project uses an OpenRouter-compatible model configuration, allowing the model to be changed through backend configuration rather than hardcoding a specific model into the application.
The current implementation uses hosted inference, so it requires an internet connection and depends on the availability and limits of the configured provider. Local, offline inference is not currently implemented.
The broader goal is to keep the application adaptable: the AI model can evolve without requiring a complete redesign of the adventure system.
| Technology | Purpose |
|---|---|
| Angular | Responsive frontend application |
| TypeScript | Frontend logic and type safety |
| SCSS / CSS | Interface styling |
| Python | Backend logic |
| FastAPI | REST API and request validation |
| Pydantic | Data models and response validation |
| HTTPX | Asynchronous HTTP requests to the AI provider |
| OpenRouter | Access to the configured AI model |
| JSON | Structured adventure catalog |
| Vercel | Frontend deployment |
| Render | Backend deployment |
ruta-viva-ai/
โโโ backend/
โ โโโ app/
โ โ โโโ api/
โ โ โ โโโ adventures.py
โ โ โโโ core/
โ โ โ โโโ config.py
โ โ โโโ data/
โ โ โ โโโ adventures.json
โ โ โโโ models/
โ โ โ โโโ adventure.py
โ โ โโโ services/
โ โ โ โโโ ai_service.py
โ โ โ โโโ catalog_service.py
โ โ โโโ main.py
โ โโโ requirements.txt
โ
โโโ frontend/
โ โโโ public/
โ โ โโโ adventure/
โ โ โโโ badge/
โ โ โโโ create/
โ โ โโโ exploration/
โ โ โโโ hero/
โ โ โโโ loading/
โ โ โโโ result/
โ โโโ src/
โ
โโโ README.md
- Python 3.11 or a compatible Python version supported by your dependencies.
- Node.js and pnpm.
- An OpenRouter API key.
- Git.
git clone https://github.com/Ezequie1Sc/ruta-viva-ai.git
cd ruta-viva-aicd backend
python -m venv .venvActivate the virtual environment.
Windows PowerShell
.\.venv\Scripts\Activate.ps1macOS / Linux
source .venv/bin/activateInstall the dependencies:
python -m pip install -r requirements.txtCreate a .env file inside backend/:
OPENROUTER_API_KEY=your_openrouter_api_key
OPENROUTER_MODEL=your_supported_model_idUse a model ID supported by OpenRouter and compatible with the application's selection prompt.
Never commit your actual API key to GitHub.
From the backend/ directory:
python -m uvicorn app.main:app --reloadThe API will be available at:
- API:
http://127.0.0.1:8000/ - Health check:
http://127.0.0.1:8000/health - Interactive documentation:
http://127.0.0.1:8000/docs
Open a second terminal:
cd frontend
pnpm install
pnpm startIf your package.json does not define a start script, run Angular directly:
pnpm exec ng serveOpen http://localhost:4200/ in your browser.
Endpoint
POST /api/adventures/generateRequest body
{
"duration": 30,
"adventure_type": "nature",
"difficulty": "easy"
}Supported adventure types:
natureculturewalksurprise
Supported difficulty levels:
easymediumhard
Example response
{
"title": "Cazadores de hojas",
"description": "Explora las formas y texturas de la vegetaciรณn sin alterar el entorno.",
"duration": 30,
"missions": [
{
"title": "Hojas diferentes",
"description": "Observa tres hojas de formas distintas sin arrancarlas.",
"xp": 15
},
{
"title": "Busca sombras",
"description": "Encuentra dos sombras interesantes creadas por la vegetaciรณn.",
"xp": 10
},
{
"title": "Detecta simetrรญa",
"description": "Encuentra una forma simรฉtrica en la naturaleza.",
"xp": 15
}
],
"total_xp": 40
}GET /healthReturns the backend service status.
Ruta Viva AI encourages exploration without putting users at unnecessary risk.
Missions should:
- Use public and accessible spaces.
- Avoid dangerous roads and restricted areas.
- Encourage observation rather than touching unknown objects or wildlife.
- Never require purchases or special equipment.
- Respect the privacy of other people and the environment.
Stay aware of your surroundings and do not use your phone while crossing streets or navigating hazardous areas.
- GPS-based mission progress and route tracking.
- More diverse adventure categories and a larger curated catalog.
- Duration-aware adventure selection.
- Improved response-time monitoring and caching.
- Additional open-weight model options.
- Optional local inference for supported devices.
- More achievement badges and progression mechanics.
- User-submitted adventures and community contributions.
Challenge: Hacktoberfest Open-Source AI Challenge โ Week 1: Touch Grass
Theme: Build something with open-weight models or open-source AI that encourages people to spend more time outside.
Ruta Viva AI addresses this challenge by using AI-assisted adventure selection to turn everyday outdoor activities into structured, game-like experiences.
The project aims to make exploration more engaging while keeping the content system flexible and the experience focused on the real world.
Built for the challenge. Designed for the outdoors.
Contributions, suggestions, bug reports, and new adventure ideas are welcome.
- Fork the repository.
- Create a feature branch.
- Make your changes.
- Test the frontend or backend affected by your changes.
- Open a pull request describing your contribution.
Please avoid committing secrets, API keys, virtual environments, or generated build artifacts.
No license has been specified in this README. Add an appropriate LICENSE file before describing the repository as open source under a particular license.
Ready to turn an ordinary walk into an adventure?
Made with curiosity, code, and a little help from AI. ๐ฑ








