Skip to content

About

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.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

ย 

History

184 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

Ruta Viva AI ๐ŸŒฟ

Turn the ordinary into an unforgettable adventure.

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.

Ruta Viva AI โ€” Explore the world beyond your screen

Live Demo Hacktoberfest 2026 Touch Grass Challenge

Live Demo ยท Source Code ยท API Documentation


๐ŸŒŽ The Idea

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.

โœจ Features

  • ๐Ÿค– 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.

๐Ÿ“ธ Explore the Experience

Create your adventure

Create an outdoor adventure Configure adventure preferences

Choose your preferred adventure type, difficulty, and duration to find an experience that fits your plans.

Discover your missions

Adventure details and outdoor missions Adventure mission interface

Additional adventure screen

Every adventure contains a set of missions designed to encourage real-world exploration.

Explore and track your journey

Outdoor exploration and progress

Turn a regular walk into an opportunity to discover something new.

Celebrate your progress

Adventure completion and results

Complete your missions, collect XP, and celebrate the experience.

Additional interface screens

Ruta Viva AI loading screen Ruta Viva AI achievement badge

๐Ÿง  How the AI Works

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]
Loading

Why this architecture?

  • 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.

๐ŸŒฑ Why Open Innovation Matters

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.

๐Ÿ› ๏ธ Tech Stack

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

๐Ÿ—๏ธ Project Architecture

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

๐Ÿš€ Getting Started

Prerequisites

  • Python 3.11 or a compatible Python version supported by your dependencies.
  • Node.js and pnpm.
  • An OpenRouter API key.
  • Git.

1. Clone the repository

git clone https://github.com/Ezequie1Sc/ruta-viva-ai.git
cd ruta-viva-ai

2. Configure the backend

cd backend
python -m venv .venv

Activate the virtual environment.

Windows PowerShell

.\.venv\Scripts\Activate.ps1

macOS / Linux

source .venv/bin/activate

Install the dependencies:

python -m pip install -r requirements.txt

3. Configure environment variables

Create a .env file inside backend/:

OPENROUTER_API_KEY=your_openrouter_api_key
OPENROUTER_MODEL=your_supported_model_id

Use a model ID supported by OpenRouter and compatible with the application's selection prompt.

Never commit your actual API key to GitHub.

4. Run the backend

From the backend/ directory:

python -m uvicorn app.main:app --reload

The 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

5. Run the frontend

Open a second terminal:

cd frontend
pnpm install
pnpm start

If your package.json does not define a start script, run Angular directly:

pnpm exec ng serve

Open http://localhost:4200/ in your browser.

๐Ÿ”Œ API Reference

Generate an adventure

Endpoint

POST /api/adventures/generate

Request body

{
  "duration": 30,
  "adventure_type": "nature",
  "difficulty": "easy"
}

Supported adventure types:

  • nature
  • culture
  • walk
  • surprise

Supported difficulty levels:

  • easy
  • medium
  • hard

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
}

Health check

GET /health

Returns the backend service status.

๐Ÿ›ก๏ธ Safety First

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.

๐Ÿ”ฎ Future Improvements

  • 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.

๐Ÿ† Hacktoberfest Open-Source AI Challenge

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.

๐Ÿค Contributing

Contributions, suggestions, bug reports, and new adventure ideas are welcome.

  1. Fork the repository.
  2. Create a feature branch.
  3. Make your changes.
  4. Test the frontend or backend affected by your changes.
  5. Open a pull request describing your contribution.

Please avoid committing secrets, API keys, virtual environments, or generated build artifacts.

๐Ÿ“„ License

No license has been specified in this README. Add an appropriate LICENSE file before describing the repository as open source under a particular license.

๐ŸŒฟ Get Outside

Ready to turn an ordinary walk into an adventure?

Start your adventure

Made with curiosity, code, and a little help from AI. ๐ŸŒฑ

About

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.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages