agentskills-azure 0.8.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- agentskills_azure-0.8.0/PKG-INFO +112 -0
- agentskills_azure-0.8.0/README.md +85 -0
- agentskills_azure-0.8.0/agentskills_azure/__init__.py +1 -0
- agentskills_azure-0.8.0/agentskills_azure/blob.py +215 -0
- agentskills_azure-0.8.0/agentskills_azure/files.py +274 -0
- agentskills_azure-0.8.0/agentskills_azure/py.typed +1 -0
- agentskills_azure-0.8.0/pyproject.toml +33 -0
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: agentskills-azure
|
|
3
|
+
Version: 0.8.0
|
|
4
|
+
Summary: Azure-backed providers for the Agent Skills format (https://agentskills.io)
|
|
5
|
+
License: MIT
|
|
6
|
+
Author: Pratik Panda
|
|
7
|
+
Requires-Python: >=3.12,<4.0
|
|
8
|
+
Classifier: Development Status :: 3 - Alpha
|
|
9
|
+
Classifier: Intended Audience :: Developers
|
|
10
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
16
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
17
|
+
Provides-Extra: blob
|
|
18
|
+
Provides-Extra: files
|
|
19
|
+
Requires-Dist: agentskills-core (>=0.8.0,<1.0)
|
|
20
|
+
Requires-Dist: azure-identity (>=1.19,<2.0)
|
|
21
|
+
Requires-Dist: azure-storage-blob[aio] (>=12.23,<13.0) ; extra == "blob"
|
|
22
|
+
Requires-Dist: azure-storage-file-share[aio] (>=12.23,<13.0) ; extra == "files"
|
|
23
|
+
Project-URL: Homepage, https://agentskills.io
|
|
24
|
+
Project-URL: Repository, https://github.com/pratikxpanda/agentskills-sdk
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
title: agentskills-azure
|
|
29
|
+
description: Azure-backed providers for Agent Skills with service-specific optional extras.
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
Azure-backed skill providers share this package and use service-specific modules and
|
|
33
|
+
optional dependencies. Blob Storage is available through the `blob` extra.
|
|
34
|
+
Azure Files SMB shares are available through the `files` extra.
|
|
35
|
+
|
|
36
|
+
## Install
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
pip install "agentskills-azure[blob,files]"
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Install only `agentskills-azure[blob]` or `agentskills-azure[files]` when you need one service.
|
|
43
|
+
|
|
44
|
+
## Blob Storage
|
|
45
|
+
|
|
46
|
+
Read Agent Skills from Azure Blob Storage with the asynchronous Azure SDK. The
|
|
47
|
+
provider uses `DefaultAzureCredential` by default, discovers skills from
|
|
48
|
+
`SKILL.md` blobs, and preserves original file bytes for complete manifests.
|
|
49
|
+
Each skill is a directory beneath the configured prefix, for example
|
|
50
|
+
`published/incident-response/SKILL.md`. Upload valid skill content before running the example.
|
|
51
|
+
Authenticate for local development with `az login`, or configure a managed identity in Azure.
|
|
52
|
+
Replace the account URL and container name with yours.
|
|
53
|
+
|
|
54
|
+
```python
|
|
55
|
+
import asyncio
|
|
56
|
+
|
|
57
|
+
from agentskills_azure.blob import AzureBlobSkillProvider
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
async def main() -> None:
|
|
61
|
+
async with AzureBlobSkillProvider(
|
|
62
|
+
"https://account.blob.core.windows.net", "skills", prefix="published/"
|
|
63
|
+
) as provider:
|
|
64
|
+
print(await provider.discover())
|
|
65
|
+
print(await provider.get_body("incident-response"))
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
asyncio.run(main())
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Pass an asynchronous Azure credential to `credential` when the application
|
|
72
|
+
manages authentication itself. Assign the identity only the blob permissions
|
|
73
|
+
needed to read the selected container.
|
|
74
|
+
|
|
75
|
+
## Azure Files
|
|
76
|
+
|
|
77
|
+
Use the async FileREST SDK to read skill directories from an SMB share without mounting it:
|
|
78
|
+
create the share and upload `published/incident-response/SKILL.md` first. The same Azure
|
|
79
|
+
credential-chain setup applies, but FileREST token authentication has different permissions.
|
|
80
|
+
|
|
81
|
+
```python
|
|
82
|
+
import asyncio
|
|
83
|
+
|
|
84
|
+
from agentskills_azure.files import AzureFilesSkillProvider
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
async def main() -> None:
|
|
88
|
+
async with AzureFilesSkillProvider(
|
|
89
|
+
"https://account.file.core.windows.net",
|
|
90
|
+
"skills",
|
|
91
|
+
prefix="published/",
|
|
92
|
+
token_intent="backup",
|
|
93
|
+
) as provider:
|
|
94
|
+
print(await provider.discover())
|
|
95
|
+
print(await provider.read_file("incident-response", "SKILL.md"))
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
asyncio.run(main())
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Token authentication requires the explicit `token_intent="backup"` opt-in. FileREST backup
|
|
102
|
+
intent bypasses file and directory ACLs, subject to Azure RBAC permissions. Assign the identity
|
|
103
|
+
only the required backup-read permissions at the narrowest applicable scope.
|
|
104
|
+
|
|
105
|
+
Discovery and listing read metadata without downloading file contents. Reads preserve original
|
|
106
|
+
bytes, disable automatic decompression, and enforce `max_file_bytes`. Recursive listing is bounded
|
|
107
|
+
by `max_files` and `max_depth`. NFS shares and reparse points are rejected.
|
|
108
|
+
|
|
109
|
+
Both providers close owned clients and default credentials. Caller-supplied async credentials
|
|
110
|
+
remain caller-owned. Fake-client conformance tests do not certify a production identity or share
|
|
111
|
+
configuration.
|
|
112
|
+
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: agentskills-azure
|
|
3
|
+
description: Azure-backed providers for Agent Skills with service-specific optional extras.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Azure-backed skill providers share this package and use service-specific modules and
|
|
7
|
+
optional dependencies. Blob Storage is available through the `blob` extra.
|
|
8
|
+
Azure Files SMB shares are available through the `files` extra.
|
|
9
|
+
|
|
10
|
+
## Install
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
pip install "agentskills-azure[blob,files]"
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Install only `agentskills-azure[blob]` or `agentskills-azure[files]` when you need one service.
|
|
17
|
+
|
|
18
|
+
## Blob Storage
|
|
19
|
+
|
|
20
|
+
Read Agent Skills from Azure Blob Storage with the asynchronous Azure SDK. The
|
|
21
|
+
provider uses `DefaultAzureCredential` by default, discovers skills from
|
|
22
|
+
`SKILL.md` blobs, and preserves original file bytes for complete manifests.
|
|
23
|
+
Each skill is a directory beneath the configured prefix, for example
|
|
24
|
+
`published/incident-response/SKILL.md`. Upload valid skill content before running the example.
|
|
25
|
+
Authenticate for local development with `az login`, or configure a managed identity in Azure.
|
|
26
|
+
Replace the account URL and container name with yours.
|
|
27
|
+
|
|
28
|
+
```python
|
|
29
|
+
import asyncio
|
|
30
|
+
|
|
31
|
+
from agentskills_azure.blob import AzureBlobSkillProvider
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
async def main() -> None:
|
|
35
|
+
async with AzureBlobSkillProvider(
|
|
36
|
+
"https://account.blob.core.windows.net", "skills", prefix="published/"
|
|
37
|
+
) as provider:
|
|
38
|
+
print(await provider.discover())
|
|
39
|
+
print(await provider.get_body("incident-response"))
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
asyncio.run(main())
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Pass an asynchronous Azure credential to `credential` when the application
|
|
46
|
+
manages authentication itself. Assign the identity only the blob permissions
|
|
47
|
+
needed to read the selected container.
|
|
48
|
+
|
|
49
|
+
## Azure Files
|
|
50
|
+
|
|
51
|
+
Use the async FileREST SDK to read skill directories from an SMB share without mounting it:
|
|
52
|
+
create the share and upload `published/incident-response/SKILL.md` first. The same Azure
|
|
53
|
+
credential-chain setup applies, but FileREST token authentication has different permissions.
|
|
54
|
+
|
|
55
|
+
```python
|
|
56
|
+
import asyncio
|
|
57
|
+
|
|
58
|
+
from agentskills_azure.files import AzureFilesSkillProvider
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
async def main() -> None:
|
|
62
|
+
async with AzureFilesSkillProvider(
|
|
63
|
+
"https://account.file.core.windows.net",
|
|
64
|
+
"skills",
|
|
65
|
+
prefix="published/",
|
|
66
|
+
token_intent="backup",
|
|
67
|
+
) as provider:
|
|
68
|
+
print(await provider.discover())
|
|
69
|
+
print(await provider.read_file("incident-response", "SKILL.md"))
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
asyncio.run(main())
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Token authentication requires the explicit `token_intent="backup"` opt-in. FileREST backup
|
|
76
|
+
intent bypasses file and directory ACLs, subject to Azure RBAC permissions. Assign the identity
|
|
77
|
+
only the required backup-read permissions at the narrowest applicable scope.
|
|
78
|
+
|
|
79
|
+
Discovery and listing read metadata without downloading file contents. Reads preserve original
|
|
80
|
+
bytes, disable automatic decompression, and enforce `max_file_bytes`. Recursive listing is bounded
|
|
81
|
+
by `max_files` and `max_depth`. NFS shares and reparse points are rejected.
|
|
82
|
+
|
|
83
|
+
Both providers close owned clients and default credentials. Caller-supplied async credentials
|
|
84
|
+
remain caller-owned. Fake-client conformance tests do not certify a production identity or share
|
|
85
|
+
configuration.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Azure-backed Agent Skills providers with provider-specific optional extras."""
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
"""Azure Blob Storage-backed Agent Skills provider."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from pathlib import PurePosixPath
|
|
6
|
+
from typing import Any
|
|
7
|
+
|
|
8
|
+
from azure.core.credentials_async import AsyncTokenCredential
|
|
9
|
+
from azure.core.exceptions import AzureError
|
|
10
|
+
from azure.core.exceptions import ResourceNotFoundError as AzureResourceNotFoundError
|
|
11
|
+
from azure.identity.aio import DefaultAzureCredential
|
|
12
|
+
|
|
13
|
+
from agentskills_core import (
|
|
14
|
+
RESOURCE_KINDS,
|
|
15
|
+
AgentSkillsError,
|
|
16
|
+
ResourceNotFoundError,
|
|
17
|
+
SkillNotFoundError,
|
|
18
|
+
SkillProvider,
|
|
19
|
+
split_frontmatter,
|
|
20
|
+
)
|
|
21
|
+
|
|
22
|
+
try:
|
|
23
|
+
from azure.storage.blob.aio import BlobServiceClient
|
|
24
|
+
except ModuleNotFoundError as exc:
|
|
25
|
+
raise ImportError("Install 'agentskills-azure[blob]' to use AzureBlobSkillProvider.") from exc
|
|
26
|
+
|
|
27
|
+
DEFAULT_MAX_FILE_BYTES = 10 * 1024 * 1024
|
|
28
|
+
SKILL_FILE_NAME = "SKILL.md"
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class AzureBlobSkillProvider(SkillProvider):
|
|
32
|
+
"""Read and discover skills stored as blobs beneath a container prefix.
|
|
33
|
+
|
|
34
|
+
A skill is a virtual directory containing ``SKILL.md`` and optional files.
|
|
35
|
+
The provider uses the Azure SDK's asynchronous clients and defaults to
|
|
36
|
+
``DefaultAzureCredential``. Call :meth:`aclose` when finished, or use the
|
|
37
|
+
provider as an asynchronous context manager.
|
|
38
|
+
|
|
39
|
+
Args:
|
|
40
|
+
account_url: Blob service endpoint, such as ``https://account.blob.core.windows.net``.
|
|
41
|
+
container_name: Container holding the skill blobs.
|
|
42
|
+
prefix: Optional path prefix inside the container.
|
|
43
|
+
credential: Optional asynchronous Azure credential. When omitted, the
|
|
44
|
+
provider creates and owns a ``DefaultAzureCredential``.
|
|
45
|
+
max_file_bytes: Maximum size of any file read by the provider.
|
|
46
|
+
|
|
47
|
+
Raises:
|
|
48
|
+
ValueError: If the container name, prefix, or size limit is invalid.
|
|
49
|
+
"""
|
|
50
|
+
|
|
51
|
+
supports_discovery = True
|
|
52
|
+
supports_resource_listing = True
|
|
53
|
+
supports_file_access = True
|
|
54
|
+
|
|
55
|
+
def __init__(
|
|
56
|
+
self,
|
|
57
|
+
account_url: str,
|
|
58
|
+
container_name: str,
|
|
59
|
+
*,
|
|
60
|
+
prefix: str = "",
|
|
61
|
+
credential: AsyncTokenCredential | None = None,
|
|
62
|
+
max_file_bytes: int = DEFAULT_MAX_FILE_BYTES,
|
|
63
|
+
) -> None:
|
|
64
|
+
if not container_name or "/" in container_name or "\\" in container_name:
|
|
65
|
+
raise ValueError("container_name must be a non-empty container name")
|
|
66
|
+
if max_file_bytes < 0:
|
|
67
|
+
raise ValueError("max_file_bytes must be non-negative")
|
|
68
|
+
self._prefix = self._normalize_prefix(prefix)
|
|
69
|
+
self._max_file_bytes = max_file_bytes
|
|
70
|
+
self._owns_credential = credential is None
|
|
71
|
+
self._credential = credential or DefaultAzureCredential()
|
|
72
|
+
self._service = BlobServiceClient(account_url, credential=self._credential)
|
|
73
|
+
self._container = self._service.get_container_client(container_name)
|
|
74
|
+
|
|
75
|
+
async def __aenter__(self) -> AzureBlobSkillProvider:
|
|
76
|
+
return self
|
|
77
|
+
|
|
78
|
+
async def __aexit__(self, *_: object) -> None:
|
|
79
|
+
await self.aclose()
|
|
80
|
+
|
|
81
|
+
async def aclose(self) -> None:
|
|
82
|
+
"""Close the Blob service client and any credential created by this provider."""
|
|
83
|
+
await self._service.close()
|
|
84
|
+
if self._owns_credential:
|
|
85
|
+
await self._credential.close()
|
|
86
|
+
|
|
87
|
+
async def discover(self) -> list[str]:
|
|
88
|
+
"""List skill IDs with a top-level ``SKILL.md`` blob."""
|
|
89
|
+
skill_ids: set[str] = set()
|
|
90
|
+
async for blob in self._container.list_blobs(name_starts_with=self._prefix or None):
|
|
91
|
+
relative = blob.name[len(self._prefix) :]
|
|
92
|
+
parts = relative.split("/")
|
|
93
|
+
if len(parts) == 2 and parts[1] == SKILL_FILE_NAME and self._valid_segment(parts[0]):
|
|
94
|
+
skill_ids.add(parts[0])
|
|
95
|
+
return sorted(skill_ids)
|
|
96
|
+
|
|
97
|
+
async def get_metadata(self, skill_id: str) -> dict[str, Any]:
|
|
98
|
+
"""Parse and return a skill's YAML frontmatter."""
|
|
99
|
+
raw = await self._read_skill_md(skill_id)
|
|
100
|
+
metadata, _ = split_frontmatter(raw)
|
|
101
|
+
return metadata
|
|
102
|
+
|
|
103
|
+
async def get_body(self, skill_id: str) -> str:
|
|
104
|
+
"""Return the Markdown body after a skill's YAML frontmatter."""
|
|
105
|
+
raw = await self._read_skill_md(skill_id)
|
|
106
|
+
_, body = split_frontmatter(raw)
|
|
107
|
+
return body
|
|
108
|
+
|
|
109
|
+
async def get_script(self, skill_id: str, name: str) -> bytes:
|
|
110
|
+
"""Read one script as raw bytes."""
|
|
111
|
+
return await self.read_file(skill_id, f"scripts/{name}")
|
|
112
|
+
|
|
113
|
+
async def get_asset(self, skill_id: str, name: str) -> bytes:
|
|
114
|
+
"""Read one asset as raw bytes."""
|
|
115
|
+
return await self.read_file(skill_id, f"assets/{name}")
|
|
116
|
+
|
|
117
|
+
async def get_reference(self, skill_id: str, name: str) -> bytes:
|
|
118
|
+
"""Read one reference as raw bytes."""
|
|
119
|
+
return await self.read_file(skill_id, f"references/{name}")
|
|
120
|
+
|
|
121
|
+
async def list_resources(self, skill_id: str) -> dict[str, list[str]]:
|
|
122
|
+
"""List direct files in the standard resource directories."""
|
|
123
|
+
paths = await self.list_files(skill_id)
|
|
124
|
+
resources = {kind: [] for kind in RESOURCE_KINDS}
|
|
125
|
+
for path in paths:
|
|
126
|
+
parts = path.split("/")
|
|
127
|
+
if len(parts) == 2 and parts[0] in resources:
|
|
128
|
+
resources[parts[0]].append(parts[1])
|
|
129
|
+
return {kind: sorted(names) for kind, names in resources.items()}
|
|
130
|
+
|
|
131
|
+
async def list_files(self, skill_id: str) -> list[str]:
|
|
132
|
+
"""List all file paths in a skill without downloading their contents."""
|
|
133
|
+
prefix = self._skill_prefix(skill_id)
|
|
134
|
+
files: list[str] = []
|
|
135
|
+
async for blob in self._container.list_blobs(name_starts_with=prefix):
|
|
136
|
+
relative = blob.name[len(prefix) :]
|
|
137
|
+
if relative and not relative.endswith("/"):
|
|
138
|
+
self._validate_relative_path(relative)
|
|
139
|
+
files.append(relative)
|
|
140
|
+
if SKILL_FILE_NAME not in files:
|
|
141
|
+
raise SkillNotFoundError(f"Skill not found: {skill_id!r}")
|
|
142
|
+
return sorted(files)
|
|
143
|
+
|
|
144
|
+
async def read_file(self, skill_id: str, path: str) -> bytes:
|
|
145
|
+
"""Read a complete file as original bytes, without newline conversion."""
|
|
146
|
+
relative = self._validate_relative_path(path)
|
|
147
|
+
blob_name = f"{self._skill_prefix(skill_id)}{relative}"
|
|
148
|
+
blob = self._container.get_blob_client(blob_name)
|
|
149
|
+
try:
|
|
150
|
+
properties = await blob.get_blob_properties()
|
|
151
|
+
if properties.size > self._max_file_bytes:
|
|
152
|
+
raise AgentSkillsError(
|
|
153
|
+
f"File exceeds the {self._max_file_bytes}-byte limit: {relative}"
|
|
154
|
+
)
|
|
155
|
+
chunks: list[bytes] = []
|
|
156
|
+
size = 0
|
|
157
|
+
async for chunk in (await blob.download_blob()).chunks():
|
|
158
|
+
size += len(chunk)
|
|
159
|
+
if size > self._max_file_bytes:
|
|
160
|
+
raise AgentSkillsError(
|
|
161
|
+
f"File exceeds the {self._max_file_bytes}-byte limit: {relative}"
|
|
162
|
+
)
|
|
163
|
+
chunks.append(chunk)
|
|
164
|
+
content = b"".join(chunks)
|
|
165
|
+
except AzureResourceNotFoundError as exc:
|
|
166
|
+
raise ResourceNotFoundError(f"File not found: {skill_id}/{relative}") from exc
|
|
167
|
+
except AzureError as exc:
|
|
168
|
+
raise AgentSkillsError("Azure Blob Storage request failed") from exc
|
|
169
|
+
if len(content) > self._max_file_bytes:
|
|
170
|
+
raise AgentSkillsError(
|
|
171
|
+
f"File exceeds the {self._max_file_bytes}-byte limit: {relative}"
|
|
172
|
+
)
|
|
173
|
+
return content
|
|
174
|
+
|
|
175
|
+
async def _read_skill_md(self, skill_id: str) -> str:
|
|
176
|
+
try:
|
|
177
|
+
return (await self.read_file(skill_id, SKILL_FILE_NAME)).decode("utf-8")
|
|
178
|
+
except ResourceNotFoundError as exc:
|
|
179
|
+
raise SkillNotFoundError(f"Skill not found: {skill_id!r}") from exc
|
|
180
|
+
except UnicodeDecodeError as exc:
|
|
181
|
+
raise AgentSkillsError(f"SKILL.md must contain UTF-8 text: {skill_id!r}") from exc
|
|
182
|
+
|
|
183
|
+
def _skill_prefix(self, skill_id: str) -> str:
|
|
184
|
+
if not self._valid_segment(skill_id):
|
|
185
|
+
raise SkillNotFoundError(f"Invalid skill ID: {skill_id!r}")
|
|
186
|
+
return f"{self._prefix}{skill_id}/"
|
|
187
|
+
|
|
188
|
+
@staticmethod
|
|
189
|
+
def _normalize_prefix(prefix: str) -> str:
|
|
190
|
+
if not prefix:
|
|
191
|
+
return ""
|
|
192
|
+
candidate = prefix[:-1] if prefix.endswith("/") else prefix
|
|
193
|
+
path = AzureBlobSkillProvider._validate_relative_path(candidate)
|
|
194
|
+
return f"{path}/"
|
|
195
|
+
|
|
196
|
+
@staticmethod
|
|
197
|
+
def _valid_segment(value: str) -> bool:
|
|
198
|
+
return (
|
|
199
|
+
bool(value)
|
|
200
|
+
and value not in {".", ".."}
|
|
201
|
+
and not any(char in value for char in "/\\\x00")
|
|
202
|
+
)
|
|
203
|
+
|
|
204
|
+
@staticmethod
|
|
205
|
+
def _validate_relative_path(path: str) -> str:
|
|
206
|
+
candidate = PurePosixPath(path)
|
|
207
|
+
if (
|
|
208
|
+
not path
|
|
209
|
+
or "\\" in path
|
|
210
|
+
or "\x00" in path
|
|
211
|
+
or candidate.is_absolute()
|
|
212
|
+
or any(part in {"", ".", ".."} for part in path.split("/"))
|
|
213
|
+
):
|
|
214
|
+
raise ResourceNotFoundError(f"Invalid skill file path: {path!r}")
|
|
215
|
+
return candidate.as_posix()
|
|
@@ -0,0 +1,274 @@
|
|
|
1
|
+
"""Azure Files-backed Agent Skills provider."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from pathlib import PurePosixPath
|
|
6
|
+
from typing import Any, Literal
|
|
7
|
+
|
|
8
|
+
from azure.core.credentials_async import AsyncTokenCredential
|
|
9
|
+
from azure.core.exceptions import AzureError
|
|
10
|
+
from azure.core.exceptions import ResourceNotFoundError as AzureResourceNotFoundError
|
|
11
|
+
from azure.identity.aio import DefaultAzureCredential
|
|
12
|
+
|
|
13
|
+
from agentskills_core import (
|
|
14
|
+
RESOURCE_KINDS,
|
|
15
|
+
AgentSkillsError,
|
|
16
|
+
ResourceNotFoundError,
|
|
17
|
+
SkillNotFoundError,
|
|
18
|
+
SkillProvider,
|
|
19
|
+
split_frontmatter,
|
|
20
|
+
)
|
|
21
|
+
|
|
22
|
+
try:
|
|
23
|
+
from azure.storage.fileshare.aio import ShareClient, ShareDirectoryClient
|
|
24
|
+
except ModuleNotFoundError as exc:
|
|
25
|
+
raise ImportError("Install 'agentskills-azure[files]' to use AzureFilesSkillProvider.") from exc
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class AzureFilesSkillProvider(SkillProvider):
|
|
29
|
+
"""Read skills from directories in an Azure Files SMB share.
|
|
30
|
+
|
|
31
|
+
Uses the async FileREST SDK, not a mounted filesystem. Token authentication
|
|
32
|
+
requires an explicit ``token_intent="backup"`` opt-in because it bypasses
|
|
33
|
+
file ACLs subject to Azure RBAC. NFS shares and reparse points are rejected.
|
|
34
|
+
|
|
35
|
+
Args:
|
|
36
|
+
account_url: File service endpoint, such as ``https://account.file.core.windows.net``.
|
|
37
|
+
share_name: SMB share containing the skill directories.
|
|
38
|
+
prefix: Optional directory beneath which skills are stored.
|
|
39
|
+
credential: Caller-owned async credential. Defaults to an owned
|
|
40
|
+
``DefaultAzureCredential``.
|
|
41
|
+
token_intent: Must be ``"backup"`` to acknowledge FileREST token semantics.
|
|
42
|
+
max_file_bytes: Maximum bytes returned by a file read.
|
|
43
|
+
max_files: Maximum files listed in one skill.
|
|
44
|
+
max_depth: Maximum nested directory depth inside one skill.
|
|
45
|
+
|
|
46
|
+
Raises:
|
|
47
|
+
ValueError: If the share, limits, or token intent are invalid.
|
|
48
|
+
ResourceNotFoundError: If the prefix contains an unsafe path.
|
|
49
|
+
"""
|
|
50
|
+
|
|
51
|
+
supports_discovery = True
|
|
52
|
+
supports_resource_listing = True
|
|
53
|
+
supports_file_access = True
|
|
54
|
+
|
|
55
|
+
def __init__(
|
|
56
|
+
self,
|
|
57
|
+
account_url: str,
|
|
58
|
+
share_name: str,
|
|
59
|
+
*,
|
|
60
|
+
prefix: str = "",
|
|
61
|
+
credential: AsyncTokenCredential | None = None,
|
|
62
|
+
token_intent: Literal["backup"] | None = None,
|
|
63
|
+
max_file_bytes: int = 10 * 1024 * 1024,
|
|
64
|
+
max_files: int = 10_000,
|
|
65
|
+
max_depth: int = 64,
|
|
66
|
+
) -> None:
|
|
67
|
+
if not self._valid_segment(share_name):
|
|
68
|
+
raise ValueError("share_name must be a non-empty share name")
|
|
69
|
+
if max_file_bytes < 0 or max_files < 1 or max_depth < 0:
|
|
70
|
+
raise ValueError(
|
|
71
|
+
"File size and depth limits must be non-negative and max_files positive"
|
|
72
|
+
)
|
|
73
|
+
if token_intent != "backup":
|
|
74
|
+
raise ValueError(
|
|
75
|
+
"Azure Files token credentials require token_intent='backup'; "
|
|
76
|
+
"this bypasses file ACLs and requires an authorized Azure RBAC role"
|
|
77
|
+
)
|
|
78
|
+
self._prefix = self._validate_path(prefix.removesuffix("/")) if prefix else ""
|
|
79
|
+
self._max_file_bytes = max_file_bytes
|
|
80
|
+
self._max_files = max_files
|
|
81
|
+
self._max_depth = max_depth
|
|
82
|
+
self._owns_credential = credential is None
|
|
83
|
+
self._credential = credential if credential is not None else DefaultAzureCredential()
|
|
84
|
+
self._share = ShareClient(
|
|
85
|
+
account_url,
|
|
86
|
+
share_name,
|
|
87
|
+
credential=self._credential,
|
|
88
|
+
token_intent=token_intent,
|
|
89
|
+
allow_trailing_dot=True,
|
|
90
|
+
)
|
|
91
|
+
|
|
92
|
+
async def __aenter__(self) -> AzureFilesSkillProvider:
|
|
93
|
+
return self
|
|
94
|
+
|
|
95
|
+
async def __aexit__(self, *_: object) -> None:
|
|
96
|
+
await self.aclose()
|
|
97
|
+
|
|
98
|
+
async def aclose(self) -> None:
|
|
99
|
+
"""Close the share client and any provider-owned credential."""
|
|
100
|
+
try:
|
|
101
|
+
await self._share.close()
|
|
102
|
+
finally:
|
|
103
|
+
if self._owns_credential:
|
|
104
|
+
await self._credential.close()
|
|
105
|
+
|
|
106
|
+
async def discover(self) -> list[str]:
|
|
107
|
+
"""Discover immediate skill directories using metadata only."""
|
|
108
|
+
skill_ids: list[str] = []
|
|
109
|
+
try:
|
|
110
|
+
root = await self._directory(self._prefix)
|
|
111
|
+
async for entry in root.list_directories_and_files(include=["Attributes"]):
|
|
112
|
+
if not entry.is_directory or not self._valid_segment(entry.name):
|
|
113
|
+
continue
|
|
114
|
+
self._reject_link(entry)
|
|
115
|
+
directory = root.get_subdirectory_client(entry.name)
|
|
116
|
+
self._reject_link(await directory.get_directory_properties())
|
|
117
|
+
try:
|
|
118
|
+
properties = await directory.get_file_client("SKILL.md").get_file_properties()
|
|
119
|
+
except AzureResourceNotFoundError:
|
|
120
|
+
continue
|
|
121
|
+
self._reject_link(properties)
|
|
122
|
+
skill_ids.append(entry.name)
|
|
123
|
+
except AzureError as exc:
|
|
124
|
+
raise AgentSkillsError("Azure Files discovery failed") from exc
|
|
125
|
+
return sorted(skill_ids)
|
|
126
|
+
|
|
127
|
+
async def get_metadata(self, skill_id: str) -> dict[str, Any]:
|
|
128
|
+
"""Return the skill's YAML frontmatter."""
|
|
129
|
+
metadata, _ = split_frontmatter(await self._read_skill_md(skill_id))
|
|
130
|
+
return metadata
|
|
131
|
+
|
|
132
|
+
async def get_body(self, skill_id: str) -> str:
|
|
133
|
+
"""Return the Markdown body after the frontmatter."""
|
|
134
|
+
_, body = split_frontmatter(await self._read_skill_md(skill_id))
|
|
135
|
+
return body
|
|
136
|
+
|
|
137
|
+
async def get_script(self, skill_id: str, name: str) -> bytes:
|
|
138
|
+
"""Read one script without executing it."""
|
|
139
|
+
return await self.read_file(skill_id, f"scripts/{name}")
|
|
140
|
+
|
|
141
|
+
async def get_asset(self, skill_id: str, name: str) -> bytes:
|
|
142
|
+
"""Read one asset as original bytes."""
|
|
143
|
+
return await self.read_file(skill_id, f"assets/{name}")
|
|
144
|
+
|
|
145
|
+
async def get_reference(self, skill_id: str, name: str) -> bytes:
|
|
146
|
+
"""Read one reference as original bytes."""
|
|
147
|
+
return await self.read_file(skill_id, f"references/{name}")
|
|
148
|
+
|
|
149
|
+
async def list_resources(self, skill_id: str) -> dict[str, list[str]]:
|
|
150
|
+
"""List direct files in the standard resource directories."""
|
|
151
|
+
resources = {kind: [] for kind in RESOURCE_KINDS}
|
|
152
|
+
for path in await self.list_files(skill_id):
|
|
153
|
+
parts = path.split("/")
|
|
154
|
+
if len(parts) == 2 and parts[0] in resources:
|
|
155
|
+
resources[parts[0]].append(parts[1])
|
|
156
|
+
return {kind: sorted(names) for kind, names in resources.items()}
|
|
157
|
+
|
|
158
|
+
async def list_files(self, skill_id: str) -> list[str]:
|
|
159
|
+
"""List canonical files recursively without downloading their contents."""
|
|
160
|
+
root_path = self._skill_path(skill_id)
|
|
161
|
+
try:
|
|
162
|
+
root = await self._directory(root_path)
|
|
163
|
+
except AzureResourceNotFoundError as exc:
|
|
164
|
+
raise SkillNotFoundError(f"Skill not found: {skill_id!r}") from exc
|
|
165
|
+
except AzureError as exc:
|
|
166
|
+
raise AgentSkillsError("Azure Files listing failed") from exc
|
|
167
|
+
files: list[str] = []
|
|
168
|
+
pending = [(root, "", 0)]
|
|
169
|
+
directories = 0
|
|
170
|
+
try:
|
|
171
|
+
while pending:
|
|
172
|
+
directory, relative, depth = pending.pop()
|
|
173
|
+
async for entry in directory.list_directories_and_files(include=["Attributes"]):
|
|
174
|
+
if not self._valid_segment(entry.name):
|
|
175
|
+
raise ResourceNotFoundError("Invalid Azure Files directory entry")
|
|
176
|
+
self._reject_link(entry)
|
|
177
|
+
path = f"{relative}/{entry.name}" if relative else entry.name
|
|
178
|
+
if entry.is_directory:
|
|
179
|
+
directories += 1
|
|
180
|
+
if depth >= self._max_depth or directories > self._max_files:
|
|
181
|
+
raise AgentSkillsError("Azure Files directory traversal limit exceeded")
|
|
182
|
+
child = directory.get_subdirectory_client(entry.name)
|
|
183
|
+
self._reject_link(await child.get_directory_properties())
|
|
184
|
+
pending.append((child, path, depth + 1))
|
|
185
|
+
else:
|
|
186
|
+
files.append(path)
|
|
187
|
+
if len(files) > self._max_files:
|
|
188
|
+
raise AgentSkillsError("Azure Files file count limit exceeded")
|
|
189
|
+
except AzureResourceNotFoundError as exc:
|
|
190
|
+
raise ResourceNotFoundError("Azure Files directory disappeared during listing") from exc
|
|
191
|
+
except AzureError as exc:
|
|
192
|
+
raise AgentSkillsError("Azure Files listing failed") from exc
|
|
193
|
+
if "SKILL.md" not in files:
|
|
194
|
+
raise SkillNotFoundError(f"Skill not found: {skill_id!r}")
|
|
195
|
+
return sorted(files)
|
|
196
|
+
|
|
197
|
+
async def read_file(self, skill_id: str, path: str) -> bytes:
|
|
198
|
+
"""Read original bytes with preflight and streamed size enforcement."""
|
|
199
|
+
relative = self._validate_path(path)
|
|
200
|
+
full_path = f"{self._skill_path(skill_id)}/{relative}"
|
|
201
|
+
parent, name = full_path.rsplit("/", 1)
|
|
202
|
+
try:
|
|
203
|
+
directory = await self._directory(parent)
|
|
204
|
+
file = directory.get_file_client(name)
|
|
205
|
+
properties = await file.get_file_properties()
|
|
206
|
+
self._reject_link(properties)
|
|
207
|
+
if properties.size > self._max_file_bytes:
|
|
208
|
+
raise AgentSkillsError(
|
|
209
|
+
f"File exceeds the {self._max_file_bytes}-byte limit: {path}"
|
|
210
|
+
)
|
|
211
|
+
chunks: list[bytes] = []
|
|
212
|
+
size = 0
|
|
213
|
+
async for chunk in (await file.download_file(decompress=False)).chunks():
|
|
214
|
+
size += len(chunk)
|
|
215
|
+
if size > self._max_file_bytes:
|
|
216
|
+
raise AgentSkillsError(
|
|
217
|
+
f"File exceeds the {self._max_file_bytes}-byte limit: {path}"
|
|
218
|
+
)
|
|
219
|
+
chunks.append(chunk)
|
|
220
|
+
return b"".join(chunks)
|
|
221
|
+
except AzureResourceNotFoundError as exc:
|
|
222
|
+
raise ResourceNotFoundError(f"File not found: {skill_id}/{relative}") from exc
|
|
223
|
+
except AzureError as exc:
|
|
224
|
+
raise AgentSkillsError("Azure Files read failed") from exc
|
|
225
|
+
|
|
226
|
+
async def _directory(self, path: str) -> ShareDirectoryClient:
|
|
227
|
+
properties = await self._share.get_share_properties()
|
|
228
|
+
if properties.protocols != "SMB":
|
|
229
|
+
raise AgentSkillsError("Only SMB Azure Files shares are supported")
|
|
230
|
+
directory = self._share.get_directory_client("")
|
|
231
|
+
self._reject_link(await directory.get_directory_properties())
|
|
232
|
+
for segment in path.split("/") if path else []:
|
|
233
|
+
directory = directory.get_subdirectory_client(segment)
|
|
234
|
+
self._reject_link(await directory.get_directory_properties())
|
|
235
|
+
return directory
|
|
236
|
+
|
|
237
|
+
async def _read_skill_md(self, skill_id: str) -> str:
|
|
238
|
+
try:
|
|
239
|
+
return (await self.read_file(skill_id, "SKILL.md")).decode("utf-8")
|
|
240
|
+
except ResourceNotFoundError as exc:
|
|
241
|
+
raise SkillNotFoundError(f"Skill not found: {skill_id!r}") from exc
|
|
242
|
+
except UnicodeDecodeError as exc:
|
|
243
|
+
raise AgentSkillsError(f"SKILL.md must contain UTF-8 text: {skill_id!r}") from exc
|
|
244
|
+
|
|
245
|
+
def _skill_path(self, skill_id: str) -> str:
|
|
246
|
+
if not self._valid_segment(skill_id):
|
|
247
|
+
raise SkillNotFoundError(f"Invalid skill ID: {skill_id!r}")
|
|
248
|
+
return f"{self._prefix}/{skill_id}" if self._prefix else skill_id
|
|
249
|
+
|
|
250
|
+
@staticmethod
|
|
251
|
+
def _reject_link(properties: Any) -> None:
|
|
252
|
+
if "reparsepoint" in (properties.file_attributes or "").lower().split("|"):
|
|
253
|
+
raise ResourceNotFoundError("Azure Files reparse points are not supported")
|
|
254
|
+
|
|
255
|
+
@staticmethod
|
|
256
|
+
def _valid_segment(value: str) -> bool:
|
|
257
|
+
return (
|
|
258
|
+
bool(value)
|
|
259
|
+
and value not in {".", ".."}
|
|
260
|
+
and not any(char in value for char in "/\\\x00")
|
|
261
|
+
)
|
|
262
|
+
|
|
263
|
+
@staticmethod
|
|
264
|
+
def _validate_path(path: str) -> str:
|
|
265
|
+
candidate = PurePosixPath(path)
|
|
266
|
+
if (
|
|
267
|
+
not path
|
|
268
|
+
or "\\" in path
|
|
269
|
+
or "\x00" in path
|
|
270
|
+
or candidate.is_absolute()
|
|
271
|
+
or any(part in {"", ".", ".."} for part in path.split("/"))
|
|
272
|
+
):
|
|
273
|
+
raise ResourceNotFoundError(f"Invalid skill file path: {path!r}")
|
|
274
|
+
return candidate.as_posix()
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
# PEP 561 typed package.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
[tool.poetry]
|
|
2
|
+
name = "agentskills-azure"
|
|
3
|
+
version = "0.8.0"
|
|
4
|
+
description = "Azure-backed providers for the Agent Skills format (https://agentskills.io)"
|
|
5
|
+
license = "MIT"
|
|
6
|
+
authors = ["Pratik Panda"]
|
|
7
|
+
readme = "README.md"
|
|
8
|
+
homepage = "https://agentskills.io"
|
|
9
|
+
repository = "https://github.com/pratikxpanda/agentskills-sdk"
|
|
10
|
+
packages = [{include = "agentskills_azure"}]
|
|
11
|
+
classifiers = [
|
|
12
|
+
"Development Status :: 3 - Alpha",
|
|
13
|
+
"Intended Audience :: Developers",
|
|
14
|
+
"Topic :: Software Development :: Libraries",
|
|
15
|
+
"Programming Language :: Python :: 3.12",
|
|
16
|
+
"Programming Language :: Python :: 3.13",
|
|
17
|
+
"Programming Language :: Python :: 3.14",
|
|
18
|
+
]
|
|
19
|
+
|
|
20
|
+
[tool.poetry.dependencies]
|
|
21
|
+
python = ">=3.12,<4.0"
|
|
22
|
+
agentskills-core = ">=0.8.0,<1.0"
|
|
23
|
+
azure-identity = ">=1.19,<2.0"
|
|
24
|
+
azure-storage-blob = {version = ">=12.23,<13.0", extras = ["aio"], optional = true}
|
|
25
|
+
azure-storage-file-share = {version = ">=12.23,<13.0", extras = ["aio"], optional = true}
|
|
26
|
+
|
|
27
|
+
[tool.poetry.extras]
|
|
28
|
+
blob = ["azure-storage-blob"]
|
|
29
|
+
files = ["azure-storage-file-share"]
|
|
30
|
+
|
|
31
|
+
[build-system]
|
|
32
|
+
requires = ["poetry-core"]
|
|
33
|
+
build-backend = "poetry.core.masonry.api"
|