olbrain-python-sdk 0.3.1__tar.gz → 0.5.0__tar.gz

{olbrain_python_sdk-0.3.1 → olbrain_python_sdk-0.5.0}/MANIFEST.in

@@ -3,7 +3,7 @@ include README.md
 include LICENSE
 include requirements.txt
 include pyproject.toml
-recursive-include olbrain *.py
+recursive-include olbrain *.py *.md
 recursive-exclude * __pycache__
 recursive-exclude * *.py[co]
 global-exclude .DS_Store

{olbrain_python_sdk-0.3.1/olbrain_python_sdk.egg-info → olbrain_python_sdk-0.5.0}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: olbrain-python-sdk
-Version: 0.3.1
+Version: 0.5.0
 Summary: Official Python SDK for Olbrain AI agents
-Home-page: https://github.com/Olbrain/olbrain-python-sdk
+Home-page: https://github.com/Olbrain/olbrain-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: Homepage, https://github.com/Olbrain/olbrain-sdk/tree/main/packages/python
+Project-URL: Bug Reports, https://github.com/Olbrain/olbrain-sdk/issues
+Project-URL: Source, https://github.com/Olbrain/olbrain-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
@@ -54,6 +54,8 @@ Dynamic: requires-python
 
 Official Python SDK for integrating Olbrain AI agents into your applications.
 
+> **Coding assistants:** the complete API reference ships in the package as [`olbrain/AGENTS.md`](olbrain/AGENTS.md) (`site-packages/olbrain/AGENTS.md`).
+
 ## Installation
 
 ```bash
@@ -66,8 +68,8 @@ For local development and testing:
 
 ```bash
 # Clone the repository
-git clone https://github.com/Olbrain/olbrain-python-sdk.git
-cd olbrain-python-sdk
+git clone https://github.com/Olbrain/olbrain-sdk.git
+cd olbrain-sdk/packages/python
 
 # Create virtual environment
 python3 -m venv venv
@@ -84,7 +86,7 @@ pytest tests/
 
 Get your credentials from the Olbrain dashboard:
 - **Agent ID**: Your unique agent identifier
-- **API Key**: Starts with `sk_live_` (production) or `sk_` (test)
+- **API Key**: an access key (`ak_…`) from Noesis → Settings → Organization → Access keys, or from the finish page Alchemist links to when it hands an agent over (that key works only for that agent)
 
 ### Basic Example
 
@@ -94,7 +96,7 @@ from olbrain import AgentClient
 # Initialize client
 client = AgentClient(
     agent_id="your-agent-id",
-    api_key="sk_live_your_api_key"
+    api_key="ak_your_api_key"
 )
 
 # Create a session and send a message
@@ -113,7 +115,7 @@ client.close()
 from olbrain import AgentClient
 
 # Automatically closes client when done
-with AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key") as client:
+with AgentClient(agent_id="your-agent-id", api_key="ak_your_key") as client:
     session_id = client.create_session(title="My Chat")
     response = client.send_and_wait(session_id, "What is machine learning?")
     print(response.text)
@@ -127,6 +129,21 @@ with AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key") as client
 - **Token Tracking** - Monitor usage and costs per request
 - **Model Override** - Switch models per-message
 - **Error Handling** - Comprehensive exception hierarchy
+- **Workflow Agents** - Run workflow agents, read and control their runs, resolve approvals (`Olbrain`)
+- **Research Agents** - Sessions, streamed turns, plans, reports and review (`Olbrain.research`, sign-ins only)
+
+### Workflow agents
+
+```python
+import os
+from olbrain import Olbrain
+
+olbrain = Olbrain(api_key=os.environ["OLBRAIN_API_KEY"])  # keep the key on your server
+run = olbrain.workflows.run("your-agent-id", payload={"url": "https://example.com"})
+print(olbrain.runs.get("your-agent-id", run["run_id"]))
+```
+
+See [`olbrain/AGENTS.md`](olbrain/AGENTS.md) for runs, approvals and research agents.
 
 ## Usage
 
