mirasoth-agentspace 0.1.0__tar.gz

mirasoth_agentspace-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: mirasoth-agentspace
+Version: 0.1.0
+Summary: Python SDK and CLI for the Mirasoth AgentSpace API - isolated cloud workspaces for agent execution
+Author: Mirasoth Inc.
+License: Dual-licensed: AGPL-3.0-or-later or Mirasoth Commercial License
+Project-URL: Homepage, https://github.com/mirasoth/agentspace
+Keywords: agentspace,mirasoth,agent,workspace,sdk,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+
+# mirasoth-agentspace (Python)
+
+Python SDK and CLI for the [Mirasoth AgentSpace](../README.md) API —
+isolated cloud workspaces for agent execution.
+
+- **Package**: `mirasoth-agentspace` (pip name) · imported as `agentspace`
+- **CLI**: installs an `agentspace` console script, command-compatible with
+  the Go CLI (`cmd/agentspace`)
+- **Zero runtime dependencies** — pure stdlib (`urllib`), Python 3.9+
+
+## Install
+
+```sh
+pip install -e python/          # from the repo
+
+# or, once published
+pip install mirasoth-agentspace
+```
+
+## SDK quickstart
+
+```python
+from agentspace import AgentSpace, ImageAttachment, TurnHints
+
+api = AgentSpace("http://127.0.0.1:8620", "asp_...")
+
+# workspace + files
+ws = api.create_workspace("demo")
+api.upload_file(ws.id, "docs/brief.md", b"# project brief")
+entries = api.list_files(ws.id, recursive=True).entries
+
+# streaming agent turn (SSE)
+ses = api.create_session(ws.id, "main")
+reply = api.run_turn(
+    ws.id, ses.id,
+    "Read docs/brief.md and write output/summary.md with a summary.",
+    on_event=lambda ev: print(ev.data, end="") if ev.type == "delta" else None,
+)
+
+# one-shot background task (fresh agent session)
+task = api.run_task(ws.id, "Append an 'Appendix' section to output/summary.md.")
+print(task.status, task.result)
+
+# scoped handles: api.workspace(ws.id).list_files(...)
+ws_handle = api.workspace(ws.id)
+result = ws_handle.search_memory("project goals")
+```
+
+### Error handling
+
+```python
+from agentspace import (
+    AgentSpaceError, APIError, NotFoundError, ConflictError,
+    RateLimitError, TurnError, TransportError,
+)
+
+try:
+    api.run_turn(ws.id, ses.id, "...")
+except TurnError as e:        # terminal SSE `error` event
+    print(e.user_message, e.error_code)
+except ConflictError:         # a turn is already in flight (409)
+    ...
+except RateLimitError:        # service-wide concurrent turn limit (429)
+    ...
+```
+
+HTTP errors map to typed subclasses (`BadRequestError`, `NotFoundError`,
+`ConflictError`, `RateLimitError`, `ServerError`, ...); every
+`APIError` carries `.status`, `.message` and the decoded `.payload`
+(`{code, message}`). `TransportError` covers connection failures.
+
+### Streaming events
+
+`iter_session_events` / `iter_task_events` yield `StreamEvent(type, data)`
+tuples — `status`, `delta`, `thinking_step`, then a terminal
+`complete` / `error` (plus raw agent protocol `event` frames on task
+streams). The server replays the last completed reply to the first late
+subscriber, so prompt-then-attach never misses the answer.
+
+### Custom transport / testing
+
+```python
+from agentspace import AgentSpace, UrllibTransport, HTTPResponse
+
+class MyTransport(UrllibTransport):
+    def request(self, method, url, headers, body, timeout):
+        ...  # proxy, logging, retry policy...
+        return HTTPResponse(200, {}, b"{}")
+
+api = AgentSpace(base_url, api_key, transport=MyTransport())
+```
+
+## CLI
+
+Command-compatible with the Go CLI — same output formats, same config
+file (`~/.agentspace/config.json`), same env vars (`AGENTSPACE_URL`,
+`AGENTSPACE_API_KEY`). Credentials resolve as: **flags > env > config**.
+
+```sh
+agentspace config set http://127.0.0.1:8620 asp_...
+agentspace whoami
+
+agentspace workspaces create demo        # alias: ws
+agentspace ws ls --json                   # machine-readable output
+agentspace ws rename <id> new-name
+agentspace ws rm <id>                     # asks for confirmation (--yes to skip)
+
+agentspace files ls -w <ws> [path]        # alias: f
+agentspace files find -w <ws> [path]     # recursive
+agentspace files upload local.txt docs/notes.txt -w <ws>
+agentspace files download docs/notes.txt ./out -w <ws>
+agentspace files mv docs/a.txt docs/b.txt -w <ws>
+agentspace files mkdir newdir -w <ws>
+agentspace files rm -r olddir -w <ws>     # -r asks for confirmation
+
+agentspace sessions create main -w <ws>   # alias: ses
+agentspace sessions ls -w <ws>
+agentspace sessions log <ses> -w <ws>     # persisted transcript
+agentspace sessions reset <ses> -w <ws>   # fresh agent context, files kept
+agentspace sessions cancel <ses> -w <ws>
+
+agentspace send "summarize docs/notes.txt" -w <ws> -s <ses>   # prompt + stream
+agentspace attach -w <ws> -s <ses>                            # live stream only
+
+agentspace tasks create "clean up temp files" -w <ws>  # alias: task/t
+agentspace tasks get <task> -w <ws>                    # status + result
+agentspace tasks attach <task> -w <ws>                # live task events
+
+agentspace memory search "deploy notes" -w <ws> -n 5  # pgvector semantic search
+agentspace apikeys create ci                          # alias: keys
+agentspace apikeys ls
+agentspace apikeys rm <key-id>
+```
+
+Global flags (usable anywhere): `--url`, `--api-key`, `--timeout`,
+`--json`, `-v/--verbose` (status + raw agent events on stderr),
+`-y/--yes` (skip destructive confirmations). In non-interactive shells,
+destructive commands (`ws rm`, `files rm -r`) refuse to run unless
+`--yes` is passed.
+
+Exit codes: `0` success · `1` API/stream error · `2` usage / missing
+credentials / declined action.
+
+## Layout & development
+
+```
+python/
+  agentspace/     # the SDK package (import name: agentspace)
+    client.py     # AgentSpace client: REST + SSE + handles
+    models.py     # typed dataclass wire models
+    errors.py     # exception hierarchy
+    sse.py        # SSE parsing (server Go-quotes data fields)
+    cli.py        # the `agentspace` CLI
+    _config.py    # CLI credentials (shared with the Go CLI)
+  tests/          # pytest suite; no network needed (scripted fake transport)
+```
+
+```sh
+cd python
+python -m pytest            # 76 tests
+pip install -e .[dev]       # editable install with dev extras
+```
+
+End-to-end example against a live stack: `examples/python/walkthrough.py`
+in the repo root (drives this SDK; also doubles as a smoke test).

