Spaces:
Sleeping
Sleeping
Deploy Skills Cloud
Browse files- README.md +92 -5
- app.py +24 -0
- docs/design/m1-skillspec.md +100 -0
- requirements.txt +15 -0
- skills/copywriter/SKILL.md +33 -0
- skills/image-gen/SKILL.md +19 -0
- src/skills_cloud/__init__.py +3 -0
- src/skills_cloud/backends.py +300 -0
- src/skills_cloud/github.py +301 -0
- src/skills_cloud/infer.py +130 -0
- src/skills_cloud/models_hub.py +77 -0
- src/skills_cloud/runner.py +90 -0
- src/skills_cloud/skill.py +506 -0
- src/skills_cloud/ui.py +725 -0
- src/skills_cloud/zerogpu.py +185 -0
README.md
CHANGED
|
@@ -1,14 +1,101 @@
|
|
| 1 |
---
|
| 2 |
title: Skills Cloud
|
| 3 |
-
emoji:
|
| 4 |
-
colorFrom:
|
| 5 |
colorTo: indigo
|
| 6 |
sdk: gradio
|
| 7 |
sdk_version: 6.24.0
|
| 8 |
-
python_version: '3.12'
|
| 9 |
app_file: app.py
|
| 10 |
pinned: false
|
| 11 |
-
|
|
|
|
|
|
|
| 12 |
---
|
| 13 |
|
| 14 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
---
|
| 2 |
title: Skills Cloud
|
| 3 |
+
emoji: ☁️
|
| 4 |
+
colorFrom: blue
|
| 5 |
colorTo: indigo
|
| 6 |
sdk: gradio
|
| 7 |
sdk_version: 6.24.0
|
|
|
|
| 8 |
app_file: app.py
|
| 9 |
pinned: false
|
| 10 |
+
hf_oauth: true
|
| 11 |
+
hf_oauth_scopes:
|
| 12 |
+
- inference-api
|
| 13 |
---
|
| 14 |
|
| 15 |
+
# ☁️ Skills Cloud
|
| 16 |
+
|
| 17 |
+
**Run lightweight agent skills in one click — no local install, no dependency conflicts.**
|
| 18 |
+
|
| 19 |
+
Lightweight skills (image generation, copywriting, …) are painful to install locally and out of
|
| 20 |
+
reach for non-developers. Skills Cloud turns a skill package (`SKILL.md`) into a ready-to-use
|
| 21 |
+
[Hugging Face Space](https://huggingface.co/spaces) built with Gradio:
|
| 22 |
+
|
| 23 |
+
- **Pick a Hub model** — run the skill on Hugging Face Inference Providers with your HF token, or
|
| 24 |
+
- **Bring your own key** — paste an Anthropic API key instead.
|
| 25 |
+
- **One-click install** — *Duplicate this Space*, drop your own `skills/<name>/SKILL.md` in, done.
|
| 26 |
+
|
| 27 |
+
Keys live only in your session. They are never stored, logged, or echoed in error messages.
|
| 28 |
+
|
| 29 |
+
## Using the Space
|
| 30 |
+
|
| 31 |
+
1. **Load skills from any GitHub repo** — paste `owner/repo`, `owner/repo@branch`, or a
|
| 32 |
+
github.com URL (deep `/tree/<branch>/<dir>` links work too) and hit **Load skills**.
|
| 33 |
+
Every `SKILL.md` in the repo becomes a tab, instantly, and the view filters to that repo
|
| 34 |
+
(use the source dropdown to see everything). Loaded repos are session-only.
|
| 35 |
+
Ported skills get their output type auto-detected (editable if the guess is wrong);
|
| 36 |
+
uploading an image automatically switches to vision or image-to-image.
|
| 37 |
+
2. Open a skill tab and pick a backend: **Hugging Face** (token, sign-in, or Space secret),
|
| 38 |
+
**Anthropic API** (key or Space secret), or **OpenAI-compatible** — point it at any
|
| 39 |
+
endpoint (OpenAI, DeepSeek, OpenRouter, local Ollama/vLLM at `http://localhost:11434/v1`);
|
| 40 |
+
custom endpoints use only the key you type, never Space secrets.
|
| 41 |
+
3. Fill in the form and hit **Run**.
|
| 42 |
+
|
| 43 |
+
> **Space owners:** setting `HF_TOKEN` or `ANTHROPIC_API_KEY` as a Space secret means every
|
| 44 |
+
> visitor runs on **your** quota/billing. That is an explicit opt-in — leave the secrets unset
|
| 45 |
+
> to require visitors to bring their own keys.
|
| 46 |
+
|
| 47 |
+
## Writing a skill
|
| 48 |
+
|
| 49 |
+
A skill is one file: `skills/<slug>/SKILL.md` — YAML frontmatter + markdown instructions.
|
| 50 |
+
The format is a superset of the Claude Code skill format: porting an existing skill is usually
|
| 51 |
+
"add an `inputs:` block, done." Unknown top-level keys are ignored.
|
| 52 |
+
|
| 53 |
+
```markdown
|
| 54 |
+
---
|
| 55 |
+
name: Copywriter
|
| 56 |
+
description: Punchy marketing copy in your chosen tone.
|
| 57 |
+
emoji: "✍️"
|
| 58 |
+
output: text # text (default) | image
|
| 59 |
+
inputs:
|
| 60 |
+
- name: product # ^[a-z][a-z0-9_]*$
|
| 61 |
+
label: Product name
|
| 62 |
+
- name: tone
|
| 63 |
+
type: select # text (default) | textarea | select
|
| 64 |
+
options: [Playful, Professional]
|
| 65 |
+
default: Professional
|
| 66 |
+
required: false
|
| 67 |
+
---
|
| 68 |
+
Write marketing copy for {{product}}. Tone: {{tone}}.
|
| 69 |
+
```
|
| 70 |
+
|
| 71 |
+
Placeholders `{{name}}` are substituted from the form. Declared inputs you don't reference are
|
| 72 |
+
appended to the prompt automatically. Broken skills never take the app down — they show up in
|
| 73 |
+
the "skill issues" panel instead. Full format rules: [docs/design/m1-skillspec.md](docs/design/m1-skillspec.md).
|
| 74 |
+
|
| 75 |
+
## Deploying your own
|
| 76 |
+
|
| 77 |
+
```bash
|
| 78 |
+
uv run python scripts_py/deploy_space.py your-username/skills-cloud --dry-run # inspect
|
| 79 |
+
uv run python scripts_py/deploy_space.py your-username/skills-cloud # publish
|
| 80 |
+
```
|
| 81 |
+
|
| 82 |
+
Requires a write-scoped HF token (`hf auth login` or `HF_TOKEN`). Or simply click
|
| 83 |
+
**Duplicate this Space** on an existing deployment — that is the intended install path.
|
| 84 |
+
|
| 85 |
+
## Development
|
| 86 |
+
|
| 87 |
+
```bash
|
| 88 |
+
uv sync # install deps
|
| 89 |
+
uv run python app.py # launch locally
|
| 90 |
+
```
|
| 91 |
+
|
| 92 |
+
Quality gates (run before every commit):
|
| 93 |
+
|
| 94 |
+
```bash
|
| 95 |
+
uv run ruff check . && uv run ruff format --check . && uv run pytest -q
|
| 96 |
+
```
|
| 97 |
+
|
| 98 |
+
Real-provider contract tests (need keys, deselected by default): `uv run pytest -m network`.
|
| 99 |
+
|
| 100 |
+
Development happens in the source repo, driven by
|
| 101 |
+
[Flow Copilot](https://github.com/flownet-tech/flow-copilot).
|
app.py
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""Skills Cloud — Gradio entrypoint.
|
| 2 |
+
|
| 3 |
+
HF Spaces convention: app.py at repo root, importable without side effects
|
| 4 |
+
(no launch, no network at import time). Spaces runs this file without
|
| 5 |
+
installing the package, so src/ goes on sys.path explicitly.
|
| 6 |
+
"""
|
| 7 |
+
|
| 8 |
+
import sys
|
| 9 |
+
from pathlib import Path
|
| 10 |
+
|
| 11 |
+
_ROOT = Path(__file__).resolve().parent
|
| 12 |
+
sys.path.insert(0, str(_ROOT / "src"))
|
| 13 |
+
|
| 14 |
+
from skills_cloud.skill import load_catalog # noqa: E402
|
| 15 |
+
from skills_cloud.ui import build_app # noqa: E402
|
| 16 |
+
from skills_cloud.zerogpu import warmup_pipelines # noqa: E402
|
| 17 |
+
|
| 18 |
+
SKILLS_DIR = _ROOT / "skills"
|
| 19 |
+
|
| 20 |
+
warmup_pipelines() # no-op off ZeroGPU; eager model load on the Space
|
| 21 |
+
demo = build_app(load_catalog(SKILLS_DIR))
|
| 22 |
+
|
| 23 |
+
if __name__ == "__main__":
|
| 24 |
+
demo.launch()
|
docs/design/m1-skillspec.md
ADDED
|
@@ -0,0 +1,100 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# M1 Design Record — SKILL.md format, SkillSpec, backends
|
| 2 |
+
|
| 3 |
+
> Decided 2026-08-13 via a 3-proposal / 2-judge design panel (lenses: MVP-minimal, HF-native,
|
| 4 |
+
> skill-author). Correctness judge picked MVP-minimal; product judge picked HF-native.
|
| 5 |
+
> This record is the manager synthesis. Rejected alternatives are noted inline.
|
| 6 |
+
|
| 7 |
+
## SKILL.md format (strict superset of Claude Code skill format)
|
| 8 |
+
|
| 9 |
+
A skill is `skills/<slug>/SKILL.md`: YAML frontmatter between `---` fences, then a markdown body.
|
| 10 |
+
`name` + `description` keep their Claude Code meaning; the body stays "instructions"; **unknown
|
| 11 |
+
top-level keys are ignored** (a warning fires only for case-typos of known keys). Unknown keys
|
| 12 |
+
**inside an `inputs` item are a hard error** (typo protection for our own schema).
|
| 13 |
+
|
| 14 |
+
| Key | Rule |
|
| 15 |
+
| --- | --- |
|
| 16 |
+
| `name` | required, non-empty str, ≤64 chars |
|
| 17 |
+
| `description` | required, non-empty str |
|
| 18 |
+
| `emoji` | optional str, default 🛠️ |
|
| 19 |
+
| `output` | optional, `text` (default) \| `image` |
|
| 20 |
+
| `models` | optional map backend→model; keys ⊆ {`anthropic`,`hf`}; `anthropic` forbidden when `output: image`; defaults filled from code constants |
|
| 21 |
+
| `inputs` | optional list: `name` (required, `^[a-z][a-z0-9_]*$`, unique), `type` `text`(default)/`textarea`/`select`/`image`, `label` (default derived from name), `required` (default true), `default` (str, `""`; not for image), `placeholder` (text/textarea only), `options` (iff select: non-empty, unique) |
|
| 22 |
+
|
| 23 |
+
Skill **kind** is derived, never declared: `text` (text out), `vision` (text out + image input),
|
| 24 |
+
`image_gen` (image out), `image_edit` (image out + image input). Image inputs cannot be referenced
|
| 25 |
+
as body placeholders; they attach to the request (vision content / image-to-image source).
|
| 26 |
+
Kind defaults: `vision→Qwen2.5-VL-72B / claude-opus-5`, `image_edit→Qwen/Qwen-Image-Edit`.
|
| 27 |
+
|
| 28 |
+
**Ported skills** (no declared `inputs`/`output`, e.g. Claude Code skills loaded from GitHub) get
|
| 29 |
+
heuristic output inference (word-boundary keyword scoring; ties→text) plus universal optional
|
| 30 |
+
inputs (`image`, `request`). The UI shows the guess as an editable dropdown; an uploaded image
|
| 31 |
+
switches chat→vision and text-to-image→image-to-image automatically at run time.
|
| 32 |
+
|
| 33 |
+
Body placeholders: `{{input_name}}`. Every placeholder must name a declared input (hard error).
|
| 34 |
+
A declared input **not** referenced in the body is auto-appended to the prompt at run time
|
| 35 |
+
(parse warning, not an error — this is what keeps porting a Claude skill "add `inputs:`, done").
|
| 36 |
+
Rejected: P1's hard error on unreferenced inputs (kills zero-edit porting); Jinja2 templating
|
| 37 |
+
(dependency + injection surface, breaks body portability); `{name}` syntax (collides with JSON/prose).
|
| 38 |
+
|
| 39 |
+
Non-gated default models (fresh-token zero-config path must not 403):
|
| 40 |
+
`anthropic→claude-opus-5`, `hf text→Qwen/Qwen2.5-72B-Instruct`, `hf image→black-forest-labs/FLUX.1-schnell`.
|
| 41 |
+
|
| 42 |
+
## Prompt composition
|
| 43 |
+
|
| 44 |
+
`resolve_values` first builds a fully-resolved dict (all declared inputs present: stripped value,
|
| 45 |
+
else `default`, required-and-empty → `InputValueError`); substitution reads only that dict — no
|
| 46 |
+
KeyError class. Rendered body = the user message (text) or the image prompt (image); `system` is
|
| 47 |
+
reserved (`None` in M1). Unreferenced non-empty inputs append as `## Inputs` + `- Label: value`
|
| 48 |
+
lines for text, plain `Label: value` lines for image (no markdown headers in image prompts).
|
| 49 |
+
Rejected: body-as-system + kickoff constant (magic with no M1 payoff); full message-list templating.
|
| 50 |
+
|
| 51 |
+
## Backend interface (SC-003)
|
| 52 |
+
|
| 53 |
+
```python
|
| 54 |
+
class Backend(Protocol):
|
| 55 |
+
id: str
|
| 56 |
+
label: str
|
| 57 |
+
supports_image: bool
|
| 58 |
+
|
| 59 |
+
def stream_text(self, req: TextRequest, *, api_key: str) -> Iterator[str]: ... # yields deltas
|
| 60 |
+
def generate_image(self, prompt: str, *, model: str, api_key: str) -> PIL.Image.Image: ...
|
| 61 |
+
```
|
| 62 |
+
|
| 63 |
+
- Stateless; SDK client constructed per call; SDK imports lazy (inside methods) so spec/loader/runner
|
| 64 |
+
tests import neither SDK. `api_key` is keyword-only, per-call, never stored/logged/echoed.
|
| 65 |
+
- Errors: `BackendError(user_message)` → `AuthError` / `ModelNotFoundError` / `RateLimitedError` /
|
| 66 |
+
`ProviderError` / `UnsupportedOperationError`; always `raise ... from e`; HF chokepoint catches
|
| 67 |
+
broad `Exception` (incl. provider-mapping `ValueError`, gated/missing repos, timeouts) with a
|
| 68 |
+
None-guard on `.response`; guard empty `chunk.choices` (usage-only final chunks); zero deltas
|
| 69 |
+
streamed → `ProviderError("The model returned no text.")`.
|
| 70 |
+
- Per-backend `max_tokens` defaults: anthropic 16000 (thinking shares the cap), hf 2048.
|
| 71 |
+
- Rejected: GenEvent dataclass union (speculative for M1 — deltas are `str`); ABC over Protocol
|
| 72 |
+
(Protocol lets the fake be a plain class).
|
| 73 |
+
|
| 74 |
+
## Loading & UI surfacing
|
| 75 |
+
|
| 76 |
+
Depth-1 scan of `skills/`; skip non-dirs and `.`/`_` prefixes; dirs without `SKILL.md` skipped;
|
| 77 |
+
per-skill broad exception catch → `SkillFailure` (one bad skill never kills the catalog);
|
| 78 |
+
deterministic order `(slug.casefold(), slug)`. Missing/empty `skills/` → app boots with a notice
|
| 79 |
+
(a crash-looping duplicated Space is the worst outcome for the Duplicate-this-Space strategy).
|
| 80 |
+
Failures + parse warnings render in a collapsed accordion — that accordion IS the skill author's
|
| 81 |
+
feedback loop on a duplicated Space.
|
| 82 |
+
|
| 83 |
+
## Credentials
|
| 84 |
+
|
| 85 |
+
Per-request from UI fields (password type). Empty field → env fallback: `HF_TOKEN` /
|
| 86 |
+
`ANTHROPIC_API_KEY` (a Space secret is the owner's explicit opt-in to paying for visitors —
|
| 87 |
+
documented in README). Keys never persisted, never in logs or error messages.
|
| 88 |
+
|
| 89 |
+
**OpenAI-compatible endpoints (custom base URL)**: the typed key ONLY — never env secrets,
|
| 90 |
+
never the OAuth session token. The endpoint is user-controlled; any fallback would exfiltrate
|
| 91 |
+
the owner's credentials to an arbitrary server. Key optional (local Ollama/vLLM need none).
|
| 92 |
+
Model ids allow Ollama-style `name:tag`; `://` remains banned everywhere (URL-shaped model ids
|
| 93 |
+
would redirect bearer tokens). Known tradeoff, accepted for the local-model use case: the Space
|
| 94 |
+
server connects to a visitor-supplied URL (SSRF surface on public deployments).
|
| 95 |
+
|
| 96 |
+
## Deferred (recorded, not lost)
|
| 97 |
+
|
| 98 |
+
`examples` frontmatter (gr.Examples prefill), `number` input type, `max_tokens` frontmatter
|
| 99 |
+
override, `format:` version gate, tags/filtering, hot reload. All additive — unknown-key tolerance
|
| 100 |
+
means old parsers ignore them.
|
requirements.txt
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Runtime dependencies for the Hugging Face Space (and plain pip users).
|
| 2 |
+
# Floors must match pyproject.toml — tests/test_packaging.py enforces the sync.
|
| 3 |
+
gradio[oauth]>=6.24,<7
|
| 4 |
+
httpx>=0.28.1
|
| 5 |
+
huggingface-hub>=1.27,<2
|
| 6 |
+
anthropic>=0.122.0
|
| 7 |
+
pyyaml>=6.0.3
|
| 8 |
+
pillow>=12.3.0
|
| 9 |
+
# ZeroGPU stack (used only when the Space runs ZeroGPU hardware; harmless on CPU)
|
| 10 |
+
spaces>=0.51.1
|
| 11 |
+
torch>=2.4
|
| 12 |
+
transformers>=4.49
|
| 13 |
+
diffusers>=0.32
|
| 14 |
+
accelerate>=1.0
|
| 15 |
+
sentencepiece>=0.2
|
skills/copywriter/SKILL.md
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
---
|
| 2 |
+
name: Copywriter
|
| 3 |
+
description: Punchy marketing copy for any product — three variants, in your chosen tone.
|
| 4 |
+
emoji: "✍️"
|
| 5 |
+
output: text
|
| 6 |
+
inputs:
|
| 7 |
+
- name: product
|
| 8 |
+
type: text
|
| 9 |
+
label: Product name
|
| 10 |
+
placeholder: e.g. AcmeBrew coffee maker
|
| 11 |
+
- name: details
|
| 12 |
+
type: textarea
|
| 13 |
+
label: What it does / who it's for
|
| 14 |
+
placeholder: One or two sentences about the product and its audience
|
| 15 |
+
- name: tone
|
| 16 |
+
type: select
|
| 17 |
+
label: Tone
|
| 18 |
+
options: [Playful, Professional, Bold, Warm]
|
| 19 |
+
default: Professional
|
| 20 |
+
required: false
|
| 21 |
+
---
|
| 22 |
+
Write three variants of marketing copy for {{product}}.
|
| 23 |
+
|
| 24 |
+
Product details: {{details}}
|
| 25 |
+
|
| 26 |
+
Tone: {{tone}}.
|
| 27 |
+
|
| 28 |
+
Each variant must have:
|
| 29 |
+
- A headline of at most 8 words
|
| 30 |
+
- One sentence of body copy (max 25 words)
|
| 31 |
+
|
| 32 |
+
Number the variants 1–3. Output only the copy — no preamble, no commentary,
|
| 33 |
+
no explanations of your choices.
|
skills/image-gen/SKILL.md
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
---
|
| 2 |
+
name: Image Generator
|
| 3 |
+
description: Turn a short description into an illustration in a style you pick.
|
| 4 |
+
emoji: "🎨"
|
| 5 |
+
output: image
|
| 6 |
+
inputs:
|
| 7 |
+
- name: subject
|
| 8 |
+
type: textarea
|
| 9 |
+
label: What to draw
|
| 10 |
+
placeholder: e.g. a lighthouse on a cliff at sunset, seabirds circling
|
| 11 |
+
- name: style
|
| 12 |
+
type: select
|
| 13 |
+
label: Style
|
| 14 |
+
options: [Photorealistic, Watercolor, Pixel art, Ink sketch, Isometric 3D]
|
| 15 |
+
default: Watercolor
|
| 16 |
+
required: false
|
| 17 |
+
---
|
| 18 |
+
{{style}} illustration of {{subject}}. High detail, coherent composition,
|
| 19 |
+
balanced lighting, no text, no watermarks, no borders.
|
src/skills_cloud/__init__.py
ADDED
|
@@ -0,0 +1,3 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""Skills Cloud — turn lightweight agent skills into one-click Hugging Face Spaces."""
|
| 2 |
+
|
| 3 |
+
__version__ = "0.1.0"
|
src/skills_cloud/backends.py
ADDED
|
@@ -0,0 +1,300 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""Provider backends: Anthropic API and Hugging Face Inference Providers.
|
| 2 |
+
|
| 3 |
+
SDK imports are lazy (inside methods) so unit tests for spec/runner import
|
| 4 |
+
neither SDK. Backends are stateless: the client is constructed per call and
|
| 5 |
+
discarded. The API key is a keyword-only, per-call argument — never stored on
|
| 6 |
+
the backend, never logged, never echoed into error messages.
|
| 7 |
+
"""
|
| 8 |
+
|
| 9 |
+
from __future__ import annotations
|
| 10 |
+
|
| 11 |
+
from collections.abc import Iterator
|
| 12 |
+
from dataclasses import dataclass
|
| 13 |
+
from typing import TYPE_CHECKING, Protocol, runtime_checkable
|
| 14 |
+
|
| 15 |
+
if TYPE_CHECKING:
|
| 16 |
+
from PIL import Image
|
| 17 |
+
|
| 18 |
+
# Anthropic default is high because extended thinking shares the cap; several
|
| 19 |
+
# HF providers reject or mis-bill large values, so HF stays conservative.
|
| 20 |
+
DEFAULT_MAX_TOKENS: dict[str, int] = {"anthropic": 16000, "hf": 2048}
|
| 21 |
+
FALLBACK_MAX_TOKENS = 4096
|
| 22 |
+
|
| 23 |
+
|
| 24 |
+
class BackendError(Exception):
|
| 25 |
+
"""Base for provider failures. ``user_message`` is safe to show in the UI."""
|
| 26 |
+
|
| 27 |
+
def __init__(self, user_message: str):
|
| 28 |
+
self.user_message = user_message
|
| 29 |
+
super().__init__(user_message)
|
| 30 |
+
|
| 31 |
+
|
| 32 |
+
class AuthError(BackendError):
|
| 33 |
+
"""The credential was rejected (or the model is gated behind a license)."""
|
| 34 |
+
|
| 35 |
+
|
| 36 |
+
class ModelNotFoundError(BackendError):
|
| 37 |
+
"""The requested model does not exist or is not served."""
|
| 38 |
+
|
| 39 |
+
|
| 40 |
+
class RateLimitedError(BackendError):
|
| 41 |
+
"""The provider throttled the request."""
|
| 42 |
+
|
| 43 |
+
|
| 44 |
+
class ProviderError(BackendError):
|
| 45 |
+
"""Any other provider-side or network failure."""
|
| 46 |
+
|
| 47 |
+
|
| 48 |
+
class UnsupportedOperationError(BackendError):
|
| 49 |
+
"""The backend cannot perform the requested operation."""
|
| 50 |
+
|
| 51 |
+
|
| 52 |
+
@dataclass(frozen=True, slots=True)
|
| 53 |
+
class TextRequest:
|
| 54 |
+
user: str
|
| 55 |
+
model: str
|
| 56 |
+
max_tokens: int
|
| 57 |
+
system: str | None = None # reserved; None in M1
|
| 58 |
+
images: tuple = () # PIL images sent as vision content with the user turn
|
| 59 |
+
base_url: str | None = None # OpenAI-compatible endpoint (openai backend only)
|
| 60 |
+
|
| 61 |
+
|
| 62 |
+
def _png_bytes(image) -> bytes:
|
| 63 |
+
from io import BytesIO
|
| 64 |
+
|
| 65 |
+
buffer = BytesIO()
|
| 66 |
+
image.save(buffer, format="PNG")
|
| 67 |
+
return buffer.getvalue()
|
| 68 |
+
|
| 69 |
+
|
| 70 |
+
def _png_base64(image) -> str:
|
| 71 |
+
import base64
|
| 72 |
+
|
| 73 |
+
return base64.b64encode(_png_bytes(image)).decode("ascii")
|
| 74 |
+
|
| 75 |
+
|
| 76 |
+
@runtime_checkable
|
| 77 |
+
class Backend(Protocol):
|
| 78 |
+
id: str
|
| 79 |
+
label: str
|
| 80 |
+
supports_image: bool
|
| 81 |
+
|
| 82 |
+
def stream_text(self, req: TextRequest, *, api_key: str) -> Iterator[str]:
|
| 83 |
+
"""Yield text deltas (not accumulated text)."""
|
| 84 |
+
...
|
| 85 |
+
|
| 86 |
+
def generate_image(
|
| 87 |
+
self, prompt: str, *, model: str, api_key: str, image: Image.Image | None = None
|
| 88 |
+
) -> Image.Image:
|
| 89 |
+
"""Return a single PIL image; ``image`` switches to image-to-image."""
|
| 90 |
+
...
|
| 91 |
+
|
| 92 |
+
|
| 93 |
+
class AnthropicBackend:
|
| 94 |
+
id = "anthropic"
|
| 95 |
+
label = "Anthropic API"
|
| 96 |
+
supports_image = False
|
| 97 |
+
|
| 98 |
+
def stream_text(self, req: TextRequest, *, api_key: str) -> Iterator[str]:
|
| 99 |
+
import anthropic
|
| 100 |
+
|
| 101 |
+
client = anthropic.Anthropic(api_key=api_key)
|
| 102 |
+
extra: dict = {"system": req.system} if req.system else {}
|
| 103 |
+
if req.images:
|
| 104 |
+
content: list[dict] = [
|
| 105 |
+
{
|
| 106 |
+
"type": "image",
|
| 107 |
+
"source": {
|
| 108 |
+
"type": "base64",
|
| 109 |
+
"media_type": "image/png",
|
| 110 |
+
"data": _png_base64(image),
|
| 111 |
+
},
|
| 112 |
+
}
|
| 113 |
+
for image in req.images
|
| 114 |
+
]
|
| 115 |
+
content.append({"type": "text", "text": req.user})
|
| 116 |
+
else:
|
| 117 |
+
content = req.user # type: ignore[assignment]
|
| 118 |
+
try:
|
| 119 |
+
with client.messages.stream(
|
| 120 |
+
model=req.model,
|
| 121 |
+
max_tokens=req.max_tokens,
|
| 122 |
+
messages=[{"role": "user", "content": content}],
|
| 123 |
+
**extra,
|
| 124 |
+
) as stream:
|
| 125 |
+
yield from stream.text_stream
|
| 126 |
+
stop = getattr(stream.get_final_message(), "stop_reason", None)
|
| 127 |
+
if stop == "max_tokens":
|
| 128 |
+
raise ProviderError("Output hit the token limit and was truncated.")
|
| 129 |
+
if stop == "refusal":
|
| 130 |
+
raise ProviderError("The model declined to complete this request.")
|
| 131 |
+
except BackendError:
|
| 132 |
+
raise
|
| 133 |
+
# Auth/NotFound/RateLimit subclass APIStatusError — order matters.
|
| 134 |
+
except anthropic.AuthenticationError as exc:
|
| 135 |
+
raise AuthError(f"API key was rejected by {self.label}. Check it and retry.") from exc
|
| 136 |
+
except anthropic.PermissionDeniedError as exc:
|
| 137 |
+
raise AuthError(f"This API key is not allowed to use {req.model!r}.") from exc
|
| 138 |
+
except anthropic.NotFoundError as exc:
|
| 139 |
+
raise ModelNotFoundError(f"Model {req.model!r} was not found on {self.label}.") from exc
|
| 140 |
+
except anthropic.RateLimitError as exc:
|
| 141 |
+
raise RateLimitedError(
|
| 142 |
+
f"Rate limited by {self.label}; wait a moment and retry."
|
| 143 |
+
) from exc
|
| 144 |
+
except anthropic.APIConnectionError as exc:
|
| 145 |
+
raise ProviderError(f"Network error reaching {self.label}.") from exc
|
| 146 |
+
except anthropic.APIStatusError as exc:
|
| 147 |
+
raise ProviderError(
|
| 148 |
+
f"{self.label} returned an error (HTTP {exc.status_code})."
|
| 149 |
+
) from exc
|
| 150 |
+
# Mid-stream transport failures escape the SDK unmapped (raw httpx
|
| 151 |
+
# errors) — never let them reach the UI as tracebacks.
|
| 152 |
+
except Exception as exc:
|
| 153 |
+
raise ProviderError(
|
| 154 |
+
f"{self.label} request failed mid-stream ({type(exc).__name__})."
|
| 155 |
+
) from exc
|
| 156 |
+
|
| 157 |
+
def generate_image(
|
| 158 |
+
self, prompt: str, *, model: str, api_key: str, image: Image.Image | None = None
|
| 159 |
+
) -> Image.Image:
|
| 160 |
+
raise UnsupportedOperationError(f"{self.label} does not provide image generation.")
|
| 161 |
+
|
| 162 |
+
|
| 163 |
+
class HFInferenceBackend:
|
| 164 |
+
id = "hf"
|
| 165 |
+
label = "Hugging Face Inference"
|
| 166 |
+
supports_image = True
|
| 167 |
+
|
| 168 |
+
def _client(self, req: TextRequest, api_key: str):
|
| 169 |
+
from huggingface_hub import InferenceClient
|
| 170 |
+
|
| 171 |
+
return InferenceClient(api_key=api_key)
|
| 172 |
+
|
| 173 |
+
def stream_text(self, req: TextRequest, *, api_key: str) -> Iterator[str]:
|
| 174 |
+
client = self._client(req, api_key)
|
| 175 |
+
messages: list[dict] = []
|
| 176 |
+
if req.system:
|
| 177 |
+
messages.append({"role": "system", "content": req.system})
|
| 178 |
+
if req.images:
|
| 179 |
+
content: list[dict] = [
|
| 180 |
+
{
|
| 181 |
+
"type": "image_url",
|
| 182 |
+
"image_url": {"url": f"data:image/png;base64,{_png_base64(image)}"},
|
| 183 |
+
}
|
| 184 |
+
for image in req.images
|
| 185 |
+
]
|
| 186 |
+
content.append({"type": "text", "text": req.user})
|
| 187 |
+
messages.append({"role": "user", "content": content})
|
| 188 |
+
else:
|
| 189 |
+
messages.append({"role": "user", "content": req.user})
|
| 190 |
+
finish = None
|
| 191 |
+
try:
|
| 192 |
+
for chunk in client.chat_completion(
|
| 193 |
+
messages=messages, model=req.model, stream=True, max_tokens=req.max_tokens
|
| 194 |
+
):
|
| 195 |
+
if not chunk.choices: # usage-only final chunks have empty choices
|
| 196 |
+
continue
|
| 197 |
+
choice = chunk.choices[0]
|
| 198 |
+
finish = getattr(choice, "finish_reason", None) or finish
|
| 199 |
+
delta = choice.delta.content
|
| 200 |
+
if delta:
|
| 201 |
+
yield delta
|
| 202 |
+
except BackendError:
|
| 203 |
+
raise
|
| 204 |
+
except Exception as exc:
|
| 205 |
+
raise _map_hf_error(exc, self.label, req.model) from exc
|
| 206 |
+
if finish == "length":
|
| 207 |
+
raise ProviderError("Output hit the token limit and was truncated.")
|
| 208 |
+
|
| 209 |
+
def generate_image(
|
| 210 |
+
self, prompt: str, *, model: str, api_key: str, image: Image.Image | None = None
|
| 211 |
+
) -> Image.Image:
|
| 212 |
+
from huggingface_hub import InferenceClient
|
| 213 |
+
|
| 214 |
+
client = InferenceClient(api_key=api_key)
|
| 215 |
+
try:
|
| 216 |
+
if image is not None:
|
| 217 |
+
# Always send bytes: image_to_image claims to accept PIL, but
|
| 218 |
+
# some provider adapters (e.g. wavespeed) require bytes and
|
| 219 |
+
# raise TypeError on Image objects.
|
| 220 |
+
return client.image_to_image(_png_bytes(image), prompt=prompt, model=model)
|
| 221 |
+
return client.text_to_image(prompt, model=model)
|
| 222 |
+
except Exception as exc:
|
| 223 |
+
raise _map_hf_error(exc, self.label, model) from exc
|
| 224 |
+
|
| 225 |
+
|
| 226 |
+
class OpenAICompatibleBackend(HFInferenceBackend):
|
| 227 |
+
"""Any OpenAI-compatible /chat/completions endpoint: OpenAI, DeepSeek,
|
| 228 |
+
OpenRouter, local Ollama/vLLM/LM Studio...
|
| 229 |
+
|
| 230 |
+
InferenceClient(base_url=...) speaks the OpenAI chat protocol, so the
|
| 231 |
+
streaming/vision/error machinery is inherited from the HF backend. The
|
| 232 |
+
key is optional (local servers need none) and callers must NEVER fall
|
| 233 |
+
back to Space secrets for custom endpoints — the endpoint is
|
| 234 |
+
user-controlled, so an env-key fallback would exfiltrate the owner's
|
| 235 |
+
secret (see ui.resolve_api_key policy).
|
| 236 |
+
"""
|
| 237 |
+
|
| 238 |
+
id = "openai"
|
| 239 |
+
label = "OpenAI-compatible endpoint"
|
| 240 |
+
supports_image = False
|
| 241 |
+
|
| 242 |
+
def _client(self, req: TextRequest, api_key: str):
|
| 243 |
+
from huggingface_hub import InferenceClient
|
| 244 |
+
|
| 245 |
+
if not req.base_url:
|
| 246 |
+
raise ProviderError("No endpoint URL configured for the OpenAI-compatible backend.")
|
| 247 |
+
return InferenceClient(base_url=req.base_url, api_key=api_key or None)
|
| 248 |
+
|
| 249 |
+
def generate_image(
|
| 250 |
+
self, prompt: str, *, model: str, api_key: str, image: Image.Image | None = None
|
| 251 |
+
) -> Image.Image:
|
| 252 |
+
raise UnsupportedOperationError(
|
| 253 |
+
f"{self.label} supports text/vision chat only (no image generation in M1)."
|
| 254 |
+
)
|
| 255 |
+
|
| 256 |
+
|
| 257 |
+
def _map_hf_error(exc: Exception, label: str, model: str) -> BackendError:
|
| 258 |
+
"""Map any huggingface_hub failure to a BackendError with a safe message.
|
| 259 |
+
|
| 260 |
+
Broad by design: provider-mapping ValueErrors, gated/missing repos, and
|
| 261 |
+
timeouts must all surface as readable messages, never raw tracebacks.
|
| 262 |
+
The ``.response`` guard survives SDK versions where it is absent.
|
| 263 |
+
"""
|
| 264 |
+
status = getattr(getattr(exc, "response", None), "status_code", None)
|
| 265 |
+
if status in (401, 403):
|
| 266 |
+
return AuthError(
|
| 267 |
+
f"Token was rejected by {label} — or model {model!r} is gated and needs its "
|
| 268 |
+
"license accepted on the Hub first, or the token lacks the "
|
| 269 |
+
"'Make calls to Inference Providers' permission (fine-grained tokens need it enabled)."
|
| 270 |
+
)
|
| 271 |
+
if status == 404:
|
| 272 |
+
return ModelNotFoundError(f"Model {model!r} was not found or is not served by {label}.")
|
| 273 |
+
if status == 429:
|
| 274 |
+
return RateLimitedError(f"Rate limited by {label}; wait a moment and retry.")
|
| 275 |
+
if isinstance(exc, ValueError):
|
| 276 |
+
return ProviderError(f"Model {model!r} is not available via {label}: {exc}")
|
| 277 |
+
if status is not None:
|
| 278 |
+
return ProviderError(f"{label} returned an error (HTTP {status}).")
|
| 279 |
+
return ProviderError(f"{label} request failed ({type(exc).__name__}).")
|
| 280 |
+
|
| 281 |
+
|
| 282 |
+
_BACKENDS: dict[str, Backend] = {}
|
| 283 |
+
|
| 284 |
+
|
| 285 |
+
def get_backend(backend_id: str) -> Backend:
|
| 286 |
+
"""Return the shared stateless backend instance for ``backend_id``."""
|
| 287 |
+
if backend_id not in _BACKENDS:
|
| 288 |
+
if backend_id == "anthropic":
|
| 289 |
+
_BACKENDS[backend_id] = AnthropicBackend()
|
| 290 |
+
elif backend_id == "hf":
|
| 291 |
+
_BACKENDS[backend_id] = HFInferenceBackend()
|
| 292 |
+
elif backend_id == "openai":
|
| 293 |
+
_BACKENDS[backend_id] = OpenAICompatibleBackend()
|
| 294 |
+
elif backend_id == "zerogpu":
|
| 295 |
+
from skills_cloud.zerogpu import ZeroGPUBackend
|
| 296 |
+
|
| 297 |
+
_BACKENDS[backend_id] = ZeroGPUBackend()
|
| 298 |
+
else:
|
| 299 |
+
raise KeyError(f"Unknown backend: {backend_id!r}")
|
| 300 |
+
return _BACKENDS[backend_id]
|
src/skills_cloud/github.py
ADDED
|
@@ -0,0 +1,301 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""Fetch skill packages from a public GitHub repository at runtime.
|
| 2 |
+
|
| 3 |
+
Primary path: GitHub Trees API lists the repo, then only SKILL.md files are
|
| 4 |
+
downloaded — repo size is irrelevant. Fallback (API rate-limited/truncated):
|
| 5 |
+
one codeload tarball request, size-capped. No git binary, nothing written to
|
| 6 |
+
disk. Remote SKILL.md files are untrusted input: they run through the same
|
| 7 |
+
parse_skill validation as bundled skills (which already rejects URL-shaped
|
| 8 |
+
model ids), sizes and counts are capped, and one bad file never kills a load.
|
| 9 |
+
"""
|
| 10 |
+
|
| 11 |
+
from __future__ import annotations
|
| 12 |
+
|
| 13 |
+
import re
|
| 14 |
+
import tarfile
|
| 15 |
+
from dataclasses import dataclass, replace
|
| 16 |
+
from io import BytesIO
|
| 17 |
+
from pathlib import Path
|
| 18 |
+
|
| 19 |
+
import httpx
|
| 20 |
+
|
| 21 |
+
from skills_cloud.infer import declares_io, make_inferred_spec
|
| 22 |
+
from skills_cloud.skill import Catalog, SkillFailure, SkillSpec, parse_skill
|
| 23 |
+
|
| 24 |
+
MAX_TARBALL_BYTES = 200 * 1024 * 1024 # fallback path only; the API path has no repo-size limit
|
| 25 |
+
MAX_SKILL_FILE_BYTES = 256 * 1024 # one SKILL.md
|
| 26 |
+
MAX_SKILLS_PER_REPO = 100
|
| 27 |
+
FETCH_TIMEOUT_SECONDS = 30.0
|
| 28 |
+
|
| 29 |
+
_OWNER_RE = re.compile(r"[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?")
|
| 30 |
+
_REPO_RE = re.compile(r"[A-Za-z0-9._-]+")
|
| 31 |
+
_SHORTHAND_RE = re.compile(rf"({_OWNER_RE.pattern})/({_REPO_RE.pattern})(?:@([\w./-]+))?", re.ASCII)
|
| 32 |
+
|
| 33 |
+
|
| 34 |
+
class RepoRefError(ValueError):
|
| 35 |
+
"""The user-supplied repo reference could not be understood."""
|
| 36 |
+
|
| 37 |
+
|
| 38 |
+
@dataclass(frozen=True, slots=True)
|
| 39 |
+
class RepoRef:
|
| 40 |
+
owner: str
|
| 41 |
+
repo: str
|
| 42 |
+
ref: str = "HEAD" # branch, tag, or commit; HEAD = default branch
|
| 43 |
+
subpath: str = "" # only load SKILL.md under this prefix
|
| 44 |
+
|
| 45 |
+
@property
|
| 46 |
+
def display(self) -> str:
|
| 47 |
+
suffix = f"@{self.ref}" if self.ref != "HEAD" else ""
|
| 48 |
+
return f"{self.owner}/{self.repo}{suffix}"
|
| 49 |
+
|
| 50 |
+
@property
|
| 51 |
+
def tarball_url(self) -> str:
|
| 52 |
+
return f"https://codeload.github.com/{self.owner}/{self.repo}/tar.gz/{self.ref}"
|
| 53 |
+
|
| 54 |
+
|
| 55 |
+
def parse_repo_ref(text: str) -> RepoRef:
|
| 56 |
+
"""Accepts 'owner/repo', 'owner/repo@ref', and github.com URLs
|
| 57 |
+
(including /tree/<branch>/<subpath> deep links)."""
|
| 58 |
+
text = text.strip().rstrip("/")
|
| 59 |
+
if not text:
|
| 60 |
+
raise RepoRefError("Enter a GitHub repository, e.g. 'owner/repo' or a github.com URL.")
|
| 61 |
+
|
| 62 |
+
cleaned = re.sub(r"^(https?://)?(www\.)?github\.com/", "", text)
|
| 63 |
+
if cleaned != text: # it was a URL — may carry /tree/<ref>/<subpath>
|
| 64 |
+
parts = cleaned.split("/")
|
| 65 |
+
if len(parts) < 2:
|
| 66 |
+
raise RepoRefError(f"{text!r} does not look like a GitHub repository.")
|
| 67 |
+
owner, repo = parts[0], parts[1].removesuffix(".git")
|
| 68 |
+
ref, subpath = "HEAD", ""
|
| 69 |
+
if len(parts) >= 4 and parts[2] in ("tree", "blob"):
|
| 70 |
+
ref = parts[3]
|
| 71 |
+
subpath = "/".join(parts[4:])
|
| 72 |
+
elif len(parts) > 2:
|
| 73 |
+
raise RepoRefError(
|
| 74 |
+
f"Unsupported GitHub URL path {'/'.join(parts[2:])!r} — "
|
| 75 |
+
"use the repo root or a /tree/<branch> link."
|
| 76 |
+
)
|
| 77 |
+
else:
|
| 78 |
+
match = _SHORTHAND_RE.fullmatch(cleaned)
|
| 79 |
+
if match is None:
|
| 80 |
+
raise RepoRefError(
|
| 81 |
+
f"{text!r} does not look like a GitHub repository. "
|
| 82 |
+
"Use 'owner/repo', 'owner/repo@branch', or a github.com URL."
|
| 83 |
+
)
|
| 84 |
+
owner, repo, ref = match.group(1), match.group(2).removesuffix(".git"), match.group(3)
|
| 85 |
+
ref, subpath = ref or "HEAD", ""
|
| 86 |
+
|
| 87 |
+
if not _OWNER_RE.fullmatch(owner) or not _REPO_RE.fullmatch(repo):
|
| 88 |
+
raise RepoRefError(f"{text!r} does not look like a GitHub repository.")
|
| 89 |
+
return RepoRef(owner=owner, repo=repo, ref=ref, subpath=subpath.strip("/"))
|
| 90 |
+
|
| 91 |
+
|
| 92 |
+
def fetch_skills(ref: RepoRef) -> Catalog:
|
| 93 |
+
"""Fetch every SKILL.md from the repo — without downloading the repo.
|
| 94 |
+
|
| 95 |
+
Primary path: one GitHub Trees API call lists the file paths, then only
|
| 96 |
+
the SKILL.md files themselves are downloaded (repo size is irrelevant —
|
| 97 |
+
a 179 MB asset repo with one 1.5 KB skill transfers 1.5 KB). Fallback
|
| 98 |
+
when the API is unavailable (rate-limited, truncated listing): the
|
| 99 |
+
codeload tarball, size-capped. Failure isolation mirrors load_catalog;
|
| 100 |
+
network problems raise RepoRefError with a readable message.
|
| 101 |
+
"""
|
| 102 |
+
entries = _try_list_skill_files(ref)
|
| 103 |
+
if entries is not None:
|
| 104 |
+
return _fetch_listed_files(entries, ref)
|
| 105 |
+
data = _download_tarball(ref)
|
| 106 |
+
return _extract_catalog(data, ref)
|
| 107 |
+
|
| 108 |
+
|
| 109 |
+
def _try_list_skill_files(ref: RepoRef) -> list[tuple[str, int]] | None:
|
| 110 |
+
"""SKILL.md (path, size) entries via the Trees API, or None to fall back.
|
| 111 |
+
|
| 112 |
+
404 is authoritative (repo/ref does not exist) and raises; everything
|
| 113 |
+
else that goes wrong (rate limit, truncation, network) returns None so
|
| 114 |
+
the tarball path gets a chance.
|
| 115 |
+
"""
|
| 116 |
+
url = f"https://api.github.com/repos/{ref.owner}/{ref.repo}/git/trees/{ref.ref}?recursive=1"
|
| 117 |
+
try:
|
| 118 |
+
response = httpx.get(
|
| 119 |
+
url,
|
| 120 |
+
timeout=FETCH_TIMEOUT_SECONDS,
|
| 121 |
+
follow_redirects=True,
|
| 122 |
+
headers={"Accept": "application/vnd.github+json"},
|
| 123 |
+
)
|
| 124 |
+
except httpx.HTTPError:
|
| 125 |
+
return None
|
| 126 |
+
if response.status_code == 404:
|
| 127 |
+
raise RepoRefError(
|
| 128 |
+
f"GitHub returned 404 for {ref.display} — the repository (or ref) "
|
| 129 |
+
"does not exist or is private."
|
| 130 |
+
)
|
| 131 |
+
if response.status_code != 200:
|
| 132 |
+
return None # rate-limited or transient — tarball fallback
|
| 133 |
+
try:
|
| 134 |
+
data = response.json()
|
| 135 |
+
except ValueError:
|
| 136 |
+
return None
|
| 137 |
+
if data.get("truncated"):
|
| 138 |
+
return None # listing incomplete for huge trees — tarball sees everything
|
| 139 |
+
return [
|
| 140 |
+
(entry["path"], int(entry.get("size", 0)))
|
| 141 |
+
for entry in data.get("tree", [])
|
| 142 |
+
if entry.get("type") == "blob" and Path(entry["path"]).name == "SKILL.md"
|
| 143 |
+
]
|
| 144 |
+
|
| 145 |
+
|
| 146 |
+
def _fetch_listed_files(entries: list[tuple[str, int]], ref: RepoRef) -> Catalog:
|
| 147 |
+
skills: list[SkillSpec] = []
|
| 148 |
+
failures: list[SkillFailure] = []
|
| 149 |
+
seen_slugs: set[str] = set()
|
| 150 |
+
for path_str, size in entries:
|
| 151 |
+
relative = Path(path_str)
|
| 152 |
+
if not _in_subpath(relative, ref):
|
| 153 |
+
continue
|
| 154 |
+
slug = _slug_for(relative, ref, seen_slugs)
|
| 155 |
+
if len(skills) + len(failures) >= MAX_SKILLS_PER_REPO:
|
| 156 |
+
failures.append(
|
| 157 |
+
SkillFailure(
|
| 158 |
+
slug, relative, f"skipped: more than {MAX_SKILLS_PER_REPO} skills in repo"
|
| 159 |
+
)
|
| 160 |
+
)
|
| 161 |
+
break
|
| 162 |
+
if size > MAX_SKILL_FILE_BYTES:
|
| 163 |
+
failures.append(
|
| 164 |
+
SkillFailure(slug, relative, f"SKILL.md exceeds {MAX_SKILL_FILE_BYTES // 1024} KB")
|
| 165 |
+
)
|
| 166 |
+
continue
|
| 167 |
+
raw_url = f"https://raw.githubusercontent.com/{ref.owner}/{ref.repo}/{ref.ref}/{path_str}"
|
| 168 |
+
try:
|
| 169 |
+
response = httpx.get(raw_url, timeout=FETCH_TIMEOUT_SECONDS, follow_redirects=True)
|
| 170 |
+
if response.status_code != 200:
|
| 171 |
+
failures.append(
|
| 172 |
+
SkillFailure(slug, relative, f"download failed (HTTP {response.status_code})")
|
| 173 |
+
)
|
| 174 |
+
continue
|
| 175 |
+
_ingest_file(relative, response.content, ref, seen_slugs, skills, failures)
|
| 176 |
+
except httpx.HTTPError as exc:
|
| 177 |
+
failures.append(SkillFailure(slug, relative, f"download failed ({type(exc).__name__})"))
|
| 178 |
+
skills.sort(key=lambda s: (s.slug.casefold(), s.slug))
|
| 179 |
+
return Catalog(tuple(skills), tuple(failures))
|
| 180 |
+
|
| 181 |
+
|
| 182 |
+
def _in_subpath(relative: Path, ref: RepoRef) -> bool:
|
| 183 |
+
if not ref.subpath:
|
| 184 |
+
return True
|
| 185 |
+
rel_dir = relative.parent.as_posix()
|
| 186 |
+
return rel_dir == ref.subpath or rel_dir.startswith(ref.subpath + "/")
|
| 187 |
+
|
| 188 |
+
|
| 189 |
+
def _ingest_file(
|
| 190 |
+
relative: Path,
|
| 191 |
+
raw: bytes,
|
| 192 |
+
ref: RepoRef,
|
| 193 |
+
seen_slugs: set[str],
|
| 194 |
+
skills: list[SkillSpec],
|
| 195 |
+
failures: list[SkillFailure],
|
| 196 |
+
) -> None:
|
| 197 |
+
slug = _slug_for(relative, ref, seen_slugs)
|
| 198 |
+
try:
|
| 199 |
+
text = raw.decode("utf-8-sig")
|
| 200 |
+
spec = parse_skill(slug, text)
|
| 201 |
+
if not declares_io(text):
|
| 202 |
+
# Ported Claude Code skill: guess the output kind and add
|
| 203 |
+
# universal optional inputs (user-editable in UI).
|
| 204 |
+
spec = make_inferred_spec(spec)
|
| 205 |
+
skills.append(replace(spec, source=ref.display))
|
| 206 |
+
seen_slugs.add(slug)
|
| 207 |
+
except Exception as exc: # same isolation contract as load_catalog
|
| 208 |
+
failures.append(SkillFailure(slug, relative, _failure_message(exc)))
|
| 209 |
+
|
| 210 |
+
|
| 211 |
+
def _download_tarball(ref: RepoRef) -> bytes:
|
| 212 |
+
try:
|
| 213 |
+
with httpx.stream(
|
| 214 |
+
"GET", ref.tarball_url, timeout=FETCH_TIMEOUT_SECONDS, follow_redirects=True
|
| 215 |
+
) as response:
|
| 216 |
+
if response.status_code == 404:
|
| 217 |
+
raise RepoRefError(
|
| 218 |
+
f"GitHub returned 404 for {ref.display} — the repository (or ref) "
|
| 219 |
+
"does not exist or is private."
|
| 220 |
+
)
|
| 221 |
+
if response.status_code != 200:
|
| 222 |
+
raise RepoRefError(
|
| 223 |
+
f"GitHub returned HTTP {response.status_code} for {ref.display}."
|
| 224 |
+
)
|
| 225 |
+
chunks: list[bytes] = []
|
| 226 |
+
total = 0
|
| 227 |
+
for chunk in response.iter_bytes():
|
| 228 |
+
total += len(chunk)
|
| 229 |
+
if total > MAX_TARBALL_BYTES:
|
| 230 |
+
raise RepoRefError(
|
| 231 |
+
f"{ref.display} archive exceeds "
|
| 232 |
+
f"{MAX_TARBALL_BYTES // (1024 * 1024)} MB and the GitHub file "
|
| 233 |
+
"listing API was unavailable (likely rate-limited). Try again "
|
| 234 |
+
"in a few minutes, or load a /tree/<branch>/<subdir> deep link."
|
| 235 |
+
)
|
| 236 |
+
chunks.append(chunk)
|
| 237 |
+
return b"".join(chunks)
|
| 238 |
+
except RepoRefError:
|
| 239 |
+
raise
|
| 240 |
+
except httpx.HTTPError as exc:
|
| 241 |
+
raise RepoRefError(
|
| 242 |
+
f"Could not reach GitHub for {ref.display}: {type(exc).__name__}."
|
| 243 |
+
) from exc
|
| 244 |
+
|
| 245 |
+
|
| 246 |
+
def _extract_catalog(data: bytes, ref: RepoRef) -> Catalog:
|
| 247 |
+
skills: list[SkillSpec] = []
|
| 248 |
+
failures: list[SkillFailure] = []
|
| 249 |
+
seen_slugs: set[str] = set()
|
| 250 |
+
try:
|
| 251 |
+
with tarfile.open(fileobj=BytesIO(data), mode="r:gz") as archive:
|
| 252 |
+
for member in archive:
|
| 253 |
+
if not member.isfile():
|
| 254 |
+
continue
|
| 255 |
+
# First path component is the "<repo>-<sha>/" prefix codeload adds.
|
| 256 |
+
relative = Path(*Path(member.name).parts[1:])
|
| 257 |
+
if relative.name != "SKILL.md":
|
| 258 |
+
continue
|
| 259 |
+
if not _in_subpath(relative, ref):
|
| 260 |
+
continue
|
| 261 |
+
slug = _slug_for(relative, ref, seen_slugs)
|
| 262 |
+
if len(skills) + len(failures) >= MAX_SKILLS_PER_REPO:
|
| 263 |
+
failures.append(
|
| 264 |
+
SkillFailure(
|
| 265 |
+
slug,
|
| 266 |
+
relative,
|
| 267 |
+
f"skipped: more than {MAX_SKILLS_PER_REPO} skills in repo",
|
| 268 |
+
)
|
| 269 |
+
)
|
| 270 |
+
break
|
| 271 |
+
if member.size > MAX_SKILL_FILE_BYTES:
|
| 272 |
+
failures.append(
|
| 273 |
+
SkillFailure(
|
| 274 |
+
slug, relative, f"SKILL.md exceeds {MAX_SKILL_FILE_BYTES // 1024} KB"
|
| 275 |
+
)
|
| 276 |
+
)
|
| 277 |
+
continue
|
| 278 |
+
handle = archive.extractfile(member)
|
| 279 |
+
if handle is None:
|
| 280 |
+
continue
|
| 281 |
+
_ingest_file(relative, handle.read(), ref, seen_slugs, skills, failures)
|
| 282 |
+
except tarfile.TarError as exc:
|
| 283 |
+
raise RepoRefError(f"GitHub response for {ref.display} was not a valid archive.") from exc
|
| 284 |
+
skills.sort(key=lambda s: (s.slug.casefold(), s.slug))
|
| 285 |
+
return Catalog(tuple(skills), tuple(failures))
|
| 286 |
+
|
| 287 |
+
|
| 288 |
+
def _slug_for(relative: Path, ref: RepoRef, seen: set[str]) -> str:
|
| 289 |
+
parent = relative.parent
|
| 290 |
+
slug = parent.name or ref.repo # SKILL.md at repo root -> repo name
|
| 291 |
+
if slug in seen: # same dir name in two groups -> disambiguate with full path
|
| 292 |
+
slug = parent.as_posix().replace("/", "-") or ref.repo
|
| 293 |
+
return slug
|
| 294 |
+
|
| 295 |
+
|
| 296 |
+
def _failure_message(exc: Exception) -> str:
|
| 297 |
+
from skills_cloud.skill import SkillValidationError
|
| 298 |
+
|
| 299 |
+
if isinstance(exc, SkillValidationError):
|
| 300 |
+
return "; ".join(exc.errors)
|
| 301 |
+
return f"{type(exc).__name__}: {exc}"
|
src/skills_cloud/infer.py
ADDED
|
@@ -0,0 +1,130 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""Heuristic kind inference for ported skills (no declared inputs/output).
|
| 2 |
+
|
| 3 |
+
Keyword heuristics guess wrong sometimes (a p5.js "generative art" skill
|
| 4 |
+
outputs CODE, not an image) — so inference only picks the DEFAULT. The UI
|
| 5 |
+
shows inferred skills with an editable output selector, and whether the run
|
| 6 |
+
uses vision / image-to-image is decided by whether the user actually uploads
|
| 7 |
+
an image. Inferred specs always get an optional image upload and an optional
|
| 8 |
+
free-text request field so any ported skill is immediately usable.
|
| 9 |
+
"""
|
| 10 |
+
|
| 11 |
+
from __future__ import annotations
|
| 12 |
+
|
| 13 |
+
import re
|
| 14 |
+
from dataclasses import replace
|
| 15 |
+
|
| 16 |
+
import yaml
|
| 17 |
+
|
| 18 |
+
from skills_cloud.skill import _FRONTMATTER_RE, DEFAULT_MODELS, InputSpec, SkillSpec
|
| 19 |
+
|
| 20 |
+
# Signals that the skill PRODUCES an image. Deliberately conservative.
|
| 21 |
+
_IMAGE_OUT_HINTS = (
|
| 22 |
+
"generate an image",
|
| 23 |
+
"generate images",
|
| 24 |
+
"image generation",
|
| 25 |
+
"text-to-image",
|
| 26 |
+
"illustration",
|
| 27 |
+
"illustrations",
|
| 28 |
+
"drawing",
|
| 29 |
+
"sticker",
|
| 30 |
+
"artwork",
|
| 31 |
+
"wallpaper",
|
| 32 |
+
"poster",
|
| 33 |
+
"生图",
|
| 34 |
+
"生成图片",
|
| 35 |
+
"插画",
|
| 36 |
+
"画一",
|
| 37 |
+
)
|
| 38 |
+
# Signals that the skill produces text/code even when art words appear.
|
| 39 |
+
_TEXT_OUT_OVERRIDES = (
|
| 40 |
+
"code",
|
| 41 |
+
"p5.js",
|
| 42 |
+
"svg",
|
| 43 |
+
"html",
|
| 44 |
+
"css",
|
| 45 |
+
"javascript",
|
| 46 |
+
"typescript",
|
| 47 |
+
"python",
|
| 48 |
+
"script",
|
| 49 |
+
"markdown",
|
| 50 |
+
"document",
|
| 51 |
+
"essay",
|
| 52 |
+
"copy",
|
| 53 |
+
"写作",
|
| 54 |
+
"文案",
|
| 55 |
+
"代码",
|
| 56 |
+
)
|
| 57 |
+
|
| 58 |
+
REQUEST_INPUT = InputSpec(
|
| 59 |
+
name="request",
|
| 60 |
+
type="textarea",
|
| 61 |
+
label="Your request",
|
| 62 |
+
required=False,
|
| 63 |
+
default="",
|
| 64 |
+
placeholder="Optional — appended to the skill's instructions",
|
| 65 |
+
options=(),
|
| 66 |
+
)
|
| 67 |
+
IMAGE_INPUT = InputSpec(
|
| 68 |
+
name="image",
|
| 69 |
+
type="image",
|
| 70 |
+
label="Image (optional)",
|
| 71 |
+
required=False,
|
| 72 |
+
default="",
|
| 73 |
+
placeholder="",
|
| 74 |
+
options=(),
|
| 75 |
+
)
|
| 76 |
+
|
| 77 |
+
|
| 78 |
+
def declares_io(text: str) -> bool:
|
| 79 |
+
"""True when the SKILL.md frontmatter explicitly declares inputs or output."""
|
| 80 |
+
match = _FRONTMATTER_RE.match(text.lstrip("").replace("\r\n", "\n"))
|
| 81 |
+
if match is None:
|
| 82 |
+
return False
|
| 83 |
+
try:
|
| 84 |
+
front = yaml.safe_load(match.group(1))
|
| 85 |
+
except yaml.YAMLError:
|
| 86 |
+
return False
|
| 87 |
+
return isinstance(front, dict) and ("output" in front or "inputs" in front)
|
| 88 |
+
|
| 89 |
+
|
| 90 |
+
def _count_hits(corpus: str, hints: tuple[str, ...]) -> int:
|
| 91 |
+
"""Count hint matches. ASCII hints match on word boundaries so 'copy'
|
| 92 |
+
does not fire inside 'copying'; CJK hints match as substrings."""
|
| 93 |
+
count = 0
|
| 94 |
+
for hint in hints:
|
| 95 |
+
if hint.isascii():
|
| 96 |
+
if re.search(rf"(?<![a-z0-9]){re.escape(hint)}(?![a-z0-9])", corpus):
|
| 97 |
+
count += 1
|
| 98 |
+
elif hint in corpus:
|
| 99 |
+
count += 1
|
| 100 |
+
return count
|
| 101 |
+
|
| 102 |
+
|
| 103 |
+
def infer_output(spec: SkillSpec) -> str:
|
| 104 |
+
"""Guess whether a ported skill produces text or an image.
|
| 105 |
+
|
| 106 |
+
Score-based: a lone stray word must not override a pile of opposite
|
| 107 |
+
evidence. Ties (including zero evidence) default to text.
|
| 108 |
+
"""
|
| 109 |
+
corpus = f"{spec.name}\n{spec.description}\n{spec.body[:2000]}".lower()
|
| 110 |
+
image_hits = _count_hits(corpus, _IMAGE_OUT_HINTS)
|
| 111 |
+
text_hits = _count_hits(corpus, _TEXT_OUT_OVERRIDES)
|
| 112 |
+
return "image" if image_hits > text_hits else "text"
|
| 113 |
+
|
| 114 |
+
|
| 115 |
+
def make_inferred_spec(spec: SkillSpec) -> SkillSpec:
|
| 116 |
+
"""Rewrite a ported spec: guessed output, universal optional inputs.
|
| 117 |
+
|
| 118 |
+
The image upload is always present (optional); at run time an uploaded
|
| 119 |
+
image switches text→vision or text-to-image→image-to-image automatically.
|
| 120 |
+
"""
|
| 121 |
+
output = infer_output(spec)
|
| 122 |
+
kind = "image_gen" if output == "image" else "text"
|
| 123 |
+
return replace(
|
| 124 |
+
spec,
|
| 125 |
+
output=output,
|
| 126 |
+
inputs=(IMAGE_INPUT, REQUEST_INPUT),
|
| 127 |
+
models=dict(DEFAULT_MODELS[kind]),
|
| 128 |
+
inferred=True,
|
| 129 |
+
warnings=(), # inference-added inputs must not trigger authoring warnings
|
| 130 |
+
)
|
src/skills_cloud/models_hub.py
ADDED
|
@@ -0,0 +1,77 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""Live model discovery from the Hugging Face Hub — no hardcoded model lists.
|
| 2 |
+
|
| 3 |
+
``list_models`` is a public endpoint (no token needed). Results are cached
|
| 4 |
+
per kind for an hour; any failure falls back to the pinned defaults so the
|
| 5 |
+
app never blocks on Hub availability. The pinned defaults stay the SELECTED
|
| 6 |
+
value because trending lists routinely contain gated models (e.g. FLUX.1-dev)
|
| 7 |
+
that would 403 a fresh token — discovery widens the menu, it does not pick.
|
| 8 |
+
"""
|
| 9 |
+
|
| 10 |
+
from __future__ import annotations
|
| 11 |
+
|
| 12 |
+
import time
|
| 13 |
+
|
| 14 |
+
from skills_cloud.skill import DEFAULT_MODELS
|
| 15 |
+
|
| 16 |
+
KIND_PIPELINES = {
|
| 17 |
+
"text": "text-generation",
|
| 18 |
+
"vision": "image-text-to-text",
|
| 19 |
+
"image_gen": "text-to-image",
|
| 20 |
+
"image_edit": "image-to-image",
|
| 21 |
+
}
|
| 22 |
+
|
| 23 |
+
# Anthropic's /v1/models endpoint requires an API key, which we do not have at
|
| 24 |
+
# UI-build time — so these are a static seed, and the dropdown accepts any
|
| 25 |
+
# custom id. Revisit if a keyless catalog endpoint appears.
|
| 26 |
+
ANTHROPIC_MODEL_CHOICES: tuple[str, ...] = (
|
| 27 |
+
"claude-opus-5",
|
| 28 |
+
"claude-sonnet-5",
|
| 29 |
+
"claude-haiku-4-5-20251001",
|
| 30 |
+
)
|
| 31 |
+
|
| 32 |
+
_TTL_SECONDS = 3600.0
|
| 33 |
+
_cache: dict[str, tuple[float, tuple[tuple[str, str], ...]]] = {}
|
| 34 |
+
|
| 35 |
+
|
| 36 |
+
def _format_count(n: int) -> str:
|
| 37 |
+
if n >= 1_000_000:
|
| 38 |
+
return f"{n / 1e6:.1f}M"
|
| 39 |
+
if n >= 1_000:
|
| 40 |
+
return f"{n / 1e3:.1f}k"
|
| 41 |
+
return str(n)
|
| 42 |
+
|
| 43 |
+
|
| 44 |
+
def hub_model_choices(kind: str, limit: int = 12) -> list[tuple[str, str]]:
|
| 45 |
+
"""Trending Hub models for this kind as (label, value) dropdown pairs.
|
| 46 |
+
|
| 47 |
+
Labels carry the Hub like-count ("owner/name · ★ 1.2k") for quick
|
| 48 |
+
comparison; values stay bare model ids.
|
| 49 |
+
"""
|
| 50 |
+
cached = _cache.get(kind)
|
| 51 |
+
now = time.monotonic()
|
| 52 |
+
if cached and now - cached[0] < _TTL_SECONDS:
|
| 53 |
+
return list(cached[1])
|
| 54 |
+
try:
|
| 55 |
+
from huggingface_hub import list_models
|
| 56 |
+
|
| 57 |
+
choices = [
|
| 58 |
+
(f"{model.id} · ★ {_format_count(model.likes or 0)}", model.id)
|
| 59 |
+
for model in list_models(
|
| 60 |
+
pipeline_tag=KIND_PIPELINES[kind],
|
| 61 |
+
inference_provider="all",
|
| 62 |
+
sort="trending_score",
|
| 63 |
+
limit=limit,
|
| 64 |
+
)
|
| 65 |
+
]
|
| 66 |
+
except Exception: # offline/Hub down: the pinned default still works
|
| 67 |
+
choices = []
|
| 68 |
+
default = DEFAULT_MODELS.get(kind, {}).get("hf")
|
| 69 |
+
if default and default not in [value for _, value in choices]:
|
| 70 |
+
choices.insert(0, (default, default))
|
| 71 |
+
if choices:
|
| 72 |
+
_cache[kind] = (now, tuple(choices))
|
| 73 |
+
return choices
|
| 74 |
+
|
| 75 |
+
|
| 76 |
+
def anthropic_model_choices() -> list[str]:
|
| 77 |
+
return list(ANTHROPIC_MODEL_CHOICES)
|
src/skills_cloud/runner.py
ADDED
|
@@ -0,0 +1,90 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""Skill execution: Gradio-free functions binding SkillSpec to a Backend.
|
| 2 |
+
|
| 3 |
+
``run_text_skill`` yields ACCUMULATED text, not deltas — Gradio replaces the
|
| 4 |
+
output component on every yield, so each yielded item must be the full text
|
| 5 |
+
so far. The UI layer only binds these functions to events.
|
| 6 |
+
"""
|
| 7 |
+
|
| 8 |
+
from __future__ import annotations
|
| 9 |
+
|
| 10 |
+
from collections.abc import Iterator
|
| 11 |
+
from typing import TYPE_CHECKING, Any
|
| 12 |
+
|
| 13 |
+
from skills_cloud.backends import (
|
| 14 |
+
DEFAULT_MAX_TOKENS,
|
| 15 |
+
FALLBACK_MAX_TOKENS,
|
| 16 |
+
Backend,
|
| 17 |
+
ProviderError,
|
| 18 |
+
TextRequest,
|
| 19 |
+
UnsupportedOperationError,
|
| 20 |
+
)
|
| 21 |
+
from skills_cloud.skill import (
|
| 22 |
+
SkillSpec,
|
| 23 |
+
collect_images,
|
| 24 |
+
render_prompt,
|
| 25 |
+
resolve_values,
|
| 26 |
+
validate_model_id,
|
| 27 |
+
)
|
| 28 |
+
|
| 29 |
+
if TYPE_CHECKING:
|
| 30 |
+
from PIL import Image
|
| 31 |
+
|
| 32 |
+
|
| 33 |
+
def resolve_model(spec: SkillSpec, backend_id: str) -> str:
|
| 34 |
+
"""Model for this spec+backend; spec.models is pre-filled with defaults."""
|
| 35 |
+
model = spec.models.get(backend_id)
|
| 36 |
+
if not model:
|
| 37 |
+
raise UnsupportedOperationError(
|
| 38 |
+
f"Skill '{spec.name}' cannot run on backend {backend_id!r}."
|
| 39 |
+
)
|
| 40 |
+
return model
|
| 41 |
+
|
| 42 |
+
|
| 43 |
+
def run_text_skill(
|
| 44 |
+
spec: SkillSpec,
|
| 45 |
+
values: dict[str, Any],
|
| 46 |
+
backend: Backend,
|
| 47 |
+
model: str,
|
| 48 |
+
api_key: str,
|
| 49 |
+
base_url: str | None = None,
|
| 50 |
+
) -> Iterator[str]:
|
| 51 |
+
"""Validate inputs, render the prompt, stream accumulated text.
|
| 52 |
+
|
| 53 |
+
Zero deltas from the provider (e.g. a refusal with no text) raises
|
| 54 |
+
ProviderError instead of silently rendering an empty output box.
|
| 55 |
+
"""
|
| 56 |
+
model = validate_model_id(model)
|
| 57 |
+
resolved = resolve_values(spec, values)
|
| 58 |
+
images = collect_images(spec, values)
|
| 59 |
+
prompt = render_prompt(spec, resolved)
|
| 60 |
+
req = TextRequest(
|
| 61 |
+
user=prompt,
|
| 62 |
+
model=model,
|
| 63 |
+
max_tokens=DEFAULT_MAX_TOKENS.get(backend.id, FALLBACK_MAX_TOKENS),
|
| 64 |
+
images=images,
|
| 65 |
+
base_url=base_url,
|
| 66 |
+
)
|
| 67 |
+
accumulated = ""
|
| 68 |
+
for delta in backend.stream_text(req, api_key=api_key):
|
| 69 |
+
accumulated += delta
|
| 70 |
+
yield accumulated
|
| 71 |
+
if not accumulated:
|
| 72 |
+
raise ProviderError("The model returned no text.")
|
| 73 |
+
|
| 74 |
+
|
| 75 |
+
def run_image_skill(
|
| 76 |
+
spec: SkillSpec,
|
| 77 |
+
values: dict[str, Any],
|
| 78 |
+
backend: Backend,
|
| 79 |
+
model: str,
|
| 80 |
+
api_key: str,
|
| 81 |
+
) -> Image.Image:
|
| 82 |
+
if not backend.supports_image:
|
| 83 |
+
raise UnsupportedOperationError(f"{backend.label} does not support image generation.")
|
| 84 |
+
model = validate_model_id(model)
|
| 85 |
+
resolved = resolve_values(spec, values)
|
| 86 |
+
images = collect_images(spec, values)
|
| 87 |
+
prompt = render_prompt(spec, resolved)
|
| 88 |
+
# An uploaded image switches text-to-image to image-to-image.
|
| 89 |
+
source = images[0] if images else None
|
| 90 |
+
return backend.generate_image(prompt, model=model, api_key=api_key, image=source)
|
src/skills_cloud/skill.py
ADDED
|
@@ -0,0 +1,506 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""SKILL.md parsing, validation, prompt rendering, and catalog loading.
|
| 2 |
+
|
| 3 |
+
Design record: docs/design/m1-skillspec.md. This module is pure: no SDK
|
| 4 |
+
imports, no Gradio imports, no network. File I/O happens only in
|
| 5 |
+
``load_catalog``.
|
| 6 |
+
"""
|
| 7 |
+
|
| 8 |
+
from __future__ import annotations
|
| 9 |
+
|
| 10 |
+
import difflib
|
| 11 |
+
import re
|
| 12 |
+
from dataclasses import dataclass
|
| 13 |
+
from pathlib import Path
|
| 14 |
+
from typing import Any, Literal
|
| 15 |
+
|
| 16 |
+
import yaml
|
| 17 |
+
|
| 18 |
+
InputType = Literal["text", "textarea", "select", "image"]
|
| 19 |
+
OutputKind = Literal["text", "image"]
|
| 20 |
+
|
| 21 |
+
BACKEND_IDS: tuple[str, ...] = ("anthropic", "hf", "openai")
|
| 22 |
+
|
| 23 |
+
# A skill's kind is derived from (output, has image input):
|
| 24 |
+
# text text out, no image in chat
|
| 25 |
+
# vision text out, image in chat with image content
|
| 26 |
+
# image_gen image out, no image in text-to-image
|
| 27 |
+
# image_edit image out, image in image-to-image
|
| 28 |
+
# Defaults are deliberately non-gated models: the zero-config path for a fresh
|
| 29 |
+
# token must not 403 on a license wall.
|
| 30 |
+
DEFAULT_MODELS: dict[str, dict[str, str]] = {
|
| 31 |
+
"text": {"anthropic": "claude-opus-5", "hf": "Qwen/Qwen2.5-72B-Instruct"},
|
| 32 |
+
"vision": {"anthropic": "claude-opus-5", "hf": "Qwen/Qwen2.5-VL-72B-Instruct"},
|
| 33 |
+
"image_gen": {"hf": "black-forest-labs/FLUX.1-schnell"},
|
| 34 |
+
"image_edit": {"hf": "Qwen/Qwen-Image-Edit"},
|
| 35 |
+
}
|
| 36 |
+
|
| 37 |
+
DEFAULT_EMOJI = "🛠️"
|
| 38 |
+
|
| 39 |
+
INPUT_NAME_RE = re.compile(r"^[a-z][a-z0-9_]*$")
|
| 40 |
+
PLACEHOLDER_RE = re.compile(r"\{\{([a-z][a-z0-9_]*)\}\}")
|
| 41 |
+
# Bare model ids only: 'owner/name', 'model-name', or Ollama-style 'name:tag'.
|
| 42 |
+
# "://" is rejected separately — a URL-shaped "model" would redirect the bearer
|
| 43 |
+
# token to an arbitrary endpoint (credential exfiltration on a public Space).
|
| 44 |
+
MODEL_ID_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._\-/:]*")
|
| 45 |
+
_ANY_BRACES_RE = re.compile(r"\{\{(.*?)\}\}", re.DOTALL)
|
| 46 |
+
_FRONTMATTER_RE = re.compile(r"\A---[ \t]*\n(.*?)\n---[ \t]*(?:\n|\Z)(.*)\Z", re.DOTALL)
|
| 47 |
+
|
| 48 |
+
_INPUT_TYPES: tuple[str, ...] = ("text", "textarea", "select", "image")
|
| 49 |
+
_OUTPUT_KINDS: tuple[str, ...] = ("text", "image")
|
| 50 |
+
_INPUT_KEYS = frozenset({"name", "type", "label", "required", "default", "placeholder", "options"})
|
| 51 |
+
_KNOWN_TOP_KEYS = frozenset({"name", "description", "emoji", "output", "models", "inputs"})
|
| 52 |
+
|
| 53 |
+
|
| 54 |
+
class SkillValidationError(Exception):
|
| 55 |
+
"""A SKILL.md failed validation. Carries every problem found, not just the first."""
|
| 56 |
+
|
| 57 |
+
def __init__(self, slug: str, errors: list[str]):
|
| 58 |
+
self.slug = slug
|
| 59 |
+
self.errors = list(errors)
|
| 60 |
+
super().__init__(f"{slug}: " + "; ".join(self.errors))
|
| 61 |
+
|
| 62 |
+
|
| 63 |
+
class InputValueError(Exception):
|
| 64 |
+
"""A user-supplied value is invalid for the skill's declared inputs."""
|
| 65 |
+
|
| 66 |
+
|
| 67 |
+
@dataclass(frozen=True, slots=True)
|
| 68 |
+
class InputSpec:
|
| 69 |
+
name: str
|
| 70 |
+
type: InputType
|
| 71 |
+
label: str
|
| 72 |
+
required: bool
|
| 73 |
+
default: str
|
| 74 |
+
placeholder: str
|
| 75 |
+
options: tuple[str, ...] # () unless type == "select"
|
| 76 |
+
|
| 77 |
+
|
| 78 |
+
@dataclass(frozen=True, slots=True)
|
| 79 |
+
class SkillSpec:
|
| 80 |
+
slug: str
|
| 81 |
+
name: str
|
| 82 |
+
description: str
|
| 83 |
+
emoji: str
|
| 84 |
+
output: OutputKind
|
| 85 |
+
models: dict[str, str] # backend id -> model id, defaults pre-filled
|
| 86 |
+
inputs: tuple[InputSpec, ...]
|
| 87 |
+
body: str
|
| 88 |
+
warnings: tuple[str, ...]
|
| 89 |
+
source: str = "bundled" # "bundled" or the repo it was loaded from
|
| 90 |
+
inferred: bool = False # True when output/inputs were guessed, not declared
|
| 91 |
+
|
| 92 |
+
@property
|
| 93 |
+
def referenced_inputs(self) -> frozenset[str]:
|
| 94 |
+
return frozenset(PLACEHOLDER_RE.findall(self.body))
|
| 95 |
+
|
| 96 |
+
@property
|
| 97 |
+
def kind(self) -> str:
|
| 98 |
+
return kind_of(self.output, self.inputs)
|
| 99 |
+
|
| 100 |
+
@property
|
| 101 |
+
def image_inputs(self) -> tuple[InputSpec, ...]:
|
| 102 |
+
return tuple(inp for inp in self.inputs if inp.type == "image")
|
| 103 |
+
|
| 104 |
+
def __hash__(self) -> int:
|
| 105 |
+
# The auto-generated hash would choke on the models dict. Gradio's
|
| 106 |
+
# gr.render tracks state via deep_hash(catalog), so SkillSpec (and
|
| 107 |
+
# everything containing it) must stay hashable — and every field must
|
| 108 |
+
# participate, or a field-only change would skip a re-render.
|
| 109 |
+
return hash(
|
| 110 |
+
(
|
| 111 |
+
self.slug,
|
| 112 |
+
self.name,
|
| 113 |
+
self.description,
|
| 114 |
+
self.emoji,
|
| 115 |
+
self.output,
|
| 116 |
+
tuple(sorted(self.models.items())),
|
| 117 |
+
self.inputs,
|
| 118 |
+
self.body,
|
| 119 |
+
self.warnings,
|
| 120 |
+
self.source,
|
| 121 |
+
self.inferred,
|
| 122 |
+
)
|
| 123 |
+
)
|
| 124 |
+
|
| 125 |
+
|
| 126 |
+
def kind_of(output: str, inputs: tuple[InputSpec, ...]) -> str:
|
| 127 |
+
has_image = any(inp.type == "image" for inp in inputs)
|
| 128 |
+
if output == "image":
|
| 129 |
+
return "image_edit" if has_image else "image_gen"
|
| 130 |
+
return "vision" if has_image else "text"
|
| 131 |
+
|
| 132 |
+
|
| 133 |
+
@dataclass(frozen=True, slots=True)
|
| 134 |
+
class SkillFailure:
|
| 135 |
+
slug: str
|
| 136 |
+
path: Path
|
| 137 |
+
message: str
|
| 138 |
+
|
| 139 |
+
|
| 140 |
+
@dataclass(frozen=True, slots=True)
|
| 141 |
+
class Catalog:
|
| 142 |
+
skills: tuple[SkillSpec, ...]
|
| 143 |
+
failures: tuple[SkillFailure, ...]
|
| 144 |
+
|
| 145 |
+
|
| 146 |
+
def merge_catalogs(base: Catalog, extra: Catalog) -> tuple[Catalog, tuple[str, ...], int]:
|
| 147 |
+
"""Merge extra into base; slugs already present are skipped, not replaced.
|
| 148 |
+
|
| 149 |
+
Returns (merged, added_slugs, skipped_count). Failures accumulate from both.
|
| 150 |
+
"""
|
| 151 |
+
existing = {spec.slug for spec in base.skills}
|
| 152 |
+
added = tuple(spec for spec in extra.skills if spec.slug not in existing)
|
| 153 |
+
skills = tuple(sorted(base.skills + added, key=lambda spec: (spec.slug.casefold(), spec.slug)))
|
| 154 |
+
merged = Catalog(skills, base.failures + extra.failures)
|
| 155 |
+
return merged, tuple(spec.slug for spec in added), len(extra.skills) - len(added)
|
| 156 |
+
|
| 157 |
+
|
| 158 |
+
def parse_skill(slug: str, text: str) -> SkillSpec:
|
| 159 |
+
# Tolerate authoring realities: editors that add a UTF-8 BOM and Windows
|
| 160 |
+
# line endings must not produce a misleading "missing frontmatter" error.
|
| 161 |
+
text = text.lstrip("").replace("\r\n", "\n")
|
| 162 |
+
match = _FRONTMATTER_RE.match(text)
|
| 163 |
+
if match is None:
|
| 164 |
+
raise SkillValidationError(
|
| 165 |
+
slug, ["missing YAML frontmatter (file must start with a '---' fenced block)"]
|
| 166 |
+
)
|
| 167 |
+
try:
|
| 168 |
+
front = yaml.safe_load(match.group(1))
|
| 169 |
+
except yaml.YAMLError as exc:
|
| 170 |
+
detail = "unknown error"
|
| 171 |
+
problem = getattr(exc, "problem", None)
|
| 172 |
+
mark = getattr(exc, "problem_mark", None)
|
| 173 |
+
if problem:
|
| 174 |
+
detail = str(problem)
|
| 175 |
+
if mark is not None:
|
| 176 |
+
detail += f" (frontmatter line {mark.line + 1})"
|
| 177 |
+
elif str(exc).strip():
|
| 178 |
+
detail = str(exc).strip().splitlines()[0]
|
| 179 |
+
raise SkillValidationError(slug, [f"invalid YAML in frontmatter: {detail}"]) from exc
|
| 180 |
+
if not isinstance(front, dict):
|
| 181 |
+
raise SkillValidationError(slug, ["frontmatter must be a YAML mapping"])
|
| 182 |
+
|
| 183 |
+
errors: list[str] = []
|
| 184 |
+
warnings: list[str] = []
|
| 185 |
+
|
| 186 |
+
for key in front:
|
| 187 |
+
if not isinstance(key, str) or key in _KNOWN_TOP_KEYS:
|
| 188 |
+
continue
|
| 189 |
+
close = difflib.get_close_matches(key.casefold(), _KNOWN_TOP_KEYS, n=1, cutoff=0.75)
|
| 190 |
+
if close:
|
| 191 |
+
warnings.append(f"unknown key '{key}' — did you mean '{close[0]}'? (ignored)")
|
| 192 |
+
|
| 193 |
+
name = _require_str(front, "name", errors, max_len=64)
|
| 194 |
+
description = _require_str(front, "description", errors)
|
| 195 |
+
|
| 196 |
+
emoji = front.get("emoji", DEFAULT_EMOJI)
|
| 197 |
+
if not isinstance(emoji, str) or not emoji.strip():
|
| 198 |
+
errors.append("'emoji' must be a non-empty string")
|
| 199 |
+
emoji = DEFAULT_EMOJI
|
| 200 |
+
|
| 201 |
+
output = front.get("output", "text")
|
| 202 |
+
if output not in _OUTPUT_KINDS:
|
| 203 |
+
errors.append(f"'output' must be one of {'|'.join(_OUTPUT_KINDS)}, got {output!r}")
|
| 204 |
+
output = "text"
|
| 205 |
+
|
| 206 |
+
inputs = _parse_inputs(front.get("inputs", []), errors)
|
| 207 |
+
models = _parse_models(front.get("models", {}), kind_of(output, inputs), errors)
|
| 208 |
+
|
| 209 |
+
body = match.group(2).strip()
|
| 210 |
+
if not body:
|
| 211 |
+
errors.append("body is required (markdown after the closing '---' fence)")
|
| 212 |
+
|
| 213 |
+
declared = {inp.name for inp in inputs}
|
| 214 |
+
image_names = {inp.name for inp in inputs if inp.type == "image"}
|
| 215 |
+
for placeholder in PLACEHOLDER_RE.findall(body):
|
| 216 |
+
if placeholder not in declared:
|
| 217 |
+
errors.append(
|
| 218 |
+
f"body placeholder '{{{{{placeholder}}}}}' does not match any declared input"
|
| 219 |
+
)
|
| 220 |
+
elif placeholder in image_names:
|
| 221 |
+
errors.append(
|
| 222 |
+
f"body placeholder '{{{{{placeholder}}}}}' refers to an image input — "
|
| 223 |
+
"image inputs cannot be substituted into text"
|
| 224 |
+
)
|
| 225 |
+
for content in _ANY_BRACES_RE.findall(body):
|
| 226 |
+
if not INPUT_NAME_RE.match(content):
|
| 227 |
+
warnings.append(
|
| 228 |
+
f"body contains '{{{{{content}}}}}' which is not a valid input placeholder; "
|
| 229 |
+
"it will be sent to the model as-is"
|
| 230 |
+
)
|
| 231 |
+
referenced = set(PLACEHOLDER_RE.findall(body))
|
| 232 |
+
for inp in inputs:
|
| 233 |
+
if inp.type != "image" and inp.name not in referenced:
|
| 234 |
+
warnings.append(
|
| 235 |
+
f"input '{inp.name}' is not referenced in the body; "
|
| 236 |
+
"its value will be appended to the prompt automatically"
|
| 237 |
+
)
|
| 238 |
+
|
| 239 |
+
if errors:
|
| 240 |
+
raise SkillValidationError(slug, errors)
|
| 241 |
+
return SkillSpec(
|
| 242 |
+
slug=slug,
|
| 243 |
+
name=name,
|
| 244 |
+
description=description,
|
| 245 |
+
emoji=emoji.strip(),
|
| 246 |
+
output=output,
|
| 247 |
+
models=models,
|
| 248 |
+
inputs=inputs,
|
| 249 |
+
body=body,
|
| 250 |
+
warnings=tuple(warnings),
|
| 251 |
+
)
|
| 252 |
+
|
| 253 |
+
|
| 254 |
+
def _require_str(front: dict, key: str, errors: list[str], *, max_len: int | None = None) -> str:
|
| 255 |
+
value = front.get(key)
|
| 256 |
+
if not isinstance(value, str) or not value.strip():
|
| 257 |
+
errors.append(f"'{key}' is required and must be a non-empty string")
|
| 258 |
+
return ""
|
| 259 |
+
value = value.strip()
|
| 260 |
+
if max_len is not None and len(value) > max_len:
|
| 261 |
+
errors.append(f"'{key}' must be at most {max_len} characters")
|
| 262 |
+
return value
|
| 263 |
+
|
| 264 |
+
|
| 265 |
+
def _parse_models(raw: Any, kind: str, errors: list[str]) -> dict[str, str]:
|
| 266 |
+
declared: dict[str, str] = {}
|
| 267 |
+
if not isinstance(raw, dict):
|
| 268 |
+
errors.append("'models' must be a mapping of backend id to model id")
|
| 269 |
+
else:
|
| 270 |
+
for key, value in raw.items():
|
| 271 |
+
if key not in BACKEND_IDS:
|
| 272 |
+
allowed = ", ".join(BACKEND_IDS)
|
| 273 |
+
errors.append(f"models: unknown backend {key!r} (allowed: {allowed})")
|
| 274 |
+
continue
|
| 275 |
+
if not isinstance(value, str) or not value.strip():
|
| 276 |
+
errors.append(f"models: model id for '{key}' must be a non-empty string")
|
| 277 |
+
continue
|
| 278 |
+
if not MODEL_ID_RE.fullmatch(value.strip()) or "://" in value:
|
| 279 |
+
errors.append(
|
| 280 |
+
f"models: model id for '{key}' must be a bare id like 'owner/name' "
|
| 281 |
+
"(URLs and endpoints are not allowed)"
|
| 282 |
+
)
|
| 283 |
+
continue
|
| 284 |
+
if kind in ("image_gen", "image_edit") and key == "anthropic":
|
| 285 |
+
errors.append("models: 'anthropic' cannot serve image skills (no image generation)")
|
| 286 |
+
continue
|
| 287 |
+
declared[key] = value.strip()
|
| 288 |
+
models = dict(DEFAULT_MODELS.get(kind, DEFAULT_MODELS["text"]))
|
| 289 |
+
models.update(declared)
|
| 290 |
+
return models
|
| 291 |
+
|
| 292 |
+
|
| 293 |
+
def _parse_inputs(raw: Any, errors: list[str]) -> tuple[InputSpec, ...]:
|
| 294 |
+
if not isinstance(raw, list):
|
| 295 |
+
errors.append("'inputs' must be a list")
|
| 296 |
+
return ()
|
| 297 |
+
specs: list[InputSpec] = []
|
| 298 |
+
seen: set[str] = set()
|
| 299 |
+
for index, item in enumerate(raw):
|
| 300 |
+
where = f"inputs[{index}]"
|
| 301 |
+
if not isinstance(item, dict):
|
| 302 |
+
errors.append(f"{where}: must be a mapping")
|
| 303 |
+
continue
|
| 304 |
+
for key in item:
|
| 305 |
+
if key not in _INPUT_KEYS:
|
| 306 |
+
errors.append(
|
| 307 |
+
f"{where}: unknown key {key!r} (allowed: {', '.join(sorted(_INPUT_KEYS))})"
|
| 308 |
+
)
|
| 309 |
+
name = item.get("name")
|
| 310 |
+
if not isinstance(name, str) or not INPUT_NAME_RE.match(name):
|
| 311 |
+
errors.append(f"{where}: 'name' is required and must match ^[a-z][a-z0-9_]*$")
|
| 312 |
+
continue
|
| 313 |
+
if name in seen:
|
| 314 |
+
errors.append(f"{where}: duplicate input name {name!r}")
|
| 315 |
+
continue
|
| 316 |
+
seen.add(name)
|
| 317 |
+
|
| 318 |
+
input_type = item.get("type", "text")
|
| 319 |
+
if input_type not in _INPUT_TYPES:
|
| 320 |
+
errors.append(
|
| 321 |
+
f"{where}: 'type' must be one of {'|'.join(_INPUT_TYPES)}, got {input_type!r}"
|
| 322 |
+
)
|
| 323 |
+
input_type = "text"
|
| 324 |
+
|
| 325 |
+
label = item.get("label", name.replace("_", " ").title())
|
| 326 |
+
if not isinstance(label, str) or not label.strip():
|
| 327 |
+
errors.append(f"{where}: 'label' must be a non-empty string")
|
| 328 |
+
label = name
|
| 329 |
+
|
| 330 |
+
required = item.get("required", True)
|
| 331 |
+
if not isinstance(required, bool):
|
| 332 |
+
errors.append(f"{where}: 'required' must be a boolean")
|
| 333 |
+
required = True
|
| 334 |
+
|
| 335 |
+
default = item.get("default", "")
|
| 336 |
+
if not isinstance(default, str):
|
| 337 |
+
errors.append(f"{where}: 'default' must be a string")
|
| 338 |
+
default = ""
|
| 339 |
+
if default and input_type == "image":
|
| 340 |
+
errors.append(f"{where}: 'default' is not allowed for image inputs")
|
| 341 |
+
default = ""
|
| 342 |
+
|
| 343 |
+
placeholder = item.get("placeholder", "")
|
| 344 |
+
if not isinstance(placeholder, str):
|
| 345 |
+
errors.append(f"{where}: 'placeholder' must be a string")
|
| 346 |
+
placeholder = ""
|
| 347 |
+
if placeholder and input_type in ("select", "image"):
|
| 348 |
+
errors.append(f"{where}: 'placeholder' is not allowed for {input_type} inputs")
|
| 349 |
+
placeholder = ""
|
| 350 |
+
|
| 351 |
+
options = _parse_options(item.get("options"), input_type, where, errors)
|
| 352 |
+
if input_type == "select" and default and options and default not in options:
|
| 353 |
+
errors.append(f"{where}: 'default' must be one of the declared options")
|
| 354 |
+
default = ""
|
| 355 |
+
|
| 356 |
+
specs.append(
|
| 357 |
+
InputSpec(
|
| 358 |
+
name=name,
|
| 359 |
+
type=input_type, # type: ignore[arg-type]
|
| 360 |
+
label=label.strip(),
|
| 361 |
+
required=required,
|
| 362 |
+
default=default,
|
| 363 |
+
placeholder=placeholder,
|
| 364 |
+
options=options,
|
| 365 |
+
)
|
| 366 |
+
)
|
| 367 |
+
return tuple(specs)
|
| 368 |
+
|
| 369 |
+
|
| 370 |
+
def _parse_options(raw: Any, input_type: str, where: str, errors: list[str]) -> tuple[str, ...]:
|
| 371 |
+
if input_type != "select":
|
| 372 |
+
if raw is not None:
|
| 373 |
+
errors.append(f"{where}: 'options' is only allowed for select inputs")
|
| 374 |
+
return ()
|
| 375 |
+
if not isinstance(raw, list) or not raw:
|
| 376 |
+
errors.append(f"{where}: select inputs require a non-empty 'options' list")
|
| 377 |
+
return ()
|
| 378 |
+
options: list[str] = []
|
| 379 |
+
for option in raw:
|
| 380 |
+
if not isinstance(option, str) or not option.strip():
|
| 381 |
+
errors.append(f"{where}: options must be non-empty strings")
|
| 382 |
+
return ()
|
| 383 |
+
options.append(option.strip())
|
| 384 |
+
if len(set(options)) != len(options):
|
| 385 |
+
errors.append(f"{where}: options must be unique")
|
| 386 |
+
return ()
|
| 387 |
+
return tuple(options)
|
| 388 |
+
|
| 389 |
+
|
| 390 |
+
def validate_model_id(model: str) -> str:
|
| 391 |
+
"""Reject anything that is not a bare model id.
|
| 392 |
+
|
| 393 |
+
A URL-shaped "model" would make the inference client treat it as an
|
| 394 |
+
endpoint and send the bearer token there — on a public Space with an
|
| 395 |
+
HF_TOKEN secret that is credential exfiltration. Enforced at parse time
|
| 396 |
+
for frontmatter and again at run time for the editable Model field.
|
| 397 |
+
"""
|
| 398 |
+
model = model.strip()
|
| 399 |
+
if not MODEL_ID_RE.fullmatch(model) or "://" in model:
|
| 400 |
+
raise InputValueError(
|
| 401 |
+
f"{model!r} is not a valid model id — use a bare id like 'owner/name' "
|
| 402 |
+
"or 'name:tag'. URLs and endpoints are not allowed."
|
| 403 |
+
)
|
| 404 |
+
return model
|
| 405 |
+
|
| 406 |
+
|
| 407 |
+
def resolve_values(spec: SkillSpec, values: dict[str, Any]) -> dict[str, str]:
|
| 408 |
+
"""Build the fully-resolved TEXT input dict: every non-image input as str.
|
| 409 |
+
|
| 410 |
+
Image inputs are validated and collected separately (collect_images).
|
| 411 |
+
Raises InputValueError on missing required values or select values outside
|
| 412 |
+
the declared options. Substitution must read only from this dict.
|
| 413 |
+
"""
|
| 414 |
+
resolved: dict[str, str] = {}
|
| 415 |
+
for inp in spec.inputs:
|
| 416 |
+
if inp.type == "image":
|
| 417 |
+
continue
|
| 418 |
+
raw = values.get(inp.name)
|
| 419 |
+
value = "" if raw is None else str(raw).strip()
|
| 420 |
+
if not value:
|
| 421 |
+
value = inp.default
|
| 422 |
+
if inp.required and not value:
|
| 423 |
+
raise InputValueError(f"'{inp.label}' is required.")
|
| 424 |
+
if inp.type == "select" and value and value not in inp.options:
|
| 425 |
+
raise InputValueError(f"'{inp.label}' must be one of: {', '.join(inp.options)}.")
|
| 426 |
+
resolved[inp.name] = value
|
| 427 |
+
return resolved
|
| 428 |
+
|
| 429 |
+
|
| 430 |
+
def collect_images(spec: SkillSpec, values: dict[str, Any]) -> tuple[Any, ...]:
|
| 431 |
+
"""Gather uploaded images for the skill's image inputs, in declared order.
|
| 432 |
+
|
| 433 |
+
Raises InputValueError when a required image input has no upload.
|
| 434 |
+
"""
|
| 435 |
+
images: list[Any] = []
|
| 436 |
+
for inp in spec.image_inputs:
|
| 437 |
+
image = values.get(inp.name)
|
| 438 |
+
if image is None:
|
| 439 |
+
if inp.required:
|
| 440 |
+
raise InputValueError(f"'{inp.label}' requires an image upload.")
|
| 441 |
+
continue
|
| 442 |
+
images.append(image)
|
| 443 |
+
return tuple(images)
|
| 444 |
+
|
| 445 |
+
|
| 446 |
+
def render_prompt(spec: SkillSpec, resolved: dict[str, str]) -> str:
|
| 447 |
+
"""Substitute placeholders and append unreferenced non-empty inputs.
|
| 448 |
+
|
| 449 |
+
``resolved`` must come from resolve_values (all declared inputs present).
|
| 450 |
+
Text skills get a markdown '## Inputs' section; image skills get plain
|
| 451 |
+
'Label: value' lines (no markdown headers inside image prompts).
|
| 452 |
+
"""
|
| 453 |
+
rendered = PLACEHOLDER_RE.sub(lambda m: resolved[m.group(1)], spec.body)
|
| 454 |
+
referenced = spec.referenced_inputs
|
| 455 |
+
extras = [
|
| 456 |
+
(inp.label, resolved[inp.name])
|
| 457 |
+
for inp in spec.inputs
|
| 458 |
+
if inp.name in resolved and inp.name not in referenced and resolved[inp.name]
|
| 459 |
+
]
|
| 460 |
+
if not extras:
|
| 461 |
+
return rendered
|
| 462 |
+
lines = "\n".join(f"- {label}: {value}" for label, value in extras)
|
| 463 |
+
if spec.output == "text":
|
| 464 |
+
return f"{rendered}\n\n## Inputs\n{lines}"
|
| 465 |
+
plain = "\n".join(f"{label}: {value}" for label, value in extras)
|
| 466 |
+
return f"{rendered}\n{plain}"
|
| 467 |
+
|
| 468 |
+
|
| 469 |
+
def load_catalog(skills_dir: Path) -> Catalog:
|
| 470 |
+
"""Scan immediate children of skills_dir for SKILL.md packages.
|
| 471 |
+
|
| 472 |
+
One bad skill must never kill the catalog: every per-directory failure is
|
| 473 |
+
isolated into a SkillFailure. A missing directory yields an empty catalog
|
| 474 |
+
(the UI shows a notice; a crash-looping Space is the worst outcome).
|
| 475 |
+
"""
|
| 476 |
+
if not skills_dir.is_dir():
|
| 477 |
+
return Catalog((), ())
|
| 478 |
+
skills: list[SkillSpec] = []
|
| 479 |
+
failures: list[SkillFailure] = []
|
| 480 |
+
children = sorted(skills_dir.iterdir(), key=lambda p: (p.name.casefold(), p.name))
|
| 481 |
+
for child in children:
|
| 482 |
+
if not child.is_dir() or child.name.startswith((".", "_")):
|
| 483 |
+
continue
|
| 484 |
+
file_names = {p.name for p in child.iterdir() if p.is_file()}
|
| 485 |
+
if "SKILL.md" not in file_names:
|
| 486 |
+
# macOS dev machines are case-insensitive; the Space is not. A
|
| 487 |
+
# case-variant is clearly an intended skill — surface it loudly.
|
| 488 |
+
variant = next((n for n in sorted(file_names) if n.lower() == "skill.md"), None)
|
| 489 |
+
if variant is not None:
|
| 490 |
+
failures.append(
|
| 491 |
+
SkillFailure(
|
| 492 |
+
child.name,
|
| 493 |
+
child / variant,
|
| 494 |
+
f"found {variant!r} but the file must be named exactly 'SKILL.md' "
|
| 495 |
+
"(filenames are case-sensitive on Hugging Face Spaces)",
|
| 496 |
+
)
|
| 497 |
+
)
|
| 498 |
+
continue
|
| 499 |
+
skill_file = child / "SKILL.md"
|
| 500 |
+
try:
|
| 501 |
+
skills.append(parse_skill(child.name, skill_file.read_text(encoding="utf-8-sig")))
|
| 502 |
+
except SkillValidationError as exc:
|
| 503 |
+
failures.append(SkillFailure(child.name, skill_file, "; ".join(exc.errors)))
|
| 504 |
+
except Exception as exc: # one hostile/corrupt file must not kill the catalog
|
| 505 |
+
failures.append(SkillFailure(child.name, skill_file, f"{type(exc).__name__}: {exc}"))
|
| 506 |
+
return Catalog(tuple(skills), tuple(failures))
|
src/skills_cloud/ui.py
ADDED
|
@@ -0,0 +1,725 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""Gradio UI: skill catalog as tabs, per-skill run panels.
|
| 2 |
+
|
| 3 |
+
Only this module (and app.py) may import gradio. Handlers are module-level
|
| 4 |
+
factories so tests can exercise them with FakeBackend and no server.
|
| 5 |
+
"""
|
| 6 |
+
|
| 7 |
+
from __future__ import annotations
|
| 8 |
+
|
| 9 |
+
import functools
|
| 10 |
+
import os
|
| 11 |
+
from collections.abc import Callable, Iterator
|
| 12 |
+
from dataclasses import dataclass, replace
|
| 13 |
+
from typing import Any
|
| 14 |
+
|
| 15 |
+
import gradio as gr
|
| 16 |
+
|
| 17 |
+
from skills_cloud import __version__
|
| 18 |
+
from skills_cloud.backends import BackendError, get_backend
|
| 19 |
+
from skills_cloud.github import RepoRefError, fetch_skills, parse_repo_ref
|
| 20 |
+
from skills_cloud.models_hub import anthropic_model_choices, hub_model_choices
|
| 21 |
+
from skills_cloud.runner import run_image_skill, run_text_skill
|
| 22 |
+
from skills_cloud.skill import (
|
| 23 |
+
DEFAULT_MODELS,
|
| 24 |
+
Catalog,
|
| 25 |
+
InputSpec,
|
| 26 |
+
InputValueError,
|
| 27 |
+
SkillSpec,
|
| 28 |
+
merge_catalogs,
|
| 29 |
+
)
|
| 30 |
+
from skills_cloud.zerogpu import is_zerogpu_available, zerogpu_text_model
|
| 31 |
+
|
| 32 |
+
TAGLINE = "Run lightweight agent skills in one click — no local install, no dependency conflicts."
|
| 33 |
+
|
| 34 |
+
HF_CHOICE = "Hugging Face"
|
| 35 |
+
ANTHROPIC_CHOICE = "Anthropic API"
|
| 36 |
+
OPENAI_CHOICE = "OpenAI-compatible"
|
| 37 |
+
ZEROGPU_CHOICE = "Space GPU (free)"
|
| 38 |
+
_BACKEND_BY_CHOICE = {
|
| 39 |
+
HF_CHOICE: "hf",
|
| 40 |
+
ANTHROPIC_CHOICE: "anthropic",
|
| 41 |
+
OPENAI_CHOICE: "openai",
|
| 42 |
+
ZEROGPU_CHOICE: "zerogpu",
|
| 43 |
+
}
|
| 44 |
+
|
| 45 |
+
|
| 46 |
+
def text_backend_choices() -> list[str]:
|
| 47 |
+
"""Space GPU leads when this IS a ZeroGPU Space — zero-friction default."""
|
| 48 |
+
if is_zerogpu_available():
|
| 49 |
+
return [ZEROGPU_CHOICE, HF_CHOICE, ANTHROPIC_CHOICE, OPENAI_CHOICE]
|
| 50 |
+
return [HF_CHOICE, ANTHROPIC_CHOICE, OPENAI_CHOICE]
|
| 51 |
+
|
| 52 |
+
|
| 53 |
+
def default_text_backend() -> str:
|
| 54 |
+
return ZEROGPU_CHOICE if is_zerogpu_available() else HF_CHOICE
|
| 55 |
+
|
| 56 |
+
|
| 57 |
+
_ENV_KEYS = {"hf": "HF_TOKEN", "anthropic": "ANTHROPIC_API_KEY"}
|
| 58 |
+
_BASE_URL_LABEL = "Endpoint base URL (e.g. https://api.openai.com/v1 · http://localhost:11434/v1)"
|
| 59 |
+
|
| 60 |
+
OUTPUT_TEXT = "Text"
|
| 61 |
+
OUTPUT_IMAGE = "Image"
|
| 62 |
+
ALL_SOURCES = "All"
|
| 63 |
+
BUILTIN_SOURCE_LABEL = "Built-in"
|
| 64 |
+
|
| 65 |
+
_KEY_LABELS = {
|
| 66 |
+
"hf": "HF token (optional if signed in with Hugging Face or HF_TOKEN secret is set)",
|
| 67 |
+
"anthropic": "Anthropic API key (leave empty to use ANTHROPIC_API_KEY secret)",
|
| 68 |
+
"openai": "API key (sent only to the endpoint above; leave empty for local servers)",
|
| 69 |
+
}
|
| 70 |
+
|
| 71 |
+
|
| 72 |
+
def resolve_api_key(backend_id: str, field_value: str, oauth_token: Any = None) -> str:
|
| 73 |
+
"""Precedence: typed field > HF OAuth session token > Space secret env var.
|
| 74 |
+
|
| 75 |
+
Setting a Space secret is the owner's explicit opt-in to paying for
|
| 76 |
+
visitors (documented in README). Returns "" when nothing is available.
|
| 77 |
+
"""
|
| 78 |
+
field = field_value.strip()
|
| 79 |
+
if field:
|
| 80 |
+
return field
|
| 81 |
+
if backend_id == "hf" and oauth_token is not None:
|
| 82 |
+
token = getattr(oauth_token, "token", "")
|
| 83 |
+
if token:
|
| 84 |
+
return token
|
| 85 |
+
return os.environ.get(_ENV_KEYS[backend_id], "")
|
| 86 |
+
|
| 87 |
+
|
| 88 |
+
def build_skill_form(spec: SkillSpec) -> list[gr.Textbox | gr.Dropdown | gr.Image]:
|
| 89 |
+
"""Inert Gradio components for a skill's declared inputs (unit-testable)."""
|
| 90 |
+
components: list[gr.Textbox | gr.Dropdown | gr.Image] = []
|
| 91 |
+
for inp in spec.inputs:
|
| 92 |
+
components.append(_build_input_component(inp))
|
| 93 |
+
return components
|
| 94 |
+
|
| 95 |
+
|
| 96 |
+
def _build_input_component(inp: InputSpec) -> gr.Textbox | gr.Dropdown | gr.Image:
|
| 97 |
+
if inp.type == "image":
|
| 98 |
+
return gr.Image(type="pil", label=inp.label, interactive=True)
|
| 99 |
+
if inp.type == "select":
|
| 100 |
+
return gr.Dropdown(
|
| 101 |
+
choices=list(inp.options),
|
| 102 |
+
value=inp.default or None,
|
| 103 |
+
label=inp.label,
|
| 104 |
+
interactive=True,
|
| 105 |
+
)
|
| 106 |
+
return gr.Textbox(
|
| 107 |
+
label=inp.label,
|
| 108 |
+
placeholder=inp.placeholder,
|
| 109 |
+
value=inp.default,
|
| 110 |
+
lines=4 if inp.type == "textarea" else 1,
|
| 111 |
+
interactive=True,
|
| 112 |
+
)
|
| 113 |
+
|
| 114 |
+
|
| 115 |
+
def _collect_values(spec: SkillSpec, form_values: tuple[Any, ...]) -> dict[str, Any]:
|
| 116 |
+
return dict(zip([inp.name for inp in spec.inputs], form_values, strict=True))
|
| 117 |
+
|
| 118 |
+
|
| 119 |
+
def _require_openai_endpoint(base_url: str, key_field: str) -> tuple[str, str]:
|
| 120 |
+
"""Custom endpoints get ONLY the typed key — never Space secrets or the
|
| 121 |
+
OAuth session token. The endpoint is user-controlled; any fallback would
|
| 122 |
+
exfiltrate the owner's credentials to an arbitrary server."""
|
| 123 |
+
base_url = (base_url or "").strip().rstrip("/")
|
| 124 |
+
if not base_url or not base_url.startswith(("http://", "https://")):
|
| 125 |
+
raise gr.Error(
|
| 126 |
+
"Enter the endpoint base URL for the OpenAI-compatible backend, "
|
| 127 |
+
"e.g. https://api.openai.com/v1 or http://localhost:11434/v1."
|
| 128 |
+
)
|
| 129 |
+
return base_url, (key_field or "").strip()
|
| 130 |
+
|
| 131 |
+
|
| 132 |
+
def _require_key(backend_id: str, field_value: str, oauth_token: Any = None) -> str:
|
| 133 |
+
api_key = resolve_api_key(backend_id, field_value, oauth_token)
|
| 134 |
+
if not api_key:
|
| 135 |
+
if backend_id == "hf":
|
| 136 |
+
raise gr.Error(
|
| 137 |
+
"Provide an HF token above, sign in with Hugging Face, or ask the "
|
| 138 |
+
"Space owner to set the HF_TOKEN secret."
|
| 139 |
+
)
|
| 140 |
+
raise gr.Error(
|
| 141 |
+
"Provide an Anthropic API key above, or ask the Space owner to set the "
|
| 142 |
+
"ANTHROPIC_API_KEY secret."
|
| 143 |
+
)
|
| 144 |
+
return api_key
|
| 145 |
+
|
| 146 |
+
|
| 147 |
+
def make_text_handler(spec: SkillSpec) -> Callable[..., Iterator[str]]:
|
| 148 |
+
def handler(
|
| 149 |
+
backend_choice: str,
|
| 150 |
+
model: str,
|
| 151 |
+
hf_key: str,
|
| 152 |
+
anthropic_key: str,
|
| 153 |
+
openai_key: str,
|
| 154 |
+
base_url: str,
|
| 155 |
+
oauth_token: gr.OAuthToken | None = None,
|
| 156 |
+
*form_values: Any,
|
| 157 |
+
) -> Iterator[str]:
|
| 158 |
+
backend_id = _BACKEND_BY_CHOICE[backend_choice]
|
| 159 |
+
endpoint = None
|
| 160 |
+
if backend_id == "zerogpu":
|
| 161 |
+
api_key = "" # the whole point: no credentials, visitor quota
|
| 162 |
+
chosen_model = zerogpu_text_model()
|
| 163 |
+
elif backend_id == "openai":
|
| 164 |
+
endpoint, api_key = _require_openai_endpoint(base_url, openai_key)
|
| 165 |
+
chosen_model = (model or "").strip() or spec.models.get("openai", "")
|
| 166 |
+
if not chosen_model:
|
| 167 |
+
raise gr.Error("Enter the model name your endpoint serves (e.g. qwen3:8b).")
|
| 168 |
+
else:
|
| 169 |
+
field = hf_key if backend_id == "hf" else anthropic_key
|
| 170 |
+
api_key = _require_key(backend_id, field, oauth_token)
|
| 171 |
+
chosen_model = (model or "").strip() or spec.models[backend_id]
|
| 172 |
+
values = _collect_values(spec, form_values)
|
| 173 |
+
try:
|
| 174 |
+
yield from run_text_skill(
|
| 175 |
+
spec, values, get_backend(backend_id), chosen_model, api_key, base_url=endpoint
|
| 176 |
+
)
|
| 177 |
+
except InputValueError as exc:
|
| 178 |
+
raise gr.Error(str(exc)) from exc
|
| 179 |
+
except BackendError as exc:
|
| 180 |
+
# Partial streamed text stays in the output box; the toast reports the failure.
|
| 181 |
+
raise gr.Error(exc.user_message) from exc
|
| 182 |
+
|
| 183 |
+
return handler
|
| 184 |
+
|
| 185 |
+
|
| 186 |
+
def make_image_handler(spec: SkillSpec) -> Callable[..., Any]:
|
| 187 |
+
def handler(
|
| 188 |
+
model: str,
|
| 189 |
+
hf_key: str,
|
| 190 |
+
oauth_token: gr.OAuthToken | None = None,
|
| 191 |
+
*form_values: Any,
|
| 192 |
+
) -> Any:
|
| 193 |
+
api_key = _require_key("hf", hf_key, oauth_token)
|
| 194 |
+
chosen_model = (model or "").strip() or spec.models["hf"]
|
| 195 |
+
values = _collect_values(spec, form_values)
|
| 196 |
+
try:
|
| 197 |
+
return run_image_skill(spec, values, get_backend("hf"), chosen_model, api_key)
|
| 198 |
+
except InputValueError as exc:
|
| 199 |
+
raise gr.Error(str(exc)) from exc
|
| 200 |
+
except BackendError as exc:
|
| 201 |
+
raise gr.Error(exc.user_message) from exc
|
| 202 |
+
|
| 203 |
+
return handler
|
| 204 |
+
|
| 205 |
+
|
| 206 |
+
def _render_issues(catalog: Catalog) -> None:
|
| 207 |
+
lines = [f"- `skills/{f.slug}`: {f.message}" for f in catalog.failures]
|
| 208 |
+
for spec in catalog.skills:
|
| 209 |
+
lines.extend(f"- `{spec.slug}`: {w}" for w in spec.warnings)
|
| 210 |
+
if not lines:
|
| 211 |
+
return
|
| 212 |
+
count = len(lines)
|
| 213 |
+
with gr.Accordion(f"⚠️ {count} skill issue(s) — details for skill authors", open=False):
|
| 214 |
+
gr.Markdown("\n".join(lines))
|
| 215 |
+
|
| 216 |
+
|
| 217 |
+
def flex_panel_visibility(mode_label: str, has_image: bool, backend_choice: str) -> dict:
|
| 218 |
+
"""Pure visibility/model matrix for the flex panel (unit-testable).
|
| 219 |
+
|
| 220 |
+
Image mode: HF only (no backend radio, HF key always shown). Text mode:
|
| 221 |
+
backend radio shown; key fields follow the chosen backend.
|
| 222 |
+
"""
|
| 223 |
+
is_text = mode_label == OUTPUT_TEXT
|
| 224 |
+
backend_id = _BACKEND_BY_CHOICE.get(backend_choice, "hf")
|
| 225 |
+
choices, value = _flex_model_choices(mode_label, has_image, backend_choice)
|
| 226 |
+
return {
|
| 227 |
+
"backend_radio": is_text,
|
| 228 |
+
"model": value,
|
| 229 |
+
"model_choices": choices,
|
| 230 |
+
"out_text": is_text,
|
| 231 |
+
"out_image": not is_text,
|
| 232 |
+
"hf_key": (not is_text or backend_id == "hf") and backend_id != "zerogpu",
|
| 233 |
+
"anthropic_key": is_text and backend_id == "anthropic",
|
| 234 |
+
"openai_key": is_text and backend_id == "openai",
|
| 235 |
+
"base_url": is_text and backend_id == "openai",
|
| 236 |
+
}
|
| 237 |
+
|
| 238 |
+
|
| 239 |
+
def _flex_default_model(mode_label: str, has_image: bool, backend_choice: str) -> str:
|
| 240 |
+
if mode_label == OUTPUT_IMAGE:
|
| 241 |
+
return DEFAULT_MODELS["image_edit" if has_image else "image_gen"]["hf"]
|
| 242 |
+
backend_id = _BACKEND_BY_CHOICE.get(backend_choice, "hf")
|
| 243 |
+
if backend_id == "openai":
|
| 244 |
+
return "" # no sane universal default — the endpoint decides what it serves
|
| 245 |
+
if backend_id == "zerogpu":
|
| 246 |
+
return zerogpu_text_model() # fixed preloaded pipeline
|
| 247 |
+
kind = "vision" if has_image else "text"
|
| 248 |
+
return DEFAULT_MODELS[kind].get(backend_id, DEFAULT_MODELS[kind]["hf"])
|
| 249 |
+
|
| 250 |
+
|
| 251 |
+
def _choice_values(choices: list) -> list[str]:
|
| 252 |
+
return [choice[1] if isinstance(choice, tuple) else choice for choice in choices]
|
| 253 |
+
|
| 254 |
+
|
| 255 |
+
def _flex_model_choices(mode_label: str, has_image: bool, backend_choice: str) -> tuple[list, str]:
|
| 256 |
+
"""Dropdown choices from the live Hub (cached) + the pinned default value.
|
| 257 |
+
|
| 258 |
+
The pinned non-gated default stays SELECTED; trending lists often lead
|
| 259 |
+
with gated models that would 403 a fresh token.
|
| 260 |
+
"""
|
| 261 |
+
value = _flex_default_model(mode_label, has_image, backend_choice)
|
| 262 |
+
backend_id = _BACKEND_BY_CHOICE.get(backend_choice, "hf")
|
| 263 |
+
if mode_label != OUTPUT_IMAGE and backend_id == "zerogpu":
|
| 264 |
+
return [(value, value)], value # fixed preloaded pipeline
|
| 265 |
+
if mode_label != OUTPUT_IMAGE and backend_id == "openai":
|
| 266 |
+
return [], value # free-form: whatever the endpoint serves
|
| 267 |
+
if mode_label != OUTPUT_IMAGE and backend_id == "anthropic":
|
| 268 |
+
choices = anthropic_model_choices()
|
| 269 |
+
elif mode_label == OUTPUT_IMAGE:
|
| 270 |
+
choices = hub_model_choices("image_edit" if has_image else "image_gen")
|
| 271 |
+
else:
|
| 272 |
+
choices = hub_model_choices("vision" if has_image else "text")
|
| 273 |
+
if value not in _choice_values(choices):
|
| 274 |
+
choices.insert(0, (value, value))
|
| 275 |
+
return choices, value
|
| 276 |
+
|
| 277 |
+
|
| 278 |
+
def _declared_model_choices(spec: SkillSpec, backend_id: str) -> tuple[list, str]:
|
| 279 |
+
if backend_id == "zerogpu":
|
| 280 |
+
value = zerogpu_text_model()
|
| 281 |
+
return [(value, value)], value
|
| 282 |
+
if backend_id == "openai":
|
| 283 |
+
value = spec.models.get("openai", "")
|
| 284 |
+
return ([(value, value)] if value else []), value
|
| 285 |
+
if backend_id == "anthropic":
|
| 286 |
+
choices = anthropic_model_choices()
|
| 287 |
+
value = spec.models.get("anthropic", choices[0])
|
| 288 |
+
else:
|
| 289 |
+
choices = hub_model_choices(spec.kind)
|
| 290 |
+
value = spec.models["hf"]
|
| 291 |
+
if value not in _choice_values(choices):
|
| 292 |
+
choices.insert(0, (value, value))
|
| 293 |
+
return choices, value
|
| 294 |
+
|
| 295 |
+
|
| 296 |
+
def _model_dropdown(choices: list, value: str) -> gr.Dropdown:
|
| 297 |
+
return gr.Dropdown(
|
| 298 |
+
choices=choices,
|
| 299 |
+
value=value,
|
| 300 |
+
label="Model",
|
| 301 |
+
allow_custom_value=True,
|
| 302 |
+
interactive=True,
|
| 303 |
+
)
|
| 304 |
+
|
| 305 |
+
|
| 306 |
+
def _with_button_lock(
|
| 307 |
+
handler: Callable, outputs_count: int, *, busy_label: str, idle_label: str
|
| 308 |
+
) -> Callable:
|
| 309 |
+
"""Wrap a run handler so it disables its own Run button while running.
|
| 310 |
+
|
| 311 |
+
The button is appended as the LAST output and driven from inside the
|
| 312 |
+
handler — NOT via a .then() chain, because chained unlock steps do not
|
| 313 |
+
fire after gr.Error (verified live in Gradio 6), which left the button
|
| 314 |
+
dead after any failed run. functools.wraps preserves the signature so
|
| 315 |
+
gradio keeps injecting gr.OAuthToken.
|
| 316 |
+
"""
|
| 317 |
+
|
| 318 |
+
def _skips() -> tuple:
|
| 319 |
+
return tuple(gr.skip() for _ in range(outputs_count))
|
| 320 |
+
|
| 321 |
+
@functools.wraps(handler)
|
| 322 |
+
def wrapped(*args: Any):
|
| 323 |
+
yield (*_skips(), gr.Button(interactive=False, value=busy_label))
|
| 324 |
+
unlock = gr.Button(interactive=True, value=idle_label)
|
| 325 |
+
try:
|
| 326 |
+
result = handler(*args)
|
| 327 |
+
if isinstance(result, Iterator):
|
| 328 |
+
for item in result:
|
| 329 |
+
part = item if isinstance(item, tuple) else (item,)
|
| 330 |
+
yield (*part, gr.skip())
|
| 331 |
+
yield (*_skips(), unlock)
|
| 332 |
+
else:
|
| 333 |
+
part = result if isinstance(result, tuple) else (result,)
|
| 334 |
+
yield (*part, unlock)
|
| 335 |
+
except BaseException:
|
| 336 |
+
# Unlock first, then let the error surface as a toast.
|
| 337 |
+
yield (*_skips(), unlock)
|
| 338 |
+
raise
|
| 339 |
+
|
| 340 |
+
return wrapped
|
| 341 |
+
|
| 342 |
+
|
| 343 |
+
def _wire_locked_run(
|
| 344 |
+
run: gr.Button,
|
| 345 |
+
handler: Callable,
|
| 346 |
+
inputs: list,
|
| 347 |
+
outputs,
|
| 348 |
+
*,
|
| 349 |
+
busy_label: str,
|
| 350 |
+
idle_label: str,
|
| 351 |
+
) -> None:
|
| 352 |
+
outputs_list = outputs if isinstance(outputs, list) else [outputs]
|
| 353 |
+
wrapped = _with_button_lock(
|
| 354 |
+
handler, len(outputs_list), busy_label=busy_label, idle_label=idle_label
|
| 355 |
+
)
|
| 356 |
+
# trigger_mode="once": clicks are ignored until the previous run finishes,
|
| 357 |
+
# even in the window before the disable update lands in the browser.
|
| 358 |
+
run.click(wrapped, inputs=inputs, outputs=[*outputs_list, run], trigger_mode="once")
|
| 359 |
+
|
| 360 |
+
|
| 361 |
+
def make_flex_handler(spec: SkillSpec) -> Callable[..., Iterator[tuple]]:
|
| 362 |
+
"""Handler for inferred skills: output mode is user-chosen, and an uploaded
|
| 363 |
+
image automatically switches chat→vision or text-to-image→image-to-image."""
|
| 364 |
+
|
| 365 |
+
def handler(
|
| 366 |
+
mode_label: str,
|
| 367 |
+
backend_choice: str,
|
| 368 |
+
model: str,
|
| 369 |
+
hf_key: str,
|
| 370 |
+
anthropic_key: str,
|
| 371 |
+
openai_key: str,
|
| 372 |
+
base_url: str,
|
| 373 |
+
oauth_token: gr.OAuthToken | None = None,
|
| 374 |
+
*form_values: Any,
|
| 375 |
+
) -> Iterator[tuple]:
|
| 376 |
+
values = _collect_values(spec, form_values)
|
| 377 |
+
has_image = any(values.get(inp.name) is not None for inp in spec.image_inputs)
|
| 378 |
+
try:
|
| 379 |
+
if mode_label == OUTPUT_IMAGE:
|
| 380 |
+
api_key = _require_key("hf", hf_key, oauth_token)
|
| 381 |
+
chosen = (model or "").strip() or _flex_default_model(
|
| 382 |
+
mode_label, has_image, HF_CHOICE
|
| 383 |
+
)
|
| 384 |
+
run_spec = replace(spec, output="image")
|
| 385 |
+
image = run_image_skill(run_spec, values, get_backend("hf"), chosen, api_key)
|
| 386 |
+
yield gr.skip(), image
|
| 387 |
+
return
|
| 388 |
+
backend_id = _BACKEND_BY_CHOICE[backend_choice]
|
| 389 |
+
endpoint = None
|
| 390 |
+
if backend_id == "zerogpu":
|
| 391 |
+
api_key = ""
|
| 392 |
+
chosen = zerogpu_text_model()
|
| 393 |
+
elif backend_id == "openai":
|
| 394 |
+
endpoint, api_key = _require_openai_endpoint(base_url, openai_key)
|
| 395 |
+
chosen = (model or "").strip()
|
| 396 |
+
if not chosen:
|
| 397 |
+
raise gr.Error("Enter the model name your endpoint serves (e.g. qwen3:8b).")
|
| 398 |
+
else:
|
| 399 |
+
field = hf_key if backend_id == "hf" else anthropic_key
|
| 400 |
+
api_key = _require_key(backend_id, field, oauth_token)
|
| 401 |
+
chosen = (model or "").strip() or _flex_default_model(
|
| 402 |
+
mode_label, has_image, backend_choice
|
| 403 |
+
)
|
| 404 |
+
run_spec = replace(spec, output="text")
|
| 405 |
+
for accumulated in run_text_skill(
|
| 406 |
+
run_spec, values, get_backend(backend_id), chosen, api_key, base_url=endpoint
|
| 407 |
+
):
|
| 408 |
+
yield accumulated, gr.skip()
|
| 409 |
+
except InputValueError as exc:
|
| 410 |
+
raise gr.Error(str(exc)) from exc
|
| 411 |
+
except BackendError as exc:
|
| 412 |
+
raise gr.Error(exc.user_message) from exc
|
| 413 |
+
|
| 414 |
+
return handler
|
| 415 |
+
|
| 416 |
+
|
| 417 |
+
def _build_flex_panel(spec: SkillSpec) -> None:
|
| 418 |
+
"""Panel for inferred (ported) skills: editable output type, universal
|
| 419 |
+
optional image upload and request field."""
|
| 420 |
+
initial_mode = OUTPUT_IMAGE if spec.output == "image" else OUTPUT_TEXT
|
| 421 |
+
initial_choices, initial_value = _flex_model_choices(
|
| 422 |
+
initial_mode, False, default_text_backend()
|
| 423 |
+
)
|
| 424 |
+
with gr.Row():
|
| 425 |
+
with gr.Column(scale=1):
|
| 426 |
+
mode = gr.Dropdown(
|
| 427 |
+
choices=[OUTPUT_TEXT, OUTPUT_IMAGE],
|
| 428 |
+
value=initial_mode,
|
| 429 |
+
label="Output type (auto-detected — change it if the guess is wrong)",
|
| 430 |
+
interactive=True,
|
| 431 |
+
)
|
| 432 |
+
backend = gr.Radio(
|
| 433 |
+
choices=text_backend_choices(),
|
| 434 |
+
value=default_text_backend(),
|
| 435 |
+
label="Run on",
|
| 436 |
+
visible=initial_mode == OUTPUT_TEXT,
|
| 437 |
+
interactive=True,
|
| 438 |
+
)
|
| 439 |
+
base_url = gr.Textbox(label=_BASE_URL_LABEL, visible=False, interactive=True)
|
| 440 |
+
model = _model_dropdown(initial_choices, initial_value)
|
| 441 |
+
hf_key = gr.Textbox(
|
| 442 |
+
label=_KEY_LABELS["hf"], type="password", visible=True, interactive=True
|
| 443 |
+
)
|
| 444 |
+
anthropic_key = gr.Textbox(
|
| 445 |
+
label=_KEY_LABELS["anthropic"], type="password", visible=False, interactive=True
|
| 446 |
+
)
|
| 447 |
+
openai_key = gr.Textbox(
|
| 448 |
+
label=_KEY_LABELS["openai"], type="password", visible=False, interactive=True
|
| 449 |
+
)
|
| 450 |
+
form = build_skill_form(spec)
|
| 451 |
+
run = gr.Button("Run", variant="primary")
|
| 452 |
+
with gr.Column(scale=1):
|
| 453 |
+
out_text = gr.Textbox(
|
| 454 |
+
label="Output", lines=16, buttons=["copy"], visible=initial_mode == OUTPUT_TEXT
|
| 455 |
+
)
|
| 456 |
+
out_image = gr.Image(
|
| 457 |
+
label="Output", interactive=False, visible=initial_mode == OUTPUT_IMAGE
|
| 458 |
+
)
|
| 459 |
+
|
| 460 |
+
image_upload = form[0] # make_inferred_spec puts the image input first
|
| 461 |
+
|
| 462 |
+
def on_mode_change(mode_label: str, image, backend_choice: str):
|
| 463 |
+
updates = flex_panel_visibility(mode_label, image is not None, backend_choice)
|
| 464 |
+
return (
|
| 465 |
+
gr.Radio(visible=updates["backend_radio"]),
|
| 466 |
+
gr.Dropdown(choices=updates["model_choices"], value=updates["model"]),
|
| 467 |
+
gr.Textbox(visible=updates["out_text"]),
|
| 468 |
+
gr.Image(visible=updates["out_image"]),
|
| 469 |
+
gr.Textbox(visible=updates["hf_key"]),
|
| 470 |
+
gr.Textbox(visible=updates["anthropic_key"]),
|
| 471 |
+
gr.Textbox(visible=updates["openai_key"]),
|
| 472 |
+
gr.Textbox(visible=updates["base_url"]),
|
| 473 |
+
)
|
| 474 |
+
|
| 475 |
+
mode.change(
|
| 476 |
+
on_mode_change,
|
| 477 |
+
inputs=[mode, image_upload, backend],
|
| 478 |
+
outputs=[backend, model, out_text, out_image, hf_key, anthropic_key, openai_key, base_url],
|
| 479 |
+
)
|
| 480 |
+
|
| 481 |
+
def on_image_change(mode_label: str, image, backend_choice: str):
|
| 482 |
+
choices, value = _flex_model_choices(mode_label, image is not None, backend_choice)
|
| 483 |
+
return gr.Dropdown(choices=choices, value=value)
|
| 484 |
+
|
| 485 |
+
image_upload.change(on_image_change, inputs=[mode, image_upload, backend], outputs=model)
|
| 486 |
+
|
| 487 |
+
def on_backend_change(mode_label: str, image, backend_choice: str):
|
| 488 |
+
updates = flex_panel_visibility(mode_label, image is not None, backend_choice)
|
| 489 |
+
return (
|
| 490 |
+
gr.Dropdown(choices=updates["model_choices"], value=updates["model"]),
|
| 491 |
+
gr.Textbox(visible=updates["hf_key"]),
|
| 492 |
+
gr.Textbox(visible=updates["anthropic_key"]),
|
| 493 |
+
gr.Textbox(visible=updates["openai_key"]),
|
| 494 |
+
gr.Textbox(visible=updates["base_url"]),
|
| 495 |
+
)
|
| 496 |
+
|
| 497 |
+
backend.change(
|
| 498 |
+
on_backend_change,
|
| 499 |
+
inputs=[mode, image_upload, backend],
|
| 500 |
+
outputs=[model, hf_key, anthropic_key, openai_key, base_url],
|
| 501 |
+
)
|
| 502 |
+
|
| 503 |
+
_wire_locked_run(
|
| 504 |
+
run,
|
| 505 |
+
make_flex_handler(spec),
|
| 506 |
+
[mode, backend, model, hf_key, anthropic_key, openai_key, base_url, *form],
|
| 507 |
+
[out_text, out_image],
|
| 508 |
+
busy_label="Running…",
|
| 509 |
+
idle_label="Run",
|
| 510 |
+
)
|
| 511 |
+
|
| 512 |
+
|
| 513 |
+
def _build_text_panel(spec: SkillSpec) -> None:
|
| 514 |
+
choices, value = _declared_model_choices(spec, _BACKEND_BY_CHOICE[default_text_backend()])
|
| 515 |
+
with gr.Row():
|
| 516 |
+
with gr.Column(scale=1):
|
| 517 |
+
backend = gr.Radio(
|
| 518 |
+
choices=text_backend_choices(),
|
| 519 |
+
value=default_text_backend(),
|
| 520 |
+
label="Run on",
|
| 521 |
+
interactive=True,
|
| 522 |
+
)
|
| 523 |
+
base_url = gr.Textbox(label=_BASE_URL_LABEL, visible=False, interactive=True)
|
| 524 |
+
model = _model_dropdown(choices, value)
|
| 525 |
+
hf_key = gr.Textbox(
|
| 526 |
+
label=_KEY_LABELS["hf"], type="password", visible=True, interactive=True
|
| 527 |
+
)
|
| 528 |
+
anthropic_key = gr.Textbox(
|
| 529 |
+
label=_KEY_LABELS["anthropic"], type="password", visible=False, interactive=True
|
| 530 |
+
)
|
| 531 |
+
openai_key = gr.Textbox(
|
| 532 |
+
label=_KEY_LABELS["openai"], type="password", visible=False, interactive=True
|
| 533 |
+
)
|
| 534 |
+
form = build_skill_form(spec)
|
| 535 |
+
run = gr.Button("Run", variant="primary")
|
| 536 |
+
with gr.Column(scale=1):
|
| 537 |
+
output = gr.Textbox(label="Output", lines=16, buttons=["copy"])
|
| 538 |
+
|
| 539 |
+
def on_backend_change(choice: str):
|
| 540 |
+
backend_id = _BACKEND_BY_CHOICE[choice]
|
| 541 |
+
new_choices, new_value = _declared_model_choices(spec, backend_id)
|
| 542 |
+
return (
|
| 543 |
+
gr.Dropdown(choices=new_choices, value=new_value or None),
|
| 544 |
+
gr.Textbox(visible=backend_id == "hf"),
|
| 545 |
+
gr.Textbox(visible=backend_id == "anthropic"),
|
| 546 |
+
gr.Textbox(visible=backend_id == "openai"),
|
| 547 |
+
gr.Textbox(visible=backend_id == "openai"),
|
| 548 |
+
)
|
| 549 |
+
|
| 550 |
+
backend.change(
|
| 551 |
+
on_backend_change,
|
| 552 |
+
inputs=backend,
|
| 553 |
+
outputs=[model, hf_key, anthropic_key, openai_key, base_url],
|
| 554 |
+
)
|
| 555 |
+
_wire_locked_run(
|
| 556 |
+
run,
|
| 557 |
+
make_text_handler(spec),
|
| 558 |
+
[backend, model, hf_key, anthropic_key, openai_key, base_url, *form],
|
| 559 |
+
output,
|
| 560 |
+
busy_label="Running…",
|
| 561 |
+
idle_label="Run",
|
| 562 |
+
)
|
| 563 |
+
|
| 564 |
+
|
| 565 |
+
def _build_image_panel(spec: SkillSpec) -> None:
|
| 566 |
+
choices, value = _declared_model_choices(spec, "hf")
|
| 567 |
+
with gr.Row():
|
| 568 |
+
with gr.Column(scale=1):
|
| 569 |
+
model = _model_dropdown(choices, value)
|
| 570 |
+
hf_key = gr.Textbox(label=_KEY_LABELS["hf"], type="password", interactive=True)
|
| 571 |
+
form = build_skill_form(spec)
|
| 572 |
+
run = gr.Button("Generate", variant="primary")
|
| 573 |
+
with gr.Column(scale=1):
|
| 574 |
+
output = gr.Image(label="Output", type="pil", interactive=False)
|
| 575 |
+
|
| 576 |
+
_wire_locked_run(
|
| 577 |
+
run,
|
| 578 |
+
make_image_handler(spec),
|
| 579 |
+
[model, hf_key, *form],
|
| 580 |
+
output,
|
| 581 |
+
busy_label="Generating…",
|
| 582 |
+
idle_label="Generate",
|
| 583 |
+
)
|
| 584 |
+
|
| 585 |
+
|
| 586 |
+
@dataclass(frozen=True, slots=True)
|
| 587 |
+
class CatalogView:
|
| 588 |
+
"""Session UI state: catalog, selected tab, and active source filter.
|
| 589 |
+
|
| 590 |
+
Must stay hashable — gr.render tracks gr.State via deep_hash.
|
| 591 |
+
"""
|
| 592 |
+
|
| 593 |
+
catalog: Catalog
|
| 594 |
+
selected: str | None = None
|
| 595 |
+
source_filter: str | None = None # None = show all; else a SkillSpec.source
|
| 596 |
+
|
| 597 |
+
@property
|
| 598 |
+
def visible_skills(self) -> tuple[SkillSpec, ...]:
|
| 599 |
+
if self.source_filter is None:
|
| 600 |
+
return self.catalog.skills
|
| 601 |
+
return tuple(s for s in self.catalog.skills if s.source == self.source_filter)
|
| 602 |
+
|
| 603 |
+
|
| 604 |
+
def load_repo_into_catalog(repo_text: str, view: CatalogView) -> tuple[CatalogView, str]:
|
| 605 |
+
"""Fetch SKILL.md packages from a GitHub repo and merge into this session's catalog."""
|
| 606 |
+
try:
|
| 607 |
+
ref = parse_repo_ref(repo_text)
|
| 608 |
+
fetched = fetch_skills(ref)
|
| 609 |
+
except RepoRefError as exc:
|
| 610 |
+
raise gr.Error(str(exc)) from exc
|
| 611 |
+
merged, added, skipped = merge_catalogs(view.catalog, fetched)
|
| 612 |
+
if not fetched.skills and not fetched.failures:
|
| 613 |
+
return view, f"No SKILL.md files found in `{ref.display}`."
|
| 614 |
+
# Show only what the user just loaded, and jump to the first new skill —
|
| 615 |
+
# a new tab buried among dozens of others reads as "nothing happened".
|
| 616 |
+
selected = added[0] if added else (fetched.skills[0].slug if fetched.skills else view.selected)
|
| 617 |
+
parts = [f"Loaded **{len(added)}** skill(s) from `{ref.display}`."]
|
| 618 |
+
if skipped:
|
| 619 |
+
parts.append(f"Skipped {skipped} already-loaded slug(s).")
|
| 620 |
+
if fetched.failures:
|
| 621 |
+
parts.append(f"{len(fetched.failures)} file(s) failed to parse — details below.")
|
| 622 |
+
if fetched.skills:
|
| 623 |
+
parts.append("Showing only this repo — use the source filter to see everything.")
|
| 624 |
+
new_filter = ref.display if fetched.skills else view.source_filter
|
| 625 |
+
return CatalogView(merged, selected, new_filter), " ".join(parts)
|
| 626 |
+
|
| 627 |
+
|
| 628 |
+
def _oauth_available() -> bool:
|
| 629 |
+
"""LoginButton is safe to mount only where OAuth can actually work.
|
| 630 |
+
|
| 631 |
+
On a Space with `hf_oauth: true` the runtime sets OAUTH_CLIENT_ID. Locally
|
| 632 |
+
Gradio mocks the flow, but that mock hard-crashes app construction unless
|
| 633 |
+
the machine is logged in to HF — so we skip the button instead.
|
| 634 |
+
"""
|
| 635 |
+
if os.environ.get("OAUTH_CLIENT_ID"):
|
| 636 |
+
return True
|
| 637 |
+
try:
|
| 638 |
+
from huggingface_hub import get_token
|
| 639 |
+
|
| 640 |
+
return get_token() is not None
|
| 641 |
+
except Exception:
|
| 642 |
+
return False
|
| 643 |
+
|
| 644 |
+
|
| 645 |
+
def build_app(catalog: Catalog) -> gr.Blocks:
|
| 646 |
+
with gr.Blocks(title="Skills Cloud") as demo:
|
| 647 |
+
with gr.Row():
|
| 648 |
+
gr.Markdown(f"# ☁️ Skills Cloud\n\n{TAGLINE}")
|
| 649 |
+
if _oauth_available():
|
| 650 |
+
gr.LoginButton(scale=0)
|
| 651 |
+
with gr.Row():
|
| 652 |
+
repo_box = gr.Textbox(
|
| 653 |
+
label="Load skills from a GitHub repo",
|
| 654 |
+
placeholder="owner/repo · owner/repo@branch · https://github.com/owner/repo",
|
| 655 |
+
scale=4,
|
| 656 |
+
interactive=True,
|
| 657 |
+
)
|
| 658 |
+
load_btn = gr.Button("Load skills", variant="secondary", scale=1)
|
| 659 |
+
status = gr.Markdown("")
|
| 660 |
+
view_state = gr.State(CatalogView(catalog))
|
| 661 |
+
|
| 662 |
+
@gr.render(inputs=view_state)
|
| 663 |
+
def render_catalog(view: CatalogView) -> None:
|
| 664 |
+
current = view.catalog
|
| 665 |
+
_render_issues(current)
|
| 666 |
+
sources = sorted({s.source for s in current.skills if s.source != "bundled"})
|
| 667 |
+
if sources:
|
| 668 |
+
labels = [ALL_SOURCES, BUILTIN_SOURCE_LABEL, *sources]
|
| 669 |
+
active = (
|
| 670 |
+
ALL_SOURCES
|
| 671 |
+
if view.source_filter is None
|
| 672 |
+
else BUILTIN_SOURCE_LABEL
|
| 673 |
+
if view.source_filter == "bundled"
|
| 674 |
+
else view.source_filter
|
| 675 |
+
)
|
| 676 |
+
source_dd = gr.Dropdown(
|
| 677 |
+
choices=labels, value=active, label="Showing skills from", interactive=True
|
| 678 |
+
)
|
| 679 |
+
|
| 680 |
+
def on_source_change(choice: str, current_view: CatalogView) -> CatalogView:
|
| 681 |
+
mapped = (
|
| 682 |
+
None
|
| 683 |
+
if choice == ALL_SOURCES
|
| 684 |
+
else "bundled"
|
| 685 |
+
if choice == BUILTIN_SOURCE_LABEL
|
| 686 |
+
else choice
|
| 687 |
+
)
|
| 688 |
+
return CatalogView(current_view.catalog, None, mapped)
|
| 689 |
+
|
| 690 |
+
source_dd.change(
|
| 691 |
+
on_source_change, inputs=[source_dd, view_state], outputs=view_state
|
| 692 |
+
)
|
| 693 |
+
skills = view.visible_skills
|
| 694 |
+
if not skills:
|
| 695 |
+
gr.Markdown(
|
| 696 |
+
"**No skills found.** Add a `skills/<name>/SKILL.md` package, or load a "
|
| 697 |
+
"GitHub repo above — see the README for the format."
|
| 698 |
+
)
|
| 699 |
+
return
|
| 700 |
+
with gr.Tabs(selected=view.selected):
|
| 701 |
+
for spec in skills:
|
| 702 |
+
with gr.Tab(f"{spec.emoji} {spec.name}", id=spec.slug):
|
| 703 |
+
gr.Markdown(spec.description)
|
| 704 |
+
if spec.inferred:
|
| 705 |
+
_build_flex_panel(spec)
|
| 706 |
+
elif spec.output == "text":
|
| 707 |
+
_build_text_panel(spec)
|
| 708 |
+
else:
|
| 709 |
+
_build_image_panel(spec)
|
| 710 |
+
|
| 711 |
+
load_btn.click(
|
| 712 |
+
load_repo_into_catalog,
|
| 713 |
+
inputs=[repo_box, view_state],
|
| 714 |
+
outputs=[view_state, status],
|
| 715 |
+
)
|
| 716 |
+
repo_box.submit(
|
| 717 |
+
load_repo_into_catalog,
|
| 718 |
+
inputs=[repo_box, view_state],
|
| 719 |
+
outputs=[view_state, status],
|
| 720 |
+
)
|
| 721 |
+
gr.Markdown(
|
| 722 |
+
f"*v{__version__} — keys live only in your session, never stored. Loaded repos are "
|
| 723 |
+
"session-only. Duplicate this Space to make it yours and add your own skills.*"
|
| 724 |
+
)
|
| 725 |
+
return demo
|
src/skills_cloud/zerogpu.py
ADDED
|
@@ -0,0 +1,185 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""Run models on this Space's own GPU via ZeroGPU — no keys, visitor quota.
|
| 2 |
+
|
| 3 |
+
Active only when SPACES_ZERO_GPU is set (a deployed ZeroGPU Space) or
|
| 4 |
+
SKILLS_CLOUD_LOCAL_PIPELINES=1 (CPU dev mode with small models). Model ids
|
| 5 |
+
come from env vars — Space owners swap models without code changes:
|
| 6 |
+
|
| 7 |
+
ZEROGPU_TEXT_MODEL (default Qwen/Qwen3-4B-Instruct-2507)
|
| 8 |
+
ZEROGPU_IMAGE_MODEL (default black-forest-labs/FLUX.1-schnell)
|
| 9 |
+
ZEROGPU_IMAGE_STEPS / ZEROGPU_GUIDANCE (schnell-appropriate defaults)
|
| 10 |
+
|
| 11 |
+
ZeroGPU pattern notes (verified against spaces lib): `import spaces` must
|
| 12 |
+
happen before torch initialises CUDA; @spaces.GPU supports generator
|
| 13 |
+
functions (streaming); off-Space the decorator degrades gracefully. Heavy
|
| 14 |
+
imports stay inside functions so the base app never pays for torch.
|
| 15 |
+
"""
|
| 16 |
+
|
| 17 |
+
from __future__ import annotations
|
| 18 |
+
|
| 19 |
+
import contextlib
|
| 20 |
+
import os
|
| 21 |
+
from collections.abc import Iterator
|
| 22 |
+
from typing import TYPE_CHECKING, Any
|
| 23 |
+
|
| 24 |
+
from skills_cloud.backends import BackendError, ProviderError, UnsupportedOperationError
|
| 25 |
+
|
| 26 |
+
if TYPE_CHECKING:
|
| 27 |
+
from PIL import Image
|
| 28 |
+
|
| 29 |
+
if os.getenv("SPACES_ZERO_GPU"): # must precede any torch import on ZeroGPU
|
| 30 |
+
import spaces # noqa: F401
|
| 31 |
+
|
| 32 |
+
|
| 33 |
+
def is_zerogpu_available() -> bool:
|
| 34 |
+
return bool(os.getenv("SPACES_ZERO_GPU") or os.getenv("SKILLS_CLOUD_LOCAL_PIPELINES"))
|
| 35 |
+
|
| 36 |
+
|
| 37 |
+
def zerogpu_text_model() -> str:
|
| 38 |
+
return os.getenv("ZEROGPU_TEXT_MODEL", "Qwen/Qwen3-4B-Instruct-2507")
|
| 39 |
+
|
| 40 |
+
|
| 41 |
+
def zerogpu_image_model() -> str:
|
| 42 |
+
return os.getenv("ZEROGPU_IMAGE_MODEL", "black-forest-labs/FLUX.1-schnell")
|
| 43 |
+
|
| 44 |
+
|
| 45 |
+
def _on_spaces() -> bool:
|
| 46 |
+
return bool(os.getenv("SPACES_ZERO_GPU"))
|
| 47 |
+
|
| 48 |
+
|
| 49 |
+
def _gpu_decorator(duration: int):
|
| 50 |
+
"""spaces.GPU when the lib is present; identity otherwise (local CPU dev)."""
|
| 51 |
+
try:
|
| 52 |
+
import spaces
|
| 53 |
+
|
| 54 |
+
return spaces.GPU(duration=duration)
|
| 55 |
+
except Exception:
|
| 56 |
+
return lambda fn: fn
|
| 57 |
+
|
| 58 |
+
|
| 59 |
+
_pipelines: dict[str, Any] = {}
|
| 60 |
+
|
| 61 |
+
|
| 62 |
+
def _get_text_pipeline():
|
| 63 |
+
if "text" not in _pipelines:
|
| 64 |
+
import torch
|
| 65 |
+
from transformers import AutoModelForCausalLM, AutoTokenizer
|
| 66 |
+
|
| 67 |
+
model_id = zerogpu_text_model()
|
| 68 |
+
tokenizer = AutoTokenizer.from_pretrained(model_id)
|
| 69 |
+
dtype = torch.bfloat16 if _on_spaces() else torch.float32
|
| 70 |
+
model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype=dtype)
|
| 71 |
+
if _on_spaces():
|
| 72 |
+
model = model.to("cuda") # intercepted by ZeroGPU's torch patching
|
| 73 |
+
_pipelines["text"] = (tokenizer, model)
|
| 74 |
+
return _pipelines["text"]
|
| 75 |
+
|
| 76 |
+
|
| 77 |
+
def _get_image_pipeline():
|
| 78 |
+
if "image" not in _pipelines:
|
| 79 |
+
import torch
|
| 80 |
+
from diffusers import AutoPipelineForText2Image
|
| 81 |
+
|
| 82 |
+
dtype = torch.bfloat16 if _on_spaces() else torch.float32
|
| 83 |
+
pipe = AutoPipelineForText2Image.from_pretrained(zerogpu_image_model(), torch_dtype=dtype)
|
| 84 |
+
if _on_spaces():
|
| 85 |
+
pipe = pipe.to("cuda")
|
| 86 |
+
_pipelines["image"] = pipe
|
| 87 |
+
return _pipelines["image"]
|
| 88 |
+
|
| 89 |
+
|
| 90 |
+
def warmup_pipelines() -> None:
|
| 91 |
+
"""Eagerly load models at Space startup so the first visitor doesn't wait.
|
| 92 |
+
|
| 93 |
+
No-op off ZeroGPU. Failures are non-fatal: the app must still boot so the
|
| 94 |
+
API-backed paths keep working (failure shows up on first GPU run instead).
|
| 95 |
+
"""
|
| 96 |
+
if not _on_spaces():
|
| 97 |
+
return
|
| 98 |
+
for loader in (_get_text_pipeline, _get_image_pipeline):
|
| 99 |
+
with contextlib.suppress(Exception): # deliberate: degraded, not dead
|
| 100 |
+
loader()
|
| 101 |
+
|
| 102 |
+
|
| 103 |
+
def _stream_chat_impl(prompt: str, max_tokens: int) -> Iterator[str]:
|
| 104 |
+
from threading import Thread
|
| 105 |
+
|
| 106 |
+
from transformers import TextIteratorStreamer
|
| 107 |
+
|
| 108 |
+
tokenizer, model = _get_text_pipeline()
|
| 109 |
+
inputs = tokenizer.apply_chat_template(
|
| 110 |
+
[{"role": "user", "content": prompt}],
|
| 111 |
+
add_generation_prompt=True,
|
| 112 |
+
return_tensors="pt",
|
| 113 |
+
).to(model.device)
|
| 114 |
+
streamer = TextIteratorStreamer(tokenizer, skip_prompt=True, skip_special_tokens=True)
|
| 115 |
+
thread = Thread(
|
| 116 |
+
target=model.generate,
|
| 117 |
+
kwargs={"input_ids": inputs, "max_new_tokens": max_tokens, "streamer": streamer},
|
| 118 |
+
)
|
| 119 |
+
thread.start()
|
| 120 |
+
try:
|
| 121 |
+
yield from streamer
|
| 122 |
+
finally:
|
| 123 |
+
thread.join()
|
| 124 |
+
|
| 125 |
+
|
| 126 |
+
def _generate_image_impl(prompt: str) -> Image.Image:
|
| 127 |
+
pipe = _get_image_pipeline()
|
| 128 |
+
steps = int(os.getenv("ZEROGPU_IMAGE_STEPS", "4")) # FLUX.1-schnell default
|
| 129 |
+
guidance = float(os.getenv("ZEROGPU_GUIDANCE", "0.0"))
|
| 130 |
+
result = pipe(prompt, num_inference_steps=steps, guidance_scale=guidance)
|
| 131 |
+
return result.images[0]
|
| 132 |
+
|
| 133 |
+
|
| 134 |
+
# GPU-decorated entry points. Durations are generous but bounded — quota is
|
| 135 |
+
# the visitor's, and a runaway generation should not eat it silently.
|
| 136 |
+
_run_chat = _gpu_decorator(duration=120)(_stream_chat_impl)
|
| 137 |
+
_run_image = _gpu_decorator(duration=90)(_generate_image_impl)
|
| 138 |
+
|
| 139 |
+
|
| 140 |
+
def _is_gradio_error(exc: Exception) -> bool:
|
| 141 |
+
"""spaces raises gradio errors for quota exhaustion — let those surface
|
| 142 |
+
verbatim (they carry the wait time). Duck-typed: this module must not
|
| 143 |
+
import gradio."""
|
| 144 |
+
return type(exc).__module__.startswith("gradio")
|
| 145 |
+
|
| 146 |
+
|
| 147 |
+
class ZeroGPUBackend:
|
| 148 |
+
"""Backend protocol implementation running on the Space's own hardware.
|
| 149 |
+
|
| 150 |
+
``api_key`` is accepted for protocol compatibility and ignored — that is
|
| 151 |
+
the whole point. ``model`` is likewise fixed to the preloaded pipeline.
|
| 152 |
+
"""
|
| 153 |
+
|
| 154 |
+
id = "zerogpu"
|
| 155 |
+
label = "Space GPU"
|
| 156 |
+
supports_image = True
|
| 157 |
+
|
| 158 |
+
def stream_text(self, req, *, api_key: str) -> Iterator[str]:
|
| 159 |
+
try:
|
| 160 |
+
yield from _run_chat(req.user, req.max_tokens)
|
| 161 |
+
except BackendError:
|
| 162 |
+
raise
|
| 163 |
+
except Exception as exc:
|
| 164 |
+
if _is_gradio_error(exc):
|
| 165 |
+
raise
|
| 166 |
+
raise ProviderError(f"Space GPU generation failed ({type(exc).__name__}).") from exc
|
| 167 |
+
|
| 168 |
+
def generate_image(
|
| 169 |
+
self, prompt: str, *, model: str, api_key: str, image: Image.Image | None = None
|
| 170 |
+
) -> Image.Image:
|
| 171 |
+
if image is not None:
|
| 172 |
+
raise UnsupportedOperationError(
|
| 173 |
+
"Space GPU image editing is not available yet — "
|
| 174 |
+
"use Hugging Face Inference for image-to-image."
|
| 175 |
+
)
|
| 176 |
+
try:
|
| 177 |
+
return _run_image(prompt)
|
| 178 |
+
except BackendError:
|
| 179 |
+
raise
|
| 180 |
+
except Exception as exc:
|
| 181 |
+
if _is_gradio_error(exc):
|
| 182 |
+
raise
|
| 183 |
+
raise ProviderError(
|
| 184 |
+
f"Space GPU image generation failed ({type(exc).__name__})."
|
| 185 |
+
) from exc
|