acontext 0.0.1.dev0__tar.gz

acontext-0.0.1.dev0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.3
+Name: acontext
+Version: 0.0.1.dev0
+Summary: Python SDK for the Acontext API
+Keywords: acontext,sdk,client,api
+Requires-Dist: httpx>=0.28.1
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/memodb-io/Acontext
+Project-URL: Issues, https://github.com/memodb-io/Acontext/issues
+Project-URL: Repository, https://github.com/memodb-io/Acontext
+Description-Content-Type: text/markdown
+
+## acontext client for python
+
+Python SDK for interacting with the Acontext REST API.
+
+### Installation
+
+```bash
+pip install acontext
+```
+
+> Requires Python 3.13 or newer.
+
+### Quickstart
+
+```python
+from acontext import AcontextClient, MessagePart
+
+with AcontextClient(api_key="sk_project_token") as client:
+    # List spaces for the authenticated project
+    spaces = client.spaces.list()
+
+    # Create a session bound to the first space
+    session = client.sessions.create(space_id=spaces[0]["id"])
+
+    # Send a text message to the session
+    client.sessions.send_message(
+        session["id"],
+        role="user",
+        parts=[MessagePart.text_part("Hello from Python!")],
+    )
+```
+
+See the inline docstrings for the full list of helpers covering sessions, spaces, artifacts and file uploads.
+
+### Working with pages and blocks
+
+```python
+from acontext import AcontextClient
+
+client = AcontextClient(api_key="sk_project_token")
+
+space = client.spaces.create()
+try:
+    page = client.pages.create(space["id"], title="Kick-off Notes")
+    client.blocks.create(
+        space["id"],
+        parent_id=page["id"],
+        block_type="text",
+        title="First block",
+        props={"text": "Plan the sprint goals"},
+    )
+finally:
+    client.close()
+```

acontext-0.0.1.dev0/README.md

@@ -0,0 +1,54 @@
+## acontext client for python
+
+Python SDK for interacting with the Acontext REST API.
+
+### Installation
+
+```bash
+pip install acontext
+```
+
+> Requires Python 3.13 or newer.
+
+### Quickstart
+
+```python
+from acontext import AcontextClient, MessagePart
+
+with AcontextClient(api_key="sk_project_token") as client:
+    # List spaces for the authenticated project
+    spaces = client.spaces.list()
+
+    # Create a session bound to the first space
+    session = client.sessions.create(space_id=spaces[0]["id"])
+
+    # Send a text message to the session
+    client.sessions.send_message(
+        session["id"],
+        role="user",
+        parts=[MessagePart.text_part("Hello from Python!")],
+    )
+```
+
+See the inline docstrings for the full list of helpers covering sessions, spaces, artifacts and file uploads.
+
+### Working with pages and blocks
+
+```python
+from acontext import AcontextClient
+
+client = AcontextClient(api_key="sk_project_token")
+
+space = client.spaces.create()
+try:
+    page = client.pages.create(space["id"], title="Kick-off Notes")
+    client.blocks.create(
+        space["id"],
+        parent_id=page["id"],
+        block_type="text",
+        title="First block",
+        props={"text": "Plan the sprint goals"},
+    )
+finally:
+    client.close()
+```

acontext-0.0.1.dev0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "acontext"
+version = "0.0.1.dev0"
+description = "Python SDK for the Acontext API"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = ["httpx>=0.28.1"]
+keywords = ["acontext", "sdk", "client", "api"]
+
+[project.urls]
+Homepage = "https://github.com/memodb-io/Acontext"
+Repository = "https://github.com/memodb-io/Acontext"
+Issues = "https://github.com/memodb-io/Acontext/issues"
+
+[dependency-groups]
+dev = ["pytest", "ruff"]
+
+[build-system]
+requires = ["uv_build>=0.9.2,<0.10.0"]
+build-backend = "uv_build"

acontext-0.0.1.dev0/src/acontext/__init__.py

