agentengine-sdk-python 0.6.2__py3-none-any.whl → 0.6.9__py3-none-any.whl

ksadk/skills/runtime/loader.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import httpx
+
+from ksadk.skills.loader import LocalSkill, load_local_skill
+from ksadk.skills.models import SkillRef
+from ksadk.skills.package_store import PackageStore, SkillPackageError
+from ksadk.skills.runtime import registry
+from ksadk.skills.service_client import SkillServiceClient
+from ksadk.skills.service_env import resolve_skill_service_url
+
+
+@dataclass
+class SkillLoadResult:
+    skills: list[LocalSkill] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+
+def load_skills(
+    *,
+    prompt: str = "",
+    skill_names: list[str] | None = None,
+    service_transport: httpx.BaseTransport | None = None,
+) -> SkillLoadResult:
+    warnings: list[str] = []
+    skills: list[LocalSkill] = []
+    skills.extend(load_local_skills())
+
+    service_url = resolve_skill_service_url(require_spaces=True)
+    if not service_url:
+        return SkillLoadResult(skills=skills, warnings=warnings)
+
+    cache_dir = Path(
+        os.environ.get("KSADK_SKILL_CACHE_DIR")
+        or Path(tempfile.gettempdir()) / "ksadk-skill-cache"
+    )
+    client = SkillServiceClient(
+        base_url=service_url,
+        token=os.environ.get("KSADK_SKILL_SERVICE_TOKEN", ""),
+        transport=service_transport,
+    )
+    store = PackageStore(cache_dir=cache_dir)
+    selected_refs: list[SkillRef] = []
+    seen_names: set[str] = {skill.name.lower() for skill in skills if skill.name}
+    for space_id in registry.user_skill_space_ids():
+        listing = client.list_skills_by_space_id(space_id)
+        selected_refs.extend(
+            registry.dedupe_skill_refs(
+                registry.select_remote_skill_refs(
+                    listing.active_skills(),
+                    prompt,
+                    skill_names=skill_names,
+                ),
+                seen_names=seen_names,
+            )
+        )
+
+    if registry.public_skill_space_ids():
+        listing = client.list_available_premade_skills()
+        selected_refs.extend(
+            registry.dedupe_skill_refs(
+                registry.select_public_skill_refs(listing.active_skills()),
+                seen_names=seen_names,
+            )
+        )
+
+    for skill in selected_refs:
+        package = store.get_cached(skill)
+        if package is None:
+            archive = client.download_skill_archive(skill)
+            try:
+                package = store.store_archive(skill, archive)
+            except SkillPackageError as exc:
+                if not _allow_hash_mismatch():
+                    raise
+                package = _store_unverified_archive(store, skill, archive)
+                warnings.append(str(exc))
+        skills.append(load_local_skill(package.root_dir))
+    return SkillLoadResult(skills=skills, warnings=warnings)
+
+
+def load_local_skills() -> list[LocalSkill]:
+    skills_dir = os.environ.get("KSADK_LOCAL_SKILLS_DIR", "").strip()
+    if not skills_dir:
+        return []
+    root = Path(skills_dir)
+    if not root.exists():
+        return []
+    return [
+        load_local_skill(path)
+        for path in sorted(root.iterdir())
+        if path.is_dir() and (path / "SKILL.md").exists()
+    ]
+
+
+def _allow_hash_mismatch() -> bool:
+    return os.environ.get("KSADK_SKILL_ALLOW_HASH_MISMATCH", "").strip().lower() in {
+        "1",
+        "true",
+        "yes",
+        "on",
+    }
+
+
+def _store_unverified_archive(store: PackageStore, skill: SkillRef, archive: bytes):
+    skill_dir = store.cache_dir / f"unverified-{skill.cache_key or skill.name or 'skill'}"
+    if skill_dir.exists():
+        shutil.rmtree(skill_dir)
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    archive_path = skill_dir / "archive.zip"
+    extract_dir = skill_dir / "extracted"
+    archive_path.write_bytes(archive)
+    extract_dir.mkdir(parents=True, exist_ok=True)
+    store._safe_extract(archive_path, extract_dir)
+    return type(
+        "UnverifiedSkillPackage",
+        (),
+        {
+            "ref": skill,
+            "archive_path": archive_path,
+            "extract_dir": extract_dir,
+            "root_dir": store._find_skill_root(extract_dir),
+            "cache_hit": False,
+        },
+    )()

