feat(plugins-tavus): rename replica/persona to face/pal

[carolin-tavus]

Summary

Align the Tavus plugin with Tavus's renamed API (replica → face, persona → pal). Public params, env vars, and the wire payload move to the new naming; the old names stay working as deprecated aliases (non-breaking for plugin users).

• Add face_id/pal_id params (and TAVUS_FACE_ID/TAVUS_PAL_ID env vars) to AvatarSession and TavusAPI.create_conversation.
• Send face_id/pal_id on the conversation-create payload; add create_pal() hitting POST /v2/pals (pal_name + default_face_id), and auto-create a pal (not a persona) when none is supplied.
• Keep replica_id/persona_id params, TAVUS_REPLICA_ID/TAVUS_PERSONA_ID env vars, and create_persona() (legacy /v2/personas) working as deprecated aliases with a DeprecationWarning.
• Update the avatar_agents/tavus example to the new names.

Test plan

• ruff check (E,W,F,I,B,C4,UP) and ruff format --check pass.
• 7 mocked pytest cases pass (installed plugin, _post mocked): new keys map onto the face_id/pal_id wire payload, deprecated args/env still work and warn, auto-create routes to /v2/pals with default_face_id, the TAVUS_FACE_ID-required error, and AvatarSession alias resolution.
• Verified live against staging end-to-end (auto-create pal via /v2/pals → conversation with face_id/pal_id) on both the new-arg and deprecated-arg paths.

Notes

The face/pal wire support is live on Tavus prod (tavusapi.com); both old and new keys are accepted, so this is non-breaking for existing integrations.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[devin-ai-integration]

Devin Review found 2 potential issues.

[devin-ai-integration]

🟡 New test file missing required category marker, which will block CI collection

The new test module lacks the mandatory pytestmark declaration (test_tavus.py:1), so pytest's category enforcement will reject it.

Impact: The tests cannot be selected or run under the standard --unit flag, and CI will fail if this file is ever added to the main test paths.

AGENTS.md rule and enforcement details

The repository's AGENTS.md states:

Adding a test: give the new module a category marker (pytestmark = pytest.mark.unit, etc.) — collection fails with a hint if it lacks one.

Every other test module in the repo (including the comparable livekit-plugins/livekit-plugins-sarvam/tests/test_speech_timing.py:13) declares a module-level pytestmark. This file contains pure unit tests (everything is mocked, no network or credentials needed), so the correct marker is pytest.mark.unit.

Suggested change

	import warnings
	import warnings
	import pytest
	pytestmark = pytest.mark.unit

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🚩 Behavioral change: missing face/pal no longer raises an exception

Previously, if no replica_id was provided (via argument or env var), create_conversation raised TavusException("TAVUS_REPLICA_ID must be set"). Now, if neither face_id nor pal_id is provided, the code silently auto-creates a pal using DEFAULT_FACE_ID = "r72f7f7f7c8b" (livekit-plugins/livekit-plugins-tavus/livekit/plugins/tavus/api.py:27). This is a deliberate UX improvement (zero-config start), but existing users who relied on the error to catch missing configuration will no longer get that safety net. The default face ID is hardcoded; if it becomes invalid on the Tavus side, the API call will fail with a less clear error from the Tavus API rather than a local validation error.

---

Was this helpful? React with 👍 or 👎 to provide feedback.