chenglu commited on
Commit
04778b8
·
verified ·
1 Parent(s): 0723bdd

Deploy Skills Cloud

Browse files
README.md CHANGED
@@ -1,14 +1,101 @@
1
  ---
2
  title: Skills Cloud
3
- emoji: 📊
4
- colorFrom: pink
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
- license: apache-2.0
 
 
12
  ---
13
 
14
- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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