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

acontext/agent/__init__.py

@@ -0,0 +1,10 @@
+"""Agent tools for LLM function calling."""
+
+from .disk import DISK_TOOLS
+from .skill import SKILL_TOOLS
+
+__all__ = [
+    "DISK_TOOLS",
+    "SKILL_TOOLS",
+]
+

acontext/agent/disk.py

@@ -328,6 +328,110 @@ class DownloadFileTool(BaseTool):
         return f"Public download URL for '{normalized_path}{filename}' (expires in {expire}s):\n{result.public_url}"
 
 
+class GrepArtifactsTool(BaseTool):
+    """Tool for searching artifact content using regex patterns."""
+
+    @property
+    def name(self) -> str:
+        return "grep_artifacts"
+
+    @property
+    def description(self) -> str:
+        return "Search for text patterns within file contents using regex. Only searches text-based files (code, markdown, json, csv, etc.). Use this to find specific code patterns, TODO comments, function definitions, or any text content."
+
+    @property
+    def arguments(self) -> dict:
+        return {
+            "query": {
+                "type": "string",
+                "description": "Regex pattern to search for (e.g., 'TODO.*', 'function.*calculate', 'import.*pandas')",
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Maximum number of results to return (default 100)",
+            },
+        }
+
+    @property
+    def required_arguments(self) -> list[str]:
+        return ["query"]
+
+    def execute(self, ctx: DiskContext, llm_arguments: dict) -> str:
+        """Search artifact content using regex pattern."""
+        query = llm_arguments.get("query")
+        limit = llm_arguments.get("limit", 100)
+
+        if not query:
+            raise ValueError("query is required")
+
+        results = ctx.client.disks.artifacts.grep_artifacts(
+            ctx.disk_id,
+            query=query,
+            limit=limit,
+        )
+
+        if not results:
+            return f"No matches found for pattern '{query}'"
+
+        matches = []
+        for artifact in results:
+            matches.append(f"{artifact.path}{artifact.filename}")
+
+        return f"Found {len(matches)} file(s) matching '{query}':\n" + "\n".join(matches)
+
+
+class GlobArtifactsTool(BaseTool):
+    """Tool for finding files by path pattern using glob syntax."""
+
+    @property
+    def name(self) -> str:
+        return "glob_artifacts"
+
+    @property
+    def description(self) -> str:
+        return "Find files by path pattern using glob syntax. Use * for any characters, ? for single character, ** for recursive directories. Perfect for finding files by extension or location."
+
+    @property
+    def arguments(self) -> dict:
+        return {
+            "query": {
+                "type": "string",
+                "description": "Glob pattern (e.g., '**/*.py' for all Python files, '*.txt' for text files in root, '/docs/**/*.md' for markdown in docs)",
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Maximum number of results to return (default 100)",
+            },
+        }
+
+    @property
+    def required_arguments(self) -> list[str]:
+        return ["query"]
+
+    def execute(self, ctx: DiskContext, llm_arguments: dict) -> str:
+        """Search artifact paths using glob pattern."""
+        query = llm_arguments.get("query")
+        limit = llm_arguments.get("limit", 100)
+
+        if not query:
+            raise ValueError("query is required")
+
+        results = ctx.client.disks.artifacts.glob_artifacts(
+            ctx.disk_id,
+            query=query,
+            limit=limit,
+        )
+
+        if not results:
+            return f"No files found matching pattern '{query}'"
+
+        matches = []
+        for artifact in results:
+            matches.append(f"{artifact.path}{artifact.filename}")
+
+        return f"Found {len(matches)} file(s) matching '{query}':\n" + "\n".join(matches)
+
+
 class DiskToolPool(BaseToolPool):
     """Tool pool for disk operations on Acontext disks."""
 
@@ -340,6 +444,8 @@ DISK_TOOLS.add_tool(WriteFileTool())
 DISK_TOOLS.add_tool(ReadFileTool())
 DISK_TOOLS.add_tool(ReplaceStringTool())
 DISK_TOOLS.add_tool(ListTool())
