Add VitePress documentation site and GitHub Actions for build + Pages deployment

.github/workflows/deploy-docs.yml

@@ -0,0 +1,57 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - '.github/workflows/deploy-docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: true
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: package-lock.json
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build VitePress site
+        run: npm run docs:build
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Docs
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - '.github/workflows/docs.yml'
+      - '.github/workflows/deploy-docs.yml'
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - '.github/workflows/docs.yml'
+      - '.github/workflows/deploy-docs.yml'
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Cache npm
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-20-${{ hashFiles('package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-20-
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build documentation
+        run: npm run docs:build

docs/.vitepress/config.ts

@@ -0,0 +1,58 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  title: 'OpenRTC',
+  description: 'Run multiple LiveKit voice agents in a single shared worker process.',
+  base: '/openrtc-python/',
+  cleanUrls: true,
+  lastUpdated: true,
+  themeConfig: {
+    logo: '/logo.svg',
+    nav: [
+      { text: 'Guide', link: '/getting-started' },
+      { text: 'Concepts', link: '/concepts/architecture' },
+      { text: 'API', link: '/api/pool' },
+      { text: 'Examples', link: '/examples' },
+    ],
+    sidebar: {
+      '/': [
+        {
+          text: 'Introduction',
+          items: [
+            { text: 'Overview', link: '/' },
+            { text: 'Getting Started', link: '/getting-started' },
+          ],
+        },
+        {
+          text: 'Core Concepts',
+          items: [
+            { text: 'Architecture', link: '/concepts/architecture' },
+          ],
+        },
+        {
+          text: 'Reference',
+          items: [
+            { text: 'AgentPool API', link: '/api/pool' },
+            { text: 'CLI', link: '/cli' },
+            { text: 'Examples', link: '/examples' },
+            { text: 'GitHub Pages Deployment', link: '/deployment/github-pages' },
+          ],
+        },
+      ],
+    },
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/mahimairaja/openrtc-python' },
+    ],
+    editLink: {
+      pattern: 'https://github.com/mahimairaja/openrtc-python/edit/main/docs/:path',
+      text: 'Edit this page on GitHub',
+    },
+    search: {
+      provider: 'local',
+    },
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright © Mahimai Raja J',
+    },
+  },
+})

docs/api/pool.md

@@ -0,0 +1,100 @@
+# AgentPool API
+
+## Imports
+
+```python
+from openrtc import AgentConfig, AgentPool
+```
+
+## `AgentConfig`
+
+```python
+@dataclass(slots=True)
+class AgentConfig:
+    name: str
+    agent_cls: type[Agent]
+    stt: Any = None
+    llm: Any = None
+    tts: Any = None
+    greeting: str | None = None
+```
+
+`AgentConfig` is returned from `AgentPool.add()` and represents a registered
+LiveKit agent configuration.
+
+## `AgentPool()`
+
+Create a pool that manages multiple LiveKit agents in one worker process.
+
+```python
+pool = AgentPool()
+```
+
+## `add()`
+
+```python
+pool.add(
+    name,
+    agent_cls,
+    *,
+    stt=None,
+    llm=None,
+    tts=None,
+    greeting=None,
+)
+```
+
+Registers a named LiveKit `Agent` subclass.
+
+### Validation rules
+
+- `name` must be a non-empty string after trimming whitespace
+- names must be unique
+- `agent_cls` must be a subclass of `livekit.agents.Agent`
+
+### Returns
+
+An `AgentConfig` instance for the registration.
+
+### Raises
+
+- `ValueError` for an empty or duplicate name
+- `TypeError` if `agent_cls` is not a LiveKit `Agent` subclass
+
+## `list_agents()`
+
+```python
+pool.list_agents()
+```
+
+Returns registered agent names in registration order.
+
+## `run()`
+
+```python
+pool.run()
+```
+
+Starts the LiveKit worker application.
+
+### Raises
+
+`RuntimeError` if called before any agents are registered.
+
+## Example
+
+```python
+from examples.agents.restaurant import RestaurantAgent
+from openrtc import AgentPool
+
+pool = AgentPool()
+pool.add(
+    "restaurant",
+    RestaurantAgent,
+    stt="deepgram/nova-3:multi",
+    llm="openai/gpt-5-mini",
+    tts="cartesia/sonic-3",
+)
+
+pool.run()
+```

docs/cli.md

@@ -0,0 +1,17 @@
+# CLI
+
+OpenRTC exposes a console script named `openrtc`.
+
+## Current status
+
+Today the CLI is a placeholder entrypoint that returns success and logs that
+full discovery-based CLI commands are planned for a future milestone.
+
+## Run the CLI
+
+```bash
+openrtc
+```
+
+Use the programmatic API for production usage today. The CLI page exists so the
+published docs accurately reflect the current package surface.

docs/concepts/architecture.md

@@ -0,0 +1,52 @@
+# Architecture
+
+OpenRTC keeps the public API intentionally narrow.
+
+## Core building blocks
+
+### `AgentConfig`
+
+`AgentConfig` stores the registration-time settings for a LiveKit agent:
+
+- unique `name`
+- `agent_cls` subclass
+- optional `stt`, `llm`, and `tts` providers
+- optional `greeting` placeholder for future use
+
+### `AgentPool`
+
+`AgentPool` owns a single LiveKit `AgentServer`, a registry of named agents, and
+one universal session handler.
+
+At startup it configures shared prewarm behavior so worker-level runtime assets
+are loaded once and reused across sessions.
+
+## Session lifecycle
+
+When a room is assigned to the worker:
+
+1. OpenRTC resolves the target agent from job metadata, room metadata, or the
+   first registered agent.
+2. Create an `AgentSession` using the selected agent configuration.
+3. Prewarmed VAD and turn detection models are injected from `proc.userdata`.
+4. The resolved agent instance is then started and connected to the LiveKit job
+   context.
+
+## Shared runtime dependencies
+
+During prewarm, OpenRTC loads:
+
+- `livekit.plugins.silero`
+- `livekit.plugins.turn_detector.multilingual.MultilingualModel`
+
+If those plugins are unavailable, OpenRTC raises a `RuntimeError` explaining
+that the package should be installed with the required extras.
+
+## Why this shape?
+
+This design keeps the package easy to reason about:
+
+- routing logic is explicit
+- worker-scoped dependencies are loaded once
+- agent registration stays stable and readable
+- the public API remains small enough for contributors to extend safely

docs/deployment/github-pages.md

@@ -0,0 +1,48 @@
+# GitHub Pages deployment
+
+This repository deploys documentation with VitePress and GitHub Actions.
+
+## Why GitHub Actions instead of a `gh-pages` branch?
+
+VitePress works well with the native GitHub Pages deployment flow:
+
+- build the site in CI
+- upload the static output as an artifact
+- deploy with `actions/deploy-pages`
+
+This keeps deployment configuration inside GitHub Actions and avoids managing a
+separate published branch.
+
+## One-time repository settings
+
+In GitHub:
+
+1. Go to **Settings → Pages**.
+2. Under **Build and deployment**, choose **GitHub Actions** as the source.
+3. Confirm the published site URL matches the repository path.
+
+For this repository, the expected project-site URL is:
+
+```text
+https://<owner>.github.io/openrtc-python/
+```
+
+## VitePress base path
+
+Because this is a project site, the VitePress config must set:
+
+```ts
+base: '/openrtc-python/'
+```
+
+If the repository name changes, update the base path in
+`docs/.vitepress/config.ts` and redeploy.
+
+## Local docs commands
+
+```bash
+npm install
+npm run docs:dev
+npm run docs:build
+npm run docs:preview
+```