# 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
pip install roohai

# For NVIDIA NeMo models (requires CUDA GPU)
pip install "roohai[nvidia]"
```

This includes all cloud providers (Deepgram, Cartesia, Bedrock), the Strands Agent SDK (OpenAI, Anthropic, Gemini, Ollama), and Silero VAD. Local model dependencies (Whisper, SpeechT5, Bark, Piper) are installed automatically when you select them in the agent wizard.

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

## Building in Code: The Builder API

If you prefer Python over YAML, the builder lets you construct a pipeline entirely in code:

```python
from roohai import Rooh

pipeline = (
    Rooh.builder()
    .stt("deepgram", model_id="nova-3", language="en", api_key="dg-xxxx")
    .llm("bedrock", model_id="anthropic.claude-3-5-sonnet-20241022-v2:0", region="us-west-2")
    .tts("cartesia", voice_id="79a125e8-cd45-4c13-8a67-188112f4dd22", api_key="sk-xxxx")
    .vad("silero")
    .vad_threshold(0.7)
    .barge_in(True)
    .silence_duration(1000)
    .system_prompt("You are a helpful voice assistant.")
    .build()
)
pipeline.load()
```

API keys can be passed inline or set as environment variables. Each builder method documents the accepted kwargs per provider — use `help(Rooh.builder().stt)` in a Python shell to see them.

See the [Examples](examples.md) page for the full builder reference, including offline agents, inline auth, and LLM hooks.

## Next Steps

- [Examples](examples.md) — Builder API, YAML config, hooks, and more
- [Architecture](architecture.md) — Understand the system design
- [Models Reference](models.md) — Detailed info on each model
- [Configuration](configuration.md) — Fine-tune your setup
