---
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
```