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 designed to operate even when there is no active internet connection or when the Gemini API quota has been exhausted. The mechanism that makes this possible is a local JSON cache of pre-generated AI responses — one entry per student. The generar_cache.py script populates this cache by calling the Gemini API once per student while you do have connectivity, so the server can serve those responses indefinitely afterward without making any further API calls.

​
Why Pre-Generate the Cache?

Rate limit protection

Live demos that call the Gemini API in real time risk hitting per-minute or per-day rate limits mid-presentation. Pre-generating eliminates this risk entirely.

Offline operation

Rural school environments frequently lack reliable connectivity. A pre-generated cache guarantees the system works regardless of network availability.

Art. VIII §6.1 compliance

The project constitution mandates a cache-based resilience mechanism as a non-negotiable architectural requirement. Running this script fulfils that obligation.

Genuine AI responses

All cached entries are generated by the live Gemini model — never written by hand — fulfilling Art. VIII §8.1.1 and §8.1.2 of the specification.

​
How the Script Works

generar_cache.py is run from the project root and follows this sequence for every student record in the dataset:
1

Verify GEMINI_API_KEY

The script reads GEMINI_API_KEY from the environment. If the variable is not set, it prints an error and exits immediately:
❌ GEMINI_API_KEY no configurada.
   Obtén una gratis en: https://aistudio.google.com/app/apikey
   export GEMINI_API_KEY=tu-key-aqui
2

Load the student dataset

Reads all student records from data/estudiantes.json:
🚀 Generando cache de fallback (Art. VIII §6.1)
   Dataset: /path/to/data/estudiantes.json
   Cache:   /path/to/cache/respuestas_ia.json
------------------------------------------------------------
3

Classify each student with the rule engine

For every student record, clasificar_estudiante() is called to determine their risk level using the deterministic rule engine. This step does not call any external API — it is purely local logic.Risk levels produced by the classifier:
SymbolLevelMeaning
🔴AltoHigh dropout risk
🟡MedioModerate risk
🟢BajoLow risk
⚪Dato insuficienteInsufficient data to classify
4

Skip ⚪ students

Students classified as ⚪ (insufficient data) do not receive an AI-generated explanation — there is not enough information to make a meaningful analysis. These students are skipped silently with a log entry:
⚪ EST-007 — Nombre Apellido: Sin datos → omitido.
5

Call Gemini live for each remaining student

For every student with a 🔴, 🟡, or 🟢 classification, generar_explicacion() is called with the student’s ID, name, grade, risk level, risk trigger reasons, and any missing variables. The script logs progress inline:
⏳ EST-001 — María García (🔴)... ✅
⏳ EST-002 — Carlos López (🟡)... ✅
⏳ EST-003 — Ana Flores (🟢)...  ✅
If a call fails (e.g., network error or quota exceeded), the entry is marked with ❌ and the script continues to the next student:
⏳ EST-004 — Pedro Quispe (🔴)... ❌ error_api
6

Save to cache via guardar_en_cache()

Each successful live response is immediately written to cache/respuestas_ia.json by guardar_en_cache(). The script waits 0.5 seconds between API calls to respect Gemini’s rate limits.At the end of the run, a summary is printed:
✅ Cache generado: 18 entradas.
   Archivo: /path/to/cache/respuestas_ia.json

​
Running the Script

Make sure your API key is exported, then run from the project root: 
export GEMINI_API_KEY=your-key-here
python3 generar_cache.py
Run generar_cache.py once before any demo or offline session to guarantee that every student’s AI explanation is available locally. You only need to re-run it if the student dataset (data/estudiantes.json) changes significantly.

​
Cache File Structure

The output is saved at cache/respuestas_ia.json. Each key is a student ID, and each value contains the AI-generated explanation, teaching recommendation, and a generation timestamp: 
{
  "EST-001": {
    "explicacion": "María presenta un patrón de asistencia crítico...",
    "recomendacion": "Se recomienda una visita domiciliaria coordinada con...",
    "generado_en": "2025-01-15T14:32:07.123456"
  },
  "EST-002": {
    "explicacion": "Carlos muestra señales de alerta moderadas en su rendimiento...",
    "recomendacion": "Reforzar el acompañamiento tutorial quincenal y...",
    "generado_en": "2025-01-15T14:32:08.001234"
  }
}
Cache entries are never written by hand — they are always produced by calling the live Gemini model. This guarantees authenticity of all AI-generated content, as required by Art. VIII §8.1.1 and §8.1.2 of the project specification.

​
How the Cache Is Consumed

The server module fallback.py reads cache/respuestas_ia.json at startup using lazy loading. When the generar_explicacion() function is called for a student:
  1. It first checks whether GEMINI_API_KEY is available and attempts a live API call.
  2. If the live call fails (no key, quota exceeded, or network error), it looks up the student ID in the loaded cache.
  3. If a cache entry is found, it is returned with origen_ia: "fallback".
  4. If neither a live response nor a cache entry is available, the response is returned with origen_ia: "error_sin_cache".
This cascade ensures the system is always operable, even in fully disconnected environments, as long as the cache was generated beforehand.

Build docs developers (and LLMs) love

Get started for freeTalk to us