+DISK_TOOLS.add_tool(GrepArtifactsTool())
+DISK_TOOLS.add_tool(GlobArtifactsTool())
 DISK_TOOLS.add_tool(DownloadFileTool())
 
 

acontext/agent/skill.py

@@ -0,0 +1,148 @@
+"""
+Skill tools for agent operations.
+"""
+
+from dataclasses import dataclass
+
+from .base import BaseContext, BaseTool, BaseToolPool
+from ..client import AcontextClient
+
+
+@dataclass
+class SkillContext(BaseContext):
+    client: AcontextClient
+
+
+class GetSkillTool(BaseTool):
+    """Tool for getting a skill by name."""
+
+    @property
+    def name(self) -> str:
+        return "get_skill"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Get a skill by its name. Return the skill information including the relative paths of the files and their mime type categories" 
+        )
+
+    @property
+    def arguments(self) -> dict:
+        return {
+            "name": {
+                "type": "string",
+                "description": "The name of the skill (unique within project).",
+            },
+        }
+
+    @property
+    def required_arguments(self) -> list[str]:
+        return ["name"]
+
+    def execute(self, ctx: SkillContext, llm_arguments: dict) -> str:
+        """Get a skill by name."""
+        name = llm_arguments.get("name")
+
+        if not name:
+            raise ValueError("name is required")
+
+        skill = ctx.client.skills.get_by_name(name)
+
+        file_count = len(skill.file_index)
+        
+        # Format all files with path and MIME type
+        if skill.file_index:
+            file_list = "\n".join(
+                [f"  - {file_info.path} ({file_info.mime})" for file_info in skill.file_index]
+            )
+        else:
+            file_list = "  [NO FILES]"
+
+        return (
+            f"Skill: {skill.name} (ID: {skill.id})\n"
+            f"Description: {skill.description}\n"
+            f"Files: {file_count} file(s)\n"
+            f"{file_list}\n"
+            f"Created: {skill.created_at}\n"
+            f"Updated: {skill.updated_at}"
+        )
+
+
+class GetSkillFileTool(BaseTool):
+    """Tool for getting a file from a skill."""
+
+    @property
+    def name(self) -> str:
+        return "get_skill_file"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Get a file from a skill by name. The file_path should be a relative path within the skill (e.g., 'scripts/extract_text.json'). "
+        )
+
+    @property
+    def arguments(self) -> dict:
+        return {
+            "skill_name": {
+                "type": "string",
+                "description": "The name of the skill.",
+            },
+            "file_path": {
+                "type": "string",
+                "description": "Relative path to the file within the skill (e.g., 'scripts/extract_text.json').",
+            },
+            "expire": {
+                "type": "integer",
+                "description": "URL expiration time in seconds (only used for non-parseable files). Defaults to 900 (15 minutes).",
+            },
+        }
+
+    @property
+    def required_arguments(self) -> list[str]:
+        return ["skill_name", "file_path"]
+
+    def execute(self, ctx: SkillContext, llm_arguments: dict) -> str:
+        """Get a skill file."""
+        skill_name = llm_arguments.get("skill_name")
+        file_path = llm_arguments.get("file_path")
+        expire = llm_arguments.get("expire")
+
+        if not file_path:
+            raise ValueError("file_path is required")
+        if not skill_name:
+            raise ValueError("skill_name is required")
+
+        result = ctx.client.skills.get_file_by_name(
+            skill_name=skill_name,
+            file_path=file_path,
+            expire=expire,
+        )
+
+        output_parts = [f"File '{result.path}' (MIME: {result.mime}) from skill '{skill_name}':"]
+
+        if result.content:
+            output_parts.append(f"\nContent (type: {result.content.type}):")
+            output_parts.append(result.content.raw)
+
+        if result.url:
+            expire_seconds = expire if expire is not None else 900
+            output_parts.append(f"\nDownload URL (expires in {expire_seconds} seconds):")
+            output_parts.append(result.url)
+
+        if not result.content and not result.url:
+            return f"File '{result.path}' retrieved but no content or URL returned."
+
+        return "\n".join(output_parts)
+
+
+class SkillToolPool(BaseToolPool):
+    """Tool pool for skill operations on Acontext skills."""
+
+    def format_context(self, client: AcontextClient) -> SkillContext:
+        return SkillContext(client=client)
+
+
+SKILL_TOOLS = SkillToolPool()
+SKILL_TOOLS.add_tool(GetSkillTool())
+SKILL_TOOLS.add_tool(GetSkillFileTool())

