feat(anam): forward output video dimensions via SessionOptions

[Smidge]

Closes #5954

What

Adds an optional anam.SessionOptions(video_width, video_height) that the Anam avatar plugin forwards into Anam's session-token request as sessionOptions.videoWidth / videoHeight. The avatar video then publishes at the Anam-resolved output size.

session = anam.AvatarSession(
    persona_config=anam.PersonaConfig(name="avatar", avatarId=ANAM_AVATAR_ID),
    session_options=anam.SessionOptions(video_width=1152, video_height=768),
)

Why

Anam's public session-token API now accepts explicit pixel output dimensions. This lets Agents users choose the avatar's output size without any provider-specific dimensions API.

Design

• Pixels only, both-or-neither — no portrait/landscape strings.
• Validation lives in Anam, not the plugin. The plugin is a thin pass-through and doesn't know the per-model allow-list; Anam validates the requested pair against the avatar model and returns HTTP 400 for an unsupported (or half) pair, which the plugin already surfaces as APIStatusError with Anam's descriptive message. No silent downgrade.
• Mirrors livekit-plugins-avatario (VideoInfo(video_width, video_height)). I named it SessionOptions to match Anam's own sessionOptions API field and leave room for future session-level options — happy to switch to a nested AvatarSession.VideoInfo if you'd prefer consistency with Avatario.
• Backward compatible: session_options is optional (NOT_GIVEN); when omitted the request body is identical to today and Anam applies the avatar model's default. No behaviour change for existing users.

Scope

5 files — types.py (new SessionOptions dataclass), avatar.py + api.py (thread through + emit camelCase), __init__.py (export), and the anam example. No new dependencies; no change to the LiveKit token / start_engine_session / wait_remote_track flow. ruff format + ruff check clean. Left version.py/changelog to the release bot per CONTRIBUTING.

Happy to add unit tests for the payload construction in whatever harness you prefer.

[CLAassistant]

All committers have signed the CLA.

[longcw]

this doesn't match the comment above "Send both or neither"?

[Smidge]

Good catch, you're right. It builds video_options from whichever field is non-None, so a lone video_width/video_height still goes out as exactly the half pair the comment says Anam rejects.

Fixing it to send both or neither, and to fail fast locally on a half pair rather than round-tripping a 400:

if session_options is not None and (
    session_options.video_width is not None
    or session_options.video_height is not None
):
    if session_options.video_width is None or session_options.video_height is None:
        raise ValueError(
            "video_width and video_height must be set together (both or neither)"
        )
    payload["sessionOptions"] = {
        "videoWidth": session_options.video_width,
        "videoHeight": session_options.video_height,
    }

Thanks for the review!

[Smidge]

Fixed in 73adbbc — sessionOptions now only goes out when both dimensions are present, and raises a ValueError on a lone width/height so it fails fast locally instead of round-tripping a 400.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 3 additional findings.