# Getting Started

This guide walks you through installing RoohAI, configuring your first voice agent, and running a conversation.

## Prerequisites

- Python 3.11+
- [Conda](https://docs.conda.io/) (recommended) or virtualenv
- A microphone and modern browser (Chrome, Edge, or Firefox)
- For cloud models: API keys for Deepgram, Cartesia, or AWS credentials for Bedrock

## Installation

### 1. Create the Environment

```bash
# Using conda (recommended)
conda create -n roohai python=3.11 -y
conda activate roohai

# Or using venv
python3.11 -m venv .venv && source .venv/bin/activate
```

### 2. Install RoohAI

```bash
# Core — includes local models (Whisper, SpeechT5, Silero VAD) and the server
pip install roohai

# All extras — adds Deepgram, Cartesia, Piper, NVIDIA NeMo
pip install "roohai[all]"

# Or pick individual extras
pip install "roohai[cloud]"     # Deepgram + Cartesia
pip install "roohai[deepgram]"  # Just Deepgram STT
pip install "roohai[cartesia]"  # Just Cartesia TTS
pip install "roohai[piper]"     # Just Piper TTS
pip install "roohai[nvidia]"    # NeMo toolkit (requires CUDA)
```

### 3. Set Up Cloud Credentials (Optional)

If you plan to use cloud models, set the relevant environment variables:

```bash
# Amazon Bedrock (for Claude LLM)
export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret
export AWS_DEFAULT_REGION=us-east-1

# Deepgram (for streaming STT)
export DEEPGRAM_API_KEY=dg-xxxx

# Cartesia (for cloud TTS)
export CARTESIA_API_KEY=sk-xxxx
```

You can also provide these through the web UI wizard — they are stored securely in `~/.roohai/secrets.yaml`.

## Running the Server

```bash
roohai
```

This starts the RoohAI server on **http://localhost:8000**. On first boot:

1. The default pipeline loads (Whisper + Bedrock Claude + SpeechT5 + Silero VAD)
2. If no agents exist, a "Default" agent is auto-created
3. The active agent's models are loaded into memory

Options:

```bash
roohai                       # Default: localhost:8000
roohai --host 0.0.0.0       # Bind to all interfaces
roohai --port 9000           # Custom port
```

## Your First Conversation

1. Click the **microphone button** to start streaming
2. The status indicator shows "Listening... (say something)"
3. Speak naturally — you'll see interim transcriptions appear in real time
4. When you pause, the pipeline processes: STT -> LLM -> TTS
5. The AI responds with synthesized speech
6. You can **interrupt at any time** by speaking while the AI is talking

## Creating a Custom Agent

Click **Create Voice Agent** in the sidebar to open the wizard:

1. **Step 1 — STT**: Choose your speech recognition model (Whisper, Wav2Vec2, or Deepgram)
2. **Step 2 — LLM**: Choose your language model (Bedrock Claude or Local TinyLlama)
3. **Step 3 — TTS**: Choose your voice (SpeechT5, Bark, Piper, or Cartesia)
4. **Step 4 — Review**: Name your agent, write a system prompt, and create it

The **system prompt** defines how your agent behaves — for example, "You are a friendly customer support agent. Keep answers brief." This is required for every agent.

The wizard handles model downloads and validation automatically. Once created, click an agent in the sidebar to activate it.

## Recommended Configurations

### Best Quality (Cloud)

| Component | Model | Why |
|-----------|-------|-----|
| STT | Deepgram Nova-3 | Real-time streaming, high accuracy |
| LLM | Bedrock Claude Haiku | Fast, capable, cost-effective |
| TTS | Cartesia Sonic-2 | Natural voice, low latency |
| VAD | Silero | Lightweight, local — no API needed |

### Fully Local (Offline)

| Component | Model | Why |
|-----------|-------|-----|
| STT | Whisper Tiny | Small footprint, multilingual |
| LLM | TinyLlama 1.1B | Runs on CPU (slow but private) |
| TTS | Piper (Lessac) | Fast local synthesis |
| VAD | Silero | Standard local VAD |

### Balanced (Mixed)

| Component | Model | Why |
|-----------|-------|-----|
| STT | Deepgram Nova-3 | Streaming transcription |
| LLM | Bedrock Claude Haiku | Cloud intelligence |
| TTS | Piper (Lessac) | Fast local voices, no API cost |
| VAD | Silero | Local, reliable |

## Next Steps

- [Architecture](architecture.md) — Understand the system design
- [Models Reference](models.md) — Detailed info on each model
- [Configuration](configuration.md) — Fine-tune your setup
- [Examples](examples.md) — Code examples for programmatic use
