acontext 0.0.1.dev2__tar.gz → 0.0.1.dev3__tar.gz

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

@@ -1,11 +1,12 @@
 Metadata-Version: 2.3
 Name: acontext
-Version: 0.0.1.dev2
+Version: 0.0.1.dev3
 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.dev3}/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.dev3}/pyproject.toml

@@ -1,13 +1,14 @@
 [project]
 name = "acontext"
-version = "0.0.1.dev2"
+version = "0.0.1.dev3"
 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"]
 

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

@@ -2,6 +2,7 @@
 High-level synchronous client for the Acontext API.
 """
 
+import os
 from collections.abc import Mapping, MutableMapping
 from typing import Any, BinaryIO
 
@@ -16,41 +17,68 @@ 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
+        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 +91,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)
@@ -123,7 +155,7 @@ class AcontextClient:
         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"):
+        if "application/json" in content_type:
             try:
                 parsed = response.json()
             except ValueError:

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

@@ -0,0 +1,162 @@
+"""
+Block endpoints.
+"""
+
+from collections.abc import Mapping, MutableMapping
+from typing import Any
+
+from ..client_types import RequesterProtocol
+from ..types.block import Block
+
+
+class BlocksAPI:
+    def __init__(self, requester: RequesterProtocol) -> None:
+        self._requester = requester
+
+    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 = self._requester.request("GET", f"/space/{space_id}/block", params=params or None)
+        return [Block.model_validate(item) for item in data]
+
+    def create(
+        self,
+        space_id: str,
+        *,
+        block_type: str,
+        parent_id: str | None = None,
+        title: str | None = None,
+        props: Mapping[str, Any] | MutableMapping[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 = self._requester.request("POST", f"/space/{space_id}/block", json_data=payload)
+        return Block.model_validate(data)
+
+    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.
+        """
+        self._requester.request("DELETE", f"/space/{space_id}/block/{block_id}")
+
+    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 = self._requester.request("GET", f"/space/{space_id}/block/{block_id}/properties")
+        return Block.model_validate(data)
+
+    def update_properties(
+        self,
+        space_id: str,
+        block_id: str,
+        *,
+        title: str | None = None,
+        props: Mapping[str, Any] | MutableMapping[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")
+        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 | 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")
+        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:
+        """Update block sort order.
+        
+        Args:
+            space_id: The UUID of the space.
+            block_id: The UUID of the block.
+            sort: The new sort order.
+        """
+        self._requester.request(
+            "PUT",
+            f"/space/{space_id}/block/{block_id}/sort",
+            json_data={"sort": sort},
+        )

acontext-0.0.1.dev3/src/acontext/resources/disks.py

@@ -0,0 +1,194 @@
+"""
+Disk and artifact endpoints.
+"""
+
+import json
+from collections.abc import Mapping, MutableMapping
+from typing import Any, BinaryIO, cast
+
+from .._utils import build_params
+from ..client_types import RequesterProtocol
+from ..types.disk import (
+    Artifact,
+    Disk,
+    GetArtifactResp,
+    ListArtifactsResp,
+    ListDisksOutput,
+    UpdateArtifactResp,
+)
+from ..uploads import FileUpload, normalize_file_upload
+
+
+class DisksAPI:
+    def __init__(self, requester: RequesterProtocol) -> None:
+        self._requester = requester
+        self.artifacts = DiskArtifactsAPI(requester)
+
+    def list(
+        self,
+        *,
+        limit: int | None = None,
+        cursor: str | None = None,
+        time_desc: bool | None = None,
+    ) -> ListDisksOutput:
+        """List all disks in the project.
+        
+        Args:
+            limit: Maximum number of disks to return. Defaults to None.
+            cursor: Cursor for pagination. Defaults to None.
+            time_desc: Order by created_at descending if True, ascending if False. Defaults to None.
+            
+        Returns:
+            ListDisksOutput containing the list of disks and pagination information.
+        """
+        params = build_params(limit=limit, cursor=cursor, time_desc=time_desc)
+        data = self._requester.request("GET", "/disk", params=params or None)
+        return ListDisksOutput.model_validate(data)
+
+    def create(self) -> Disk:
+        """Create a new disk.
+        
+        Returns:
+            The created Disk object.
+        """
+        data = self._requester.request("POST", "/disk")
+        return Disk.model_validate(data)
+
+    def delete(self, disk_id: str) -> None:
+        """Delete a disk by its ID.
+        
+        Args:
+            disk_id: The UUID of the disk to delete.
+        """
+        self._requester.request("DELETE", f"/disk/{disk_id}")
+
+
+class DiskArtifactsAPI:
+    def __init__(self, requester: RequesterProtocol) -> None:
+        self._requester = requester
+
+    def upsert(
+        self,
+        disk_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,
+    ) -> Artifact:
+        """Upload a file to create or update an artifact.
+        
+        Args:
+            disk_id: The UUID of the disk.
+            file: The file to upload (FileUpload object or tuple format).
+            file_path: Directory path (not including filename), defaults to "/".
+            meta: Custom metadata as JSON-serializable dict, defaults to None.
+            
+        Returns:
+            Artifact containing the created/updated artifact information.
+        """
+        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(cast(Mapping[str, Any], meta))
+        data = self._requester.request(
+            "POST",
+            f"/disk/{disk_id}/artifact",
+            data=form or None,
+            files=files,
+        )
+        return Artifact.model_validate(data)
+
+    def get(
+        self,
+        disk_id: str,
+        *,
+        file_path: str,
+        filename: str,
+        with_public_url: bool | None = None,
+        with_content: bool | None = None,
+        expire: int | None = None,
+    ) -> GetArtifactResp:
+        """Get an artifact by disk ID, file path, and filename.
+        
+        Args:
+            disk_id: The UUID of the disk.
+            file_path: Directory path (not including filename).
+            filename: The filename of the artifact.
+            with_public_url: Whether to include a presigned public URL. Defaults to None.
+            with_content: Whether to include file content. Defaults to None.
+            expire: URL expiration time in seconds. Defaults to None.
+            
+        Returns:
+            GetArtifactResp containing the artifact and optionally public URL and content.
+        """
+        full_path = f"{file_path.rstrip('/')}/{filename}"
+        params = build_params(
+            file_path=full_path,
+            with_public_url=with_public_url,
+            with_content=with_content,
+            expire=expire,
+        )
+        data = self._requester.request("GET", f"/disk/{disk_id}/artifact", params=params)
+        return GetArtifactResp.model_validate(data)
+
+    def update(
+        self,
+        disk_id: str,
+        *,
+        file_path: str,
+        filename: str,
+        meta: Mapping[str, Any] | MutableMapping[str, Any],
+    ) -> UpdateArtifactResp:
+        """Update an artifact's metadata.
+        
+        Args:
+            disk_id: The UUID of the disk.
+            file_path: Directory path (not including filename).
+            filename: The filename of the artifact.
+            meta: Custom metadata as JSON-serializable dict.
+            
+        Returns:
+            UpdateArtifactResp containing the updated artifact information.
+        """
+        full_path = f"{file_path.rstrip('/')}/{filename}"
+        payload = {
+            "file_path": full_path,
+            "meta": json.dumps(cast(Mapping[str, Any], meta)),
+        }
+        data = self._requester.request("PUT", f"/disk/{disk_id}/artifact", json_data=payload)
+        return UpdateArtifactResp.model_validate(data)
+
+    def delete(
+        self,
+        disk_id: str,
+        *,
+        file_path: str,
+        filename: str,
+    ) -> None:
+        """Delete an artifact by disk ID, file path, and filename.
+        
+        Args:
+            disk_id: The UUID of the disk.
+            file_path: Directory path (not including filename).
+            filename: The filename of the artifact.
+        """
+        full_path = f"{file_path.rstrip('/')}/{filename}"
+        params = {"file_path": full_path}
+        self._requester.request("DELETE", f"/disk/{disk_id}/artifact", params=params)
+
+    def list(
+        self,
+        disk_id: str,
+        *,
+        path: str | None = None,
+    ) -> ListArtifactsResp:
+        params: dict[str, Any] = {}
+        if path is not None:
+            params["path"] = path
+        data = self._requester.request("GET", f"/disk/{disk_id}/artifact/ls", params=params or None)
+        return ListArtifactsResp.model_validate(data)