tavus-cli 0.1.1__tar.gz → 0.2.0__tar.gz

{tavus_cli-0.1.1 → tavus_cli-0.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: tavus-cli
-Version: 0.1.1
-Summary: Tavus CLI and MCP server for agentic persona creation and editing.
+Version: 0.2.0
+Summary: Tavus CLI and MCP server for agentic PAL creation and editing.
 Requires-Python: >=3.11
 Requires-Dist: fastmcp>=2.0.0
 Requires-Dist: httpx>=0.27.0
@@ -20,21 +20,25 @@ Description-Content-Type: text/markdown
 
 # tavus-cli
 
-Agent-facing surfaces that let another agent (Claude, Codex, or any MCP-aware client) drive Tavus persona creation end-to-end — separate from the human-facing Conversational Persona Builder.
+Agent-facing surfaces that let another agent (Claude, Codex, or any MCP-aware client) drive Tavus PAL creation end-to-end — separate from the human-facing PAL Maker.
 
 ## What's here
 
-- **MCP server.** Persona CRUD plus mutations for tools, KB, guardrails, pronunciation dicts, layers, and objectives. Local stdio for IDE-embedded clients, remote (Cloudflare Worker) for hosted agents.
-- **CLI.** Scripted persona authoring + publish. `tavus persona list / options / patch`, JSON round-tripping, OS-keychain auth.
+- **MCP server.** PAL CRUD plus mutations for tools, KB, guardrails, pronunciation dicts, layers, and objectives. Local stdio for IDE-embedded clients, remote (Cloudflare Worker) for hosted agents.
+- **CLI.** Scripted PAL authoring + publish. `tavus pal list / options / patch`, JSON round-tripping, OS-keychain auth.
 - **Codex skill.** Publishable skill so an external agent can invoke the MCP server and CLI without reading the full Tavus API.
 
-## Why standalone (not under Conversational Persona Builder)
+## Why standalone (not under PAL Maker)
 
-The Conversational Persona Builder project is the **human** builder — replica-driven, in-product. This repo is for **agents driving the API** without that UI. Adjacent in code and concepts, but a different deliverable and audience.
+The PAL Maker project is the **human** builder — face-driven, in-product. This repo is for **agents driving the API** without that UI. Adjacent in code and concepts, but a different deliverable and audience.
+
+> The Tavus API exposes `/v2/pals` and `/v2/faces` as backwards-compatible
+> vocabulary aliases over `/v2/personas` and `/v2/replicas`. This toolkit speaks
+> the new pal/face vocabulary throughout.
 
 ## Out of scope (for now)
 
-- Replica/video preview surfaces (live in the Conversational Persona Builder)
+- Face/video preview surfaces (live in the PAL Maker)
 - Marketplace / sharing UX
 - Multi-tenant auth beyond the existing dev-portal token model
 
@@ -57,11 +61,11 @@ Examples:
 
 ```bash
 # Production defaults; only the API key is required.
-TAVUS_API_KEY=... uv run tavus persona list
+TAVUS_API_KEY=... uv run tavus pal list
 
 # Test DB without URL overrides.
-TAVUS_ENV=TEST TAVUS_API_KEY=... uv run tavus persona list
-uv run tavus --env TEST persona list
+TAVUS_ENV=TEST TAVUS_API_KEY=... uv run tavus pal list
+uv run tavus --env TEST pal list
 ```
 
 The login flow opens the dev-portal at `/dev/cli-authorize` with a loopback callback URL and an
@@ -87,9 +91,9 @@ Local development commands:
 
 ```bash
 uv run tavus doctor
-uv run tavus persona list
-uv run tavus persona options <persona_id>
-uv run tavus persona patch <persona_id> --op replace --path /persona_name --value '"New Name"'
+uv run tavus pal list
+uv run tavus pal options <pal_id>
+uv run tavus pal patch <pal_id> --op replace --path /pal_name --value '"New Name"'
 ```
 
 ## MCP
@@ -184,8 +188,8 @@ OAuth routes yet.
 
 ## Codex Skill
 
-A publishable Codex skill for this repo lives at `skills/tavus-agentic-personas/`.
-It documents the CLI and MCP workflows, safe persona patching, environment setup,
+A publishable Codex skill for this repo lives at `skills/tavus-agentic-pals/`.
+It documents the CLI and MCP workflows, safe PAL patching, environment setup,
 and concrete examples for agents using this toolkit.
 
 Install it by copying that folder into `${CODEX_HOME:-$HOME/.codex}/skills/`, or

{tavus_cli-0.1.1 → tavus_cli-0.2.0}/README.md

@@ -1,20 +1,24 @@
 # tavus-cli
 
-Agent-facing surfaces that let another agent (Claude, Codex, or any MCP-aware client) drive Tavus persona creation end-to-end — separate from the human-facing Conversational Persona Builder.
+Agent-facing surfaces that let another agent (Claude, Codex, or any MCP-aware client) drive Tavus PAL creation end-to-end — separate from the human-facing PAL Maker.
 
 ## What's here
 
-- **MCP server.** Persona CRUD plus mutations for tools, KB, guardrails, pronunciation dicts, layers, and objectives. Local stdio for IDE-embedded clients, remote (Cloudflare Worker) for hosted agents.
-- **CLI.** Scripted persona authoring + publish. `tavus persona list / options / patch`, JSON round-tripping, OS-keychain auth.
+- **MCP server.** PAL CRUD plus mutations for tools, KB, guardrails, pronunciation dicts, layers, and objectives. Local stdio for IDE-embedded clients, remote (Cloudflare Worker) for hosted agents.
+- **CLI.** Scripted PAL authoring + publish. `tavus pal list / options / patch`, JSON round-tripping, OS-keychain auth.
 - **Codex skill.** Publishable skill so an external agent can invoke the MCP server and CLI without reading the full Tavus API.
 
-## Why standalone (not under Conversational Persona Builder)
+## Why standalone (not under PAL Maker)
 
-The Conversational Persona Builder project is the **human** builder — replica-driven, in-product. This repo is for **agents driving the API** without that UI. Adjacent in code and concepts, but a different deliverable and audience.
+The PAL Maker project is the **human** builder — face-driven, in-product. This repo is for **agents driving the API** without that UI. Adjacent in code and concepts, but a different deliverable and audience.
+
+> The Tavus API exposes `/v2/pals` and `/v2/faces` as backwards-compatible
+> vocabulary aliases over `/v2/personas` and `/v2/replicas`. This toolkit speaks
+> the new pal/face vocabulary throughout.
 
 ## Out of scope (for now)
 
-- Replica/video preview surfaces (live in the Conversational Persona Builder)
+- Face/video preview surfaces (live in the PAL Maker)
 - Marketplace / sharing UX
 - Multi-tenant auth beyond the existing dev-portal token model
 
@@ -37,11 +41,11 @@ Examples:
 
 ```bash
 # Production defaults; only the API key is required.
-TAVUS_API_KEY=... uv run tavus persona list
+TAVUS_API_KEY=... uv run tavus pal list
 
 # Test DB without URL overrides.
-TAVUS_ENV=TEST TAVUS_API_KEY=... uv run tavus persona list
-uv run tavus --env TEST persona list
+TAVUS_ENV=TEST TAVUS_API_KEY=... uv run tavus pal list
+uv run tavus --env TEST pal list
 ```
 
 The login flow opens the dev-portal at `/dev/cli-authorize` with a loopback callback URL and an
@@ -67,9 +71,9 @@ Local development commands:
 
 ```bash
 uv run tavus doctor
-uv run tavus persona list
-uv run tavus persona options <persona_id>
-uv run tavus persona patch <persona_id> --op replace --path /persona_name --value '"New Name"'
+uv run tavus pal list
+uv run tavus pal options <pal_id>
+uv run tavus pal patch <pal_id> --op replace --path /pal_name --value '"New Name"'
 ```
 
 ## MCP
@@ -164,8 +168,8 @@ OAuth routes yet.
 
 ## Codex Skill
 
-A publishable Codex skill for this repo lives at `skills/tavus-agentic-personas/`.
-It documents the CLI and MCP workflows, safe persona patching, environment setup,
+A publishable Codex skill for this repo lives at `skills/tavus-agentic-pals/`.
+It documents the CLI and MCP workflows, safe PAL patching, environment setup,
 and concrete examples for agents using this toolkit.
 
 Install it by copying that folder into `${CODEX_HOME:-$HOME/.codex}/skills/`, or

{tavus_cli-0.1.1 → tavus_cli-0.2.0}/docs/gemini-enterprise/README.md

@@ -86,14 +86,19 @@ after the connector passes Gemini Enterprise's review in `stg`.
 
 ## Scopes
 
+> **Naming note.** Tools and API paths use the new **pal/face** vocabulary
+> (`tavus_pal_*`, `/v2/pals`, `/v2/faces`). The OAuth **scope** strings remain
+> `tavus.personas.*` / `tavus.resources.*` — they are an auth-server contract and
+> are intentionally left unchanged until the auth team confirms pal-named scopes.
+
 | Scope | Grants |
 | --- | --- |
 | `tavus` | All scopes below (umbrella; default when no scope requested) |
-| `tavus.personas.read` | List, get, and describe personas + attached resources |
-| `tavus.personas.write` | Create, patch, delete personas; create from templates |
+| `tavus.personas.read` | List, get, and describe pals + attached resources |
+| `tavus.personas.write` | Create, patch, delete pals; create from templates |
 | `tavus.conversations.read` | (Reserved — read-only conversation tools land in a follow-up) |
 | `tavus.conversations.write` | Create + end conversations; run `tavus_quickstart` |
-| `tavus.resources.read` | List replicas, voices, guardrails, objectives, documents, llm tools; scaffold embed code |
+| `tavus.resources.read` | List faces, voices, guardrails, objectives, documents, llm tools; scaffold embed code |
 
 ## Tools → scope → API
 
@@ -102,17 +107,17 @@ forwarded from the bearer token.
 
 | Tool | Scope | Tavus API path |
 | --- | --- | --- |
-| `tavus_persona_list` | `tavus.personas.read` | `GET /v2/personas` |
-| `tavus_persona_get` | `tavus.personas.read` | `GET /v2/personas/{id}` |
-| `tavus_describe_persona_options` | `tavus.personas.read` | `GET /v2/personas/{id}` + `GET /v2/{replicas,voices,guardrails,objectives,documents,tools}` |
-| `tavus_persona_create` | `tavus.personas.write` | `POST /v2/personas` |
-| `tavus_persona_from_template` | `tavus.personas.write` | `POST /v2/personas` |
-| `tavus_persona_delete` | `tavus.personas.write` | `DELETE /v2/personas/{id}` |
-| `tavus_patch_persona` | `tavus.personas.write` | `PATCH /v2/personas/{id}` |
+| `tavus_pal_list` | `tavus.personas.read` | `GET /v2/pals` |
+| `tavus_pal_get` | `tavus.personas.read` | `GET /v2/pals/{id}` |
+| `tavus_describe_pal_options` | `tavus.personas.read` | `GET /v2/pals/{id}` + `GET /v2/{faces,voices,guardrails,objectives,documents,tools}` |
+| `tavus_pal_create` | `tavus.personas.write` | `POST /v2/pals` |
+| `tavus_pal_from_template` | `tavus.personas.write` | `POST /v2/pals` |
+| `tavus_pal_delete` | `tavus.personas.write` | `DELETE /v2/pals/{id}` |
+| `tavus_patch_pal` | `tavus.personas.write` | `PATCH /v2/pals/{id}` |
 | `tavus_conversation_create` | `tavus.conversations.write` | `POST /v2/conversations` |
 | `tavus_conversation_end` | `tavus.conversations.write` | `POST /v2/conversations/{id}/end` |
-| `tavus_quickstart` | `tavus.conversations.write` (+ implicit `tavus.personas.write`) | `POST /v2/personas` + `POST /v2/conversations` |
-| `tavus_replica_list` | `tavus.resources.read` | `GET /v2/replicas` |
+| `tavus_quickstart` | `tavus.conversations.write` (+ implicit `tavus.personas.write`) | `POST /v2/pals` + `POST /v2/conversations` |
+| `tavus_face_list` | `tavus.resources.read` | `GET /v2/faces` |
 | `tavus_resource_list` | `tavus.resources.read` | `GET /v2/{guardrails,objectives,documents,voices,tools}` |
 | `tavus_scaffold_embed` | `tavus.resources.read` | none (returns starter HTML/TSX locally) |
 
@@ -123,12 +128,12 @@ should rely on:
 
 | Annotation | Tools |
 | --- | --- |
-| `readOnlyHint: true` | `tavus_persona_list`, `tavus_persona_get`, `tavus_describe_persona_options`, `tavus_replica_list`, `tavus_resource_list`, `tavus_scaffold_embed` |
-| `destructiveHint: true` | `tavus_persona_delete`, `tavus_patch_persona`, `tavus_conversation_end` |
+| `readOnlyHint: true` | `tavus_pal_list`, `tavus_pal_get`, `tavus_describe_pal_options`, `tavus_face_list`, `tavus_resource_list`, `tavus_scaffold_embed` |
+| `destructiveHint: true` | `tavus_pal_delete`, `tavus_patch_pal`, `tavus_conversation_end` |
 | `openWorldHint: false` | `tavus_scaffold_embed` (returns local code, no network) |
 
 `idempotentHint: false` is set on every create-style tool that produces a new
-persona or conversation ID.
+pal or conversation ID.
 
 ## Adding the connector in Gemini Enterprise
 
@@ -160,7 +165,7 @@ persona or conversation ID.
 | Production | `https://mcp.tavus.io/mcp` | `https://tavusapi.com/v2` | `https://platform.tavus.io` | provided privately |
 
 Each env has a dedicated `gemini-enterprise-test@tavus.io` account pre-seeded
-with eval personas, replicas, and documents. Credentials and the golden query
+with eval pals, faces, and documents. Credentials and the golden query
 set ship out-of-band to the Gemini Enterprise reviewer.
 
 ## Support

{tavus_cli-0.1.1 → tavus_cli-0.2.0}/docs/gemini-enterprise/listing.md

@@ -6,18 +6,18 @@ intake. Edit here; ship the final values to the Gemini Enterprise admin.
 ## Short description (≤ 140 chars)
 
 > Create, configure, and run Tavus Conversational Video Interface (CVI)
-> personas and conversations from inside Gemini Enterprise.
+> pals and conversations from inside Gemini Enterprise.
 
 ## Long description (1–2 paragraphs)
 
 > Tavus is the Conversational Video Interface (CVI) platform powering real-time
-> AI video agents — replica avatars that hear, see, and respond on a Daily WebRTC
-> call. This connector lets a Gemini Enterprise agent author Tavus personas
-> (prompt, replica, voice, knowledge base, guardrails, objectives, perception
+> AI video agents — face avatars that hear, see, and respond on a Daily WebRTC
+> call. This connector lets a Gemini Enterprise agent author Tavus pals
+> (prompt, face, voice, knowledge base, guardrails, objectives, perception
 > layers) and spin up live conversations entirely through MCP.
 >
-> Typical agent tasks: "Create a tutor persona for our onboarding flow and start
-> a conversation," "rename persona X and swap its replica," "list all personas
+> Typical agent tasks: "Create a tutor pal for our onboarding flow and start
+> a conversation," "rename pal X and swap its face," "list all pals
 > tagged as customer-support and end any active conversations on them," or
 > "scaffold the React snippet I need to embed conversation Y in our portal."
 > Every write tool declares a destructive hint, every read tool declares a
@@ -74,7 +74,7 @@ API keys.** Tavus will share them via Google's secure intake channel.
 
 ## Marketplace tags
 
-`conversational-video`, `ai-agents`, `webrtc`, `avatars`, `cvi`, `personas`,
+`conversational-video`, `ai-agents`, `webrtc`, `avatars`, `cvi`, `pals`,
 `mcp`.
 
 ## Outstanding before submission
@@ -84,7 +84,7 @@ API keys.** Tavus will share them via Google's secure intake channel.
       mirroring [README.md](./README.md).
 - [ ] Stand up `mcp-connectors@tavus.io` distribution list.
 - [ ] Mint the three `gemini-enterprise-test+<env>@tavus.io` accounts and
-      seed each with the personas/replicas listed in
+      seed each with the pals/faces listed in
       [test-queries.md](./test-queries.md).
 - [ ] Reserve a final marketing-approved short + long description (the copy
       above is a starting point, not a sign-off).

tavus_cli-0.2.0/docs/gemini-enterprise/test-queries.md

@@ -0,0 +1,161 @@
+# Tavus MCP — Gemini Enterprise eval query set
+
+This is the "golden" query set Gemini Enterprise's review team runs against
+each test environment. Each query lists the natural-language prompt, the tool
+the agent is expected to call, the expected response shape, and the pass/fail
+criteria.
+
+Each test-env Tavus account is pre-seeded with at least:
+
+- 3 pals (`customer-support-demo`, `interviewer-demo`, `tutor-demo`)
+- 5 system faces
+- 2 documents
+- 1 guardrail set
+- 1 objective tree
+
+Credentials and exact pal/face IDs are delivered out-of-band per
+[README.md → Test environments](./README.md#test-environments).
+
+## Tool coverage matrix
+
+| # | Query intent | Tool exercised | Scope required |
+| --- | --- | --- | --- |
+| 1 | List pals | `tavus_pal_list` | `tavus.personas.read` |
+| 2 | Get a pal | `tavus_pal_get` | `tavus.personas.read` |
+| 3 | Describe pal options | `tavus_describe_pal_options` | `tavus.personas.read` |
+| 4 | Create a pal | `tavus_pal_create` | `tavus.personas.write` |
+| 5 | Create pal from template | `tavus_pal_from_template` | `tavus.personas.write` |
+| 6 | Patch a pal | `tavus_patch_pal` | `tavus.personas.write` |
+| 7 | Delete a pal | `tavus_pal_delete` | `tavus.personas.write` |
+| 8 | List faces | `tavus_face_list` | `tavus.resources.read` |
+| 9 | List voices | `tavus_resource_list` | `tavus.resources.read` |
+| 10 | Scaffold embed code | `tavus_scaffold_embed` | `tavus.resources.read` |
+| 11 | Quickstart end-to-end | `tavus_quickstart` | `tavus.personas.write` + `tavus.conversations.write` |
+| 12 | Create + end a conversation | `tavus_conversation_create`, `tavus_conversation_end` | `tavus.conversations.write` |
+
+## Queries
+
+### 1 — List pals
+
+> "Show me the first ten pals in my Tavus account."
+
+- **Expected tool call:** `tavus_pal_list({ "limit": 10 })`
+- **Expected response shape:**
+  ```jsonc
+  { "data": [ { "pal_id": "p…", "pal_name": "…", "created_at": "…" } ] }
+  ```
+- **Pass criteria:** `data.length >= 3`; every entry has a `pal_id` and a
+  `pal_name`.
+
+### 2 — Get a pal
+
+> "What's the system prompt on pal `customer-support-demo`?"
+
+- **Expected tool call:** `tavus_pal_get({ "pal_id": "<id>", "include_settings": true })`
+- **Pass criteria:** response includes `system_prompt` matching the seed value
+  `"You are a warm, concise customer support specialist…"`.
+
+### 3 — Describe pal options
+
+> "What faces, voices, and guardrails can I attach to pal `customer-support-demo`?"
+
+- **Expected tool call:** `tavus_describe_pal_options({ "pal_id": "<id>" })`
+- **Pass criteria:** response includes `available.faces`, `available.voices`,
+  `available.guardrails`, and `schemas.patchable_paths`.
+
+### 4 — Create a pal
+
+> "Create a new pal named `Gemini-eval-create` with the system prompt
+> `You are a Gemini Enterprise eval bot. Answer questions briefly.`"
+
+- **Expected tool call:** `tavus_pal_create({ "pal_name": "Gemini-eval-create", "system_prompt": "You are a Gemini Enterprise eval bot…" })`
+- **Pass criteria:** response contains a `pal_id`; a follow-up
+  `tavus_pal_get` on that ID returns the same prompt.
+- **Cleanup:** call `tavus_pal_delete` on the returned `pal_id`.
+
+### 5 — Create pal from template
+
+> "Spin up an interviewer pal biased for a senior backend role."
+
+- **Expected tool call:** `tavus_pal_from_template({ "template": "interviewer", "business_context": "Senior backend interview." })`
+- **Pass criteria:** `pal_id` returned; system prompt contains the literal
+  string `"Business context:"` followed by the supplied context.
+- **Cleanup:** delete the created pal.
+
+### 6 — Patch a pal
+
+> "Rename pal `customer-support-demo` to `customer-support-demo-renamed`."
+
+- **Expected tool call:** `tavus_patch_pal({ "pal_id": "<id>", "ops": [ { "op": "replace", "path": "/pal_name", "value": "customer-support-demo-renamed" } ] })`
+- **Pass criteria:** subsequent `tavus_pal_get` returns the new name.
+- **Cleanup:** patch the name back to `customer-support-demo`.
+
+### 7 — Delete a pal
+
+> "Delete pal `<temp-id>`." (use the pal created in query 4)
+
+- **Expected tool call:** `tavus_pal_delete({ "pal_id": "<id>" })`
+- **Pass criteria:** subsequent `tavus_pal_get` returns 404.
+
+### 8 — List faces
+
+> "What stock faces are available?"
+
+- **Expected tool call:** `tavus_face_list({ "stock": true })`
+- **Pass criteria:** `data.length >= 5`; each entry has a `face_id` and a
+  `face_name`.
+
+### 9 — List voices
+
+> "Show me 25 voices on the account."
+
+- **Expected tool call:** `tavus_resource_list({ "resource": "voices", "limit": 25 })`
+- **Pass criteria:** `data` is an array of objects with `voice_id` (or
+  equivalent ID field).
+
+### 10 — Scaffold embed code
+
+> "Give me the React iframe snippet for conversation
+> `https://tavus.daily.co/example`."
+
+- **Expected tool call:** `tavus_scaffold_embed({ "conversation_url": "https://tavus.daily.co/example", "target": "iframe" })`
+- **Pass criteria:** response contains a `files[0].content` string with the
+  conversation URL embedded inside an `<iframe>` tag.
+
+### 11 — Quickstart end-to-end
+
+> "Make me a tutor pal that explains gradient descent and start a
+> conversation with it."
+
+- **Expected tool call:** `tavus_quickstart({ "system_prompt": "<tutor prompt>", "pal_name": "Gradient descent tutor" })`
+- **Pass criteria:** response contains both `pal.pal_id` and
+  `conversation.conversation_id`, plus a `conversation_url` on the
+  conversation object.
+- **Cleanup:** call `tavus_conversation_end` on the conversation, then
+  `tavus_pal_delete` on the pal.
+
+### 12 — Create + end a conversation
+
+> "Create a conversation with pal `customer-support-demo`."
+
+- **Expected tool call:** `tavus_conversation_create({ "pal_id": "<id>" })`
+- **Pass criteria:** response contains a `conversation_id` and a
+  `conversation_url`.
+
+> "End that conversation."
+
+- **Expected tool call:** `tavus_conversation_end({ "conversation_id": "<id>" })`
+- **Pass criteria:** 2xx response; a subsequent `tavus_conversation_create`
+  against the same pal succeeds (i.e. the pal is not locked).
+
+## Failure handling
+
+For every query, Gemini Enterprise's tester should:
+
+- Confirm the bearer token survives in `Authorization: Bearer …` on every
+  follow-up MCP call.
+- Confirm the tool's `annotations.destructiveHint` matches the spec table in
+  the [README](./README.md#tool-annotations) — destructive tools should prompt
+  the user before invocation.
+- Capture any non-2xx Tavus API response in the eval log; Tavus support will
+  triage based on the embedded `status` + `body` fields.

{tavus_cli-0.1.1 → tavus_cli-0.2.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "tavus-cli"
-version = "0.1.1"
-description = "Tavus CLI and MCP server for agentic persona creation and editing."
+version = "0.2.0"
+description = "Tavus CLI and MCP server for agentic PAL creation and editing."
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [

tavus_cli-0.2.0/skills/tavus-agentic-pals/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: tavus-agentic-pals
+description: Use when Codex needs to create, inspect, edit, test, or embed Tavus pals with the tavus CLI or tavus-mcp MCP server. Covers local TEST/STG/PROD environment selection, dev-portal-style Firebase login, API-key storage, safe pal patching, account resource discovery, conversation creation, embed scaffolding, and CLI/MCP examples.
+---
+
+# Tavus Agentic PALs
+
+## Operating Model
+
+Use the `tavus` CLI when working in a local shell, debugging auth/env problems, validating patches, or producing reproducible commands for a human. Use the `tavus-mcp` MCP server when an agent host can call MCP tools directly and should create or edit Tavus resources through structured tool calls.
+
+Do not invent Tavus IDs. Discover faces, voices, guardrails, objectives, documents, and tools before attaching them to a pal. Do not delete pals or end conversations unless the user explicitly asks for that destructive action.
+
+For richer examples, read `references/examples.md`. For driving the new conversational pal builder (autocomplete, scoped LLM patches, publish), read `references/builder-workflow.md`. For driving a pal end-to-end through text (no daily.co/video — ideal for fast regression tests), read `references/chat-mode.md`. For the fully autonomous build-and-verify loop that chats with the builder *and* judges the result against CVI in one tool call, read `references/build-and-verify.md`.
+
+## Setup
+
+From the `tavus-mcp` repo:
+
+```bash
+uv sync --extra dev
+cp .env.example .env
+uv run tavus doctor --skip-network
+```
+
+The default environment is `PROD`. To switch to the test DB, set `TAVUS_ENV=TEST`
+in `.env` / the shell or pass `--env TEST` to the CLI. Explicit
+`TAVUS_PUBLIC_API_BASE_URL` and `TAVUS_PORTAL_API_BASE_URL` always win.
+
+Authentication options:
+
+```bash
+uv run tavus auth login
+uv run tavus auth status
+uv run tavus auth logout
+```
+
+`auth login` mirrors dev-portal login: Firebase popup sign-in, `/v3/users/me` developer validation, `/v3/users/update-metadata`, `/v2/api-key`, then env-scoped keyring storage. For noninteractive automation, set `TAVUS_API_KEY` or `TAVUS_<ENV>_API_KEY`.
+
+## CLI Workflow
+
+Start every live workflow with:
+
+```bash
+uv run tavus doctor
+```
+
+For greenfield work:
+
+```bash
+uv run tavus face list --stock --limit 5
+uv run tavus pal create \
+  --name "Support Concierge" \
+  --system-prompt "You are a concise support concierge..."
+uv run tavus conversation create --pal-id p123 --face-id r456
+```
+
+For existing pal edits:
+
+```bash
+uv run tavus pal get p123 --include-settings
+uv run tavus pal options p123
+uv run tavus pal paths
+uv run tavus pal patch p123 \
+  --path /pal_name \
+  --value '"Support Concierge v2"' \
+  --dry-run
+uv run tavus pal patch p123 \
+  --path /pal_name \
+  --value '"Support Concierge v2"'
+```
+
+Use `--dry-run` before applying manual JSON Patch operations. For multi-operation patches, write a JSON array and pass `--patch-file patch.json`.
+
+## MCP Setup
+
+Configure the MCP host to run the server from the repo:
+
+```json
+{
+  "mcpServers": {
+    "tavus": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/tavus-mcp", "tavus-mcp"]
+    }
+  }
+}
+```
+
+The MCP server reads the same `.env` and keyring as the CLI.
+
+## MCP Tool Map
+
+PAL tools:
+
+- `tavus_pal_list(limit, page, pal_type)`
+- `tavus_pal_get(pal_id, include_settings)`
+- `tavus_pal_create(system_prompt, pal_name, default_face_id)`
+- `tavus_pal_delete(pal_id)`
+- `tavus_patch_pal(pal_id, ops)`
+- `tavus_describe_pal_options(pal_id)`
+- `tavus_pal_from_template(template, pal_name, business_context, default_face_id, layers)`
+
+Conversation and resource tools:
+
+- `tavus_face_list(limit, stock)`
+- `tavus_conversation_create(pal_id, face_id, conversation_name)`
+- `tavus_conversation_end(conversation_id)`
+- `tavus_quickstart(system_prompt, pal_name, face_id)`
+- `tavus_resource_list(resource, limit)` for `guardrails`, `objectives`, `documents`, `voices`, or `tools`
+- `tavus_scaffold_embed(conversation_url, target, component_name)`
+
+`tavus_scaffold_embed` returns a file manifest. The MCP host agent writes files if the user wants files created.
+
+Conversational builder tools (mirrors the dev-portal creator-studio UI):
+
+- `tavus_builder_create(name, greeting?, pal_id?, model?)`
+- `tavus_builder_list(limit?, page?, pal_id?, name?, status?)`
+- `tavus_builder_get(builder_id)` / `tavus_builder_delete(builder_id)`
+- `tavus_builder_chat(builder_id, message)` — returns `{text, suggestions, draft_ready, targets}`
+- `tavus_builder_chat_history(builder_id, limit)`
+- `tavus_builder_append_messages(builder_id, messages)`
+- `tavus_builder_update_objectives|guardrails|greeting|personality(builder_id, message, ...)`
+- `tavus_builder_publish(builder_id)`
+
+Chat-mode (text-only pal testing) and preview:
+
+- `tavus_chat_start(pal_id, custom_greeting?, conversation_name?)`
+- `tavus_chat_turn(conversation_id, text, timeout_s?)` — one round-trip, returns `{text}`
+- `tavus_chat_end(conversation_id)`
+- `tavus_pal_preview(pal_id, face_id?, conversation_name?)` — returns `{conversation_id, conversation_url}` for handoff to a human
+
+Autonomous build + verify (one call drives the full loop):
+
+- `tavus_pal_build_and_verify(prompt, face_id?, max_rounds?, answers?)` — opens a builder session, converses with it through RQH's inner driver until `draft_ready` or `max_rounds`, publishes, asks RQH to select/attach a default face when `face_id` is omitted, runs a CVI text-mode smoke test, and returns a judge verdict over objectives/guardrails/knowledge base/tools. The builder driver, face selection, probe generator, and judge run on RQH — no client-side LLM key required.
+
+## Safe PAL Editing
+
+Before patching an existing pal, call `tavus_describe_pal_options` or `tavus pal options`. Use its `available` resources and `schemas.patchable_paths` output to choose valid IDs and patch paths.
+
+Prefer focused patches over full rebuilds:
+
+```json
+[
+  {"op": "replace", "path": "/pal_name", "value": "Support Concierge v2"},
+  {"op": "replace", "path": "/layers/conversational_flow/active_listening", "value": true},
+  {"op": "replace", "path": "/guardrails_id", "value": "grd_123"}
+]
+```
+
+Common patch targets include `/system_prompt`, `/greeting`, `/context`, `/pal_name`, `/default_face_id`, `/objectives_id`, `/guardrails_id`, `/document_ids`, `/document_tags`, and nested layer paths under `/layers/llm`, `/layers/tts`, `/layers/stt`, `/layers/perception`, `/layers/conversational_flow`, `/layers/capabilities`, and `/layers/knowledge_base`.
+
+## Creation Patterns
+
+Use `tavus_quickstart` or `uv run tavus quickstart` when the user wants a pal plus a conversation quickly. It uses the first stock face unless a face ID is provided.
+
+Use `tavus_pal_from_template` when the user asks for a common archetype. Supported templates are `customer-support`, `interviewer`, `sales`, `tutor`, and `dev-rel`.
+
+Use `tavus_pal_create` or `uv run tavus pal create` for precise custom prompts.
+
+Use the **conversational builder** when the user wants to *iterate* on a pal — talk to the builder, accept autocomplete suggestions, let the builder LLM scope which sections to re-draft, then publish. See `references/builder-workflow.md` for the full loop. The tight iteration pattern looks like:
+
+```bash
+uv run tavus builder create --name "Market Researcher" --model claude-sonnet-4-6
+uv run tavus builder chat <bid> --message "B2B SaaS, mid-market, founder-led"
+uv run tavus builder update personality <bid> --message "make the tone more direct" --system-prompt
+uv run tavus builder publish <bid>
+# A freshly built pal usually has no default_face_id. Attach one before testing.
+uv run tavus face list --stock --limit 1 --json   # grab a stock face_id
+uv run tavus pal patch <pid> --path /default_face_id --value '"<face_id>"'
+uv run tavus chat start --pal-id <pid>
+uv run tavus chat turn <cid> --message "describe your research process"
+uv run tavus pal preview <pid>   # prints conversation_url to hand to the user
+```
+
+When the agent wants the **whole loop** (build → publish → test → judge) in one shot, use the autonomous tool — see `references/build-and-verify.md`:
+
+```bash
+uv run tavus pal build \
+  --prompt "Friendly DevRel pal for a Postgres extension company" \
+  --max-rounds 4 --json
+```
+
+Gotchas worth knowing:
+
+- The `--model` flag takes the exact `BuilderLLM` enum string — currently `claude-sonnet-4-6` or `gpt-oss-120b`. Shorthand like `claude` / `openai` is rejected by RQH validation.
+- Standalone `tavus builder publish` pals may land with `default_face_id=""`; attach one before manual `tavus_chat_start` / preview. The autonomous `tavus pal build` command asks RQH to select one automatically unless you pass `--face-id`.
+
+The agent loop: edit → `tavus_chat_*` to test → patch via `tavus_builder_update_*` or `tavus_patch_pal` to refine → `tavus_pal_preview` when ready for visual confirmation.
+
+## Validation
+
+Use these checks after changing this repo or before claiming the tool is healthy:
+
+```bash
+uv run ruff check .
+uv run pytest -q
+uv run python -m compileall -q src tests
+uv build
+uv run tavus doctor
+```
+
+For read-only live smoke, prefer:
+
+```bash
+uv run tavus pal list --limit 1 --json
+uv run tavus face list --stock --limit 1 --json
+```

tavus_cli-0.2.0/skills/tavus-agentic-pals/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Tavus Agentic PALs"
+  short_description: "Build Tavus pals with the tavus CLI and MCP server."
+  default_prompt: "Use the Tavus Agentic PALs skill to create or edit a Tavus pal through the tavus CLI or tavus-mcp MCP server."