Spaces:
Running
Running
| title: Gargi AI | |
| colorFrom: purple | |
| colorTo: indigo | |
| sdk: docker | |
| app_port: 7860 | |
| pinned: false | |
| # Gargi AI | |
| Gargi AI is a real-time AI teacher that turns any topic into an interactive | |
| voice lesson. Students can speak or type naturally, watch a Live2D teacher | |
| avatar respond with lip-sync, see adaptive whiteboard notes, and take quizzes | |
| inside the classroom. | |
| The app is built with FastAPI, Gemini Live, SQLite, PixiJS, and | |
| pixi-live2d-display. | |
| ## Run locally | |
| ```powershell | |
| python -m venv .venv | |
| .\.venv\Scripts\Activate.ps1 | |
| python -m pip install -r requirements.txt | |
| Copy-Item .env.example .env | |
| # Add your GEMINI_API_KEY to .env | |
| python app.py | |
| ``` | |
| Open `http://localhost:7860/docs` for the interactive API. | |
| Open `http://localhost:7860` for the Gargi AI web interface. | |
| ## Deploy to Hugging Face Spaces | |
| This project is ready for a Hugging Face Docker Space. | |
| ### 1. Create a new Space | |
| 1. Go to Hugging Face Spaces. | |
| 2. Choose **Create new Space**. | |
| 3. Select **Docker** as the Space SDK. | |
| 4. Upload or push this repository to the Space. | |
| The included `Dockerfile` runs: | |
| ```bash | |
| uvicorn gargi_ai.main:app --host 0.0.0.0 --port 7860 | |
| ``` | |
| Hugging Face Spaces expects web apps to listen on port `7860`, so no extra | |
| port configuration is required. | |
| ### 2. Add Space secrets | |
| In your Space settings, add these secrets or variables: | |
| ```text | |
| GEMINI_API_KEY=your Gemini API key | |
| GEMINI_MODEL=gemini-3.5-flash | |
| GEMINI_LIVE_MODEL=gemini-3.1-flash-live-preview | |
| GEMINI_LIVE_VOICE=Aoede | |
| EDGE_TTS_VOICE=en-US-JennyNeural | |
| DATABASE_URL=sqlite:///./data/gargi_ai.db | |
| AUDIO_DIR=data/audio | |
| ``` | |
| For persistent Hugging Face storage, enable persistent storage in the Space and | |
| use: | |
| ```text | |
| DATABASE_URL=sqlite:////data/gargi_ai.db | |
| AUDIO_DIR=/data/audio | |
| ``` | |
| ### 3. Deploy | |
| Commit and push to the Space repository: | |
| ```bash | |
| git add . | |
| git commit -m "Deploy Gargi AI to Hugging Face Spaces" | |
| git push | |
| ``` | |
| After the Space builds, open the public Space URL. The app UI is served at `/` | |
| and the API docs are available at `/docs`. | |
| ### Notes for the demo | |
| - Live voice uses Gemini Live over WebSockets. | |
| - If Gemini Live audio is unavailable, the browser fallback TTS speaks the | |
| streamed teacher transcript in near real time. | |
| - If Gemini artifact generation hits quota or temporary overload, Gargi creates | |
| a fallback whiteboard and quiz so the classroom keeps working. | |
| - Free-tier Gemini quota can return `429 RESOURCE_EXHAUSTED`; add billing or | |
| wait for quota reset if this happens during judging. | |
| ## Teaching flow | |
| 1. Create a lesson with `POST /api/v1/sessions`. | |
| 2. Send the browser ASR transcript to | |
| `POST /api/v1/sessions/{session_id}/teach`. | |
| 3. Consume the SSE events: `status`, `text_delta`, `lesson_payload`, | |
| `audio_ready`, `error`, and `done`. | |
| 4. Play the returned MP3 URL and submit quiz answers through the quiz endpoint. | |
| Edge TTS is used by the non-live fallback route. The classroom also supports | |
| browser speech synthesis fallback when live audio is unavailable. | |
| ## Gemini Live voice flow | |
| The primary real-time voice endpoint is: | |
| ```text | |
| ws://localhost:7860/api/v1/sessions/{session_id}/live | |
| ``` | |
| After connecting, wait for the JSON `ready` message. Send raw mono PCM signed | |
| 16-bit little-endian microphone chunks as binary WebSocket messages at 16 kHz. | |
| Send `{"type":"audio_end"}` when microphone capture stops. | |
| The server returns: | |
| - Binary messages: Gemini native audio, mono PCM signed 16-bit at 24 kHz. | |
| - `input_transcription`: ASR transcript fragments. | |
| - `output_transcription`: spoken model transcript fragments. | |
| - `lesson_payload`: whiteboard blocks, quiz, and learning-state updates. | |
| - `turn_complete`, `interrupted`, or `error` control messages. | |
| The connection supports multiple conversational turns and persists completed | |
| turns in SQLite. The existing SSE + Edge TTS route remains available as a | |
| fallback. | |
| ## Tests | |
| ```powershell | |
| python -m pytest -q | |
| ``` | |
| Set `RUN_LIVE_TESTS=1` and configure `GEMINI_API_KEY` to enable the optional | |
| live provider smoke test. | |
| To print a real Gemini answer and verify Live API audio support: | |
| ```powershell | |
| python test_gemini.py | |
| ``` | |
| Optionally save the Live API's raw 24 kHz PCM response: | |
| ```powershell | |
| python test_gemini.py --save-live-audio data/live_test_output.pcm | |
| ``` | |