README.md

metadata

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

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:

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:

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:

DATABASE_URL=sqlite:////data/gargi_ai.db
AUDIO_DIR=/data/audio

3. Deploy

Commit and push to the Space repository:

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:

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

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:

python test_gemini.py

Optionally save the Live API's raw 24 kHz PCM response:

python test_gemini.py --save-live-audio data/live_test_output.pcm