feat: export global vendor types at top-level; add agora_agent.cn module

Global vendor classes now resolve to real types via the top-level TYPE_CHECKING
block, so `from agora_agent import DeepgramSTT` gives IDE autocomplete (was Any).
CN vendors get a dedicated `agora_agent.cn` module (natural names), which also
resolves the MicrosoftSTT/MicrosoftTTS/MiniMaxTTS collisions. SpatiusAvatar (CN) is
now cn-only; XaiGrok/GenericAvatar demoted to TYPE_CHECKING-only.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: plutoless

.fernignore

@@ -1,6 +1,7 @@
 # Specify files that shouldn't be modified by Fern
 src/agora_agent/pool_client.py
 src/agora_agent/__init__.py
+src/agora_agent/cn.py
 src/agora_agent/core/domain.py
 changelog.md
 

docs/guides/avatars.md

@@ -132,7 +132,8 @@ agent = (
 `SpatiusAvatar` is available for `Area.CN` sessions. Provide `spatius_api_key`, `spatius_app_id`, `spatius_avatar_id`, and `agora_uid` when constructing the avatar. `agora_token` is optional and is generated at session start when omitted, like SenseTime and Generic avatars.
 
 ```python
-from agora_agent import Agora, Area, CNAgent, GenericTTS, SpatiusAvatar, TencentSTT
+from agora_agent import Agora, Area, CNAgent, GenericTTS
+from agora_agent.cn import SpatiusAvatar, TencentSTT
 
 client = Agora(
     area=Area.CN,

src/agora_agent/__init__.py

@@ -20,12 +20,57 @@
         AgentSessionOptions,
         CNAgent,
         GlobalAgent,
-        GenericAvatar,
-        SpatiusAvatar,
         RegionalAgent,
-        XaiGrok,
         generate_rtc_token,
         GenerateTokenOptions,
+        # Global (non-CN) vendor classes — re-exported from agentkit for static typing so
+        # `from agora_agent import DeepgramSTT` autocompletes. Runtime resolution and
+        # `__all__` membership come from the `__getattr__` fallback + the `__all__` union
+        # below, so these need no `_dynamic_imports` / `_ROOT_ALL` entries.
+        # CN vendors are intentionally not here — import them from `agora_agent.cn`.
+        AkoolAvatar,
+        AmazonBedrock,
+        AmazonSTT,
+        AmazonTTS,
+        AnamAvatar,
+        Anthropic,
+        AresSTT,
+        AssemblyAISTT,
+        AzureOpenAI,
+        CartesiaTTS,
+        CustomLLM,
+        DeepgramSTT,
+        DeepgramTTS,
+        Dify,
+        ElevenLabsTTS,
+        FishAudioTTS,
+        Gemini,
+        GeminiLive,
+        GenericAvatar,
+        GenericTTS,
+        GoogleSTT,
+        GoogleTTS,
+        Groq,
+        HeyGenAvatar,
+        HumeAITTS,
+        LiveAvatarAvatar,
+        MicrosoftSTT,
+        MicrosoftTTS,
+        MiniMaxTTS,
+        MurfTTS,
+        OpenAI,
+        OpenAIRealtime,
+        OpenAISTT,
+        OpenAITTS,
+        RimeTTS,
+        SarvamSTT,
+        SarvamTTS,
+        SpeechmaticsSTT,
+        VertexAI,
+        VertexAILLM,
+        XaiGrok,
+        XaiSTT,
+        XaiTTS,
     )
     from .agentkit.agent_session import AsyncAgentSession
 
@@ -39,9 +84,6 @@
     "AsyncAgentSession": ".agentkit.agent_session",
     "AsyncAgora": ".pool_client",
     "AsyncAgentClient": ".pool_client",
-    "GenericAvatar": ".agentkit",
-    "SpatiusAvatar": ".agentkit",
-    "XaiGrok": ".agentkit",
     "GenerateTokenOptions": ".agentkit",
     "__version__": ".version",
     "agentkit": ".agentkit",
@@ -63,9 +105,6 @@
     "AsyncAgentSession",
     "AsyncAgora",
     "AsyncAgentClient",
-    "GenericAvatar",
-    "SpatiusAvatar",
-    "XaiGrok",
     "GenerateTokenOptions",
     "Pool",
     "__version__",

src/agora_agent/cn.py

@@ -0,0 +1,60 @@
+# isort: skip_file
+"""China (CN) vendor classes for the Agora Conversational AI SDK.
+
+Import CN vendors explicitly from this module so they stay separate from the global
+top-level namespace::
+
+    from agora_agent.cn import AliyunLLM, MiniMaxTTS, TencentSTT
+
+``MicrosoftSTT`` / ``MicrosoftTTS`` / ``MiniMaxTTS`` here are the CN variants; the
+global variants of those names are available from the top-level package
+(e.g. ``from agora_agent import MiniMaxTTS``).
+"""
+
+from .agentkit.vendors.cn import (
+    AliyunLLM,
+    BytedanceDuplexTTS,
+    BytedanceLLM,
+    BytedanceTTS,
+    CosyVoiceTTS,
+    DeepSeekLLM,
+    FengmingSTT,
+    MicrosoftSTT,
+    MicrosoftTTS,
+    MiniMaxTTS,
+    SenseTimeAvatar,
+    SpatiusAvatar,
+    StepFunTTS,
+    TencentLLM,
+    TencentSTT,
+    TencentTTS,
+    XfyunBigModelSTT,
+    XfyunDialectSTT,
+    XfyunSTT,
+)
+
+__all__ = [
+    # STT
+    "FengmingSTT",
+    "MicrosoftSTT",
+    "TencentSTT",
+    "XfyunBigModelSTT",
+    "XfyunDialectSTT",
+    "XfyunSTT",
+    # TTS
+    "BytedanceDuplexTTS",
+    "BytedanceTTS",
+    "CosyVoiceTTS",
+    "MicrosoftTTS",
+    "MiniMaxTTS",
+    "StepFunTTS",
+    "TencentTTS",
+    # LLM
+    "AliyunLLM",
+    "BytedanceLLM",
+    "DeepSeekLLM",
+    "TencentLLM",
+    # Avatar
+    "SenseTimeAvatar",
+    "SpatiusAvatar",
+]

tests/custom/test_llm_vendors.py

@@ -128,28 +128,30 @@ def test_dify_serializes_conversation_fields() -> None:
 
 
 def test_llm_vendors_reject_missing_required_models() -> None:
+    # These intentionally omit the required `model` to assert it raises; the top-level
+    # vendor types are now real, so mypy needs the call-arg ignores.
     with pytest.raises(Exception, match="model"):
-        OpenAI(api_key="openai-key", base_url="https://api.openai.com/v1/chat/completions")
+        OpenAI(api_key="openai-key", base_url="https://api.openai.com/v1/chat/completions")  # type: ignore[call-arg]
 
     with pytest.raises(Exception, match="model"):
-        Anthropic(
+        Anthropic(  # type: ignore[call-arg]
             api_key="anthropic-key",
             url="https://api.anthropic.com/v1/messages",
             headers={"anthropic-version": "2023-06-01"},
             max_tokens=1024,
         )
 
     with pytest.raises(Exception, match="model"):
-        Gemini(api_key="google-key")
+        Gemini(api_key="google-key")  # type: ignore[call-arg]
 
     with pytest.raises(Exception, match="model"):
-        Groq(api_key="groq-key", base_url="https://api.groq.com/openai/v1/chat/completions")
+        Groq(api_key="groq-key", base_url="https://api.groq.com/openai/v1/chat/completions")  # type: ignore[call-arg]
 
     with pytest.raises(Exception, match="model"):
-        VertexAILLM(api_key="vertex-token", project_id="project", location="us-central1")
+        VertexAILLM(api_key="vertex-token", project_id="project", location="us-central1")  # type: ignore[call-arg]
 
     with pytest.raises(Exception, match="model"):
-        AmazonBedrock(access_key="aws-access", secret_key="aws-secret", region="us-east-1")
+        AmazonBedrock(access_key="aws-access", secret_key="aws-secret", region="us-east-1")  # type: ignore[call-arg]
 
 
 def test_openai_managed_mode_is_restricted_to_supported_models() -> None: