brickly-sdk 0.1.0__tar.gz

brickly_sdk-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+dist/
+build/
+*.egg-info/

brickly_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: brickly-sdk
+Version: 0.1.0
+Summary: Python SDK for Brickly brick runtimes.
+Author: Brickly
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# brickly-sdk-python
+
+Python SDK for Brickly brick runtimes. It speaks BPP over stdin/stdout and keeps stdout reserved for protocol messages.
+
+## Quick Start
+
+```python
+from brickly import BricklyRuntime
+
+brick = BricklyRuntime("com.example.python")
+
+
+@brick.on_command("hello")
+def hello(ctx, input):
+    ctx.progress(0.5, "working...")
+    ctx.chunk("hello\n")
+    return {"ok": True, "input": input}
+
+
+brick.run()
+```
+
+The SDK handles:
+
+- `host.hello` -> `runtime.ready`
+- `runtime.ping` -> `runtime.pong`
+- `command.invoke` dispatch
+- `command.cancel` via `ctx.cancel_event`, `ctx.is_cancelled()`, and `ctx.on_cancel(...)`
+- `command.progress`, `command.chunk`, and `command.output`
+- `host.*` request id allocation and `host.result` / `host.error` routing
+- `runtime.shutdown` -> optional shutdown hook -> `runtime.bye`
+- `ui.create_browser_window`, `WindowHandle.call(...)`, and event routing for `window.*`
+- `events.publish(...)` and `events.on(...)`
+- `brick.platform.system.*` / `ctx.platform.system.*`, plus `brick.system.*` / `ctx.system.*` aliases
+- `brick.invoke(...)` / `ctx.invoke(...)` for child cross-brick command calls inside command scope
+- `brick.invoke_root(...)` for root cross-brick command calls outside command scope
+- `brick.invoke_stream(...)` / `ctx.invoke_stream(...)` for streaming child cross-brick command calls
+- `brick.open_session(...)` / `ctx.open_session(...)` for stateful cross-brick sessions
+- `brick.platform.clipboard.read_content()` / `set_content(...)`
+
+## Logging
+
+`brick.log(...)` writes plain messages to stderr. Stdout is reserved for BPP protocol messages. The Brickly host log center attaches the brick id, source, stream, and scope metadata when collecting stderr, so brick code should not add a `[brickId]` prefix by itself.
+
+## Window Example
+
+```python
+from brickly import BricklyRuntime
+
+brick = BricklyRuntime("com.example.window")
+
+
+@brick.on_command("open")
+def open_window(ctx, input):
+    win = ctx.ui.create_browser_window("ui/index.html", {"width": 640, "height": 480})
+    win.on("closed", lambda payload: brick.log("closed", payload))
+    win.set_title("Hello from Python")
+    return {"windowId": win.id}
+
+
+brick.run()
+```
+
+## Cross-Brick Invoke
+
+Inside a command handler, use `ctx.invoke` to call another brick command. The SDK automatically sends the current `parentRequestId`, so the host attaches the child call to the same invocation graph. Brickly starts, reuses, and recycles the target brick instance automatically. Pass `profile_id` when the target brick should run with a specific Profile; omit it to use the target brick's default Profile.
+
+```python
+result = ctx.invoke(
+    "com.brickly.openai",
+    "chat",
+    {"prompt": "hello"},
+    profile_id="work",
+)
+```
+
+Use `invoke_stream` when the target command emits progress, chunks, or named outputs before its final result. The SDK sends `host.invoke` with `stream: true` and yields events in host order:
+
+```python
+for event in ctx.invoke_stream("com.brickly.openai", "chat", {"prompt": "hello"}):
+    if event["type"] == "progress":
+        ctx.progress(event.get("progress", 0), event.get("message"))
+    elif event["type"] == "chunk":
+        ctx.chunk(event.get("chunk"))
+    elif event["type"] == "output":
+        ctx.output(event["name"], event.get("value"))
+    elif event["type"] == "result":
+        return event["result"]
+```
+
+If the host returns `host.error`, `invoke_stream` raises `BppError`, matching normal `invoke` error handling.
+
+To create a top-level cross-brick call outside command scope, use the explicit root API:
+
+```python
+result = brick.invoke_root(
+    "com.brickly.openai",
+    "chat",
+    {"prompt": "hello"},
+    profile_id="work",
+)
+```
+
+The caller manifest must declare the target brick and allowed commands in `dependencies`:
+
+```json
+"dependencies": {
+  "com.brickly.openai": {
+    "commands": ["chat"]
+  }
+}
+```
+
+## Platform System API
+
+`brick.platform.system.*`, `brick.system.*`, `ctx.platform.system.*`, and `ctx.system.*` call host system capabilities through BPP `host.platform.system.*`:
+
+```python
+@brick.on_command("show-app-info")
+def show_app_info(ctx, _input):
+    return {
+        "appName": ctx.system.get_app_name(),
+        "appVersion": ctx.system.get_app_version(),
+        "userData": ctx.system.get_path("userData"),
+        "isMacOS": ctx.system.is_macos(),
+    }
+```
+
+Current methods are `show_notification`, `shell_open_path`, `shell_trash_item`, `shell_show_item_in_folder`, `shell_open_external`, `shell_beep`, `get_native_id`, `get_app_name`, `get_app_version`, `get_path`, `get_file_icon`, `read_current_folder_path`, `read_current_browser_url`, `is_dev`, `is_macos`, `is_windows`, and `is_linux`.
+
+`get_path()` supports `home`, `appData`, `assets`, `userData`, `sessionData`, `temp`, `exe`, `module`, `desktop`, `documents`, `downloads`, `music`, `pictures`, `videos`, `recent`, `logs`, and `crashDumps`. Runtime calls are still checked by manifest permissions on the host side: notifications require `os.notification`; Shell capabilities require `os.exec`; app info, paths, native ID, platform checks, and current folder path reads require `os.env`; file icons require `fs.read`. `read_current_folder_path()` works when Finder is frontmost on macOS or Explorer is frontmost on Windows; it raises `CURRENT_FOLDER_UNAVAILABLE` when no readable foreground file-manager folder is available. `read_current_browser_url()` is reserved and currently returns `UNSUPPORTED_PLATFORM`.
+
+## Platform Clipboard API
+
+`brick.platform.clipboard.*` and `ctx.platform.clipboard.*` call host clipboard capabilities through BPP `host.platform.clipboard.*`:
+
+```python
+@brick.on_command("replace-clipboard")
+def replace_clipboard(ctx, _input):
+    previous = ctx.platform.clipboard.read_content()
+    updated = ctx.platform.clipboard.set_content({"kind": "text", "text": "Updated by Python"})
+    return {"previous": previous, "updated": updated}
+```
+
+Current methods are `read_content()` and `set_content(content)`.
+
+## Cross-Brick Sessions
+
+Use `ctx.open_session` when the target brick keeps in-memory state that must survive across multiple command calls. Calls through the same session are routed to the same target brick instance, and each `session.invoke` automatically carries the current `parentRequestId`, until `close()` is called or the caller brick instance exits.
+
+```python
+session = ctx.open_session("com.brickly.openai", profile_id="work")
+
+try:
+    session.invoke("start-thread", {"title": "Draft"})
+    reply = session.invoke("chat", {"prompt": "continue the thread"})
+finally:
+    session.close()
+```
+
+`profile_id` is the target brick Profile ID. Session invokes are checked against the caller manifest's `dependencies[target].commands` on every command call.
+
+## Errors
+
+Raise `BppError` to preserve a specific Brickly error code:
+
+```python
+from brickly import BppError
+
+raise BppError("INVALID_INPUT", "url is required")
+```

