Metadata-Version: 2.4
Name: lampgo-livekit-agent-sdk
Version: 0.3.0
Summary: Business-facing Lampgo LiveKit Agent SDK.
License-Expression: Apache-2.0
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: livekit-agents[codecs]<2,>=1.5.5
Requires-Dist: livekit-api<2,>=1.0.7
Requires-Dist: livekit-plugins-openai>=1.5.5
Requires-Dist: livekit-plugins-silero>=1.5.5
Requires-Dist: pydantic<3,>=2
Requires-Dist: python-dotenv>=1
Requires-Dist: pyyaml>=6
Requires-Dist: typer>=0.15
Requires-Dist: uvicorn>=0.30
Description-Content-Type: text/markdown

# Lampgo LiveKit Agent SDK

Business-facing SDK for the Lampgo LiveKit RTC + Agent stack.

Full Chinese usage guide in this repository: `../docs/xiaomi-livekit-agent-sdk/usage.md`.

It wraps:

- LiveKit token generation with internal `RoomAgentDispatch`.
- `voice_agents[].name -> agent_name` mapping.
- FastAPI `/rtc/token` and `/healthz` routes.
- Parent process supervision for one HTTP token process plus one Agent Worker process per voice agent.
- LiveKit Agents runtime with Silero VAD, OpenAI-compatible LLM, and Volcengine STT/TTS.

## Install

From public PyPI:

```bash
pip install lampgo-livekit-agent-sdk
```

For local development from the repository root:

```bash
pip install -e ./xiaomi-livekit-agent-sdk
```

The Volcengine STT/TTS plugin is bundled in this SDK wheel, so business users do not
install `livekit-plugins-volcengine` separately.

> Both **local mode** (`livekit.api_key` + `livekit.api_secret`) and **cloud mode**
> (`platform.*` + `agent.registration_token`) work on the public PyPI install. For
> cloud mode on the public `livekit-agents`, the SDK adds external agent-token support
> at runtime, so no internal index or patched framework is required.

## Single Config File

The SDK uses one YAML file by default: `roles.yaml`.

The file now describes concrete voice agents. Each voice agent directly configures how it listens (`stt`), thinks (`llm`), and speaks (`tts`):

```yaml
version: 1

livekit:
  url: ${LIVEKIT_URL}
  api_key: ${LIVEKIT_API_KEY}
  api_secret: ${LIVEKIT_API_SECRET}

token_api:
  shared_secret: ${TOKEN_API_SHARED_SECRET:-}
  ttl_seconds: 600
  min_ttl_seconds: 60
  max_ttl_seconds: 3600

agent:
  name_prefix: lampgo-agent

providers:
  openai_internal:
    type: openai
    api_key: ${OPENAI_API_KEY}
    base_url: ${OPENAI_BASE_URL}

  volc_main:
    type: volcengine
    app_id: ${VOLCENGINE_APP_ID}
    access_token: ${VOLCENGINE_ACCESS_TOKEN}

defaults:
  stt:
    provider: volc_main
    options:
      resource_id: volc.bigasr.sauc.duration
      sample_rate: 16000
      result_type: single

  llm:
    provider: openai_internal
    options:
      model: xiaomi/mimo-v2-flash
      temperature: 0.3
      max_tokens: 512

  tts:
    provider: volc_main
    options:
      cluster: volcano_tts
      voice: BV700_streaming
      sample_rate: 24000
      streaming: true

voice_agents:
  - name: customer-service
    display_name: "小米客服助手"
    llm:
      system_prompt: "你是小米客服助手，用中文简短回答用户问题，不要使用 Markdown 或表情符号。"
```

`llm.system_prompt` is the model system prompt. For longer prompts, use:

```yaml
voice_agents:
  - name: customer-service
    llm:
      system_prompt_file: ./prompts/customer-service.md
```

If `token_api.shared_secret` is set, `/rtc/token` requires:

```http
Authorization: Bearer <shared bearer secret>
```

An empty `token_api.shared_secret` disables token API bearer auth for local/LAN testing.
If a token request sends `ttl_seconds`, the server clamps it to the configured min/max range.

Environment variables are only used when the YAML explicitly references them, for example `${OPENAI_API_KEY}` or `${TOKEN_API_SHARED_SECRET:-}`.

## Voice Agents

The SDK maps each configured voice agent to an internal LiveKit `agent_name`.

Default generated agent name:

```text
{agent.name_prefix or "lampgo-agent"}-{voice_agent_name_slug}
```

The public token API never returns `agent_name`.

## Run

```bash
lampgo-livekit-agent --config-file roles.yaml --host 0.0.0.0 --port 8080
```

Equivalent Python entry point:

```python
from lampgo_livekit_agent import LiveKitAgentConfig, start_service

start_service(config=LiveKitAgentConfig.from_env(config_file="roles.yaml"))
```

## Token API

For compatibility, the request field is still named `role`; it selects `voice_agents[].name`.

Request:

```bash
curl -X POST http://127.0.0.1:8080/rtc/token \
  -H 'Content-Type: application/json' \
  -d '{
    "room_name": "room-001",
    "user_identity": "user-001",
    "role": "customer-service",
    "metadata": {"tenant_id": "business-a"}
  }'
```

The new `voice_agent` field is also accepted:

```json
{
  "room_name": "room-001",
  "user_identity": "user-001",
  "voice_agent": "customer-service"
}
```

Response:

```json
{
  "token": "...",
  "serverUrl": "ws://192.168.31.116:7880",
  "roomName": "room-001",
  "identity": "user-001",
  "role": "customer-service"
}
```

The JWT contains:

```python
RoomConfiguration(
    agents=[RoomAgentDispatch(agent_name="<internal voice agent agent_name>")]
)
```

## FastAPI Integration

For an existing business FastAPI application:

```python
from fastapi import FastAPI
from lampgo_livekit_agent import LiveKitAgentConfig
from lampgo_livekit_agent.fastapi import mount_livekit_routes

app = FastAPI()
config = LiveKitAgentConfig.from_env(config_file="roles.yaml")

mount_livekit_routes(app, config=config)
```

Business services remain responsible for user authentication and room/tenant authorization.
