Improve docs

[sebvanleuven]

Improving the explanation of avatar types, and prioritizing the examples with avatar_id.
Generat improvements to options and pipeline behaviour.

---

Summary by cubic

Improved docs and examples to favor avatar_id-based ephemeral personas, clarified orchestration (Anam vs custom passthrough) and LLM options, and tightened guidance on talk vs talk_stream latency and streaming suitability.

• Docs and Examples

  • README: clarified persona types (pre-defined vs ephemeral), orchestration (STT → LLM → TTS → Avatar), and audio passthrough with explicit end_sequence; added LLM options including CUSTOMER_CLIENT_V1; noted not to use persona_id as avatar_id; updated WebRTC wording.
  • Examples: persona_interactive_video uses avatar_id + voice_id + llm_id (+ avatar_model), disables passthrough, removes audio file ingest, and requires ANAM_AVATAR_ID/ANAM_VOICE_ID/ANAM_LLM_ID; audio passthrough example adds interrupt support and warns not to use persona_id.
  • SDK: docstrings clarify talk() is not for streaming and is higher latency vs send_talk_stream(); improved PersonaConfig docs.
  • Version: uv.lock bumped to anam 0.2.0a2.

• Migration

  • Env vars: use ANAM_AVATAR_ID, ANAM_VOICE_ID, ANAM_LLM_ID (optional ANAM_AVATAR_MODEL).
  • Ephemeral personas: set avatar_id, voice_id, llm_id; do not set persona_id.
  • Pre-defined personas: use persona_id only; other config ignored except enable_audio_passthrough.
  • Audio passthrough: provide sample_rate/channels and call end_sequence when TTS finishes.
  • Streaming: use send_talk_stream for continuous text; use talk() for one-shot speech.

^{Written for commit 95de175. Summary will update on new commits.}

[cubic-dev-ai]

4 issues found across 6 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="examples/persona_interactive_video.py">

<violation number="1" location="examples/persona_interactive_video.py:46">
P2: ANAM_LLM_ID is documented as optional, but the new REQUIRED_ENV_VARS check makes it mandatory and raises before main runs. This prevents running the example with default LLMs.</violation>
</file>

<file name="src/anam/client.py">

<violation number="1" location="src/anam/client.py:547">
P3: Fix the spelling in this docstring to avoid user-facing typos ("whith continous" → "with continuous").</violation>
</file>

<file name="src/anam/types.py">

<violation number="1" location="src/anam/types.py:53">
P3: This docstring now claims all other parameters are ignored for persona_id, but README states enable_audio_passthrough is still respected. Update the wording to include the exception so users aren’t misled.</violation>
</file>

<file name="examples/avatar_audio_passthrough.py">

<violation number="1" location="examples/avatar_audio_passthrough.py:198">
P1: avatar_id is being passed as persona_id. According to the SDK docs, avatar_id must be configured via PersonaConfig (ephemeral persona); using persona_id here treats it as a pre-defined persona and bypasses the intended avatar configuration.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 4 files (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="src/anam/client.py">

<violation number="1" location="src/anam/client.py:547">
P3: Fix the typo in the docstring: "continous" → "continuous".</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}