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

acontext/agent/skill.py

@@ -2,15 +2,126 @@
 Skill tools for agent operations.
 """
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 
 from .base import BaseContext, BaseTool, BaseToolPool
 from ..client import AcontextClient
+from ..async_client import AcontextAsyncClient
+from ..types.skill import Skill
 
 
 @dataclass
 class SkillContext(BaseContext):
+    """Context for skill tools with preloaded skill name mapping."""
+
     client: AcontextClient
+    skills: dict[str, Skill] = field(default_factory=dict)
+
+    @classmethod
+    def create(cls, client: AcontextClient, skill_ids: list[str]) -> "SkillContext":
+        """Create a SkillContext by preloading skills from a list of skill IDs.
+
+        Args:
+            client: The Acontext client instance.
+            skill_ids: List of skill UUIDs to preload.
+
+        Returns:
+            SkillContext with preloaded skills mapped by name.
+
+        Raises:
+            ValueError: If duplicate skill names are found.
+        """
+        skills: dict[str, Skill] = {}
+        for skill_id in skill_ids:
+            skill = client.skills.get(skill_id)
+            if skill.name in skills:
+                raise ValueError(
+                    f"Duplicate skill name '{skill.name}' found. "
+                    f"Existing ID: {skills[skill.name].id}, New ID: {skill.id}"
+                )
+            skills[skill.name] = skill
+        return cls(client=client, skills=skills)
+
+    def get_skill(self, skill_name: str) -> Skill:
+        """Get a skill by name from the preloaded skills.
+
+        Args:
+            skill_name: The name of the skill.
+
+        Returns:
+            The Skill object.
+
+        Raises:
+            ValueError: If the skill is not found in the context.
+        """
+        if skill_name not in self.skills:
+            available = ", ".join(self.skills.keys()) if self.skills else "[none]"
+            raise ValueError(
+                f"Skill '{skill_name}' not found in context. Available skills: {available}"
+            )
+        return self.skills[skill_name]
+
+    def list_skill_names(self) -> list[str]:
+        """Return list of available skill names in this context."""
+        return list(self.skills.keys())
+
+
+@dataclass
+class AsyncSkillContext(BaseContext):
+    """Async context for skill tools with preloaded skill name mapping."""
+
+    client: AcontextAsyncClient
+    skills: dict[str, Skill] = field(default_factory=dict)
+
+    @classmethod
+    async def create(
+        cls, client: AcontextAsyncClient, skill_ids: list[str]
+    ) -> "AsyncSkillContext":
+        """Create an AsyncSkillContext by preloading skills from a list of skill IDs.
+
+        Args:
+            client: The Acontext async client instance.
+            skill_ids: List of skill UUIDs to preload.
+
+        Returns:
+            AsyncSkillContext with preloaded skills mapped by name.
+
+        Raises:
+            ValueError: If duplicate skill names are found.
+        """
+        skills: dict[str, Skill] = {}
+        for skill_id in skill_ids:
+            skill = await client.skills.get(skill_id)
+            if skill.name in skills:
+                raise ValueError(
+                    f"Duplicate skill name '{skill.name}' found. "
+                    f"Existing ID: {skills[skill.name].id}, New ID: {skill.id}"
+                )
+            skills[skill.name] = skill
+        return cls(client=client, skills=skills)
+
+    def get_skill(self, skill_name: str) -> Skill:
+        """Get a skill by name from the preloaded skills.
+
+        Args:
+            skill_name: The name of the skill.
+
+        Returns:
+            The Skill object.
+
+        Raises:
+            ValueError: If the skill is not found in the context.
+        """
+        if skill_name not in self.skills:
+            available = ", ".join(self.skills.keys()) if self.skills else "[none]"
+            raise ValueError(
+                f"Skill '{skill_name}' not found in context. Available skills: {available}"
+            )
+        return self.skills[skill_name]
+
+    def list_skill_names(self) -> list[str]:
+        """Return list of available skill names in this context."""
+        return list(self.skills.keys())
 
 
 class GetSkillTool(BaseTool):
@@ -23,37 +134,70 @@ class GetSkillTool(BaseTool):
     @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" 
+            "Get a skill by its name. Returns the skill information including "
+            "the relative paths of the files and their mime type categories."
         )
 
     @property
     def arguments(self) -> dict:
         return {
-            "name": {
+            "skill_name": {
                 "type": "string",
-                "description": "The name of the skill (unique within project).",
+                "description": "The name of the skill.",
             },
         }
 
     @property
     def required_arguments(self) -> list[str]:
-        return ["name"]
+        return ["skill_name"]
 
     def execute(self, ctx: SkillContext, llm_arguments: dict) -> str:
         """Get a skill by name."""
-        name = llm_arguments.get("name")
+        skill_name = llm_arguments.get("skill_name")
+
+        if not skill_name:
+            raise ValueError("skill_name is required")
+
+        skill = ctx.get_skill(skill_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}"
+        )
+
+    async def async_execute(self, ctx: AsyncSkillContext, llm_arguments: dict) -> str:
+        """Get a skill by name (async)."""
+        skill_name = llm_arguments.get("skill_name")
 
-        if not name:
-            raise ValueError("name is required")
+        if not skill_name:
+            raise ValueError("skill_name is required")
 
-        skill = ctx.client.skills.get_by_name(name)
+        skill = ctx.get_skill(skill_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]
+                [
+                    f"  - {file_info.path} ({file_info.mime})"
+                    for file_info in skill.file_index
+                ]
             )
         else:
             file_list = "  [NO FILES]"
@@ -62,9 +206,7 @@ class GetSkillTool(BaseTool):
             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}"
+            f"{file_list}"
         )
 
 
@@ -78,7 +220,9 @@ class GetSkillFileTool(BaseTool):
     @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'). "
+            "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')."
+            "Tips: SKILL.md is the first file you should read to understand the full picture of this skill's content."
         )
 
     @property
@@ -108,18 +252,61 @@ class GetSkillFileTool(BaseTool):
         file_path = llm_arguments.get("file_path")
         expire = llm_arguments.get("expire")
 
+        if not skill_name:
+            raise ValueError("skill_name is required")
         if not file_path:
             raise ValueError("file_path is required")
+
+        skill = ctx.get_skill(skill_name)
+
+        result = ctx.client.skills.get_file(
+            skill_id=skill.id,
+            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)
+
+    async def async_execute(self, ctx: AsyncSkillContext, llm_arguments: dict) -> str:
+        """Get a skill file (async)."""
+        skill_name = llm_arguments.get("skill_name")
+        file_path = llm_arguments.get("file_path")
+        expire = llm_arguments.get("expire")
+
         if not skill_name:
             raise ValueError("skill_name is required")
+        if not file_path:
+            raise ValueError("file_path is required")
 
-        result = ctx.client.skills.get_file_by_name(
-            skill_name=skill_name,
+        skill = ctx.get_skill(skill_name)
+
+        result = await ctx.client.skills.get_file(
+            skill_id=skill.id,
             file_path=file_path,
             expire=expire,
         )
 
-        output_parts = [f"File '{result.path}' (MIME: {result.mime}) from skill '{skill_name}':"]
+        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}):")
@@ -127,7 +314,9 @@ class GetSkillFileTool(BaseTool):
 
         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(
+                f"\nDownload URL (expires in {expire_seconds} seconds):"
+            )
             output_parts.append(result.url)
 
         if not result.content and not result.url:
@@ -136,13 +325,81 @@ class GetSkillFileTool(BaseTool):
         return "\n".join(output_parts)
 
 
+class ListSkillsTool(BaseTool):
+    """Tool for listing available skills in the context."""
+
+    @property
+    def name(self) -> str:
+        return "list_skills"
+
+    @property
+    def description(self) -> str:
+        return "List all available skills in the current context with their names and descriptions."
+
+    @property
+    def arguments(self) -> dict:
+        return {}
+
+    @property
+    def required_arguments(self) -> list[str]:
+        return []
+
+    def execute(self, ctx: SkillContext, llm_arguments: dict) -> str:
+        """List all available skills."""
+        if not ctx.skills:
+            return "No skills available in the current context."
+
+        skill_list = []
+        for skill_name, skill in ctx.skills.items():
+            skill_list.append(f"- {skill_name}: {skill.description}")
+
+        return f"Available skills ({len(ctx.skills)}):\n" + "\n".join(skill_list)
+
+    async def async_execute(self, ctx: AsyncSkillContext, llm_arguments: dict) -> str:
+        """List all available skills (async)."""
+        if not ctx.skills:
+            return "No skills available in the current context."
+
+        skill_list = []
+        for skill_name, skill in ctx.skills.items():
+            skill_list.append(f"- {skill_name}: {skill.description}")
+
+        return f"Available skills ({len(ctx.skills)}):\n" + "\n".join(skill_list)
+
+
 class SkillToolPool(BaseToolPool):
     """Tool pool for skill operations on Acontext skills."""
 
-    def format_context(self, client: AcontextClient) -> SkillContext:
-        return SkillContext(client=client)
+    def format_context(
+        self, client: AcontextClient, skill_ids: list[str]
+    ) -> SkillContext:
+        """Create a SkillContext by preloading skills from a list of skill IDs.
+
+        Args:
+            client: The Acontext client instance.
+            skill_ids: List of skill UUIDs to preload.
+
+        Returns:
+            SkillContext with preloaded skills mapped by name.
+        """
+        return SkillContext.create(client=client, skill_ids=skill_ids)
+
+    async def async_format_context(
+        self, client: AcontextAsyncClient, skill_ids: list[str]
+    ) -> AsyncSkillContext:
+        """Create an AsyncSkillContext by preloading skills from a list of skill IDs.
+
+        Args:
+            client: The Acontext async client instance.
+            skill_ids: List of skill UUIDs to preload.
+
+        Returns:
+            AsyncSkillContext with preloaded skills mapped by name.
+        """
+        return await AsyncSkillContext.create(client=client, skill_ids=skill_ids)
 
 
 SKILL_TOOLS = SkillToolPool()
+SKILL_TOOLS.add_tool(ListSkillsTool())
 SKILL_TOOLS.add_tool(GetSkillTool())
 SKILL_TOOLS.add_tool(GetSkillFileTool())

acontext/resources/async_disks.py

@@ -33,26 +33,28 @@ class AsyncDisksAPI:
         time_desc: bool | None = None,
     ) -> ListDisksOutput:
         """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.
