conversimple-sdk 0.1.0__tar.gz

conversimple_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,377 @@
+Metadata-Version: 2.4
+Name: conversimple-sdk
+Version: 0.1.0
+Summary: Python SDK for Conversimple Conversational AI Platform
+Home-page: https://github.com/conversimple/conversimple-sdk
+Author: Conversimple
+Author-email: support@conversimple.com
+Project-URL: Bug Tracker, https://github.com/conversimple/conversimple-sdk/issues
+Project-URL: Documentation, https://docs.conversimple.com/sdk
+Project-URL: Platform, https://platform.conversimple.com
+Keywords: conversational ai,voice ai,chatbot,websocket,sdk,speech to text,text to speech
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: License :: OSI Approved :: MIT License
+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
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: websockets>=12.0
+Requires-Dist: aiofiles>=23.0
+Requires-Dist: aiohttp>=3.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Provides-Extra: examples
+Requires-Dist: aiofiles>=23.0; extra == "examples"
+Requires-Dist: aiohttp>=3.8.0; extra == "examples"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Conversimple SDK
+
+Python client library for the Conversimple Conversational AI Platform.
+
+This SDK enables customers to build and deploy AI agents that integrate with the Conversimple platform's WebRTC infrastructure and conversation management, providing real-time voice conversation capabilities with function calling support.
+
+## Features
+
+- **Real-time Voice Conversations**: Integrate with WebRTC-based voice conversations
+- **Function Calling**: Define tools that can be executed during conversations
+- **Event-Driven Architecture**: React to conversation lifecycle events  
+- **Auto-Reconnection**: Fault-tolerant WebSocket connection with exponential backoff
+- **Type Hints**: Full typing support for better development experience
+- **Async/Await Support**: Both sync and async tool definitions
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install conversimple-sdk
+```
+
+### Basic Usage
+
+```python
+import asyncio
+from conversimple import ConversimpleAgent, tool
+
+class MyAgent(ConversimpleAgent):
+    @tool("Get current weather for a location")
+    def get_weather(self, location: str) -> dict:
+        return {"location": location, "temperature": 72, "condition": "sunny"}
+
+    def on_conversation_started(self, conversation_id: str):
+        print(f"Conversation started: {conversation_id}")
+
+async def main():
+    agent = MyAgent(
+        api_key="your-api-key",
+        customer_id="your-customer-id"
+    )
+    
+    await agent.start()
+    
+    # Keep running
+    while True:
+        await asyncio.sleep(1)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Core Concepts
+
+### Agent Session Model
+
+Each `ConversimpleAgent` instance handles a single conversation session. For multiple concurrent conversations, create multiple agent instances:
+
+```python
+# Per-conversation agent instances
+async def handle_conversation(conversation_id):
+    agent = MyAgent(api_key=api_key, customer_id=customer_id)
+    await agent.start(conversation_id=conversation_id)
+```
+
+### Tool Registration
+
+Define tools using the `@tool` and `@tool_async` decorators:
+
+```python
+from conversimple import tool, tool_async
+
+class BusinessAgent(ConversimpleAgent):
+    @tool("Look up customer information")
+    def lookup_customer(self, customer_id: str) -> dict:
+        # Synchronous tool execution
+        return customer_database.get(customer_id)
+    
+    @tool_async("Send email notification")
+    async def send_email(self, email: str, subject: str, body: str) -> dict:
+        # Asynchronous tool execution
+        result = await email_service.send(email, subject, body)
+        return {"sent": True, "message_id": result.id}
+```
+
+### Event Callbacks
+
+Handle conversation lifecycle events:
+
+```python
+class MyAgent(ConversimpleAgent):
+    def on_conversation_started(self, conversation_id: str):
+        print(f"🎤 Conversation started: {conversation_id}")
+    
+    def on_conversation_ended(self, conversation_id: str):
+        print(f"📞 Conversation ended: {conversation_id}")
+    
+    def on_tool_called(self, tool_call):
+        print(f"🔧 Executing tool: {tool_call.tool_name}")
+    
+    def on_error(self, error_type: str, message: str, details: dict):
+        print(f"❌ Error ({error_type}): {message}")
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+export CONVERSIMPLE_API_KEY="your-api-key"
+export CONVERSIMPLE_CUSTOMER_ID="your-customer-id" 
+export CONVERSIMPLE_PLATFORM_URL="ws://localhost:4000/sdk/websocket"
+export CONVERSIMPLE_LOG_LEVEL="INFO"
+```
+
+### Programmatic Configuration
+
+```python
+agent = ConversimpleAgent(
+    api_key="your-api-key",
+    customer_id="your-customer-id",
+    platform_url="wss://platform.conversimple.com/sdk/websocket"
+)
+```
+
+## Examples
+
+The SDK includes several example implementations:
+
+### Simple Weather Agent
+```bash
+python examples/simple_agent.py
+```
+
+A basic agent that provides weather information, demonstrating:
+- Tool registration with `@tool` decorator
+- Conversation lifecycle callbacks
+- Basic agent structure
+
+### Customer Service Agent  
+```bash
+python examples/customer_service.py
+```
+
+Advanced customer service agent with multiple tools:
+- Customer lookup and account management
+- Support ticket creation
+- Email notifications
+- Refund processing
+- Async tool execution
+
+### Multi-Step Booking Agent
+```bash  
+python examples/booking_agent.py
+```
+
+Complex booking workflow demonstrating:
+- Multi-turn conversation state management
+- Booking creation, confirmation, and cancellation
+- Business rule validation
+- Transaction-like processes
+
+## API Reference
+
+### ConversimpleAgent
+
+Main agent class for platform integration.
+
+#### Methods
+
+- `__init__(api_key, customer_id=None, platform_url="ws://localhost:4000/sdk/websocket")`
+- `async start(conversation_id=None)` - Start agent and connect to platform
+- `async stop()` - Stop agent and disconnect
+- `on_conversation_started(conversation_id)` - Conversation started callback
+- `on_conversation_ended(conversation_id)` - Conversation ended callback  
+- `on_tool_called(tool_call)` - Tool execution callback
+- `on_tool_completed(call_id, result)` - Tool completion callback
+- `on_error(error_type, message, details)` - Error handling callback
+
+### Tool Decorators
+
+#### @tool(description)
+Register synchronous tool function.
+
+```python
+@tool("Description of what this tool does")
+def my_tool(self, param1: str, param2: int = 10) -> dict:
+    return {"result": "success"}
+```
+
+#### @tool_async(description)  
+Register asynchronous tool function.
+
+```python
+@tool_async("Description of async tool")
+async def my_async_tool(self, param: str) -> dict:
+    await asyncio.sleep(0.1)  # Async operation
+    return {"result": "success"}
+```
+
+### Type Hints
+
+The SDK automatically generates JSON schemas from Python type hints:
+
+- `str` → `"type": "string"`
+- `int` → `"type": "integer"`  
+- `float` → `"type": "number"`
+- `bool` → `"type": "boolean"`
+- `list` → `"type": "array"`
+- `dict` → `"type": "object"`
+- `Optional[T]` → Same as T (nullable)
+
+## Protocol Details
+
+### WebSocket Messages
+
+The SDK communicates with the platform using these message types:
+
+#### Outgoing (SDK → Platform)
+- `register_conversation_tools` - Register available tools
+- `tool_call_response` - Tool execution results
+- `tool_call_error` - Tool execution failures  
+- `heartbeat` - Connection keepalive
+
+#### Incoming (Platform → SDK)
+- `tool_call_request` - Tool execution requests
+- `conversation_lifecycle` - Conversation started/ended
+- `config_update` - Configuration updates
+- `analytics_update` - Usage analytics
+
+### Message Format
+
+Tool registration:
+```json
+{
+  "conversation_id": "conv_123",
+  "tools": [
+    {
+      "name": "get_weather",
+      "description": "Get weather for location", 
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "location": {"type": "string"}
+        },
+        "required": ["location"]
+      }
+    }
+  ]
+}
+```
+
+Tool execution:
+```json
+{
+  "call_id": "call_abc123",
+  "result": {"temperature": 22, "condition": "sunny"}
+}
+```
+
+## Error Handling
+
+The SDK provides comprehensive error handling:
+
+### Connection Errors
+- Automatic reconnection with exponential backoff
+- Configurable retry attempts and timeouts
+- Connection state monitoring
+
+### Tool Execution Errors
+- Automatic error reporting to platform
+- Exception wrapping and formatting
+- Timeout handling
+
+### Logging
+```python
+import logging
+
+# Configure SDK logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("conversimple")
+```
+
+## Development
+
+### Setup Development Environment
+
+```bash
+git clone https://github.com/conversimple/conversimple-sdk
+cd conversimple-sdk
+
+# Create virtual environment  
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt -r requirements-dev.txt
+
+# Install in editable mode
+pip install -e .
+```
+
+### Running Tests
+
+```bash
+pytest tests/
+```
+
+### Code Formatting
+
+```bash
+black conversimple/
+flake8 conversimple/
+mypy conversimple/
+```
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Support
+
+- **Documentation**: https://docs.conversimple.com/sdk
+- **GitHub Issues**: https://github.com/conversimple/conversimple-sdk/issues  
+- **Email Support**: support@conversimple.com
+- **Community**: https://community.conversimple.com

