feat(tavus): rename replicaId/personaId options to faceId/palId#1886
feat(tavus): rename replicaId/personaId options to faceId/palId#1886carolin-tavus wants to merge 9 commits into
Conversation
Tavus is renaming its public API surface from replica/persona to face/pal. Rename the plugin's public options (faceId/palId) and env vars (TAVUS_FACE_ID/TAVUS_PAL_ID); the old replicaId/personaId options and TAVUS_REPLICA_ID/TAVUS_PERSONA_ID env vars still work as deprecated aliases. The Tavus wire payload keys are unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
🦋 Changeset detectedLatest commit: bbc9aa6 The changes in this PR will be included in the next version bump. This PR includes changesets to release 35 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
|
turbo/no-undeclared-env-vars lint rule requires env vars read in source to be listed in globalEnv. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Mocked vitest unit tests (no live API): faceId/palId map onto the unchanged wire keys, deprecated replicaId/personaId still work and warn, env-var fallback, and the TAVUS_FACE_ID-required error. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The Tavus API now accepts face_id/pal_id on /v2/conversations and exposes /v2/pals (pal_name + default_face_id). Send the new keys, add createPal() hitting /v2/pals, and auto-create a pal (not a persona) when none is given. createPersona() stays as a deprecated alias on the legacy /v2/personas. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A pal carries its own default_face_id, so a conversation can be created from palId alone. Require faceId only when no palId is given (to create one); otherwise send palId and let the pal's default face apply. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Instead of erroring when neither a face nor a pal is given, fall back to a default stock face to create the pal, so the zero-config path works. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| if (!palId) { | ||
| // no pal to reuse, so create one — falling back to the default face | ||
| palId = await this.createPal({ defaultFaceId: faceId || DEFAULT_FACE_ID }); |
There was a problem hiding this comment.
🚩 New pal is created on every conversation when palId is not cached
When no palId is provided (neither via options nor env), createConversation calls createPal which makes an extra HTTP request to /v2/pals on every invocation. If createConversation is called multiple times for the same face (e.g., in a loop or for multiple sessions), a new pal is created each time. There's no caching of the created pal ID. This may be intentional (each conversation gets its own pal) or it may cause unnecessary API calls and pal proliferation. Worth confirming with the Tavus API's expected usage pattern.
Was this helpful? React with 👍 or 👎 to provide feedback.
Align the Tavus plugin with the new face/pal API, updating options and environment variables while maintaining deprecated aliases.
| let palId = | ||
| resolveRenamedOption(options.palId, options.personaId, 'personaId', 'palId') || | ||
| process.env.TAVUS_PAL_ID || | ||
| deprecatedEnv('TAVUS_PERSONA_ID', 'TAVUS_PAL_ID'); |
There was a problem hiding this comment.
🚩 Deprecated personaId values are now sent as pal_id on the wire
When a caller passes the deprecated personaId option, resolveRenamedOption at plugins/tavus/src/api.ts:128 maps it to palId, which is sent as pal_id on the wire (plugins/tavus/src/api.ts:138). The old code sent this same value as persona_id. If the Tavus API treats persona IDs and pal IDs as distinct namespaces, existing persona IDs passed via the deprecated option would fail on the new endpoint. This is likely correct if Tavus's API migration accepts old persona IDs as pal IDs, but it's worth confirming with the Tavus API documentation.
Was this helpful? React with 👍 or 👎 to provide feedback.
Previously the deprecation warning fired whenever a deprecated option was present, even if the new option was also given and took precedence. Warn only when the deprecated value is the one used. (addresses Devin review comment) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
3 participants
Description
Align the Tavus plugin with Tavus's renamed API (
replica→face,persona→pal). Public options, env vars, and the wire payload move to the new naming, with the old names kept as deprecated aliases (non-breaking for plugin users).Changes Made
faceId/palIdoptions (andTAVUS_FACE_ID/TAVUS_PAL_IDenv vars) toAvatarSessionandTavusAPI.createConversation.face_id/pal_idon the conversation-create payload; addcreatePal()hittingPOST /v2/pals(pal_name+default_face_id), and auto-create a pal (not a persona) when none is supplied.replicaId/personaIdoptions,TAVUS_REPLICA_ID/TAVUS_PERSONA_IDenv vars, andcreatePersona()(legacy/v2/personas) working as deprecated aliases with a warning.turbo.jsonenv-var declarations + changeset.Pre-Review Checklist
pnpm --filter @livekit/agents-plugin-tavus... build(incl.tsctypecheck),lint,prettier --check, andapi:checkpass locallyTesting
face_id/pal_idwire payload, deprecated args/env still work + warn, auto-create routes to/v2/palswithdefault_face_id, theTAVUS_FACE_ID-required error)restaurant_agent.ts/realtime_agent.ts— n/aAdditional 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. Verified the full new path end-to-end against staging.