-            
+
         Returns:
             ListDisksOutput containing the list of disks and pagination information.
         """
-        params = build_params(user=user, 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, *, user: str | None = None) -> Disk:
         """Create a new disk.
-        
+
         Args:
             user: Optional user identifier string. Defaults to None.
-            
+
         Returns:
             The created Disk object.
         """
@@ -64,7 +66,7 @@ class AsyncDisksAPI:
 
     async def delete(self, disk_id: str) -> None:
         """Delete a disk by its ID.
-        
+
         Args:
             disk_id: The UUID of the disk to delete.
         """
@@ -79,20 +81,22 @@ class AsyncDiskArtifactsAPI:
         self,
         disk_id: str,
         *,
-        file: FileUpload
-        | tuple[str, BinaryIO | bytes]
-        | tuple[str, BinaryIO | bytes, str],
+        file: (
+            FileUpload
+            | tuple[str, BinaryIO | bytes]
+            | tuple[str, BinaryIO | bytes, str]
+        ),
         file_path: str | None = None,
         meta: Mapping[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.
         """
@@ -122,7 +126,7 @@ class AsyncDiskArtifactsAPI:
         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).
@@ -130,7 +134,7 @@ class AsyncDiskArtifactsAPI:
             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.
         """
@@ -141,7 +145,9 @@ class AsyncDiskArtifactsAPI:
             with_content=with_content,
             expire=expire,
         )
-        data = await self._requester.request("GET", f"/disk/{disk_id}/artifact", params=params)
+        data = await self._requester.request(
+            "GET", f"/disk/{disk_id}/artifact", params=params
+        )
         return GetArtifactResp.model_validate(data)
 
     async def update(
@@ -153,13 +159,13 @@ class AsyncDiskArtifactsAPI:
         meta: Mapping[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.
         """
