player2py 0.1.1
Python client for the Player2 API - AI powered gaming tools
License: MIT
Requires Python: >=3.7
Keywords: player2, ai, gaming, speech, text-to-speech, speech-to-text, chat

# Player2 Python Client

A Python client for the Player2 API - AI powered gaming tools.

## Installation

```bash
pip install player2
```

## Prerequisites

1. Download and run the latest version of the Player2 App at https://player2.game
2. Make sure the Player2 App is running and accessible at http://localhost:4315
3. Ensure you are authenticated in the Player2 App

## Quick Start

```python
from player2 import Player2Client

# Initialize the client
client = Player2Client(game_name="my-awesome-game")

# Check if the server is healthy
health = client.health()
print(f"Player2 version: {health.client_version}")

# Get selected characters
characters = client.get_selected_characters()
for character in characters.characters:
    print(f"Character: {character.name} - {character.description}")

# Create a chat completion
response = client.chat_completions(
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello, how are you?"}
    ]
)
print(f"Response: {response.choices[0].message.content}")

# Text to speech
client.tts_speak(
    text="Hello, this is a test message!",
    voice_ids=["01955d76-ed5b-73e0-a88d-cbeb3c5b499d"],
    play_in_app=True
)
```

## Features

- **Characters API**: Get selected characters from the Player2 App
- **Chat API**: Create chat completions following OpenAI API format
- **Speech to Text (STT)**: Start/stop speech recognition and get recognized text
- **Text to Speech (TTS)**: Convert text to speech with various voices
- **System API**: Health checks and system information

## API Reference

### Client Initialization

```python
from player2 import Player2Client

client = Player2Client(
    base_url="http://localhost:4315",  # Default
    game_name="your-game-name",        # Required for tracking
    timeout=30                         # Request timeout in seconds
)
```

### Characters API

```python
# Get selected characters
characters = client.get_selected_characters()
```

### Chat API

```python
# Create chat completion
response = client.chat_completions(
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ]
)
```

### Speech to Text (STT)

```python
# Start speech recognition
client.stt_start(timeout=30)

# Stop speech recognition and get text
result = client.stt_stop()
print(f"Recognized text: {result.text}")

# Get available languages
languages = client.stt_languages()

# Get current language
current_lang = client.stt_get_language()

# Set language
client.stt_set_language(code="en-US")
```

### Text to Speech (TTS)

```python
# Get available voices
voices = client.tts_voices()

# Speak text
client.tts_speak(
    text="Hello, world!",
    voice_ids=["voice-id-1", "voice-id-2"],
    play_in_app=True,
    speed=1.0,
    voice_gender="female",
    voice_language="en_US",
    audio_format="mp3"
)

# Stop speaking
client.tts_stop()

# Get current volume
volume = client.tts_get_volume()

# Set volume (0.0 to 1.0)
client.tts_set_volume(volume=0.7)
```

### System API

```python
# Check health
health = client.health()
print(f"Client version: {health.client_version}")
```

## Error Handling

The client raises specific exceptions for different error scenarios:

```python
from player2 import Player2Error, Player2AuthError, Player2RateLimitError

try:
    response = client.chat_completions(messages=[...])
except Player2AuthError:
    print("Authentication required - please log in to Player2 App")
except Player2RateLimitError:
    print("Rate limit exceeded - please wait before making more requests")
except Player2Error as e:
    print(f"Player2 API error: {e}")
```

## Examples

### Simple Chat Bot

```python
from player2 import Player2Client

client = Player2Client(game_name="chat-bot")

def chat_bot():
    while True:
        user_input = input("You: ")
        if user_input.lower() == "quit":
            break
            
        response = client.chat_completions(
            messages=[
                {"role": "system", "content": "You are a friendly chatbot."},
                {"role": "user", "content": user_input}
            ]
        )
        
        reply = response.choices[0].message.content
        print(f"Bot: {reply}")
        
        # Speak the response
        client.tts_speak(text=reply, play_in_app=True)

chat_bot()
```

### Voice-Controlled Assistant

```python
from player2 import Player2Client
import time

client = Player2Client(game_name="voice-assistant")

def voice_assistant():
    print("Voice assistant started. Say 'stop' to exit.")
    
    while True:
        # Start listening
        client.stt_start(timeout=10)
        print("Listening...")
        
        # Stop and get text
        try:
            result = client.stt_stop()
            text = result.text.lower()
            
            if "stop" in text:
                print("Goodbye!")
                break
                
            print(f"You said: {text}")
            
            # Get AI response
            response = client.chat_completions(
                messages=[
                    {"role": "system", "content": "You are a helpful voice assistant."},
                    {"role": "user", "content": text}
                ]
            )
            
            reply = response.choices[0].message.content
            print(f"Assistant: {reply}")
            
            # Speak response
            client.tts_speak(text=reply, play_in_app=True)
            
        except Exception as e:
            print(f"Error: {e}")

voice_assistant()
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Support

- Join our Discord server for help and support
- Check the [Player2 documentation](https://player2.game) for more information
- Report issues on GitHub

## Developer Terms of Service

By using this API you agree to our Developer Terms of Service.