brickly_sdk-0.1.0/README.md

@@ -0,0 +1,171 @@
+# brickly-sdk-python
+
+Python SDK for Brickly brick runtimes. It speaks BPP over stdin/stdout and keeps stdout reserved for protocol messages.
+
+## Quick Start
+
+```python
+from brickly import BricklyRuntime
+
+brick = BricklyRuntime("com.example.python")
+
+
+@brick.on_command("hello")
+def hello(ctx, input):
+    ctx.progress(0.5, "working...")
+    ctx.chunk("hello\n")
+    return {"ok": True, "input": input}
+
+
+brick.run()
+```
+
+The SDK handles:
+
+- `host.hello` -> `runtime.ready`
+- `runtime.ping` -> `runtime.pong`
+- `command.invoke` dispatch
+- `command.cancel` via `ctx.cancel_event`, `ctx.is_cancelled()`, and `ctx.on_cancel(...)`
+- `command.progress`, `command.chunk`, and `command.output`
+- `host.*` request id allocation and `host.result` / `host.error` routing
+- `runtime.shutdown` -> optional shutdown hook -> `runtime.bye`
+- `ui.create_browser_window`, `WindowHandle.call(...)`, and event routing for `window.*`
+- `events.publish(...)` and `events.on(...)`
+- `brick.platform.system.*` / `ctx.platform.system.*`, plus `brick.system.*` / `ctx.system.*` aliases
+- `brick.invoke(...)` / `ctx.invoke(...)` for child cross-brick command calls inside command scope
+- `brick.invoke_root(...)` for root cross-brick command calls outside command scope
+- `brick.invoke_stream(...)` / `ctx.invoke_stream(...)` for streaming child cross-brick command calls
+- `brick.open_session(...)` / `ctx.open_session(...)` for stateful cross-brick sessions
+- `brick.platform.clipboard.read_content()` / `set_content(...)`
+
+## Logging
+
+`brick.log(...)` writes plain messages to stderr. Stdout is reserved for BPP protocol messages. The Brickly host log center attaches the brick id, source, stream, and scope metadata when collecting stderr, so brick code should not add a `[brickId]` prefix by itself.
+
+## Window Example
+
+```python
+from brickly import BricklyRuntime
+
+brick = BricklyRuntime("com.example.window")
+
+
+@brick.on_command("open")
+def open_window(ctx, input):
+    win = ctx.ui.create_browser_window("ui/index.html", {"width": 640, "height": 480})
+    win.on("closed", lambda payload: brick.log("closed", payload))
+    win.set_title("Hello from Python")
+    return {"windowId": win.id}
+
+
+brick.run()
+```
+
+## Cross-Brick Invoke
+
+Inside a command handler, use `ctx.invoke` to call another brick command. The SDK automatically sends the current `parentRequestId`, so the host attaches the child call to the same invocation graph. Brickly starts, reuses, and recycles the target brick instance automatically. Pass `profile_id` when the target brick should run with a specific Profile; omit it to use the target brick's default Profile.
+
+```python
+result = ctx.invoke(
+    "com.brickly.openai",
+    "chat",
+    {"prompt": "hello"},
+    profile_id="work",
+)
+```
+
+Use `invoke_stream` when the target command emits progress, chunks, or named outputs before its final result. The SDK sends `host.invoke` with `stream: true` and yields events in host order:
+
+```python
+for event in ctx.invoke_stream("com.brickly.openai", "chat", {"prompt": "hello"}):
+    if event["type"] == "progress":
+        ctx.progress(event.get("progress", 0), event.get("message"))
+    elif event["type"] == "chunk":
+        ctx.chunk(event.get("chunk"))
+    elif event["type"] == "output":
+        ctx.output(event["name"], event.get("value"))
+    elif event["type"] == "result":
+        return event["result"]
+```
+
+If the host returns `host.error`, `invoke_stream` raises `BppError`, matching normal `invoke` error handling.
+
+To create a top-level cross-brick call outside command scope, use the explicit root API:
+
+```python
+result = brick.invoke_root(
+    "com.brickly.openai",
+    "chat",
+    {"prompt": "hello"},
+    profile_id="work",
+)
+```
+
+The caller manifest must declare the target brick and allowed commands in `dependencies`:
+
+```json
+"dependencies": {
+  "com.brickly.openai": {
+    "commands": ["chat"]
+  }
+}
+```
+
+## Platform System API
+
+`brick.platform.system.*`, `brick.system.*`, `ctx.platform.system.*`, and `ctx.system.*` call host system capabilities through BPP `host.platform.system.*`:
+
+```python
+@brick.on_command("show-app-info")
+def show_app_info(ctx, _input):
+    return {
+        "appName": ctx.system.get_app_name(),
+        "appVersion": ctx.system.get_app_version(),
+        "userData": ctx.system.get_path("userData"),
+        "isMacOS": ctx.system.is_macos(),
+    }
+```
+
+Current methods are `show_notification`, `shell_open_path`, `shell_trash_item`, `shell_show_item_in_folder`, `shell_open_external`, `shell_beep`, `get_native_id`, `get_app_name`, `get_app_version`, `get_path`, `get_file_icon`, `read_current_folder_path`, `read_current_browser_url`, `is_dev`, `is_macos`, `is_windows`, and `is_linux`.
+
+`get_path()` supports `home`, `appData`, `assets`, `userData`, `sessionData`, `temp`, `exe`, `module`, `desktop`, `documents`, `downloads`, `music`, `pictures`, `videos`, `recent`, `logs`, and `crashDumps`. Runtime calls are still checked by manifest permissions on the host side: notifications require `os.notification`; Shell capabilities require `os.exec`; app info, paths, native ID, platform checks, and current folder path reads require `os.env`; file icons require `fs.read`. `read_current_folder_path()` works when Finder is frontmost on macOS or Explorer is frontmost on Windows; it raises `CURRENT_FOLDER_UNAVAILABLE` when no readable foreground file-manager folder is available. `read_current_browser_url()` is reserved and currently returns `UNSUPPORTED_PLATFORM`.
+
+## Platform Clipboard API
+
+`brick.platform.clipboard.*` and `ctx.platform.clipboard.*` call host clipboard capabilities through BPP `host.platform.clipboard.*`:
+
+```python
+@brick.on_command("replace-clipboard")
+def replace_clipboard(ctx, _input):
+    previous = ctx.platform.clipboard.read_content()
+    updated = ctx.platform.clipboard.set_content({"kind": "text", "text": "Updated by Python"})
+    return {"previous": previous, "updated": updated}
+```
+
+Current methods are `read_content()` and `set_content(content)`.
+
+## Cross-Brick Sessions
+
+Use `ctx.open_session` when the target brick keeps in-memory state that must survive across multiple command calls. Calls through the same session are routed to the same target brick instance, and each `session.invoke` automatically carries the current `parentRequestId`, until `close()` is called or the caller brick instance exits.
+
+```python
+session = ctx.open_session("com.brickly.openai", profile_id="work")
+
+try:
+    session.invoke("start-thread", {"title": "Draft"})
+    reply = session.invoke("chat", {"prompt": "continue the thread"})
+finally:
+    session.close()
+```
+
+`profile_id` is the target brick Profile ID. Session invokes are checked against the caller manifest's `dependencies[target].commands` on every command call.
+
+## Errors
+
+Raise `BppError` to preserve a specific Brickly error code:
+
+```python
+from brickly import BppError
+
+raise BppError("INVALID_INPUT", "url is required")
+```

brickly_sdk-0.1.0/brickly/__init__.py

@@ -0,0 +1,31 @@
+from .api import (
+    BricklyRuntime,
+    CommandContext,
+    EventEnvelope,
+    EventsApi,
+    UiApi,
+    WebContentsApi,
+    WindowHandle,
+)
+from .errors import BppError, payload_to_error
+from .protocol import PROTOCOL_VERSION, PlatformSystemPathName
+from .runtime import BppTransport
+from .system import ClipboardApi, PlatformApi, SystemApi
+
+__all__ = [
+    "BppError",
+    "BppTransport",
+    "BricklyRuntime",
+    "ClipboardApi",
+    "CommandContext",
+    "EventEnvelope",
+    "EventsApi",
+    "PlatformApi",
+    "PROTOCOL_VERSION",
+    "PlatformSystemPathName",
+    "SystemApi",
+    "UiApi",
+    "WebContentsApi",
+    "WindowHandle",
+    "payload_to_error",
+]