olbrain-python-sdk 0.2.1__tar.gz → 0.3.0__tar.gz

{olbrain_python_sdk-0.2.1/olbrain_python_sdk.egg-info → olbrain_python_sdk-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: olbrain-python-sdk
-Version: 0.2.1
+Version: 0.3.0
 Summary: Official Python SDK for Olbrain AI agents
 Home-page: https://github.com/Olbrain/olbrain-python-sdk
 Author: Olbrain Team
@@ -63,7 +63,7 @@ pip install olbrain-python-sdk
 ## Quick Start
 
 ```python
-from olbrain import AgentClient
+from olbrain import AgentClient, ChatResponse
 
 # Initialize client
 client = AgentClient(
@@ -71,82 +71,106 @@ client = AgentClient(
     api_key="sk_live_your_api_key"
 )
 
-# Create a session and send a message
+# Create a session
 session_id = client.create_session(title="My Chat")
-response = client.send_and_wait(session_id, "Hello!")
 
+# Send a message
+response_data = client.send(session_id, "Hello!")
+
+# Parse response
+response = ChatResponse.from_dict(response_data, session_id)
 print(response.text)
+print(f"Cost: ${response.cost:.6f}")
+
 client.close()
 ```
 
 ## Features
 
 - **Simple API** - Just `agent_id` and `api_key` to get started
-- **Session Management** - Create, update, archive sessions with metadata
-- **Sync & Streaming** - Both request-response and real-time streaming
+- **Session-based Conversations** - Maintain conversation context across messages
+- **Synchronous & Async** - Both sync responses and async webhook patterns
 - **Token Tracking** - Monitor usage and costs per request
 - **Model Override** - Switch models per-message
 - **Error Handling** - Comprehensive exception hierarchy
 
 ## Usage
 
-### Synchronous Messaging
+### Basic Messaging
 
 ```python
-from olbrain import AgentClient
+from olbrain import AgentClient, ChatResponse
 
 with AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key") as client:
-    session_id = client.create_session()
-    response = client.send_and_wait(session_id, "What is Python?")
-
+    # Create session
+    session_id = client.create_session(
+        title="Support Chat",
+        user_id="user-123",
+        mode="production"
+    )
+
+    # Send message and get response
+    response_data = client.send(session_id, "What is Python?")
+
+    # Parse response
+    response = ChatResponse.from_dict(response_data, session_id)
     print(response.text)
     print(f"Tokens: {response.token_usage.total_tokens}")
+    print(f"Model: {response.model}")
+    print(f"Cost: ${response.cost:.6f}")
 ```
 
-### Real-Time Streaming
+### Continuing a Conversation
 
 ```python
-from olbrain import AgentClient
+# Send multiple messages in the same session
+session_id = client.create_session(title="Q&A Session")
 
-client = AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key")
+# First message
+response1 = client.send(session_id, "What is machine learning?")
+print(ChatResponse.from_dict(response1, session_id).text)
 
-def on_message(msg):
-    print(f"[{msg['role']}]: {msg['content']}")
-
-session_id = client.create_session(on_message=on_message)
-client.send(session_id, "Tell me a story")
-client.run()  # Blocks and processes messages
+# Follow-up message - agent remembers context
+response2 = client.send(session_id, "Can you give me an example?")
+print(ChatResponse.from_dict(response2, session_id).text)
 ```
 
-### Session Management
+### Model Override
 
 ```python
-# Create session with metadata
-session_id = client.create_session(
-    title="Support Chat",
-    user_id="user-123",
-    metadata={"source": "web"},
-    mode="production"
+# Use a specific model for a message
+response_data = client.send(
+    session_id,
+    "Complex question here",
+    model="gpt-4o"  # Override default model
 )
 
-# Get session info
-info = client.get_session(session_id)
-print(f"Messages: {info.message_count}")
+response = ChatResponse.from_dict(response_data, session_id)
+print(f"Used model: {response.model}")
+```
 
-# Get message history
-messages = client.get_messages(session_id, limit=20)
+### Async Webhook Pattern
 
-# Archive session
-client.delete_session(session_id)
+```python
+# Send message with async processing
+# Response will be delivered to your webhook URL
+result = client.send_async(
+    session_id="existing-session",
+    message="Process this in the background",
+    webhook_url="https://your-app.com/webhook"
+)
+
+print(f"Message queued: {result['success']}")
 ```
 
-### Model Override
+### Message Metadata
 
 ```python
-response = client.send_and_wait(
+# Include custom metadata with messages
+response_data = client.send(
     session_id,
-    "Complex question here",
-    model="gpt-4"  # Override default model
+    "Tell me a joke",
+    metadata={"category": "humor", "source": "example"}
 )
 ```
 
@@ -156,18 +180,20 @@ response = client.send_and_wait(
 from olbrain import AgentClient
 from olbrain.exceptions import (
     AuthenticationError,
-    SessionNotFoundError,
     RateLimitError,
+    NetworkError,
     OlbrainError
 )
 
 try:
     client = AgentClient(agent_id="...", api_key="...")
-    response = client.send_and_wait(session_id, "Hello")
+    response = client.send(session_id, "Hello")
 except AuthenticationError:
     print("Invalid API key")
 except RateLimitError as e:
     print(f"Rate limited. Retry after {e.retry_after}s")
+except NetworkError as e:
+    print(f"Network error: {e}")
 except OlbrainError as e:
     print(f"Error: {e}")
 ```
@@ -195,22 +221,35 @@ logging.basicConfig(level=logging.DEBUG)
 | Method | Description |
 |--------|-------------|
 | `create_session()` | Create a new chat session |
-| `send(session_id, message)` | Send message (async, use callback) |
-| `send_and_wait(session_id, message)` | Send message and wait for response |
-| `get_session(session_id)` | Get session details |
-| `update_session(session_id, ...)` | Update session title/metadata |
-| `delete_session(session_id)` | Archive a session |
-| `get_messages(session_id)` | Get message history |
-| `get_session_stats(session_id)` | Get token usage stats |
+| `send(session_id, message, ...)` | Send message and get response (sync) |
+| `send_async(session_id, message, webhook_url, ...)` | Send message for async processing |
 | `close()` | Clean up resources |
 
+#### Deprecated Methods (v0.3.0+)
+
+The following methods are deprecated and raise `NotImplementedError`:
+- `send_and_wait()` - Use `send()` instead
+- `get_session()` - Not supported by webhook API
+- `update_session()` - Not supported by webhook API
+- `delete_session()` - Not supported by webhook API
+- `get_messages()` - Not supported by webhook API
+- `get_session_stats()` - Not supported by webhook API
+- `listen()` - SSE streaming not supported
+- `run()` - SSE streaming not supported
+
 ### Response Objects
 
 **ChatResponse**
 - `text` - Response text
+- `session_id` - Session identifier
 - `success` - Success status
 - `token_usage` - TokenUsage object
-- `model_used` - Model that generated response
+- `model` - Model that generated response
+- `processing_time_ms` - Processing time in milliseconds
+- `cost` - Cost in USD
+- `mode` - Response mode ("sync" or "session_created")
+- `metadata` - Optional metadata
+- `error` - Error message if failed
 
 **TokenUsage**
 - `prompt_tokens` - Input tokens
@@ -228,18 +267,27 @@ logging.basicConfig(level=logging.DEBUG)
 | `RateLimitError` | Rate limit exceeded |
 | `NetworkError` | Connection issues |
 | `ValidationError` | Invalid input |
-| `StreamingError` | Streaming error |
+
+## Migration from v0.2.x
+
+See [MIGRATION.md](MIGRATION.md) for detailed migration guide from v0.2.x to v0.3.0.
+
+Major changes in v0.3.0:
+- Removed SSE streaming (use sync or async webhook patterns)
+- Removed session management endpoints (get/update/delete)
+- Removed message history retrieval
+- Updated response schema field names (`model_used` → `model`, etc.)
 
 ## Examples
 
 See the [examples/](examples/) directory:
 
-- `basic_usage.py` - Core SDK features
-- `session_management.py` - Session CRUD operations
-- `streaming_responses.py` - Real-time streaming
+- `basic_usage.py` - Core SDK features (current API)
 - `error_handling.py` - Error handling patterns
 - `advanced_features.py` - Advanced usage
 
+**Note:** `streaming_responses.py` and `session_management.py` are deprecated and kept for reference only.
+
 ## License
 
 MIT License - see [LICENSE](LICENSE)

olbrain_python_sdk-0.3.0/README.md

@@ -0,0 +1,251 @@
+# Olbrain Python SDK
+
+[![PyPI version](https://badge.fury.io/py/olbrain-python-sdk.svg)](https://pypi.org/project/olbrain-python-sdk/)
+[![Python Support](https://img.shields.io/pypi/pyversions/olbrain-python-sdk.svg)](https://pypi.org/project/olbrain-python-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Official Python SDK for integrating Olbrain AI agents into your applications.
+
+## Installation
+
+```bash
+pip install olbrain-python-sdk
+```
+
+## Quick Start
+
+```python
+from olbrain import AgentClient, ChatResponse
+
+# Initialize client
+client = AgentClient(
+    agent_id="your-agent-id",
+    api_key="sk_live_your_api_key"
+)
+
+# Create a session
+session_id = client.create_session(title="My Chat")
+
+# Send a message
+response_data = client.send(session_id, "Hello!")
+
+# Parse response
+response = ChatResponse.from_dict(response_data, session_id)
+print(response.text)
+print(f"Cost: ${response.cost:.6f}")
+
+client.close()
+```
+
+## Features
+
+- **Simple API** - Just `agent_id` and `api_key` to get started
+- **Session-based Conversations** - Maintain conversation context across messages
+- **Synchronous & Async** - Both sync responses and async webhook patterns
+- **Token Tracking** - Monitor usage and costs per request
+- **Model Override** - Switch models per-message
+- **Error Handling** - Comprehensive exception hierarchy
+
+## Usage
+
+### Basic Messaging
+
+```python
+from olbrain import AgentClient, ChatResponse
+
+with AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key") as client:
+    # Create session
+    session_id = client.create_session(
+        title="Support Chat",
+        user_id="user-123",
+        mode="production"
+    )
+
+    # Send message and get response
+    response_data = client.send(session_id, "What is Python?")
+
+    # Parse response
+    response = ChatResponse.from_dict(response_data, session_id)
+    print(response.text)
+    print(f"Tokens: {response.token_usage.total_tokens}")
+    print(f"Model: {response.model}")
+    print(f"Cost: ${response.cost:.6f}")
+```
+
+### Continuing a Conversation
+
+```python
+# Send multiple messages in the same session
+session_id = client.create_session(title="Q&A Session")
+
+# First message
+response1 = client.send(session_id, "What is machine learning?")
+print(ChatResponse.from_dict(response1, session_id).text)
+
+# Follow-up message - agent remembers context
+response2 = client.send(session_id, "Can you give me an example?")
+print(ChatResponse.from_dict(response2, session_id).text)
+```
+
+### Model Override
+
+```python
+# Use a specific model for a message
+response_data = client.send(
+    session_id,
+    "Complex question here",
+    model="gpt-4o"  # Override default model
+)
+
+response = ChatResponse.from_dict(response_data, session_id)
+print(f"Used model: {response.model}")
+```
+
+### Async Webhook Pattern
+
+```python
+# Send message with async processing
+# Response will be delivered to your webhook URL
+result = client.send_async(
+    session_id="existing-session",
+    message="Process this in the background",
+    webhook_url="https://your-app.com/webhook"
+)
+
+print(f"Message queued: {result['success']}")
+```
+
+### Message Metadata
+
+```python
+# Include custom metadata with messages
+response_data = client.send(
+    session_id,
+    "Tell me a joke",
+    metadata={"category": "humor", "source": "example"}
+)
+```
+
+### Error Handling
+
+```python
+from olbrain import AgentClient
+from olbrain.exceptions import (
+    AuthenticationError,
+    RateLimitError,
+    NetworkError,
+    OlbrainError
+)
+
+try:
+    client = AgentClient(agent_id="...", api_key="...")
+    response = client.send(session_id, "Hello")
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after}s")
+except NetworkError as e:
+    print(f"Network error: {e}")
+except OlbrainError as e:
+    print(f"Error: {e}")
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+export OLBRAIN_API_KEY="sk_live_your_api_key"
+export OLBRAIN_AGENT_ID="your-agent-id"
+```
+
+### Logging
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+## API Reference
+
+### AgentClient
+
+| Method | Description |
+|--------|-------------|
+| `create_session()` | Create a new chat session |
+| `send(session_id, message, ...)` | Send message and get response (sync) |
+| `send_async(session_id, message, webhook_url, ...)` | Send message for async processing |
+| `close()` | Clean up resources |
+
+#### Deprecated Methods (v0.3.0+)
+
+The following methods are deprecated and raise `NotImplementedError`:
+- `send_and_wait()` - Use `send()` instead
+- `get_session()` - Not supported by webhook API
+- `update_session()` - Not supported by webhook API
+- `delete_session()` - Not supported by webhook API
+- `get_messages()` - Not supported by webhook API
+- `get_session_stats()` - Not supported by webhook API
+- `listen()` - SSE streaming not supported
+- `run()` - SSE streaming not supported
+
+### Response Objects
+
+**ChatResponse**
+- `text` - Response text
+- `session_id` - Session identifier
+- `success` - Success status
+- `token_usage` - TokenUsage object
+- `model` - Model that generated response
+- `processing_time_ms` - Processing time in milliseconds
+- `cost` - Cost in USD
+- `mode` - Response mode ("sync" or "session_created")
+- `metadata` - Optional metadata
+- `error` - Error message if failed
+
+**TokenUsage**
+- `prompt_tokens` - Input tokens
+- `completion_tokens` - Output tokens
+- `total_tokens` - Total tokens
+- `cost` - Cost in USD
+
+### Exceptions
+
+| Exception | Description |
+|-----------|-------------|
+| `OlbrainError` | Base exception |
+| `AuthenticationError` | Invalid API key |
+| `SessionNotFoundError` | Session not found |
+| `RateLimitError` | Rate limit exceeded |
+| `NetworkError` | Connection issues |
+| `ValidationError` | Invalid input |
+
+## Migration from v0.2.x
+
+See [MIGRATION.md](MIGRATION.md) for detailed migration guide from v0.2.x to v0.3.0.
+
+Major changes in v0.3.0:
+- Removed SSE streaming (use sync or async webhook patterns)
+- Removed session management endpoints (get/update/delete)
+- Removed message history retrieval
+- Updated response schema field names (`model_used` → `model`, etc.)
+
+## Examples
+
+See the [examples/](examples/) directory:
+
+- `basic_usage.py` - Core SDK features (current API)
+- `error_handling.py` - Error handling patterns
+- `advanced_features.py` - Advanced usage
+
+**Note:** `streaming_responses.py` and `session_management.py` are deprecated and kept for reference only.
+
+## License
+
+MIT License - see [LICENSE](LICENSE)
+
+## Links
+
+- [PyPI](https://pypi.org/project/olbrain-python-sdk/)
+- [GitHub](https://github.com/Olbrain/olbrain-python-sdk)
+- [Issues](https://github.com/Olbrain/olbrain-python-sdk/issues)

olbrain_python_sdk-0.3.0/examples/basic_usage.py

@@ -0,0 +1,149 @@
+"""
+Basic usage examples for the Olbrain Python SDK.
+
+This example demonstrates the fundamental features of the SDK including:
+- Client initialization
+- Session creation
+- Sending messages (synchronous)
+- Using model overrides
+- Error handling
+"""
+
+import os
+from olbrain import AgentClient, ChatResponse
+from olbrain.exceptions import (
+    OlbrainError,
+    AuthenticationError,
+    NetworkError
+)
+
+
+def main():
+    """Basic usage example."""
+
+    # Get credentials from environment variables
+    api_key = os.getenv("OLBRAIN_API_KEY", "sk_live_your-api-key-here")
+    agent_id = os.getenv("OLBRAIN_AGENT_ID", "your-agent-id-here")
+    # Optional: custom agent URL (auto-constructed from agent_id if not provided)
+    agent_url = os.getenv("OLBRAIN_AGENT_URL")
+
+    if api_key == "sk_live_your-api-key-here" or agent_id == "your-agent-id-here":
+        print("Please set OLBRAIN_API_KEY and OLBRAIN_AGENT_ID environment variables")
+        print()
+        print("Example:")
+        print("  export OLBRAIN_API_KEY=sk_live_your_key_here")
+        print("  export OLBRAIN_AGENT_ID=your-agent-id")
+        return
+
+    try:
+        # Initialize the client
+        client = AgentClient(
+            agent_id=agent_id,
+            api_key=api_key,
+            agent_url=agent_url  # Optional - uses default Cloud Run URL if not provided
+        )
+        print(f"Client initialized for agent {agent_id}")
+        print(f"Agent URL: {client.agent_url}")
+
+        # -----------------------------------------------------------------
+        # Example 1: Creating a session and sending messages
+        # -----------------------------------------------------------------
+        print("\n--- Example 1: Create Session and Send Messages ---")
+
+        # Create a session (first message without session_id creates the session)
+        session_id = client.create_session(
+            title="Basic Demo Chat",
+            user_id="demo-user-123",
+            mode="production"
+        )
+        print(f"Session created: {session_id}")
+
+        # Send a message and get response
+        response_data = client.send(session_id, "Hello! Can you introduce yourself?")
+
+        # Parse response
+        response = ChatResponse.from_dict(response_data, session_id)
+        print(f"Agent: {response.text}")
+        if response.token_usage:
+            print(f"Tokens used: {response.token_usage.total_tokens}")
+        if response.model:
+            print(f"Model: {response.model}")
+        if response.cost:
+            print(f"Cost: ${response.cost:.6f}")
+
+        # Send another message in the same session
+        response_data2 = client.send(session_id, "What can you help me with?")
+        response2 = ChatResponse.from_dict(response_data2, session_id)
+        print(f"\nAgent: {response2.text}")
+
+        # -----------------------------------------------------------------
+        # Example 2: Using model override
+        # -----------------------------------------------------------------
+        print("\n--- Example 2: Model Override ---")
+
+        # Send message with specific model
+        response_data = client.send(
+            session_id,
+            "Explain quantum computing in one sentence",
+            model="gpt-4o"  # Override default model
+        )
+        response = ChatResponse.from_dict(response_data, session_id)
+        print(f"Response: {response.text}")
+        print(f"Model used: {response.model}")
+
+        # -----------------------------------------------------------------
+        # Example 3: Using metadata
+        # -----------------------------------------------------------------
+        print("\n--- Example 3: Message with Metadata ---")
+
+        response_data = client.send(
+            session_id,
+            "Tell me a joke",
+            metadata={"category": "humor", "source": "example"}
+        )
+        response = ChatResponse.from_dict(response_data, session_id)
+        print(f"Agent: {response.text}")
+
+        # -----------------------------------------------------------------
+        # Example 4: Multiple sessions
+        # -----------------------------------------------------------------
+        print("\n--- Example 4: Multiple Independent Sessions ---")
+
+        # Create a second session
+        session2_id = client.create_session(
+            title="Second Chat",
+            user_id="another-user"
+        )
+        print(f"Second session created: {session2_id}")
+
+        # Send message to second session
+        response_data = client.send(session2_id, "Hi! What's your favorite color?")
+        response = ChatResponse.from_dict(response_data, session2_id)
+        print(f"Agent (Session 2): {response.text}")
+
+        # Sessions are independent
+        response_data = client.send(
+            session2_id,
+            "Do you remember what I asked in my first session?"
+        )
+        response = ChatResponse.from_dict(response_data, session2_id)
+        print(f"Agent (Session 2): {response.text}")
+
+        print("\nNote: Sessions are independent - each maintains its own conversation context")
+
+    except AuthenticationError:
+        print("Authentication failed. Please check your API key.")
+    except NetworkError as e:
+        print(f"Network error: {e}")
+    except OlbrainError as e:
+        print(f"Olbrain error: {e}")
+    except Exception as e:
+        print(f"Unexpected error: {e}")
+    finally:
+        if 'client' in locals():
+            client.close()
+            print("\nClient closed")
+
+
+if __name__ == "__main__":
+    main()

{olbrain_python_sdk-0.2.1 → olbrain_python_sdk-0.3.0}/examples/session_management.py

@@ -1,4 +1,20 @@
 """
+DEPRECATED: Most features in this example are no longer supported.
+
+Session management endpoints (get, update, delete, stats, message history) are not supported
+by the current API (v0.3.0+). The agent API uses a webhook-only architecture.
+
+ONLY the following operations are supported:
+- create_session(): Create a new session (first message without session_id)
+- send(): Send messages to existing sessions
+
+For current usage patterns, see basic_usage.py
+
+This file is kept for reference only and will be removed in a future release.
+
+---
+
+Original documentation (DEPRECATED):
 Session management example for the Olbrain Python SDK.
 
 This example demonstrates:

{olbrain_python_sdk-0.2.1 → olbrain_python_sdk-0.3.0}/examples/streaming_responses.py

@@ -1,4 +1,18 @@
 """
+DEPRECATED: This example is no longer valid.
+
+SSE streaming is not supported by the current API (v0.3.0+).
+The agent API uses a webhook-only architecture and does not provide SSE streaming endpoints.
+
+For current usage patterns, see:
+- basic_usage.py: Synchronous message sending with send()
+- Use send_async() with a webhook URL if you need async processing
+
+This file is kept for reference only and will be removed in a future release.
+
+---
+
+Original documentation (DEPRECATED):
 Streaming responses example for the Olbrain Python SDK.
 
 This example demonstrates: