acontext 0.0.1.dev3__tar.gz → 0.0.1.dev4__tar.gz

{acontext-0.0.1.dev3 → acontext-0.0.1.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: acontext
-Version: 0.0.1.dev3
+Version: 0.0.1.dev4
 Summary: Python SDK for the Acontext API
 Keywords: acontext,sdk,client,api
 Requires-Dist: httpx>=0.28.1

{acontext-0.0.1.dev3 → acontext-0.0.1.dev4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "acontext"
-version = "0.0.1.dev3"
+version = "0.0.1.dev4"
 description = "Python SDK for the Acontext API"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -18,7 +18,11 @@ Repository = "https://github.com/memodb-io/Acontext"
 Issues = "https://github.com/memodb-io/Acontext/issues"
 
 [dependency-groups]
-dev = ["pytest", "ruff"]
+dev = [
+    "pytest", 
+    "ruff",
+    "pytest-asyncio"
+]
 
 [build-system]
 requires = ["uv_build>=0.9.2,<0.10.0"]

{acontext-0.0.1.dev3 → acontext-0.0.1.dev4}/src/acontext/__init__.py

@@ -4,12 +4,25 @@ Python SDK for the Acontext API.
 
 from importlib import metadata as _metadata
 
+from .async_client import AcontextAsyncClient
 from .client import AcontextClient, FileUpload, MessagePart
 from .messages import AcontextMessage
-from .resources import BlocksAPI, DiskArtifactsAPI, DisksAPI, SessionsAPI, SpacesAPI
+from .resources import (
+    AsyncBlocksAPI,
+    AsyncDiskArtifactsAPI,
+    AsyncDisksAPI,
+    AsyncSessionsAPI,
+    AsyncSpacesAPI,
+    BlocksAPI,
+    DiskArtifactsAPI,
+    DisksAPI,
+    SessionsAPI,
+    SpacesAPI,
+)
 
 __all__ = [
     "AcontextClient",
+    "AcontextAsyncClient",
     "FileUpload",
     "MessagePart",
     "AcontextMessage",
@@ -18,6 +31,11 @@ __all__ = [
     "BlocksAPI",
     "SessionsAPI",
     "SpacesAPI",
+    "AsyncDisksAPI",
+    "AsyncDiskArtifactsAPI",
+    "AsyncBlocksAPI",
+    "AsyncSessionsAPI",
+    "AsyncSpacesAPI",
     "__version__",
 ]
 

acontext-0.0.1.dev4/src/acontext/async_client.py

@@ -0,0 +1,206 @@
+"""
+High-level asynchronous client for the Acontext API.
+"""
+
+import os
+from collections.abc import Mapping
+from typing import Any, BinaryIO
+
+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.async_disks import AsyncDisksAPI as AsyncDisksAPI
+from .resources.async_blocks import AsyncBlocksAPI as AsyncBlocksAPI
+from .resources.async_sessions import AsyncSessionsAPI as AsyncSessionsAPI
+from .resources.async_spaces import AsyncSpacesAPI as AsyncSpacesAPI
+
+
+class AcontextAsyncClient:
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout | None = 10.0,
+        user_agent: str | None = None,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        """
+        Initialize the Acontext async client.
+
+        Args:
+            api_key: API key for authentication. Can also be set via ACONTEXT_API_KEY env var.
+            base_url: Base URL for the API. Defaults to DEFAULT_BASE_URL. Can also be set via ACONTEXT_BASE_URL env var.
+            timeout: Request timeout in seconds. Defaults to 10.0. Can also be set via ACONTEXT_TIMEOUT env var.
+                   Can also be an httpx.Timeout object.
+            user_agent: Custom user agent string. Can also be set via ACONTEXT_USER_AGENT env var.
+            client: Optional httpx.AsyncClient instance to reuse. If provided, headers and base_url
+                   will be merged with the client configuration.
+        """
+        # Priority: explicit parameters > environment variables > defaults
+        # Load api_key from parameter or environment variable
+        api_key = api_key or os.getenv("ACONTEXT_API_KEY")
+        if not api_key or not api_key.strip():
+            raise ValueError(
+                "api_key is required. Provide it either as a parameter (api_key='...') "
+                "or set the ACONTEXT_API_KEY environment variable."
+            )
+
+        # Load other parameters from environment variables if not provided
+        if base_url is None:
+            base_url = os.getenv("ACONTEXT_BASE_URL", DEFAULT_BASE_URL)
+        base_url = base_url.rstrip("/")
+
+        if user_agent is None:
+            user_agent = os.getenv("ACONTEXT_USER_AGENT", DEFAULT_USER_AGENT)
+
+        # Handle timeout: support both float and httpx.Timeout
+        if timeout is None:
+            timeout_str = os.getenv("ACONTEXT_TIMEOUT")
+            if timeout_str:
+                try:
+                    timeout = float(timeout_str)
+                except ValueError:
+                    timeout = 10.0
+            else:
+                timeout = 10.0
+
+        # Determine actual timeout value
+        actual_timeout: float | httpx.Timeout
+        if isinstance(timeout, httpx.Timeout):
+            actual_timeout = timeout
+        else:
+            actual_timeout = float(timeout)
+
+        headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Accept": "application/json",
+            "User-Agent": 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.AsyncClient(
+                base_url=base_url,
+                headers=headers,
+                timeout=actual_timeout,
+            )
+            self._owns_client = True
+            self._base_url = base_url
+
+        self._timeout = actual_timeout
+
+        self.spaces = AsyncSpacesAPI(self)
+        self.sessions = AsyncSessionsAPI(self)
+        self.disks = AsyncDisksAPI(self)
+        self.artifacts = self.disks.artifacts
+        self.blocks = AsyncBlocksAPI(self)
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    async def aclose(self) -> None:
+        """Close the async client."""
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "AcontextAsyncClient":
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:  # noqa: D401 - standard context manager protocol
+        await self.aclose()
+
+    # ------------------------------------------------------------------
+    # HTTP plumbing shared by resource clients
+    # ------------------------------------------------------------------
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json_data: Mapping[str, Any] | None = None,
+        data: Mapping[str, Any] | None = None,
+        files: Mapping[str, tuple[str, BinaryIO, str | None]] | None = None,
+        unwrap: bool = True,
+    ) -> Any:
+        try:
+            response = await 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] | None = None
+        if "application/json" in content_type:
+            try:
+                parsed = response.json()
+            except ValueError:
+                parsed = None
+        else:
+            parsed = None
+
+        if response.status_code >= 400:
+            message = response.reason_phrase
+            payload: Mapping[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}
+
+        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.dev3 → acontext-0.0.1.dev4}/src/acontext/client.py

