# Voice Agent Platform

Backend (Django) and voice agent worker for the LiveKit-based voice agent. See [VOICE_AGENT_BACKEND_DESIGN.md](VOICE_AGENT_BACKEND_DESIGN.md) for full design.

## Structure

- **backend/** — Django app (PostgreSQL, Redis, Celery). REST API for tokens, conversations, turns, transcript; agent config; knowledge base.
- **worker/** — Voice agent worker (Python). Connects to LiveKit, runs STT → LLM → TTS, posts turns to backend.
- **livekit-master/** — Local LiveKit server (Go). Run this for real-time rooms and agent dispatch.

## Backend (Django)

### Setup

1. Activate your virtualenv, then install backend dependencies (required before migrate):

   ```bash
   cd backend
   python -m pip install -r requirements.txt
   ```
   On Windows PowerShell, use `python` (not `python3`). Ensure the venv that has Django is the one used here.

2. Copy env and set values:

   ```bash
   cp .env.example .env
   # Edit .env: SECRET_KEY, DATABASE_URL, REDIS_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET
   ```
   On Windows: `copy .env.example .env`

3. Create PostgreSQL DB (see “PostgreSQL setup” below), then run migrations:

   ```bash
   python manage.py migrate
   python manage.py createsuperuser   # optional
   ```

4. Run server:

   ```bash
   python manage.py runserver
   ```

5. **Django admin** — To log in at http://localhost:8000/admin/ with username **admin**, password **admin**, email **admin@gmail.com**, run once (from `backend/`):

   ```bash
   python manage.py create_admin
   ```

   Then open http://localhost:8000/admin/ and sign in with **admin** / **admin**. (Or use `python manage.py createsuperuser` to create a different admin user.)

6. (Optional) Run Celery worker for async tasks (requires `celery` installed):

   ```bash
   celery -A config worker -l info
   ```

### Test APIs

With the server running, from `backend/` run:

```bash
python test_apis.py
```

This hits `/`, `/api/`, `/api/agents/`, and the full conversation flow: start session → create user turn → attach agent response → get transcript. Optional: `python test_apis.py --base http://localhost:8000`.

### API (examples)

- **POST /api/sessions/start/** — Body: `{ "room_name?", "session_id?", "identity?" }`. Returns `token`, `room_name`, `conversation_id`, `identity`.
- **GET /api/token/?room=...&identity=...** — Returns LiveKit user token and conversation_id.
- **GET /api/conversations/<id>/transcript/** — Full transcript (user + agent turns).
- **GET /api/agents/<agent_name>/config/** — Agent config for worker (voice, guardrails, system_tools, etc.).

Worker POSTs to:

- **POST /api/conversations/<id>/turns/** — Create user turn (transcript, detected_language, stt_provider).
- **POST /api/conversations/<id>/turns/<turn_id>/response/** — Attach agent response (response_text, llm_provider, tts_provider, language_used).

## Worker

1. Use the **same virtualenv** as the backend. Activate it first, then install deps. On Windows use `python` (not `python3`):

   ```powershell
   # Activate the project venv (same as backend)
   & "C:\Users\Bhavya sree\Downloads\livekit-master\env\Scripts\Activate.ps1"
   # Or from repo root: .\env\Scripts\Activate.ps1

   cd "C:\Users\Bhavya sree\Downloads\livekit-master\worker"
   python -m pip install -r requirements.txt
   ```

2. Copy `.env.example` to `.env` and set `LIVEKIT_URL`, `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET`, `BACKEND_URL`, and STT/TTS/LLM API keys.

3. Run the worker (stub; wire full pipeline with livekit-agents). **Activate the venv in this terminal too**:

   **From the worker folder** (recommended on Windows):
   ```powershell
   & "C:\Users\Bhavya sree\Downloads\livekit-master\env\Scripts\Activate.ps1"
   cd "C:\Users\Bhavya sree\Downloads\livekit-master\worker"
   python main.py
   ```

   Or from the **repo root**:
   ```powershell
   cd "C:\Users\Bhavya sree\Downloads\livekit-master"
   python -m worker.main
   ```

### APIs used for STT, LLM, TTS

The worker uses one provider for each part of the pipeline. Set these in **worker/.env**:

| Role | Provider   | Env variable(s)     | Docs |
|------|------------|---------------------|------|
| **STT** (speech → text) | **Deepgram** | `DEEPGRAM_API_KEY` | [Deepgram API](https://developers.deepgram.com/home) |
| **LLM** (text → reply)  | **Sarvam AI** | `SARVAM_API_KEY`   | [Sarvam API](https://docs.sarvam.ai/sarvam-api-docs) |
| **TTS** (reply → speech) | **ElevenLabs** | `ELEVENLABS_API_KEY` and `ELEVEN_API_KEY` (LiveKit plugin reads `ELEVEN_API_KEY`) | [ElevenLabs API](https://elevenlabs.io/docs/eleven-api/quickstart) |

- **STT**: User audio → Deepgram → transcript + detected language → stored as user turn.
- **LLM**: Transcript + history (+ optional RAG) → Sarvam → response text.
- **TTS**: Response text → ElevenLabs → audio → published to the room.

Agent config in Django (`stt_provider`, `tts_provider`, `llm_provider`) can override or match these; the worker uses the keys above to call each API.

## LiveKit server

**ws://localhost:7880** is not a website you open in a browser. It is the WebSocket URL where the worker and LiveKit client connect. For it to work you must **run the LiveKit server** (Go) from `livekit-master/` (see its README). Until that server is running, "site can't be reached" at ws://localhost:7880 is expected.

Build and run the Go server from `livekit-master/`; use the same `LIVEKIT_API_KEY` and `LIVEKIT_API_SECRET` in backend and worker.

## Database

**PostgreSQL.** Run `python manage.py migrate` in `backend/`. Redis is used for Celery broker and cache (see design doc).

### PostgreSQL setup

#### Step-by-step: Create database and user

**Option 1 — Run the PowerShell script (easiest on Windows)**

1. Open **PowerShell**.
2. Go to the backend folder:
   ```powershell
   cd "C:\Users\Bhavya sree\Downloads\livekit-master\backend"
   ```
   (Or use your actual path to `livekit-master\backend`.)
3. Run the script:
   ```powershell
   .\scripts\create_db_voicebot.ps1
   ```
4. When prompted, enter the **postgres** user’s password (the one you set when you installed PostgreSQL). You may be asked twice (once for CREATE USER, once for CREATE DATABASE).
5. If you see “User may already exist” or “Database may already exist”, that’s fine — the script will set the password or skip.
6. Next: make sure `backend\.env` has `DATABASE_URL=postgresql://voicebot:vmc@localhost:5432/voicebot`, then run `python manage.py migrate`.

---

**Option 2 — Run the SQL file in psql**

1. Open **PowerShell** (or Command Prompt).
2. Go to the folder that contains the SQL file:
   ```powershell
   cd "C:\Users\Bhavya sree\Downloads\livekit-master\backend\scripts"
   ```
3. Run psql with the SQL file. Use the path where PostgreSQL is installed (change `16` to your version, e.g. `15` or `17`):
   ```powershell
   & "C:\Program Files\PostgreSQL\16\bin\psql.exe" -U postgres -f create_db_voicebot.sql
   ```
4. When prompted, enter the **postgres** user’s password.
5. You should see `CREATE USER` and `CREATE DATABASE` in the output. If you get “already exists”, the user or database was created earlier — you can run:
   ```powershell
   & "C:\Program Files\PostgreSQL\16\bin\psql.exe" -U postgres -c "ALTER USER voicebot WITH PASSWORD 'vmc';"
   ```
   to reset the password.
6. Next: ensure `backend\.env` has `DATABASE_URL=postgresql://voicebot:vmc@localhost:5432/voicebot`, then run `python manage.py migrate`.

---

**Option 3 — Run SQL commands one by one in PowerShell**

1. Open **PowerShell**.
2. Run (change `16` to your PostgreSQL version if needed):
   ```powershell
   & "C:\Program Files\PostgreSQL\16\bin\psql.exe" -U postgres -c "CREATE USER voicebot WITH PASSWORD 'vmc';"
   ```
   Enter the postgres password when asked.
3. Then run:
   ```powershell
   & "C:\Program Files\PostgreSQL\16\bin\psql.exe" -U postgres -c "CREATE DATABASE voicebot OWNER voicebot;"
   ```
   Enter the postgres password again if asked.
4. If the user already exists and you only need to fix the password:
   ```powershell
   & "C:\Program Files\PostgreSQL\16\bin\psql.exe" -U postgres -c "ALTER USER voicebot WITH PASSWORD 'vmc';"
   ```
5. Next: set `DATABASE_URL=postgresql://voicebot:vmc@localhost:5432/voicebot` in `backend\.env`, then run `python manage.py migrate`.

---

**After the database and user are created**

1. Copy `backend\.env.example` to `backend\.env` if you haven’t already:
   ```powershell
   cd "C:\Users\Bhavya sree\Downloads\livekit-master\backend"
   copy .env.example .env
   ```
2. Open `backend\.env` and confirm this line (no extra spaces or quotes):
   ```
   DATABASE_URL=postgresql://voicebot:vmc@localhost:5432/voicebot
   ```
3. Create all tables:
   ```powershell
   python manage.py migrate
   ```
4. Start the server:
   ```powershell
   python manage.py runserver
   ```

---

### PostgreSQL setup (reference)

1. Install PostgreSQL (e.g. from [postgresql.org](https://www.postgresql.org/download/) or package manager).

2. Create the database and user. **Do not paste the whole block into PowerShell** — run the commands as described.

   **Option A — Windows (PowerShell), one command at a time:**

   If `psql` is not in PATH, use the full path to `psql.exe` (version number may differ):

   ```powershell
   & "C:\Program Files\PostgreSQL\16\bin\psql.exe" -U postgres -c "CREATE USER voicebot WITH PASSWORD 'vmc';"
   & "C:\Program Files\PostgreSQL\16\bin\psql.exe" -U postgres -c "CREATE DATABASE voicebot OWNER voicebot;"
   ```

   If you added PostgreSQL’s `bin` folder to your system PATH:

   ```powershell
   psql -U postgres -c "CREATE USER voicebot WITH PASSWORD 'vmc';"
   psql -U postgres -c "CREATE DATABASE voicebot OWNER voicebot;"
   ```

   **Option B — pgAdmin (Windows GUI):**  
   Open pgAdmin → connect as `postgres` → right‑click “Login/Group Roles” → Create → Login → name: `voicebot`, password: `vmc`. Then right‑click “Databases” → Create → Database → name: `voicebot`, owner: `voicebot`.

   **Option C — Linux/macOS (terminal):**
   ```bash
   psql -U postgres -c "CREATE USER voicebot WITH PASSWORD 'vmc';"
   psql -U postgres -c "CREATE DATABASE voicebot OWNER voicebot;"
   ```

   Or run `psql -U postgres`, then type each SQL line and press Enter:
   ```sql
   CREATE USER voicebot WITH PASSWORD 'vmc';
   CREATE DATABASE voicebot OWNER voicebot;
   \q
   ```

3. Set `DATABASE_URL` in `backend/.env`:
   ```
   DATABASE_URL=postgresql://voicebot:vmc@localhost:5432/voicebot
   ```

4. Run migrations from the backend directory:
   ```bash
   cd backend
   python manage.py migrate
   python manage.py createsuperuser   # optional, for /admin/
   ```

### "password authentication failed for user voicebot"

This means PostgreSQL does not accept the password in your `DATABASE_URL`. Fix it in one of these ways:

**Option A — Fix script (easiest)**  
From the `backend` folder run:
```powershell
python scripts/fix_voicebot_db.py
```
Enter your **postgres** user password when prompted. The script sets the voicebot password to `vmc` and creates the database. Then run `python manage.py migrate` and `python manage.py runserver`.

**Option 1 — Reset the password (if user `voicebot` already exists)**  
Open pgAdmin or run as postgres (use your real PostgreSQL path if needed):

```powershell
& "C:\Program Files\PostgreSQL\16\bin\psql.exe" -U postgres -c "ALTER USER voicebot WITH PASSWORD 'vmc';"
```

**Option 2 — Create the user and database (if you never created them)**  
Run as postgres (database name: **voicebot**):

```powershell
& "C:\Program Files\PostgreSQL\16\bin\psql.exe" -U postgres -c "CREATE USER voicebot WITH PASSWORD 'vmc';"
& "C:\Program Files\PostgreSQL\16\bin\psql.exe" -U postgres -c "CREATE DATABASE voicebot OWNER voicebot;"
```

Or from backend folder: `.\scripts\create_db_voicebot.ps1`

**Option 3 — Use the default `postgres` superuser for development**  
If you know the postgres user’s password, in `backend/.env` set:

```
DATABASE_URL=postgresql://postgres:YOUR_POSTGRES_PASSWORD@localhost:5432/voicebot
```

Then create the database if it doesn’t exist:

```powershell
& "C:\Program Files\PostgreSQL\16\bin\psql.exe" -U postgres -c "CREATE DATABASE voicebot;"
```

After fixing the user/password, run `python manage.py runserver` again.