Skip to main content

Python SDK

Build real-time conversational AI applications in Python with speech-to-text, text-to-speech, and LLM capabilities.

Limited Capabilities

This SDK does not include full capabilities such as VAD (Voice Activity Detection), Audio Player, or Audio Recorder. For these features, please use our JavaScript SDK or Unity SDK.

PyPI version Python 3.12+

Installation​

pip install ug-python-sdk

Or using Poetry:

poetry add ug-python-sdk

Requirements: Python 3.12 or higher

Quick Start​

Here's a simple example that creates a conversation and sends a text message:

import asyncio
from ug_python_sdk import Client

async def main():
    # Initialize the client
    client = Client()

    # Authenticate with your API key
    await client.authenticate(api_key="your-api-key")

    # Start a conversation session
    async with client.session() as session:
        # Configure the AI assistant
        await session.set_configuration(
            prompt="You are a helpful assistant.",
            temperature=0.7
        )

        # Send a message and stream responses
        async for event in session.interact(text="Hello! How are you?"):
            if event.type == "text":
                print(f"Assistant: {event.text}")
            elif event.type == "completed":
                print("Interaction complete")

asyncio.run(main())

Authentication Options​

API Key Authentication​

# Basic API key authentication
await client.authenticate(api_key="your-api-key")

# With team context
await client.authenticate(
    api_key="your-api-key",
    team_id="team-123"
)

# For a specific player
await client.authenticate(
    api_key="your-api-key",
    player_id="player-456"
)

Google OAuth​

# Opens browser for Google login
await client.google_authenticate()

Session Configuration​

Configure the AI assistant's behavior:

await session.set_configuration(
    prompt="You are a friendly assistant who helps with coding questions.",
    temperature=0.7,
    audio_output=True,
    voice_profile={
        "provider": "elevenlabs",
        "voice_id": "your-voice-id",
        "speed": 1.0,
        "stability": 0.5,
        "similarity_boost": 0.75
    }
)

Voice Providers​

ElevenLabs:

voice_profile = {
    "provider": "elevenlabs",
    "voice_id": "voice-id",
    "speed": 1.0,
    "stability": 0.5,
    "similarity_boost": 0.75
}

Deepdub:

voice_profile = {
    "provider": "deepdub",
    "voice_id": "voice-id",
    "locale": "en-US",
    "tempo": 1.0,
    "variance": 0.5,
    "accent_blending": 0.3
}

Real-time Streaming​

Stream text and audio responses with event handling:

async for event in session.interact(text="Tell me a story"):
    match event.type:
        case "text":
            print(event.text, end="", flush=True)
        case "audio":
            # Handle audio data
            audio_chunk = event.data
        case "data":
            # Handle utility results
            print(f"Data: {event.data}")
        case "completed":
            print("\nDone!")

Audio Input (Speech-to-Text)​

Process audio input for transcription:

# Add audio data
await session.add_audio(
    audio_data=audio_bytes,
    mime_type="audio/wav",
    sample_rate=16000
)

# Transcribe the audio
transcript = await session.transcribe(language="en")
print(f"Transcription: {transcript}")

Utilities​

Add structured outputs with classification or extraction utilities:

Classification​

await session.set_configuration(
    prompt="You are a sentiment analysis assistant.",
    utilities={
        "sentiment": {
            "type": "classify",
            "classification_question": "What is the sentiment: {{user_input}}",
            "answers": ["positive", "negative", "neutral"]
        }
    },
    on_output_utilities=["sentiment"]
)

async for event in session.interact(text="I love this product!"):
    if event.type == "data":
        print(f"Sentiment: {event.data['sentiment']}")

Extraction​

await session.set_configuration(
    prompt="You are a helpful assistant.",
    utilities={
        "key_points": {
            "type": "extract",
            "extract_prompt": "Extract the main points from: {{assistant_output}}"
        }
    },
    on_output_utilities=["key_points"]
)

Player Management​

Manage players programmatically:

# List all players
players = await client.list_players()

# Create a new player
player = await client.create_player(
    external_id="user-123",
    metadata={"name": "John"}
)

# Get a player
player = await client.get_player(player_id="player-id")

# Delete a player
await client.delete_player(player_id="player-id")

Complete Example​

Here's a full conversational AI example:

import asyncio
from ug_python_sdk import Client

async def chat():
    client = Client()
    await client.authenticate(api_key="your-api-key")

    async with client.session() as session:
        await session.set_configuration(
            prompt="""You are a helpful AI assistant.
            Be concise and friendly in your responses.""",
            temperature=0.7,
            audio_output=False
        )

        print("Chat started! Type 'quit' to exit.\n")

        while True:
            user_input = input("You: ")
            if user_input.lower() == 'quit':
                break

            print("Assistant: ", end="")
            async for event in session.interact(text=user_input):
                if event.type == "text":
                    print(event.text, end="", flush=True)
            print("\n")

if __name__ == "__main__":
    asyncio.run(chat())

Resources​

Next Steps​