# RoohAI Framework

A modular, extensible framework for building real-time voice agents with swappable Speech-to-Text, Language Model, Text-to-Speech, and Voice Activity Detection components.

## Overview

RoohAI lets you assemble a conversational voice pipeline from interchangeable models. Choose local models for privacy and offline use, or cloud APIs for speed and quality — and swap them at runtime without restarting the server.

```
Microphone -> [STT] -> [LLM] -> [TTS] -> Speaker
                         ^
                       [VAD] (speech boundary detection)
```

### Key Features

- **Swappable models** — Mix local and cloud models via a registry + YAML config
- **Dual transport** — WebSocket and WebRTC support, selectable per-agent
- **Real-time streaming** — Deepgram live transcription with interim results
- **Barge-in support** — Users can interrupt the AI mid-response; playback stops immediately
- **Agent system** — Create, save, and switch between different voice agent configurations
- **Web UI** — Browser-based interface with a 4-step agent creation wizard
- **Hot-swap** — Change any model at runtime via API without server restart

## Documentation

| Document | Description |
|----------|-------------|
| [Getting Started](getting-started.md) | Installation, setup, and running your first agent |
| [Architecture](architecture.md) | System design, pipeline flow, and component overview |
| [Models Reference](models.md) | All available STT, TTS, LLM, and VAD models |
| [Configuration](configuration.md) | YAML config, agent configs, and secrets management |
| [API Reference](api.md) | REST, WebSocket, and WebRTC API endpoints |
| [Building Custom Models](custom-models.md) | How to implement and register your own models |
| [Examples](examples.md) | WebRTC, open-source pipelines, barge-in, and more |
<!-- | [Building & Publishing](building.md) | Build the wheel, test locally, publish to PyPI | -->

## Supported Models

| Component | Local | Cloud |
|-----------|-------|-------|
| **STT** | Whisper (tiny-large), Wav2Vec2, NVIDIA Parakeet, NVIDIA Canary-Qwen | Deepgram (Nova-2, Nova-3) |
| **LLM** | TinyLlama | Amazon Bedrock (Claude Haiku, Sonnet, Opus) |
| **TTS** | SpeechT5, Bark (small/large), Piper | Cartesia |
| **VAD** | Silero | — |

## Quick Start

```bash
# Create environment and install
conda create -n roohai python=3.11 -y
conda activate roohai
pip install "roohai[all]"

# Start the voice UI
roohai

# Open http://localhost:8000 in your browser
```