@@ -0,0 +1,33 @@
+"""
+Python SDK for the Acontext API.
+"""
+
+from importlib import metadata as _metadata
+
+from .client import AcontextClient, FileUpload, MessagePart
+from .resources import (
+    ArtifactFilesAPI,
+    ArtifactsAPI,
+    BlocksAPI,
+    PagesAPI,
+    SessionsAPI,
+    SpacesAPI,
+)
+
+__all__ = [
+    "AcontextClient",
+    "FileUpload",
+    "MessagePart",
+    "ArtifactsAPI",
+    "ArtifactFilesAPI",
+    "BlocksAPI",
+    "PagesAPI",
+    "SessionsAPI",
+    "SpacesAPI",
+    "__version__",
+]
+
+try:
+    __version__ = _metadata.version("acontext")
+except _metadata.PackageNotFoundError:  # pragma: no cover - local/checkout usage
+    __version__ = "0.0.0"

acontext-0.0.1.dev0/src/acontext/_constants.py

@@ -0,0 +1,15 @@
+"""
+Internal constants shared across the Python SDK.
+"""
+
+from importlib import metadata as _metadata
+
+DEFAULT_BASE_URL = "https://api.acontext.io/api/v1"
+SUPPORTED_ROLES = {"user", "assistant", "system", "tool", "function"}
+
+try:
+    _VERSION = _metadata.version("acontext-py")
+except _metadata.PackageNotFoundError:  # pragma: no cover - local/checkout usage
+    _VERSION = "0.0.0"
+
+DEFAULT_USER_AGENT = f"acontext-py/{_VERSION}"

acontext-0.0.1.dev0/src/acontext/client.py

@@ -0,0 +1,176 @@
+"""
+High-level synchronous client for the Acontext API.
+"""
+
+from typing import Any, BinaryIO, Mapping, MutableMapping
+
+import httpx
+
+from ._constants import DEFAULT_BASE_URL, DEFAULT_USER_AGENT
+from .errors import APIError, TransportError
+from .messages import MessagePart as MessagePart
+from .uploads import FileUpload as FileUpload
+from .resources.artifacts import ArtifactsAPI as ArtifactsAPI
+from .resources.blocks import BlocksAPI as BlocksAPI
+from .resources.pages import PagesAPI as PagesAPI
+from .resources.sessions import SessionsAPI as SessionsAPI
+from .resources.spaces import SpacesAPI as SpacesAPI
+
+class AcontextClient:
+    """
+    Synchronous HTTP client for the Acontext REST API.
+
+    Example::
+
+        from acontext import AcontextClient, MessagePart
+
+        with AcontextClient(api_key="sk_...") as client:
+            spaces = client.spaces.list()
+            session = client.sessions.create(space_id=spaces[0]["id"])
+            client.sessions.send_message(
+                session["id"],
+                role="user",
+                parts=[MessagePart.text_part("Hello Acontext!")],
+            )
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | httpx.Timeout | None = 10.0,
+        user_agent: str | None = None,
+        client: httpx.Client | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        base_url = base_url.rstrip("/")
+        headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Accept": "application/json",
+            "User-Agent": user_agent or DEFAULT_USER_AGENT,
+        }
+
+        if client is not None:
+            self._client = client
+            self._owns_client = False
+            if client.base_url == httpx.URL():
+                client.base_url = httpx.URL(base_url)
+            for name, value in headers.items():
+                if name not in client.headers:
+                    client.headers[name] = value
+            self._base_url = str(client.base_url) or base_url
+        else:
+            self._client = httpx.Client(base_url=base_url, headers=headers, timeout=timeout)
+            self._owns_client = True
+            self._base_url = base_url
+
+        self._timeout = timeout
+
+        self.spaces = SpacesAPI(self)
+        self.sessions = SessionsAPI(self)
+        self.artifacts = ArtifactsAPI(self)
+        self.pages = PagesAPI(self)
+        self.blocks = BlocksAPI(self)
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "AcontextClient":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:  # noqa: D401 - standard context manager protocol
+        self.close()
+
+    # ------------------------------------------------------------------
+    # HTTP plumbing shared by resource clients
+    # ------------------------------------------------------------------
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json_data: Mapping[str, Any] | MutableMapping[str, Any] | None = None,
+        data: Mapping[str, Any] | MutableMapping[str, Any] | None = None,
+        files: Mapping[str, tuple[str, BinaryIO, str | None]] | None = None,
+        unwrap: bool = True,
+    ) -> Any:
+        try:
+            response = self._client.request(
+                method=method,
+                url=path,
+                params=params,
+                json=json_data,
+                data=data,
+                files=files,
+                timeout=self._timeout,
+            )
+        except httpx.HTTPError as exc:  # pragma: no cover - passthrough to caller
+            raise TransportError(str(exc)) from exc
+
+        return self._handle_response(response, unwrap=unwrap)
+
+    @staticmethod
+    def _handle_response(response: httpx.Response, *, unwrap: bool) -> Any:
+        content_type = response.headers.get("content-type", "")
+
+        parsed: Mapping[str, Any] | MutableMapping[str, Any] | None
+        if "application/json" in content_type or content_type.startswith("application/problem+json"):
+            try:
+                parsed = response.json()
+            except ValueError:
+                parsed = None
+        else:
+            parsed = None
+
+        if response.status_code >= 400:
+            message = response.reason_phrase
+            payload: Mapping[str, Any] | MutableMapping[str, Any] | None = parsed
+            code: int | None = None
+            error: str | None = None
+            if payload and isinstance(payload, Mapping):
+                message = str(payload.get("msg") or payload.get("message") or message)
+                error = payload.get("error")
+                try:
+                    code_val = payload.get("code")
+                    if isinstance(code_val, int):
+                        code = code_val
+                except Exception:  # pragma: no cover - defensive
+                    code = None
+            raise APIError(
+                status_code=response.status_code,
+                code=code,
+                message=message,
+                error=error,
+                payload=payload,
+            )
+
+        if parsed is None:
+            if unwrap:
+                return response.text
+            return {"code": response.status_code, "data": response.text, "msg": response.reason_phrase}
+
+        if not isinstance(parsed, Mapping):
+            if unwrap:
+                return parsed
+            return parsed
+
+        app_code = parsed.get("code")
+        if isinstance(app_code, int) and app_code >= 400:
+            raise APIError(
+                status_code=response.status_code,
+                code=app_code,
+                message=str(parsed.get("msg") or response.reason_phrase),
+                error=parsed.get("error"),
+                payload=parsed,
+            )
+
+        return parsed.get("data") if unwrap else parsed

acontext-0.0.1.dev0/src/acontext/client_types.py

@@ -0,0 +1,20 @@
+"""
+Common typing helpers used by resource modules to avoid circular imports.
+"""
+
+from typing import Any, BinaryIO, Mapping, MutableMapping, Protocol
+
+
+class RequesterProtocol(Protocol):
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json_data: Mapping[str, Any] | MutableMapping[str, Any] | None = None,
+        data: Mapping[str, Any] | MutableMapping[str, Any] | None = None,
+        files: Mapping[str, tuple[str, BinaryIO, str | None]] | None = None,
+        unwrap: bool = True,
+    ) -> Any:
+        ...

acontext-0.0.1.dev0/src/acontext/errors.py

@@ -0,0 +1,43 @@
+"""
+Custom exceptions raised by the acontext Python client.
+"""
+
+from typing import Any, Mapping, MutableMapping
+
+
+class AcontextError(Exception):
+    """Base exception for all errors raised by ``acontext``."""
+
+
+class APIError(AcontextError):
+    """
+    Raised when the server returns an error response.
+
+    Attributes:
+        status_code: HTTP status code returned by the server.
+        code: Optional application-level error code from the payload.
+        message: Human readable message if provided by the server.
+        error: Raw error field from the payload in non-release environments.
+        payload: The full parsed JSON payload.
+    """
+
+    def __init__(
+        self,
+        *,
+        status_code: int,
+        code: int | None = None,
+        message: str | None = None,
+        error: str | None = None,
+        payload: Mapping[str, Any] | MutableMapping[str, Any] | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        self.error = error
+        self.payload = payload
+        details = message or error or "API request failed"
+        super().__init__(f"{status_code}: {details}")
+
+
+class TransportError(AcontextError):
+    """Raised when the underlying HTTP transport failed before receiving a response."""

acontext-0.0.1.dev0/src/acontext/messages.py

@@ -0,0 +1,94 @@
+"""
+Support for constructing session messages.
+"""
+
+from dataclasses import dataclass
+from typing import Any, BinaryIO, Mapping, MutableMapping, Sequence, Tuple
+
+from .uploads import FileUpload, normalize_file_upload
+
+
+@dataclass(slots=True)
+class MessagePart:
+    """
+    Represents a single message part for ``/session/{id}/messages``.
+
+    Args:
+        type: One of ``text``, ``image``, ``audio``, ``video``, ``file``, ``tool-call``,
+            ``tool-result`` or ``data``.
+        text: Optional textual payload for ``text`` parts.
+        meta: Optional metadata dictionary accepted by the API.
+        file: Optional file attachment; required for binary part types.
+        file_field: Optional field name to use in the multipart body. When omitted the
+            client will auto-generate deterministic field names.
+    """
+
+    type: str
+    text: str | None = None
+    meta: Mapping[str, Any] | None = None
+    file: FileUpload | tuple[str, BinaryIO | bytes] | tuple[str, BinaryIO | bytes, str | None] | None = None
+    file_field: str | None = None
+
+    @classmethod
+    def text_part(cls, text: str, *, meta: Mapping[str, Any] | None = None) -> "MessagePart":
+        return cls(type="text", text=text, meta=meta)
+
+    @classmethod
+    def file_part(
+        cls,
+        upload: FileUpload | tuple[str, BinaryIO | bytes] | tuple[str, BinaryIO | bytes, str | None],
+        *,
+        meta: Mapping[str, Any] | None = None,
+        type: str = "file",
+    ) -> "MessagePart":
+        return cls(type=type, file=upload, meta=meta)
+
+
+def normalize_message_part(part: MessagePart | str | Mapping[str, Any]) -> MessagePart:
+    if isinstance(part, MessagePart):
+        return part
+    if isinstance(part, str):
+        return MessagePart(type="text", text=part)
+    if isinstance(part, Mapping):
+        if "type" not in part:
+            raise ValueError("mapping message parts must include a 'type'")
+        file = part.get("file")
+        normalized_file: FileUpload | tuple[str, BinaryIO | bytes] | tuple[str, BinaryIO | bytes, str | None] | None
+        if file is None:
+            normalized_file = None
+        else:
+            normalized_file = file  # type: ignore[assignment]
+        return MessagePart(
+            type=str(part["type"]),
+            text=part.get("text"),
+            meta=part.get("meta"),
+            file=normalized_file,
+            file_field=part.get("file_field"),
+        )
+    raise TypeError("unsupported message part type")
+
+
+def build_message_payload(
+    parts: Sequence[MessagePart | str | Mapping[str, Any]],
+) -> tuple[list[MutableMapping[str, Any]], dict[str, Tuple[str, BinaryIO, str | None]]]:
+    payload_parts: list[MutableMapping[str, Any]] = []
+    files: dict[str, Tuple[str, BinaryIO, str | None]] = {}
+
+    for idx, raw_part in enumerate(parts):
+        part = normalize_message_part(raw_part)
+        payload: MutableMapping[str, Any] = {"type": part.type}
+
+        if part.meta is not None:
+            payload["meta"] = dict(part.meta)
+        if part.text is not None:
+            payload["text"] = part.text
+
+        if part.file is not None:
+            upload = normalize_file_upload(part.file)
+            field_name = part.file_field or f"file_{idx}"
+            payload["file_field"] = field_name
+            files[field_name] = upload.as_httpx()
+
+        payload_parts.append(payload)
+
+    return payload_parts, files

acontext-0.0.1.dev0/src/acontext/resources/__init__.py

@@ -0,0 +1,19 @@
+"""Resource-specific API helpers for the Acontext client."""
+
+from .artifacts import (
+    ArtifactFilesAPI,
+    ArtifactsAPI,
+)
+from .blocks import BlocksAPI
+from .pages import PagesAPI
+from .sessions import SessionsAPI
+from .spaces import SpacesAPI
+
+__all__ = [
+    "ArtifactsAPI",
+    "ArtifactFilesAPI",
+    "BlocksAPI",
+    "PagesAPI",
+    "SessionsAPI",
+    "SpacesAPI",
+]

acontext-0.0.1.dev0/src/acontext/resources/artifacts.py

@@ -0,0 +1,98 @@
+"""
+Artifact and file endpoints.
+"""
+
+import json
+from typing import Any, BinaryIO, Mapping, MutableMapping
+
+from ..client_types import RequesterProtocol
+from ..uploads import FileUpload, normalize_file_upload
+
+
+class ArtifactsAPI:
+    def __init__(self, requester: RequesterProtocol) -> None:
+        self._requester = requester
+        self.files = ArtifactFilesAPI(requester)
+
+    def list(self) -> Any:
+        return self._requester.request("GET", "/artifact")
+
+    def create(self) -> Any:
+        return self._requester.request("POST", "/artifact")
+
+    def delete(self, artifact_id: str) -> None:
+        self._requester.request("DELETE", f"/artifact/{artifact_id}")
+
+
+class ArtifactFilesAPI:
+    def __init__(self, requester: RequesterProtocol) -> None:
+        self._requester = requester
+
+    def upload(
+        self,
+        artifact_id: str,
+        *,
+        file: FileUpload | tuple[str, BinaryIO | bytes] | tuple[str, BinaryIO | bytes, str | None],
+        file_path: str | None = None,
+        meta: Mapping[str, Any] | MutableMapping[str, Any] | None = None,
+    ) -> Any:
+        upload = normalize_file_upload(file)
+        files = {"file": upload.as_httpx()}
+        form: dict[str, Any] = {}
+        if file_path:
+            form["file_path"] = file_path
+        if meta is not None:
+            form["meta"] = json.dumps(meta)
+        return self._requester.request(
+            "POST",
+            f"/artifact/{artifact_id}/file",
+            data=form or None,
+            files=files,
+        )
+
+    def update(
+        self,
+        artifact_id: str,
+        *,
+        file_path: str,
+        file: FileUpload | tuple[str, BinaryIO | bytes] | tuple[str, BinaryIO | bytes, str | None],
+    ) -> Any:
+        upload = normalize_file_upload(file)
+        files = {"file": upload.as_httpx()}
+        form = {"file_path": file_path}
+        return self._requester.request(
+            "PUT",
+            f"/artifact/{artifact_id}/file",
+            data=form,
+            files=files,
+        )
+
+    def delete(self, artifact_id: str, *, file_path: str) -> None:
+        params = {"file_path": file_path}
+        self._requester.request("DELETE", f"/artifact/{artifact_id}/file", params=params)
+
+    def get(
+        self,
+        artifact_id: str,
+        *,
+        file_path: str,
+        with_public_url: bool | None = None,
+        expire: int | None = None,
+    ) -> Any:
+        params: dict[str, Any] = {"file_path": file_path}
+        if with_public_url is not None:
+            params["with_public_url"] = "true" if with_public_url else "false"
+        if expire is not None:
+            params["expire"] = expire
+        return self._requester.request("GET", f"/artifact/{artifact_id}/file", params=params)
+
+    def list(
+        self,
+        artifact_id: str,
+        *,
+        path: str | None = None,
+    ) -> Any:
+        params: dict[str, Any] = {}
+        if path is not None:
+            params["path"] = path
+        return self._requester.request("GET", f"/artifact/{artifact_id}/file/ls", params=params or None)

acontext-0.0.1.dev0/src/acontext/resources/blocks.py

@@ -0,0 +1,83 @@
+"""
+Block endpoints.
+"""
+
+from typing import Any, Mapping, MutableMapping
+
+from ..client_types import RequesterProtocol
+
+
+class BlocksAPI:
+    def __init__(self, requester: RequesterProtocol) -> None:
+        self._requester = requester
+
+    def list(self, space_id: str, *, parent_id: str) -> Any:
+        if not parent_id:
+            raise ValueError("parent_id is required")
+        params = {"parent_id": parent_id}
+        return self._requester.request("GET", f"/space/{space_id}/block", params=params)
+
+    def create(
+        self,
+        space_id: str,
+        *,
+        parent_id: str,
+        block_type: str,
+        title: str | None = None,
+        props: Mapping[str, Any] | MutableMapping[str, Any] | None = None,
+    ) -> Any:
+        if not parent_id:
+            raise ValueError("parent_id is required")
+        if not block_type:
+            raise ValueError("block_type is required")
+        payload: dict[str, Any] = {"parent_id": parent_id, "type": block_type}
+        if title is not None:
+            payload["title"] = title
+        if props is not None:
+            payload["props"] = props
+        return self._requester.request("POST", f"/space/{space_id}/block", json_data=payload)
+
+    def delete(self, space_id: str, block_id: str) -> None:
+        self._requester.request("DELETE", f"/space/{space_id}/block/{block_id}")
+
+    def get_properties(self, space_id: str, block_id: str) -> Any:
+        return self._requester.request("GET", f"/space/{space_id}/block/{block_id}/properties")
+
+    def update_properties(
+        self,
+        space_id: str,
+        block_id: str,
+        *,
+        title: str | None = None,
+        props: Mapping[str, Any] | MutableMapping[str, Any] | None = None,
+    ) -> None:
+        payload: dict[str, Any] = {}
+        if title is not None:
+            payload["title"] = title
+        if props is not None:
+            payload["props"] = props
+        if not payload:
+            raise ValueError("title or props must be provided")
+        self._requester.request("PUT", f"/space/{space_id}/block/{block_id}/properties", json_data=payload)
+
+    def move(
+        self,
+        space_id: str,
+        block_id: str,
+        *,
+        parent_id: str,
+        sort: int | None = None,
+    ) -> None:
+        if not parent_id:
+            raise ValueError("parent_id is required")
+        payload: dict[str, Any] = {"parent_id": parent_id}
+        if sort is not None:
+            payload["sort"] = sort
+        self._requester.request("PUT", f"/space/{space_id}/block/{block_id}/move", json_data=payload)
+
+    def update_sort(self, space_id: str, block_id: str, *, sort: int) -> None:
+        self._requester.request(
+            "PUT",
+            f"/space/{space_id}/block/{block_id}/sort",
+            json_data={"sort": sort},
+        )

acontext-0.0.1.dev0/src/acontext/resources/pages.py

@@ -0,0 +1,82 @@
+"""
+Page endpoints.
+"""
+
+from typing import Any, Mapping, MutableMapping
+
+from ..client_types import RequesterProtocol
+
+
+class PagesAPI:
+    def __init__(self, requester: RequesterProtocol) -> None:
+        self._requester = requester
+
+    def list(self, space_id: str, *, parent_id: str | None = None) -> Any:
+        params: dict[str, Any] = {}
+        if parent_id is not None:
+            params["parent_id"] = parent_id
+        return self._requester.request("GET", f"/space/{space_id}/page", params=params or None)
+
+    def create(
+        self,
+        space_id: str,
+        *,
+        parent_id: str | None = None,
+        title: str | None = None,
+        props: Mapping[str, Any] | MutableMapping[str, Any] | None = None,
+    ) -> Any:
+        payload: dict[str, Any] = {}
+        if parent_id is not None:
+            payload["parent_id"] = parent_id
+        if title is not None:
+            payload["title"] = title
+        if props is not None:
+            payload["props"] = props
+        return self._requester.request("POST", f"/space/{space_id}/page", json_data=payload)
+
+    def delete(self, space_id: str, page_id: str) -> None:
+        self._requester.request("DELETE", f"/space/{space_id}/page/{page_id}")
+
+    def get_properties(self, space_id: str, page_id: str) -> Any:
+        return self._requester.request("GET", f"/space/{space_id}/page/{page_id}/properties")
+
+    def update_properties(
+        self,
+        space_id: str,
+        page_id: str,
+        *,
+        title: str | None = None,
+        props: Mapping[str, Any] | MutableMapping[str, Any] | None = None,
+    ) -> None:
+        payload: dict[str, Any] = {}
+        if title is not None:
+            payload["title"] = title
+        if props is not None:
+            payload["props"] = props
+        if not payload:
+            raise ValueError("title or props must be provided")
+        self._requester.request("PUT", f"/space/{space_id}/page/{page_id}/properties", json_data=payload)
+
+    def move(
+        self,
+        space_id: str,
+        page_id: str,
+        *,
+        parent_id: str | None = None,
+        sort: int | None = None,
+    ) -> None:
+        payload: dict[str, Any] = {}
+        if parent_id is not None:
+            payload["parent_id"] = parent_id
+        if sort is not None:
+            payload["sort"] = sort
+        if not payload:
+            raise ValueError("parent_id or sort must be provided")
+        self._requester.request("PUT", f"/space/{space_id}/page/{page_id}/move", json_data=payload)
+
+    def update_sort(self, space_id: str, page_id: str, *, sort: int) -> None:
+        self._requester.request(
+            "PUT",
+            f"/space/{space_id}/page/{page_id}/sort",
+            json_data={"sort": sort},
+        )

acontext-0.0.1.dev0/src/acontext/resources/sessions.py

@@ -0,0 +1,107 @@
+"""
+Sessions endpoints.
+"""
+
+import json
+from typing import Any, Mapping, MutableMapping, Sequence
+
+from .._constants import SUPPORTED_ROLES
+from ..messages import MessagePart, build_message_payload
+from ..client_types import RequesterProtocol
+
+
+class SessionsAPI:
+    def __init__(self, requester: RequesterProtocol) -> None:
+        self._requester = requester
+
+    def list(
+        self,
+        *,
+        space_id: str | None = None,
+        not_connected: bool | None = None,
+    ) -> Any:
+        params: dict[str, Any] = {}
+        if space_id:
+            params["space_id"] = space_id
+        if not_connected is not None:
+            params["not_connected"] = "true" if not_connected else "false"
+        return self._requester.request("GET", "/session", params=params or None)
+
+    def create(
+        self,
+        *,
+        space_id: str | None = None,
+        configs: Mapping[str, Any] | MutableMapping[str, Any] | None = None,
+    ) -> Any:
+        payload: dict[str, Any] = {}
+        if space_id:
+            payload["space_id"] = space_id
+        if configs is not None:
+            payload["configs"] = configs
+        return self._requester.request("POST", "/session", json_data=payload)
+
+    def delete(self, session_id: str) -> None:
+        self._requester.request("DELETE", f"/session/{session_id}")
+
+    def update_configs(
+        self,
+        session_id: str,
+        *,
+        configs: Mapping[str, Any] | MutableMapping[str, Any],
+    ) -> None:
+        payload = {"configs": configs}
+        self._requester.request("PUT", f"/session/{session_id}/configs", json_data=payload)
+
+    def get_configs(self, session_id: str) -> Any:
+        return self._requester.request("GET", f"/session/{session_id}/configs")
+
+    def connect_to_space(self, session_id: str, *, space_id: str) -> None:
+        payload = {"space_id": space_id}
+        self._requester.request("POST", f"/session/{session_id}/connect_to_space", json_data=payload)
+
+    def send_message(
+        self,
+        session_id: str,
+        *,
+        role: str,
+        parts: Sequence[MessagePart | str | Mapping[str, Any]],
+    ) -> Any:
+        if role not in SUPPORTED_ROLES:
+            raise ValueError(f"role must be one of {SUPPORTED_ROLES!r}")
+        if not parts:
+            raise ValueError("parts must contain at least one entry")
+
+        payload_parts, files = build_message_payload(parts)
+        payload = {"role": role, "parts": payload_parts}
+
+        if files:
+            form_data = {"payload": json.dumps(payload)}
+            return self._requester.request(
+                "POST",
+                f"/session/{session_id}/messages",
+                data=form_data,
+                files=files,
+            )
+
+        return self._requester.request(
+            "POST",
+            f"/session/{session_id}/messages",
+            json_data=payload,
+        )
+
+    def get_messages(
+        self,
+        session_id: str,
+        *,
+        limit: int | None = None,
+        cursor: str | None = None,
+        with_asset_public_url: bool | None = None,
+    ) -> Any:
+        params: dict[str, Any] = {}
+        if limit is not None:
+            params["limit"] = limit
+        if cursor is not None:
+            params["cursor"] = cursor
+        if with_asset_public_url is not None:
+            params["with_asset_public_url"] = "true" if with_asset_public_url else "false"
+        return self._requester.request("GET", f"/session/{session_id}/messages", params=params or None)

acontext-0.0.1.dev0/src/acontext/resources/spaces.py

@@ -0,0 +1,36 @@
+"""
+Spaces endpoints.
+"""
+
+from typing import Any, Mapping, MutableMapping
+
+from ..client_types import RequesterProtocol
+
+
+class SpacesAPI:
+    def __init__(self, requester: RequesterProtocol) -> None:
+        self._requester = requester
+
+    def list(self) -> Any:
+        return self._requester.request("GET", "/space")
+
+    def create(self, *, configs: Mapping[str, Any] | MutableMapping[str, Any] | None = None) -> Any:
+        payload: dict[str, Any] = {}
+        if configs is not None:
+            payload["configs"] = configs
+        return self._requester.request("POST", "/space", json_data=payload)
+
+    def delete(self, space_id: str) -> None:
+        self._requester.request("DELETE", f"/space/{space_id}")
+
+    def update_configs(
+        self,
+        space_id: str,
+        *,
+        configs: Mapping[str, Any] | MutableMapping[str, Any],
+    ) -> None:
+        payload = {"configs": configs}
+        self._requester.request("PUT", f"/space/{space_id}/configs", json_data=payload)
+
+    def get_configs(self, space_id: str) -> Any:
+        return self._requester.request("GET", f"/space/{space_id}/configs")

acontext-0.0.1.dev0/src/acontext/uploads.py

@@ -0,0 +1,44 @@
+"""
+Utilities for working with file uploads.
+"""
+
+import io
+from dataclasses import dataclass
+from typing import BinaryIO, Tuple
+
+
+@dataclass(slots=True)
+class FileUpload:
+    """
+    Represents a file payload for multipart requests.
+
+    Accepts either a binary stream (any object exposing ``read``) or raw ``bytes``.
+    """
+
+    filename: str
+    content: BinaryIO | bytes
+    content_type: str | None = None
+
+    def as_httpx(self) -> Tuple[str, BinaryIO, str | None]:
+        """
+        Convert to the tuple format expected by ``httpx``.
+        """
+        if isinstance(self.content, (bytes, bytearray)):
+            buffer = io.BytesIO(self.content)
+            return self.filename, buffer, self.content_type or "application/octet-stream"
+        return self.filename, self.content, self.content_type or "application/octet-stream"
+
+
+def normalize_file_upload(
+    upload: FileUpload | tuple[str, BinaryIO | bytes] | tuple[str, BinaryIO | bytes, str | None],
+) -> FileUpload:
+    if isinstance(upload, FileUpload):
+        return upload
+    if isinstance(upload, tuple):
+        if len(upload) == 2:
+            filename, content = upload
+            return FileUpload(filename=filename, content=content)
+        if len(upload) == 3:
+            filename, content, content_type = upload
+            return FileUpload(filename=filename, content=content, content_type=content_type)
+    raise TypeError("Unsupported file upload payload")