echo-tutor / README.md
Nanny7's picture
feat(auth): add central Nova auth proxy mode with feature flag
5dca017
|
Raw History Blame Contribute Delete
3.78 kB
---
title: ECHO TUTOR PRO
emoji: 'πŸ—£οΈ'
colorFrom: blue
colorTo: indigo
sdk: docker
app_file: app.py
pinned: false
---
# ECHO TUTOR PRO πŸ—£οΈ
An AI-powered English language tutor with a premium, immersive interface. Practice natural English conversation with real-time corrections, suggestions, and adaptive difficulty.
## ✨ Features
- **Streaming AI Responses** β€” Real-time token-by-token response rendering via SSE
- **Adaptive Difficulty** β€” Beginner, Intermediate, and Advanced levels
- **Conversation Topics** β€” 8 curated topics: Free Talk, Travel, Food, Tech, Movies, Sports, Work, Daily Life
- **Premium UI** β€” Glassmorphism design, animated particle background, 3D orb avatar
- **Voice Interaction** β€” Real-time Speech-to-Text (STT) and Text-to-Speech (TTS)
- **Audio Waveform** β€” Live microphone visualization using Web Audio API
- **Smart Corrections** β€” AI provides inline corrections and vocabulary suggestions
- **PWA Support** β€” Installable as a Progressive Web App
- **Session Persistence** β€” Conversation history saved across page refreshes
- **Keyboard Shortcuts** β€” Ctrl+M (mic), Enter (send), Escape (end)
## πŸš€ Quick Start
### 1. Clone the repository
```bash
git clone <your-repo-url>
cd echo-tutor
```
### 2. Set environment variable
```bash
export NVIDIA_API_KEY="your-api-key-here"
```
### 3. Install dependencies
```bash
pip install -r requirements.txt
```
### 4. Run locally
```bash
python app.py
```
Open `http://localhost:7860` in your browser.
## Auth + Nova Integration (Production Runtime)
- Production runtime for `PROJECT_APP` is Flask via `app.py` (not `main.py`).
- Auth pages are served as standalone routes:
- `/signup`
- `/verify`
- `/login`
- Auth API is mounted under `/auth` from `auth_module.flask_auth_routes`.
- Signup/request-otp generates local OTP and pushes it to Nova when configured:
- `POST /api/external/push-otp` on Nova
- `GET /api/external/check-verified` on Nova
Required env keys for integration:
- `NOVA_API_URL`
- `NOVA_API_KEY`
- `APP_ID`
- `JWT_SECRET_KEY`
To route auth through Nova centrally, set:
- `AUTH_MODE=central`
- `AUTH_PROXY_TIMEOUT_SECONDS=15`
## 🐳 Docker
```bash
docker build -t echo-tutor .
docker run -p 7860:7860 -e NVIDIA_API_KEY="your-key" echo-tutor
```
## πŸ“ Project Structure
```
echo-tutor/
β”œβ”€β”€ app.py # Flask backend with streaming SSE
β”œβ”€β”€ config.py # Configuration (levels, topics, API settings)
β”œβ”€β”€ requirements.txt # Python dependencies
β”œβ”€β”€ Dockerfile # Docker container configuration
β”œβ”€β”€ Procfile # Gunicorn process file
β”œβ”€β”€ templates/
β”‚ └── index.html # Main application template
└── static/
β”œβ”€β”€ css/style.css # Premium glassmorphism design system
β”œβ”€β”€ js/script.js # Application engine (SSE, particles, waveform)
β”œβ”€β”€ manifest.json # PWA manifest
β”œβ”€β”€ service-worker.js
└── icons/
β”œβ”€β”€ icon-192.png
└── icon-512.png
```
## πŸ”§ API Endpoints
| Endpoint | Method | Description |
| -------------- | ------ | ------------------------------------ |
| `/` | GET | Main application page |
| `/chat` | POST | Non-streaming chat endpoint |
| `/chat/stream` | POST | SSE streaming chat endpoint |
| `/topics` | GET | Available topics & difficulty levels |
| `/health` | GET | Health check with uptime |
## 🌐 Deploy on Hugging Face Spaces
1. Push to your HF Space repository
2. Set `NVIDIA_API_KEY` as a Space secret
3. The app runs automatically via Docker
For more: <https://huggingface.co/docs/hub/spaces-config-reference>