skillplus 0.1.0__tar.gz

skillplus-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Backend
+backend/.venv/
+backend/.env
+backend/__pycache__/
+backend/**/__pycache__/
+backend/.pytest_cache/
+backend/.ruff_cache/
+*.pyc
+
+# Frontend
+frontend/node_modules/
+frontend/.next/
+frontend/out/
+
+# Admin
+skillplus-admin/node_modules/
+skillplus-admin/.next/
+skillplus-admin/.env
+
+# SDK
+sdk/node_modules/
+sdk/dist/
+python-sdk/dist/
+python-sdk/.pytest_cache/
+python-sdk/**/__pycache__/
+
+# OS
+.DS_Store
+skills
+agent-browser/
+
+# Sensitive files (contain server passwords)
+Full_Scan_Version_Management.md
+skillplus_project_summary.md
+.claude/skillplus-rules.md
+Optimizing SkillPlus Database Performance.md
+
+# Credential vault — plaintext secrets, NEVER commit/push. Local only.
+*.local.md
+docs/prod/CREDENTIALS.local.md

skillplus-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SkillPlus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skillplus-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: skillplus
+Version: 0.1.0
+Summary: Official Python SDK for SkillPlus
+Project-URL: Homepage, https://skillplus.xyz
+Project-URL: Documentation, https://docs.skillplus.xyz
+Author: SkillPlus
+License: MIT
+License-File: LICENSE
+Keywords: ai,sdk,security,skillplus
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.28
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SkillPlus Python SDK
+
+Official Python SDK for the hosted SkillPlus API.
+
+SkillPlus provides security intelligence for AI skills and agent-facing software, helping developers, teams, and platforms scan, understand, and trust AI skills before installation, approval, or integration.
+
+## Install
+
+```bash
+pip install skillplus
+```
+
+## Basic usage
+
+```python
+from skillplus import SkillPlus
+
+client = SkillPlus(api_key="skp_...")
+
+result = client.query("https://github.com/owner/repo")
+
+if result.status == "found" and result.report:
+    print(result.report.rating)  # "safe" | "medium" | "high"
+```
+
+### Advanced options
+
+For repositories containing many skills, or to queue a scan automatically when
+no report exists yet:
+
+```python
+result = client.query(
+    "https://github.com/owner/repo",
+    skill_path="skills/example",   # pick one skill in a multi-skill repo
+    scan_if_missing=True,          # queue a scan if no report exists
+)
+```
+
+The SDK talks to the official SkillPlus service at `https://skillplus.xyz`.
+
+## Context manager
+
+```python
+from skillplus import SkillPlus
+
+with SkillPlus(api_key="skp_...") as client:
+    result = client.scan(
+        "https://github.com/owner/repo",
+        skill_path="skills/example",
+    )
+    print(result.status)
+```
+
+## Methods
+
+| Method | Use case |
+|---|---|
+| `query(...)` | Check whether SkillPlus already has a report for a skill. |
+| `scan(...)` | Request a scan when a report is missing or when a fresh check is needed. |
+| `get_report(scan_id)` | Retrieve structured report data for dashboards, registries, or automation. |
+| `get_badge(scan_id)` | Fetch the badge SVG for embedding. |
+| `get_badge_url(scan_id)` | Generate a badge URL for READMEs, marketplaces, or internal portals. |
+
+## Error handling
+
+```python
+from skillplus import SkillPlus, SkillPlusError
+
+client = SkillPlus(api_key="skp_...")
+
+try:
+    result = client.query("https://github.com/owner/repo")
+except SkillPlusError as error:
+    print(error.status_code)
+    print(error.message)
+```
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run python -m build
+```

skillplus-0.1.0/README.md

@@ -0,0 +1,84 @@
+# SkillPlus Python SDK
+
+Official Python SDK for the hosted SkillPlus API.
+
+SkillPlus provides security intelligence for AI skills and agent-facing software, helping developers, teams, and platforms scan, understand, and trust AI skills before installation, approval, or integration.
+
+## Install
+
+```bash
+pip install skillplus
+```
+
+## Basic usage
+
+```python
+from skillplus import SkillPlus
+
+client = SkillPlus(api_key="skp_...")
+
+result = client.query("https://github.com/owner/repo")
+
+if result.status == "found" and result.report:
+    print(result.report.rating)  # "safe" | "medium" | "high"
+```
+
+### Advanced options
+
+For repositories containing many skills, or to queue a scan automatically when
+no report exists yet:
+
+```python
+result = client.query(
+    "https://github.com/owner/repo",
+    skill_path="skills/example",   # pick one skill in a multi-skill repo
+    scan_if_missing=True,          # queue a scan if no report exists
+)
+```
+
+The SDK talks to the official SkillPlus service at `https://skillplus.xyz`.
+
+## Context manager
+
+```python
+from skillplus import SkillPlus
+
+with SkillPlus(api_key="skp_...") as client:
+    result = client.scan(
+        "https://github.com/owner/repo",
+        skill_path="skills/example",
+    )
+    print(result.status)
+```
+
+## Methods
+
+| Method | Use case |
+|---|---|
+| `query(...)` | Check whether SkillPlus already has a report for a skill. |
+| `scan(...)` | Request a scan when a report is missing or when a fresh check is needed. |
+| `get_report(scan_id)` | Retrieve structured report data for dashboards, registries, or automation. |
+| `get_badge(scan_id)` | Fetch the badge SVG for embedding. |
+| `get_badge_url(scan_id)` | Generate a badge URL for READMEs, marketplaces, or internal portals. |
+
+## Error handling
+
+```python
+from skillplus import SkillPlus, SkillPlusError
+
+client = SkillPlus(api_key="skp_...")
+
+try:
+    result = client.query("https://github.com/owner/repo")
+except SkillPlusError as error:
+    print(error.status_code)
+    print(error.message)
+```
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run python -m build
+```

skillplus-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "skillplus"
+version = "0.1.0"
+description = "Official Python SDK for SkillPlus"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "SkillPlus" }]
+keywords = ["skillplus", "ai", "security", "sdk"]
+dependencies = ["httpx>=0.28"]
+
+[project.urls]
+Homepage = "https://skillplus.xyz"
+Documentation = "https://docs.skillplus.xyz"
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.2",
+    "pytest>=8",
+    "respx>=0.22",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/skillplus"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/skillplus", "tests", "README.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

skillplus-0.1.0/src/skillplus/__init__.py

@@ -0,0 +1,49 @@
+from .client import SkillPlus
+from .errors import SkillPlusError
+from .types import (
+    AgentRun,
+    AiCategoryResult,
+    AiFalsePositive,
+    AiReport,
+    AiReportStatus,
+    IssueCategory,
+    PlatformListing,
+    QueryResult,
+    QueryStatus,
+    Rating,
+    ScanIssue,
+    ScanReport,
+    ScanResult,
+    ScanStatus,
+    ScanSummary,
+    Severity,
+    SeverityNormalized,
+    SupplyChainHit,
+    SupplyChainReport,
+    Verdict,
+)
+
+__all__ = [
+    "AgentRun",
+    "AiCategoryResult",
+    "AiFalsePositive",
+    "AiReport",
+    "AiReportStatus",
+    "IssueCategory",
+    "PlatformListing",
+    "QueryResult",
+    "QueryStatus",
+    "Rating",
+    "ScanIssue",
+    "ScanReport",
+    "ScanResult",
+    "ScanStatus",
+    "ScanSummary",
+    "Severity",
+    "SeverityNormalized",
+    "SupplyChainHit",
+    "SupplyChainReport",
+    "SkillPlus",
+    "SkillPlusError",
+    "Verdict",
+]

skillplus-0.1.0/src/skillplus/client.py

@@ -0,0 +1,378 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+
+from .errors import SkillPlusError
+from .types import (
+    AgentRun,
+    AiCategoryResult,
+    AiFalsePositive,
+    AiReport,
+    PlatformListing,
+    QueryResult,
+    ScanIssue,
+    ScanReport,
+    ScanResult,
+    ScanSummary,
+    SupplyChainHit,
+    SupplyChainReport,
+)
+
+DEFAULT_BASE_URL = "https://skillplus.xyz"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+_RETRY_STATUSES = frozenset({429, 502, 503})
+
+
+class SkillPlus:
+    """Client for the hosted SkillPlus API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max(0, max_retries)
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            timeout=timeout,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": "skillplus-python/0.1.0",
+            },
+        )
+
+    def __enter__(self) -> SkillPlus:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+
+        self._client.close()
+
+    def query(
+        self,
+        repo_url: str,
+        *,
+        skill_path: str | None = None,
+        scan_if_missing: bool = False,
+        preferred_provider: str | None = None,
+    ) -> QueryResult:
+        """Query an existing report, optionally queueing a scan if no report exists."""
+
+        payload = self._request_json(
+            "POST",
+            "/api/sdk/query",
+            json={
+                "repo_url": repo_url,
+                "skill_path": skill_path,
+                "scan_if_missing": scan_if_missing,
+                "preferred_provider": preferred_provider,
+            },
+        )
+        return _parse_query_result(payload)
+
+    def scan(
+        self,
+        repo_url: str,
+        *,
+        skill_path: str | None = None,
+        preferred_provider: str | None = None,
+        force: bool = False,
+    ) -> ScanResult:
+        """Request a scan for a skill."""
+
+        payload = self._request_json(
+            "POST",
+            "/api/sdk/scan",
+            json={
+                "repo_url": repo_url,
+                "skill_path": skill_path,
+                "preferred_provider": preferred_provider,
+                "force": force,
+            },
+        )
+        return _parse_scan_result(payload)
+
+    def wait_for_report(
+        self,
+        repo_url: str,
+        *,
+        skill_path: str | None = None,
+        preferred_provider: str | None = None,
+        interval: float = 5.0,
+        timeout: float = 600.0,
+    ) -> ScanReport:
+        """Query-and-wait: poll until a completed report exists (scanning if
+        missing). This is the reliable path after a ``queued`` result, which
+        may carry no scan_id to poll."""
+
+        deadline = time.monotonic() + timeout
+        while True:
+            result = self.query(
+                repo_url,
+                skill_path=skill_path,
+                scan_if_missing=True,
+                preferred_provider=preferred_provider,
+            )
+            if result.status == "found" and result.report and result.report.status == "completed":
+                return result.report
+            if result.status in ("failed", "not_found"):
+                raise SkillPlusError(f"Scan {result.status}: {result.message}", detail=result.status)
+            if time.monotonic() + interval > deadline:
+                raise SkillPlusError(
+                    f"Timed out waiting for report (last status: {result.status})",
+                    detail=result.status,
+                )
+            time.sleep(interval)
+
+    def get_report(self, scan_id: str) -> ScanReport:
+        """Retrieve structured report data by scan ID."""
+
+        payload = self._request_json("GET", f"/api/report/{scan_id}")
+        return _parse_report(payload)
+
+    def get_badge(self, scan_id: str) -> str:
+        """Fetch the badge SVG for a report."""
+
+        return self._request_text("GET", f"/api/report/{scan_id}/badge.svg")
+
+    def get_badge_url(self, scan_id: str) -> str:
+        """Return the public badge URL for a report."""
+
+        return f"{self._base_url}/api/report/{scan_id}/badge.svg"
+
+    def _request_json(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        response = self._request(method, path, **kwargs)
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise SkillPlusError("SkillPlus returned invalid JSON", status_code=response.status_code) from exc
+
+        if not isinstance(payload, dict):
+            raise SkillPlusError(
+                "SkillPlus returned an unexpected response",
+                status_code=response.status_code,
+                detail=payload,
+            )
+        return payload
+
+    def _request_text(self, method: str, path: str, **kwargs: Any) -> str:
+        return self._request(method, path, **kwargs).text
+
+    @staticmethod
+    def _retry_delay(response: httpx.Response | None, attempt: int) -> float:
+        if response is not None:
+            retry_after = response.headers.get("Retry-After")
+            if retry_after:
+                try:
+                    return min(max(float(retry_after), 0.0), 60.0)
+                except ValueError:
+                    pass
+        return min(2.0**attempt, 10.0)
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        response: httpx.Response | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._client.request(method, path, **kwargs)
+            except httpx.RequestError as exc:
+                if attempt < self._max_retries:
+                    time.sleep(self._retry_delay(None, attempt))
+                    continue
+                raise SkillPlusError(str(exc), detail=exc) from exc
+            if response.status_code in _RETRY_STATUSES and attempt < self._max_retries:
+                time.sleep(self._retry_delay(response, attempt))
+                continue
+            break
+        assert response is not None
+
+        if response.is_error:
+            detail: object | None = None
+            message = response.reason_phrase
+            try:
+                detail = response.json()
+                if isinstance(detail, dict):
+                    message = str(detail.get("detail") or detail.get("message") or message)
+            except ValueError:
+                detail = response.text or None
+                if response.text:
+                    message = response.text
+
+            raise SkillPlusError(message, status_code=response.status_code, detail=detail)
+
+        return response
+
+
+def _parse_query_result(payload: dict[str, Any]) -> QueryResult:
+    return QueryResult(
+        status=payload["status"],
+        message=payload["message"],
+        scan_id=payload.get("scan_id"),
+        poll_url=payload.get("poll_url"),
+        report=_parse_report(payload["report"]) if payload.get("report") else None,
+    )
+
+
+def _parse_scan_result(payload: dict[str, Any]) -> ScanResult:
+    return ScanResult(
+        status=payload["status"],
+        message=payload["message"],
+        scan_id=payload.get("scan_id"),
+        poll_url=payload.get("poll_url"),
+        report=_parse_report(payload["report"]) if payload.get("report") else None,
+    )
+
+
+def _parse_report(payload: dict[str, Any]) -> ScanReport:
+    return ScanReport(
+        scan_id=payload["scan_id"],
+        skill_name=payload["skill_name"],
+        source=payload["source"],
+        skill_path=payload["skill_path"],
+        tree_sha=payload["tree_sha"],
+        rule_version=payload["rule_version"],
+        valid_skill=payload["valid_skill"],
+        rating=payload["rating"],
+        verdict=payload.get("verdict")
+        or {"low": "safe", "critical": "high"}.get(payload["rating"], payload["rating"]),
+        scanned_at=payload["scanned_at"],
+        cached=payload["cached"],
+        scan_duration_ms=payload["scan_duration_ms"],
+        summary=_parse_summary(payload["summary"]),
+        issues=[_parse_issue(issue) for issue in payload.get("issues", [])],
+        report_url=payload["report_url"],
+        badge_url=payload["badge_url"],
+        blacklisted=bool(payload.get("blacklisted")),
+        whitelisted=bool(payload.get("whitelisted")),
+        status=payload["status"],
+        ai_report=_parse_ai_report(payload["ai_report"]) if payload.get("ai_report") else None,
+        external_links=payload.get("external_links") or {},
+        platform_listings=[
+            PlatformListing(
+                platform=listing["platform"],
+                url=listing["url"],
+                installs=listing["installs"],
+            )
+            for listing in payload.get("platform_listings", [])
+        ],
+        supply_chain=_parse_supply_chain(payload.get("supply_chain")),
+    )
+
+
+def _parse_supply_chain(payload: dict[str, Any] | None) -> SupplyChainReport | None:
+    if not payload:
+        return None
+    return SupplyChainReport(
+        dependency_count=payload.get("dependency_count") or 0,
+        endpoint_count=payload.get("endpoint_count") or 0,
+        blacklist_hits=[
+            SupplyChainHit(
+                kind=hit["kind"],
+                ecosystem=hit.get("ecosystem"),
+                name=hit["name"],
+                version_spec=hit.get("version_spec") or {},
+                reason=hit["reason"],
+                severity=hit["severity"],
+                reference_url=hit.get("reference_url"),
+                match_strength=hit["match_strength"],
+                matched_version=hit.get("matched_version"),
+            )
+            for hit in payload.get("blacklist_hits", [])
+        ],
+    )
+
+
+def _parse_summary(payload: dict[str, Any]) -> ScanSummary:
+    return ScanSummary(
+        total_issues=payload["total_issues"],
+        danger=payload["danger"],
+        warning=payload["warning"],
+        info=payload["info"],
+        files_scanned=payload["files_scanned"],
+        by_category=payload.get("by_category") or {},
+    )
+
+
+def _parse_issue(payload: dict[str, Any]) -> ScanIssue:
+    return ScanIssue(
+        rule_id=payload["rule_id"],
+        severity=payload["severity"],
+        severity_normalized=payload.get("severity_normalized")
+        or {"danger": "high", "warning": "medium", "info": "low"}.get(
+            payload["severity"], payload["severity"]
+        ),
+        category=payload["category"],
+        message=payload["message"],
+        file=payload.get("file"),
+        line=payload.get("line"),
+        snippet=payload.get("snippet"),
+        domain=payload.get("domain"),
+    )
+
+
+def _parse_ai_report(payload: dict[str, Any]) -> AiReport:
+    return AiReport(
+        status=payload["status"],
+        risk_level=payload.get("risk_level"),
+        refined_rating=payload.get("refined_rating"),
+        false_positives=[
+            AiFalsePositive(
+                rule_id=false_positive["rule_id"],
+                file=false_positive["file"],
+                reason=false_positive["reason"],
+            )
+            for false_positive in payload.get("false_positives", [])
+        ],
+        analysis=[_parse_ai_category(item) for item in payload.get("analysis", [])],
+        summary=payload.get("summary"),
+        categories_checked=[
+            _parse_ai_category(item) for item in payload.get("categories_checked", [])
+        ],
+        tokens_used=payload.get("tokens_used"),
+        duration_ms=payload.get("duration_ms"),
+        error_message=payload.get("error_message"),
+        agents=(
+            [
+                AgentRun(
+                    agent=run["agent"],
+                    status=run["status"],
+                    findings=run.get("findings") or [],
+                    summary=run.get("summary"),
+                    tokens_used=run.get("tokens_used"),
+                    duration_ms=run.get("duration_ms"),
+                    error_message=run.get("error_message"),
+                )
+                for run in payload["agents"]
+            ]
+            if payload.get("agents") is not None
+            else None
+        ),
+    )
+
+
+def _parse_ai_category(payload: dict[str, Any]) -> AiCategoryResult:
+    return AiCategoryResult(
+        category=payload["category"],
+        status=payload["status"],
+        severity=payload["severity"],
+        title=payload["title"],
+        description=payload["description"],
+        evidence=payload.get("evidence") or [],
+        confidence=payload.get("confidence") or 0.0,
+    )

skillplus-0.1.0/src/skillplus/errors.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+
+class SkillPlusError(Exception):
+    """Error raised by the SkillPlus SDK."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        detail: object | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.detail = detail

skillplus-0.1.0/src/skillplus/types.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal, TypeAlias
+
+Rating: TypeAlias = Literal["safe", "low", "medium", "high", "unknown"]
+# Rating system v3: three-tier verdict (low→safe, critical→high). Prefer over Rating.
+Verdict: TypeAlias = Literal["safe", "medium", "high", "unknown"]
+# Raw rule-issue severity. v3 scans emit high/medium/low; reports scanned
+# before v3 may still carry danger/warning/info. Prefer SeverityNormalized.
+Severity: TypeAlias = Literal[
+    "high", "medium", "low", "critical", "danger", "warning", "info", "safe"
+]
+# Rating system v3: unified finding severity. Prefer over Severity.
+SeverityNormalized: TypeAlias = Literal["high", "medium", "low", "safe"]
+IssueCategory: TypeAlias = Literal[
+    "url",
+    "code",
+    "prompt",
+    "structure",
+    "persistence",
+    "credential",
+    "supply_chain",
+    "propagation",
+]
+QueryStatus: TypeAlias = Literal["found", "queued", "running", "not_found", "failed"]
+ScanStatus: TypeAlias = Literal["found", "queued", "running", "failed"]
+AiReportStatus: TypeAlias = Literal["pending", "processing", "completed", "failed"]
+
+
+@dataclass(slots=True)
+class ScanIssue:
+    rule_id: str
+    severity: Severity  # deprecated: prefer severity_normalized
+    severity_normalized: SeverityNormalized
+    category: IssueCategory
+    message: str
+    file: str | None = None
+    line: int | None = None
+    snippet: str | None = None
+    domain: str | None = None
+
+
+@dataclass(slots=True)
+class ScanSummary:
+    total_issues: int
+    danger: int
+    warning: int
+    info: int
+    files_scanned: int
+    by_category: dict[str, int] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class AiFalsePositive:
+    rule_id: str
+    file: str
+    reason: str
+
+
+@dataclass(slots=True)
+class AiCategoryResult:
+    category: str
+    status: str
+    severity: str
+    title: str
+    description: str
+    evidence: list[str] = field(default_factory=list)
+    confidence: float = 0.0
+
+
+@dataclass(slots=True)
+class AgentRun:
+    """One agent's run in the v2 multi-agent pipeline (present on get_report)."""
+
+    agent: str
+    status: str
+    findings: list[dict] = field(default_factory=list)
+    summary: str | None = None
+    tokens_used: int | None = None
+    duration_ms: int | None = None
+    error_message: str | None = None
+
+
+@dataclass(slots=True)
+class AiReport:
+    status: AiReportStatus
+    risk_level: str | None
+    refined_rating: Rating | None
+    false_positives: list[AiFalsePositive] = field(default_factory=list)
+    analysis: list[AiCategoryResult] = field(default_factory=list)
+    summary: str | None = None
+    categories_checked: list[AiCategoryResult] = field(default_factory=list)
+    tokens_used: int | None = None
+    duration_ms: int | None = None
+    error_message: str | None = None
+    # Per-agent detail (multi-agent pipeline); None when not exposed.
+    agents: list[AgentRun] | None = None
+
+
+@dataclass(slots=True)
+class SupplyChainHit:
+    """One supply-chain blacklist hit (a dependency/domain known to be poisoned)."""
+
+    kind: str
+    ecosystem: str | None
+    name: str
+    version_spec: dict
+    reason: str
+    severity: str
+    reference_url: str | None
+    match_strength: str
+    matched_version: str | None = None
+
+
+@dataclass(slots=True)
+class SupplyChainReport:
+    """Supply-chain section of a report. Any blacklist hit floors the verdict
+    to high unless the skill is admin-whitelisted."""
+
+    dependency_count: int = 0
+    endpoint_count: int = 0
+    blacklist_hits: list[SupplyChainHit] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class PlatformListing:
+    platform: str
+    url: str
+    installs: int
+
+
+@dataclass(slots=True)
+class ScanReport:
+    scan_id: str
+    skill_name: str
+    source: str
+    skill_path: str
+    tree_sha: str
+    rule_version: str
+    valid_skill: bool
+    rating: Rating  # deprecated: prefer verdict
+    verdict: Verdict
+    scanned_at: str
+    cached: bool
+    scan_duration_ms: int
+    summary: ScanSummary
+    issues: list[ScanIssue]
+    report_url: str
+    badge_url: str
+    blacklisted: bool
+    whitelisted: bool
+    status: str
+    ai_report: AiReport | None = None
+    external_links: dict[str, str] = field(default_factory=dict)
+    platform_listings: list[PlatformListing] = field(default_factory=list)
+    # Supply-chain snapshot; None when the section is unavailable.
+    supply_chain: SupplyChainReport | None = None
+
+
+@dataclass(slots=True)
+class QueryResult:
+    status: QueryStatus
+    message: str
+    scan_id: str | None = None
+    poll_url: str | None = None
+    report: ScanReport | None = None
+
+
+@dataclass(slots=True)
+class ScanResult:
+    status: ScanStatus
+    message: str
+    scan_id: str | None = None
+    poll_url: str | None = None
+    report: ScanReport | None = None

skillplus-0.1.0/tests/test_client.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+import json
+
+import pytest
+import respx
+from httpx import Response
+
+from skillplus import SkillPlus, SkillPlusError
+
+
+REPORT_PAYLOAD = {
+    "scan_id": "scan_123",
+    "skill_name": "example",
+    "source": "github:owner/repo",
+    "skill_path": "skills/example",
+    "tree_sha": "abc123",
+    "rule_version": "rules-v1",
+    "valid_skill": True,
+    "rating": "safe",
+    "scanned_at": "2026-06-10T00:00:00Z",
+    "cached": True,
+    "scan_duration_ms": 1200,
+    "summary": {
+        "total_issues": 1,
+        "danger": 0,
+        "warning": 1,
+        "info": 0,
+        "files_scanned": 4,
+        "by_category": {"url": 1},
+    },
+    "issues": [
+        {
+            "rule_id": "external-url",
+            "severity": "warning",
+            "category": "url",
+            "message": "External URL found",
+            "file": "SKILL.md",
+            "line": 12,
+            "snippet": "https://example.com",
+            "domain": "example.com",
+        }
+    ],
+    "report_url": "https://skillplus.xyz/report/scan_123",
+    "badge_url": "https://skillplus.xyz/api/report/scan_123/badge.svg",
+    "blacklisted": False,
+    "whitelisted": False,
+    "status": "completed",
+    "ai_report": {
+        "status": "completed",
+        "risk_level": "low",
+        "refined_rating": "safe",
+        "false_positives": [
+            {"rule_id": "external-url", "file": "SKILL.md", "reason": "Documentation link"}
+        ],
+        "analysis": [
+            {
+                "category": "Command Execution",
+                "status": "pass",
+                "severity": "safe",
+                "title": "No command execution",
+                "description": "No risky command execution was found.",
+                "evidence": ["No shell usage"],
+                "confidence": 0.98,
+            }
+        ],
+        "summary": "No meaningful risk found.",
+        "categories_checked": [],
+        "tokens_used": 500,
+        "duration_ms": 800,
+        "error_message": None,
+    },
+    "external_links": {"website": "https://example.com"},
+    "platform_listings": [
+        {"platform": "skills.sh", "url": "https://skills.sh/owner/repo/example", "installs": 10}
+    ],
+}
+
+
+@respx.mock
+def test_query_sends_auth_and_request_body() -> None:
+    route = respx.post("https://skillplus.xyz/api/sdk/query").mock(
+        return_value=Response(
+            200,
+            json={
+                "status": "found",
+                "message": "Report found",
+                "scan_id": "scan_123",
+                "poll_url": "/api/scan/status/scan_123",
+                "report": REPORT_PAYLOAD,
+            },
+        )
+    )
+
+    with SkillPlus(api_key="skp_test") as client:
+        result = client.query(
+            "https://github.com/owner/repo",
+            skill_path="skills/example",
+            scan_if_missing=True,
+            preferred_provider="github",
+        )
+
+    request = route.calls.last.request
+    assert request.headers["Authorization"] == "Bearer skp_test"
+    assert request.headers["Content-Type"] == "application/json"
+    assert json.loads(request.read()) == {
+        "repo_url": "https://github.com/owner/repo",
+        "skill_path": "skills/example",
+        "scan_if_missing": True,
+        "preferred_provider": "github",
+    }
+    assert result.status == "found"
+    assert result.scan_id == "scan_123"
+    assert result.report is not None
+    assert result.report.rating == "safe"
+    assert result.report.summary.warning == 1
+    assert result.report.issues[0].rule_id == "external-url"
+    assert result.report.ai_report is not None
+    assert result.report.ai_report.false_positives[0].reason == "Documentation link"
+
+
+@respx.mock
+def test_query_without_report_returns_status_envelope() -> None:
+    respx.post("https://skillplus.xyz/api/sdk/query").mock(
+        return_value=Response(
+            200,
+            json={
+                "status": "queued",
+                "message": "Scan queued",
+                "scan_id": "scan_queued",
+                "poll_url": "/api/scan/status/scan_queued",
+                "report": None,
+            },
+        )
+    )
+
+    client = SkillPlus(api_key="skp_test")
+    try:
+        result = client.query("https://github.com/owner/repo", scan_if_missing=True)
+    finally:
+        client.close()
+
+    assert result.status == "queued"
+    assert result.scan_id == "scan_queued"
+    assert result.report is None
+
+
+@respx.mock
+def test_scan_sends_force_flag() -> None:
+    route = respx.post("https://skillplus.xyz/api/sdk/scan").mock(
+        return_value=Response(
+            200,
+            json={
+                "status": "running",
+                "message": "Scan already running",
+                "scan_id": "scan_running",
+                "poll_url": "/api/scan/status/scan_running",
+                "report": None,
+            },
+        )
+    )
+
+    with SkillPlus(api_key="skp_test") as client:
+        result = client.scan("https://github.com/owner/repo", skill_path="skills/example", force=True)
+
+    assert json.loads(route.calls.last.request.read()) == {
+        "repo_url": "https://github.com/owner/repo",
+        "skill_path": "skills/example",
+        "preferred_provider": None,
+        "force": True,
+    }
+    assert result.status == "running"
+    assert result.report is None
+
+
+@respx.mock
+def test_get_report_parses_report() -> None:
+    respx.get("https://skillplus.xyz/api/report/scan_123").mock(
+        return_value=Response(200, json=REPORT_PAYLOAD)
+    )
+
+    with SkillPlus(api_key="skp_test") as client:
+        report = client.get_report("scan_123")
+
+    assert report.scan_id == "scan_123"
+    assert report.platform_listings[0].platform == "skills.sh"
+
+
+@respx.mock
+def test_get_badge_returns_svg_text() -> None:
+    respx.get("https://skillplus.xyz/api/report/scan_123/badge.svg").mock(
+        return_value=Response(200, text="<svg></svg>")
+    )
+
+    with SkillPlus(api_key="skp_test") as client:
+        badge = client.get_badge("scan_123")
+
+    assert badge == "<svg></svg>"
+
+
+def test_get_badge_url_uses_hosted_service() -> None:
+    client = SkillPlus(api_key="skp_test")
+    try:
+        assert (
+            client.get_badge_url("scan_123")
+            == "https://skillplus.xyz/api/report/scan_123/badge.svg"
+        )
+    finally:
+        client.close()
+
+
+@respx.mock
+def test_non_ok_response_raises_skillplus_error() -> None:
+    respx.post("https://skillplus.xyz/api/sdk/query").mock(
+        return_value=Response(401, json={"detail": "Invalid API key"})
+    )
+
+    with SkillPlus(api_key="bad_key") as client:
+        with pytest.raises(SkillPlusError) as exc_info:
+            client.query("https://github.com/owner/repo")
+
+    assert exc_info.value.status_code == 401
+    assert exc_info.value.message == "Invalid API key"

skillplus-0.1.0/tests/test_v3_features.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import copy
+
+import pytest
+import respx
+from httpx import Response
+
+from skillplus import SkillPlus, SkillPlusError
+
+from test_client import REPORT_PAYLOAD
+
+
+def _report(**overrides):
+    payload = copy.deepcopy(REPORT_PAYLOAD)
+    payload.update(overrides)
+    return payload
+
+
+SUPPLY_CHAIN = {
+    "dependency_count": 12,
+    "endpoint_count": 3,
+    "blacklist_hits": [
+        {
+            "kind": "package",
+            "ecosystem": "pypi",
+            "name": "litellm",
+            "version_spec": {"exact": ["1.82.7", "1.82.8"]},
+            "reason": "known malicious release",
+            "severity": "critical",
+            "reference_url": "https://example.com/advisory",
+            "match_strength": "exact",
+            "matched_version": "1.82.7",
+        }
+    ],
+}
+
+
+@respx.mock
+def test_supply_chain_parsed() -> None:
+    respx.get("https://skillplus.xyz/api/report/scan_123").mock(
+        return_value=Response(200, json=_report(supply_chain=SUPPLY_CHAIN))
+    )
+    with SkillPlus(api_key="skp_test") as client:
+        report = client.get_report("scan_123")
+
+    assert report.supply_chain is not None
+    assert report.supply_chain.dependency_count == 12
+    assert report.supply_chain.endpoint_count == 3
+    hit = report.supply_chain.blacklist_hits[0]
+    assert hit.name == "litellm"
+    assert hit.ecosystem == "pypi"
+    assert hit.matched_version == "1.82.7"
+    assert hit.version_spec == {"exact": ["1.82.7", "1.82.8"]}
+
+
+@respx.mock
+def test_supply_chain_absent_is_none() -> None:
+    respx.get("https://skillplus.xyz/api/report/scan_123").mock(
+        return_value=Response(200, json=_report())
+    )
+    with SkillPlus(api_key="skp_test") as client:
+        report = client.get_report("scan_123")
+    assert report.supply_chain is None
+
+
+@respx.mock
+def test_agent_runs_parsed() -> None:
+    payload = _report()
+    payload["ai_report"]["agents"] = [
+        {
+            "agent": "supply_chain",
+            "status": "completed",
+            "findings": [{"category": "SUPPLY_CHAIN", "severity": "high"}],
+            "summary": "one poisoned dependency",
+            "tokens_used": 1234,
+            "duration_ms": 4000,
+            "error_message": None,
+        }
+    ]
+    respx.get("https://skillplus.xyz/api/report/scan_123").mock(
+        return_value=Response(200, json=payload)
+    )
+    with SkillPlus(api_key="skp_test") as client:
+        report = client.get_report("scan_123")
+
+    assert report.ai_report is not None
+    assert report.ai_report.agents is not None
+    assert report.ai_report.agents[0].agent == "supply_chain"
+    assert report.ai_report.agents[0].findings[0]["severity"] == "high"
+
+
+@respx.mock
+def test_v3_severity_passthrough() -> None:
+    payload = _report()
+    payload["issues"][0]["severity"] = "high"
+    respx.get("https://skillplus.xyz/api/report/scan_123").mock(
+        return_value=Response(200, json=payload)
+    )
+    with SkillPlus(api_key="skp_test") as client:
+        report = client.get_report("scan_123")
+    assert report.issues[0].severity == "high"
+    assert report.issues[0].severity_normalized == "high"
+
+
+@respx.mock
+def test_base_url_override() -> None:
+    respx.get("https://staging.example.com/api/report/scan_123").mock(
+        return_value=Response(200, json=_report())
+    )
+    with SkillPlus(api_key="skp_test", base_url="https://staging.example.com/") as client:
+        report = client.get_report("scan_123")
+        assert client.get_badge_url("scan_123") == (
+            "https://staging.example.com/api/report/scan_123/badge.svg"
+        )
+    assert report.scan_id == "scan_123"
+
+
+@respx.mock
+def test_retry_on_429_with_retry_after() -> None:
+    route = respx.get("https://skillplus.xyz/api/report/scan_123")
+    route.side_effect = [
+        Response(429, headers={"Retry-After": "0"}, json={"detail": "Rate limit exceeded"}),
+        Response(200, json=_report()),
+    ]
+    with SkillPlus(api_key="skp_test") as client:
+        report = client.get_report("scan_123")
+    assert report.scan_id == "scan_123"
+    assert route.call_count == 2
+
+
+@respx.mock
+def test_no_retry_when_disabled() -> None:
+    respx.get("https://skillplus.xyz/api/report/scan_123").mock(
+        return_value=Response(429, headers={"Retry-After": "0"}, json={"detail": "Rate limit exceeded"})
+    )
+    with SkillPlus(api_key="skp_test", max_retries=0) as client:
+        with pytest.raises(SkillPlusError) as excinfo:
+            client.get_report("scan_123")
+    assert excinfo.value.status_code == 429
+
+
+@respx.mock
+def test_wait_for_report_polls_until_completed() -> None:
+    queued = {"status": "queued", "message": "Scan queued", "scan_id": None, "poll_url": None}
+    found = {
+        "status": "found",
+        "message": "Report found",
+        "scan_id": "scan_123",
+        "poll_url": "/api/scan/status/scan_123",
+        "report": _report(),
+    }
+    route = respx.post("https://skillplus.xyz/api/sdk/query")
+    route.side_effect = [Response(200, json=queued), Response(200, json=found)]
+
+    with SkillPlus(api_key="skp_test") as client:
+        report = client.wait_for_report(
+            "https://github.com/owner/repo", interval=0.01, timeout=5.0
+        )
+
+    assert report.scan_id == "scan_123"
+    assert route.call_count == 2
+
+
+@respx.mock
+def test_wait_for_report_times_out() -> None:
+    queued = {"status": "queued", "message": "Scan queued", "scan_id": None, "poll_url": None}
+    respx.post("https://skillplus.xyz/api/sdk/query").mock(
+        return_value=Response(200, json=queued)
+    )
+    with SkillPlus(api_key="skp_test") as client:
+        with pytest.raises(SkillPlusError) as excinfo:
+            client.wait_for_report("https://github.com/owner/repo", interval=0.01, timeout=0.02)
+    assert "Timed out" in str(excinfo.value)
+
+
+@respx.mock
+def test_verdict_fallback_from_legacy_rating() -> None:
+    respx.get("https://skillplus.xyz/api/report/scan_123").mock(
+        return_value=Response(200, json=_report(rating="low"))
+    )
+    with SkillPlus(api_key="skp_test") as client:
+        report = client.get_report("scan_123")
+    assert report.rating == "low"
+    assert report.verdict == "safe"