Skip to main content

Python SDK

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

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​