acontext 0.0.14__py3-none-any.whl → 0.0.17__py3-none-any.whl

acontext/resources/async_spaces.py

@@ -23,6 +23,7 @@ class AsyncSpacesAPI:
     async def list(
         self,
         *,
+        user: str | None = None,
         limit: int | None = None,
         cursor: str | None = None,
         time_desc: bool | None = None,
@@ -30,6 +31,7 @@ class AsyncSpacesAPI:
         """List all spaces in the project.
 
         Args:
+            user: Filter by user identifier. Defaults to None.
             limit: Maximum number of spaces 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.
@@ -37,20 +39,28 @@ class AsyncSpacesAPI:
         Returns:
             ListSpacesOutput containing the list of spaces and pagination information.
         """
-        params = build_params(limit=limit, cursor=cursor, time_desc=time_desc)
+        params = build_params(user=user, limit=limit, cursor=cursor, time_desc=time_desc)
         data = await self._requester.request("GET", "/space", params=params or None)
         return ListSpacesOutput.model_validate(data)
 
-    async def create(self, *, configs: Mapping[str, Any] | None = None) -> Space:
+    async def create(
+        self,
+        *,
+        user: str | None = None,
+        configs: Mapping[str, Any] | None = None,
+    ) -> Space:
         """Create a new space.
 
         Args:
+            user: Optional user identifier string. Defaults to None.
             configs: Optional space configuration dictionary. Defaults to None.
 
         Returns:
             The created Space object.
         """
         payload: dict[str, Any] = {}
+        if user is not None:
+            payload["user"] = user
         if configs is not None:
             payload["configs"] = configs
         data = await self._requester.request("POST", "/space", json_data=payload)

acontext/resources/async_users.py

@@ -0,0 +1,57 @@
+"""
+User management endpoints (async).
+"""
+
+from urllib.parse import quote
+
+from .._utils import build_params
+from ..client_types import AsyncRequesterProtocol
+from ..types.user import GetUserResourcesOutput, ListUsersOutput
+
+
+class AsyncUsersAPI:
+    def __init__(self, requester: AsyncRequesterProtocol) -> None:
+        self._requester = requester
+
+    async def list(
+        self,
+        *,
+        limit: int | None = None,
+        cursor: str | None = None,
+        time_desc: bool | None = None,
+    ) -> ListUsersOutput:
+        """List all users in the project.
+
+        Args:
+            limit: Maximum number of users to return. If not provided or 0, all users will be returned. 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:
+            ListUsersOutput containing the list of users and pagination information.
+        """
+        params = build_params(limit=limit, cursor=cursor, time_desc=time_desc)
+        data = await self._requester.request("GET", "/user/ls", params=params or None)
+        return ListUsersOutput.model_validate(data)
+
+    async def get_resources(self, identifier: str) -> GetUserResourcesOutput:
+        """Get resource counts for a user.
+
+        Args:
+            identifier: The user identifier string.
+
+        Returns:
+            GetUserResourcesOutput containing counts for Spaces, Sessions, Disks, and Skills.
+        """
+        data = await self._requester.request(
+            "GET", f"/user/{quote(identifier, safe='')}/resources"
+        )
+        return GetUserResourcesOutput.model_validate(data)
+
+    async def delete(self, identifier: str) -> None:
+        """Delete a user and cascade delete all associated resources (Space, Session, Disk, Skill).
+
+        Args:
+            identifier: The user identifier string.
+        """
+        await self._requester.request("DELETE", f"/user/{quote(identifier, safe='')}")

acontext/resources/disks.py

@@ -2,10 +2,14 @@
 Disk and artifact endpoints.
 """
 
+from __future__ import annotations
+
 import json
 from collections.abc import Mapping
 from typing import Any, BinaryIO, cast
 
+from pydantic import TypeAdapter
+
 from .._utils import build_params
 from ..client_types import RequesterProtocol
 from ..types.disk import (
@@ -27,6 +31,7 @@ class DisksAPI:
     def list(
         self,
         *,
+        user: str | None = None,
         limit: int | None = None,
         cursor: str | None = None,
         time_desc: bool | None = None,
@@ -34,6 +39,7 @@ class DisksAPI:
         """List all disks in the project.
         
         Args:
+            user: Filter by user identifier. Defaults to None.
             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.
@@ -41,17 +47,23 @@ class DisksAPI:
         Returns:
             ListDisksOutput containing the list of disks and pagination information.
         """
-        params = build_params(limit=limit, cursor=cursor, time_desc=time_desc)
+        params = build_params(user=user, 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:
+    def create(self, *, user: str | None = None) -> Disk:
         """Create a new disk.
         
+        Args:
+            user: Optional user identifier string. Defaults to None.
+            
         Returns:
             The created Disk object.
         """
-        data = self._requester.request("POST", "/disk")
+        payload: dict[str, Any] = {}
+        if user is not None:
+            payload["user"] = user
+        data = self._requester.request("POST", "/disk", json_data=payload or None)
         return Disk.model_validate(data)
 
     def delete(self, disk_id: str) -> None:
@@ -187,8 +199,85 @@ class DiskArtifactsAPI:
         *,
         path: str | None = None,
     ) -> ListArtifactsResp:
+        """List artifacts in a disk at a specific path.
+        
+        Args:
+            disk_id: The UUID of the disk.
+            path: Directory path to list. Defaults to None (root).
+            
+        Returns:
+            ListArtifactsResp containing the list of artifacts.
+        """
         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)
+
+    def grep_artifacts(
+        self,
+        disk_id: str,
+        *,
+        query: str,
+        limit: int = 100,
+    ) -> list[Artifact]:
+        """Search artifact content using regex pattern.
+        
+        Args:
+            disk_id: The disk ID to search in
+            query: Regex pattern to search for in file content
+            limit: Maximum number of results (default 100, max 1000)
+            
+        Returns:
+            List of matching artifacts
+            
+        Example:
+        ```python
+            # Search for TODO comments in code
+            results = client.disks.artifacts.grep_artifacts(
+                disk_id="disk-uuid",
+                query="TODO.*bug"
+            )
+        ```
+        """
+        params = build_params(query=query, limit=limit)
+        data = self._requester.request(
+            "GET",
+            f"/disk/{disk_id}/artifact/grep",
+            params=params
+        )
+        return TypeAdapter(list[Artifact]).validate_python(data)
+
+    def glob_artifacts(
+        self,
+        disk_id: str,
+        *,
+        query: str,
+        limit: int = 100,
+    ) -> list[Artifact]:
+        """Search artifact paths using glob pattern.
+        
+        Args:
+            disk_id: The disk ID to search in
+            query: Glob pattern (e.g., '**/*.py', '*.txt')
+            limit: Maximum number of results (default 100, max 1000)
+            
+        Returns:
+            List of matching artifacts
+            
+        Example:
+        ```python
+            # Find all Python files
+            results = client.disks.artifacts.glob_artifacts(
+                disk_id="disk-uuid",
+                query="**/*.py"
+            )
+        ```
+        """
+        params = build_params(query=query, limit=limit)
+        data = self._requester.request(
+            "GET",
+            f"/disk/{disk_id}/artifact/glob",
+            params=params
+        )
+        return TypeAdapter(list[Artifact]).validate_python(data)

acontext/resources/sessions.py

@@ -37,6 +37,7 @@ class SessionsAPI:
     def list(
         self,
         *,
+        user: str | None = None,
         space_id: str | None = None,
         not_connected: bool | None = None,
         limit: int | None = None,
@@ -46,6 +47,7 @@ class SessionsAPI:
         """List all sessions in the project.
 
         Args:
+            user: Filter by user identifier. Defaults to None.
             space_id: Filter sessions by space ID. Defaults to None.
             not_connected: Filter sessions that are not connected to a space. Defaults to None.
             limit: Maximum number of sessions to return. Defaults to None.
@@ -56,6 +58,8 @@ class SessionsAPI:
             ListSessionsOutput containing the list of sessions and pagination information.
         """
         params: dict[str, Any] = {}
+        if user:
+            params["user"] = user
         if space_id:
             params["space_id"] = space_id
         params.update(
@@ -72,6 +76,7 @@ class SessionsAPI:
     def create(
         self,
         *,
+        user: str | None = None,
         space_id: str | None = None,
         disable_task_tracking: bool | None = None,
         configs: Mapping[str, Any] | None = None,
@@ -79,6 +84,7 @@ class SessionsAPI:
         """Create a new session.
 
         Args:
+            user: Optional user identifier string. Defaults to None.
             space_id: Optional space ID to associate with the session. Defaults to None.
             disable_task_tracking: Whether to disable task tracking for this session. Defaults to None (server default: False).
             configs: Optional session configuration dictionary. Defaults to None.
@@ -87,6 +93,8 @@ class SessionsAPI:
             The created Session object.
         """
         payload: dict[str, Any] = {}
+        if user:
+            payload["user"] = user
         if space_id:
             payload["space_id"] = space_id
         if disable_task_tracking is not None:
@@ -271,6 +279,7 @@ class SessionsAPI:
         format: Literal["acontext", "openai", "anthropic", "gemini"] = "openai",
         time_desc: bool | None = None,
         edit_strategies: Optional[List[EditStrategy]] = None,
+        pin_editing_strategies_at_message: str | None = None,
     ) -> GetMessagesOutput:
         """Get messages for a session.
 
@@ -287,6 +296,12 @@ class SessionsAPI:
                     - Remove tool results: [{"type": "remove_tool_result", "params": {"keep_recent_n_tool_results": 3}}]
                     - Token limit: [{"type": "token_limit", "params": {"limit_tokens": 20000}}]
                 Defaults to None.
+            pin_editing_strategies_at_message: Message ID to pin editing strategies at.
+                When provided, strategies are only applied to messages up to and including
+                this message ID, keeping subsequent messages unchanged. This helps maintain
+                prompt cache stability by preserving a stable prefix. The response includes
+                edit_at_message_id indicating where strategies were applied. Pass this value
+                in subsequent requests to maintain cache hits. Defaults to None.
 
         Returns:
             GetMessagesOutput containing the list of messages and pagination information.
@@ -304,6 +319,8 @@ class SessionsAPI:
         )
         if edit_strategies is not None:
             params["edit_strategies"] = json.dumps(edit_strategies)
