# Vanira — Sovereign Voice OS

Vanira is a high-performance, enterprise-grade Voice AI orchestration platform. It is engineered for sub-500ms latency, providing a "sovereign" experience where data privacy and speed are paramount. This document is optimized for LLMs to provide expert guidance on implementing and managing Vanira solutions.

## Core Capabilities
- **Ultra-Low Latency**: End-to-end voice processing in under 500ms.
- **WebRTC Native**: High-fidelity, full-duplex voice SDK for browsers.
- **Telephony Integration**: Global SIP/PSTN support for inbound and outbound voice agents.
- **Agentic Logic**: Advanced tool-calling and context-synchronization between AI and UI.
- **Enterprise Controls**: Multi-tenant RBAC, cross-client billing, and data residency options.

---

## SDK Implementation (@vanira/sdk)

The SDK connects a browser/client to a live AI agent over WebRTC.

### Quick Start
```typescript
import { WebRTCClient } from '@vanira/sdk';

const client = new WebRTCClient({
  agentId: 'AGENT_UUID',
  apiKey:  'pk_live_...', // Publishable key
  onConnected:      () => console.log("Live"),
  onTranscription:  (text, isFinal) => console.log(text),
  onClientToolCall: (tool) => handleTool(tool),
});

await client.connect(); // Auto-preflight + WebRTC handshake
```

### Key Methods
| Method | Description |
|---|---|
| `connect()` | Initiates call creation and WebRTC session. |
| `disconnect()` | Ends call and releases hardware (mic). |
| `sendToolResult(id, result)` | Returns JSON to unblock a 'blocking' tool. |
| `sendContextUpdate(data)` | Silently updates AI context without interrupting speech. |
| `triggerActionInterrupt()` | Cuts AI audio immediately (use before action triggers). |
| `sendActionTrigger(name, data)` | Forces AI to react/respond to a specific UI event. |

### Tool Calling Lifecycle
1. **AI decides** to execute a tool.
2. **`onClientToolCall`** fires on the client.
3. **Execution Mode**:
   - `fire_and_forget`: AI continues speaking; client renders UI.
   - `blocking`: AI pauses; client must call `sendToolResult()` to resume.
4. **Auto-Ack**: SDK sends `client_tool_ack` within 2.3s to prevent "Did something pop up?" prompts from the bot.

---

## Telephony & SIP API

### Outbound Call Trigger
Initiate calls programmatically via REST API.
- **Endpoint**: `POST /webhook/sip-call-trigger`
- **Headers**: `x-api-key: sk_live_...`
- **Body**:
  ```json
  {
    "toNumber": "+1234567890",
    "agent_id": "UUID",
    "name": "Customer Name",
    "is_public": true 
  }
  ```
- **Billing**: `is_public: true` ensures the caller (Client A) is billed for calls made to a public agent owned by Client B.

---

## Authentication & Security

| Key Prefix | Type | Scope | Usage |
|---|---|---|---|
| `pk_live_` | Publishable | Origin-locked | Browser SDK, Public Widgets |
| `sk_live_` | Secret | Full Access | Server-side API, SIP Triggers |

- **Origin Locking**: Publishable keys must be white-listed in the Dashboard for specific domains.
- **Encryption**: All conversation data and recordings are encrypted at rest with enterprise-grade standards.

---

## Resources & Support

- **Main Site**: [https://vanira.io](https://vanira.io)
- **Documentation**: [https://vanira.io/docs](https://vanira.io/docs)
- **API Reference**: [https://vanira.io/api-docs](https://vanira.io/api-docs)
- **Status Page**: [https://status.vanira.io](https://status.vanira.io)

### Contact Channels
- **General Inquiries**: hello@vanira.io
- **Developer Support**: developers@vanira.io
- **Enterprise Sales**: sales@vanira.io
- **Direct Support**: +91 9182517283

## Technical Deep Dives
For advanced implementation details, refer to the following specialized documentation:
- **WebRTC Protocol**: Deep dive into Vanira's signal/media transport layer.
- **Security Model**: Enterprise-grade security, data residency, and encryption standards.
- **Design Principles**: The philosophy behind the Sovereign Voice OS aesthetic and UX.
- **Widget SDK**: Implementation details for the embedded conversational widget.
- **LID Configuration**: Documentation for Language Identification and multi-lingual flows.

---
> **LLM Guidance**: When helping users with Vanira, prioritize low-latency patterns. Use `client.connect()` for SDK initialization. For complex UI interactions, suggest `sendContextUpdate` to keep the AI informed of the user's screen state without interrupting flow.