Metadata-Version: 2.4
Name: skillplus
Version: 0.1.2
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](https://skillplus.xyz) 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
```

Requires Python 3.10+.

## Quick start

One call that always ends with a completed report — scanning first if the
skill has never been seen:

```python
from skillplus import SkillPlus

client = SkillPlus(api_key="skp_...")

report = client.wait_for_report("https://www.skills.sh/vercel-labs/skills/find-skills")
# GitHub repositories work the same way: "https://github.com/owner/repo"

print(report.verdict)  # "safe" | "medium" | "high" | "unknown" — UI labels: Safe / Caution / High Risk / Unrated
print(report.summary.total_issues)
if report.supply_chain:
    print(report.supply_chain.blacklist_hits)  # poisoned-dependency hits
```

Prefer `verdict` over the legacy `rating` field — it folds historical values
onto the current three-tier scale.

## Lower-level: check without waiting

`query` returns immediately with the current state (`found` / `queued` /
`running` / `not_found` / `failed`) and never blocks:

```python
result = client.query("https://www.skills.sh/vercel-labs/skills/find-skills")

if result.status == "found" and result.report:
    print(result.report.verdict)
```

## 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",       # multi-skill repos are usually on GitHub
    skill_path="skills/example",           # pick one skill in the repo
    scan_if_missing=True,                  # queue a scan if no report exists
)
```

Client options:

```python
client = SkillPlus(
    api_key="skp_...",
    base_url="https://skillplus.xyz",  # staging / self-hosted override
    timeout=30.0,                      # per-request timeout (seconds)
    max_retries=2,                     # retries on 429/502/503, honoring Retry-After
)
```

## Context manager

```python
from skillplus import SkillPlus

with SkillPlus(api_key="skp_...") as client:
    result = client.scan("https://www.skills.sh/vercel-labs/skills/find-skills")
    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. |
| `wait_for_report(...)` | Query-and-wait: scans if missing, polls, and returns the completed report. |
| `get_report(scan_id)` | Retrieve structured report data: verdict, findings, AI audit, supply-chain snapshot. |
| `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://www.skills.sh/vercel-labs/skills/find-skills")
except SkillPlusError as error:
    print(error.status_code)
    print(error.message)
```

## Development

```bash
uv sync --extra dev
uv run pytest
uv build
```
