olbrain-python-sdk 0.2.0__tar.gz → 0.2.2__tar.gz

olbrain_python_sdk-0.2.2/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: olbrain-python-sdk
+Version: 0.2.2
+Summary: Official Python SDK for Olbrain AI agents
+Home-page: https://github.com/Olbrain/olbrain-python-sdk
+Author: Olbrain Team
+Author-email: Olbrain Team <support@olbrain.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Olbrain/olbrain-python-sdk
+Project-URL: Bug Reports, https://github.com/Olbrain/olbrain-python-sdk/issues
+Project-URL: Source, https://github.com/Olbrain/olbrain-python-sdk
+Project-URL: Documentation, https://docs.olbrain.com/python-sdk
+Keywords: olbrain,ai,agents,chatbot,nlp,artificial intelligence,sdk,api,conversation,streaming
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.7
+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>=6.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.18.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.12.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: flake8>=4.0.0; extra == "dev"
+Requires-Dist: mypy>=0.910; extra == "dev"
+Requires-Dist: requests-mock>=1.9.0; extra == "dev"
+Provides-Extra: async
+Requires-Dist: aiohttp>=3.8.0; extra == "async"
+Requires-Dist: aiofiles>=0.7.0; extra == "async"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# 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
+
+# Initialize client
+client = AgentClient(
+    agent_id="your-agent-id",
+    api_key="sk_live_your_api_key"
+)
+
+# Create a session and send a message
+session_id = client.create_session(title="My Chat")
+response = client.send_and_wait(session_id, "Hello!")
+
+print(response.text)
+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
+- **Token Tracking** - Monitor usage and costs per request
+- **Model Override** - Switch models per-message
+- **Error Handling** - Comprehensive exception hierarchy
+
+## Usage
+
+### Synchronous Messaging
+
+```python
+from olbrain import AgentClient
+
+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?")
+
+    print(response.text)
+    print(f"Tokens: {response.token_usage.total_tokens}")
+```
+
+### Real-Time Streaming
+
+```python
+from olbrain import AgentClient
+
+client = AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key")
+
+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
+```
+
+### Session Management
+
+```python
+# Create session with metadata
+session_id = client.create_session(
+    title="Support Chat",
+    user_id="user-123",
+    metadata={"source": "web"},
+    mode="production"
+)
+
+# Get session info
+info = client.get_session(session_id)
+print(f"Messages: {info.message_count}")
+
+# Get message history
+messages = client.get_messages(session_id, limit=20)
+
+# Archive session
+client.delete_session(session_id)
+```
+
+### Model Override
+
+```python
+response = client.send_and_wait(
+    session_id,
+    "Complex question here",
+    model="gpt-4"  # Override default model
+)
+```
+
+### Error Handling
+
+```python
+from olbrain import AgentClient
+from olbrain.exceptions import (
+    AuthenticationError,
+    SessionNotFoundError,
+    RateLimitError,
+    OlbrainError
+)
+
+try:
+    client = AgentClient(agent_id="...", api_key="...")
+    response = client.send_and_wait(session_id, "Hello")
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after}s")
+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 (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 |
+| `close()` | Clean up resources |
+
+### Response Objects
+
+**ChatResponse**
+- `text` - Response text
+- `success` - Success status
+- `token_usage` - TokenUsage object
+- `model_used` - Model that generated response
+
+**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 |
+| `StreamingError` | Streaming error |
+
+## Examples
+
+See the [examples/](examples/) directory:
+
+- `basic_usage.py` - Core SDK features
+- `session_management.py` - Session CRUD operations
+- `streaming_responses.py` - Real-time streaming
+- `error_handling.py` - Error handling patterns
+- `advanced_features.py` - Advanced usage
+
+## 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.2.2/README.md

@@ -0,0 +1,203 @@
+# 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
+
+# Initialize client
+client = AgentClient(
+    agent_id="your-agent-id",
+    api_key="sk_live_your_api_key"
+)
+
+# Create a session and send a message
+session_id = client.create_session(title="My Chat")
+response = client.send_and_wait(session_id, "Hello!")
+
+print(response.text)
+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
+- **Token Tracking** - Monitor usage and costs per request
+- **Model Override** - Switch models per-message
+- **Error Handling** - Comprehensive exception hierarchy
+
+## Usage
+
+### Synchronous Messaging
+
+```python
+from olbrain import AgentClient
+
+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?")
+
+    print(response.text)
+    print(f"Tokens: {response.token_usage.total_tokens}")
+```
+
+### Real-Time Streaming
+
+```python
+from olbrain import AgentClient
+
+client = AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key")
+
+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
+```
+
+### Session Management
+
+```python
+# Create session with metadata
+session_id = client.create_session(
+    title="Support Chat",
+    user_id="user-123",
+    metadata={"source": "web"},
+    mode="production"
+)
+
+# Get session info
+info = client.get_session(session_id)
+print(f"Messages: {info.message_count}")
+
+# Get message history
+messages = client.get_messages(session_id, limit=20)
+
+# Archive session
+client.delete_session(session_id)
+```
+
+### Model Override
+
+```python
+response = client.send_and_wait(
+    session_id,
+    "Complex question here",
+    model="gpt-4"  # Override default model
+)
+```
+
+### Error Handling
+
+```python
+from olbrain import AgentClient
+from olbrain.exceptions import (
+    AuthenticationError,
+    SessionNotFoundError,
+    RateLimitError,
+    OlbrainError
+)
+
+try:
+    client = AgentClient(agent_id="...", api_key="...")
+    response = client.send_and_wait(session_id, "Hello")
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after}s")
+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 (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 |
+| `close()` | Clean up resources |
+
+### Response Objects
+
+**ChatResponse**
+- `text` - Response text
+- `success` - Success status
+- `token_usage` - TokenUsage object
+- `model_used` - Model that generated response
+
+**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 |
+| `StreamingError` | Streaming error |
+
+## Examples
+
+See the [examples/](examples/) directory:
+
+- `basic_usage.py` - Core SDK features
+- `session_management.py` - Session CRUD operations
+- `streaming_responses.py` - Real-time streaming
+- `error_handling.py` - Error handling patterns
+- `advanced_features.py` - Advanced usage
+
+## 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.2.0 → olbrain_python_sdk-0.2.2}/examples/advanced_features.py

@@ -1,5 +1,5 @@
 """
-Advanced features example for the Alchemist Python SDK.
+Advanced features example for the Olbrain Python SDK.
 
 This example demonstrates:
 - Context manager usage
@@ -14,8 +14,8 @@ import time
 import logging
 from typing import Dict, Any
 from contextlib import contextmanager
-from alchemist import AgentClient
-from alchemist.exceptions import AlchemistError
+from olbrain import AgentClient
+from olbrain.exceptions import OlbrainError
 
 
 # Configure logging for performance monitoring
@@ -32,7 +32,7 @@ def timer(operation_name: str):
     logger.info(f"{operation_name} took {end_time - start_time:.2f} seconds")
 
 
-class AdvancedAlchemistClient:
+class AdvancedOlbrainClient:
     """Extended client with additional features."""
     
     def __init__(self, agent_id: str, api_key: str, **kwargs):
@@ -100,15 +100,15 @@ def demonstrate_context_manager_usage():
     print("🎯 Context Manager Usage")
     print("=" * 60)
     
-    api_key = os.getenv("ALCHEMIST_API_KEY", "demo-key")
-    agent_id = os.getenv("ALCHEMIST_AGENT_ID", "demo-agent")
+    api_key = os.getenv("OLBRAIN_API_KEY", "demo-key")
+    agent_id = os.getenv("OLBRAIN_AGENT_ID", "demo-agent")
     
     if api_key == "demo-key":
         print("⚠️ Skipping context manager demo - no valid API key")
         return
     
     # Using the client as a context manager ensures proper cleanup
-    with AlchemistClient(api_key=api_key) as client:
+    with AgentClient(api_key=api_key) as client:
         print("✅ Client initialized in context manager")
         
         try:
@@ -135,7 +135,7 @@ def demonstrate_custom_configuration():
     print("⚙️ Custom Configuration")
     print("=" * 60)
     
-    api_key = os.getenv("ALCHEMIST_API_KEY", "demo-key")
+    api_key = os.getenv("OLBRAIN_API_KEY", "demo-key")
     
     # Configuration for high-performance usage
     high_perf_config = {
@@ -161,11 +161,11 @@ def demonstrate_custom_configuration():
         # Demonstrate different configurations
         try:
             # Test with quick config
-            with AlchemistClient(api_key=api_key, **quick_config) as quick_client:
+            with AgentClient(api_key=api_key, **quick_config) as quick_client:
                 print("\n✅ Quick client initialized")
                 
             # Test with high-performance config
-            with AlchemistClient(api_key=api_key, **high_perf_config) as hp_client:
+            with AgentClient(api_key=api_key, **high_perf_config) as hp_client:
                 print("✅ High-performance client initialized")
                 
         except Exception as e:
@@ -180,15 +180,15 @@ def demonstrate_metadata_handling():
     print("📊 Metadata Handling")
     print("=" * 60)
     
-    api_key = os.getenv("ALCHEMIST_API_KEY", "demo-key")
-    agent_id = os.getenv("ALCHEMIST_AGENT_ID", "demo-agent")
+    api_key = os.getenv("OLBRAIN_API_KEY", "demo-key")
+    agent_id = os.getenv("OLBRAIN_AGENT_ID", "demo-agent")
     
     if api_key == "demo-key":
         print("⚠️ Skipping metadata demo - no valid API key")
         return
     
     try:
-        with AlchemistClient(api_key=api_key) as client:
+        with AgentClient(api_key=api_key) as client:
             agent = client.get_agent(agent_id)
             
             # Create session with rich metadata
@@ -279,8 +279,8 @@ def demonstrate_performance_monitoring():
     print("📈 Performance Monitoring")
     print("=" * 60)
     
-    api_key = os.getenv("ALCHEMIST_API_KEY", "demo-key")
-    agent_id = os.getenv("ALCHEMIST_AGENT_ID", "demo-agent")
+    api_key = os.getenv("OLBRAIN_API_KEY", "demo-key")
+    agent_id = os.getenv("OLBRAIN_AGENT_ID", "demo-agent")
     
     if api_key == "demo-key":
         print("⚠️ Skipping performance monitoring demo - no valid API key")
@@ -288,7 +288,7 @@ def demonstrate_performance_monitoring():
     
     try:
         # Use our extended client with metrics
-        extended_client = AdvancedAlchemistClient(api_key=api_key)
+        extended_client = AdvancedAgentClient(api_key=api_key)
         agent = extended_client.get_agent_with_metrics(agent_id)
         
         print("🚀 Running performance test with metrics collection...")
@@ -351,15 +351,15 @@ def demonstrate_advanced_session_management():
     print("💼 Advanced Session Management")
     print("=" * 60)
     
-    api_key = os.getenv("ALCHEMIST_API_KEY", "demo-key")
-    agent_id = os.getenv("ALCHEMIST_AGENT_ID", "demo-agent")
+    api_key = os.getenv("OLBRAIN_API_KEY", "demo-key")
+    agent_id = os.getenv("OLBRAIN_AGENT_ID", "demo-agent")
     
     if api_key == "demo-key":
         print("⚠️ Skipping advanced session demo - no valid API key")
         return
     
     try:
-        with AlchemistClient(api_key=api_key) as client:
+        with AgentClient(api_key=api_key) as client:
             agent = client.get_agent(agent_id)
             
             # Create multiple sessions with different purposes
@@ -453,7 +453,7 @@ def demonstrate_advanced_session_management():
 
 def main():
     """Run all advanced feature demonstrations."""
-    print("🚀 Alchemist SDK Advanced Features Examples")
+    print("🚀 Olbrain SDK Advanced Features Examples")
     print("This demo showcases advanced usage patterns and features.\n")
     
     demonstrate_context_manager_usage()

{olbrain_python_sdk-0.2.0 → olbrain_python_sdk-0.2.2}/examples/basic_usage.py

@@ -23,16 +23,16 @@ def main():
     """Basic usage example."""
 
     # Get credentials from environment variables
-    api_key = os.getenv("OLBRAIN_API_KEY", "ak_your-api-key-here")
+    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 == "ak_your-api-key-here" or agent_id == "your-agent-id-here":
+    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=ak_your_key_here")
+        print("  export OLBRAIN_API_KEY=sk_live_your_key_here")
         print("  export OLBRAIN_AGENT_ID=your-agent-id")
         return