aip-agents-binary 0.0.0__py3-none-any.whl

aip_agents/skills/stager.py

@@ -0,0 +1,224 @@
+"""Skill staging utilities.
+
+This module stages local skill directories into a filesystem backend so skills can be
+discovered and read from backend storage (DeepAgents-compatible flow).
+
+Author:
+    Saul Sayers (saul.sayers@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import json
+import posixpath
+from collections.abc import Iterable, Sequence
+from copy import deepcopy
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+from aip_agents.middleware.backends.protocol import BackendProtocol
+from aip_agents.skills.errors import SkillValidationError
+from aip_agents.skills.models import ResourceEntry, ResourceManifest, ResourceType, Skill
+
+_DEFAULT_SKILLS_BACKEND_ROOT = "/skills"
+_DEFAULT_SKILL_SKIP_DIRS = {
+    ".git",
+    ".hg",
+    ".svn",
+    "__pycache__",
+    ".venv",
+    "node_modules",
+}
+_RESOURCE_INDEX_FILENAME = ".aip-skill-index.json"
+
+
+def _iter_skill_files(skill_root: Path) -> Iterable[Path]:
+    for path in sorted(skill_root.rglob("*")):
+        if path.is_dir():
+            continue
+
+        relative = path.relative_to(skill_root)
+
+        if any(part in _DEFAULT_SKILL_SKIP_DIRS for part in relative.parts):
+            continue
+        if path.name == _RESOURCE_INDEX_FILENAME:
+            continue  # pragma: no cover
+
+        yield path
+
+
+def _is_utf8_text(data: bytes) -> bool:
+    """Return True if data is valid UTF-8."""
+    try:
+        data.decode("utf-8")
+        return True
+    except UnicodeDecodeError:
+        return False
+
+
+def _ensure_posix_root(path: str) -> str:
+    normalized = path.strip()
+    if not normalized:
+        return "/"
+    normalized = "/" + normalized.lstrip("/")
+    return normalized.rstrip("/") or "/"
+
+
+def _classify_resource_type(relative_path: str) -> ResourceType:
+    p = PurePosixPath(relative_path)
+    parts = p.parts
+    if len(parts) <= 1:
+        if p.name.upper() in {"SKILL.MD", "INSTRUCTION.MD", "GUIDE.MD"}:
+            return ResourceType.INSTRUCTION
+        return ResourceType.ASSET
+    parent = parts[0].lower()
+    if parent == "instructions":
+        return ResourceType.INSTRUCTION
+    if parent == "references":
+        return ResourceType.REFERENCE
+    if parent == "examples":
+        return ResourceType.EXAMPLE
+    if parent == "scripts":
+        return ResourceType.SCRIPT
+    return ResourceType.ASSET
+
+
+_MAX_SUMMARY_LENGTH = 200
+
+
+def _extract_summary(content: str) -> str | None:
+    for line in content.splitlines():
+        stripped = line.strip()
+        if stripped:
+            return stripped[:_MAX_SUMMARY_LENGTH]
+    return None
+
+
+@dataclass(frozen=True, slots=True)
+class SkippedSkillFile:
+    """A file that was skipped during staging (e.g., binary or unsupported type)."""
+
+    relative_path: str
+    backend_path: str
+    size_bytes: int
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class StagedSkill:
+    """Result of staging a single skill into the backend filesystem.
+
+    Attributes:
+        name (str): Skill name.
+        backend_root (str): Backend root directory for the staged skill.
+        staged_files (tuple[str, ...]): Backend file paths written.
+        metadata (dict[str, Any]): Raw parsed skill frontmatter.
+        provenance (dict[str, Any]): Source and trust context.
+    """
+
+    name: str
+    backend_root: str
+    staged_files: tuple[str, ...]
+    metadata: dict[str, Any]
+    provenance: dict[str, Any]
+    skipped_files: tuple[SkippedSkillFile, ...] = ()
+
+
+class SkillStager:
+    """Stages local skill directories into a remote filesystem backend."""
+
+    def __init__(self, *, backend: BackendProtocol, destination_root: str = _DEFAULT_SKILLS_BACKEND_ROOT) -> None:
+        """Initialize the stager with a backend protocol and destination root."""
+        self._backend = backend
+        self._destination_root = _ensure_posix_root(destination_root)
+
+    def stage(self, skills: Sequence[Skill]) -> list[StagedSkill]:
+        """Stage multiple skills and return the staged results."""
+        results: list[StagedSkill] = []
+        for skill in skills:
+            results.append(self.stage_one(skill))
+        return results
+
+    def stage_one(self, skill: Skill) -> StagedSkill:
+        """Stage a single skill into the backend and return the result."""
+        if not skill.skill_md_path.is_file():
+            raise SkillValidationError(f"Missing required SKILL.md at: {skill.skill_md_path}.")
+
+        staged_files: list[str] = []
+        resource_entries: list[ResourceEntry] = []
+        backend_root = posixpath.join(self._destination_root, skill.name)
+
+        for local_path in _iter_skill_files(skill.local_root_path):
+            rel = local_path.relative_to(skill.local_root_path).as_posix()
+            backend_path = posixpath.join(backend_root, rel)
+
+            data = local_path.read_bytes()
+            is_binary = not _is_utf8_text(data)
+            resource_type = _classify_resource_type(rel)
+            size_bytes = len(data)
+
+            if is_binary:
+                self._backend.write_bytes(backend_path, data)
+                entry = ResourceEntry(
+                    backend_path=backend_path,
+                    relative_path=rel,
+                    resource_type=resource_type,
+                    size_bytes=size_bytes,
+                    is_binary=True,
+                    summary=None,
+                )
+                resource_entries.append(entry)
+                staged_files.append(backend_path)
+            else:
+                content = data.decode("utf-8")
+                summary = _extract_summary(content)
+                self._backend.write(backend_path, content)
+                entry = ResourceEntry(
+                    backend_path=backend_path,
+                    relative_path=rel,
+                    resource_type=resource_type,
+                    size_bytes=size_bytes,
+                    is_binary=False,
+                    summary=summary,
+                )
+                resource_entries.append(entry)
+                staged_files.append(backend_path)
+
+        resource_entries.sort(key=lambda e: e.relative_path)
+
+        manifest = ResourceManifest(
+            skill_name=skill.name,
+            resources=resource_entries,
+        )
+
+        manifest_path = posixpath.join(backend_root, _RESOURCE_INDEX_FILENAME)
+        manifest_json = json.dumps(
+            {
+                "skill_name": manifest.skill_name,
+                "resources": [
+                    {
+                        "backend_path": e.backend_path,
+                        "relative_path": e.relative_path,
+                        "resource_type": e.resource_type.value,
+                        "size_bytes": e.size_bytes,
+                        "is_binary": e.is_binary,
+                        "summary": e.summary,
+                    }
+                    for e in manifest.resources
+                ],
+            },
+            sort_keys=True,
+            indent=2,
+            ensure_ascii=False,
+        )
+        self._backend.write(manifest_path, manifest_json)
+        staged_files.append(manifest_path)
+
+        return StagedSkill(
+            name=skill.name,
+            backend_root=backend_root,
+            staged_files=tuple(staged_files),
+            metadata=deepcopy(skill.metadata),
+            provenance=deepcopy(skill.provenance),
+        )

aip_agents/skills/validation.py

@@ -0,0 +1,53 @@
+"""Skill validation helpers.
+
+Author:
+    Saul Sayers (saul.sayers@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Final
+
+from aip_agents.skills.errors import SkillValidationError
+
+_SKILL_NAME_RE: Final[re.Pattern[str]] = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
+_SKILL_NAME_MAX_LEN: Final[int] = 64
+
+
+def validate_skill_name(name: str) -> None:
+    """Validate a skill name against DeepAgents naming rules.
+
+    Args:
+        name (str): Skill directory name.
+
+    Returns:
+        None: This function returns None.
+    """
+    if not name or len(name) > _SKILL_NAME_MAX_LEN or _SKILL_NAME_RE.fullmatch(name) is None:
+        raise SkillValidationError(
+            "Invalid skill name. Expected lowercase alphanumerics with single hyphens "
+            f"(max {_SKILL_NAME_MAX_LEN} chars): {name!r}."
+        )
+
+
+def validate_skill_root(skill_root: Path) -> None:
+    """Validate a local skill root directory.
+
+    Args:
+        skill_root (Path): Local path to the skill directory.
+
+    Returns:
+        None: This function returns None.
+    """
+    if not skill_root.exists():
+        raise SkillValidationError(f"Skill path does not exist: {skill_root}.")
+    if not skill_root.is_dir():
+        raise SkillValidationError(f"Skill path is not a directory: {skill_root}.")
+
+    validate_skill_name(skill_root.name)
+
+    skill_md_path = skill_root / "SKILL.md"
+    if not skill_md_path.is_file():
+        raise SkillValidationError(f"Missing required SKILL.md at: {skill_md_path}.")

aip_agents/storage/__init__.py

@@ -0,0 +1,41 @@
+"""Storage module for aip_agents.
+
+This module provides comprehensive storage functionality including object storage
+clients, storage providers for tool outputs, and configuration management.
+
+Authors:
+    Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+# Object storage clients
+from aip_agents.storage.base import BaseObjectStorageClient
+from aip_agents.storage.clients.minio_client import MinioConfig, MinioObjectStorage
+
+# Configuration and factory
+from aip_agents.storage.config import (
+    StorageConfig,
+    StorageProviderFactory,
+    StorageType,
+)
+
+# Storage providers
+from aip_agents.storage.providers.base import BaseStorageProvider, StorageError
+from aip_agents.storage.providers.memory import InMemoryStorageProvider
+from aip_agents.storage.providers.object_storage import ObjectStorageProvider
+
+__all__ = [
+    # Object storage
+    "BaseObjectStorageClient",
+    "MinioConfig",
+    "MinioObjectStorage",
+    # Storage providers
+    "BaseStorageProvider",
+    "StorageError",
+    "InMemoryStorageProvider",
+    "ObjectStorageProvider",
+    # Configuration
+    "StorageConfig",
+    "StorageType",
+    "StorageProviderFactory",
+]

aip_agents/storage/base.py

@@ -0,0 +1,85 @@
+"""Base class for object storage clients.
+
+Authors:
+    Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from abc import ABC, abstractmethod
+from typing import BinaryIO
+
+
+class BaseObjectStorageClient(ABC):
+    """Abstract base class for object storage clients."""
+
+    @abstractmethod
+    def object_exists(self, object_key: str) -> bool:
+        """Check if an object exists in the storage.
+
+        Args:
+            object_key: The key of the object to check.
+
+        Returns:
+            True if the object exists, False otherwise.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def upload(
+        self,
+        object_key: str,
+        file_stream: bytes | BinaryIO,
+        filename: str | None = None,
+        content_type: str | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> str:
+        """Upload data to object storage.
+
+        Args:
+            object_key: The key of the object in the storage
+            file_stream: The binary data to upload
+            filename: The name of the file
+            content_type: The content type of the file
+            metadata: Additional metadata to store with the object
+
+        Returns:
+            The key of the uploaded object
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get(self, object_key: str) -> bytes:
+        """Get data from object storage.
+
+        Args:
+            object_key: The key of the object in the storage
+
+        Returns:
+            The binary data of the object
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete(self, object_key: str) -> None:
+        """Delete data from object storage.
+
+        Args:
+            object_key: The key of the object in the storage
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def generate_presigned_url(
+        self, object_key: str, expires: int = 24, response_headers: dict[str, str] | None = None
+    ) -> str:
+        """Generate a presigned URL for accessing the object.
+
+        Args:
+            object_key: The key of the object in the storage
+            expires: The number of hours the URL is valid for
+            response_headers: Additional headers to include in the response
+
+        Returns:
+            The presigned URL
+        """
+        raise NotImplementedError

aip_agents/storage/clients/__init__.py

@@ -0,0 +1,12 @@
+"""Storage client implementations.
+
+This module contains concrete implementations of object storage clients
+for various backends like MinIO, AWS S3, etc.
+
+Authors:
+    Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+"""
+
+from aip_agents.storage.clients.minio_client import MinioConfig, MinioObjectStorage
+
+__all__ = ["MinioConfig", "MinioObjectStorage"]