aex-brain 1.0.0__tar.gz

aex_brain-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Weilue Luo
+
+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.

aex_brain-1.0.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: aex-brain
+Version: 1.0.0
+Summary: Typed Python client for Brain sessions, tools, checkpoints, and event streams
+Author: AEX
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Classifier: Operating System :: OS Independent
+License-File: LICENSE
+Project-URL: Documentation, https://aexhq.github.io/brain/docs/sdks/python/
+Project-URL: Issues, https://github.com/aexhq/brain/issues
+Project-URL: Source, https://github.com/aexhq/brain
+
+# Brain Python SDK
+
+Install with `python -m pip install aex-brain==1.0.0`. Requires Python 3.11+;
+there are no runtime dependencies. Import the client from `brain` and generated
+`TypedDict` definitions from `brain.types`. The wheel includes PEP 561 type data.
+
+```python
+import os
+from contextlib import closing
+from brain import Brain
+
+brain = Brain('http://127.0.0.1:8080', os.environ['BRAIN_API_KEY'])
+session = brain.create({
+    'harness': 'pi', 'config': {'model': 'openai/gpt-4.1-mini', 'tools': []},
+})
+message = brain.send(session['id'], {'type': 'user.message', 'text': 'Hello!'})
+with closing(brain.observe(session['id'])) as events:
+    for event in events:
+        if event['type'] == 'assistant.message':
+            print(event['data']['text'])
+        if event.get('input_id') != message['id']:
+            continue
+        if event['type'] == 'session.error':
+            raise RuntimeError(event['data']['message'])
+        if event['type'] == 'session.status' and event['data']['status'] == 'idle':
+            break
+```
+
+This is a synchronous client. `timeout=30` configures the socket timeout, including
+stream reads. Requests are never automatically retried. `BrainError` preserves the
+HTTP status, server error code, and request ID. Closing the observer does not stop
+execution; call `interrupt(session_id)` for that.
+
+Pin the package and matching server image commit recorded by the release workflow.
+[SDK reference](https://aexhq.github.io/brain/docs/sdks/python/) ·
+[Server setup](https://aexhq.github.io/brain/docs/quickstart/)
+

aex_brain-1.0.0/README.md

@@ -0,0 +1,36 @@
+# Brain Python SDK
+
+Install with `python -m pip install aex-brain==1.0.0`. Requires Python 3.11+;
+there are no runtime dependencies. Import the client from `brain` and generated
+`TypedDict` definitions from `brain.types`. The wheel includes PEP 561 type data.
+
+```python
+import os
+from contextlib import closing
+from brain import Brain
+
+brain = Brain('http://127.0.0.1:8080', os.environ['BRAIN_API_KEY'])
+session = brain.create({
+    'harness': 'pi', 'config': {'model': 'openai/gpt-4.1-mini', 'tools': []},
+})
+message = brain.send(session['id'], {'type': 'user.message', 'text': 'Hello!'})
+with closing(brain.observe(session['id'])) as events:
+    for event in events:
+        if event['type'] == 'assistant.message':
+            print(event['data']['text'])
+        if event.get('input_id') != message['id']:
+            continue
+        if event['type'] == 'session.error':
+            raise RuntimeError(event['data']['message'])
+        if event['type'] == 'session.status' and event['data']['status'] == 'idle':
+            break
+```
+
+This is a synchronous client. `timeout=30` configures the socket timeout, including
+stream reads. Requests are never automatically retried. `BrainError` preserves the
+HTTP status, server error code, and request ID. Closing the observer does not stop
+execution; call `interrupt(session_id)` for that.
+
+Pin the package and matching server image commit recorded by the release workflow.
+[SDK reference](https://aexhq.github.io/brain/docs/sdks/python/) ·
+[Server setup](https://aexhq.github.io/brain/docs/quickstart/)

aex_brain-1.0.0/brain/__init__.py

@@ -0,0 +1,110 @@
+"""Small synchronous Brain client. Requests are never automatically retried."""
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from typing import Any
+from urllib.error import HTTPError
+from urllib.parse import quote, urlencode
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+from .types import CreateSession, Event, EventList, Input, Session, SessionList, SyncStatus, ToolCatalog
+
+__all__ = ["Brain", "BrainError"]
+
+
+class BrainError(Exception):
+    def __init__(self, status: int, code: str, message: str, request_id: str | None = None):
+        super().__init__(message)
+        self.status, self.code, self.request_id = status, code, request_id
+
+
+class _NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+class Brain:
+    def __init__(self, url: str, token: str, timeout: float = 30):
+        self.url, self.token, self.timeout = url.rstrip("/"), token, timeout
+        self._opener = build_opener(_NoRedirect())
+
+    def _open(self, method: str, path: str, body: Any = None, stream: bool = False):
+        headers = {"Authorization": f"Bearer {self.token}", "Content-Type": "application/json"}
+        if stream:
+            headers["Accept"] = "text/event-stream"
+        req = Request(self.url + path, data=None if body is None else json.dumps(body).encode(), headers=headers, method=method)
+        try:
+            return self._opener.open(req, timeout=self.timeout)
+        except HTTPError as error:
+            try:
+                payload = json.loads(error.read(1 << 20))
+            except (ValueError, UnicodeError):
+                payload = {}
+            finally:
+                error.close()
+            detail = payload.get("error", {})
+            raise BrainError(error.code, detail.get("code", "http_error"), detail.get("message", str(error)), payload.get("request_id")) from error
+
+    def _request(self, method: str, path: str, body: Any = None) -> Any:
+        with self._open(method, path, body) as response:
+            return json.load(response)
+
+    def create(self, config: CreateSession) -> Session:
+        return self._request("POST", "/sessions", config)
+
+    def get(self, session_id: str) -> Session:
+        return self._request("GET", f"/sessions/{quote(session_id, safe='')}")
+
+    def list(self, after: str = "", limit: int = 100) -> SessionList:
+        return self._request("GET", "/sessions?" + urlencode({"after": after, "limit": limit}))
+
+    def send(self, session_id: str, event: Input) -> Event:
+        return self._request("POST", f"/sessions/{quote(session_id, safe='')}/events", event)
+
+    def interrupt(self, session_id: str) -> None:
+        self.send(session_id, {"type": "user.interrupt"})
+
+    def resume(self, session_id: str) -> Session:
+        return self._request("POST", f"/sessions/{quote(session_id, safe='')}/resume")
+
+    def close(self, session_id: str) -> None:
+        self._request("POST", f"/sessions/{quote(session_id, safe='')}/close")
+
+    def flush(self, session_id: str) -> SyncStatus:
+        return self._request("POST", f"/sessions/{quote(session_id, safe='')}/flush")
+
+    def sync(self, session_id: str) -> SyncStatus:
+        return self._request("GET", f"/sessions/{quote(session_id, safe='')}/sync")
+
+    def restore(self, session_id: str, checkpoint: str) -> Session:
+        return self._request("POST", f"/sessions/{quote(session_id, safe='')}/restore", {"checkpoint": checkpoint})
+
+    def catalog(self) -> ToolCatalog:
+        return self._request("GET", "/catalog")
+
+    def history(self, session_id: str, after: str = "", limit: int = 100) -> EventList:
+        return self._request("GET", f"/sessions/{quote(session_id, safe='')}/events?" + urlencode({"after": after, "limit": limit}))
+
+    def observe(self, session_id: str, after: str = "") -> Iterator[Event]:
+        path = f"/sessions/{quote(session_id, safe='')}/events?" + urlencode({"after": after})
+        with self._open("GET", path, stream=True) as response:
+            data: list[str] = []
+            size = 0
+            while True:
+                line = response.readline((4 << 20) + 1)
+                size += len(line)
+                if size > 4 << 20:
+                    raise ValueError("event exceeds client limit")
+                if not line:
+                    if data:
+                        raise ValueError("incomplete event stream")
+                    return
+                text = line.decode().rstrip("\r\n")
+                if not text:
+                    if data:
+                        yield json.loads("\n".join(data))
+                    data, size = [], 0
+                elif text.startswith("data:"):
+                    data.append(text[5:].removeprefix(" "))
+

aex_brain-1.0.0/brain/types.py

@@ -0,0 +1,101 @@
+# Generated by go run ./cmd/generate; do not edit.
+from __future__ import annotations
+from typing import Any, NotRequired, TypedDict
+
+class Call(TypedDict):
+    id: str
+    name: str
+    arguments: Any
+
+class Checkpoint(TypedDict):
+    id: str
+    offset: int
+    time: str
+
+class Content(TypedDict):
+    type: str
+    text: NotRequired[str]
+    data: NotRequired[str]
+    mime_type: NotRequired[str]
+
+class CreateSession(TypedDict):
+    harness: str
+    config: SessionConfig
+
+class ErrorDetail(TypedDict):
+    code: str
+    message: str
+
+class ErrorResponse(TypedDict):
+    error: ErrorDetail
+    request_id: str
+
+class Event(TypedDict):
+    id: str
+    type: str
+    time: str
+    input_id: NotRequired[str]
+    data: Any
+    cursor: NotRequired[str]
+
+class EventList(TypedDict):
+    events: list[Event]
+    next_cursor: str
+
+class Input(TypedDict):
+    type: str
+    text: NotRequired[str]
+    delivery: NotRequired[str]
+    key: NotRequired[str]
+
+class Restore(TypedDict):
+    checkpoint: str
+
+class Result(TypedDict):
+    content: list[Content]
+    is_error: NotRequired[bool]
+    unknown_outcome: NotRequired[bool]
+
+class Session(TypedDict):
+    id: str
+    harness: str
+    config: SessionConfig
+    status: str
+    created_at: str
+    updated_at: str
+    checkpoint: NotRequired[Checkpoint]
+
+class SessionConfig(TypedDict):
+    model: str
+    reasoning_effort: NotRequired[str]
+    instructions: NotRequired[str]
+    tools: list[str]
+
+class SessionList(TypedDict):
+    sessions: list[Session]
+
+class Status(TypedDict):
+    status: str
+
+class SyncStatus(TypedDict):
+    checkpoint: NotRequired[str]
+    history_bytes: int
+    resume_offset: int
+    native_checkpoint: NotRequired[str]
+    time: NotRequired[str]
+    pending: bool
+    error: NotRequired[str]
+
+class Tool(TypedDict):
+    name: str
+    description: str
+    input_schema: Any
+    output_schema: NotRequired[Any]
+
+class ToolCatalog(TypedDict):
+    tools: list[Tool]
+
+class ToolResult(TypedDict):
+    call_id: str
+    result: Result
+

aex_brain-1.0.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["flit_core==3.12.0"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "aex-brain"
+version = "1.0.0"
+description = "Typed Python client for Brain sessions, tools, checkpoints, and event streams"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "AEX"}]
+classifiers = ["Programming Language :: Python :: 3", "Typing :: Typed", "Operating System :: OS Independent"]
+
+[project.urls]
+Documentation = "https://aexhq.github.io/brain/docs/sdks/python/"
+Source = "https://github.com/aexhq/brain"
+Issues = "https://github.com/aexhq/brain/issues"
+
+[tool.flit.module]
+name = "brain"
+
+[tool.flit.sdist]
+include = ["test_client.py"]

aex_brain-1.0.0/test_client.py

@@ -0,0 +1,34 @@
+import io
+import unittest
+from urllib.error import HTTPError
+from brain import Brain, BrainError
+
+
+class ClientTests(unittest.TestCase):
+    def test_no_retry_and_error_identity(self):
+        client = Brain("http://brain.test", "token")
+        class Opener:
+            calls = 0
+            def open(self, request, **kwargs):
+                self.calls += 1
+                raise HTTPError(request.full_url, 429, "busy", {}, io.BytesIO(b'{"error":{"code":"overloaded","message":"busy"},"request_id":"request"}'))
+        opener = Opener()
+        client._opener = opener
+        with self.assertRaises(BrainError) as raised:
+            client.send("session", {"type": "user.message", "text": "hello"})
+        self.assertEqual(opener.calls, 1)
+        self.assertEqual(raised.exception.code, "overloaded")
+        self.assertEqual(raised.exception.request_id, "request")
+
+    def test_stream_comments_and_utf8(self):
+        client = Brain("http://brain.test", "token")
+        class Opener:
+            def open(self, request, **kwargs):
+                return io.BytesIO(': keepalive\n\ndata: {"id":"one","data":{"text":"你好"}}\n\n'.encode())
+        client._opener = Opener()
+        self.assertEqual(list(client.observe("session"))[0]["data"]["text"], "你好")
+
+
+if __name__ == "__main__":
+    unittest.main()
+