mirasoth_agentspace-0.1.0/README.md

@@ -0,0 +1,165 @@
+# mirasoth-agentspace (Python)
+
+Python SDK and CLI for the [Mirasoth AgentSpace](../README.md) API —
+isolated cloud workspaces for agent execution.
+
+- **Package**: `mirasoth-agentspace` (pip name) · imported as `agentspace`
+- **CLI**: installs an `agentspace` console script, command-compatible with
+  the Go CLI (`cmd/agentspace`)
+- **Zero runtime dependencies** — pure stdlib (`urllib`), Python 3.9+
+
+## Install
+
+```sh
+pip install -e python/          # from the repo
+
+# or, once published
+pip install mirasoth-agentspace
+```
+
+## SDK quickstart
+
+```python
+from agentspace import AgentSpace, ImageAttachment, TurnHints
+
+api = AgentSpace("http://127.0.0.1:8620", "asp_...")
+
+# workspace + files
+ws = api.create_workspace("demo")
+api.upload_file(ws.id, "docs/brief.md", b"# project brief")
+entries = api.list_files(ws.id, recursive=True).entries
+
+# streaming agent turn (SSE)
+ses = api.create_session(ws.id, "main")
+reply = api.run_turn(
+    ws.id, ses.id,
+    "Read docs/brief.md and write output/summary.md with a summary.",
+    on_event=lambda ev: print(ev.data, end="") if ev.type == "delta" else None,
+)
+
+# one-shot background task (fresh agent session)
+task = api.run_task(ws.id, "Append an 'Appendix' section to output/summary.md.")
+print(task.status, task.result)
+
+# scoped handles: api.workspace(ws.id).list_files(...)
+ws_handle = api.workspace(ws.id)
+result = ws_handle.search_memory("project goals")
+```
+
+### Error handling
+
+```python
+from agentspace import (
+    AgentSpaceError, APIError, NotFoundError, ConflictError,
+    RateLimitError, TurnError, TransportError,
+)
+
+try:
+    api.run_turn(ws.id, ses.id, "...")
+except TurnError as e:        # terminal SSE `error` event
+    print(e.user_message, e.error_code)
+except ConflictError:         # a turn is already in flight (409)
+    ...
+except RateLimitError:        # service-wide concurrent turn limit (429)
+    ...
+```
+
+HTTP errors map to typed subclasses (`BadRequestError`, `NotFoundError`,
+`ConflictError`, `RateLimitError`, `ServerError`, ...); every
+`APIError` carries `.status`, `.message` and the decoded `.payload`
+(`{code, message}`). `TransportError` covers connection failures.
+
+### Streaming events
+
+`iter_session_events` / `iter_task_events` yield `StreamEvent(type, data)`
+tuples — `status`, `delta`, `thinking_step`, then a terminal
+`complete` / `error` (plus raw agent protocol `event` frames on task
+streams). The server replays the last completed reply to the first late
+subscriber, so prompt-then-attach never misses the answer.
+
+### Custom transport / testing
+
+```python
+from agentspace import AgentSpace, UrllibTransport, HTTPResponse
+
+class MyTransport(UrllibTransport):
+    def request(self, method, url, headers, body, timeout):
+        ...  # proxy, logging, retry policy...
+        return HTTPResponse(200, {}, b"{}")
+
+api = AgentSpace(base_url, api_key, transport=MyTransport())
+```
+
+## CLI
+
+Command-compatible with the Go CLI — same output formats, same config
+file (`~/.agentspace/config.json`), same env vars (`AGENTSPACE_URL`,
+`AGENTSPACE_API_KEY`). Credentials resolve as: **flags > env > config**.
+
+```sh
+agentspace config set http://127.0.0.1:8620 asp_...
+agentspace whoami
+
+agentspace workspaces create demo        # alias: ws
+agentspace ws ls --json                   # machine-readable output
+agentspace ws rename <id> new-name
+agentspace ws rm <id>                     # asks for confirmation (--yes to skip)
+
+agentspace files ls -w <ws> [path]        # alias: f
+agentspace files find -w <ws> [path]     # recursive
+agentspace files upload local.txt docs/notes.txt -w <ws>
+agentspace files download docs/notes.txt ./out -w <ws>
+agentspace files mv docs/a.txt docs/b.txt -w <ws>
+agentspace files mkdir newdir -w <ws>
+agentspace files rm -r olddir -w <ws>     # -r asks for confirmation
+
+agentspace sessions create main -w <ws>   # alias: ses
+agentspace sessions ls -w <ws>
+agentspace sessions log <ses> -w <ws>     # persisted transcript
+agentspace sessions reset <ses> -w <ws>   # fresh agent context, files kept
+agentspace sessions cancel <ses> -w <ws>
+
+agentspace send "summarize docs/notes.txt" -w <ws> -s <ses>   # prompt + stream
+agentspace attach -w <ws> -s <ses>                            # live stream only
+
+agentspace tasks create "clean up temp files" -w <ws>  # alias: task/t
+agentspace tasks get <task> -w <ws>                    # status + result
+agentspace tasks attach <task> -w <ws>                # live task events
+
+agentspace memory search "deploy notes" -w <ws> -n 5  # pgvector semantic search
+agentspace apikeys create ci                          # alias: keys
+agentspace apikeys ls
+agentspace apikeys rm <key-id>
+```
+
+Global flags (usable anywhere): `--url`, `--api-key`, `--timeout`,
+`--json`, `-v/--verbose` (status + raw agent events on stderr),
+`-y/--yes` (skip destructive confirmations). In non-interactive shells,
+destructive commands (`ws rm`, `files rm -r`) refuse to run unless
+`--yes` is passed.
+
+Exit codes: `0` success · `1` API/stream error · `2` usage / missing
+credentials / declined action.
+
+## Layout & development
+
+```
+python/
+  agentspace/     # the SDK package (import name: agentspace)
+    client.py     # AgentSpace client: REST + SSE + handles
+    models.py     # typed dataclass wire models
+    errors.py     # exception hierarchy
+    sse.py        # SSE parsing (server Go-quotes data fields)
+    cli.py        # the `agentspace` CLI
+    _config.py    # CLI credentials (shared with the Go CLI)
+  tests/          # pytest suite; no network needed (scripted fake transport)
+```
+
+```sh
+cd python
+python -m pytest            # 76 tests
+pip install -e .[dev]       # editable install with dev extras
+```
+
+End-to-end example against a live stack: `examples/python/walkthrough.py`
+in the repo root (drives this SDK; also doubles as a smoke test).

