feat: make pyaudio an optional dependency by lazy loading (#1731)

Author: mehtarac

README.md

@@ -208,6 +208,16 @@ Build real-time voice and audio conversations with persistent streaming connecti
 - Google Gemini Live
 - OpenAI Realtime API
 
+**Installation:**
+
+```bash
+# Server-side only (no audio I/O dependencies)
+pip install strands-agents[bidi]
+
+# With audio I/O support (includes PyAudio dependency)
+pip install strands-agents[bidi,bidi-io]
+```
+
 **Quick Example:**
 
 ```python
@@ -223,7 +233,7 @@ async def main():
     model = BidiNovaSonicModel()
     agent = BidiAgent(model=model, tools=[calculator, stop_conversation])
 
-    # Setup audio and text I/O
+    # Setup audio and text I/O (requires bidi-io extra)
     audio_io = BidiAudioIO()
     text_io = BidiTextIO()
 
@@ -238,6 +248,8 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+> **Note**: `BidiAudioIO` and `BidiTextIO` require the `bidi-io` extra. For server-side deployments where audio I/O is handled by clients (browsers, mobile apps), install only `strands-agents[bidi]` and implement custom input/output handlers using the `BidiInput` and `BidiOutput` protocols.
+
 **Configuration Options:**
 
 ```python

pyproject.toml

@@ -73,15 +73,17 @@ a2a = [
 
 bidi = [
     "aws_sdk_bedrock_runtime; python_version>='3.12'",
+    "smithy-aws-core>=0.0.1; python_version>='3.12'",
+]
+bidi-io = [
     "prompt_toolkit>=3.0.0,<4.0.0",
     "pyaudio>=0.2.13,<1.0.0",
-    "smithy-aws-core>=0.0.1; python_version>='3.12'",
 ]
 bidi-gemini = ["google-genai>=1.32.0,<2.0.0"]
 bidi-openai = ["websockets>=15.0.0,<17.0.0"]
 
 all = ["strands-agents[a2a,anthropic,docs,gemini,litellm,llamaapi,mistral,ollama,openai,writer,sagemaker,otel]"]
-bidi-all = ["strands-agents[a2a,bidi,bidi-gemini,bidi-openai,docs,otel]"]
+bidi-all = ["strands-agents[a2a,bidi,bidi-io,bidi-gemini,bidi-openai,docs,otel]"]
 
 dev = [
     "commitizen>=4.4.0,<5.0.0",

src/strands/experimental/bidi/__init__.py

@@ -1,5 +1,7 @@
 """Bidirectional streaming package."""
 
+from typing import Any
+
 # Main components - Primary user interface
 # Re-export standard agent events for tool handling
 from ...types._events import (
@@ -9,9 +11,6 @@
 )
 from .agent.agent import BidiAgent
 
-# IO channels - Hardware abstraction
-from .io.audio import BidiAudioIO
-
 # Model interface (for custom implementations)
 from .models.model import BidiModel
 
@@ -40,8 +39,6 @@
 __all__ = [
     # Main interface
     "BidiAgent",
-    # IO channels
-    "BidiAudioIO",
     # Built-in tools
     "stop_conversation",
     # Input Event types
@@ -68,3 +65,19 @@
     # Model interface
     "BidiModel",
 ]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy load IO implementations only when accessed.
+
+    This defers the import of optional dependencies until actually needed.
+    """
+    if name == "BidiAudioIO":
+        from .io.audio import BidiAudioIO
+
+        return BidiAudioIO
+    if name == "BidiTextIO":
+        from .io.text import BidiTextIO
+
+        return BidiTextIO
+    raise AttributeError(f"cannot import name '{name}' from '{__name__}' ({__file__})")