Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Pierrot-01/Hackathon_epis_2026/llms.txt

Use this file to discover all available pages before exploring further.

Vanguardia EPIS is a FastAPI-based early-warning system for school dropout risk in Peruvian rural schools. It pairs a deterministic rule engine with Google Gemini AI and is designed to run on any machine — including those with limited or intermittent connectivity. This guide walks you through every step from cloning the repository to verifying the server is running correctly.

​
Prerequisites

Before you begin, make sure the following are available on your machine:

Python 3.11+

Required for all backend dependencies. Check with python3 --version.

pip

Python’s package manager, bundled with Python 3.11+. Check with pip --version.

Gemini API Key

Free developer key from Google AI Studio. Required for live AI responses.

​
Installation Steps

1

Clone the repository

Download the project from GitHub and navigate into the project root:
git clone https://github.com/Pierrot-01/Hackathon_epis_2026.git
cd Hackathon_epis_2026
2

Install Python dependencies

Install all required packages from the backend/requirements.txt file:
pip install -r backend/requirements.txt
This installs the following packages:
PackageVersionPurpose
fastapi>=0.115.0REST API framework
uvicorn[standard]>=0.30.0ASGI server for FastAPI
google-genai>=2.0.0Google Gemini AI client
python-dotenv>=1.0.0.env file loader
pydantic>=2.0.0Data validation and models
Debian / Arch Linux users: If your system Python is managed by the OS package manager and blocks global installs, add the --break-system-packages flag:
pip install -r backend/requirements.txt --break-system-packages
Alternatively, use a Python virtual environment (see Optional: Virtual Environment below).
3

Configure environment variables

Create your backend/.env file from the provided template and add your Gemini API key:
cp backend/.env.example backend/.env
Then edit backend/.env with your key:
GEMINI_API_KEY=tu-api-key-de-gemini-aqui
See the Configuration page for all available options including the PORT variable and start.sh flags.
4

Pre-generate the AI cache (recommended)

Before your first run — especially before a demo or offline session — pre-generate all Gemini AI responses into a local cache file. This step avoids rate-limit errors during live presentations:
export GEMINI_API_KEY=tu-api-key-de-gemini-aqui
python3 generar_cache.py
This saves responses to cache/respuestas_ia.json. See the Cache Generation page for full details.
5

Start the server

Use the automated startup script (Linux / macOS):
./start.sh
Or start FastAPI directly from the backend/ directory:
cd backend && python3 main.py
The server starts on port 8000 by default. Once running, the following URLs are available:

Main App

http://localhost:8000 — Login screen (index.html)

Monitoring Dashboard

http://localhost:8000/monitoreo.html — Interactive risk panel

API Docs

http://localhost:8000/docs — Swagger / OpenAPI reference

​
Verifying the Installation

After installation, validate the deterministic rule engine by running the built-in test suite: 
python3 backend/classifier.py
Expected output: 
✅ Todos los tests pasaron! (10/10)
This confirms that the risk classification logic (Art. III of the project constitution) is working correctly across all 10 canonical test cases. The classifier is fully deterministic — identical inputs will always produce identical outputs, independent of network or AI availability.

​
Optional: Virtual Environment

If you prefer to isolate Vanguardia EPIS dependencies from your system Python, set up a virtual environment before running pip install: 
# Create the virtual environment
python3 -m venv .venv

# Activate it (Linux / macOS)
source .venv/bin/activate

# Activate it (Windows PowerShell)
.venv\Scripts\Activate.ps1

# Install dependencies
pip install -r backend/requirements.txt
Remember to activate the virtual environment each time you open a new terminal session before running ./start.sh or python3 main.py.

Build docs developers (and LLMs) love

Get started for freeTalk to us