ksadk/skills/runtime/registry.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import os
+import re
+
+from ksadk.skills.models import SkillRef
+from ksadk.skills.runtime.base import normalize_skill_names
+from ksadk.skills.service_env import (
+    parse_skill_space_ids,
+    public_skill_space_ids as configured_public_skill_space_ids,
+    skill_space_ids as configured_skill_space_ids,
+    user_skill_space_ids as configured_user_skill_space_ids,
+)
+
+
+def skill_space_ids() -> list[str]:
+    return configured_skill_space_ids()
+
+
+def user_skill_space_ids() -> list[str]:
+    return configured_user_skill_space_ids()
+
+
+def public_skill_space_ids() -> list[str]:
+    return configured_public_skill_space_ids()
+
+
+def parse_space_ids(*raw_values: str) -> list[str]:
+    return parse_skill_space_ids(*raw_values)
+
+
+def dedupe_skill_refs(skill_refs: list[SkillRef], *, seen_names: set[str]) -> list[SkillRef]:
+    selected: list[SkillRef] = []
+    seen_keys: set[str] = set()
+    for skill in skill_refs:
+        name_key = skill.name.lower() if skill.name else ""
+        key = skill.cache_key or skill.skill_id or skill.name
+        if not name_key or name_key in seen_names or key in seen_keys:
+            continue
+        seen_names.add(name_key)
+        seen_keys.add(key)
+        selected.append(skill)
+    return selected
+
+
+def select_public_skill_refs(skill_refs: list[SkillRef]) -> list[SkillRef]:
+    allowlist = {name.lower() for name in normalize_skill_names(os.environ.get("KSADK_PUBLIC_SKILL_ALLOWLIST", ""))}
+    if not allowlist:
+        return [skill for skill in skill_refs if skill.name]
+    return [
+        skill
+        for skill in skill_refs
+        if skill.name and skill.name.lower() in allowlist
+    ]
+
+
+def select_remote_skill_refs(
+    skill_refs: list[SkillRef],
+    prompt: str,
+    *,
+    skill_names: list[str] | None = None,
+) -> list[SkillRef]:
+    if not prompt and not normalize_skill_names(skill_names):
+        return []
+    return [match.skill for match in match_skill_refs(skill_refs, prompt, skill_names=skill_names)]
+
+
+class SkillMatch:
+    def __init__(self, skill: SkillRef, score: int, reason: str):
+        self.skill = skill
+        self.score = score
+        self.reason = reason
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "name": self.skill.name,
+            "description": self.skill.description,
+            "version": self.skill.version,
+            "score": self.score,
+            "reason": self.reason,
+            "aliases": list(self.skill.aliases),
+            "tags": list(self.skill.tags),
+        }
+
+
+def match_skill_refs(
+    skill_refs: list[SkillRef],
+    prompt: str,
+    *,
+    skill_names: list[str] | None = None,
+    limit: int | None = None,
+) -> list[SkillMatch]:
+    requested_names = {name.lower() for name in normalize_skill_names(skill_names)}
+    normalized_prompt = prompt.lower()
+    prompt_tokens = _tokens(normalized_prompt)
+    matches: list[SkillMatch] = []
+    seen: set[str] = set()
+    for skill in skill_refs:
+        if not skill.name:
+            continue
+        skill_name = skill.name.lower()
+        if requested_names:
+            if skill_name not in requested_names:
+                continue
+            score, reason = 100, "exact_name"
+        else:
+            score, reason = _metadata_score(skill, normalized_prompt, prompt_tokens)
+            if score <= 0:
+                continue
+        key = skill.cache_key or skill.skill_id or skill.name
+        if key in seen:
+            continue
+        seen.add(key)
+        matches.append(SkillMatch(skill=skill, score=score, reason=reason))
+    matches.sort(key=lambda item: (-item.score, item.skill.name.lower()))
+    if limit is not None:
+        return matches[: max(0, limit)]
+    return matches
+
+
+def _metadata_score(skill: SkillRef, normalized_prompt: str, prompt_tokens: set[str]) -> tuple[int, str]:
+    if skill.name and skill.name.lower() in normalized_prompt:
+        return 90, "name"
+    for alias in skill.aliases:
+        if alias.lower() in normalized_prompt:
+            return 80, "alias"
+    for tag in skill.tags:
+        tag_key = tag.lower()
+        if tag_key and (tag_key in normalized_prompt or tag_key in prompt_tokens):
+            return 65, "tag"
+
+    text = " ".join(
+        [
+            skill.description or "",
+            " ".join(skill.examples),
+        ]
+    ).lower()
+    skill_tokens = _tokens(text)
+    overlap = prompt_tokens & skill_tokens
+    if overlap:
+        return min(55, 20 + len(overlap) * 10), "metadata"
+    return 0, ""
+
+
+def _tokens(value: str) -> set[str]:
+    return {
+        token
+        for token in re.split(r"[^0-9a-zA-Z\u4e00-\u9fff]+", value.lower())
+        if len(token) >= 2
+    }