@@ -137,7 +154,7 @@ Send a message and wait for the complete response:
 ```python
 from olbrain import AgentClient
 
-with AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key") as client:
+with AgentClient(agent_id="your-agent-id", api_key="ak_your_key") as client:
     # Create a new chat session
     session_id = client.create_session(title="My Chat")
 
@@ -152,12 +169,12 @@ with AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key") as client
 
 ### 2. Real-Time Streaming (Callback Pattern)
 
-Receive messages in real-time as they arrive:
+Receive new messages as they arrive (the client polls the session every 2 seconds):
 
 ```python
 from olbrain import AgentClient
 
-client = AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key")
+client = AgentClient(agent_id="your-agent-id", api_key="ak_your_key")
 
 # Define message handler
 def on_message(msg):
@@ -189,7 +206,7 @@ Create, retrieve, and manage chat sessions:
 ```python
 from olbrain import AgentClient
 
-with AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key") as client:
+with AgentClient(agent_id="your-agent-id", api_key="ak_your_key") as client:
     # Create session with metadata
     session = client.create_session(
         title="Support Chat",
@@ -208,15 +225,9 @@ with AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key") as client
     for msg in messages.get('messages', []):
         print(f"{msg['role']}: {msg['content']}")
 
-    # Update session
-    updated = client.update_session(session, title="Updated Chat Title")
-
     # Get session statistics
     stats = client.get_session_stats(session)
     print(f"Stats: {stats}")
-
-    # Archive/delete session
-    client.delete_session(session)
 ```
 
 ### 4. Model Override
@@ -226,7 +237,7 @@ Send messages using a specific model:
 ```python
 from olbrain import AgentClient
 
-with AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key") as client:
+with AgentClient(agent_id="your-agent-id", api_key="ak_your_key") as client:
     session_id = client.create_session()
 
     # Use specific model for this request
@@ -246,7 +257,7 @@ Maintain conversation context:
 ```python
 from olbrain import AgentClient
 
-with AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key") as client:
+with AgentClient(agent_id="your-agent-id", api_key="ak_your_key") as client:
     session_id = client.create_session(title="Q&A Session")
 
     # First message
@@ -277,7 +288,7 @@ from olbrain.exceptions import (
 )
 
 try:
-    client = AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key")
+    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")
 
@@ -305,24 +316,21 @@ finally:
 
 ### API Key
 
-The SDK validates API keys. Valid prefixes are:
-- `sk_live_` - Production keys
-- `org_live_` - Organization keys
-- `sk_` - Test keys
-- `org_` - Test organization keys
+The SDK validates API keys. Access keys (`ak_`) are the only kind issued today; the older
+`sk_live_`, `org_live_`, `sk_` and `org_` prefixes still pass validation.
 
 ```python
 # Valid API key
 client = AgentClient(
     agent_id="your-agent-id",
-    api_key="sk_live_24c2859a0cf359b8aebbe3d8e9c60f0341d111b30004a56b428726edb354bec5"
+    api_key="ak_your_api_key_here"
 )
 ```
 
 ### Environment Variables
 
 ```bash
-export OLBRAIN_API_KEY="sk_live_your_api_key"
+export OLBRAIN_API_KEY="ak_your_api_key"
 export OLBRAIN_AGENT_ID="your-agent-id"
 ```
 
@@ -348,10 +356,10 @@ client = AgentClient(agent_id="...", api_key="...")
 ### Common Issues
 
 **"Invalid API key" error**
-- Ensure your API key starts with `sk_live_`, `org_live_`, `sk_`, or `org_`
+- Ensure your API key starts with `ak_` (or one of the older `sk_live_`, `org_live_`, `sk_`, `org_` prefixes)
 - Check that you copied the key correctly (no extra spaces)
 
-**"Stream connection failed" error**
+**"Message poll failed" in the logs**
 - Check that your agent ID is correct
 - Verify you have a stable internet connection
 - Try restarting the client
@@ -397,8 +405,8 @@ The test will:
 |--------|-----------|---------|-------------|
 | `create_session()` | `title`, `user_id`, `metadata`, `on_message`, `mode`, `description` | `str` (session_id) | Create a new chat session |
 | `get_session(session_id)` | `session_id` | `SessionInfo` | Get session details |
