Metadata-Version: 2.1
Name: voicepilot-sdk
Version: 0.1.3
Summary: Official Python SDK for high-fidelity voice and conversational AI.
Home-page: https://openclaw.intelligens.app
Author: VoicePilot Team
Author-email: support@intelligens.app
License: UNKNOWN
Project-URL: Homepage, https://openclaw.intelligens.app
Project-URL: Source, https://github.com/voicepilot/voicepilot-python
Project-URL: Bug Tracker, https://github.com/voicepilot/voicepilot-python/issues
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: urllib3>=1.26.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: responses; extra == "dev"
Provides-Extra: ws
Requires-Dist: websocket-client>=1.3.0; extra == "ws"

# 🚀 VoicePilot Python SDK

The official Python client for the **VoicePilot** high-fidelity voice and conversational AI platform.

## Installation

```bash
pip install voicepilot-sdk
# For real-time conversational features:
pip install voicepilot-sdk[ws]
```

## Quick Start

### Initialize Client
```python
from voicepilot import VoicePilotClient

# Generate your key at https://openclaw.intelligens.app
client = VoicePilotClient(api_key="sk_platform_your_key_here")
```

### Text-to-Speech (TTS)
```python
# Standard TTS (returns base64 string)
response = client.tts.create("Hello, welcome to VoicePilot!", voice="anushka")

# Streaming TTS (yields raw WAV bytes directly)
with open("output.wav", "wb") as f:
    for chunk in client.tts.stream("Hello from the streaming API!", voice="anushka"):
        f.write(chunk)
```

### Speech-to-Text (STT)
```python
result = client.stt.transcribe("speech_sample.wav")
print(f"Transcription: {result.transcript}")
```

### Agent Management & Text Chat
```python
# Create and delete agents
agent = client.agents.create(name="Support", system_prompt="You are a helpful assistant.")
client.agents.delete(agent.id)

# Stateless text chat with an agent (no WebSockets needed)
response = client.agents.chat(
    agent_id=agent.id,
    text="Hello!",
    history=[{"role": "user", "content": "Hi there"}]
)
print(response.reply_text)
```

### 📞 Call Lifecycle (Create & End Calls)
The SDK provides dedicated methods to reserve call sessions and finalize them, which is essential for billing, analytics, and triggering webhooks.

**1. Manual Create & End (Recommended for custom integrations):**
```python
# Create a conversation log *before* connecting your frontend WebSockets
conv = client.conversations.create(agent_id="my_agent_id")
print(f"Pass this ID to your frontend: {conv['conversation_id']}")

# ... User completes the call on the frontend ...

# Explicitly end the call to finalize logs and trigger your webhooks
client.conversations.end(conv['conversation_id'])
```

**2. Automatic Lifecycle via Built-In WebSocket Client:**
```python
# The `connect` context manager automatically calls `conversations.create()` 
# when entering the block, and cleanly closes the socket upon exiting.
with client.agents.connect(agent_id="my_agent_id") as session:
    # Get the auto-generated conversation ID
    print(f"Active Session: {session.conversation_id}")
    
    session.send("Tell me a story.")
    for message in session.listen():
        if message.type == "agent.response":
            print(f"Agent: {message.text}")
```

## Error Handling
The SDK provides a typed exception hierarchy for easy error management.

```python
from voicepilot.exceptions import ValidationError, AuthenticationError

try:
    client.tts.create("")
except ValidationError as e:
    print(f"Oops: {e}")
except AuthenticationError:
    print("Check your API key!")
```

## Development
- **Tests**: `pytest tests/`
- **Build**: `python -m build`