ksadk/skills/runtime/request.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from ksadk.skills.runtime.base import normalize_skill_names
+
+
+class SkillWorkflowRequestError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class SkillWorkflowRequest:
+    workflow_prompt: str = ""
+    skill_names: list[str] = field(default_factory=list)
+
+
+def parse_workflow_request(argv: list[str]) -> SkillWorkflowRequest:
+    args = list(argv)
+    has_prompt_file = "--prompt-file" in args
+    has_request_file = "--request-file" in args
+    if has_prompt_file and has_request_file:
+        raise SkillWorkflowRequestError("--prompt-file and --request-file cannot be used together")
+
+    if has_request_file:
+        return _request_from_json_file(_option_value(args, "--request-file"))
+    if has_prompt_file:
+        return SkillWorkflowRequest(workflow_prompt=Path(_option_value(args, "--prompt-file")).read_text(encoding="utf-8"))
+    if not args:
+        return SkillWorkflowRequest()
+    return SkillWorkflowRequest(workflow_prompt=args[0])
+
+
+def _option_value(args: list[str], name: str) -> str:
+    try:
+        index = args.index(name)
+        value = args[index + 1]
+    except (ValueError, IndexError) as exc:
+        raise SkillWorkflowRequestError(f"{name} requires a file path") from exc
+    if value.startswith("--"):
+        raise SkillWorkflowRequestError(f"{name} requires a file path")
+    return value
+
+
+def _request_from_json_file(path: str) -> SkillWorkflowRequest:
+    try:
+        payload = json.loads(Path(path).read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise SkillWorkflowRequestError(f"invalid request file JSON: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise SkillWorkflowRequestError("request file must contain a JSON object")
+    prompt = payload.get("workflow_prompt", payload.get("prompt", ""))
+    skill_names = _skill_names_from_payload(payload)
+    return SkillWorkflowRequest(
+        workflow_prompt=str(prompt or ""),
+        skill_names=skill_names,
+    )
+
+
+def _skill_names_from_payload(payload: dict[str, Any]) -> list[str]:
+    for key in ("skill_names", "selected_skills"):
+        if key in payload:
+            return normalize_skill_names(payload.get(key))
+    return []

ksadk/skills/service_client.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from typing import Any
+from urllib.parse import quote, urlsplit, urlunsplit
+
+import httpx
+import requests
+
+from ksadk.common.auth import AWSV4Auth
+
+from ksadk.skills.models import SkillListResponse, SkillRef
+
+
+class SkillServiceClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        token: str = "",
+        access_key: str = "",
+        secret_key: str = "",
+        account_id: str = "",
+        region: str = "",
+        api_version: str = "",
+        sign_service: str = "",
+        extra_headers: Mapping[str, str] | None = None,
+        timeout: float = 60.0,
+        transport: httpx.BaseTransport | None = None,
+    ):
+        self.base_url = _normalize_base_url(base_url)
+        self.token = token
+        self.access_key = access_key or _env("KSADK_SKILL_SERVICE_ACCESS_KEY", "KSYUN_ACCESS_KEY", "KS3_ACCESS_KEY")
+        self.secret_key = secret_key or _env("KSADK_SKILL_SERVICE_SECRET_KEY", "KSYUN_SECRET_KEY", "KS3_SECRET_KEY")
+        self.account_id = account_id or _env("KSADK_SKILL_SERVICE_ACCOUNT_ID", "KSYUN_ACCOUNT_ID")
+        self.logical_region = region or _env("KSADK_SKILL_SERVICE_REGION", "KSYUN_REGION") or "cn-beijing-6"
+        self.region = _normalize_control_region(self.logical_region)
+        self.custom_source = _resolve_custom_source(self.logical_region)
+        self.api_version = api_version or os.environ.get("KSADK_SKILL_SERVICE_API_VERSION", "2024-06-12")
+        self.sign_service = sign_service or os.environ.get("KSADK_SKILL_SERVICE_SIGN_SERVICE", "aicp")
+        self.extra_headers = dict(extra_headers or {})
+        self.timeout = timeout
+        self.transport = transport
+        self._requests_session: requests.Session | None = None
+        self._auth = AWSV4Auth(
+            access_key_id=self.access_key,
+            secret_access_key=self.secret_key,
+            region=self.region,
+            service=self.sign_service,
+        )
+
+    def action_url(self, action: str) -> str:
+        if self._is_kop_mode():
+            return (
+                f"{self._kop_base_url()}/?Action={quote(action.lstrip('/'))}"
+                f"&Version={quote(self.api_version)}"
+            )
+        return f"{self.base_url}/{action.lstrip('/')}"
+
+    def list_skill_spaces(self, *, page_number: int = 1, page_size: int = 100) -> dict[str, Any]:
+        return self._get_json(
+            "ListSkillSpaces",
+            {"PageNumber": page_number, "PageSize": page_size},
+        )
+
+    def list_skills_by_space_id(self, space_id: str) -> SkillListResponse:
+        if self._is_kop_mode():
+            payload = self._get_json(
+                "ListSkillsBySpaceId",
+                {"SpaceId": space_id, "PageNumber": 1, "PageSize": 100},
+            )
+        else:
+            payload = self._get_json("ListSkillsBySpaceId", {"SpaceId": space_id})
+        return SkillListResponse.from_payload(payload, space_id=space_id)
+
+    def list_available_premade_skills(self) -> SkillListResponse:
+        payload = self._get_json("ListAvailablePremadeSkills", {})
+        return SkillListResponse.from_payload(payload, space_id="public", space_name="Public Skills")
+
+    def get_skill_download_url(self, skill: SkillRef) -> str:
+        action = "GetSkillDownloadUrl" if skill.version_id else "GetPremadeSkillDownloadUrl"
+        payload = self._get_json(
+            action,
+            {
+                "SkillId": skill.skill_id,
+                "VersionId": skill.version_id,
+            },
+        )
+        data = payload.get("Data") or payload.get("data") or {}
+        return str(data.get("DownloadUrl") or data.get("download_url") or "")
+
+    def download_skill_archive(self, skill: SkillRef) -> bytes:
+        download_url = self.get_skill_download_url(skill)
+        if not download_url:
+            raise ValueError(f"Skill Service did not return DownloadUrl for {skill.skill_id}")
+        with httpx.Client(**self._client_kwargs()) as client:
+            response = client.get(download_url)
+            response.raise_for_status()
+            return response.content
+
+    def _get_json(self, action: str, params: dict[str, Any]) -> dict[str, Any]:
+        if self._is_kop_mode():
+            return self._get_json_kop(action, params)
+        with httpx.Client(**self._client_kwargs()) as client:
+            response = client.get(self.action_url(action), params=params, headers=self._headers())
+            response.raise_for_status()
+            return self._decode_response(action, response)
+
+    def _post_json(self, action: str, payload: dict[str, Any]) -> dict[str, Any]:
+        with httpx.Client(**self._client_kwargs()) as client:
+            response = client.post(self.action_url(action), json=payload, headers=self._headers())
+            response.raise_for_status()
+            return self._decode_response(action, response)
+
+    def _decode_response(self, action: str, response: httpx.Response) -> dict[str, Any]:
+        data = response.json()
+        if not isinstance(data, dict):
+            raise ValueError(f"Skill Service returned non-object response for {action}")
+        code = data.get("Code", data.get("code"))
+        if code not in (None, 0, 200, "0", "200"):
+            request_id = str(data.get("RequestId") or data.get("request_id") or "")
+            message = str(data.get("Message") or data.get("message") or "")
+            raise ValueError(
+                f"Skill Service {action} failed: code={code}, "
+                f"request_id={request_id}, message={message}"
+            )
+        return data
+
+    def _client_kwargs(self) -> dict[str, Any]:
+        kwargs: dict[str, Any] = {"timeout": self.timeout}
+        if self.transport is not None:
+            kwargs["transport"] = self.transport
+        return kwargs
+
+    def _headers(self, *, action: str = "") -> dict[str, str]:
+        headers = {"Accept": "application/json", "Content-Type": "application/json"}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        if self.account_id:
+            headers["X-Ksc-Account-Id"] = self.account_id
+        if self._is_kop_mode():
+            headers.update(
+                {
+                    "Host": urlsplit(self._kop_base_url()).netloc,
+                    "X-Ksc-Region": self.region,
+                    "X-Ksc-Source": "ksadk-skill-runtime",
+                }
+            )
+            if self.custom_source:
+                headers["X-KSC-CUSTOM-SOURCE"] = self.custom_source
+            if action:
+                headers["X-Action"] = action
+                headers["X-Version"] = self.api_version
+        headers.update(self.extra_headers)
+        return headers
+
+    def _get_json_kop(self, action: str, params: dict[str, Any]) -> dict[str, Any]:
+        query = {"Action": action, "Version": self.api_version, **params}
+        headers = self._headers(action=action)
+        if self.transport is not None:
+            with httpx.Client(**self._client_kwargs()) as client:
+                response = client.get(self._kop_base_url() + "/", params=query, headers=headers)
+                response.raise_for_status()
+                return self._decode_response(action, response)
+        if not self._auth.is_enabled:
+            raise ValueError(
+                "AICP Skill Service endpoint requires signing credentials. "
+                "Set KSADK_SKILL_SERVICE_ACCESS_KEY/KSADK_SKILL_SERVICE_SECRET_KEY "
+                "or KSYUN_ACCESS_KEY/KSYUN_SECRET_KEY."
+            )
+        response = self._requests().get(
+            self._kop_base_url() + "/",
+            params=query,
+            headers=headers,
+            auth=self._auth.get_auth(),
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+        data = response.json()
+        if not isinstance(data, dict):
+            raise ValueError(f"Skill Service returned non-object response for {action}")
+        code = data.get("Code", data.get("code"))
+        if code not in (None, 0, 200, "0", "200"):
+            request_id = str(data.get("RequestId") or data.get("request_id") or "")
+            message = str(data.get("Message") or data.get("message") or data.get("Error") or "")
+            raise ValueError(
+                f"Skill Service {action} failed: code={code}, "
+                f"request_id={request_id}, message={message}"
+            )
+        return data
+
+    def _requests(self) -> requests.Session:
+        if self._requests_session is None:
+            self._requests_session = requests.Session()
+        return self._requests_session
+
+    def _is_kop_mode(self) -> bool:
+        host = urlsplit(self.base_url).netloc.lower()
+        return (
+            host.endswith("aicp.inner.api.ksyun.com")
+            or host.endswith("aicp.internal.api.ksyun.com")
+            or host.endswith("aicp.api.ksyun.com")
+        )
+
+    def _kop_base_url(self) -> str:
+        parsed = urlsplit(self.base_url)
+        return urlunsplit((parsed.scheme, parsed.netloc, "", "", "")).rstrip("/")
+
+
+def _env(*names: str) -> str:
+    for name in names:
+        value = os.environ.get(name, "").strip()
+        if value:
+            return value
+    return ""
+
+
+def _normalize_control_region(region: str) -> str:
+    region = (region or "cn-beijing-6").strip()
+    if region.lower() == "pre-online":
+        return os.environ.get("AGENTENGINE_PRE_CONTROL_REGION", "cn-beijing-6")
+    return region
+
+
+def _resolve_custom_source(region: str) -> str:
+    if (region or "").strip().lower() == "pre-online":
+        return os.environ.get("AGENTENGINE_PRE_CUSTOM_SOURCE", "pre")
+    return ""
+
+
+def _normalize_base_url(base_url: str) -> str:
+    parsed = urlsplit(base_url.strip())
+    path = parsed.path.rstrip("/")
+    if path.endswith("/openapi.json"):
+        path = path[: -len("/openapi.json")]
+    elif path.endswith("/docs"):
+        path = path[: -len("/docs")] + "/api/v1"
+    return urlunsplit((parsed.scheme, parsed.netloc, path, "", "")).rstrip("/")

ksadk/skills/service_env.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import os
+
+from ksadk.common.aicp_env import resolve_aicp_connection
+
+
+def parse_skill_space_ids(*raw_values: str) -> list[str]:
+    spaces: list[str] = []
+    seen: set[str] = set()
+    for raw in raw_values:
+        for part in raw.split(","):
+            space_id = part.strip()
+            if not space_id or space_id in seen:
+                continue
+            seen.add(space_id)
+            spaces.append(space_id)
+    return spaces
+
+
+def user_skill_space_ids() -> list[str]:
+    return parse_skill_space_ids(
+        os.environ.get("KSADK_SKILL_SPACE_IDS") or os.environ.get("SKILL_SPACE_ID") or ""
+    )
+
+
+def public_skill_space_ids() -> list[str]:
+    return parse_skill_space_ids(os.environ.get("KSADK_PUBLIC_SKILL_SPACE_IDS") or "")
+
+
+def skill_space_ids() -> list[str]:
+    return parse_skill_space_ids(
+        os.environ.get("KSADK_SKILL_SPACE_IDS") or os.environ.get("SKILL_SPACE_ID") or "",
+        os.environ.get("KSADK_PUBLIC_SKILL_SPACE_IDS") or "",
+    )
+
+
+def resolve_skill_service_url(*, require_spaces: bool = True) -> str:
+    explicit = os.environ.get("KSADK_SKILL_SERVICE_URL", "").strip()
+    if explicit:
+        return explicit
+    if require_spaces and not skill_space_ids():
+        return ""
+
+    connection = resolve_aicp_connection("KSADK_SKILL_SERVICE")
+    return f"{connection['scheme']}://{connection['endpoint']}".rstrip("/")
+
+
+def should_resolve_child_skill_service_url() -> bool:
+    if os.environ.get("KSADK_SKILL_SERVICE_URL", "").strip():
+        return True
+    if os.environ.get("KSADK_SKILL_SERVICE_ENDPOINT", "").strip():
+        return True
+    if os.environ.get("KSADK_SKILL_SERVICE_SCHEME", "").strip():
+        return True
+
+    mode = os.environ.get("KSADK_AICP_ENDPOINT_MODE", "").strip().lower()
+    return mode not in {"", "auto", "detect"}