-| `update_session(session_id, ...)` | `session_id`, `title`, `metadata`, `status` | `SessionInfo` | Update session properties |
-| `delete_session(session_id)` | `session_id` | `Dict` | Archive/delete a session |
+| `update_session(session_id, ...)` | `session_id`, `title`, `metadata`, `status` | - | Not supported: raises `OlbrainError` (the Olbrain API has no endpoint for it) |
+| `delete_session(session_id)` | `session_id` | - | Not supported: raises `OlbrainError` (the Olbrain API has no endpoint for it) |
 | `get_messages(session_id, ...)` | `session_id`, `limit`, `offset` | `Dict` | Get message history |
 | `get_session_stats(session_id)` | `session_id` | `Dict` | Get session statistics |
 
@@ -408,7 +416,7 @@ The test will:
 |--------|-----------|---------|-------------|
 | `send(session_id, message, ...)` | `session_id`, `message`, `user_id`, `metadata`, `model` | `Dict` | Send message (async with callback) |
 | `send_and_wait(session_id, message, ...)` | `session_id`, `message`, `user_id`, `metadata`, `model`, `timeout` | `ChatResponse` | Send and wait for response |
-| `listen(session_id, on_message)` | `session_id`, `on_message` | - | Start listening to session |
+| `listen(session_id, on_message)` | `session_id`, `on_message` | - | Poll the session every 2 s and call `on_message` for each new message |
 | `run()` | - | - | Block and process streaming messages |
 | `close()` | - | - | Close client and cleanup resources |
 
@@ -509,7 +517,7 @@ python examples/basic_usage.py
 
 ## Support
 