@@ -3,7 +3,7 @@ High-level synchronous client for the Acontext API.
 """
 
 import os
-from collections.abc import Mapping, MutableMapping
+from collections.abc import Mapping
 from typing import Any, BinaryIO
 
 import httpx
@@ -70,6 +70,7 @@ class AcontextClient:
                 timeout = 10.0
 
         # Determine actual timeout value
+        actual_timeout: float | httpx.Timeout
         if isinstance(timeout, httpx.Timeout):
             actual_timeout = timeout
         else:
@@ -130,8 +131,8 @@ class AcontextClient:
         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,
+        json_data: Mapping[str, Any] | None = None,
+        data: Mapping[str, Any] | None = None,
         files: Mapping[str, tuple[str, BinaryIO, str | None]] | None = None,
         unwrap: bool = True,
     ) -> Any:
@@ -154,10 +155,10 @@ class AcontextClient:
     def _handle_response(response: httpx.Response, *, unwrap: bool) -> Any:
         content_type = response.headers.get("content-type", "")
 
-        parsed: Mapping[str, Any] | MutableMapping[str, Any] | None
+        parsed: Mapping[str, Any] | None
         if "application/json" in content_type:
             try:
-                parsed = response.json()
+                parsed = response.json() # dict
             except ValueError:
                 parsed = None
         else:
@@ -165,7 +166,7 @@ class AcontextClient:
 
         if response.status_code >= 400:
             message = response.reason_phrase
-            payload: Mapping[str, Any] | MutableMapping[str, Any] | None = parsed
+            payload: Mapping[str, Any] | None = parsed
             code: int | None = None
             error: str | None = None
             if payload and isinstance(payload, Mapping):
@@ -190,11 +191,6 @@ class AcontextClient:
                 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(

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

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

{acontext-0.0.1.dev3 → acontext-0.0.1.dev4}/src/acontext/errors.py

@@ -2,7 +2,7 @@
 Custom exceptions raised by the acontext Python client.
 """
 
