# Vg Livekit

Voice AI assistant built with **LiveKit Agents** for Python. Speak to the agent in your terminal, browser, or via telephony.

## Getting started

To get up and running with this project:

- [ ] [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files
- [ ] [Add files using the command line](https://docs.gitlab.com/topics/git/add_files/#add-files-to-a-git-repository) or push an existing Git repository:

```
cd existing_repo
git remote add origin http://10.0.0.109:400/VikasGupta/vg-livekit.git
git branch -M main
git push -uf origin main
```

- [ ] [Set up project integrations](http://10.0.0.109:400/VikasGupta/vg-livekit/-/settings/integrations)
- [ ] [Invite team members and collaborators](https://docs.gitlab.com/ee/user/project/members/)
- [ ] [Create a new merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)
- [ ] [Automatically close issues from merge requests](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically)
- [ ] [Enable merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/)
- [ ] [Set auto-merge](https://docs.gitlab.com/user/project/merge_requests/auto_merge/)

## Test and Deploy

- [ ] [Get started with GitLab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/)
- [ ] [Analyze code with SAST](https://docs.gitlab.com/ee/user/application_security/sast/)
- [ ] [Deploy to Kubernetes, EC2, or ECS with Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/requirements.html)
- [ ] [Pull-based deployments for Kubernetes](https://docs.gitlab.com/ee/user/clusters/agent/)
- [ ] [Set up protected environments](https://docs.gitlab.com/ee/ci/environments/protected_environments.html)

---

## Description

**LiveKit** is an open-source, WebRTC-based real-time communication platform. This project runs a **LiveKit Agent** that joins a room when a user connects, receives audio, runs STT → LLM → TTS, and sends speech back.

- **Real-time audio** over WebRTC
- **Rooms** where users and the agent exchange audio
- **Voice pipeline:** Deepgram (STT) → OpenAI (LLM) → Cartesia (TTS)

Console mode lets you talk to the agent from your terminal; **dev** mode connects to LiveKit so you can use the [Agents Playground](https://docs.livekit.io/agents/start/playground/) or your own frontend.

## Requirements

- **Python 3.10+**
- **LiveKit Cloud** account (free): [cloud.livekit.io](https://cloud.livekit.io/)
- **OpenAI API key** (for the LLM)
- **Console mode only:** PortAudio. On Debian/Ubuntu: `sudo apt-get install libportaudio2`
- Optional: [LiveKit CLI](https://docs.livekit.io/home/cli/cli-setup) for `lk cloud auth` and `lk app env -w`

## Installation

### 1. Install dependencies

```bash
cd /var/www/html/livekit_voicebot
uv sync
# or: pip install -r requirements.txt
```

### 2. Environment variables

```bash
cp .env.example .env.local
```

Edit `.env.local`: set `LIVEKIT_URL`, `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET`, `OPENAI_API_KEY`. Or use:

```bash
lk cloud auth
lk app env -w -d .env.local
```
Then add `OPENAI_API_KEY` manually.

### 3. Download model files (first time only)

```bash
uv run python agent.py download-files
# or: python agent.py download-files
```

## Usage

**Console** (talk in terminal):

```bash
uv run python agent.py console
# or: python agent.py console
```

**Dev** (for Playground or your frontend):

```bash
uv run python agent.py dev
```

**Production:**

```bash
uv run python agent.py start
```

## Project layout

| File | Purpose |
|------|--------|
| `agent.py` | Agent logic and CLI (`console` / `dev` / `start` / `download-files`) |
| `pyproject.toml` | Dependencies (uv) |
| `requirements.txt` | Dependencies (pip) |
| `.env.example` | Env template |

## Troubleshooting

### `OSError: PortAudio library not found` (console mode)

Install PortAudio:

- **Debian/Ubuntu:** `sudo apt-get update && sudo apt-get install -y libportaudio2`
- **Fedora:** `sudo dnf install portaudio`
- **macOS:** `brew install portaudio`

Then run `python3 agent.py console` again.

## Support and docs

- [LiveKit](https://livekit.io/)
- [LiveKit Agents – Voice AI](https://docs.livekit.io/agents/start/voice-ai/)
- [LiveKit Agents – Build](https://docs.livekit.io/agents/build/)

---

# Editing this README

When you're ready to make this README your own, edit this file and use the template below (or structure it however you want). Thanks to [makeareadme.com](https://www.makeareadme.com/) for the template.

## Suggestions for a good README

Every project is different, so consider which of these sections apply to yours.

| Section | Use for |
|--------|---------|
| **Name** | A clear, self-explaining project name. |
| **Description** | What the project does, context, and links to references. Features or background can go here. |
| **Badges** | Metadata (e.g. build status). [Shields](https://shields.io/) is one option. |
| **Visuals** | Screenshots or short videos (e.g. GIFs, [Asciinema](https://asciinema.org/)). |
| **Installation** | Step-by-step install. Include requirements and OS/language version if relevant. |
| **Usage** | Examples and expected output. Link to more advanced examples if needed. |
| **Support** | Where to get help: issue tracker, chat, email, etc. |
| **Roadmap** | Planned releases or features. |
| **Contributing** | How to contribute and what you expect (e.g. tests, lint). |
| **Authors and acknowledgment** | Credits and thanks. |
| **License** | How the project is licensed. |
| **Project status** | If the project is inactive or looking for maintainers, say so at the top. |