acontext/async_client.py

@@ -17,6 +17,8 @@ from .resources.async_blocks import AsyncBlocksAPI as AsyncBlocksAPI
 from .resources.async_sessions import AsyncSessionsAPI as AsyncSessionsAPI
 from .resources.async_spaces import AsyncSpacesAPI as AsyncSpacesAPI
 from .resources.async_tools import AsyncToolsAPI as AsyncToolsAPI
+from .resources.async_skills import AsyncSkillsAPI as AsyncSkillsAPI
+from .resources.async_users import AsyncUsersAPI as AsyncUsersAPI
 
 
 class AcontextAsyncClient:
@@ -109,6 +111,8 @@ class AcontextAsyncClient:
         self.artifacts = self.disks.artifacts
         self.blocks = AsyncBlocksAPI(self)
         self.tools = AsyncToolsAPI(self)
+        self.skills = AsyncSkillsAPI(self)
+        self.users = AsyncUsersAPI(self)
 
     @property
     def base_url(self) -> str:

acontext/client.py

@@ -17,6 +17,8 @@ from .resources.blocks import BlocksAPI as BlocksAPI
 from .resources.sessions import SessionsAPI as SessionsAPI
 from .resources.spaces import SpacesAPI as SpacesAPI
 from .resources.tools import ToolsAPI as ToolsAPI
+from .resources.skills import SkillsAPI as SkillsAPI
+from .resources.users import UsersAPI as UsersAPI
 
 
 class AcontextClient:
@@ -109,6 +111,8 @@ class AcontextClient:
         self.artifacts = self.disks.artifacts
         self.blocks = BlocksAPI(self)
         self.tools = ToolsAPI(self)
+        self.skills = SkillsAPI(self)
+        self.users = UsersAPI(self)
 
     @property
     def base_url(self) -> str:

acontext/resources/__init__.py

@@ -5,11 +5,15 @@ from .async_disks import AsyncDisksAPI, AsyncDiskArtifactsAPI
 from .async_sessions import AsyncSessionsAPI
 from .async_spaces import AsyncSpacesAPI
 from .async_tools import AsyncToolsAPI
+from .async_skills import AsyncSkillsAPI
+from .async_users import AsyncUsersAPI
 from .blocks import BlocksAPI
 from .disks import DisksAPI, DiskArtifactsAPI
 from .sessions import SessionsAPI
 from .spaces import SpacesAPI
 from .tools import ToolsAPI