-from collections.abc import Mapping, MutableMapping
+from collections.abc import Mapping
 from typing import Any
 
 
@@ -29,7 +29,7 @@ class APIError(AcontextError):
         code: int | None = None,
         message: str | None = None,
         error: str | None = None,
-        payload: Mapping[str, Any] | MutableMapping[str, Any] | None = None,
+        payload: Mapping[str, Any] | None = None,
     ) -> None:
         self.status_code = status_code
         self.code = code

{acontext-0.0.1.dev3 → acontext-0.0.1.dev4}/src/acontext/messages.py

@@ -2,7 +2,7 @@
 Support for constructing session messages.
 """
 
-from collections.abc import Mapping, MutableMapping, Sequence
+from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
 from typing import Any, Literal
 
@@ -25,14 +25,6 @@ class MessagePart:
     meta: Mapping[str, Any] | 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_field_part(cls, file_field: str, *, meta: Mapping[str, Any] | None = None) -> "MessagePart":
-        return cls(type="file", file_field=file_field, meta=meta)
-
 @dataclass(slots=True)
 class AcontextMessage:
     """
@@ -41,7 +33,7 @@ class AcontextMessage:
 
     role: Literal["user", "assistant", "system"]
     parts: list[MessagePart]
-    meta: MutableMapping[str, Any] | None = None
+    meta: Mapping[str, Any] | None = None
 
 
 def build_acontext_message(

{acontext-0.0.1.dev3 → acontext-0.0.1.dev4}/src/acontext/resources/__init__.py

@@ -1,5 +1,9 @@
 """Resource-specific API helpers for the Acontext client."""
 
+from .async_blocks import AsyncBlocksAPI
+from .async_disks import AsyncDisksAPI, AsyncDiskArtifactsAPI
+from .async_sessions import AsyncSessionsAPI
+from .async_spaces import AsyncSpacesAPI
 from .blocks import BlocksAPI
 from .disks import DisksAPI, DiskArtifactsAPI
 from .sessions import SessionsAPI
@@ -11,4 +15,9 @@ __all__ = [
     "BlocksAPI",
     "SessionsAPI",
     "SpacesAPI",
+    "AsyncDisksAPI",
+    "AsyncDiskArtifactsAPI",
+    "AsyncBlocksAPI",
+    "AsyncSessionsAPI",
+    "AsyncSpacesAPI",
 ]

acontext-0.0.1.dev4/src/acontext/resources/async_blocks.py

@@ -0,0 +1,163 @@
+"""
+Block endpoints (async).
+"""
+
+from collections.abc import Mapping
+from typing import Any
+
+from ..client_types import AsyncRequesterProtocol
+from ..types.block import Block
+
+
+class AsyncBlocksAPI:
+    def __init__(self, requester: AsyncRequesterProtocol) -> None:
+        self._requester = requester
+
+    async def list(
+        self,
+        space_id: str,
+        *,
+        parent_id: str | None = None,
+        block_type: str | None = None,
+    ) -> list[Block]:
+        """List blocks in a space.
+        
+        Args:
+            space_id: The UUID of the space.
+            parent_id: Filter blocks by parent ID. Defaults to None.
+            block_type: Filter blocks by type (e.g., "page", "folder", "text", "sop"). Defaults to None.
+            
+        Returns:
+            List of Block objects.
+        """
+        params: dict[str, Any] = {}
+        if parent_id is not None:
+            params["parent_id"] = parent_id
+        if block_type is not None:
+            params["type"] = block_type
+        data = await self._requester.request("GET", f"/space/{space_id}/block", params=params or None)
+        return [Block.model_validate(item) for item in data]
+
+    async def create(
+        self,
+        space_id: str,
+        *,
+        block_type: str,
+        parent_id: str | None = None,
+        title: str | None = None,
+        props: Mapping[str, Any] | None = None,
+    ) -> Block:
+        """Create a new block in a space.
+        
+        Args:
+            space_id: The UUID of the space.
+            block_type: The type of block (e.g., "page", "folder", "text", "sop").
+            parent_id: Optional parent block ID. Defaults to None.
+            title: Optional block title. Defaults to None.
+            props: Optional block properties dictionary. Defaults to None.
+            
+        Returns:
+            The created Block object.
+        """
+        payload: dict[str, Any] = {"type": block_type}
+        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
+        data = await self._requester.request("POST", f"/space/{space_id}/block", json_data=payload)
+        return Block.model_validate(data)
+
+    async def delete(self, space_id: str, block_id: str) -> None:
+        """Delete a block by its ID.
+        
+        Args:
+            space_id: The UUID of the space.
+            block_id: The UUID of the block to delete.
+        """
+        await self._requester.request("DELETE", f"/space/{space_id}/block/{block_id}")
+
+    async def get_properties(self, space_id: str, block_id: str) -> Block:
+        """Get block properties.
+        
+        Args:
+            space_id: The UUID of the space.
+            block_id: The UUID of the block.
+            
+        Returns:
+            Block object containing the properties.
+        """
+        data = await self._requester.request("GET", f"/space/{space_id}/block/{block_id}/properties")
+        return Block.model_validate(data)
+
+    async def update_properties(
+        self,
+        space_id: str,
+        block_id: str,
+        *,
+        title: str | None = None,
+        props: Mapping[str, Any] | None = None,
+    ) -> None:
+        """Update block properties.
+        
+        Args:
+            space_id: The UUID of the space.
+            block_id: The UUID of the block.
+            title: Optional block title. Defaults to None.
+            props: Optional block properties dictionary. Defaults to None.
+            
+        Raises:
+            ValueError: If both title and props are 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")
+        await self._requester.request("PUT", f"/space/{space_id}/block/{block_id}/properties", json_data=payload)
+
+    async def move(
+        self,
+        space_id: str,
+        block_id: str,
+        *,
+        parent_id: str | None = None,
+        sort: int | None = None,
+    ) -> None:
+        """Move a block by updating its parent or sort order.
+        
+        Args:
+            space_id: The UUID of the space.
+            block_id: The UUID of the block to move.
+            parent_id: Optional new parent block ID. Defaults to None.
+            sort: Optional new sort order. Defaults to None.
+            
+        Raises:
+            ValueError: If both parent_id and sort are 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")
+        await self._requester.request("PUT", f"/space/{space_id}/block/{block_id}/move", json_data=payload)
+
+    async def update_sort(self, space_id: str, block_id: str, *, sort: int) -> None:
+        """Update block sort order.
+        
+        Args:
+            space_id: The UUID of the space.
+            block_id: The UUID of the block.
+            sort: The new sort order.
+        """
+        await self._requester.request(
+            "PUT",
+            f"/space/{space_id}/block/{block_id}/sort",
+            json_data={"sort": sort},
+        )
+