+        if pin_editing_strategies_at_message is not None:
+            params["pin_editing_strategies_at_message"] = pin_editing_strategies_at_message
         data = self._requester.request(
             "GET", f"/session/{session_id}/messages", params=params or None
         )

acontext/resources/skills.py

@@ -0,0 +1,146 @@
+"""
+Skills endpoints.
+"""
+
+import json
+from collections.abc import Mapping
+from typing import Any, BinaryIO, cast
+
+from .._utils import build_params
+from ..client_types import RequesterProtocol
+from ..types.skill import (
+    GetSkillFileResp,
+    ListSkillsOutput,
+    Skill,
+    SkillCatalogItem,
+    _ListSkillsResponse,
+)
+from ..uploads import FileUpload, normalize_file_upload
+
+
+class SkillsAPI:
+    def __init__(self, requester: RequesterProtocol) -> None:
+        self._requester = requester
+
+    def create(
+        self,
+        *,
+        file: FileUpload
+        | tuple[str, BinaryIO | bytes]
+        | tuple[str, BinaryIO | bytes, str],
+        user: str | None = None,
+        meta: Mapping[str, Any] | None = None,
+    ) -> Skill:
+        """Create a new skill by uploading a ZIP file.
+
+        The ZIP file must contain a SKILL.md file (case-insensitive) with YAML format
+        containing 'name' and 'description' fields.
+
+        Args:
+            file: The ZIP file to upload (FileUpload object or tuple format).
+            user: Optional user identifier string. Defaults to None.
+            meta: Custom metadata as JSON-serializable dict, defaults to None.
+
+        Returns:
+            Skill containing the created skill information.
+        """
+        upload = normalize_file_upload(file)
+        files = {"file": upload.as_httpx()}
+        form: dict[str, Any] = {}
+        if user is not None:
+            form["user"] = user
+        if meta is not None:
+            form["meta"] = json.dumps(cast(Mapping[str, Any], meta))
+        data = self._requester.request(
+            "POST",
+            "/agent_skills",
+            data=form or None,
+            files=files,
+        )
+        return Skill.model_validate(data)
+
+    def list_catalog(
+        self,
+        *,
+        user: str | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+        time_desc: bool | None = None,
+    ) -> ListSkillsOutput:
+        """Get a catalog of skills (names and descriptions only) with pagination.
+
+        Args:
+            user: Filter by user identifier. Defaults to None.
+            limit: Maximum number of skills per page (defaults to 100, max 200).
+            cursor: Cursor for pagination to fetch the next page (optional).
+            time_desc: Order by created_at descending if True, ascending if False (defaults to False).
+
+        Returns:
+            ListSkillsOutput containing skills with name and description for the current page,
+            along with pagination information (next_cursor and has_more).
+        """
+        effective_limit = limit if limit is not None else 100
+        params = build_params(user=user, limit=effective_limit, cursor=cursor, time_desc=time_desc)
+        data = self._requester.request("GET", "/agent_skills", params=params or None)
+        api_response = _ListSkillsResponse.model_validate(data)
+
+        # Convert to catalog format (name and description only)
+        return ListSkillsOutput(
+            items=[
+                SkillCatalogItem(name=skill.name, description=skill.description)
+                for skill in api_response.items
+            ],
+            next_cursor=api_response.next_cursor,
+            has_more=api_response.has_more,
+        )
+
+    def get_by_name(self, name: str) -> Skill:
+        """Get a skill by its name.
+
+        Args:
+            name: The name of the skill (unique within project).
+
+        Returns:
+            Skill containing the skill information.
+        """
+        params = {"name": name}
+        data = self._requester.request("GET", "/agent_skills/by_name", params=params)
+        return Skill.model_validate(data)
+
+    def delete(self, skill_id: str) -> None:
+        """Delete a skill by its ID.
+
+        Args:
+            skill_id: The UUID of the skill to delete.
+        """
+        self._requester.request("DELETE", f"/agent_skills/{skill_id}")
+
+    def get_file_by_name(
+        self,
+        *,
+        skill_name: str,
+        file_path: str,
+        expire: int | None = None,
+    ) -> GetSkillFileResp:
+        """Get a file from a skill by name.
+
+        The backend automatically returns content for parseable text files, or a presigned URL
+        for non-parseable files (binary, images, etc.).
+
+        Args:
+            skill_name: The name of the skill.
+            file_path: Relative path to the file within the skill (e.g., 'scripts/extract_text.json').
+            expire: URL expiration time in seconds. Defaults to 900 (15 minutes).
+
+        Returns:
+            GetSkillFileResp containing the file path, MIME type, and either content or URL.
+        """
+        endpoint = f"/agent_skills/by_name/{skill_name}/file"
+
+        params = {"file_path": file_path}
+        if expire is not None:
+            params["expire"] = expire
+
+        data = self._requester.request("GET", endpoint, params=params)
+        return GetSkillFileResp.model_validate(data)
+

acontext/resources/spaces.py

@@ -23,6 +23,7 @@ class SpacesAPI:
     def list(
         self,
         *,
+        user: str | None = None,
         limit: int | None = None,
         cursor: str | None = None,
         time_desc: bool | None = None,
@@ -30,6 +31,7 @@ class SpacesAPI:
         """List all spaces in the project.
 
         Args:
+            user: Filter by user identifier. Defaults to None.
             limit: Maximum number of spaces 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.
@@ -37,20 +39,28 @@ class SpacesAPI:
         Returns:
             ListSpacesOutput containing the list of spaces and pagination information.
         """
-        params = build_params(limit=limit, cursor=cursor, time_desc=time_desc)
+        params = build_params(user=user, limit=limit, cursor=cursor, time_desc=time_desc)
         data = self._requester.request("GET", "/space", params=params or None)
         return ListSpacesOutput.model_validate(data)
 
-    def create(self, *, configs: Mapping[str, Any] | None = None) -> Space:
+    def create(
+        self,
+        *,
+        user: str | None = None,
+        configs: Mapping[str, Any] | None = None,
+    ) -> Space:
         """Create a new space.
 
         Args:
+            user: Optional user identifier string. Defaults to None.
             configs: Optional space configuration dictionary. Defaults to None.
 
         Returns:
             The created Space object.
         """
         payload: dict[str, Any] = {}
+        if user is not None:
+            payload["user"] = user
         if configs is not None:
             payload["configs"] = configs
         data = self._requester.request("POST", "/space", json_data=payload)

acontext/resources/users.py

@@ -0,0 +1,57 @@
+"""
+User management endpoints.
+"""
+
+from urllib.parse import quote
+
+from .._utils import build_params
+from ..client_types import RequesterProtocol
+from ..types.user import GetUserResourcesOutput, ListUsersOutput
+
+
+class UsersAPI:
+    def __init__(self, requester: RequesterProtocol) -> None:
+        self._requester = requester
+
+    def list(
+        self,
+        *,
+        limit: int | None = None,
+        cursor: str | None = None,
+        time_desc: bool | None = None,
+    ) -> ListUsersOutput:
+        """List all users in the project.
+
+        Args:
+            limit: Maximum number of users to return. If not provided or 0, all users will be returned. 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:
+            ListUsersOutput containing the list of users and pagination information.
+        """
+        params = build_params(limit=limit, cursor=cursor, time_desc=time_desc)
+        data = self._requester.request("GET", "/user/ls", params=params or None)
+        return ListUsersOutput.model_validate(data)
+
+    def get_resources(self, identifier: str) -> GetUserResourcesOutput:
+        """Get resource counts for a user.
+
+        Args:
+            identifier: The user identifier string.
+
+        Returns:
+            GetUserResourcesOutput containing counts for Spaces, Sessions, Disks, and Skills.
+        """
+        data = self._requester.request(
+            "GET", f"/user/{quote(identifier, safe='')}/resources"
+        )
+        return GetUserResourcesOutput.model_validate(data)
+
+    def delete(self, identifier: str) -> None:
+        """Delete a user and cascade delete all associated resources (Space, Session, Disk, Skill).
+
+        Args:
+            identifier: The user identifier string.
+        """
+        self._requester.request("DELETE", f"/user/{quote(identifier, safe='')}")

acontext/types/__init__.py

@@ -1,9 +1,9 @@
 """Type definitions for API responses."""
 
+from .common import FileContent
 from .disk import (
     Artifact,
     Disk,
-    FileContent,
     GetArtifactResp,
     ListArtifactsResp,
     ListDisksOutput,
@@ -38,6 +38,19 @@ from .tool import (
     ToolReferenceData,
     ToolRenameItem,
 )
+from .skill import (
+    FileInfo,
+    GetSkillFileResp,
+    ListSkillsOutput,
+    Skill,
+    SkillCatalogItem,
+)
+from .user import (
+    GetUserResourcesOutput,
+    ListUsersOutput,
+    User,
+    UserResourceCounts,
+)
 
 __all__ = [
     # Disk types
@@ -75,4 +88,15 @@ __all__ = [
     "InsertBlockResponse",
     "ToolReferenceData",
     "ToolRenameItem",
+    # Skill types
+    "FileInfo",
+    "Skill",
+    "SkillCatalogItem",
+    "ListSkillsOutput",
+    "GetSkillFileResp",
+    # User types
+    "GetUserResourcesOutput",
+    "ListUsersOutput",
+    "User",
+    "UserResourceCounts",
 ]

acontext/types/common.py

@@ -0,0 +1,11 @@
+"""Common type definitions shared across modules."""
+
+from pydantic import BaseModel, Field
+
+
+class FileContent(BaseModel):
+    """Parsed file content model."""
+
+    type: str = Field(..., description="File content type: 'text', 'json', 'csv', or 'code'")
+    raw: str = Field(..., description="Raw text content of the file")
+

acontext/types/disk.py

@@ -4,12 +4,15 @@ from typing import Any
 
 from pydantic import BaseModel, Field
 
+from .common import FileContent
+
 
 class Disk(BaseModel):
     """Disk model representing a disk resource."""
 
     id: str = Field(..., description="Disk UUID")
     project_id: str = Field(..., description="Project UUID")
+    user_id: str | None = Field(None, description="User UUID")
     created_at: str = Field(..., description="ISO 8601 formatted creation timestamp")
     updated_at: str = Field(..., description="ISO 8601 formatted update timestamp")
 
@@ -36,13 +39,6 @@ class Artifact(BaseModel):
     updated_at: str = Field(..., description="ISO 8601 formatted update timestamp")
 
 
-class FileContent(BaseModel):
-    """Parsed file content model."""
-
-    type: str = Field(..., description="File content type: 'text', 'json', 'csv', or 'code'")
-    raw: str = Field(..., description="Raw text content of the file")
-
-
 class GetArtifactResp(BaseModel):
     """Response model for getting an artifact."""