olbrain-python-sdk 0.2.0__tar.gz

olbrain_python_sdk-0.2.0/.gitignore

@@ -0,0 +1,79 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# OS
+.DS_Store
+Thumbs.db

olbrain_python_sdk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Olbrain Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

olbrain_python_sdk-0.2.0/MANIFEST.in

@@ -0,0 +1,11 @@
+# Include important files in the package distribution
+include README.md
+include LICENSE
+include requirements.txt
+include pyproject.toml
+recursive-include olbrain *.py
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+global-exclude .DS_Store
+global-exclude *.pyc
+global-exclude *.pyo

olbrain_python_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,357 @@
+Metadata-Version: 2.4
+Name: olbrain-python-sdk
+Version: 0.2.0
+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://badge.fury.io/py/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 websites and mobile apps. Provides a simple interface for session management, messaging, and real-time streaming.
+
+## Features
+
+- **Simple Integration**: Just provide `agent_id` and `api_key`
+- **Session Management**: Full CRUD operations for sessions
+- **Synchronous & Streaming**: Both request-response and real-time streaming patterns
+- **Message History**: Retrieve conversation history with pagination
+- **Token Tracking**: Monitor token usage and costs
+- **Model Override**: Switch models per-message
+- **Error Handling**: Comprehensive exception hierarchy
+
+## Installation
+
+```bash
+pip install olbrain-python-sdk
+```
+
+### Development Installation
+
+```bash
+git clone https://github.com/olbrain/olbrain-python-sdk.git
+cd olbrain-python-sdk
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Basic Usage (Synchronous)
+
+```python
+from olbrain import AgentClient
+
+# Initialize client
+client = AgentClient(
+    agent_id="your-agent-id",
+    api_key="ak_your_api_key"
+)
+
+# Create a session
+session_id = client.create_session(title="My Chat", user_id="user-123")
+
+# Send message and get response
+response = client.send_and_wait(session_id, "Hello! How can you help me?")
+print(f"Agent: {response.text}")
+print(f"Tokens used: {response.token_usage.total_tokens}")
+
+# Clean up
+client.close()
+```
+
+### Real-Time Streaming
+
+```python
+from olbrain import AgentClient
+
+client = AgentClient(agent_id="your-agent-id", api_key="ak_your_api_key")
+
+# Define callback for incoming messages
+def on_message(msg):
+    print(f"[{msg['role']}]: {msg['content']}")
+
+# Create session with streaming enabled
+session_id = client.create_session(on_message=on_message, title="Streaming Chat")
+
+# Send message - response arrives via callback
+client.send(session_id, "Tell me a story")
+
+# Block and process messages (Ctrl+C to exit)
+client.run()
+```
+
+### Session Management
+
+```python
+from olbrain import AgentClient
+
+client = AgentClient(agent_id="your-agent-id", api_key="ak_your_api_key")
+
+# Create session with metadata
+session_id = client.create_session(
+    title="Support Chat",
+    user_id="customer-456",
+    metadata={"source": "website", "page": "/help"},
+    mode="production",  # or "development", "testing"
+    description="Customer support conversation"
+)
+
+# Get session details
+info = client.get_session(session_id)
+print(f"Title: {info.title}")
+print(f"Status: {info.status}")
+print(f"Messages: {info.message_count}")
+
+# Update session
+client.update_session(session_id, title="Renamed Chat")
+
+# Get message history
+result = client.get_messages(session_id, limit=20)
+for msg in result['messages']:
+    print(f"{msg['role']}: {msg['content']}")
+
+# Get session statistics
+stats = client.get_session_stats(session_id)
+print(f"Total tokens: {stats['stats'].get('total_tokens')}")
+
+# Archive session when done
+client.delete_session(session_id)
+```
+
+### Model Override
+
+```python
+# Use a specific model for a message
+response = client.send(
+    session_id,
+    "Explain quantum computing",
+    model="gpt-4"  # Override the agent's default model
+)
+```
+
+### Error Handling
+
+```python
+from olbrain import AgentClient
+from olbrain.exceptions import (
+    AuthenticationError,
+    SessionNotFoundError,
+    RateLimitError,
+    NetworkError,
+    OlbrainError
+)
+
+try:
+    client = AgentClient(agent_id="your-agent-id", api_key="ak_your_key")
+    session_id = client.create_session()
+    response = client.send_and_wait(session_id, "Hello!")
+
+except AuthenticationError:
+    print("Invalid API key")
+except SessionNotFoundError:
+    print("Session does not exist")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after} seconds")
+except NetworkError as e:
+    print(f"Network error: {e}")
+except OlbrainError as e:
+    print(f"Error: {e}")
+```
+
+### Context Manager
+
+```python
+from olbrain import AgentClient
+
+with AgentClient(agent_id="your-agent-id", api_key="ak_your_key") as client:
+    session_id = client.create_session(title="Quick Chat")
+    response = client.send_and_wait(session_id, "Hello!")
+    print(response.text)
+# Client automatically closed
+```
+
+## API Reference
+
+### AgentClient
+
+Main client class for interacting with Olbrain agents.
+
+#### Constructor
+
+```python
+AgentClient(
+    agent_id: str,           # Agent identifier (required)
+    api_key: str,            # API key starting with 'ak_' (required)
+    agent_url: str = None    # Custom URL (auto-constructed if not provided)
+)
+```
+
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `create_session(on_message, title, user_id, metadata, mode, description)` | Create a new session |
+| `send(session_id, message, user_id, metadata, model, mode)` | Send message (async via callback) |
+| `send_and_wait(session_id, message, user_id, metadata, model, timeout)` | Send message and wait for response |
+| `listen(session_id, on_message)` | Start listening to a session |
+| `get_session(session_id)` | Get session details |
+| `update_session(session_id, title, metadata, status)` | Update session |
+| `delete_session(session_id)` | Archive a session |
+| `get_session_stats(session_id)` | Get session statistics |
+| `get_messages(session_id, limit, offset)` | Get message history |
+| `run()` | Block and process message callbacks |
+| `close()` | Clean up resources |
+
+### Data Classes
+
+#### ChatResponse
+
+```python
+@dataclass
+class ChatResponse:
+    text: str                          # Response text
+    session_id: str                    # Session identifier
+    success: bool                      # Success status
+    token_usage: Optional[TokenUsage]  # Token usage info
+    model_used: Optional[str]          # Model that generated response
+    response_time_ms: Optional[int]    # Response time
+    error: Optional[str]               # Error message if failed
+```
+
+#### TokenUsage
+
+```python
+@dataclass
+class TokenUsage:
+    prompt_tokens: int      # Input tokens
+    completion_tokens: int  # Output tokens
+    total_tokens: int       # Total tokens
+    cost: float            # Cost in USD
+```
+
+#### SessionInfo
+
+```python
+@dataclass
+class SessionInfo:
+    session_id: str         # Session identifier
+    title: str              # Session title
+    status: str             # 'active' or 'archived'
+    created_at: str         # Creation timestamp
+    updated_at: str         # Last update timestamp
+    message_count: int      # Number of messages
+    user_id: Optional[str]  # User identifier
+    channel: str            # Channel type
+    metadata: Dict          # Session metadata
+```
+
+### Exceptions
+
+| Exception | Description |
+|-----------|-------------|
+| `OlbrainError` | Base exception class |
+| `AuthenticationError` | Invalid API key |
+| `SessionNotFoundError` | Session does not exist |
+| `SessionError` | Session operation failed |
+| `RateLimitError` | Rate limit exceeded (has `retry_after`) |
+| `NetworkError` | Network connectivity issues |
+| `ValidationError` | Input validation failed |
+| `StreamingError` | Streaming error |
+
+## Configuration
+
+### Environment Variables
+
+```bash
+export OLBRAIN_API_KEY="ak_your_api_key"
+export OLBRAIN_AGENT_ID="your-agent-id"
+export OLBRAIN_AGENT_URL="https://custom-url.com"  # Optional
+```
+
+### Logging
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+## Examples
+
+See the [examples/](examples/) directory:
+
+- `basic_usage.py` - Core SDK features
+- `session_management.py` - Session CRUD operations
+- `streaming_responses.py` - Real-time streaming
+
+## Changelog
+
+### v0.2.0
+
+- Added session management methods (`get_session`, `update_session`, `delete_session`)
+- Added `get_session_stats` and `get_messages` for analytics
+- Added `send_and_wait` for synchronous request-response
+- Enhanced `create_session` with `user_id`, `metadata`, `mode`, `description`
+- Enhanced `send` with `user_id`, `metadata`, `model` override
+- Added `TokenUsage` and `SessionInfo` data classes
+- Added `SessionNotFoundError` exception
+- Improved error handling with `_handle_response_errors`
+- Renamed from `alchemist` to `olbrain`
+
+### v0.1.0
+
+- Initial release
+- Basic session creation and messaging
+- Real-time streaming support
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/olbrain/olbrain-python-sdk/issues)
+- **Email**: support@olbrain.com