@@ -168,7 +174,9 @@ class AsyncDiskArtifactsAPI:
             "file_path": full_path,
             "meta": json.dumps(cast(Mapping[str, Any], meta)),
         }
-        data = await self._requester.request("PUT", f"/disk/{disk_id}/artifact", json_data=payload)
+        data = await self._requester.request(
+            "PUT", f"/disk/{disk_id}/artifact", json_data=payload
+        )
         return UpdateArtifactResp.model_validate(data)
 
     async def delete(
@@ -179,7 +187,7 @@ class AsyncDiskArtifactsAPI:
         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).
@@ -187,7 +195,9 @@ class AsyncDiskArtifactsAPI:
         """
         full_path = f"{file_path.rstrip('/')}/{filename}"
         params = {"file_path": full_path}
-        await self._requester.request("DELETE", f"/disk/{disk_id}/artifact", params=params)
+        await self._requester.request(
+            "DELETE", f"/disk/{disk_id}/artifact", params=params
+        )
 
     async def list(
         self,
@@ -195,9 +205,83 @@ class AsyncDiskArtifactsAPI:
         *,
         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 = await self._requester.request("GET", f"/disk/{disk_id}/artifact/ls", params=params or None)
+        data = await self._requester.request(
+            "GET", f"/disk/{disk_id}/artifact/ls", params=params or None
+        )
         return ListArtifactsResp.model_validate(data)
 
+    async 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 = await client.disks.artifacts.grep_artifacts(
+                disk_id="disk-uuid",
+                query="TODO.*bug"
+            )
+        ```
+        """
+        params = build_params(query=query, limit=limit)
+        data = await self._requester.request(
+            "GET", f"/disk/{disk_id}/artifact/grep", params=params
+        )
+        return [Artifact.model_validate(item) for item in data]
+
+    async 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 = await client.disks.artifacts.glob_artifacts(
+                disk_id="disk-uuid",
+                query="**/*.py"
+            )
+        ```
+        """
+        params = build_params(query=query, limit=limit)
+        data = await self._requester.request(
+            "GET", f"/disk/{disk_id}/artifact/glob", params=params
+        )
+        return [Artifact.model_validate(item) for item in data]

acontext/resources/async_sessions.py

@@ -78,6 +78,7 @@ class AsyncSessionsAPI:
         *,
         user: str | None = None,
         space_id: str | None = None,
+        disable_task_tracking: bool | None = None,
         configs: Mapping[str, Any] | None = None,
     ) -> Session:
         """Create a new session.
@@ -85,6 +86,7 @@ class AsyncSessionsAPI:
         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.
 
         Returns:
@@ -95,6 +97,8 @@ class AsyncSessionsAPI:
             payload["user"] = user
         if space_id:
             payload["space_id"] = space_id
+        if disable_task_tracking is not None:
+            payload["disable_task_tracking"] = disable_task_tracking
         if configs is not None:
             payload["configs"] = configs
         data = await self._requester.request("POST", "/session", json_data=payload)
@@ -367,21 +371,22 @@ 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.
 
-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.
 
-    Returns the count of messages by their observing status:
-    observed, in_process, and pending.
-
-    Args:
-        session_id: The UUID of the session.
+        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)
+        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)