mirasoth_agentspace-0.1.0/agentspace/__init__.py

@@ -0,0 +1,118 @@
+"""agentspace — Python SDK and CLI for the Mirasoth AgentSpace API.
+
+Distributed as ``mirasoth-agentspace`` on PyPI; imported as ``agentspace``.
+Standalone cloud service providing isolated workspaces for agent
+execution: workspace/file CRUD, streaming agent sessions (SSE), one-shot
+tasks, semantic memory search — pure stdlib, zero runtime dependencies.
+
+Quickstart::
+
+    from agentspace import AgentSpace
+
+    api = AgentSpace("http://127.0.0.1:8620", "asp_...")
+    ws = api.create_workspace("demo")
+    api.upload_file(ws.id, "docs/brief.md", b"# brief")
+
+    ses = api.create_session(ws.id, "main")
+    reply = api.run_turn(ws.id, ses.id, "Read docs/brief.md and summarize it.")
+
+The package also installs an ``agentspace`` console script (see
+:mod:`agentspace.cli`).
+"""
+
+from .client import (
+    DEFAULT_TIMEOUT,
+    AgentSpace,
+    AgentSpaceClient,
+    HTTPResponse,
+    SessionHandle,
+    TaskHandle,
+    Transport,
+    UrllibTransport,
+    WorkspaceHandle,
+)
+from .errors import (
+    AgentSpaceError,
+    APIError,
+    BadRequestError,
+    ConflictError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    TransportError,
+    TurnError,
+    UnauthorizedError,
+)
+from .models import (
+    TASK_TERMINAL_STATUSES,
+    ApiKey,
+    ApiKeyCreated,
+    ApiKeyList,
+    FileEntry,
+    FileEntryList,
+    Identity,
+    ImageAttachment,
+    Session,
+    SessionList,
+    SessionMessage,
+    SessionMessageList,
+    Task,
+    TaskList,
+    TurnAccepted,
+    TurnHints,
+    Workspace,
+    WorkspaceList,
+)
+from .sse import StreamEvent, parse_error_payload, parse_sse_stream
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # client
+    "AgentSpace",
+    "AgentSpaceClient",
+    "WorkspaceHandle",
+    "SessionHandle",
+    "TaskHandle",
+    "Transport",
+    "UrllibTransport",
+    "HTTPResponse",
+    "DEFAULT_TIMEOUT",
+    # errors
+    "AgentSpaceError",
+    "APIError",
+    "BadRequestError",
+    "UnauthorizedError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "ServerError",
+    "TransportError",
+    "TurnError",
+    # models
+    "Identity",
+    "Workspace",
+    "WorkspaceList",
+    "FileEntry",
+    "FileEntryList",
+    "Session",
+    "SessionList",
+    "SessionMessage",
+    "SessionMessageList",
+    "TurnAccepted",
+    "TurnHints",
+    "Task",
+    "TaskList",
+    "TASK_TERMINAL_STATUSES",
+    "ApiKey",
+    "ApiKeyCreated",
+    "ApiKeyList",
+    "ImageAttachment",
+    # sse
+    "StreamEvent",
+    "parse_sse_stream",
+    "parse_error_payload",
+]