conversimple_sdk-0.1.0/README.md

@@ -0,0 +1,327 @@
+# Conversimple SDK
+
+Python client library for the Conversimple Conversational AI Platform.
+
+This SDK enables customers to build and deploy AI agents that integrate with the Conversimple platform's WebRTC infrastructure and conversation management, providing real-time voice conversation capabilities with function calling support.
+
+## Features
+
+- **Real-time Voice Conversations**: Integrate with WebRTC-based voice conversations
+- **Function Calling**: Define tools that can be executed during conversations
+- **Event-Driven Architecture**: React to conversation lifecycle events  
+- **Auto-Reconnection**: Fault-tolerant WebSocket connection with exponential backoff
+- **Type Hints**: Full typing support for better development experience
+- **Async/Await Support**: Both sync and async tool definitions
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install conversimple-sdk
+```
+
+### Basic Usage
+
+```python
+import asyncio
+from conversimple import ConversimpleAgent, tool
+
+class MyAgent(ConversimpleAgent):
+    @tool("Get current weather for a location")
+    def get_weather(self, location: str) -> dict:
+        return {"location": location, "temperature": 72, "condition": "sunny"}
+
+    def on_conversation_started(self, conversation_id: str):
+        print(f"Conversation started: {conversation_id}")
+
+async def main():
+    agent = MyAgent(
+        api_key="your-api-key",
+        customer_id="your-customer-id"
+    )
+    
+    await agent.start()
+    
+    # Keep running
+    while True:
+        await asyncio.sleep(1)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Core Concepts
+
+### Agent Session Model
+
+Each `ConversimpleAgent` instance handles a single conversation session. For multiple concurrent conversations, create multiple agent instances:
+
+```python
+# Per-conversation agent instances
+async def handle_conversation(conversation_id):
+    agent = MyAgent(api_key=api_key, customer_id=customer_id)
+    await agent.start(conversation_id=conversation_id)
+```
+
+### Tool Registration
+
+Define tools using the `@tool` and `@tool_async` decorators:
+
+```python
+from conversimple import tool, tool_async
+
+class BusinessAgent(ConversimpleAgent):
+    @tool("Look up customer information")
+    def lookup_customer(self, customer_id: str) -> dict:
+        # Synchronous tool execution
+        return customer_database.get(customer_id)
+    
+    @tool_async("Send email notification")
+    async def send_email(self, email: str, subject: str, body: str) -> dict:
+        # Asynchronous tool execution
+        result = await email_service.send(email, subject, body)
+        return {"sent": True, "message_id": result.id}
+```
+
+### Event Callbacks
+
+Handle conversation lifecycle events:
+
+```python
+class MyAgent(ConversimpleAgent):
+    def on_conversation_started(self, conversation_id: str):
+        print(f"🎤 Conversation started: {conversation_id}")
+    
+    def on_conversation_ended(self, conversation_id: str):
+        print(f"📞 Conversation ended: {conversation_id}")
+    
+    def on_tool_called(self, tool_call):
+        print(f"🔧 Executing tool: {tool_call.tool_name}")
+    
+    def on_error(self, error_type: str, message: str, details: dict):
+        print(f"❌ Error ({error_type}): {message}")
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+export CONVERSIMPLE_API_KEY="your-api-key"
+export CONVERSIMPLE_CUSTOMER_ID="your-customer-id" 
+export CONVERSIMPLE_PLATFORM_URL="ws://localhost:4000/sdk/websocket"
+export CONVERSIMPLE_LOG_LEVEL="INFO"
+```
+
+### Programmatic Configuration
+
+```python
+agent = ConversimpleAgent(
+    api_key="your-api-key",
+    customer_id="your-customer-id",
+    platform_url="wss://platform.conversimple.com/sdk/websocket"
+)
+```
+
+## Examples
+
+The SDK includes several example implementations:
+
+### Simple Weather Agent
+```bash
+python examples/simple_agent.py
+```
+
+A basic agent that provides weather information, demonstrating:
+- Tool registration with `@tool` decorator
+- Conversation lifecycle callbacks
+- Basic agent structure
+
+### Customer Service Agent  
+```bash
+python examples/customer_service.py
+```
+
+Advanced customer service agent with multiple tools:
+- Customer lookup and account management
+- Support ticket creation
+- Email notifications
+- Refund processing
+- Async tool execution
+
+### Multi-Step Booking Agent
+```bash  
+python examples/booking_agent.py
+```
+
+Complex booking workflow demonstrating:
+- Multi-turn conversation state management
+- Booking creation, confirmation, and cancellation
+- Business rule validation
+- Transaction-like processes
+
+## API Reference
+
+### ConversimpleAgent
+
+Main agent class for platform integration.
+
+#### Methods
+
+- `__init__(api_key, customer_id=None, platform_url="ws://localhost:4000/sdk/websocket")`
+- `async start(conversation_id=None)` - Start agent and connect to platform
+- `async stop()` - Stop agent and disconnect
+- `on_conversation_started(conversation_id)` - Conversation started callback
+- `on_conversation_ended(conversation_id)` - Conversation ended callback  
+- `on_tool_called(tool_call)` - Tool execution callback
+- `on_tool_completed(call_id, result)` - Tool completion callback
+- `on_error(error_type, message, details)` - Error handling callback
+
+### Tool Decorators
+
+#### @tool(description)
+Register synchronous tool function.
+
+```python
+@tool("Description of what this tool does")
+def my_tool(self, param1: str, param2: int = 10) -> dict:
+    return {"result": "success"}
+```
+
+#### @tool_async(description)  
+Register asynchronous tool function.
+
+```python
+@tool_async("Description of async tool")
+async def my_async_tool(self, param: str) -> dict:
+    await asyncio.sleep(0.1)  # Async operation
+    return {"result": "success"}
+```
+
+### Type Hints
+
+The SDK automatically generates JSON schemas from Python type hints:
+
+- `str` → `"type": "string"`
+- `int` → `"type": "integer"`  
+- `float` → `"type": "number"`
+- `bool` → `"type": "boolean"`
+- `list` → `"type": "array"`
+- `dict` → `"type": "object"`
+- `Optional[T]` → Same as T (nullable)
+
+## Protocol Details
+
+### WebSocket Messages
+
+The SDK communicates with the platform using these message types:
+
+#### Outgoing (SDK → Platform)
+- `register_conversation_tools` - Register available tools
+- `tool_call_response` - Tool execution results
+- `tool_call_error` - Tool execution failures  
+- `heartbeat` - Connection keepalive
+
+#### Incoming (Platform → SDK)
+- `tool_call_request` - Tool execution requests
+- `conversation_lifecycle` - Conversation started/ended
+- `config_update` - Configuration updates
+- `analytics_update` - Usage analytics
+
+### Message Format
+
+Tool registration:
+```json
+{
+  "conversation_id": "conv_123",
+  "tools": [
+    {
+      "name": "get_weather",
+      "description": "Get weather for location", 
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "location": {"type": "string"}
+        },
+        "required": ["location"]
+      }
+    }
+  ]
+}
+```
+
+Tool execution:
+```json
+{
+  "call_id": "call_abc123",
+  "result": {"temperature": 22, "condition": "sunny"}
+}
+```
+
+## Error Handling
+
+The SDK provides comprehensive error handling:
+
+### Connection Errors
+- Automatic reconnection with exponential backoff
+- Configurable retry attempts and timeouts
+- Connection state monitoring
+
+### Tool Execution Errors
+- Automatic error reporting to platform
+- Exception wrapping and formatting
+- Timeout handling
+
+### Logging
+```python
+import logging
+
+# Configure SDK logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("conversimple")
+```
+
+## Development
+
+### Setup Development Environment
+
+```bash
+git clone https://github.com/conversimple/conversimple-sdk
+cd conversimple-sdk
+
+# Create virtual environment  
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt -r requirements-dev.txt
+
+# Install in editable mode
+pip install -e .
+```
+
+### Running Tests
+
+```bash
+pytest tests/
+```
+
+### Code Formatting
+
+```bash
+black conversimple/
+flake8 conversimple/
+mypy conversimple/
+```
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Support
+
+- **Documentation**: https://docs.conversimple.com/sdk
+- **GitHub Issues**: https://github.com/conversimple/conversimple-sdk/issues  
+- **Email Support**: support@conversimple.com
+- **Community**: https://community.conversimple.com