+from .skills import SkillsAPI
+from .users import UsersAPI
 
 __all__ = [
     "DisksAPI",
@@ -18,10 +22,14 @@ __all__ = [
     "SessionsAPI",
     "SpacesAPI",
     "ToolsAPI",
+    "SkillsAPI",
+    "UsersAPI",
     "AsyncDisksAPI",
     "AsyncDiskArtifactsAPI",
     "AsyncBlocksAPI",
     "AsyncSessionsAPI",
     "AsyncSpacesAPI",
     "AsyncToolsAPI",
+    "AsyncSkillsAPI",
+    "AsyncUsersAPI",
 ]

acontext/resources/async_disks.py

@@ -27,6 +27,7 @@ class AsyncDisksAPI:
     async def list(
         self,
         *,
+        user: str | None = None,
         limit: int | None = None,
         cursor: str | None = None,
         time_desc: bool | None = None,
@@ -34,6 +35,7 @@ class AsyncDisksAPI:
         """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 +43,23 @@ class AsyncDisksAPI:
         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 = await self._requester.request("GET", "/disk", params=params or None)
         return ListDisksOutput.model_validate(data)
 
-    async def create(self) -> Disk:
+    async 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 = await self._requester.request("POST", "/disk")
+        payload: dict[str, Any] = {}
+        if user is not None:
+            payload["user"] = user
+        data = await self._requester.request("POST", "/disk", json_data=payload or None)
         return Disk.model_validate(data)
 
     async def delete(self, disk_id: str) -> None:

acontext/resources/async_sessions.py

@@ -37,6 +37,7 @@ class AsyncSessionsAPI:
     async 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 AsyncSessionsAPI:
         """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 AsyncSessionsAPI:
             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,12 +76,14 @@ class AsyncSessionsAPI:
     async def create(
         self,
         *,
+        user: str | None = None,
         space_id: str | None = None,
         configs: Mapping[str, Any] | None = None,
     ) -> Session:
         """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.
             configs: Optional session configuration dictionary. Defaults to None.
 
@@ -85,6 +91,8 @@ class AsyncSessionsAPI:
             The created Session object.
         """
         payload: dict[str, Any] = {}
+        if user:
+            payload["user"] = user
         if space_id:
             payload["space_id"] = space_id
         if configs is not None:
@@ -267,6 +275,7 @@ class AsyncSessionsAPI:
         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.
 
@@ -283,6 +292,12 @@ class AsyncSessionsAPI:
                     - 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.
@@ -300,6 +315,10 @@ class AsyncSessionsAPI:
         )
         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 = await self._requester.request(
             "GET", f"/session/{session_id}/messages", params=params or None
         )
@@ -348,20 +367,21 @@ class AsyncSessionsAPI:
         )
         return TokenCounts.model_validate(data)
 
+
 async def messages_observing_status(self, session_id: str) -> MessageObservingStatus:
-        """Get message observing status counts for a session.
-        
-        Returns the count of messages by their observing status:
-        observed, in_process, and pending.
-        
-        Args:
-            session_id: The UUID of the session.
-        
-        Returns:
-            MessageObservingStatus object containing observed, in_process, 
-            pending counts and updated_at timestamp.
-        """
-        data = await self._requester.request(
-            "GET", f"/session/{session_id}/observing_status"
-        )
-        return MessageObservingStatus.model_validate(data)
+    """Get message observing status counts for a session.
+
+    Returns the count of messages by their observing status:
+    observed, in_process, and pending.
+
+    Args:
+        session_id: The UUID of the session.
+
+    Returns:
+        MessageObservingStatus object containing observed, in_process,
+        pending counts and updated_at timestamp.
+    """
+    data = await self._requester.request(
+        "GET", f"/session/{session_id}/observing_status"
+    )
+    return MessageObservingStatus.model_validate(data)

acontext/resources/async_skills.py

@@ -0,0 +1,150 @@
+"""
+Skills endpoints (async).
+"""
+
+import json
+from collections.abc import Mapping
+from typing import Any, BinaryIO, cast
+
+from .._utils import build_params
+from ..client_types import AsyncRequesterProtocol
+from ..types.skill import (
+    GetSkillFileResp,
+    ListSkillsOutput,
+    Skill,
+    SkillCatalogItem,
+    _ListSkillsResponse,
+)
+from ..uploads import FileUpload, normalize_file_upload
+
+
+class AsyncSkillsAPI:
+    def __init__(self, requester: AsyncRequesterProtocol) -> None:
+        self._requester = requester
+
+    async 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 = await self._requester.request(
+            "POST",
+            "/agent_skills",
+            data=form or None,
+            files=files,
+        )
+        return Skill.model_validate(data)
+
+    async 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 = await 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,
+        )
+
+    async 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 = await self._requester.request(
+            "GET", "/agent_skills/by_name", params=params
+        )
+        return Skill.model_validate(data)
+
+    async def delete(self, skill_id: str) -> None:
+        """Delete a skill by its ID.
+
+        Args:
+            skill_id: The UUID of the skill to delete.
+        """
+        await self._requester.request("DELETE", f"/agent_skills/{skill_id}")
+
+    async 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 = await self._requester.request("GET", endpoint, params=params)
+        return GetSkillFileResp.model_validate(data)
+