acontext 0.0.1.dev2__tar.gz → 0.0.1.dev4__tar.gz

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

@@ -1,11 +1,12 @@
 Metadata-Version: 2.3
 Name: acontext
-Version: 0.0.1.dev2
+Version: 0.0.1.dev4
 Summary: Python SDK for the Acontext API
 Keywords: acontext,sdk,client,api
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: openai>=2.6.1
 Requires-Dist: anthropic>=0.72.0
+Requires-Dist: pydantic>=2.12.3
 Requires-Python: >=3.10
 Project-URL: Homepage, https://github.com/memodb-io/Acontext
 Project-URL: Issues, https://github.com/memodb-io/Acontext/issues
@@ -63,7 +64,7 @@ try:
             content=b"# Retro Notes\nWe shipped file uploads successfully!\n",
             content_type="text/markdown",
         ),
-        file_path="notes/retro.md",
+        file_path="/notes/",
         meta={"source": "readme-demo"},
     )
 finally:

{acontext-0.0.1.dev2 → acontext-0.0.1.dev4}/README.md

@@ -49,7 +49,7 @@ try:
             content=b"# Retro Notes\nWe shipped file uploads successfully!\n",
             content_type="text/markdown",
         ),
-        file_path="notes/retro.md",
+        file_path="/notes/",
         meta={"source": "readme-demo"},
     )
 finally:

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

@@ -1,13 +1,14 @@
 [project]
 name = "acontext"
-version = "0.0.1.dev2"
+version = "0.0.1.dev4"
 description = "Python SDK for the Acontext API"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
     "httpx>=0.28.1",
     "openai>=2.6.1",
-    "anthropic>=0.72.0"
+    "anthropic>=0.72.0",
+    "pydantic>=2.12.3",
 ]
 keywords = ["acontext", "sdk", "client", "api"]
 
@@ -17,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.dev2 → 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.dev2 → acontext-0.0.1.dev4}/src/acontext/_constants.py

@@ -5,7 +5,6 @@ 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")

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

@@ -0,0 +1,42 @@
+"""Utility functions for the acontext Python client."""
+
+from typing import Any
+
+
+def bool_to_str(value: bool) -> str:
+    """Convert a boolean value to string representation used by the API.
+    
+    Args:
+        value: The boolean value to convert.
+        
+    Returns:
+        "true" if value is True, "false" otherwise.
+    """
+    return "true" if value else "false"
+
+
+def build_params(**kwargs: Any) -> dict[str, Any]:
+    """Build query parameters dictionary, filtering None values and converting booleans.
+    
+    This function filters out None values and converts boolean values to their
+    string representations ("true" or "false") as expected by the API.
+    
+    Args:
+        **kwargs: Keyword arguments to build parameters from.
+        
+    Returns:
+        Dictionary with non-None parameters, with booleans converted to strings.
+        
+    Example:
+        >>> build_params(limit=10, cursor=None, time_desc=True)
+        {'limit': 10, 'time_desc': 'true'}
+    """
+    params: dict[str, Any] = {}
+    for key, value in kwargs.items():
+        if value is not None:
+            if isinstance(value, bool):
+                params[key] = bool_to_str(value)
+            else:
+                params[key] = value
+    return params
+

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.dev2 → acontext-0.0.1.dev4}/src/acontext/client.py

@@ -2,7 +2,8 @@
 High-level synchronous client for the Acontext API.
 """
 
-from collections.abc import Mapping, MutableMapping
+import os
+from collections.abc import Mapping
 from typing import Any, BinaryIO
 
 import httpx
@@ -16,41 +17,69 @@ from .resources.blocks import BlocksAPI as BlocksAPI
 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!")],
-            )
-    """
+class AcontextClient:
 
     def __init__(
         self,
         *,
-        api_key: str,
-        base_url: str = DEFAULT_BASE_URL,
+        api_key: str | None = None,
+        base_url: str | None = None,
         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")
+        """
+        Initialize the Acontext 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.Client 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 or DEFAULT_USER_AGENT,
+            "User-Agent": user_agent,
         }
 
         if client is not None:
@@ -63,11 +92,15 @@ class AcontextClient:
                     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._client = httpx.Client(
+                base_url=base_url,
+                headers=headers,
+                timeout=actual_timeout,
+            )
             self._owns_client = True
             self._base_url = base_url
 
-        self._timeout = timeout
+        self._timeout = actual_timeout
 
         self.spaces = SpacesAPI(self)
         self.sessions = SessionsAPI(self)
@@ -98,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:
@@ -122,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
-        if "application/json" in content_type or content_type.startswith("application/problem+json"):
+        parsed: Mapping[str, Any] | None
+        if "application/json" in content_type:
             try:
-                parsed = response.json()
+                parsed = response.json() # dict
             except ValueError:
                 parsed = None
         else:
@@ -133,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):
@@ -158,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.dev2 → 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.dev2 → 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.dev2 → 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",
 ]