Logios AI · Tutor de Idiomas con IA

Tutor conversacional de idiomas impulsado por inteligencia artificial (Google Gemini), creado para Cartagena Construye con IA.

---

🌟 Características

• Conversación Fluida: Práctica conversacional continua con retención de contexto reciente.
• Pedagogía Positiva: Corrección puntual y amigable de errores gramaticales con explicaciones breves.
• Multilingüe: Soporte para 6 idiomas (Inglés 🇬🇧, Español 🇪🇸, Francés 🇫🇷, Portugués 🇧🇷, Alemán 🇩🇪 e Italiano 🇮🇹).
• Frontend Modular: Interfaz web rápida, responsiva y accesible sin dependencias externas pesadas.
• Backend Robusto: FastAPI con tipado estricto (Pydantic v2) y arquitectura en capas.

---

🏗️ Arquitectura del Proyecto

Logios-AI/
├── app/                      # Capa Backend (FastAPI)
│   ├── __init__.py
│   ├── config.py             # Configuración centralizada y entorno
│   ├── main.py               # Enrutamiento, CORS y montaje de estáticos
│   ├── schemas.py            # Modelos y validaciones Pydantic
│   └── services/
│       ├── __init__.py
│       └── ai_service.py     # Integración con Google GenAI SDK y prompts
├── static/                   # Capa Frontend (Modular)
│   ├── css/
│   │   └── style.css         # Hoja de estilos y diseño responsivo
│   ├── js/
│   │   └── app.js            # Controlador cliente, estado y llamadas a la API
│   └── index.html            # Plantilla principal de la interfaz de chat
├── .env.example              # Plantilla de variables de entorno
├── .gitignore                # Archivos ignorados por Git
├── requirements.txt          # Dependencias del proyecto
├── LICENSE                   # Licencia MIT
└── README.md                 # Documentación del sistema

---

🚀 Puesta en Marcha Local

1. Configuración de Variables de Entorno

Copia el archivo de ejemplo y añade tu clave de API de Google Gemini:

cp .env.example .env

Edita .env con tu clave:

GEMINI_API_KEY=tu_clave_de_gemini_aqui
GEMINI_MODEL=gemini-flash-latest

2. Instalación de Dependencias

Crea y activa tu entorno virtual (si aún no lo tienes):

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Instala los paquetes requeridos:

pip install -r requirements.txt

3. Ejecutar el Servidor

Inicia el servidor de desarrollo con recarga automática:

uvicorn app.main:app --reload --port 8000

O si usas el ejecutable del entorno virtual directamente:

.\.venv\Scripts\python.exe -m uvicorn app.main:app --reload --port 8000

4. Acceso y Verificación

• Interfaz Web: http://localhost:8000
• Monitoreo de Salud: http://localhost:8000/health
• Documentación Interactiva (Swagger/OpenAPI): http://localhost:8000/docs

---

💡 Flujo de Trabajo y Demo

1. Selecciona el idioma que deseas practicar en la barra lateral.
2. Haz clic en una sugerencia inicial o escribe tu mensaje en el chat (por ejemplo: I go yesterday to university.).
3. Logios celebrará tu intento, corregirá la conjugación del pasado ("I went"), te dará una explicación breve y continuará la conversación con una pregunta abierta.

---

🌐 Despliegue en Producción

Para desplegar esta aplicación en producción de manera estable, segura y escalable, tienes varias opciones recomendadas:

Opción 1: Plataformas en la Nube (PaaS) - Recomendado y rápido

Plataformas como Render, Railway o Fly.io detectarán automáticamente el archivo Dockerfile incluido en la raíz del proyecto.

1. Sube tu repositorio a GitHub.
2. Crea un nuevo servicio web en Render/Railway y conéctalo a tu repositorio.
3. Configura las siguientes variables de entorno en la plataforma:
   • GEMINI_API_KEY: Tu clave privada de la API de Google Gemini.
   • PORT: El puerto (generalmente asignado dinámicamente por la plataforma, ej: 8000).
4. La plataforma construirá la imagen del contenedor y lanzará la aplicación de forma automática.

Opción 2: Usando Docker de Forma Manual

Si deseas desplegar en tu propio servidor (VPS) usando contenedores:

# Construir la imagen de Docker
docker build -t logios-ai:latest .

# Ejecutar el contenedor mapeando el puerto 8000
docker run -d -p 8000:8000 --env-file .env --name logios-app logios-ai:latest

Opción 3: Servidor Linux VPS (Despliegue Tradicional)

Si prefieres correrlo directamente en una máquina virtual de Linux (Ubuntu/Debian):

1. Clonar e instalar dependencias:

   git clone <tu-repositorio>
   cd Logios-AI
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

2. Crear archivo de servicio Systemd (para que corra en segundo plano permanentemente):

   # /etc/systemd/system/logios.service
   [Unit]
   Description=Logios AI FastAPI Service
   After=network.target
   
   [Service]
   User=www-data
   WorkingDirectory=/var/www/Logios-AI
   ExecStart=/var/www/Logios-AI/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
   Restart=always
   
   [Install]
   WantedBy=multi-user.target

3. Iniciar el servicio:

   sudo systemctl enable logios
   sudo systemctl start logios

4. Configurar Nginx como Proxy Inverso: Redirige las solicitudes HTTPS del puerto 80/443 de tu dominio público al puerto interno 8000 usando Nginx.