anam 0.0.1a1__tar.gz

anam-0.0.1a1/.gitignore

@@ -0,0 +1,21 @@
+# Python
+.conda*
+poetry.lock
+__pycache__
+
+# Apple
+.DS_Store
+
+# Environments
+.env.*
+.env
+
+# Code in non-ready-state
+anam_python_sdk/scratch/*
+anam_python_sdk/scratch
+
+# Builds
+/dist*
+
+# Example outputs
+recordings/

anam-0.0.1a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024–2026, Anam AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

anam-0.0.1a1/PKG-INFO

@@ -0,0 +1,357 @@
+Metadata-Version: 2.4
+Name: anam
+Version: 0.0.1a1
+Summary: Official Python SDK for Anam AI - Real-time AI avatar streaming
+Project-URL: Homepage, https://www.anam.ai
+Project-URL: Documentation, https://docs.anam.ai
+Project-URL: Repository, https://github.com/anam-org/python-sdk
+Project-URL: Issues, https://github.com/anam-org/python-sdk/issues
+Author-email: Anam AI <support@anam.ai>
+License: MIT
+License-File: LICENSE
+Keywords: ai,anam,avatar,real-time,streaming,webrtc
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: aiortc>=1.14.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: display
+Requires-Dist: opencv-python>=4.9.0; extra == 'display'
+Requires-Dist: sounddevice>=0.4.6; extra == 'display'
+Description-Content-Type: text/markdown
+
+# Anam AI Python SDK
+
+Official Python SDK for [Anam AI](https://anam.ai) - Real-time AI avatar streaming.
+
+[![PyPI version](https://badge.fury.io/py/anam-ai.svg)](https://badge.fury.io/py/anam-ai)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv add anam-ai
+
+# With optional display utilities (for testing)
+uv add anam-ai --extra display
+
+# Using pip
+pip install anam-ai
+
+# With optional display utilities (for testing)
+pip install anam-ai[display]
+```
+
+## Quick Start
+
+```python
+import asyncio
+from anam import AnamClient
+from av.video.frame import VideoFrame
+from av.audio.frame import AudioFrame
+
+async def main():
+    # Create client with your API key and persona
+    client = AnamClient(
+        api_key="your-api-key",
+        persona_id="your-persona-id",
+    )
+
+    # Connect and stream
+    async with client.connect() as session:
+        print(f"Connected! Session: {session.session_id}")
+        
+        # Consume video and audio frames concurrently
+        async def consume_video():
+            async for frame in session.video_frames():
+                img = frame.to_ndarray(format="rgb24")  # numpy array (H, W, 3) in RGB format - use "bgr24" for OpenCV
+                print(f"Video: {frame.width}x{frame.height}")
+        
+        async def consume_audio():
+            async for frame in session.audio_frames():
+                samples = frame.to_ndarray()  # int16 samples (1D array, interleaved for stereo)
+                # Determine mono/stereo from frame layout
+                channel_type = "mono" if frame.layout.nb_channels == 1 else "stereo"
+                print(f"Audio: {samples.size} samples ({channel_type}) @ {frame.sample_rate}Hz")
+        
+        # Run both streams concurrently until session closes
+        await asyncio.gather(
+            consume_video(),
+            consume_audio(),
+        )
+
+asyncio.run(main())
+```
+
+## Features
+
+- 🎥 **Real-time Audio/Video streaming** - Receive synchronized audio/video frames from the avatar (as PyAV AudioFrame/VideoFrame objects)
+- 💬 **Two-way communication** - Send text messages (like transcribed user speech) and receive generated responses
+- 🎤 **Audio-passthrough** - Send TTS generated audio input and receive rendered synchronized audio/video avatar
+- 🗣️ **Direct text-to-speech** - Send text directly to TTS for immediate speech output (bypasses LLM processing)
+- 🎯 **Async iterator API** - Clean, Pythonic async/await patterns for continuous stream of audio/video frames
+- 🎯 **Event-driven API** - Simple decorator-based event handlers for discrete events
+- 📝 **Fully typed** - Complete type hints for IDE support
+- 🔒 **Server-side ready** - Designed for server-side Python applications (e.g. for use in a web application)
+
+## API Reference
+
+### AnamClient
+
+The main client class for connecting to Anam AI.
+
+```python
+from anam import AnamClient, PersonaConfig, ClientOptions
+
+# Simple initialization
+client = AnamClient(
+    api_key="your-api-key",
+    persona_id="your-persona-id",
+)
+
+# Advanced initialization with full persona config
+client = AnamClient(
+    api_key="your-api-key",
+    persona_config=PersonaConfig(
+        persona_id="your-persona-id",
+        name="My Assistant",
+        system_prompt="You are a helpful assistant...",
+        voice_id="emma",
+        language_code="en",
+    ),
+    options=ClientOptions(
+        disable_input_audio=True,  # Don't capture microphone
+    ),
+)
+```
+
+### Video and Audio Frames
+
+Frames are **PyAV objects** (VideoFrame/AudioFrame) containing synchronized **decoded audio (PCM) and video (RGB) samples** from the avatar, delivered over WebRTC and extracted by aiortc. All PyAV frame attributes are accessible (samples, format, layout, etc.). Access the frames via **async iterators** and **run both iterators concurrently**, e.g. using `asyncio.gather()`:
+
+```python
+async with client.connect() as session:
+    async def process_video():
+        async for frame in session.video_frames():
+            img = frame.to_ndarray(format="rgb24")  # RGB numpy array
+            # Process frame...
+    
+    async def process_audio():
+        async for frame in session.audio_frames():
+            samples = frame.to_ndarray()  # int16 samples
+            # Process frame...
+    
+    # Both streams run concurrently
+    await asyncio.gather(process_video(), process_audio())
+```
+
+### Events
+
+Register callbacks for connection and message events using the `@client.on()` decorator:
+
+```python
+from anam import AnamEvent
+
+@client.on(AnamEvent.MESSAGE_RECEIVED)
+async def on_message(message: Message):
+    """Called when a chat message is received."""
+    print(f"{message.role}: {message.content}")
+
+@client.on(AnamEvent.CONNECTION_ESTABLISHED)
+async def on_connected():
+    """Called when the connection is established."""
+    pass
+
+@client.on(AnamEvent.CONNECTION_CLOSED)
+async def on_closed(code: str, reason: str | None):
+    """Called when the connection is closed."""
+    pass
+```
+
+### Session
+
+The `Session` object is returned by `client.connect()` and provides methods for interacting with the avatar:
+
+```python
+async with client.connect() as session:
+    # Send a text message (simulates user speech)
+    await session.send_message("Hello, how are you?")
+    
+    # Interrupt the avatar if speaking
+    await session.interrupt()
+    
+    # Wait until the session ends
+    await session.wait_until_closed()
+```
+
+
+
+## Examples
+
+### Save Video and Audio
+
+```python
+import cv2
+import wave
+import asyncio
+from anam import AnamClient
+
+client = AnamClient(api_key="...", persona_id="...")
+
+video_writer = cv2.VideoWriter("output.mp4", ...)
+audio_writer = wave.open("output.wav", "wb")
+
+async def save_video(session):
+    async for frame in session.video_frames():
+        # Read frame as BGR for OpenCV VideoWriter
+        bgr_frame = frame.to_ndarray(format="bgr24")
+        video_writer.write(bgr_frame)
+
+async def save_audio(session):
+    async for frame in session.audio_frames():
+        # Initialize writer on first frame
+        if audio_writer.getnframes() == 0:
+            audio_writer.setnchannels(frame.layout.nb_channels)
+            audio_writer.setsampwidth(2)  # 16-bit
+            audio_writer.setframerate(frame.sample_rate)
+        # Write audio data (convert to int16 and get bytes)
+        audio_writer.writeframes(frame.to_ndarray().tobytes())
+
+async with client.connect() as session:
+    # Record for 30 seconds
+    await asyncio.wait_for(
+        asyncio.gather(save_video(session), save_audio(session)),
+        timeout=30.0,
+    )
+```
+
+### Display Video with OpenCV
+
+```python
+import cv2
+import asyncio
+from anam import AnamClient
+
+client = AnamClient(api_key="...", persona_id="...")
+latest_frame = None
+
+async def update_frame(session):
+    global latest_frame
+    async for frame in session.video_frames():
+        # Read frame as BGR for OpenCV display
+        latest_frame = frame.to_ndarray(format="bgr24")
+
+async def main():
+    async with client.connect() as session:
+        # Start frame consumer
+        frame_task = asyncio.create_task(update_frame(session))
+        
+        # Display loop
+        while True:
+            if latest_frame is not None:
+                cv2.imshow("Avatar", latest_frame)
+            if cv2.waitKey(1) & 0xFF == ord('q'):
+                break
+        frame_task.cancel()
+
+asyncio.run(main())
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+export ANAM_API_KEY="your-api-key"
+export ANAM_PERSONA_ID="your-persona-id"
+```
+
+### Client Options
+
+```python
+from anam import ClientOptions
+
+options = ClientOptions(
+    api_base_url="https://api.anam.ai",  # API base URL
+    api_version="v1",                     # API version
+    disable_input_audio=False,            # Disable microphone input
+    ice_servers=None,                     # Custom ICE servers
+)
+```
+
+### Persona Configuration
+
+```python
+from anam import PersonaConfig
+
+persona = PersonaConfig(
+    persona_id="your-persona-id",    # Required
+    name="Assistant",                 # Display name
+    avatar_id="anna_v2",             # Avatar to use
+    voice_id="emma",                 # Voice to use
+    system_prompt="You are...",      # Custom system prompt
+    language_code="en",              # Language code
+    llm_id="gpt-4",                  # LLM model
+    max_session_length_seconds=300,  # Max session duration
+)
+```
+
+## Error Handling
+
+```python
+from anam import AnamError, AuthenticationError, SessionError
+
+try:
+    async with client.connect() as session:
+        await session.wait_until_closed()
+except AuthenticationError as e:
+    print(f"Invalid API key: {e}")
+except SessionError as e:
+    print(f"Session error: {e}")
+except AnamError as e:
+    print(f"Anam error [{e.code}]: {e.message}")
+```
+
+## Requirements
+
+- Python 3.10+
+- Dependencies are installed automatically:
+  - `aiortc` - WebRTC implementation
+  - `aiohttp` - HTTP client
+  - `websockets` - WebSocket client
+  - `numpy` - Array handling
+
+Optional for display utilities:
+- `opencv-python` - Video display
+- `sounddevice` - Audio playback
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- [Anam AI Website](https://anam.ai)
+- [Documentation](https://docs.anam.ai)
+- [API Reference](https://docs.anam.ai/api-reference)