mirasoth_agentspace-0.1.0/agentspace/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m agentspace`` — delegates to the ``agentspace`` CLI."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

mirasoth_agentspace-0.1.0/agentspace/_config.py

@@ -0,0 +1,57 @@
+"""CLI credential storage, file-compatible with the Go CLI.
+
+The Go CLI (``cmd/agentspace``) and this Python CLI share the same config
+file (``~/.agentspace/config.json`` with ``{"url": ..., "apiKey": ...}``)
+and the same environment variables (``AGENTSPACE_URL`` /
+``AGENTSPACE_API_KEY``), so either CLI can pick up where the other left
+off. Environment variables always win over the file.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Tuple
+
+ENV_URL = "AGENTSPACE_URL"
+ENV_API_KEY = "AGENTSPACE_API_KEY"
+ENV_CONFIG = "AGENTSPACE_CONFIG"
+
+
+def config_file() -> Path:
+    """Location of the shared CLI config file."""
+    override = os.environ.get(ENV_CONFIG)
+    if override:
+        return Path(override)
+    return Path.home() / ".agentspace" / "config.json"
+
+
+def load_config() -> Tuple[str, str]:
+    """Resolve credentials: env vars win over the config file. May be empty."""
+    stored: dict = {}
+    path = config_file()
+    try:
+        stored = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(stored, dict):
+            stored = {}
+    except (OSError, ValueError):
+        stored = {}
+    url = os.environ.get(ENV_URL, "") or str(stored.get("url") or "")
+    api_key = os.environ.get(ENV_API_KEY, "") or str(stored.get("apiKey") or "")
+    return url, api_key
+
+
+def save_config(url: str, api_key: str) -> Path:
+    """Persist credentials to the shared config file (created 0600)."""
+    path = config_file()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps({"url": url, "apiKey": api_key}, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    try:
+        path.chmod(0o600)
+    except OSError:
+        pass  # e.g. some filesystems ignore POSIX modes
+    return path