-- **Issues**: [GitHub Issues](https://github.com/Olbrain/olbrain-python-sdk/issues)
+- **Issues**: [GitHub Issues](https://github.com/Olbrain/olbrain-sdk/issues)
 - **Documentation**: See [examples/](examples/) directory
 - **API Status**: Check [status page](https://olbrain.com/status)
 
@@ -524,6 +532,6 @@ Current version: **0.2.0**
 ## Links
 
 - [PyPI Package](https://pypi.org/project/olbrain-python-sdk/)
-- [GitHub Repository](https://github.com/Olbrain/olbrain-python-sdk)
-- [Report Issues](https://github.com/Olbrain/olbrain-python-sdk/issues)
+- [GitHub Repository](https://github.com/Olbrain/olbrain-sdk)
+- [Report Issues](https://github.com/Olbrain/olbrain-sdk/issues)
 - [Olbrain Website](https://olbrain.com)

{olbrain_python_sdk-0.3.1 → olbrain_python_sdk-0.5.0}/README.md

@@ -6,6 +6,8 @@
 
 Official Python SDK for integrating Olbrain AI agents into your applications.
 
+> **Coding assistants:** the complete API reference ships in the package as [`olbrain/AGENTS.md`](olbrain/AGENTS.md) (`site-packages/olbrain/AGENTS.md`).
+
 ## Installation
 
 ```bash
@@ -18,8 +20,8 @@ For local development and testing:
 
 ```bash
 # Clone the repository
-git clone https://github.com/Olbrain/olbrain-python-sdk.git
-cd olbrain-python-sdk
+git clone https://github.com/Olbrain/olbrain-sdk.git
+cd olbrain-sdk/packages/python
 
 # Create virtual environment
 python3 -m venv venv
@@ -36,7 +38,7 @@ pytest tests/
 
 Get your credentials from the Olbrain dashboard:
 - **Agent ID**: Your unique agent identifier
-- **API Key**: Starts with `sk_live_` (production) or `sk_` (test)
+- **API Key**: an access key (`ak_…`) from Noesis → Settings → Organization → Access keys, or from the finish page Alchemist links to when it hands an agent over (that key works only for that agent)
 
 ### Basic Example
 
@@ -46,7 +48,7 @@ from olbrain import AgentClient
 # Initialize client
 client = AgentClient(
     agent_id="your-agent-id",
-    api_key="sk_live_your_api_key"
+    api_key="ak_your_api_key"
 )
 
 # Create a session and send a message
@@ -65,7 +67,7 @@ client.close()
 from olbrain import AgentClient
 
 # Automatically closes client when done
-with AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key") as client:
+with AgentClient(agent_id="your-agent-id", api_key="ak_your_key") as client:
     session_id = client.create_session(title="My Chat")
     response = client.send_and_wait(session_id, "What is machine learning?")
     print(response.text)
@@ -79,6 +81,21 @@ with AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key") as client
 - **Token Tracking** - Monitor usage and costs per request
 - **Model Override** - Switch models per-message
 - **Error Handling** - Comprehensive exception hierarchy
+- **Workflow Agents** - Run workflow agents, read and control their runs, resolve approvals (`Olbrain`)
+- **Research Agents** - Sessions, streamed turns, plans, reports and review (`Olbrain.research`, sign-ins only)
+
+### Workflow agents
+
+```python
+import os
+from olbrain import Olbrain
+
+olbrain = Olbrain(api_key=os.environ["OLBRAIN_API_KEY"])  # keep the key on your server
+run = olbrain.workflows.run("your-agent-id", payload={"url": "https://example.com"})
+print(olbrain.runs.get("your-agent-id", run["run_id"]))
+```
+
+See [`olbrain/AGENTS.md`](olbrain/AGENTS.md) for runs, approvals and research agents.
 
 ## Usage
 
@@ -89,7 +106,7 @@ Send a message and wait for the complete response:
 ```python
 from olbrain import AgentClient
 
-with AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key") as client:
+with AgentClient(agent_id="your-agent-id", api_key="ak_your_key") as client:
     # Create a new chat session
     session_id = client.create_session(title="My Chat")
 
@@ -104,12 +121,12 @@ with AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key") as client
 
 ### 2. Real-Time Streaming (Callback Pattern)
 
-Receive messages in real-time as they arrive:
+Receive new messages as they arrive (the client polls the session every 2 seconds):
 
 ```python
 from olbrain import AgentClient
 
-client = AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key")
+client = AgentClient(agent_id="your-agent-id", api_key="ak_your_key")
 
 # Define message handler
 def on_message(msg):
@@ -141,7 +158,7 @@ Create, retrieve, and manage chat sessions:
 ```python
 from olbrain import AgentClient
 
-with AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key") as client:
+with AgentClient(agent_id="your-agent-id", api_key="ak_your_key") as client:
     # Create session with metadata
     session = client.create_session(
         title="Support Chat",
@@ -160,15 +177,9 @@ with AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key") as client
     for msg in messages.get('messages', []):
         print(f"{msg['role']}: {msg['content']}")
 
-    # Update session
-    updated = client.update_session(session, title="Updated Chat Title")
-
     # Get session statistics
     stats = client.get_session_stats(session)
     print(f"Stats: {stats}")
-
-    # Archive/delete session
-    client.delete_session(session)
 ```
 
 ### 4. Model Override
@@ -178,7 +189,7 @@ Send messages using a specific model:
 ```python
 from olbrain import AgentClient
 
-with AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key") as client:
+with AgentClient(agent_id="your-agent-id", api_key="ak_your_key") as client:
     session_id = client.create_session()
 
     # Use specific model for this request
@@ -198,7 +209,7 @@ Maintain conversation context:
 ```python
 from olbrain import AgentClient
 
-with AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key") as client:
+with AgentClient(agent_id="your-agent-id", api_key="ak_your_key") as client:
     session_id = client.create_session(title="Q&A Session")
 
     # First message
@@ -229,7 +240,7 @@ from olbrain.exceptions import (
 )
 
 try:
-    client = AgentClient(agent_id="your-agent-id", api_key="sk_live_your_key")
+    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")
 
@@ -257,24 +268,21 @@ finally:
 
 ### API Key
 
-The SDK validates API keys. Valid prefixes are:
-- `sk_live_` - Production keys
-- `org_live_` - Organization keys
-- `sk_` - Test keys
-- `org_` - Test organization keys
+The SDK validates API keys. Access keys (`ak_`) are the only kind issued today; the older
+`sk_live_`, `org_live_`, `sk_` and `org_` prefixes still pass validation.
 
 ```python
 # Valid API key
 client = AgentClient(
     agent_id="your-agent-id",
-    api_key="sk_live_24c2859a0cf359b8aebbe3d8e9c60f0341d111b30004a56b428726edb354bec5"
+    api_key="ak_your_api_key_here"
 )
 ```
 
 ### Environment Variables
 
 ```bash
-export OLBRAIN_API_KEY="sk_live_your_api_key"
+export OLBRAIN_API_KEY="ak_your_api_key"
 export OLBRAIN_AGENT_ID="your-agent-id"
 ```
 
@@ -300,10 +308,10 @@ client = AgentClient(agent_id="...", api_key="...")
 ### Common Issues
 
 **"Invalid API key" error**
-- Ensure your API key starts with `sk_live_`, `org_live_`, `sk_`, or `org_`
+- Ensure your API key starts with `ak_` (or one of the older `sk_live_`, `org_live_`, `sk_`, `org_` prefixes)
 - Check that you copied the key correctly (no extra spaces)
 
-**"Stream connection failed" error**
+**"Message poll failed" in the logs**
 - Check that your agent ID is correct
 - Verify you have a stable internet connection
 - Try restarting the client
@@ -349,8 +357,8 @@ The test will:
 |--------|-----------|---------|-------------|
 | `create_session()` | `title`, `user_id`, `metadata`, `on_message`, `mode`, `description` | `str` (session_id) | Create a new chat session |
 | `get_session(session_id)` | `session_id` | `SessionInfo` | Get session details |
-| `update_session(session_id, ...)` | `session_id`, `title`, `metadata`, `status` | `SessionInfo` | Update session properties |
-| `delete_session(session_id)` | `session_id` | `Dict` | Archive/delete a session |
+| `update_session(session_id, ...)` | `session_id`, `title`, `metadata`, `status` | - | Not supported: raises `OlbrainError` (the Olbrain API has no endpoint for it) |
+| `delete_session(session_id)` | `session_id` | - | Not supported: raises `OlbrainError` (the Olbrain API has no endpoint for it) |
 | `get_messages(session_id, ...)` | `session_id`, `limit`, `offset` | `Dict` | Get message history |
 | `get_session_stats(session_id)` | `session_id` | `Dict` | Get session statistics |
 
@@ -360,7 +368,7 @@ The test will:
 |--------|-----------|---------|-------------|
 | `send(session_id, message, ...)` | `session_id`, `message`, `user_id`, `metadata`, `model` | `Dict` | Send message (async with callback) |
 | `send_and_wait(session_id, message, ...)` | `session_id`, `message`, `user_id`, `metadata`, `model`, `timeout` | `ChatResponse` | Send and wait for response |
-| `listen(session_id, on_message)` | `session_id`, `on_message` | - | Start listening to session |
+| `listen(session_id, on_message)` | `session_id`, `on_message` | - | Poll the session every 2 s and call `on_message` for each new message |
 | `run()` | - | - | Block and process streaming messages |
 | `close()` | - | - | Close client and cleanup resources |
 
@@ -461,7 +469,7 @@ python examples/basic_usage.py
 
 ## Support
 
-- **Issues**: [GitHub Issues](https://github.com/Olbrain/olbrain-python-sdk/issues)
+- **Issues**: [GitHub Issues](https://github.com/Olbrain/olbrain-sdk/issues)
 - **Documentation**: See [examples/](examples/) directory
 - **API Status**: Check [status page](https://olbrain.com/status)
 
@@ -476,6 +484,6 @@ Current version: **0.2.0**
 ## Links
 
 - [PyPI Package](https://pypi.org/project/olbrain-python-sdk/)
-- [GitHub Repository](https://github.com/Olbrain/olbrain-python-sdk)
-- [Report Issues](https://github.com/Olbrain/olbrain-python-sdk/issues)
+- [GitHub Repository](https://github.com/Olbrain/olbrain-sdk)
+- [Report Issues](https://github.com/Olbrain/olbrain-sdk/issues)
 - [Olbrain Website](https://olbrain.com)