Add Hedra Avatar Plugin

[toubatbrian]

Plugin has been fully tested with both using avatar_id mode and uploading image mode.

Summary by CodeRabbit

Release Notes

• New Features

  • Added Hedra avatar plugin for LiveKit agents, enabling avatar-driven agent workflows with voice interaction capabilities.
  • Included example integration demonstrating complete Hedra avatar setup with session management and metrics collection.

• Documentation

  • Added comprehensive plugin documentation with installation, configuration, and usage examples.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 7779d32

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 18 packages

Name	Type
@livekit/agents-plugin-hedra	Patch
@livekit/agents	Patch
@livekit/agents-plugin-anam	Patch
@livekit/agents-plugin-baseten	Patch
@livekit/agents-plugin-bey	Patch
@livekit/agents-plugin-cartesia	Patch
@livekit/agents-plugin-deepgram	Patch
@livekit/agents-plugin-elevenlabs	Patch
@livekit/agents-plugin-google	Patch
@livekit/agents-plugin-inworld	Patch
@livekit/agents-plugin-livekit	Patch
@livekit/agents-plugin-neuphonic	Patch
@livekit/agents-plugin-openai	Patch
@livekit/agents-plugin-resemble	Patch
@livekit/agents-plugin-rime	Patch
@livekit/agents-plugin-silero	Patch
@livekit/agents-plugin-xai	Patch
@livekit/agents-plugins-test	Patch

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

[davidzhao]

@codex review

[davidzhao]

lg, just a couple of nits

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Nice work!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

A new Hedra avatar plugin is introduced for LiveKit agents, featuring core implementation with avatar session management, API integration with retry logic, complete package configuration, documentation, and example usage demonstrating integration across the agent framework.

Changes

Cohort / File(s)	Summary
Plugin Core Implementation plugins/hedra/src/avatar.ts, plugins/hedra/src/index.ts, plugins/hedra/src/log.ts, plugins/hedra/src/version.ts	Introduces HedraException, AvatarImage, AvatarSessionOptions, and AvatarSession class with start() method for orchestrating Hedra avatar sessions. Includes API token generation, multipart FormData request handling, retry logic with exponential backoff, and audio streaming configuration. Registers HedraPlugin and re-exports public members.
Plugin Configuration & Build plugins/hedra/package.json, plugins/hedra/tsconfig.json, plugins/hedra/tsup.config.ts, plugins/hedra/api-extractor.json	Establishes package metadata, TypeScript configuration with dist output, build tooling via tsup, and API declaration extraction.
Plugin Documentation plugins/hedra/README.md	Provides installation, prerequisites, usage patterns, configuration reference for AvatarSession and AvatarImage, and complete agent integration example.
Example Integration examples/src/hedra/hedra_avatar.ts, examples/package.json	Demonstrates complete avatar-driven agent workflow with prewarm VAD loading, voice agent setup (Deepgram STT, OpenAI LLM, Sonic-3 TTS), AvatarSession initialization, metrics collection, and initial greeting.
Release & Configuration .changeset/hip-brooms-stand.md, REUSE.toml, turbo.json	Adds changeset for patch release, copyright/license annotations for image and README assets, and three new global environment variables (HEDRA_API_KEY, HEDRA_API_URL, HEDRA_AVATAR_ID).

Sequence Diagram(s)

sequenceDiagram
    actor Agent as Agent/User
    participant AvatarSession as AvatarSession
    participant LiveKit as LiveKit<br/>(Access Token)
    participant HedraAPI as Hedra API
    participant AudioOutput as Audio Output<br/>Stream

    Agent->>AvatarSession: start(agentSession, room, options)
    AvatarSession->>LiveKit: create AccessToken<br/>(avatar identity, room, publish-on-behalf)
    LiveKit-->>AvatarSession: token
    AvatarSession->>HedraAPI: POST /agents/start<br/>(multipart: livekit_url, livekit_token, avatar_id/image)
    alt Retry Loop
        HedraAPI-->>AvatarSession: error or timeout
        AvatarSession->>AvatarSession: wait exponential backoff
        AvatarSession->>HedraAPI: retry POST request
    end
    HedraAPI-->>AvatarSession: success
    AvatarSession->>AudioOutput: configure DataStreamAudioOutput<br/>(sample_rate, waitRemoteTrack)
    AvatarSession->>agentSession: route audio to avatar
    agentSession-->>Agent: avatar active

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐰 A hedra-born avatar hops into place,
With plugins, tokens, and API grace,
From prewarm VAD to streaming delight,
The agents dance through morning light! ✨

✨ Finishing touches

• 📝 Generate docstrings

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0bf2a8e and 7779d32.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (14)

• .changeset/hip-brooms-stand.md
• REUSE.toml
• examples/package.json
• examples/src/hedra/hedra_avatar.ts
• plugins/hedra/README.md
• plugins/hedra/api-extractor.json
• plugins/hedra/package.json
• plugins/hedra/src/avatar.ts
• plugins/hedra/src/index.ts
• plugins/hedra/src/log.ts
• plugins/hedra/src/version.ts
• plugins/hedra/tsconfig.json
• plugins/hedra/tsup.config.ts
• turbo.json

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}