Deploy Token Holdem final validation Space

.agents/skills/art-asset-generator/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: art-asset-generator
+description: Generate final visual image assets for Token Hold'em and save them as real repo files under assets/. Use when Codex is asked to generate actual image files, create tavern background art, create LLM avatar portraits, create poker table assets, create transparent PNG/WebP sprites, use image generation to create assets, save generated assets into the repo, update the asset manifest, integrate generated art through CSS/HTML/token_holdem/render.py, or replace CSS placeholders with real art assets. This skill must produce actual generated files when image generation is available, not just prompts.
+---
+
+# Art Asset Generator
+
+## Overview
+
+Generate, save, optimize, manifest, integrate, and QA production image assets for Token Hold'em. Prefer real repo artifacts over prompt-only output; use prompt-only fallbacks only when Codex image generation is unavailable in the current environment.
+
+## Coordination
+
+Load companion skills when their responsibility applies:
+
+- Use `pixel-tavern-art-director` for visual direction, palette, lighting, composition, negative prompts, and QA criteria.
+- Use `image-asset-pipeline` for manifest shape, naming, asset slots, dimensions, optimization, and UI integration rules.
+- Use `llm-avatar-personification` for LLM avatar concepts that avoid exact company logos, mascots, or wordmarks.
+- Use `poker-table-ui-layout` for seat/table/community-card constraints before making table, overlay, chip, or card assets.
+- Use `gradio-game-scene-composer` when integrating assets into full-page Gradio scene structure or CSS layering.
+
+Always inspect current repo state before generating:
+
+- `assets/token-holdem/manifest.json`
+- `token_holdem/render.py`
+- `app.py`
+- Any existing `docs/token-holdem-*` prompt, persona, or visual direction files
+- Existing generated assets under `assets/`
+
+## Workflow
+
+1. Read visual direction, layout constraints, and the asset manifest.
+2. Identify the exact asset slot to generate, including manifest `id`, target use site, and displayed CSS size.
+3. Decide dimensions, format, alpha, filename, and destination path before generation.
+4. Use Codex's available image generation capability to create the actual image file.
+5. Save the generated file under the repo's `assets/` tree, normally `assets/token-holdem/`.
+6. Inspect the generated asset visually. Check art direction, transparency, crop safety, readability, and absence of baked UI text or logos.
+7. Regenerate or refine poor assets instead of accepting unusable output.
+8. Optimize or convert when needed for Hugging Face Spaces. Prefer PNG for alpha-critical art and WebP for full-scene/background assets when quality remains acceptable.
+9. Update `assets/token-holdem/manifest.json` with filename, path, dimensions, format, purpose/role, where it is used, source, prompt summary, and QA notes.
+10. Wire the asset into the Gradio app through CSS, HTML, or helpers in `token_holdem/render.py` where appropriate.
+11. Run checks that prove the app still imports and loads. Prefer `uv run pytest`; for UI-impacting changes, also run `uv run python app.py` and inspect the Gradio URL.
+
+## Asset Decisions
+
+Use these defaults unless the manifest or layout requires something else:
+
+- Tavern backgrounds: `1920x1080` or `2560x1440`, no alpha, full-scene composition, dark quiet center for table/cards/seats.
+- Poker table art: `1536x864` or `2048x1152`, transparent PNG when layered over tavern art, no baked cards, chips, labels, or pot text.
+- LLM avatars: `512x512` transparent PNG or WebP with alpha when supported, consistent camera angle and tavern rim light, no exact company marks.
+- Sprites, chips, candles, props, overlays, seat frames: transparent PNG with tight but safe padding.
+- Card backs: high-resolution rectangular PNG/WebP matching the current CSS card proportions, no ranks, suits, brands, watermarks, or readable words.
+
+Use kebab-case filenames with dimensions, for example `tavern-bg-main-1920x1080.webp`, `table-felt-top-1536x864.png`, `avatar-gpt-architect-neutral-512.png`, or `prop-candle-lit-256x512.png`.
+
+## Image Generation Requirements
+
+The expected output is actual generated image files committed to the repo workspace. Do not stop at writing prompts when image generation is available.
+
+When calling image generation, include:
+
+- Token Hold'em as the project context.
+- Exact canvas dimensions and aspect ratio.
+- Pixel-art cozy tavern poker style, warm candle/hearth lighting, premium game UI readability.
+- Required alpha/transparent background when appropriate.
+- Composition safe areas and any live UI that must remain readable.
+- Negative constraints: no text unless explicitly required, no logos, no exact company mascots, no watermarks, no baked cards/chips/pot/player labels unless the asset is specifically that object.
+
+If image generation is unavailable, explicitly state that limitation and provide fallback output only:
+
+- Final generation prompts.
+- Planned filenames and destination paths.
+- Manifest entries marked as pending generation.
+- Integration notes marked blocked until assets exist.
+
+## Manifest Update
+
+Preserve the existing manifest schema. For generated assets, ensure each relevant entry has:
+
+- `file`: repo-root-relative or app-servable path used by the code.
+- `dimensions`: actual pixel dimensions.
+- `format`: actual file format.
+- `alpha`: whether the final file has transparency.
+- `source`: mark as generated, including the generation tool/model if known.
+- `purpose` or `role`: what the file is for.
+- `usedBy` or equivalent notes: CSS selector, HTML/render helper, or file where it is wired.
+- `prompt` or concise prompt summary.
+- `qa`: brief checks performed and any known limitations.
+
+If the existing manifest entry is a placeholder, update it in place rather than creating a duplicate ID. Keep IDs stable.
+
+## Integration Rules
+
+Wire assets only where they improve the actual game UI:
+
+- Use CSS background layers for tavern scene art and table surfaces.
+- Use `<img>` or render helper output for semantic or positioned assets only when needed.
+- Keep live gameplay information rendered by code: cards, pot, player names, stacks, action state, buttons, timers, and status labels.
+- Set explicit dimensions, aspect ratios, `object-fit`, `object-position`, and `pointer-events` behavior.
+- Preserve the current 8-seat layout: human seat bottom-center, seats 1-7 around the table, community cards in the fixed center zone, action buttons outside table art.
+- Avoid external asset URLs. All final assets must live under the repo.
+
+## QA Output
+
+End asset-generation tasks with a concise report:
+
+- Files generated and saved.
+- Manifest entries changed.
+- App integration locations changed, such as CSS selectors or `token_holdem/render.py` helpers.
+- Visual QA notes: match to art direction, readability, transparency, crop safety, no prohibited logos/text.
+- Checks run and results.

.agents/skills/art-asset-generator/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Art Asset Generator"
+  short_description: "Generate final Token Hold'em art assets"
+  default_prompt: "Use $art-asset-generator to generate and integrate a final Token Hold'em image asset."

.agents/skills/cozy-game-polish-qa/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: cozy-game-polish-qa
+description: Review and improve Token Hold'em final UI polish, UX quality, game feel, animations, hover/focus states, readability, accessibility, responsive behavior, and premium cozy tavern presentation. Use when Codex is asked for UI polish, UX review, game feel, animations, hover states, readability, accessibility, final quality pass, polish punch list, prioritized improvements, mobile checks, or a premium feel review for the Token Hold'em app.
+---
+
+# Cozy Game Polish QA
+
+## Purpose
+
+Use this skill to make Token Hold'em feel like a polished cozy tavern poker game rather than a functional demo. Focus on clarity, charm, responsiveness, readable game state, accessible interactions, and satisfying feedback.
+
+## Workflow
+
+1. Inspect the running app or relevant UI code before making recommendations. If feasible, run the app and capture desktop and mobile views.
+2. Review the experience as a player, not only as an implementer: evaluate whether the current turn, pot, stacks, bet size, player status, available actions, and result state are immediately legible.
+3. Produce a prioritized polish punch list before editing when the request is review-only. If the user asks to improve the app, implement the highest-impact items directly.
+4. Keep changes coherent with a cozy tavern poker fantasy: warm, tactile, readable, playful, and calm under repeated play.
+5. Verify the result after changes with screenshots or interaction checks when a browser is available.
+
+## Review Checklist
+
+### Readability and Game State
+
+- Ensure the active player, dealer/button, blinds, folded/all-in/sitting-out states, pot, current bet, call amount, and winner/result messages are visible without hunting.
+- Prefer concise table labels over verbose explanatory text.
+- Make numeric values scannable with consistent formatting, spacing, and alignment.
+- Check that cards, chips, player names, and action controls remain readable against textured or illustrated backgrounds.
+- Avoid hiding essential state inside hover-only UI.
+
+### Interaction Feel
+
+- Add clear hover, active, disabled, selected, focus-visible, and loading states for buttons, cards, seats, and controls.
+- Make primary actions feel deliberate: call/check/bet/raise/fold should have distinct weight and clear affordance.
+- Use transitions for state changes that benefit comprehension, such as chips moving to the pot, active seat changes, revealed cards, winner highlight, and hand reset.
+- Keep animation durations short enough for repeated play, usually 120-300ms for UI feedback and 300-700ms for celebratory or spatial motion.
+- Respect `prefers-reduced-motion`; provide non-motion emphasis such as color, outline, glow, or opacity changes.
+
+### Cozy Tavern Premium Feel
+
+- Look for tactile material cues: felt, wood, brass, parchment, candlelight, soft shadows, bevels, chip depth, and warm highlights.
+- Use charm in small doses: subtle ambient details, satisfying chip/card motion, clear win celebration, and personable status copy.
+- Avoid clutter, novelty fonts for critical text, overdone glow, muddy contrast, and single-hue palettes.
+- Make the first screen feel like the game is already alive: table centered, players seated, core controls visible, and no empty demo scaffolding.
+
+### Accessibility
+
+- Verify text contrast for critical controls and state labels.
+- Ensure all interactive elements are keyboard reachable with visible focus.
+- Use semantic buttons for actions and avoid click-only divs.
+- Ensure disabled controls communicate why an action is unavailable through nearby state or labels.
+- Confirm target sizes are comfortable on touch screens, roughly 44px minimum for primary controls.
+
+### Mobile and Responsive
+
+- Check narrow screens for overlapping cards, clipped buttons, cramped labels, and unreadable chip counts.
+- Prioritize the current player hand, available actions, pot/current bet, and active opponent status on mobile.
+- Let decorative tavern elements yield space before game-critical information does.
+- Use stable dimensions for cards, chips, seats, toolbars, and controls so hover states and changing labels do not shift the layout.
+
+## Output Format
+
+When reviewing, return:
+
+- `Polish punch list`: grouped by visual polish, game-state clarity, interaction feel, accessibility, and responsive behavior.
+- `Prioritized improvements`: order by player impact and implementation risk, with `P0`, `P1`, or `P2`.
+- `Animation recommendations`: include what should move, why it helps, suggested duration/easing, and reduced-motion fallback.
+- `Mobile/responsive checks`: list specific viewports or layout states to test.
+- `Premium feel review`: summarize whether the current build feels like a cozy tavern poker game and name the biggest missing ingredient.
+
+When editing code, include a concise final summary of changed files and verification performed.

.agents/skills/cozy-game-polish-qa/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Cozy Game Polish QA"
+  short_description: "Review cozy poker UI polish and game feel"
+  default_prompt: "Use $cozy-game-polish-qa to run a final polish pass on Token Hold'em."

.agents/skills/gradio-game-scene-composer/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: gradio-game-scene-composer
+description: Turn Gradio apps into full-page, immersive, game-like scenes using custom HTML, CSS, and layered layout architecture. Use when Codex is asked for full-page game UI, immersive Gradio layout, replacing generic Gradio panels, background scene composition, HUD/sidebar/action bar layout, CSS layering, z-index strategy, responsive game scene design, or Token Hold'em tavern poker scene composition.
+---
+
+# Gradio Game Scene Composer
+
+## Purpose
+
+Use this skill to make a Gradio app feel like an integrated game screen rather than a demo. For Token Hold'em, the tavern environment should be the full-page background, with the poker table, avatars, HUD panels, speech bubbles, sidebars, and action buttons layered above it.
+
+Preserve gameplay behavior. Do not change poker engine logic, state transitions, or callback semantics unless the user explicitly asks. Prefer edits to render helpers, CSS, HTML templates, layout wrappers, and component placement.
+
+## First Pass
+
+1. Inspect `app.py` and rendering/layout helpers before editing. In Token Hold'em, start with `token_holdem/render.py` for HTML/CSS table rendering and only touch `token_holdem/engine.py` if a rendering bug proves engine-adjacent.
+2. Identify which Gradio components are functional controls or outputs, then decide whether each belongs in the game scene, a HUD layer, a side drawer, an action bar, or a hidden plumbing role.
+3. Keep Gradio event wiring intact. Move or restyle components through `elem_id`, `elem_classes`, layout containers, `gr.HTML`, and CSS rather than rewriting callbacks.
+4. Produce or follow the scene plan before large edits: scene layout architecture, DOM layer plan, CSS strategy, breakpoints, component integration, and checklist.
+
+## Scene Architecture
+
+Use a root scene shell that owns the viewport and isolates game visuals from generic Gradio framing:
+
+```html
+<div class="game-scene">
+  <div class="scene-bg"></div>
+  <main class="scene-stage">
+    <section class="table-layer">...</section>
+    <section class="avatar-layer">...</section>
+    <section class="speech-layer">...</section>
+  </main>
+  <aside class="hud hud-left">...</aside>
+  <aside class="hud hud-right">...</aside>
+  <footer class="action-bar">...</footer>
+</div>
+```
+
+Map the app's actual DOM to this model. If Gradio must render controls outside the custom HTML block, style its rows/columns as scene overlays with stable IDs/classes.
+
+Recommended layer order:
+
+1. `scene-bg`: tavern environment, full viewport, non-interactive.
+2. `scene-lighting`: optional vignette/candlelight/material overlays, non-interactive.
+3. `scene-stage`: poker table and player positions.
+4. `table-felt` and card/chip objects.
+5. `avatar-layer`: player portraits and status badges.
+6. `speech-layer`: bubbles, model thoughts, current action callouts.
+7. `hud` panels: hand status, logs, settings, history, model info.
+8. `action-bar`: player controls, bet slider/input, primary actions.
+9. `modal/toast` layer: blocking dialogs and transient alerts.
+
+Use explicit z-index tokens instead of scattered numbers:
+
+```css
+:root {
+  --z-bg: 0;
+  --z-stage: 10;
+  --z-table: 20;
+  --z-avatars: 30;
+  --z-speech: 40;
+  --z-hud: 50;
+  --z-actions: 60;
+  --z-modal: 100;
+}
+```
+
+## CSS Strategy
+
+- Make the app root fill the viewport: set `min-height: 100dvh` on the Gradio container and the scene shell.
+- Hide or neutralize generic demo framing only inside the app scope. Avoid global CSS that breaks Gradio internals, dropdowns, modals, or accessibility.
+- Use CSS Grid for page-level composition: background, stage, left/right HUD, bottom action bar.
+- Use absolute positioning only inside stable scene containers such as the poker table or avatar layer.
+- Use Flexbox for compact HUD panel content, button groups, chip rows, and speech bubble internals.
+- Use stable dimensions with `clamp()`, `aspect-ratio`, `minmax()`, and fixed card/control slots so changing labels do not shift the scene.
+- Keep decorative backgrounds behind readable UI. Add scrims, shadows, or panel surfaces where text crosses detailed art.
+- Prefer class and ID hooks on Gradio components. Avoid brittle selectors based on generated DOM depth unless no better hook exists.
+
+Example page grid:
+
+```css
+.game-scene {
+  min-height: 100dvh;
+  display: grid;
+  grid-template-columns: minmax(220px, 18vw) 1fr minmax(260px, 22vw);
+  grid-template-rows: minmax(0, 1fr) auto;
+  grid-template-areas:
+    "left stage right"
+    "actions actions actions";
+  position: relative;
+  overflow: hidden;
+}
+```
+
+## Responsive Breakpoints
+
+Plan at least three states:
+
+- Desktop wide: tavern fills the page, table centered, side HUDs visible, action bar fixed along the bottom.
+- Tablet or narrow desktop: collapse one sidebar below or into a drawer; keep the table and action bar dominant.
+- Mobile portrait: prioritize human hand, pot/current turn, action controls, and active opponent. Move logs/history into tabs, accordions, or a drawer.
+
+Use responsive rules that preserve game legibility:
+
+- Keep primary action controls at comfortable touch size, around 44px minimum.
+- Reduce decorative tavern details before shrinking cards, chip counts, or player state below readability.
+- Check long model names, large stack values, verbose action text, and disabled button labels.
+- Avoid `100vh` alone on mobile; prefer `100dvh` with fallbacks if needed.
+
+## Gradio Integration
+
+- Use `gr.Blocks(css=...)` or a linked CSS file for the scene system; keep large CSS in helpers or constants if the repo already does.
+- Assign `elem_id` or `elem_classes` to Gradio components that need scene placement.
+- Use `gr.HTML` for complex layered visuals that are output-only, such as the tavern/table scene.
+- Keep interactive controls as real Gradio components when they drive callbacks. Restyle and reposition them instead of replacing them with inert HTML.
+- If custom HTML buttons are unavoidable, bridge them carefully without breaking existing event wiring; otherwise avoid this path.
+- Keep hidden state components and callback dependencies present even if visually hidden. Use accessible hiding patterns where appropriate.
+- Verify Gradio overlays, dropdown menus, and disabled states still render above the scene and remain clickable.
+
+## Token Hold'em Constraints
+
+- Do not change deterministic poker rules in `token_holdem/engine.py` for visual scene work.
+- Keep exactly 8 seats unless the user explicitly requests a gameplay change.
+- Keep seat 0 as the human bottom-center and seats 1-7 as LLM opponents around the table.
+- Keep community cards in the fixed center table zone.
+- Keep action buttons outside the table art as Gradio controls, visually integrated into the action bar.
+- Preserve callback inputs/outputs in `app.py`; if moving components, keep their variables and event bindings intact.
+
+## Implementation Checklist
+
+When using this skill, produce or execute this checklist:
+
+1. Define the full-screen scene shell and decide which existing Gradio blocks map to each scene layer.
+2. Add stable DOM hooks: IDs/classes for scene root, stage, table, sidebars, HUD panels, logs, speech bubbles, and actions.
+3. Establish z-index tokens and ensure non-interactive visual layers use `pointer-events: none`.
+4. Build the CSS grid/flex structure for desktop, tablet, and mobile breakpoints.
+5. Integrate the poker table and avatars into the scene stage without changing game state logic.
+6. Place Gradio controls into the HUD/action layer while preserving event wiring.
+7. Add readable surfaces, scrims, and contrast rules over the tavern background.
+8. Check overflow, clipping, focus states, disabled states, and dropdown/modal stacking.
+9. Run the app and inspect desktop plus mobile viewport screenshots when feasible.
+10. Run the relevant tests, usually `uv run pytest` for Token Hold'em.
+
+## Expected Output
+
+For planning requests, return:
+
+- `Scene layout architecture`: root shell, regions, and responsibilities.
+- `DOM layer plan`: ordered layer list with z-index and interaction behavior.
+- `CSS grid/flex strategy`: desktop structure and responsive adjustments.
+- `Responsive breakpoints`: concrete viewport behaviors and priorities.
+- `Gradio component integration plan`: which components become scene HTML, HUD, sidebars, action bar, or hidden state.
+- `Implementation checklist`: ordered, testable steps.
+
+For implementation requests, make scoped code changes, then summarize changed files and verification performed.

.agents/skills/gradio-game-scene-composer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Gradio Game Scene Composer"
+  short_description: "Compose immersive Gradio game scenes"
+  default_prompt: "Use $gradio-game-scene-composer to turn this Gradio app into a full-screen layered game scene."

.agents/skills/gradio/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: gradio
+description: Build Gradio web UIs and demos in Python. Use when creating, modifying, debugging, or answering questions about Gradio and its capabilties, components, event listeners, or layouts.
+---
+
+# Gradio
+
+Gradio is a Python library for building interactive web UIs and ML demos. This skill covers the core API, patterns, and examples.
+
+## References
+- `references/examples.md` -  Illustrative examples showcasing the core Gradio API.
+- `references/api-signatures.md` - API signatures of commonly used components.
+- `references/event-listeners.md` - API signatures of events supported by each component.
+
+## Guides
+
+Detailed guides on specific topics (read these when relevant):
+
+- [Quickstart](https://www.gradio.app/guides/quickstart)
+- [The Interface Class](https://www.gradio.app/guides/the-interface-class)
+- [Blocks and Event Listeners](https://www.gradio.app/guides/blocks-and-event-listeners)
+- [Controlling Layout](https://www.gradio.app/guides/controlling-layout)
+- [More Blocks Features](https://www.gradio.app/guides/more-blocks-features)
+- [Custom CSS and JS](https://www.gradio.app/guides/custom-CSS-and-JS)
+- [Streaming Outputs](https://www.gradio.app/guides/streaming-outputs)
+- [Streaming Inputs](https://www.gradio.app/guides/streaming-inputs)
+- [Sharing Your App](https://www.gradio.app/guides/sharing-your-app)
+- [Custom HTML Components](https://www.gradio.app/guides/custom-HTML-components)
+- [Getting Started with the Python Client](https://www.gradio.app/guides/getting-started-with-the-python-client)
+- [Getting Started with the JS Client](https://www.gradio.app/guides/getting-started-with-the-js-client)
+
+## Core Patterns
+
+**Interface** (high-level): wraps a function with input/output components.
+
+```python
+import gradio as gr
+
+def greet(name):
+    return f"Hello {name}!"
+
+gr.Interface(fn=greet, inputs="text", outputs="text").launch()
+```
+
+**Blocks** (low-level): flexible layout with explicit event wiring.
+
+```python
+import gradio as gr
+
+with gr.Blocks() as demo:
+    name = gr.Textbox(label="Name")
+    output = gr.Textbox(label="Greeting")
+    btn = gr.Button("Greet")
+    btn.click(fn=lambda n: f"Hello {n}!", inputs=name, outputs=output)
+
+demo.launch()
+```
+
+**ChatInterface**: high-level wrapper for chatbot UIs.
+
+```python
+import gradio as gr
+
+def respond(message, history):
+    return f"You said: {message}"
+
+gr.ChatInterface(fn=respond).launch()
+```
+
+## Custom HTML Components
+
+If a task requires significant customization of an existing component or a component that doesn't exist in Gradio, you can create one with `gr.HTML`. It supports `html_template` (with `${}` JS expressions and `{{}}` Handlebars syntax), `css_template` for scoped styles, and `js_on_load` for interactivity — where `props.value` updates the component value and `trigger('event_name')` fires Gradio events. For reuse, subclass `gr.HTML` and define `api_info()` for API/MCP support. 
+
+See the [full guide](https://www.gradio.app/guides/custom-HTML-components) as well as example in `references/examples.md`
+
+## Server Mode
+
+Use `gr.Server` instead of gr.Blocks when the users requests any of the following:
+- Completely custom UI (your own HTML, React, Svelte, etc.) powered by Gradio's backend.
+- Full control of FastAPI server (custom GET/POST routes, middleware, dependency injection) alongside Gradio API endpoints
+
+See the [full guide](https://www.gradio.app/guides/server-mode) and example in `references/examples.md`.
+
+If the user's use case can be handled by Gradio's built-in components or customizable HTML components, prefer not to use `gr.Server`.

.agents/skills/gradio/references/api-signatures.md

@@ -0,0 +1,115 @@
+# Component API Signatures
+
+Quick reference for common Gradio component constructors.
+
+## `Textbox`
+
+```python
+Textbox(value: str | I18nData | Callable | None = None, type: Literal['text', 'password', 'email'] = "text", lines: int = 1, max_lines: int | None = None, placeholder: str | I18nData | None = None, label: str | I18nData | None = None, info: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, interactive: bool | None = None, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, autofocus: bool = False, autoscroll: bool = True, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", text_align: Literal['left', 'right'] | None = None, rtl: bool = False, buttons: list[Literal['copy'] | Button] | None = None, max_length: int | None = None, submit_btn: str | bool | None = False, stop_btn: str | bool | None = False, html_attributes: InputHTMLAttributes | None = None)
+```
+
+Creates a textarea for user to enter string input or display string output.
+
+## `Number`
+
+```python
+Number(value: float | Callable | None = None, label: str | I18nData | None = None, placeholder: str | I18nData | None = None, info: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, interactive: bool | None = None, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", buttons: list[Button] | None = None, precision: int | None = None, minimum: float | None = None, maximum: float | None = None, step: float = 1)
+```
+
+Creates a numeric field for user to enter numbers as input or display numeric output.
+
+## `Slider`
+
+```python
+Slider(minimum: float = 0, maximum: float = 100, value: float | Callable | None = None, step: float | None = None, precision: int | None = None, label: str | I18nData | None = None, info: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, interactive: bool | None = None, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", randomize: bool = False, buttons: list[Literal['reset']] | None = None)
+```
+
+Creates a slider that ranges from {minimum} to {maximum} with a step size of {step}.
+
+## `Checkbox`
+
+```python
+Checkbox(value: bool | Callable = False, label: str | I18nData | None = None, info: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, interactive: bool | None = None, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", buttons: list[Button] | None = None)
+```
+
+Creates a checkbox that can be set to `True` or `False`. Can be used as an input to pass a boolean value to a function or as an output to display a boolean value.
+
+## `Dropdown`
+
+```python
+Dropdown(choices: Sequence[str | int | float | tuple[str | I18nData, str | int | float]] | None = None, value: str | int | float | Sequence[str | int | float] | Callable | DefaultValue | None = DefaultValue(), type: Literal['value', 'index'] = "value", multiselect: bool | None = None, allow_custom_value: bool = False, max_choices: int | None = None, filterable: bool = True, label: str | I18nData | None = None, info: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, interactive: bool | None = None, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", buttons: list[Button] | None = None)
+```
+
+Creates a dropdown of choices from which a single entry or multiple entries can be selected (as an input component) or displayed (as an output component).
+
+## `Radio`
+
+```python
+Radio(choices: Sequence[str | int | float | tuple[str | I18nData, str | int | float]] | None = None, value: str | int | float | Callable | None = None, type: Literal['value', 'index'] = "value", label: str | I18nData | None = None, info: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, interactive: bool | None = None, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", rtl: bool = False, buttons: list[Button] | None = None)
+```
+
+Creates a set of (string or numeric type) radio buttons of which only one can be selected.
+
+## `Image`
+
+```python
+Image(value: str | PIL.Image.Image | np.ndarray | Callable | None = None, format: str = "webp", height: int | str | None = None, width: int | str | None = None, image_mode: Literal['1', 'L', 'P', 'RGB', 'RGBA', 'CMYK', 'YCbCr', 'LAB', 'HSV', 'I', 'F'] | None = "RGB", sources: list[Literal['upload', 'webcam', 'clipboard']] | Literal['upload', 'webcam', 'clipboard'] | None = None, type: Literal['numpy', 'pil', 'filepath'] = "numpy", label: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, buttons: list[Literal['download', 'share', 'fullscreen'] | Button] | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, interactive: bool | None = None, visible: bool | Literal['hidden'] = True, streaming: bool = False, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", webcam_options: WebcamOptions | None = None, placeholder: str | None = None, watermark: WatermarkOptions | None = None)
+```
+
+Creates an image component that can be used to upload images (as an input) or display images (as an output).
+
+## `Audio`
+
+```python
+Audio(value: str | Path | tuple[int, np.ndarray] | Callable | None = None, sources: list[Literal['upload', 'microphone']] | Literal['upload', 'microphone'] | None = None, type: Literal['numpy', 'filepath'] = "numpy", label: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, interactive: bool | None = None, visible: bool | Literal['hidden'] = True, streaming: bool = False, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", format: Literal['wav', 'mp3'] | None = None, autoplay: bool = False, editable: bool = True, buttons: list[Literal['download', 'share'] | Button] | None = None, waveform_options: WaveformOptions | dict | None = None, loop: bool = False, recording: bool = False, subtitles: str | Path | list[dict[str, Any]] | None = None, playback_position: float = 0)
+```
+
+Creates an audio component that can be used to upload/record audio (as an input) or display audio (as an output).
+
+## `Video`
+
+```python
+Video(value: str | Path | Callable | None = None, format: str | None = None, sources: list[Literal['upload', 'webcam']] | Literal['upload', 'webcam'] | None = None, height: int | str | None = None, width: int | str | None = None, label: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, interactive: bool | None = None, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", webcam_options: WebcamOptions | None = None, include_audio: bool | None = None, autoplay: bool = False, buttons: list[Literal['download', 'share'] | Button] | None = None, loop: bool = False, streaming: bool = False, watermark: WatermarkOptions | None = None, subtitles: str | Path | list[dict[str, Any]] | None = None, playback_position: float = 0)
+```
+
+Creates a video component that can be used to upload/record videos (as an input) or display videos (as an output). For the video to be playable in the browser it must have a compatible container and codec combination. Allowed combinations are .mp4 with h264 codec, .ogg with theora codec, and .webm with vp9 codec. If the component detects that the output video would not be playable in the browser it will attempt to convert it to a playable mp4 video. If the conversion fails, the original video is returned.
+
+## `File`
+
+```python
+File(value: str | list[str] | Callable | None = None, file_count: Literal['single', 'multiple', 'directory'] = "single", file_types: list[str] | None = None, type: Literal['filepath', 'binary'] = "filepath", label: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, height: int | str | float | None = None, interactive: bool | None = None, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", allow_reordering: bool = False, buttons: list[Button] | None = None)
+```
+
+Creates a file component that allows uploading one or more generic files (when used as an input) or displaying generic files or URLs for download (as output).       Demo: zip_files, zip_to_json
+
+## `Chatbot`
+
+```python
+Chatbot(value: list[MessageDict | Message] | Callable | None = None, label: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, autoscroll: bool = True, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", height: int | str | None = 400, resizable: bool = False, max_height: int | str | None = None, min_height: int | str | None = None, editable: Literal['user', 'all'] | None = None, latex_delimiters: list[dict[str, str | bool]] | None = None, rtl: bool = False, buttons: list[Literal['share', 'copy', 'copy_all'] | Button] | None = None, watermark: str | None = None, avatar_images: tuple[str | Path | None, str | Path | None] | None = None, sanitize_html: bool = True, render_markdown: bool = True, feedback_options: list[str] | tuple[str, ...] | None = ('Like', 'Dislike'), feedback_value: Sequence[str | None] | None = None, line_breaks: bool = True, layout: Literal['panel', 'bubble'] | None = None, placeholder: str | None = None, examples: list[ExampleMessage] | None = None, allow_file_downloads: bool = True, group_consecutive_messages: bool = True, allow_tags: list[str] | bool = True, reasoning_tags: list[tuple[str, str]] | None = None, like_user_message: bool = False)
+```
+
+Creates a chatbot that displays user-submitted messages and responses. Supports a subset of Markdown including bold, italics, code, tables. Also supports audio/video/image files, which are displayed in the Chatbot, and other kinds of files which are displayed as links. This component is usually used as an output component.
+
+## `Button`
+
+```python
+Button(value: str | I18nData | Callable = "Run", every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, variant: Literal['primary', 'secondary', 'stop', 'huggingface'] = "secondary", size: Literal['sm', 'md', 'lg'] = "lg", icon: str | Path | None = None, link: str | None = None, link_target: Literal['_self', '_blank', '_parent', '_top'] = "_self", visible: bool | Literal['hidden'] = True, interactive: bool = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", scale: int | None = None, min_width: int | None = None)
+```
+
+Creates a button that can be assigned arbitrary .click() events. The value (label) of the button can be used as an input to the function (rarely used) or set via the output of a function.
+
+## `Markdown`
+
+```python
+Markdown(value: str | I18nData | Callable | None = None, label: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, scale: int | None = None, min_width: int | None = None, rtl: bool = False, latex_delimiters: list[dict[str, str | bool]] | None = None, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", sanitize_html: bool = True, line_breaks: bool = False, header_links: bool = False, height: int | str | None = None, max_height: int | str | None = None, min_height: int | str | None = None, buttons: list[Literal['copy']] | None = None, container: bool = False, padding: bool = False)
+```
+
+Used to render arbitrary Markdown output. Can also render latex enclosed by dollar signs as well as code blocks with syntax highlighting. Supported languages are bash, c, cpp, go, java, javascript, json, php, python, rust, sql, and yaml. As this component does not accept user input, it is rarely used as an input component.
+
+## `HTML`
+
+```python
+HTML(value: Any | Callable | None = None, label: str | I18nData | None = None, html_template: str = "${value}", css_template: str = "", js_on_load: str | None = "element.addEventListener('click', function() { trigger('click') });", apply_default_css: bool = True, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool = False, scale: int | None = None, min_width: int | None = None, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", min_height: int | None = None, max_height: int | None = None, container: bool = False, padding: bool = False, autoscroll: bool = False, buttons: list[Button] | None = None, head: str | None = None, server_functions: list[Callable] | None = None, props: Any)
+```
+
+Creates a component with arbitrary HTML. Can include CSS and JavaScript to create highly customized and interactive components.

.agents/skills/gradio/references/event-listeners.md

@@ -0,0 +1,132 @@
+# Event Listeners
+
+Events supported by each component.
+
+
+## Event Listener Signature
+
+```python
+component.event_name(
+    fn: Callable | None | Literal["decorator"] = "decorator",
+    inputs: Component | Sequence[Component] | set[Component] | None = None,
+    outputs: Component | Sequence[Component] | set[Component] | None = None,
+    api_name: str | None = None,
+    api_description: str | None | Literal[False] = None,
+    scroll_to_output: bool = False,
+    show_progress: Literal["full", "minimal", "hidden"] = "full",
+    show_progress_on: Component | Sequence[Component] | None = None,
+    queue: bool = True,
+    batch: bool = False,
+    max_batch_size: int = 4,
+    preprocess: bool = True,
+    postprocess: bool = True,
+    cancels: dict[str, Any] | list[dict[str, Any]] | None = None,
+    trigger_mode: Literal["once", "multiple", "always_last"] | None = None,
+    js: str | Literal[True] | None = None,
+    concurrency_limit: int | None | Literal["default"] = "default",
+    concurrency_id: str | None = None,
+    api_visibility: Literal["public", "private", "undocumented"] = "public",
+    time_limit: int | None = None,
+    stream_every: float = 0.5,
+    key: int | str | tuple[int | str, ...] | None = None,
+    validator: Callable | None = None,
+) -> Dependency
+```
+
+## Supported Events by Component
+
+- **AnnotatedImage**: change, select
+
+- **Audio**: stream, change, clear, play, pause, stop, pause, start_recording, pause_recording, stop_recording, upload, input
+
+- **BarPlot**: change, select, double_click
+
+- **BrowserState**: change
+
+- **Button**: change, click
+
+- **Chatbot**: change, select, like, retry, undo, example_select, option_select, clear, copy, edit
+
+- **Checkbox**: change, input, select
+
+- **CheckboxGroup**: change, input, select
+
+- **ClearButton**: change, click
+
+- **Code**: change, input, focus, blur
+
+- **ColorPicker**: change, input, release, submit, focus, blur
+
+- **Dataframe**: change, input, select, edit
+
+- **Dataset**: change, click, select
+
+- **DateTime**: change, submit
+
+- **DeepLinkButton**: change, click
+
+- **Dialogue**: change, input, submit
+
+- **DownloadButton**: change, click
+
+- **Dropdown**: change, input, select, focus, blur, key_up
+
+- **DuplicateButton**: change, click
+
+- **File**: change, select, clear, upload, delete, download
+
+- **FileExplorer**: change, input, select
+
+- **Gallery**: select, upload, change, delete, preview_close, preview_open
+
+- **HTML**: change, input, click, double_click, submit, stop, edit, clear, play, pause, end, start_recording, pause_recording, stop_recording, focus, blur, upload, release, select, stream, like, example_select, option_select, load, key_up, apply, delete, tick, undo, retry, expand, collapse, download, copy
+
+- **HighlightedText**: change, select
+
+- **Image**: clear, change, stream, select, upload, input
+
+- **ImageEditor**: clear, change, input, select, upload, apply
+
+- **ImageSlider**: clear, change, stream, select, upload, input
+
+- **JSON**: change
+
+- **Label**: change, select
+
+- **LinePlot**: change, select, double_click
+
+- **LoginButton**: change, click
+
+- **Markdown**: change, copy
+
+- **Model3D**: change, upload, edit, clear
+
+- **MultimodalTextbox**: change, input, select, submit, focus, blur, stop
+
+- **Navbar**: change
+
+- **Number**: change, input, submit, focus, blur
+
+- **ParamViewer**: change, upload
+
+- **Plot**: change
+
+- **Radio**: select, change, input
+
+- **ScatterPlot**: change, select, double_click
+
+- **SimpleImage**: clear, change, upload
+
+- **Slider**: change, input, release
+
+- **State**: change
+
+- **Textbox**: change, input, select, submit, focus, blur, stop, copy
+
+- **Timer**: change, tick
+
+- **UploadButton**: change, click, upload
+
+- **Video**: change, clear, start_recording, stop_recording, stop, play, pause, end, upload, input
+
+- **WorkflowCanvas**: change

.agents/skills/gradio/references/examples.md

@@ -0,0 +1,613 @@
+# Gradio End-to-End Examples
+
+Complete working Gradio apps for reference.
+
+## Blocks Essay Simple
+
+```python
+import gradio as gr
+
+def change_textbox(choice):
+    if choice == "short":
+        return gr.Textbox(lines=2, visible=True)
+    elif choice == "long":
+        return gr.Textbox(lines=8, visible=True, value="Lorem ipsum dolor sit amet")
+    else:
+        return gr.Textbox(visible=False)
+
+with gr.Blocks() as demo:
+    radio = gr.Radio(
+        ["short", "long", "none"], label="What kind of essay would you like to write?"
+    )
+    text = gr.Textbox(lines=2, interactive=True, buttons=["copy"])
+    radio.change(fn=change_textbox, inputs=radio, outputs=text)
+
+demo.launch()
+```
+
+## Blocks Flipper
+
+```python
+import numpy as np
+import gradio as gr
+
+def flip_text(x):
+    return x[::-1]
+
+def flip_image(x):
+    return np.fliplr(x)
+
+with gr.Blocks() as demo:
+    gr.Markdown("Flip text or image files using this demo.")
+    with gr.Tab("Flip Text"):
+        text_input = gr.Textbox()
+        text_output = gr.Textbox()
+        text_button = gr.Button("Flip")
+    with gr.Tab("Flip Image"):
+        with gr.Row():
+            image_input = gr.Image()
+            image_output = gr.Image()
+        image_button = gr.Button("Flip")
+
+    with gr.Accordion("Open for More!", open=False):
+        gr.Markdown("Look at me...")
+        temp_slider = gr.Slider(
+            0, 1,
+            value=0.1,
+            step=0.1,
+            interactive=True,
+            label="Slide me",
+        )
+
+    text_button.click(flip_text, inputs=text_input, outputs=text_output)
+    image_button.click(flip_image, inputs=image_input, outputs=image_output)
+
+demo.launch()
+```
+
+## Blocks Form
+
+```python
+import gradio as gr
+
+with gr.Blocks() as demo:
+    name_box = gr.Textbox(label="Name")
+    age_box = gr.Number(label="Age", minimum=0, maximum=100)
+    symptoms_box = gr.CheckboxGroup(["Cough", "Fever", "Runny Nose"])
+    submit_btn = gr.Button("Submit")
+
+    with gr.Column(visible=False) as output_col:
+        diagnosis_box = gr.Textbox(label="Diagnosis")
+        patient_summary_box = gr.Textbox(label="Patient Summary")
+
+    def submit(name, age, symptoms):
+        return {
+            submit_btn: gr.Button(visible=False),
+            output_col: gr.Column(visible=True),
+            diagnosis_box: "covid" if "Cough" in symptoms else "flu",
+            patient_summary_box: f"{name}, {age} y/o",
+        }
+
+    submit_btn.click(
+        submit,
+        [name_box, age_box, symptoms_box],
+        [submit_btn, diagnosis_box, patient_summary_box, output_col],
+    )
+
+demo.launch()
+```
+
+## Blocks Hello
+
+```python
+import gradio as gr
+
+def welcome(name):
+    return f"Welcome to Gradio, {name}!"
+
+with gr.Blocks() as demo:
+    gr.Markdown(
+    """
+    # Hello World!
+    Start typing below to see the output.
+    """)
+    inp = gr.Textbox(placeholder="What is your name?")
+    out = gr.Textbox()
+    inp.change(welcome, inp, out)
+
+demo.launch()
+```
+
+## Blocks Layout
+
+```python
+import gradio as gr
+
+demo = gr.Blocks()
+
+with demo:
+    with gr.Row():
+        gr.Image(interactive=True, scale=2)
+        gr.Image()
+    with gr.Row():
+        gr.Textbox(label="Text")
+        gr.Number(label="Count", scale=2)
+        gr.Radio(choices=["One", "Two"])
+    with gr.Row():
+        gr.Button("500", scale=0, min_width=500)
+        gr.Button("A", scale=0)
+        gr.Button("grow")
+    with gr.Row():
+        gr.Textbox()
+        gr.Textbox()
+        gr.Button()
+    with gr.Row():
+        with gr.Row():
+            with gr.Column():
+                gr.Textbox(label="Text")
+                gr.Number(label="Count")
+                gr.Radio(choices=["One", "Two"])
+            gr.Image()
+            with gr.Column():
+                gr.Image(interactive=True)
+                gr.Image()
+    gr.Image()
+    gr.Textbox(label="Text")
+    gr.Number(label="Count")
+    gr.Radio(choices=["One", "Two"])
+
+demo.launch()
+```
+
+## Calculator
+
+```python
+import gradio as gr
+
+def calculator(num1, operation, num2):
+    if operation == "add":
+        return num1 + num2
+    elif operation == "subtract":
+        return num1 - num2
+    elif operation == "multiply":
+        return num1 * num2
+    elif operation == "divide":
+        if num2 == 0:
+            raise gr.Error("Cannot divide by zero!")
+        return num1 / num2
+
+demo = gr.Interface(
+    calculator,
+    [
+        "number",
+        gr.Radio(["add", "subtract", "multiply", "divide"]),
+        "number"
+    ],
+    "number",
+    examples=[
+        [45, "add", 3],
+        [3.14, "divide", 2],
+        [144, "multiply", 2.5],
+        [0, "subtract", 1.2],
+    ],
+    title="Toy Calculator",
+    description="Here's a sample toy calculator.",
+    api_name="predict"
+)
+
+demo.launch()
+```
+
+## Chatbot Simple
+
+```python
+import gradio as gr
+import random
+import time
+
+with gr.Blocks() as demo:
+    chatbot = gr.Chatbot()
+    msg = gr.Textbox()
+    clear = gr.ClearButton([msg, chatbot])
+
+    def respond(message, chat_history):
+        bot_message = random.choice(["How are you?", "Today is a great day", "I'm very hungry"])
+        chat_history.append({"role": "user", "content": message})
+        chat_history.append({"role": "assistant", "content": bot_message})
+        time.sleep(2)
+        return "", chat_history
+
+    msg.submit(respond, [msg, chatbot], [msg, chatbot])
+
+demo.launch()
+```
+
+## Chatbot Streaming
+
+```python
+import gradio as gr
+import random
+import time
+
+with gr.Blocks() as demo:
+    chatbot = gr.Chatbot()
+    msg = gr.Textbox()
+    clear = gr.Button("Clear")
+
+    def user(user_message, history: list):
+        return "", history + [{"role": "user", "content": user_message}]
+
+    def bot(history: list):
+        bot_message = random.choice(["How are you?", "I love you", "I'm very hungry"])
+        history.append({"role": "assistant", "content": ""})
+        for character in bot_message:
+            history[-1]['content'] += character
+            time.sleep(0.05)
+            yield history
+
+    msg.submit(user, [msg, chatbot], [msg, chatbot], queue=False).then(
+        bot, chatbot, chatbot
+    )
+    clear.click(lambda: None, None, chatbot, queue=False)
+
+demo.launch()
+```
+
+## Custom Css
+
+```python
+import gradio as gr
+
+with gr.Blocks() as demo:
+    with gr.Column(elem_classes="cool-col"):
+        gr.Markdown("### Gradio Demo with Custom CSS", elem_classes="darktest")
+        gr.Markdown(
+            elem_classes="markdown",
+            value="Resize the browser window to see the CSS media query in action.",
+        )
+
+if __name__ == "__main__":
+    demo.launch(css_paths=["demo/custom_css/custom_css.css"])
+```
+
+## Fake Diffusion
+
+```python
+import gradio as gr
+import numpy as np
+import time
+
+def fake_diffusion(steps):
+    rng = np.random.default_rng()
+    for i in range(steps):
+        time.sleep(1)
+        image = rng.random(size=(600, 600, 3))
+        yield image
+    image = np.ones((1000,1000,3), np.uint8)
+    image[:] = [255, 124, 0]
+    yield image
+
+demo = gr.Interface(fake_diffusion,
+                    inputs=gr.Slider(1, 10, 3, step=1),
+                    outputs="image",
+                    api_name="predict")
+
+demo.launch()
+```
+
+## Hello World
+
+```python
+import gradio as gr
+
+
+def greet(name):
+    return "Hello " + name + "!"
+
+
+demo = gr.Interface(fn=greet, inputs="textbox", outputs="textbox", api_name="predict")
+
+demo.launch()
+```
+
+## Image Editor
+
+```python
+import gradio as gr
+import time
+
+
+def sleep(im):
+    time.sleep(5)
+    return [im["background"], im["layers"][0], im["layers"][1], im["composite"]]
+
+
+def predict(im):
+    return im["composite"]
+
+
+with gr.Blocks() as demo:
+    with gr.Row():
+        im = gr.ImageEditor(
+            type="numpy",
+        )
+        im_preview = gr.Image()
+    n_upload = gr.Number(0, label="Number of upload events", step=1)
+    n_change = gr.Number(0, label="Number of change events", step=1)
+    n_input = gr.Number(0, label="Number of input events", step=1)
+
+    im.upload(lambda x: x + 1, outputs=n_upload, inputs=n_upload)
+    im.change(lambda x: x + 1, outputs=n_change, inputs=n_change)
+    im.input(lambda x: x + 1, outputs=n_input, inputs=n_input)
+    im.change(predict, outputs=im_preview, inputs=im, show_progress="hidden")
+
+demo.launch()
+```
+
+## On Listener Decorator
+
+```python
+import gradio as gr
+
+with gr.Blocks() as demo:
+    name = gr.Textbox(label="Name")
+    output = gr.Textbox(label="Output Box")
+    greet_btn = gr.Button("Greet")
+
+    @gr.on(triggers=[name.submit, greet_btn.click], inputs=name, outputs=output)
+    def greet(name):
+        return "Hello " + name + "!"
+
+demo.launch()
+```
+
+## Render Merge
+
+```python
+import gradio as gr
+import time
+
+with gr.Blocks() as demo:
+    text_count = gr.Slider(1, 5, value=1, step=1, label="Textbox Count")
+
+    @gr.render(inputs=text_count)
+    def render_count(count):
+        boxes = []
+        for i in range(count):
+            box = gr.Textbox(label=f"Box {i}")
+            boxes.append(box)
+
+        def merge(*args):
+            time.sleep(0.2)  # simulate a delay
+            return " ".join(args)
+
+        merge_btn.click(merge, boxes, output)
+
+        def clear():
+            time.sleep(0.2)  # simulate a delay
+            return [" "] * count
+
+        clear_btn.click(clear, None, boxes)
+
+        def countup():
+            time.sleep(0.2)  # simulate a delay
+            return list(range(count))
+
+        count_btn.click(countup, None, boxes, queue=False)
+
+    with gr.Row():
+        merge_btn = gr.Button("Merge")
+        clear_btn = gr.Button("Clear")
+        count_btn = gr.Button("Count")
+
+    output = gr.Textbox()
+
+demo.launch()
+```
+
+## Reverse Audio 2
+
+```python
+import gradio as gr
+import numpy as np
+
+def reverse_audio(audio):
+    sr, data = audio
+    return (sr, np.flipud(data))
+
+demo = gr.Interface(fn=reverse_audio,
+                    inputs="microphone",
+                    outputs="audio", api_name="predict")
+
+demo.launch()
+```
+
+## Sepia Filter
+
+```python
+import numpy as np
+import gradio as gr
+
+def sepia(input_img):
+    sepia_filter = np.array([
+        [0.393, 0.769, 0.189],
+        [0.349, 0.686, 0.168],
+        [0.272, 0.534, 0.131]
+    ])
+    sepia_img = input_img.dot(sepia_filter.T)
+    sepia_img /= sepia_img.max()
+    return sepia_img
+
+demo = gr.Interface(sepia, gr.Image(), "image", api_name="predict")
+demo.launch()
+```
+
+## Sort Records
+
+```python
+import gradio as gr
+
+def sort_records(records):
+    return records.sort("Quantity")
+
+demo = gr.Interface(
+    sort_records,
+    gr.Dataframe(
+        headers=["Item", "Quantity"],
+        datatype=["str", "number"],  
+        row_count=3,
+        column_count=2,
+        column_limits=(2, 2),
+        type="polars"
+    ),
+    "dataframe",
+    description="Sort by Quantity"
+)
+
+demo.launch()
+```
+
+## Streaming Simple
+
+```python
+import gradio as gr
+
+with gr.Blocks() as demo:
+    with gr.Row():
+        with gr.Column():
+            input_img = gr.Image(label="Input", sources="webcam")
+        with gr.Column():
+            output_img = gr.Image(label="Output")
+        input_img.stream(lambda s: s, input_img, output_img, time_limit=15, stream_every=0.1, concurrency_limit=30)
+
+if __name__ == "__main__":
+
+    demo.launch()
+```
+
+## Tabbed Interface Lite
+
+```python
+import gradio as gr
+
+hello_world = gr.Interface(lambda name: "Hello " + name, "text", "text", api_name="predict")
+bye_world = gr.Interface(lambda name: "Bye " + name, "text", "text", api_name="predict")
+chat = gr.ChatInterface(lambda *args: "Hello " + args[0], api_name="chat")
+
+demo = gr.TabbedInterface([hello_world, bye_world, chat], ["Hello World", "Bye World", "Chat"])
+
+demo.launch()
+```
+
+## Tax Calculator
+
+```python
+import gradio as gr
+
+def tax_calculator(income, marital_status, assets):
+    tax_brackets = [(10, 0), (25, 8), (60, 12), (120, 20), (250, 30)]
+    total_deductible = sum(cost for cost, deductible in zip(assets["Cost"], assets["Deductible"]) if deductible)
+    taxable_income = income - total_deductible
+
+    total_tax = 0
+    for bracket, rate in tax_brackets:
+        if taxable_income > bracket:
+            total_tax += (taxable_income - bracket) * rate / 100
+
+    if marital_status == "Married":
+        total_tax *= 0.75
+    elif marital_status == "Divorced":
+        total_tax *= 0.8
+
+    return round(total_tax)
+
+demo = gr.Interface(
+    tax_calculator,
+    [
+        "number",
+        gr.Radio(["Single", "Married", "Divorced"]),
+        gr.Dataframe(
+            headers=["Item", "Cost", "Deductible"],
+            datatype=["str", "number", "bool"],  
+            label="Assets Purchased this Year",
+        ),
+    ],
+    gr.Number(label="Tax due"),
+    examples=[
+        [10000, "Married", [["Suit", 5000, True], ["Laptop (for work)", 800, False], ["Car", 1800, True]]],
+        [80000, "Single", [["Suit", 800, True], ["Watch", 1800, True], ["Food", 800, True]]],
+    ],
+    live=True,
+    api_name="predict"
+)
+
+demo.launch()
+```
+
+## Timer Simple
+
+```python
+import gradio as gr
+import random
+import time
+
+with gr.Blocks() as demo:
+  timer = gr.Timer(1)
+  timestamp = gr.Number(label="Time")
+  timer.tick(lambda: round(time.time()), outputs=timestamp, api_name="timestamp")
+
+  number = gr.Number(lambda: random.randint(1, 10), every=timer, label="Random Number")
+  with gr.Row():
+    gr.Button("Start").click(lambda: gr.Timer(active=True), None, timer)
+    gr.Button("Stop").click(lambda: gr.Timer(active=False), None, timer)
+    gr.Button("Go Fast").click(lambda: 0.2, None, timer)
+
+if __name__ == "__main__":
+  demo.launch()
+```
+
+## Variable Outputs
+
+```python
+import gradio as gr
+
+max_textboxes = 10
+
+def variable_outputs(k):
+    k = int(k)
+    return [gr.Textbox(visible=True)]*k + [gr.Textbox(visible=False)]*(max_textboxes-k)
+
+with gr.Blocks() as demo:
+    s = gr.Slider(1, max_textboxes, value=max_textboxes, step=1, label="How many textboxes to show:")
+    textboxes = []
+    for i in range(max_textboxes):
+        t = gr.Textbox(f"Textbox {i}")
+        textboxes.append(t)
+
+    s.change(variable_outputs, s, textboxes)
+
+if __name__ == "__main__":
+   demo.launch()
+```
+
+## Video Identity
+
+```python
+import gradio as gr
+from gradio.media import get_video
+
+def video_identity(video):
+    return video
+
+# get_video() returns file paths to sample media included with Gradio
+demo = gr.Interface(video_identity,
+                    gr.Video(),
+                    "playable_video",
+                    examples=[
+                        get_video("world.mp4")
+                    ],
+                    cache_examples=True,
+                    api_name="predict",)
+
+demo.launch()
+```

.agents/skills/hf-cli/.hf-skill-manifest.json

@@ -0,0 +1,4 @@
+{
+  "installed_revision": "7bf59b7f85b79c74207b10d5e425934514e8b089",
+  "schema_version": 1
+}

.agents/skills/hf-cli/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: hf-cli
+description: "Hugging Face Hub CLI (`hf`) for downloading, uploading, and managing models, datasets, spaces, buckets, repos, papers, jobs, and more on the Hugging Face Hub. Use when: handling authentication; managing local cache; managing Hugging Face Buckets; running or scheduling jobs on Hugging Face infrastructure; managing Hugging Face repos; discussions and pull requests; browsing models, datasets and spaces; reading, searching, or browsing academic papers; managing collections; querying datasets; configuring spaces; setting up webhooks; or deploying and managing HF Inference Endpoints. Make sure to use this skill whenever the user mentions 'hf', 'huggingface', 'Hugging Face', 'huggingface-cli', or 'hugging face cli', or wants to do anything related to the Hugging Face ecosystem and to AI and ML in general. Also use for cloud storage needs like training checkpoints, data pipelines, or agent traces. Use even if the user doesn't explicitly ask for a CLI command. Replaces the deprecated `huggingface-cli`."
+---
+
+Install: `curl -LsSf https://hf.co/cli/install.sh | bash -s`.
+
+The Hugging Face Hub CLI tool `hf` is available. IMPORTANT: The `hf` command replaces the deprecated `huggingface-cli` command.
+
+Use `hf --help` to view available functions. Note that auth commands are now all under `hf auth` e.g. `hf auth whoami`.
+
+Generated with `huggingface_hub v1.19.0`. Run `hf skills add --force` to regenerate.
+
+## Commands
+
+- `hf cp SRC` — Copy files between local paths, repositories, and buckets. `[--format [auto|human|agent|json|quiet]]`
+- `hf download REPO_ID` — Download files from the Hub. `[--type [model|dataset|space] --revision TEXT --include TEXT --exclude TEXT --cache-dir TEXT --local-dir TEXT --force-download --dry-run --max-workers INTEGER --format [auto|human|agent|json|quiet]]`
+- `hf env` — Print information about the environment. `[--format [auto|human|agent|json|quiet]]`
+- `hf sync` — Sync files between local directory and a bucket. `[--delete --ignore-times --ignore-sizes --plan TEXT --apply TEXT --dry-run --include TEXT --exclude TEXT --filter-from TEXT --existing --ignore-existing --verbose --format [auto|human|agent|json|quiet]]`
+- `hf update` — Update the `hf` CLI to the latest version. `[--format [auto|human|agent|json|quiet]]`
+- `hf upload REPO_ID` — Upload a file or a folder to the Hub. Recommended for single-commit uploads. `[--type [model|dataset|space] --revision TEXT --private --include TEXT --exclude TEXT --delete TEXT --commit-message TEXT --commit-description TEXT --create-pr --every FLOAT --format [auto|human|agent|json|quiet]]`
+- `hf upload-large-folder REPO_ID LOCAL_PATH` — Upload a large folder to the Hub. Recommended for resumable uploads. `[--type [model|dataset|space] --revision TEXT --private --include TEXT --exclude TEXT --num-workers INTEGER --no-report --no-bars --format [auto|human|agent|json|quiet]]`
+- `hf version` — Print information about the hf version. `[--format [auto|human|agent|json|quiet]]`
+
+### `hf auth` — Manage authentication (login, logout, etc.).
+
+- `hf auth list` — List all stored access tokens. `[--format [auto|human|agent|json|quiet]]`
+- `hf auth login` — Login using a token from huggingface.co/settings/tokens. `[--add-to-git-credential --force --format [auto|human|agent|json|quiet]]`
+- `hf auth logout` — Logout from a specific token. `[--token-name TEXT --format [auto|human|agent|json|quiet]]`
+- `hf auth switch` — Switch between access tokens. `[--token-name TEXT --add-to-git-credential --format [auto|human|agent|json|quiet]]`
+- `hf auth token` — Print the current access token to stdout. `[--format [auto|human|agent|json|quiet]]`
+- `hf auth whoami` — Find out which huggingface.co account you are logged in as. `[--format [auto|human|agent|json|quiet]]`
+
+### `hf buckets` — Commands to interact with buckets.
+
+- `hf buckets cp SRC` — Copy files between local paths, repositories, and buckets. `[--format [auto|human|agent|json|quiet]]`
+- `hf buckets create BUCKET_ID` — Create a new bucket. `[--private --region [us|eu] --exist-ok --format [auto|human|agent|json|quiet]]`
+- `hf buckets delete BUCKET_ID` — Delete a bucket. `[--yes --missing-ok --format [auto|human|agent|json|quiet]]`
+- `hf buckets info BUCKET_ID` — Get info about a bucket. `[--format [auto|human|agent|json|quiet]]`
+- `hf buckets list` — List buckets or files in a bucket. `[--human-readable --tree --recursive --search TEXT --format [auto|human|agent|json|quiet]]`
+- `hf buckets move FROM_ID TO_ID` — Move (rename) a bucket to a new name or namespace. `[--format [auto|human|agent|json|quiet]]`
+- `hf buckets remove ARGUMENT` — Remove files from a bucket. `[--recursive --yes --dry-run --include TEXT --exclude TEXT --format [auto|human|agent|json|quiet]]`
+- `hf buckets sync` — Sync files between local directory and a bucket. `[--delete --ignore-times --ignore-sizes --plan TEXT --apply TEXT --dry-run --include TEXT --exclude TEXT --filter-from TEXT --existing --ignore-existing --verbose --format [auto|human|agent|json|quiet]]`
+
+### `hf cache` — Manage local cache directory.
+
+- `hf cache list` — List cached repositories or revisions. `[--cache-dir TEXT --revisions --filter TEXT --sort [accessed|accessed:asc|accessed:desc|modified|modified:asc|modified:desc|name|name:asc|name:desc|size|size:asc|size:desc] --limit INTEGER --format [auto|human|agent|json|quiet]]`
+- `hf cache prune` — Remove detached revisions from the cache. `[--cache-dir TEXT --yes --dry-run --format [auto|human|agent|json|quiet]]`
+- `hf cache rm TARGETS` — Remove cached repositories or revisions. `[--cache-dir TEXT --yes --dry-run --format [auto|human|agent|json|quiet]]`
+- `hf cache verify REPO_ID` — Verify checksums for a single repo revision from cache or a local directory. `[--type [model|dataset|space] --revision TEXT --cache-dir TEXT --local-dir TEXT --fail-on-missing-files --fail-on-extra-files --format [auto|human|agent|json|quiet]]`
+
+### `hf collections` — Interact with collections on the Hub.
+
+- `hf collections add-item COLLECTION_SLUG ITEM_ID ITEM_TYPE` — Add an item to a collection. `[--note TEXT --exists-ok --format [auto|human|agent|json|quiet]]`
+- `hf collections create TITLE` — Create a new collection on the Hub. `[--namespace TEXT --description TEXT --private --exists-ok --format [auto|human|agent|json|quiet]]`
+- `hf collections delete COLLECTION_SLUG` — Delete a collection from the Hub. `[--missing-ok --format [auto|human|agent|json|quiet]]`
+- `hf collections delete-item COLLECTION_SLUG ITEM_OBJECT_ID` — Delete an item from a collection. `[--missing-ok --format [auto|human|agent|json|quiet]]`
+- `hf collections info COLLECTION_SLUG` — Get info about a collection on the Hub. `[--format [auto|human|agent|json|quiet]]`
+- `hf collections list` — List collections on the Hub. `[--owner TEXT --item TEXT --sort [lastModified|trending|upvotes] --limit INTEGER --format [auto|human|agent|json|quiet]]`
+- `hf collections update COLLECTION_SLUG` — Update a collection's metadata on the Hub. `[--title TEXT --description TEXT --position INTEGER --private --theme TEXT --format [auto|human|agent|json|quiet]]`
+- `hf collections update-item COLLECTION_SLUG ITEM_OBJECT_ID` — Update an item in a collection. `[--note TEXT --position INTEGER --format [auto|human|agent|json|quiet]]`
+
+### `hf datasets` — Interact with datasets on the Hub.
+
+- `hf datasets card DATASET_ID` — Get the dataset card (README) for a dataset on the Hub. `[--metadata --text --format [auto|human|agent|json|quiet]]`
+- `hf datasets info DATASET_ID` — Get info about a dataset on the Hub. `[--revision TEXT --expand TEXT --format [auto|human|agent|json|quiet]]`
+- `hf datasets leaderboard DATASET_ID` — List model scores from a dataset leaderboard. This command helps find the best models for a task or compare models by benchmark scores. Use 'hf datasets ls --filter benchmark:official' to list available leaderboards. `[--limit INTEGER --format [auto|human|agent|json|quiet]]`
+- `hf datasets list` — List datasets on the Hub, or files in a dataset repo. `[--search TEXT --author TEXT --filter TEXT --sort [created_at|downloads|last_modified|likes|trending_score] --limit INTEGER --expand TEXT --human-readable --tree --recursive --revision TEXT --format [auto|human|agent|json|quiet]]`
+- `hf datasets parquet DATASET_ID` — List parquet file URLs available for a dataset. `[--subset TEXT --split TEXT --format [auto|human|agent|json|quiet]]`
+- `hf datasets sql SQL` — Execute a raw SQL query with DuckDB against dataset parquet URLs. `[--format [auto|human|agent|json|quiet]]`
+
+### `hf discussions` — Manage discussions and pull requests on the Hub.
+
+- `hf discussions close REPO_ID NUM` — Close a discussion or pull request. `[--comment TEXT --yes --type [model|dataset|space] --format [auto|human|agent|json|quiet]]`
+- `hf discussions comment REPO_ID NUM` — Comment on a discussion or pull request. `[--body TEXT --body-file PATH --type [model|dataset|space] --format [auto|human|agent|json|quiet]]`
+- `hf discussions create REPO_ID --title TEXT` — Create a new discussion or pull request on a repo. `[--body TEXT --body-file PATH --pull-request --type [model|dataset|space] --format [auto|human|agent|json|quiet]]`
+- `hf discussions diff REPO_ID NUM` — Show the diff of a pull request. `[--type [model|dataset|space] --format [auto|human|agent|json|quiet]]`
+- `hf discussions info REPO_ID NUM` — Get info about a discussion or pull request. `[--type [model|dataset|space] --format [auto|human|agent|json|quiet]]`
+- `hf discussions list REPO_ID` — List discussions and pull requests on a repo. `[--status [open|closed|merged|draft|all] --kind [all|discussion|pull_request] --author TEXT --limit INTEGER --type [model|dataset|space] --format [auto|human|agent|json|quiet]]`
+- `hf discussions merge REPO_ID NUM` — Merge a pull request. `[--comment TEXT --yes --type [model|dataset|space] --format [auto|human|agent|json|quiet]]`
+- `hf discussions rename REPO_ID NUM NEW_TITLE` — Rename a discussion or pull request. `[--type [model|dataset|space] --format [auto|human|agent|json|quiet]]`
+- `hf discussions reopen REPO_ID NUM` — Reopen a closed discussion or pull request. `[--comment TEXT --yes --type [model|dataset|space] --format [auto|human|agent|json|quiet]]`
+
+### `hf endpoints` — Manage Hugging Face Inference Endpoints.
+
+- `hf endpoints catalog deploy --repo TEXT` — Deploy an Inference Endpoint from the Model Catalog. `[--name TEXT --accelerator TEXT --namespace TEXT --format [auto|human|agent|json|quiet]]`
+- `hf endpoints catalog list` — List available Catalog models. `[--format [auto|human|agent|json|quiet]]`
+- `hf endpoints delete NAME` — Delete an Inference Endpoint permanently. `[--namespace TEXT --yes --format [auto|human|agent|json|quiet]]`
+- `hf endpoints deploy NAME --repo TEXT --framework TEXT --accelerator TEXT --instance-size TEXT --instance-type TEXT --region TEXT --vendor TEXT` — Deploy an Inference Endpoint from a Hub repository. `[--namespace TEXT --task TEXT --min-replica INTEGER --max-replica INTEGER --scale-to-zero-timeout INTEGER --scaling-metric [pendingRequests|hardwareUsage] --scaling-threshold FLOAT --format [auto|human|agent|json|quiet]]`
+- `hf endpoints describe NAME` — Get information about an existing endpoint. `[--namespace TEXT --format [auto|human|agent|json|quiet]]`
+- `hf endpoints list` — Lists all Inference Endpoints for the given namespace. `[--namespace TEXT --format [auto|human|agent|json|quiet]]`
+- `hf endpoints pause NAME` — Pause an Inference Endpoint. `[--namespace TEXT --format [auto|human|agent|json|quiet]]`
+- `hf endpoints resume NAME` — Resume an Inference Endpoint. `[--namespace TEXT --fail-if-already-running --format [auto|human|agent|json|quiet]]`
+- `hf endpoints scale-to-zero NAME` — Scale an Inference Endpoint to zero. `[--namespace TEXT --format [auto|human|agent|json|quiet]]`
+- `hf endpoints update NAME` — Update an existing endpoint. `[--namespace TEXT --repo TEXT --accelerator TEXT --instance-size TEXT --instance-type TEXT --framework TEXT --revision TEXT --task TEXT --min-replica INTEGER --max-replica INTEGER --scale-to-zero-timeout INTEGER --scaling-metric [pendingRequests|hardwareUsage] --scaling-threshold FLOAT --format [auto|human|agent|json|quiet]]`
+
+### `hf extensions` — Manage hf CLI extensions.
+
+- `hf extensions exec NAME` — Execute an installed extension.
+- `hf extensions install REPO_ID` — Install an extension from a public GitHub repository. `[--force --format [auto|human|agent|json|quiet]]`
+- `hf extensions list` — List installed extension commands. `[--format [auto|human|agent|json|quiet]]`
+- `hf extensions remove NAME` — Remove an installed extension. `[--format [auto|human|agent|json|quiet]]`
+- `hf extensions search` — Search extensions available on GitHub (tagged with 'hf-extension' topic). `[--format [auto|human|agent|json|quiet]]`
+
+### `hf jobs` — Run and manage Jobs on the Hub.
+
+- `hf jobs cancel JOB_ID` — Cancel a Job `[--namespace TEXT --format [auto|human|agent|json|quiet]]`
+- `hf jobs hardware` — List available hardware options for Jobs `[--format [auto|human|agent|json|quiet]]`
+- `hf jobs inspect JOB_IDS` — Display detailed information on one or more Jobs `[--namespace TEXT --format [auto|human|agent|json|quiet]]`
+- `hf jobs labels JOB_ID` — Update labels on a Job. Replaces all existing labels. `[--label TEXT --clear --namespace TEXT --format [auto|human|agent|json|quiet]]`
+- `hf jobs logs JOB_ID` — Fetch the logs of a Job. `[--follow --tail INTEGER --namespace TEXT --format [auto|human|agent|json|quiet]]`
+- `hf jobs ps` — List Jobs. `[--all --namespace TEXT --filter TEXT --format [auto|human|agent|json|quiet]]`
+- `hf jobs run IMAGE COMMAND` — Run a Job. `[--env TEXT --secrets TEXT --label TEXT --volume TEXT --env-file TEXT --secrets-file TEXT --flavor [cpu-basic|cpu-upgrade|cpu-performance|cpu-xl|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|a100x4|a100x8|h200|h200x2|h200x4|h200x8|rtx-pro-6000|rtx-pro-6000x2|rtx-pro-6000x4|rtx-pro-6000x8] --timeout TEXT --detach --expose INTEGER --namespace TEXT]`
+- `hf jobs scheduled delete SCHEDULED_JOB_ID` — Delete a scheduled Job. `[--namespace TEXT --format [auto|human|agent|json|quiet]]`
+- `hf jobs scheduled inspect SCHEDULED_JOB_IDS` — Display detailed information on one or more scheduled Jobs `[--namespace TEXT --format [auto|human|agent|json|quiet]]`
+- `hf jobs scheduled labels SCHEDULED_JOB_ID` — Update labels on a scheduled Job. Replaces all existing labels. `[--label TEXT --clear --namespace TEXT --format [auto|human|agent|json|quiet]]`
+- `hf jobs scheduled ps` — List scheduled Jobs `[--all --namespace TEXT --filter TEXT --format [auto|human|agent|json|quiet]]`
+- `hf jobs scheduled resume SCHEDULED_JOB_ID` — Resume (unpause) a scheduled Job. `[--namespace TEXT --format [auto|human|agent|json|quiet]]`
+- `hf jobs scheduled run SCHEDULE IMAGE COMMAND` — Schedule a Job. `[--suspend --concurrency --env TEXT --secrets TEXT --label TEXT --volume TEXT --env-file TEXT --secrets-file TEXT --flavor [cpu-basic|cpu-upgrade|cpu-performance|cpu-xl|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|a100x4|a100x8|h200|h200x2|h200x4|h200x8|rtx-pro-6000|rtx-pro-6000x2|rtx-pro-6000x4|rtx-pro-6000x8] --timeout TEXT --expose INTEGER --namespace TEXT]`
+- `hf jobs scheduled suspend SCHEDULED_JOB_ID` — Suspend (pause) a scheduled Job. `[--namespace TEXT --format [auto|human|agent|json|quiet]]`
+- `hf jobs scheduled uv run SCHEDULE SCRIPT` — Run a UV script (local file or URL) on HF infrastructure `[--suspend --concurrency --image TEXT --flavor [cpu-basic|cpu-upgrade|cpu-performance|cpu-xl|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|a100x4|a100x8|h200|h200x2|h200x4|h200x8|rtx-pro-6000|rtx-pro-6000x2|rtx-pro-6000x4|rtx-pro-6000x8] --env TEXT --secrets TEXT --label TEXT --volume TEXT --env-file TEXT --secrets-file TEXT --timeout TEXT --expose INTEGER --namespace TEXT --with TEXT --python TEXT]`
+- `hf jobs stats` — Fetch the resource usage statistics and metrics of Jobs `[--namespace TEXT --format [auto|human|agent|json|quiet]]`
+- `hf jobs uv run SCRIPT` — Run a UV script (local file or URL) on HF infrastructure `[--image TEXT --flavor [cpu-basic|cpu-upgrade|cpu-performance|cpu-xl|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|a100x4|a100x8|h200|h200x2|h200x4|h200x8|rtx-pro-6000|rtx-pro-6000x2|rtx-pro-6000x4|rtx-pro-6000x8] --env TEXT --secrets TEXT --label TEXT --volume TEXT --env-file TEXT --secrets-file TEXT --timeout TEXT --detach --expose INTEGER --namespace TEXT --with TEXT --python TEXT]`
+
+### `hf models` — Interact with models on the Hub.
+
+- `hf models card MODEL_ID` — Get the model card (README) for a model on the Hub. `[--metadata --text --format [auto|human|agent|json|quiet]]`
+- `hf models info MODEL_ID` — Get info about a model on the Hub. `[--revision TEXT --expand TEXT --format [auto|human|agent|json|quiet]]`
+- `hf models list` — List models on the Hub, or files in a model repo. `[--search TEXT --author TEXT --filter TEXT --num-parameters TEXT --sort [created_at|downloads|last_modified|likes|trending_score] --limit INTEGER --expand TEXT --human-readable --tree --recursive --revision TEXT --format [auto|human|agent|json|quiet]]`
+
+### `hf papers` — Interact with papers on the Hub.
+
+- `hf papers info PAPER_ID` — Get info about a paper on the Hub. `[--format [auto|human|agent|json|quiet]]`
+- `hf papers list` — List daily papers on the Hub. `[--date TEXT --week TEXT --month TEXT --submitter TEXT --sort [publishedAt|trending] --limit INTEGER --format [auto|human|agent|json|quiet]]`
+- `hf papers read PAPER_ID` — Read a paper as markdown. `[--format [auto|human|agent|json|quiet]]`
+- `hf papers search QUERY` — Search papers on the Hub. `[--limit INTEGER --format [auto|human|agent|json|quiet]]`
+
+### `hf repos` — Manage repos on the Hub.
+
+- `hf repos branch create REPO_ID BRANCH` — Create a new branch for a repo on the Hub. `[--revision TEXT --type [model|dataset|space] --exist-ok --format [auto|human|agent|json|quiet]]`
+- `hf repos branch delete REPO_ID BRANCH` — Delete a branch from a repo on the Hub. `[--type [model|dataset|space] --format [auto|human|agent|json|quiet]]`
+- `hf repos cp SRC` — Copy files between local paths, repositories, and buckets. `[--format [auto|human|agent|json|quiet]]`
+- `hf repos create REPO_ID` — Create a new repo on the Hub. `[--type [model|dataset|space] --space-sdk TEXT --private --public --protected --exist-ok --resource-group-id TEXT --region [us|eu] --flavor [cpu-basic|cpu-upgrade|zero-a10g|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|a100x4|a100x8] --storage [small|medium|large] --sleep-time INTEGER --secrets TEXT --secrets-file TEXT --env TEXT --env-file TEXT --volume TEXT --format [auto|human|agent|json|quiet]]`
+- `hf repos delete REPO_ID` — Delete a repo from the Hub. This is an irreversible operation. `[--type [model|dataset|space] --missing-ok --yes --format [auto|human|agent|json|quiet]]`
+- `hf repos delete-files REPO_ID PATTERNS` — Delete files from a repo on the Hub. `[--type [model|dataset|space] --revision TEXT --commit-message TEXT --commit-description TEXT --create-pr --format [auto|human|agent|json|quiet]]`
+- `hf repos duplicate FROM_ID` — Duplicate a repo on the Hub (model, dataset, or Space). `[--type [model|dataset|space] --private --public --protected --exist-ok --flavor [cpu-basic|cpu-upgrade|zero-a10g|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|a100x4|a100x8] --storage [small|medium|large] --sleep-time INTEGER --secrets TEXT --secrets-file TEXT --env TEXT --env-file TEXT --volume TEXT --format [auto|human|agent|json|quiet]]`
+- `hf repos list` — List all repos (models, datasets, spaces, buckets) with storage info. `[--namespace TEXT --type [model|dataset|space|bucket] --search TEXT --limit INTEGER --explore --format [auto|human|agent|json|quiet]]`
+- `hf repos move FROM_ID TO_ID` — Move a repository from a namespace to another namespace. `[--type [model|dataset|space] --format [auto|human|agent|json|quiet]]`
+- `hf repos settings REPO_ID` — Update the settings of a repository. `[--gated [auto|manual|false] --private --public --protected --type [model|dataset|space] --format [auto|human|agent|json|quiet]]`
+- `hf repos tag create REPO_ID TAG` — Create a tag for a repo. `[--message TEXT --revision TEXT --type [model|dataset|space] --format [auto|human|agent|json|quiet]]`
+- `hf repos tag delete REPO_ID TAG` — Delete a tag for a repo. `[--yes --type [model|dataset|space] --format [auto|human|agent|json|quiet]]`
+- `hf repos tag list REPO_ID` — List tags for a repo. `[--type [model|dataset|space] --format [auto|human|agent|json|quiet]]`
+
+### `hf skills` — Manage skills for AI assistants.
+
+- `hf skills add` — Download a Hugging Face skill and install it for an AI assistant. `[--claude --global --dest PATH --force --format [auto|human|agent|json|quiet]]`
+- `hf skills list` — List available skills from the Hugging Face marketplace. `[--format [auto|human|agent|json|quiet]]`
+- `hf skills preview` — Print the generated `hf-cli` SKILL.md to stdout. `[--format [auto|human|agent|json|quiet]]`
+- `hf skills update` — Update installed Hugging Face marketplace skills. `[--claude --global --dest PATH --format [auto|human|agent|json|quiet]]`
+
+### `hf spaces` — Interact with spaces on the Hub.
+
+- `hf spaces card SPACE_ID` — Get the Space card (README) for a Space on the Hub. `[--metadata --text --format [auto|human|agent|json|quiet]]`
+- `hf spaces dev-mode SPACE_ID` — Enable or disable dev mode on a Space. `[--stop --format [auto|human|agent|json|quiet]]`
+- `hf spaces hardware` — List available hardware options for Spaces. `[--format [auto|human|agent|json|quiet]]`
+- `hf spaces hot-reload SPACE_ID` — Hot-reload any Python file of a Space without a full rebuild + restart. `[--local-file PATH --skip-checks --skip-summary --format [auto|human|agent|json|quiet]]`
+- `hf spaces info SPACE_ID` — Get info about a space on the Hub. `[--revision TEXT --expand TEXT --format [auto|human|agent|json|quiet]]`
+- `hf spaces list` — List spaces on the Hub, or files in a space repo. `[--search TEXT --author TEXT --filter TEXT --sort [created_at|last_modified|likes|trending_score] --limit INTEGER --expand TEXT --human-readable --tree --recursive --revision TEXT --format [auto|human|agent|json|quiet]]`
+- `hf spaces logs SPACE_ID` — Fetch the run or build logs of a Space. `[--build --follow --tail INTEGER --format [auto|human|agent|json|quiet]]`
+- `hf spaces pause SPACE_ID` — Pause a Space. `[--format [auto|human|agent|json|quiet]]`
+- `hf spaces restart SPACE_ID` — Restart a Space. `[--factory-reboot --format [auto|human|agent|json|quiet]]`
+- `hf spaces search QUERY` — Search spaces on the Hub using semantic search. `[--filter TEXT --sdk TEXT --include-non-running --description --limit INTEGER --format [auto|human|agent|json|quiet]]`
+- `hf spaces secrets add SPACE_ID` — Add or update secrets for a Space. `[--secrets TEXT --secrets-file TEXT --format [auto|human|agent|json|quiet]]`
+- `hf spaces secrets delete SPACE_ID KEY` — Remove a secret from a Space. `[--yes --format [auto|human|agent|json|quiet]]`
+- `hf spaces secrets list SPACE_ID` — List secrets for a Space. Secret values are write-only and not returned. `[--format [auto|human|agent|json|quiet]]`
+- `hf spaces settings SPACE_ID` — Update the settings of a Space. `[--sleep-time INTEGER --hardware [cpu-basic|cpu-upgrade|zero-a10g|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|a100x4|a100x8] --format [auto|human|agent|json|quiet]]`
+- `hf spaces ssh SPACE_ID` — SSH into a Space's Dev Mode container. `[--identity-file PATH --dry-run --auto --format [auto|human|agent|json|quiet]]`
+- `hf spaces variables add SPACE_ID` — Add or update environment variables for a Space. `[--env TEXT --env-file TEXT --format [auto|human|agent|json|quiet]]`
+- `hf spaces variables delete SPACE_ID KEY` — Remove an environment variable from a Space. `[--yes --format [auto|human|agent|json|quiet]]`
+- `hf spaces variables list SPACE_ID` — List environment variables for a Space. `[--format [auto|human|agent|json|quiet]]`
+- `hf spaces volumes delete SPACE_ID` — Remove all volumes from a Space. `[--yes --format [auto|human|agent|json|quiet]]`
+- `hf spaces volumes list SPACE_ID` — List volumes mounted in a Space. `[--format [auto|human|agent|json|quiet]]`
+- `hf spaces volumes set SPACE_ID` — Set (replace) volumes for a Space. `[--volume TEXT --format [auto|human|agent|json|quiet]]`
+
+### `hf webhooks` — Manage webhooks on the Hub.
+
+- `hf webhooks create --watch TEXT` — Create a new webhook. `[--url TEXT --job-id TEXT --domain [repo|discussions] --secret TEXT --format [auto|human|agent|json|quiet]]`
+- `hf webhooks delete WEBHOOK_ID` — Delete a webhook permanently. `[--yes --format [auto|human|agent|json|quiet]]`
+- `hf webhooks disable WEBHOOK_ID` — Disable an active webhook. `[--format [auto|human|agent|json|quiet]]`
+- `hf webhooks enable WEBHOOK_ID` — Enable a disabled webhook. `[--format [auto|human|agent|json|quiet]]`
+- `hf webhooks info WEBHOOK_ID` — Show full details for a single webhook. `[--format [auto|human|agent|json|quiet]]`
+- `hf webhooks list` — List all webhooks for the current user. `[--format [auto|human|agent|json|quiet]]`
+- `hf webhooks update WEBHOOK_ID` — Update an existing webhook. Only provided options are changed. `[--url TEXT --watch TEXT --domain [repo|discussions] --secret TEXT --format [auto|human|agent|json|quiet]]`
+
+## Common options
+
+- `--format` — Output format: `--format json` (or `--json`) or `--format table` (default).
+- `-q / --quiet` — Quiet output (one ID per line).
+- `--revision` — Git revision id which can be a branch name, a tag, or a commit hash.
+- `--token` — Use a User Access Token. Prefer setting `HF_TOKEN` env var instead of passing `--token`.
+- `--type` — The type of repository (model, dataset, or space).
+
+## Mounting repos as local filesystems
+
+To mount Hub repositories or buckets as local filesystems — no download, no copy, no waiting — use `hf-mount`. Files are fetched on demand. GitHub: https://github.com/huggingface/hf-mount
+
+Install: `curl -fsSL https://raw.githubusercontent.com/huggingface/hf-mount/main/install.sh | sh`
+
+Some command examples:
+- `hf-mount start repo openai-community/gpt2 /tmp/gpt2` — mount a repo (read-only)
+- `hf-mount start --hf-token $HF_TOKEN bucket myuser/my-bucket /tmp/data` — mount a bucket (read-write)
+- `hf-mount status` / `hf-mount stop /tmp/data` — list or unmount
+
+## Tips
+
+- Use `hf <command> --help` for full options, descriptions, usage, and real-world examples
+- Authenticate with `HF_TOKEN` env var (recommended) or with `--token`
+- Update the CLI with `hf update` (uses the correct command for the detected install method)

.agents/skills/hf-gradio/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: hf-gradio
+description: Use Gradio applications via API. Use when the user asks for to generate a prediction from a Gradio app on Hugging Face spaces or public URL. For example, "Generate an image using black-forest-labs/FLUX.2-dev". 
+---
+
+## hf-gradio CLI Skill
+
+The `hf-gradio` CLI `gradio` CLI includes `info` and `predict` commands for interacting with Gradio apps programmatically. 
+
+## Step 1 - Verify installation
+
+Verify that either `hf-gradio` or `gradio` are installed in the current virtual environment.
+
+If the `hf` CLI app is installed. The `hf-gradio` extension can be installed via
+
+```bash
+hf extensions install gradio-app/hf-gradio
+```
+
+### Step 2 - Use `info` to discover endpoints and payload format
+
+```bash
+gradio info <space_id_or_url>
+```
+
+```bash
+hf-gradio info <space_id_or_url>
+```
+
+```bash
+hf gradio info <space_id_or_url>
+```
+
+Returns a JSON payload describing all endpoints, their parameters (with types and defaults), and return values.
+
+```bash
+gradio info gradio/calculator
+#    {
+#   "/predict": {
+#     "parameters": [
+#       {"name": "num1", "required": true, "default": null, "type": {"type": "number"}},
+#       {"name": "operation", "required": true, "default": null, "type": {"enum": ["add", "subtract", "multiply", "divide"], "type": "string"}},
+#       {"name": "num2", "required": true, "default": null, "type": {"type": "number"}}
+#     ],
+#     "returns": [{"name": "output", "type": {"type": "number"}}],
+#     "description": ""
+#   }
+# }
+```
+
+File-type parameters show `"type": "filepath"` with instructions to include `"meta": {"_type": "gradio.FileData"}` — this signals the file will be uploaded to the remote server.
+
+## Step 3 - Use `predict` to generate the prediction
+
+```bash
+gradio predict <space_id_or_url> <endpoint> <json_payload>
+```
+
+```bash
+hf-gradio predict <space_id_or_url> <endpoint> <json_payload>
+```
+
+```bash
+hf gradio predict <space_id_or_url> <endpoint> <json_payload>
+```
+
+Returns a JSON object with named output keys.
+
+```bash
+# Simple numeric prediction
+gradio predict gradio/calculator /predict '{"num1": 5, "operation": "multiply", "num2": 3}'
+# {"output": 15}
+
+# Image generation
+gradio predict black-forest-labs/FLUX.2-dev /infer '{"prompt": "A majestic dragon"}'
+# {"Result": "/tmp/gradio/.../image.webp", "Seed": 1117868604}
+
+# File upload (must include meta key)
+gradio predict gradio/image_mod /predict '{"image": {"path": "/path/to/image.png", "meta": {"_type": "gradio.FileData"}}}'
+# {"output": "/tmp/gradio/.../output.png"}
+```
+
+Both commands accept `--token` for accessing private Spaces.

.agents/skills/hf-mem/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: hf-mem
+description: Hugging Face CLI to estimate the required memory to load Safetensors or GGUF model weights for inference from the Hugging Face Hub
+---
+
+`hf_mem` estimates the required memory for inference, including model weights and an optional KV cache, for Safetensors and GGUF for models on the Hugging Face Hub using HTTP Range requests i.e., without downloading or loading any weights locally.
+
+## When to use?
+
+- User asks how much VRAM or memory a model needs to run
+- User wants to know if a model fits on their GPU or a given instance
+- User references a Hugging Face model ID or URL and asks about inference requirements
+
+## What are the requirements?
+
+- `uv` installed (for `uvx`)
+- `HF_TOKEN` env var or `--hf-token` flag (for gated or private models only)
+
+## How to run?
+
+Run with `--model-id` pointing to the Hugging Face Hub repository which will check that it either contains Safetensors (via `model.safetensors`, `model.safetensors.index.json` if sharded, or `model_index.json` for Diffusers) or GGUF model weights within.
+
+```bash
+uvx hf-mem --model-id <model-id> --json-output
+```
+
+If the repository contains GGUF model weights in multiple precisions / quantizations, the estimations will be on a per-file basis, whereas for inference you won't load all of those but rather only a single precision. This being said, for GGUF you might as well need to provide `--gguf-file` to target the specific file (or path if sharded) you want to run.
+
+```bash
+uvx hf-mem --model-id <model-id> --gguf-file <file-or-path> --json-output
+```
+
+Additionally, `hf-mem` comes with an `--experimental` flag that will also calculate the KV cache memory requirements too, useful for large-language models, meaning it applies to LLMs (`...ForCausalLM`), VLMs (`...ForConditionalGeneration`), and GGUF models.
+
+As per the context window, it will be read from the default or overridden with `--max-model-len` a la vLLM. And, same goes for the KV cache precision, which will default to the model precision unless manually set via `--kv-cache-dtype` a la vLLM too.
+
+For Safetensors use as:
+
+```bash
+uvx hf-mem --model-id <model-id> --experimental [--max-model-len N] [--batch-size N] [--kv-cache-dtype auto|bfloat16|fp8|fp8_ds_mla|fp8_e4m3|fp8_e5m2|fp8_inc] --json-output
+```
+
+And, for GGUF use as:
+
+```bash
+uvx hf-mem --model-id <model-id> --gguf-file <file-or-path> --experimental [--max-model-len N] [--batch-size N] [--kv-cache-dtype auto|F32|F16|Q4_0|Q4_1|Q5_0|Q5_1|Q8_0|Q8_1|Q2_K|Q3_K|Q4_K|Q5_K|Q6_K|Q8_K|IQ2_XXS|IQ2_XS|IQ3_XXS|IQ1_S|IQ4_NL|IQ3_S|IQ2_S|IQ4_XS|I8|I16|I32|I64|F64|IQ1_M|BF16|TQ1_0|TQ2_0|MXFP4] --json-output
+```
+
+## Examples
+
+For Transformers with Safetensors weights:
+
+```bash
+uvx hf-mem --model-id MiniMaxAI/MiniMax-M2 --json-output
+```
+
+For Diffusers with Safetensors weights:
+
+```bash
+uvx hf-mem --model-id Qwen/Qwen-Image --json-output
+```
+
+For Sentence Transformers with Safetensors weights:
+
+```bash
+uvx hf-mem --model-id google/embeddinggemma-300m --json-output
+```
+
+With `--experimental` to include the KV cache estimation for LLMs and VLMs:
+
+```bash
+uvx hf-mem --model-id mistralai/Mistral-7B-v0.1 --experimental --json-output
+```
+
+And, for LLMs or VLMs with GGUF weights:
+
+```bash
+uvx hf-mem --model-id unsloth/Qwen3.5-397B-A17B-GGUF --gguf-file Q4_K_M --experimental --json-output
+```

.agents/skills/huggingface-best/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: huggingface-best
+description: >
+  Use when the user asks about finding the best, top, or recommended model for a task,
+  wants to know what AI model to use, or wants to compare models by benchmark scores.
+  Triggers on: "best model for X", "what model should I use for", "top models for [task]",
+  "which model runs on my laptop/machine/device", "recommend a model for", "what LLM should
+  I use for", "compare models for", "what's state of the art for", or any question about
+  choosing an AI model for a specific use case. Always use this skill when the user wants
+  model recommendations or comparisons, even if they don't explicitly mention HuggingFace
+  or benchmarks.
+---
+
+# HuggingFace Best Model Finder
+
+Finds the best models for a task by querying official HF benchmark leaderboards, enriching
+results with model size data, filtering for what fits on the user's device, and returning a
+comparison table with benchmark scores.
+
+---
+
+## Step 1: Parse the request
+
+Extract from the user's message:
+- **Task**: what they want the model to do (coding, math/reasoning, chat, OCR, RAG/retrieval, speech recognition, image classification, multimodal, agents, etc.)
+- **Device**: hardware constraints (MacBook M-series 8/16/32/64GB unified memory, RTX GPU with VRAM amount, CPU-only, cloud/no constraint, etc.)
+
+If device is not mentioned, skip filtering entirely and return the highest-performing models regardless of size. If the task is genuinely ambiguous, ask one clarifying question.
+
+### Device → max parameter budget
+
+When a device is specified, extract its available memory (unified RAM for Apple Silicon, VRAM for discrete GPUs) and apply:
+
+- **fp16 max params (B)** ≈ memory (GB) ÷ 2
+- **Q4 max params (B)** ≈ memory (GB) × 2
+
+Examples: 16GB → 8B fp16 / 32B Q4 — 24GB VRAM → 12B fp16 / 48B Q4 — 8GB → 4B fp16 / 16B Q4
+
+---
+
+## Step 2: Find relevant benchmark datasets
+
+Fetch the full list of official HF benchmarks:
+
+```bash
+curl -s -H "Authorization: Bearer $(cat ~/.cache/huggingface/token)" \
+  "https://huggingface.co/api/datasets?filter=benchmark:official&limit=500" | jq '[.[] | {id, tags, description}]'
+```
+
+Read the returned list and select the datasets most relevant to the user's task — match on dataset id, tags, and description. Use your judgment; don't limit yourself to 2-3. Aim for comprehensive coverage: if 5 benchmarks clearly cover the task, use all 5.
+
+---
+
+## Step 3: Fetch top models from leaderboards
+
+For each selected benchmark dataset:
+
+```bash
+curl -s -H "Authorization: Bearer $(cat ~/.cache/huggingface/token)" \
+  "https://huggingface.co/api/datasets/<namespace>/<repo>/leaderboard" | jq '[.[:15] | .[] | {rank, modelId, value, verified}]'
+```
+
+Collect model IDs and scores across all benchmarks. If a leaderboard returns an error (404, 401, etc.), skip it and note it in the output.
+
+---
+
+## Step 4: Enrich with model metadata
+
+For the top 10-15 candidate model IDs, get model infos.
+
+```bash
+# REST API
+curl -s -H "Authorization: Bearer $(cat ~/.cache/huggingface/token)" \
+  "https://huggingface.co/api/models/org/model1" | jq '{safetensors, tags, cardData}'
+
+# CLI (hf-cli)
+hf models info org/model1 --json | jq '{safetensors, tags, cardData}'
+```
+
+Extract from each response:
+- **Parameters**: `safetensors.total` → convert to B (e.g., 7_241_748_480 → "7.2B")
+- **License**: from model card tags (look for `license:apache-2.0`, `license:mit`, etc.)
+- If `safetensors` is absent, parse size from the model name (look for "7b", "8b", "13b", "70b", "72b", etc.)
+
+---
+
+## Step 5: Filter and rank
+
+**If a device was specified:**
+1. Remove models exceeding the fp16 parameter budget for the device
+2. Flag models that fit only with Q4 quantization (multiply budget by ~4 for Q4 capacity)
+3. If a highly-ranked model is slightly over budget, keep it with a "needs Q4" note — don't silently drop it
+
+**If no device was mentioned:** skip all size filtering — just rank by benchmark score.
+
+Then: rank by benchmark score (descending), keep top 5-8 models.
+
+Include proprietary models (GPT-4, Claude, Gemini) if they appear on leaderboards, but flag them as "API only / not self-hostable". If the user explicitly asked for local/open models only, exclude them.
+
+---
+
+## Step 6: Output
+
+### Comparison table
+
+```markdown
+| # | Model | Params | [Benchmark 1] | [Benchmark 2] | License | On device |
+|---|-------|--------|--------------|--------------|---------|-----------|
+| ⭐1 | [org/name](https://huggingface.co/org/name) | 7B | 85.2% | — | Apache 2.0 | Yes (fp16) |
+| 2 | [org/name](https://huggingface.co/org/name) | 13B | 83.1% | 71.5% | MIT | Q4 only |
+| 3 | [org/name](https://huggingface.co/org/name) | 70B | 90.0% | 81.0% | Llama | Too large |
+```
+
+- Link model names to `https://huggingface.co/<model_id>`
+- Use `—` for benchmarks where the model wasn't evaluated
+- Star the top recommended pick with ⭐
+- "On device" values: `Yes (fp16)`, `Q4 only`, `Too large`, `API only`
+
+### Follow-up
+
+After presenting the table, ask the user: "Would you like to run **[top recommended model]**?"
+
+If they say yes, ask whether they'd prefer to:
+- **Run locally** — ask about their device if not already known, then give appropriate setup instructions
+- **Run on HF Jobs** — point them to the HF Jobs guide: https://huggingface.co/docs/huggingface_hub/en/guides/jobs
+
+---
+
+## Error handling
+
+- **Leaderboard not found**: skip, note "leaderboard unavailable" in output
+- **Model missing from hub_repo_details**: fall back to parsing size from model name
+- **No benchmarks found for task**: use the curated fallback table above, or try `hub_repo_search` with `filters=["<task>"]` sorted by `trendingScore`
+- **All leaderboards fail**: fall back to `hub_repo_search` for popular models tagged with the task, note that results are by popularity rather than benchmark score

.agents/skills/huggingface-community-evals/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: huggingface-community-evals
+description: Run evaluations for Hugging Face Hub models using inspect-ai and lighteval on local hardware. Use for backend selection, local GPU evals, and choosing between vLLM / Transformers / accelerate. Not for HF Jobs orchestration, model-card PRs, .eval_results publication, or community-evals automation.
+---
+
+# Overview
+
+This skill is for **running evaluations against models on the Hugging Face Hub on local hardware**.
+
+It covers:
+- `inspect-ai` with local inference
+- `lighteval` with local inference
+- choosing between `vllm`, Hugging Face Transformers, and `accelerate`
+- smoke tests, task selection, and backend fallback strategy
+
+It does **not** cover:
+- Hugging Face Jobs orchestration
+- model-card or `model-index` edits
+- README table extraction
+- Artificial Analysis imports
+- `.eval_results` generation or publishing
+- PR creation or community-evals automation
+
+If the user wants to **run the same eval remotely on Hugging Face Jobs**, hand off to the `hugging-face-jobs` skill and pass it one of the local scripts in this skill.
+
+If the user wants to **publish results into the community evals workflow**, stop after generating the evaluation run and hand off that publishing step to `~/code/community-evals`.
+
+> All paths below are relative to the directory containing this `SKILL.md`.
+
+# When To Use Which Script
+
+| Use case | Script |
+|---|---|
+| Local `inspect-ai` eval on a Hub model via inference providers | `scripts/inspect_eval_uv.py` |
+| Local GPU eval with `inspect-ai` using `vllm` or Transformers | `scripts/inspect_vllm_uv.py` |
+| Local GPU eval with `lighteval` using `vllm` or `accelerate` | `scripts/lighteval_vllm_uv.py` |
+| Extra command patterns | `examples/USAGE_EXAMPLES.md` |
+
+# Prerequisites
+
+- Prefer `uv run` for local execution.
+- Set `HF_TOKEN` for gated/private models.
+- For local GPU runs, verify GPU access before starting:
+
+```bash
+uv --version
+printenv HF_TOKEN >/dev/null
+nvidia-smi
+```
+
+If `nvidia-smi` is unavailable, either:
+- use `scripts/inspect_eval_uv.py` for lighter provider-backed evaluation, or
+- hand off to the `hugging-face-jobs` skill if the user wants remote compute.
+
+# Core Workflow
+
+1. Choose the evaluation framework.
+   - Use `inspect-ai` when you want explicit task control and inspect-native flows.
+   - Use `lighteval` when the benchmark is naturally expressed as a lighteval task string, especially leaderboard-style tasks.
+2. Choose the inference backend.
+   - Prefer `vllm` for throughput on supported architectures.
+   - Use Hugging Face Transformers (`--backend hf`) or `accelerate` as compatibility fallbacks.
+3. Start with a smoke test.
+   - `inspect-ai`: add `--limit 10` or similar.
+   - `lighteval`: add `--max-samples 10`.
+4. Scale up only after the smoke test passes.
+5. If the user wants remote execution, hand off to `hugging-face-jobs` with the same script + args.
+
+# Quick Start
+
+## Option A: inspect-ai with local inference providers path
+
+Best when the model is already supported by Hugging Face Inference Providers and you want the lowest local setup overhead.
+
+```bash
+uv run scripts/inspect_eval_uv.py \
+  --model meta-llama/Llama-3.2-1B \
+  --task mmlu \
+  --limit 20
+```
+
+Use this path when:
+- you want a quick local smoke test
+- you do not need direct GPU control
+- the task already exists in `inspect-evals`
+
+## Option B: inspect-ai on Local GPU
+
+Best when you need to load the Hub model directly, use `vllm`, or fall back to Transformers for unsupported architectures.
+
+Local GPU:
+
+```bash
+uv run scripts/inspect_vllm_uv.py \
+  --model meta-llama/Llama-3.2-1B \
+  --task gsm8k \
+  --limit 20
+```
+
+Transformers fallback:
+
+```bash
+uv run scripts/inspect_vllm_uv.py \
+  --model microsoft/phi-2 \
+  --task mmlu \
+  --backend hf \
+  --trust-remote-code \
+  --limit 20
+```
+
+## Option C: lighteval on Local GPU
+
+Best when the task is naturally expressed as a `lighteval` task string, especially Open LLM Leaderboard style benchmarks.
+
+Local GPU:
+
+```bash
+uv run scripts/lighteval_vllm_uv.py \
+  --model meta-llama/Llama-3.2-3B-Instruct \
+  --tasks "leaderboard|mmlu|5,leaderboard|gsm8k|5" \
+  --max-samples 20 \
+  --use-chat-template
+```
+
+`accelerate` fallback:
+
+```bash
+uv run scripts/lighteval_vllm_uv.py \
+  --model microsoft/phi-2 \
+  --tasks "leaderboard|mmlu|5" \
+  --backend accelerate \
+  --trust-remote-code \
+  --max-samples 20
+```
+
+# Remote Execution Boundary
+
+This skill intentionally stops at **local execution and backend selection**.
+
+If the user wants to:
+- run these scripts on Hugging Face Jobs
+- pick remote hardware
+- pass secrets to remote jobs
+- schedule recurring runs
+- inspect / cancel / monitor jobs
+
+then switch to the **`hugging-face-jobs`** skill and pass it one of these scripts plus the chosen arguments.
+
+# Task Selection
+
+`inspect-ai` examples:
+- `mmlu`
+- `gsm8k`
+- `hellaswag`
+- `arc_challenge`
+- `truthfulqa`
+- `winogrande`
+- `humaneval`
+
+`lighteval` task strings use `suite|task|num_fewshot`:
+- `leaderboard|mmlu|5`
+- `leaderboard|gsm8k|5`
+- `leaderboard|arc_challenge|25`
+- `lighteval|hellaswag|0`
+
+Multiple `lighteval` tasks can be comma-separated in `--tasks`.
+
+# Backend Selection
+
+- Prefer `inspect_vllm_uv.py --backend vllm` for fast GPU inference on supported architectures.
+- Use `inspect_vllm_uv.py --backend hf` when `vllm` does not support the model.
+- Prefer `lighteval_vllm_uv.py --backend vllm` for throughput on supported models.
+- Use `lighteval_vllm_uv.py --backend accelerate` as the compatibility fallback.
+- Use `inspect_eval_uv.py` when Inference Providers already cover the model and you do not need direct GPU control.
+
+# Hardware Guidance
+
+| Model size | Suggested local hardware |
+|---|---|
+| `< 3B` | consumer GPU / Apple Silicon / small dev GPU |
+| `3B - 13B` | stronger local GPU |
+| `13B+` | high-memory local GPU or hand off to `hugging-face-jobs` |
+
+For smoke tests, prefer cheaper local runs plus `--limit` or `--max-samples`.
+
+# Troubleshooting
+
+- CUDA or vLLM OOM:
+  - reduce `--batch-size`
+  - reduce `--gpu-memory-utilization`
+  - switch to a smaller model for the smoke test
+  - if necessary, hand off to `hugging-face-jobs`
+- Model unsupported by `vllm`:
+  - switch to `--backend hf` for `inspect-ai`
+  - switch to `--backend accelerate` for `lighteval`
+- Gated/private repo access fails:
+  - verify `HF_TOKEN`
+- Custom model code required:
+  - add `--trust-remote-code`
+
+# Examples
+
+See:
+- `examples/USAGE_EXAMPLES.md` for local command patterns
+- `scripts/inspect_eval_uv.py`
+- `scripts/inspect_vllm_uv.py`
+- `scripts/lighteval_vllm_uv.py`

.agents/skills/huggingface-community-evals/examples/.env.example

@@ -0,0 +1,3 @@
+# Hugging Face Token (required for gated/private models)
+# Get your token at: https://huggingface.co/settings/tokens
+HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

.agents/skills/huggingface-community-evals/examples/USAGE_EXAMPLES.md

@@ -0,0 +1,101 @@
+# Usage Examples
+
+This document provides practical examples for **running evaluations locally** against Hugging Face Hub models.
+
+## What this skill covers
+
+- `inspect-ai` local runs
+- `inspect-ai` with `vllm` or Transformers backends
+- `lighteval` local runs with `vllm` or `accelerate`
+- smoke tests and backend fallback patterns
+
+## What this skill does NOT cover
+
+- `model-index`
+- `.eval_results`
+- community eval publication workflows
+- model-card PR creation
+- Hugging Face Jobs orchestration
+
+If you want to run these same scripts remotely, use the `hugging-face-jobs` skill and pass one of the scripts in `scripts/`.
+
+## Setup
+
+```bash
+cd skills/hugging-face-evaluation
+export HF_TOKEN=hf_xxx
+uv --version
+```
+
+For local GPU runs:
+
+```bash
+nvidia-smi
+```
+
+## inspect-ai examples
+
+### Quick smoke test
+
+```bash
+uv run scripts/inspect_eval_uv.py \
+  --model meta-llama/Llama-3.2-1B \
+  --task mmlu \
+  --limit 10
+```
+
+### Local GPU with vLLM
+
+```bash
+uv run scripts/inspect_vllm_uv.py \
+  --model meta-llama/Llama-3.2-8B-Instruct \
+  --task gsm8k \
+  --limit 20
+```
+
+### Transformers fallback
+
+```bash
+uv run scripts/inspect_vllm_uv.py \
+  --model microsoft/phi-2 \
+  --task mmlu \
+  --backend hf \
+  --trust-remote-code \
+  --limit 20
+```
+
+## lighteval examples
+
+### Single task
+
+```bash
+uv run scripts/lighteval_vllm_uv.py \
+  --model meta-llama/Llama-3.2-3B-Instruct \
+  --tasks "leaderboard|mmlu|5" \
+  --max-samples 20
+```
+
+### Multiple tasks
+
+```bash
+uv run scripts/lighteval_vllm_uv.py \
+  --model meta-llama/Llama-3.2-3B-Instruct \
+  --tasks "leaderboard|mmlu|5,leaderboard|gsm8k|5" \
+  --max-samples 20 \
+  --use-chat-template
+```
+
+### accelerate fallback
+
+```bash
+uv run scripts/lighteval_vllm_uv.py \
+  --model microsoft/phi-2 \
+  --tasks "leaderboard|mmlu|5" \
+  --backend accelerate \
+  --trust-remote-code \
+  --max-samples 20
+```
+
+## Hand-off to Hugging Face Jobs
+
+When local hardware is not enough, switch to the `hugging-face-jobs` skill and run one of these scripts remotely. Keep the script path and args; move the orchestration there.

.agents/skills/huggingface-community-evals/scripts/inspect_eval_uv.py

@@ -0,0 +1,104 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "inspect-ai>=0.3.0",
+#     "inspect-evals",
+#     "openai",
+# ]
+# ///
+
+"""
+Entry point script for running inspect-ai evaluations against Hugging Face inference providers.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+
+def _inspect_evals_tasks_root() -> Optional[Path]:
+    """Return the installed inspect_evals package path if available."""
+    try:
+        import inspect_evals
+
+        return Path(inspect_evals.__file__).parent
+    except Exception:
+        return None
+
+
+def _normalize_task(task: str) -> str:
+    """Allow lighteval-style `suite|task|shots` strings by keeping the task name."""
+    if "|" in task:
+        parts = task.split("|")
+        if len(parts) >= 2 and parts[1]:
+            return parts[1]
+    return task
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Inspect-ai job runner")
+    parser.add_argument("--model", required=True, help="Model ID on Hugging Face Hub")
+    parser.add_argument("--task", required=True, help="inspect-ai task to execute")
+    parser.add_argument("--limit", type=int, default=None, help="Limit number of samples to evaluate")
+    parser.add_argument(
+        "--tasks-root",
+        default=None,
+        help="Optional path to inspect task files. Defaults to the installed inspect_evals package.",
+    )
+    parser.add_argument(
+        "--sandbox",
+        default="local",
+        help="Sandbox backend to use (default: local for HF jobs without Docker).",
+    )
+    args = parser.parse_args()
+
+    # Ensure downstream libraries can read the token passed as a secret
+    hf_token = os.getenv("HF_TOKEN")
+    if hf_token:
+        os.environ.setdefault("HUGGING_FACE_HUB_TOKEN", hf_token)
+        os.environ.setdefault("HF_HUB_TOKEN", hf_token)
+
+    task = _normalize_task(args.task)
+    tasks_root = Path(args.tasks_root) if args.tasks_root else _inspect_evals_tasks_root()
+    if tasks_root and not tasks_root.exists():
+        tasks_root = None
+
+    cmd = [
+        "inspect",
+        "eval",
+        task,
+        "--model",
+        f"hf-inference-providers/{args.model}",
+        "--log-level",
+        "info",
+        # Reduce batch size to avoid OOM errors (default is 32)
+        "--max-connections",
+        "1",
+        # Set a small positive temperature (HF doesn't allow temperature=0)
+        "--temperature",
+        "0.001",
+    ]
+
+    if args.sandbox:
+        cmd.extend(["--sandbox", args.sandbox])
+
+    if args.limit:
+        cmd.extend(["--limit", str(args.limit)])
+
+    try:
+        subprocess.run(cmd, check=True, cwd=tasks_root)
+        print("Evaluation complete.")
+    except subprocess.CalledProcessError as exc:
+        location = f" (cwd={tasks_root})" if tasks_root else ""
+        print(f"Evaluation failed with exit code {exc.returncode}{location}", file=sys.stderr)
+        raise
+
+
+if __name__ == "__main__":
+    main()
+

.agents/skills/huggingface-community-evals/scripts/inspect_vllm_uv.py

@@ -0,0 +1,306 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "inspect-ai>=0.3.0",
+#     "inspect-evals",
+#     "vllm>=0.4.0",
+#     "torch>=2.0.0",
+#     "transformers>=4.40.0",
+# ]
+# ///
+
+"""
+Entry point script for running inspect-ai evaluations with vLLM or HuggingFace Transformers backend.
+
+This script runs evaluations on custom HuggingFace models using local GPU inference,
+separate from inference provider scripts (which use external APIs).
+
+Usage (standalone):
+    uv run scripts/inspect_vllm_uv.py --model "meta-llama/Llama-3.2-1B" --task "mmlu"
+
+Model backends:
+    - vllm: Fast inference with vLLM (recommended for large models)
+    - hf: HuggingFace Transformers backend (broader model compatibility)
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+from typing import Optional
+
+
+def setup_environment() -> None:
+    """Configure environment variables for HuggingFace authentication."""
+    hf_token = os.getenv("HF_TOKEN")
+    if hf_token:
+        os.environ.setdefault("HUGGING_FACE_HUB_TOKEN", hf_token)
+        os.environ.setdefault("HF_HUB_TOKEN", hf_token)
+
+
+def run_inspect_vllm(
+    model_id: str,
+    task: str,
+    limit: Optional[int] = None,
+    max_connections: int = 4,
+    temperature: float = 0.0,
+    tensor_parallel_size: int = 1,
+    gpu_memory_utilization: float = 0.8,
+    dtype: str = "auto",
+    trust_remote_code: bool = False,
+    log_level: str = "info",
+) -> None:
+    """
+    Run inspect-ai evaluation with vLLM backend.
+
+    Args:
+        model_id: HuggingFace model ID
+        task: inspect-ai task to execute (e.g., "mmlu", "gsm8k")
+        limit: Limit number of samples to evaluate
+        max_connections: Maximum concurrent connections
+        temperature: Sampling temperature
+        tensor_parallel_size: Number of GPUs for tensor parallelism
+        gpu_memory_utilization: GPU memory fraction
+        dtype: Data type (auto, float16, bfloat16)
+        trust_remote_code: Allow remote code execution
+        log_level: Logging level
+    """
+    setup_environment()
+
+    model_spec = f"vllm/{model_id}"
+    cmd = [
+        "inspect",
+        "eval",
+        task,
+        "--model",
+        model_spec,
+        "--log-level",
+        log_level,
+        "--max-connections",
+        str(max_connections),
+    ]
+
+    # vLLM supports temperature=0 unlike HF inference providers
+    cmd.extend(["--temperature", str(temperature)])
+
+    # Older inspect-ai CLI versions do not support --model-args; rely on defaults
+    # and let vLLM choose sensible settings for small models.
+    if tensor_parallel_size != 1:
+        cmd.extend(["--tensor-parallel-size", str(tensor_parallel_size)])
+    if gpu_memory_utilization != 0.8:
+        cmd.extend(["--gpu-memory-utilization", str(gpu_memory_utilization)])
+    if dtype != "auto":
+        cmd.extend(["--dtype", dtype])
+    if trust_remote_code:
+        cmd.append("--trust-remote-code")
+
+    if limit:
+        cmd.extend(["--limit", str(limit)])
+
+    print(f"Running: {' '.join(cmd)}")
+
+    try:
+        subprocess.run(cmd, check=True)
+        print("Evaluation complete.")
+    except subprocess.CalledProcessError as exc:
+        print(f"Evaluation failed with exit code {exc.returncode}", file=sys.stderr)
+        sys.exit(exc.returncode)
+
+
+def run_inspect_hf(
+    model_id: str,
+    task: str,
+    limit: Optional[int] = None,
+    max_connections: int = 1,
+    temperature: float = 0.001,
+    device: str = "auto",
+    dtype: str = "auto",
+    trust_remote_code: bool = False,
+    log_level: str = "info",
+) -> None:
+    """
+    Run inspect-ai evaluation with HuggingFace Transformers backend.
+
+    Use this when vLLM doesn't support the model architecture.
+
+    Args:
+        model_id: HuggingFace model ID
+        task: inspect-ai task to execute
+        limit: Limit number of samples
+        max_connections: Maximum concurrent connections (keep low for memory)
+        temperature: Sampling temperature
+        device: Device to use (auto, cuda, cpu)
+        dtype: Data type
+        trust_remote_code: Allow remote code execution
+        log_level: Logging level
+    """
+    setup_environment()
+
+    model_spec = f"hf/{model_id}"
+
+    cmd = [
+        "inspect",
+        "eval",
+        task,
+        "--model",
+        model_spec,
+        "--log-level",
+        log_level,
+        "--max-connections",
+        str(max_connections),
+        "--temperature",
+        str(temperature),
+    ]
+
+    if device != "auto":
+        cmd.extend(["--device", device])
+    if dtype != "auto":
+        cmd.extend(["--dtype", dtype])
+    if trust_remote_code:
+        cmd.append("--trust-remote-code")
+
+    if limit:
+        cmd.extend(["--limit", str(limit)])
+
+    print(f"Running: {' '.join(cmd)}")
+
+    try:
+        subprocess.run(cmd, check=True)
+        print("Evaluation complete.")
+    except subprocess.CalledProcessError as exc:
+        print(f"Evaluation failed with exit code {exc.returncode}", file=sys.stderr)
+        sys.exit(exc.returncode)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Run inspect-ai evaluations with vLLM or HuggingFace Transformers on custom models",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Run MMLU with vLLM backend
+  uv run scripts/inspect_vllm_uv.py --model meta-llama/Llama-3.2-1B --task mmlu
+
+  # Run with HuggingFace Transformers backend
+  uv run scripts/inspect_vllm_uv.py --model meta-llama/Llama-3.2-1B --task mmlu --backend hf
+
+  # Run with limited samples for testing
+  uv run scripts/inspect_vllm_uv.py --model meta-llama/Llama-3.2-1B --task mmlu --limit 10
+
+  # Run on multiple GPUs with tensor parallelism
+  uv run scripts/inspect_vllm_uv.py --model meta-llama/Llama-3.2-70B --task mmlu --tensor-parallel-size 4
+
+Available tasks (from inspect-evals):
+  - mmlu: Massive Multitask Language Understanding
+  - gsm8k: Grade School Math
+  - hellaswag: Common sense reasoning
+  - arc_challenge: AI2 Reasoning Challenge
+  - truthfulqa: TruthfulQA benchmark
+  - winogrande: Winograd Schema Challenge
+  - humaneval: Code generation (HumanEval)
+
+        """,
+    )
+
+    parser.add_argument(
+        "--model",
+        required=True,
+        help="HuggingFace model ID (e.g., meta-llama/Llama-3.2-1B)",
+    )
+    parser.add_argument(
+        "--task",
+        required=True,
+        help="inspect-ai task to execute (e.g., mmlu, gsm8k)",
+    )
+    parser.add_argument(
+        "--backend",
+        choices=["vllm", "hf"],
+        default="vllm",
+        help="Model backend (default: vllm)",
+    )
+    parser.add_argument(
+        "--limit",
+        type=int,
+        default=None,
+        help="Limit number of samples to evaluate",
+    )
+    parser.add_argument(
+        "--max-connections",
+        type=int,
+        default=None,
+        help="Maximum concurrent connections (default: 4 for vllm, 1 for hf)",
+    )
+    parser.add_argument(
+        "--temperature",
+        type=float,
+        default=None,
+        help="Sampling temperature (default: 0.0 for vllm, 0.001 for hf)",
+    )
+    parser.add_argument(
+        "--tensor-parallel-size",
+        type=int,
+        default=1,
+        help="Number of GPUs for tensor parallelism (vLLM only, default: 1)",
+    )
+    parser.add_argument(
+        "--gpu-memory-utilization",
+        type=float,
+        default=0.8,
+        help="GPU memory fraction to use (vLLM only, default: 0.8)",
+    )
+    parser.add_argument(
+        "--dtype",
+        default="auto",
+        choices=["auto", "float16", "bfloat16", "float32"],
+        help="Data type for model weights (default: auto)",
+    )
+    parser.add_argument(
+        "--device",
+        default="auto",
+        help="Device for HF backend (auto, cuda, cpu)",
+    )
+    parser.add_argument(
+        "--trust-remote-code",
+        action="store_true",
+        help="Allow executing remote code from model repository",
+    )
+    parser.add_argument(
+        "--log-level",
+        default="info",
+        choices=["debug", "info", "warning", "error"],
+        help="Logging level (default: info)",
+    )
+
+    args = parser.parse_args()
+
+    if args.backend == "vllm":
+        run_inspect_vllm(
+            model_id=args.model,
+            task=args.task,
+            limit=args.limit,
+            max_connections=args.max_connections or 4,
+            temperature=args.temperature if args.temperature is not None else 0.0,
+            tensor_parallel_size=args.tensor_parallel_size,
+            gpu_memory_utilization=args.gpu_memory_utilization,
+            dtype=args.dtype,
+            trust_remote_code=args.trust_remote_code,
+            log_level=args.log_level,
+        )
+    else:
+        run_inspect_hf(
+            model_id=args.model,
+            task=args.task,
+            limit=args.limit,
+            max_connections=args.max_connections or 1,
+            temperature=args.temperature if args.temperature is not None else 0.001,
+            device=args.device,
+            dtype=args.dtype,
+            trust_remote_code=args.trust_remote_code,
+            log_level=args.log_level,
+        )
+
+
+if __name__ == "__main__":
+    main()

.agents/skills/huggingface-community-evals/scripts/lighteval_vllm_uv.py

@@ -0,0 +1,297 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "lighteval[accelerate,vllm]>=0.6.0",
+#     "torch>=2.0.0",
+#     "transformers>=4.40.0",
+#     "accelerate>=0.30.0",
+#     "vllm>=0.4.0",
+# ]
+# ///
+
+"""
+Entry point script for running lighteval evaluations with local GPU backends.
+
+This script runs evaluations using vLLM or accelerate on custom HuggingFace models.
+It is separate from inference provider scripts and evaluates models directly on local hardware.
+
+Usage (standalone):
+    uv run scripts/lighteval_vllm_uv.py --model "meta-llama/Llama-3.2-1B" --tasks "leaderboard|mmlu|5"
+
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+from typing import Optional
+
+
+def setup_environment() -> None:
+    """Configure environment variables for HuggingFace authentication."""
+    hf_token = os.getenv("HF_TOKEN")
+    if hf_token:
+        os.environ.setdefault("HUGGING_FACE_HUB_TOKEN", hf_token)
+        os.environ.setdefault("HF_HUB_TOKEN", hf_token)
+
+
+def run_lighteval_vllm(
+    model_id: str,
+    tasks: str,
+    output_dir: Optional[str] = None,
+    max_samples: Optional[int] = None,
+    batch_size: int = 1,
+    tensor_parallel_size: int = 1,
+    gpu_memory_utilization: float = 0.8,
+    dtype: str = "auto",
+    trust_remote_code: bool = False,
+    use_chat_template: bool = False,
+    system_prompt: Optional[str] = None,
+) -> None:
+    """
+    Run lighteval with vLLM backend for efficient GPU inference.
+
+    Args:
+        model_id: HuggingFace model ID (e.g., "meta-llama/Llama-3.2-1B")
+        tasks: Task specification (e.g., "leaderboard|mmlu|5" or "lighteval|hellaswag|0")
+        output_dir: Directory for evaluation results
+        max_samples: Limit number of samples per task
+        batch_size: Batch size for evaluation
+        tensor_parallel_size: Number of GPUs for tensor parallelism
+        gpu_memory_utilization: GPU memory fraction to use (0.0-1.0)
+        dtype: Data type for model weights (auto, float16, bfloat16)
+        trust_remote_code: Allow executing remote code from model repo
+        use_chat_template: Apply chat template for conversational models
+        system_prompt: System prompt for chat models
+    """
+    setup_environment()
+
+    # Build lighteval vllm command
+    cmd = [
+        "lighteval",
+        "vllm",
+        model_id,
+        tasks,
+        "--batch-size", str(batch_size),
+        "--tensor-parallel-size", str(tensor_parallel_size),
+        "--gpu-memory-utilization", str(gpu_memory_utilization),
+        "--dtype", dtype,
+    ]
+
+    if output_dir:
+        cmd.extend(["--output-dir", output_dir])
+
+    if max_samples:
+        cmd.extend(["--max-samples", str(max_samples)])
+
+    if trust_remote_code:
+        cmd.append("--trust-remote-code")
+
+    if use_chat_template:
+        cmd.append("--use-chat-template")
+
+    if system_prompt:
+        cmd.extend(["--system-prompt", system_prompt])
+
+    print(f"Running: {' '.join(cmd)}")
+
+    try:
+        subprocess.run(cmd, check=True)
+        print("Evaluation complete.")
+    except subprocess.CalledProcessError as exc:
+        print(f"Evaluation failed with exit code {exc.returncode}", file=sys.stderr)
+        sys.exit(exc.returncode)
+
+
+def run_lighteval_accelerate(
+    model_id: str,
+    tasks: str,
+    output_dir: Optional[str] = None,
+    max_samples: Optional[int] = None,
+    batch_size: int = 1,
+    dtype: str = "bfloat16",
+    trust_remote_code: bool = False,
+    use_chat_template: bool = False,
+    system_prompt: Optional[str] = None,
+) -> None:
+    """
+    Run lighteval with accelerate backend for multi-GPU distributed inference.
+
+    Use this backend when vLLM is not available or for models not supported by vLLM.
+
+    Args:
+        model_id: HuggingFace model ID
+        tasks: Task specification
+        output_dir: Directory for evaluation results
+        max_samples: Limit number of samples per task
+        batch_size: Batch size for evaluation
+        dtype: Data type for model weights
+        trust_remote_code: Allow executing remote code
+        use_chat_template: Apply chat template
+        system_prompt: System prompt for chat models
+    """
+    setup_environment()
+
+    # Build lighteval accelerate command
+    cmd = [
+        "lighteval",
+        "accelerate",
+        model_id,
+        tasks,
+        "--batch-size", str(batch_size),
+        "--dtype", dtype,
+    ]
+
+    if output_dir:
+        cmd.extend(["--output-dir", output_dir])
+
+    if max_samples:
+        cmd.extend(["--max-samples", str(max_samples)])
+
+    if trust_remote_code:
+        cmd.append("--trust-remote-code")
+
+    if use_chat_template:
+        cmd.append("--use-chat-template")
+
+    if system_prompt:
+        cmd.extend(["--system-prompt", system_prompt])
+
+    print(f"Running: {' '.join(cmd)}")
+
+    try:
+        subprocess.run(cmd, check=True)
+        print("Evaluation complete.")
+    except subprocess.CalledProcessError as exc:
+        print(f"Evaluation failed with exit code {exc.returncode}", file=sys.stderr)
+        sys.exit(exc.returncode)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Run lighteval evaluations with vLLM or accelerate backend on custom HuggingFace models",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Run MMLU evaluation with vLLM
+  uv run scripts/lighteval_vllm_uv.py --model meta-llama/Llama-3.2-1B --tasks "leaderboard|mmlu|5"
+
+  # Run with accelerate backend instead of vLLM
+  uv run scripts/lighteval_vllm_uv.py --model meta-llama/Llama-3.2-1B --tasks "leaderboard|mmlu|5" --backend accelerate
+
+  # Run with chat template for instruction-tuned models
+  uv run scripts/lighteval_vllm_uv.py --model meta-llama/Llama-3.2-1B-Instruct --tasks "leaderboard|mmlu|5" --use-chat-template
+
+  # Run with limited samples for testing
+  uv run scripts/lighteval_vllm_uv.py --model meta-llama/Llama-3.2-1B --tasks "leaderboard|mmlu|5" --max-samples 10
+
+Task format:
+  Tasks use the format: "suite|task|num_fewshot"
+  - leaderboard|mmlu|5 (MMLU with 5-shot)
+  - lighteval|hellaswag|0 (HellaSwag zero-shot)
+  - leaderboard|gsm8k|5 (GSM8K with 5-shot)
+  - Multiple tasks: "leaderboard|mmlu|5,leaderboard|gsm8k|5"
+        """,
+    )
+
+    parser.add_argument(
+        "--model",
+        required=True,
+        help="HuggingFace model ID (e.g., meta-llama/Llama-3.2-1B)",
+    )
+    parser.add_argument(
+        "--tasks",
+        required=True,
+        help="Task specification (e.g., 'leaderboard|mmlu|5')",
+    )
+    parser.add_argument(
+        "--backend",
+        choices=["vllm", "accelerate"],
+        default="vllm",
+        help="Inference backend to use (default: vllm)",
+    )
+    parser.add_argument(
+        "--output-dir",
+        default=None,
+        help="Directory for evaluation results",
+    )
+    parser.add_argument(
+        "--max-samples",
+        type=int,
+        default=None,
+        help="Limit number of samples per task (useful for testing)",
+    )
+    parser.add_argument(
+        "--batch-size",
+        type=int,
+        default=1,
+        help="Batch size for evaluation (default: 1)",
+    )
+    parser.add_argument(
+        "--tensor-parallel-size",
+        type=int,
+        default=1,
+        help="Number of GPUs for tensor parallelism (vLLM only, default: 1)",
+    )
+    parser.add_argument(
+        "--gpu-memory-utilization",
+        type=float,
+        default=0.8,
+        help="GPU memory fraction to use (vLLM only, default: 0.8)",
+    )
+    parser.add_argument(
+        "--dtype",
+        default="auto",
+        choices=["auto", "float16", "bfloat16", "float32"],
+        help="Data type for model weights (default: auto)",
+    )
+    parser.add_argument(
+        "--trust-remote-code",
+        action="store_true",
+        help="Allow executing remote code from model repository",
+    )
+    parser.add_argument(
+        "--use-chat-template",
+        action="store_true",
+        help="Apply chat template for instruction-tuned/chat models",
+    )
+    parser.add_argument(
+        "--system-prompt",
+        default=None,
+        help="System prompt for chat models",
+    )
+
+    args = parser.parse_args()
+
+    if args.backend == "vllm":
+        run_lighteval_vllm(
+            model_id=args.model,
+            tasks=args.tasks,
+            output_dir=args.output_dir,
+            max_samples=args.max_samples,
+            batch_size=args.batch_size,
+            tensor_parallel_size=args.tensor_parallel_size,
+            gpu_memory_utilization=args.gpu_memory_utilization,
+            dtype=args.dtype,
+            trust_remote_code=args.trust_remote_code,
+            use_chat_template=args.use_chat_template,
+            system_prompt=args.system_prompt,
+        )
+    else:
+        run_lighteval_accelerate(
+            model_id=args.model,
+            tasks=args.tasks,
+            output_dir=args.output_dir,
+            max_samples=args.max_samples,
+            batch_size=args.batch_size,
+            dtype=args.dtype if args.dtype != "auto" else "bfloat16",
+            trust_remote_code=args.trust_remote_code,
+            use_chat_template=args.use_chat_template,
+            system_prompt=args.system_prompt,
+        )
+
+
+if __name__ == "__main__":
+    main()

.agents/skills/huggingface-datasets/.hf-skill-manifest.json

@@ -0,0 +1,4 @@
+{
+  "installed_revision": "b3df145a3a5a3e64ac075d781c625896d9d2bfcd",
+  "schema_version": 1
+}

.agents/skills/huggingface-datasets/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: huggingface-datasets
+description: Use this skill for Hugging Face Dataset Viewer API workflows that fetch subset/split metadata, paginate rows, search text, apply filters, download parquet URLs, and read size or statistics.
+---
+
+# Hugging Face Dataset Viewer
+
+Use this skill to execute read-only Dataset Viewer API calls for dataset exploration and extraction.
+
+## Core workflow
+
+1. Optionally validate dataset availability with `/is-valid`.
+2. Resolve `config` + `split` with `/splits`.
+3. Preview with `/first-rows`.
+4. Paginate content with `/rows` using `offset` and `length` (max 100).
+5. Use `/search` for text matching and `/filter` for row predicates.
+6. Retrieve parquet links via `/parquet` and totals/metadata via `/size` and `/statistics`.
+
+## Defaults
+
+- Base URL: `https://datasets-server.huggingface.co`
+- Default API method: `GET`
+- Query params should be URL-encoded.
+- `offset` is 0-based.
+- `length` max is usually `100` for row-like endpoints.
+- Gated/private datasets require `Authorization: Bearer <HF_TOKEN>`.
+
+## Dataset Viewer
+
+- `Validate dataset`: `/is-valid?dataset=<namespace/repo>`
+- `List subsets and splits`: `/splits?dataset=<namespace/repo>`
+- `Preview first rows`: `/first-rows?dataset=<namespace/repo>&config=<config>&split=<split>`
+- `Paginate rows`: `/rows?dataset=<namespace/repo>&config=<config>&split=<split>&offset=<int>&length=<int>`
+- `Search text`: `/search?dataset=<namespace/repo>&config=<config>&split=<split>&query=<text>&offset=<int>&length=<int>`
+- `Filter with predicates`: `/filter?dataset=<namespace/repo>&config=<config>&split=<split>&where=<predicate>&orderby=<sort>&offset=<int>&length=<int>`
+- `List parquet shards`: `/parquet?dataset=<namespace/repo>`
+- `Get size totals`: `/size?dataset=<namespace/repo>`
+- `Get column statistics`: `/statistics?dataset=<namespace/repo>&config=<config>&split=<split>`
+- `Get Croissant metadata (if available)`: `/croissant?dataset=<namespace/repo>`
+
+Pagination pattern:
+
+```bash
+curl "https://datasets-server.huggingface.co/rows?dataset=stanfordnlp/imdb&config=plain_text&split=train&offset=0&length=100"
+curl "https://datasets-server.huggingface.co/rows?dataset=stanfordnlp/imdb&config=plain_text&split=train&offset=100&length=100"
+```
+
+When pagination is partial, use response fields such as `num_rows_total`, `num_rows_per_page`, and `partial` to drive continuation logic.
+
+Search/filter notes:
+
+- `/search` matches string columns (full-text style behavior is internal to the API).
+- `/filter` requires predicate syntax in `where` and optional sort in `orderby`.
+- Keep filtering and searches read-only and side-effect free.
+
+For CLI-based parquet URL discovery or SQL, use the `hf-cli` skill with `hf datasets parquet` and `hf datasets sql`.
+
+## Creating and Uploading Datasets
+
+Use one of these flows depending on dependency constraints.
+
+Zero local dependencies (Hub UI):
+
+- Create dataset repo in browser: `https://huggingface.co/new-dataset`
+- Upload parquet files in the repo "Files and versions" page.
+- Verify shards appear in Dataset Viewer:
+
+```bash
+curl -s "https://datasets-server.huggingface.co/parquet?dataset=<namespace>/<repo>"
+```
+
+Low dependency CLI flow (`npx @huggingface/hub` / `hfjs`):
+
+- Set auth token:
+
+```bash
+export HF_TOKEN=<your_hf_token>
+```
+
+- Upload parquet folder to a dataset repo (auto-creates repo if missing):
+
+```bash
+npx -y @huggingface/hub upload datasets/<namespace>/<repo> ./local/parquet-folder data
+```
+
+- Upload as private repo on creation:
+
+```bash
+npx -y @huggingface/hub upload datasets/<namespace>/<repo> ./local/parquet-folder data --private
+```
+
+After upload, call `/parquet` to discover `<config>/<split>/<shard>` values for querying with `@~parquet`.
+
+## Agent Traces
+
+The Hub supports raw agent session traces from Claude Code, Codex, and Pi Agent. Upload them to Hugging Face Datasets as original JSONL files and the Hub can auto-detect the trace format, tag the dataset as `Traces`, and enable the trace viewer for browsing sessions, turns, tool calls, and model responses. Common local session directories:
+
+- Claude Code: `~/.claude/projects`
+- Codex: `~/.codex/sessions`
+- Pi: `~/.pi/agent/sessions`
+
+Default to private dataset repos because traces can contain prompts, file paths, tool outputs, secrets, or PII. Preserve the raw `.jsonl` files and nest them by project/cwd instead of uploading every session at the dataset root.
+
+```bash
+hf repos create <namespace>/<repo> --type dataset --private --exist-ok
+hf upload <namespace>/<repo> ~/.codex/sessions codex/<project-or-cwd> --type dataset
+```

.agents/skills/huggingface-gradio/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: huggingface-gradio
+description: Build Gradio web UIs and demos in Python. Use when creating or editing Gradio apps, components, event listeners, layouts, or chatbots.
+---
+
+# Gradio
+
+Gradio is a Python library for building interactive web UIs and ML demos. This skill covers the core API, patterns, and examples.
+
+## Guides
+
+Detailed guides on specific topics (read these when relevant):
+
+- [Quickstart](https://www.gradio.app/guides/quickstart)
+- [The Interface Class](https://www.gradio.app/guides/the-interface-class)
+- [Blocks and Event Listeners](https://www.gradio.app/guides/blocks-and-event-listeners)
+- [Controlling Layout](https://www.gradio.app/guides/controlling-layout)
+- [More Blocks Features](https://www.gradio.app/guides/more-blocks-features)
+- [Custom CSS and JS](https://www.gradio.app/guides/custom-CSS-and-JS)
+- [Streaming Outputs](https://www.gradio.app/guides/streaming-outputs)
+- [Streaming Inputs](https://www.gradio.app/guides/streaming-inputs)
+- [Sharing Your App](https://www.gradio.app/guides/sharing-your-app)
+- [Custom HTML Components](https://www.gradio.app/guides/custom-HTML-components)
+- [Getting Started with the Python Client](https://www.gradio.app/guides/getting-started-with-the-python-client)
+- [Getting Started with the JS Client](https://www.gradio.app/guides/getting-started-with-the-js-client)
+
+## Core Patterns
+
+**Interface** (high-level): wraps a function with input/output components.
+
+```python
+import gradio as gr
+
+def greet(name):
+    return f"Hello {name}!"
+
+gr.Interface(fn=greet, inputs="text", outputs="text").launch()
+```
+
+**Blocks** (low-level): flexible layout with explicit event wiring.
+
+```python
+import gradio as gr
+
+with gr.Blocks() as demo:
+    name = gr.Textbox(label="Name")
+    output = gr.Textbox(label="Greeting")
+    btn = gr.Button("Greet")
+    btn.click(fn=lambda n: f"Hello {n}!", inputs=name, outputs=output)
+
+demo.launch()
+```
+
+**ChatInterface**: high-level wrapper for chatbot UIs.
+
+```python
+import gradio as gr
+
+def respond(message, history):
+    return f"You said: {message}"
+
+gr.ChatInterface(fn=respond).launch()
+```
+
+## Key Component Signatures
+
+### `Textbox(value: str | I18nData | Callable | None = None, type: Literal['text', 'password', 'email'] = "text", lines: int = 1, max_lines: int | None = None, placeholder: str | I18nData | None = None, label: str | I18nData | None = None, info: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, interactive: bool | None = None, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, autofocus: bool = False, autoscroll: bool = True, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", text_align: Literal['left', 'right'] | None = None, rtl: bool = False, buttons: list[Literal['copy'] | Button] | None = None, max_length: int | None = None, submit_btn: str | bool | None = False, stop_btn: str | bool | None = False, html_attributes: InputHTMLAttributes | None = None)`
+Creates a textarea for user to enter string input or display string output..
+
+### `Number(value: float | Callable | None = None, label: str | I18nData | None = None, placeholder: str | I18nData | None = None, info: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, interactive: bool | None = None, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", buttons: list[Button] | None = None, precision: int | None = None, minimum: float | None = None, maximum: float | None = None, step: float = 1)`
+Creates a numeric field for user to enter numbers as input or display numeric output..
+
+### `Slider(minimum: float = 0, maximum: float = 100, value: float | Callable | None = None, step: float | None = None, precision: int | None = None, label: str | I18nData | None = None, info: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, interactive: bool | None = None, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", randomize: bool = False, buttons: list[Literal['reset']] | None = None)`
+Creates a slider that ranges from {minimum} to {maximum} with a step size of {step}..
+
+### `Checkbox(value: bool | Callable = False, label: str | I18nData | None = None, info: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, interactive: bool | None = None, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", buttons: list[Button] | None = None)`
+Creates a checkbox that can be set to `True` or `False`.
+
+### `Dropdown(choices: Sequence[str | int | float | tuple[str, str | int | float]] | None = None, value: str | int | float | Sequence[str | int | float] | Callable | DefaultValue | None = DefaultValue(), type: Literal['value', 'index'] = "value", multiselect: bool | None = None, allow_custom_value: bool = False, max_choices: int | None = None, filterable: bool = True, label: str | I18nData | None = None, info: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, interactive: bool | None = None, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", buttons: list[Button] | None = None)`
+Creates a dropdown of choices from which a single entry or multiple entries can be selected (as an input component) or displayed (as an output component)..
+
+### `Radio(choices: Sequence[str | int | float | tuple[str, str | int | float]] | None = None, value: str | int | float | Callable | None = None, type: Literal['value', 'index'] = "value", label: str | I18nData | None = None, info: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, interactive: bool | None = None, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", rtl: bool = False, buttons: list[Button] | None = None)`
+Creates a set of (string or numeric type) radio buttons of which only one can be selected..
+
+### `Image(value: str | PIL.Image.Image | np.ndarray | Callable | None = None, format: str = "webp", height: int | str | None = None, width: int | str | None = None, image_mode: Literal['1', 'L', 'P', 'RGB', 'RGBA', 'CMYK', 'YCbCr', 'LAB', 'HSV', 'I', 'F'] | None = "RGB", sources: list[Literal['upload', 'webcam', 'clipboard']] | Literal['upload', 'webcam', 'clipboard'] | None = None, type: Literal['numpy', 'pil', 'filepath'] = "numpy", label: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, buttons: list[Literal['download', 'share', 'fullscreen'] | Button] | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, interactive: bool | None = None, visible: bool | Literal['hidden'] = True, streaming: bool = False, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", webcam_options: WebcamOptions | None = None, placeholder: str | None = None, watermark: WatermarkOptions | None = None)`
+Creates an image component that can be used to upload images (as an input) or display images (as an output)..
+
+### `Audio(value: str | Path | tuple[int, np.ndarray] | Callable | None = None, sources: list[Literal['upload', 'microphone']] | Literal['upload', 'microphone'] | None = None, type: Literal['numpy', 'filepath'] = "numpy", label: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, interactive: bool | None = None, visible: bool | Literal['hidden'] = True, streaming: bool = False, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", format: Literal['wav', 'mp3'] | None = None, autoplay: bool = False, editable: bool = True, buttons: list[Literal['download', 'share'] | Button] | None = None, waveform_options: WaveformOptions | dict | None = None, loop: bool = False, recording: bool = False, subtitles: str | Path | list[dict[str, Any]] | None = None, playback_position: float = 0)`
+Creates an audio component that can be used to upload/record audio (as an input) or display audio (as an output)..
+
+### `Video(value: str | Path | Callable | None = None, format: str | None = None, sources: list[Literal['upload', 'webcam']] | Literal['upload', 'webcam'] | None = None, height: int | str | None = None, width: int | str | None = None, label: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, interactive: bool | None = None, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", webcam_options: WebcamOptions | None = None, include_audio: bool | None = None, autoplay: bool = False, buttons: list[Literal['download', 'share'] | Button] | None = None, loop: bool = False, streaming: bool = False, watermark: WatermarkOptions | None = None, subtitles: str | Path | list[dict[str, Any]] | None = None, playback_position: float = 0)`
+Creates a video component that can be used to upload/record videos (as an input) or display videos (as an output).
+
+### `File(value: str | list[str] | Callable | None = None, file_count: Literal['single', 'multiple', 'directory'] = "single", file_types: list[str] | None = None, type: Literal['filepath', 'binary'] = "filepath", label: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, height: int | str | float | None = None, interactive: bool | None = None, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", allow_reordering: bool = False, buttons: list[Button] | None = None)`
+Creates a file component that allows uploading one or more generic files (when used as an input) or displaying generic files or URLs for download (as output).
+
+### `Chatbot(value: list[MessageDict | Message] | Callable | None = None, label: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, container: bool = True, scale: int | None = None, min_width: int = 160, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, autoscroll: bool = True, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", height: int | str | None = 400, resizable: bool = False, max_height: int | str | None = None, min_height: int | str | None = None, editable: Literal['user', 'all'] | None = None, latex_delimiters: list[dict[str, str | bool]] | None = None, rtl: bool = False, buttons: list[Literal['share', 'copy', 'copy_all'] | Button] | None = None, watermark: str | None = None, avatar_images: tuple[str | Path | None, str | Path | None] | None = None, sanitize_html: bool = True, render_markdown: bool = True, feedback_options: list[str] | tuple[str, ...] | None = ('Like', 'Dislike'), feedback_value: Sequence[str | None] | None = None, line_breaks: bool = True, layout: Literal['panel', 'bubble'] | None = None, placeholder: str | None = None, examples: list[ExampleMessage] | None = None, allow_file_downloads: <class 'inspect._empty'> = True, group_consecutive_messages: bool = True, allow_tags: list[str] | bool = True, reasoning_tags: list[tuple[str, str]] | None = None, like_user_message: bool = False)`
+Creates a chatbot that displays user-submitted messages and responses.
+
+### `Button(value: str | I18nData | Callable = "Run", every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, variant: Literal['primary', 'secondary', 'stop', 'huggingface'] = "secondary", size: Literal['sm', 'md', 'lg'] = "lg", icon: str | Path | None = None, link: str | None = None, link_target: Literal['_self', '_blank', '_parent', '_top'] = "_self", visible: bool | Literal['hidden'] = True, interactive: bool = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", scale: int | None = None, min_width: int | None = None)`
+Creates a button that can be assigned arbitrary .click() events.
+
+### `Markdown(value: str | I18nData | Callable | None = None, label: str | I18nData | None = None, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool | None = None, rtl: bool = False, latex_delimiters: list[dict[str, str | bool]] | None = None, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", sanitize_html: bool = True, line_breaks: bool = False, header_links: bool = False, height: int | str | None = None, max_height: int | str | None = None, min_height: int | str | None = None, buttons: list[Literal['copy']] | None = None, container: bool = False, padding: bool = False)`
+Used to render arbitrary Markdown output.
+
+### `HTML(value: Any | Callable | None = None, label: str | I18nData | None = None, html_template: str = "${value}", css_template: str = "", js_on_load: str | None = "element.addEventListener('click', function() { trigger('click') });", apply_default_css: bool = True, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool = False, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", min_height: int | None = None, max_height: int | None = None, container: bool = False, padding: bool = False, autoscroll: bool = False, buttons: list[Button] | None = None, server_functions: list[Callable] | None = None, props: Any)`
+Creates a component with arbitrary HTML.
+
+
+## Custom HTML Components
+
+If a task requires significant customization of an existing component or a component that doesn't exist in Gradio, you can create one with `gr.HTML`. It supports `html_template` (with `${}` JS expressions and `{{}}` Handlebars syntax), `css_template` for scoped styles, and `js_on_load` for interactivity — where `props.value` updates the component value and `trigger('event_name')` fires Gradio events. For reuse, subclass `gr.HTML` and define `api_info()` for API/MCP support. See the [full guide](https://www.gradio.app/guides/custom-HTML-components).
+
+Here's an example that shows how to create and use these kinds of components:
+
+```python
+import gradio as gr
+
+class StarRating(gr.HTML):
+    def __init__(self, label, value=0, **kwargs):
+        html_template = """
+        <h2>${label} rating:</h2>
+        ${Array.from({length: 5}, (_, i) => `<img class='${i < value ? '' : 'faded'}' src='https://upload.wikimedia.org/wikipedia/commons/d/df/Award-star-gold-3d.svg'>`).join('')}
+        """
+        css_template = """
+            img { height: 50px; display: inline-block; cursor: pointer; }
+            .faded { filter: grayscale(100%); opacity: 0.3; }
+        """
+        js_on_load = """
+            const imgs = element.querySelectorAll('img');
+            imgs.forEach((img, index) => {
+                img.addEventListener('click', () => {
+                    props.value = index + 1;
+                });
+            });
+        """
+        super().__init__(value=value, label=label, html_template=html_template, css_template=css_template, js_on_load=js_on_load, **kwargs)
+
+    def api_info(self):
+        return {"type": "integer", "minimum": 0, "maximum": 5}
+
+
+with gr.Blocks() as demo:
+    gr.Markdown("# Restaurant Review")
+    food_rating = StarRating(label="Food", value=3)
+    service_rating = StarRating(label="Service", value=3)
+    ambience_rating = StarRating(label="Ambience", value=3)
+    average_btn = gr.Button("Calculate Average Rating")
+    rating_output = StarRating(label="Average", value=3)
+    def calculate_average(food, service, ambience):
+        return round((food + service + ambience) / 3)
+    average_btn.click(
+        fn=calculate_average,
+        inputs=[food_rating, service_rating, ambience_rating],
+        outputs=rating_output
+    )
+
+demo.launch()
+```
+
+## Event Listeners
+
+All event listeners share the same signature:
+
+```python
+component.event_name(
+    fn: Callable | None | Literal["decorator"] = "decorator",
+    inputs: Component | Sequence[Component] | set[Component] | None = None,
+    outputs: Component | Sequence[Component] | set[Component] | None = None,
+    api_name: str | None = None,
+    api_description: str | None | Literal[False] = None,
+    scroll_to_output: bool = False,
+    show_progress: Literal["full", "minimal", "hidden"] = "full",
+    show_progress_on: Component | Sequence[Component] | None = None,
+    queue: bool = True,
+    batch: bool = False,
+    max_batch_size: int = 4,
+    preprocess: bool = True,
+    postprocess: bool = True,
+    cancels: dict[str, Any] | list[dict[str, Any]] | None = None,
+    trigger_mode: Literal["once", "multiple", "always_last"] | None = None,
+    js: str | Literal[True] | None = None,
+    concurrency_limit: int | None | Literal["default"] = "default",
+    concurrency_id: str | None = None,
+    api_visibility: Literal["public", "private", "undocumented"] = "public",
+    time_limit: int | None = None,
+    stream_every: float = 0.5,
+    key: int | str | tuple[int | str, ...] | None = None,
+    validator: Callable | None = None,
+) -> Dependency
+```
+
+Supported events per component:
+
+- **AnnotatedImage**: select
+- **Audio**: stream, change, clear, play, pause, stop, pause, start_recording, pause_recording, stop_recording, upload, input
+- **BarPlot**: select, double_click
+- **BrowserState**: change
+- **Button**: click
+- **Chatbot**: change, select, like, retry, undo, example_select, option_select, clear, copy, edit
+- **Checkbox**: change, input, select
+- **CheckboxGroup**: change, input, select
+- **ClearButton**: click
+- **Code**: change, input, focus, blur
+- **ColorPicker**: change, input, submit, focus, blur
+- **Dataframe**: change, input, select, edit
+- **Dataset**: click, select
+- **DateTime**: change, submit
+- **DeepLinkButton**: click
+- **Dialogue**: change, input, submit
+- **DownloadButton**: click
+- **Dropdown**: change, input, select, focus, blur, key_up
+- **DuplicateButton**: click
+- **File**: change, select, clear, upload, delete, download
+- **FileExplorer**: change, input, select
+- **Gallery**: select, upload, change, delete, preview_close, preview_open
+- **HTML**: change, input, click, double_click, submit, stop, edit, clear, play, pause, end, start_recording, pause_recording, stop_recording, focus, blur, upload, release, select, stream, like, example_select, option_select, load, key_up, apply, delete, tick, undo, retry, expand, collapse, download, copy
+- **HighlightedText**: change, select
+- **Image**: clear, change, stream, select, upload, input
+- **ImageEditor**: clear, change, input, select, upload, apply
+- **ImageSlider**: clear, change, stream, select, upload, input
+- **JSON**: change
+- **Label**: change, select
+- **LinePlot**: select, double_click
+- **LoginButton**: click
+- **Markdown**: change, copy
+- **Model3D**: change, upload, edit, clear
+- **MultimodalTextbox**: change, input, select, submit, focus, blur, stop
+- **Navbar**: change
+- **Number**: change, input, submit, focus, blur
+- **ParamViewer**: change, upload
+- **Plot**: change
+- **Radio**: select, change, input
+- **ScatterPlot**: select, double_click
+- **SimpleImage**: clear, change, upload
+- **Slider**: change, input, release
+- **State**: change
+- **Textbox**: change, input, select, submit, focus, blur, stop, copy
+- **Timer**: tick
+- **UploadButton**: click, upload
+- **Video**: change, clear, start_recording, stop_recording, stop, play, pause, end, upload, input
+
+## Prediction CLI
+
+The `gradio` CLI includes `info` and `predict` commands for interacting with Gradio apps programmatically. These are especially useful for coding agents that need to use Spaces in their workflows.
+
+### `gradio info` — Discover endpoints and parameters
+
+```bash
+gradio info <space_id_or_url>
+```
+
+Returns a JSON payload describing all endpoints, their parameters (with types and defaults), and return values.
+
+```bash
+gradio info gradio/calculator
+# {
+#   "/predict": {
+#     "parameters": [
+#       {"name": "num1", "required": true, "default": null, "type": {"type": "number"}},
+#       {"name": "operation", "required": true, "default": null, "type": {"enum": ["add", "subtract", "multiply", "divide"], "type": "string"}},
+#       {"name": "num2", "required": true, "default": null, "type": {"type": "number"}}
+#     ],
+#     "returns": [{"name": "output", "type": {"type": "number"}}],
+#     "description": ""
+#   }
+# }
+```
+
+File-type parameters show `"type": "filepath"` with instructions to include `"meta": {"_type": "gradio.FileData"}` — this signals the file will be uploaded to the remote server.
+
+### `gradio predict` — Send predictions
+
+```bash
+gradio predict <space_id_or_url> <endpoint> <json_payload>
+```
+
+Returns a JSON object with named output keys.
+
+```bash
+# Simple numeric prediction
+gradio predict gradio/calculator /predict '{"num1": 5, "operation": "multiply", "num2": 3}'
+# {"output": 15}
+
+# Image generation
+gradio predict black-forest-labs/FLUX.2-dev /infer '{"prompt": "A majestic dragon"}'
+# {"Result": "/tmp/gradio/.../image.webp", "Seed": 1117868604}
+
+# File upload (must include meta key)
+gradio predict gradio/image_mod /predict '{"image": {"path": "/path/to/image.png", "meta": {"_type": "gradio.FileData"}}}'
+# {"output": "/tmp/gradio/.../output.png"}
+```
+
+Both commands accept `--token` for accessing private Spaces.
+
+## Additional Reference
+
+- [End-to-End Examples](examples.md) — complete working apps

.agents/skills/huggingface-gradio/examples.md

@@ -0,0 +1,613 @@
+# Gradio End-to-End Examples
+
+Complete working Gradio apps for reference.
+
+## Blocks Essay Simple
+
+```python
+import gradio as gr
+
+def change_textbox(choice):
+    if choice == "short":
+        return gr.Textbox(lines=2, visible=True)
+    elif choice == "long":
+        return gr.Textbox(lines=8, visible=True, value="Lorem ipsum dolor sit amet")
+    else:
+        return gr.Textbox(visible=False)
+
+with gr.Blocks() as demo:
+    radio = gr.Radio(
+        ["short", "long", "none"], label="What kind of essay would you like to write?"
+    )
+    text = gr.Textbox(lines=2, interactive=True, buttons=["copy"])
+    radio.change(fn=change_textbox, inputs=radio, outputs=text)
+
+demo.launch()
+```
+
+## Blocks Flipper
+
+```python
+import numpy as np
+import gradio as gr
+
+def flip_text(x):
+    return x[::-1]
+
+def flip_image(x):
+    return np.fliplr(x)
+
+with gr.Blocks() as demo:
+    gr.Markdown("Flip text or image files using this demo.")
+    with gr.Tab("Flip Text"):
+        text_input = gr.Textbox()
+        text_output = gr.Textbox()
+        text_button = gr.Button("Flip")
+    with gr.Tab("Flip Image"):
+        with gr.Row():
+            image_input = gr.Image()
+            image_output = gr.Image()
+        image_button = gr.Button("Flip")
+
+    with gr.Accordion("Open for More!", open=False):
+        gr.Markdown("Look at me...")
+        temp_slider = gr.Slider(
+            0, 1,
+            value=0.1,
+            step=0.1,
+            interactive=True,
+            label="Slide me",
+        )
+
+    text_button.click(flip_text, inputs=text_input, outputs=text_output)
+    image_button.click(flip_image, inputs=image_input, outputs=image_output)
+
+demo.launch()
+```
+
+## Blocks Form
+
+```python
+import gradio as gr
+
+with gr.Blocks() as demo:
+    name_box = gr.Textbox(label="Name")
+    age_box = gr.Number(label="Age", minimum=0, maximum=100)
+    symptoms_box = gr.CheckboxGroup(["Cough", "Fever", "Runny Nose"])
+    submit_btn = gr.Button("Submit")
+
+    with gr.Column(visible=False) as output_col:
+        diagnosis_box = gr.Textbox(label="Diagnosis")
+        patient_summary_box = gr.Textbox(label="Patient Summary")
+
+    def submit(name, age, symptoms):
+        return {
+            submit_btn: gr.Button(visible=False),
+            output_col: gr.Column(visible=True),
+            diagnosis_box: "covid" if "Cough" in symptoms else "flu",
+            patient_summary_box: f"{name}, {age} y/o",
+        }
+
+    submit_btn.click(
+        submit,
+        [name_box, age_box, symptoms_box],
+        [submit_btn, diagnosis_box, patient_summary_box, output_col],
+    )
+
+demo.launch()
+```
+
+## Blocks Hello
+
+```python
+import gradio as gr
+
+def welcome(name):
+    return f"Welcome to Gradio, {name}!"
+
+with gr.Blocks() as demo:
+    gr.Markdown(
+    """
+    # Hello World!
+    Start typing below to see the output.
+    """)
+    inp = gr.Textbox(placeholder="What is your name?")
+    out = gr.Textbox()
+    inp.change(welcome, inp, out)
+
+demo.launch()
+```
+
+## Blocks Layout
+
+```python
+import gradio as gr
+
+demo = gr.Blocks()
+
+with demo:
+    with gr.Row():
+        gr.Image(interactive=True, scale=2)
+        gr.Image()
+    with gr.Row():
+        gr.Textbox(label="Text")
+        gr.Number(label="Count", scale=2)
+        gr.Radio(choices=["One", "Two"])
+    with gr.Row():
+        gr.Button("500", scale=0, min_width=500)
+        gr.Button("A", scale=0)
+        gr.Button("grow")
+    with gr.Row():
+        gr.Textbox()
+        gr.Textbox()
+        gr.Button()
+    with gr.Row():
+        with gr.Row():
+            with gr.Column():
+                gr.Textbox(label="Text")
+                gr.Number(label="Count")
+                gr.Radio(choices=["One", "Two"])
+            gr.Image()
+            with gr.Column():
+                gr.Image(interactive=True)
+                gr.Image()
+    gr.Image()
+    gr.Textbox(label="Text")
+    gr.Number(label="Count")
+    gr.Radio(choices=["One", "Two"])
+
+demo.launch()
+```
+
+## Calculator
+
+```python
+import gradio as gr
+
+def calculator(num1, operation, num2):
+    if operation == "add":
+        return num1 + num2
+    elif operation == "subtract":
+        return num1 - num2
+    elif operation == "multiply":
+        return num1 * num2
+    elif operation == "divide":
+        if num2 == 0:
+            raise gr.Error("Cannot divide by zero!")
+        return num1 / num2
+
+demo = gr.Interface(
+    calculator,
+    [
+        "number",
+        gr.Radio(["add", "subtract", "multiply", "divide"]),
+        "number"
+    ],
+    "number",
+    examples=[
+        [45, "add", 3],
+        [3.14, "divide", 2],
+        [144, "multiply", 2.5],
+        [0, "subtract", 1.2],
+    ],
+    title="Toy Calculator",
+    description="Here's a sample toy calculator.",
+    api_name="predict"
+)
+
+demo.launch()
+```
+
+## Chatbot Simple
+
+```python
+import gradio as gr
+import random
+import time
+
+with gr.Blocks() as demo:
+    chatbot = gr.Chatbot()
+    msg = gr.Textbox()
+    clear = gr.ClearButton([msg, chatbot])
+
+    def respond(message, chat_history):
+        bot_message = random.choice(["How are you?", "Today is a great day", "I'm very hungry"])
+        chat_history.append({"role": "user", "content": message})
+        chat_history.append({"role": "assistant", "content": bot_message})
+        time.sleep(2)
+        return "", chat_history
+
+    msg.submit(respond, [msg, chatbot], [msg, chatbot])
+
+demo.launch()
+```
+
+## Chatbot Streaming
+
+```python
+import gradio as gr
+import random
+import time
+
+with gr.Blocks() as demo:
+    chatbot = gr.Chatbot()
+    msg = gr.Textbox()
+    clear = gr.Button("Clear")
+
+    def user(user_message, history: list):
+        return "", history + [{"role": "user", "content": user_message}]
+
+    def bot(history: list):
+        bot_message = random.choice(["How are you?", "I love you", "I'm very hungry"])
+        history.append({"role": "assistant", "content": ""})
+        for character in bot_message:
+            history[-1]['content'] += character
+            time.sleep(0.05)
+            yield history
+
+    msg.submit(user, [msg, chatbot], [msg, chatbot], queue=False).then(
+        bot, chatbot, chatbot
+    )
+    clear.click(lambda: None, None, chatbot, queue=False)
+
+demo.launch()
+```
+
+## Custom Css
+
+```python
+import gradio as gr
+
+with gr.Blocks() as demo:
+    with gr.Column(elem_classes="cool-col"):
+        gr.Markdown("### Gradio Demo with Custom CSS", elem_classes="darktest")
+        gr.Markdown(
+            elem_classes="markdown",
+            value="Resize the browser window to see the CSS media query in action.",
+        )
+
+if __name__ == "__main__":
+    demo.launch(css_paths=["demo/custom_css/custom_css.css"])
+```
+
+## Fake Diffusion
+
+```python
+import gradio as gr
+import numpy as np
+import time
+
+def fake_diffusion(steps):
+    rng = np.random.default_rng()
+    for i in range(steps):
+        time.sleep(1)
+        image = rng.random(size=(600, 600, 3))
+        yield image
+    image = np.ones((1000,1000,3), np.uint8)
+    image[:] = [255, 124, 0]
+    yield image
+
+demo = gr.Interface(fake_diffusion,
+                    inputs=gr.Slider(1, 10, 3, step=1),
+                    outputs="image",
+                    api_name="predict")
+
+demo.launch()
+```
+
+## Hello World
+
+```python
+import gradio as gr
+
+
+def greet(name):
+    return "Hello " + name + "!"
+
+
+demo = gr.Interface(fn=greet, inputs="textbox", outputs="textbox", api_name="predict")
+
+demo.launch()
+```
+
+## Image Editor
+
+```python
+import gradio as gr
+import time
+
+
+def sleep(im):
+    time.sleep(5)
+    return [im["background"], im["layers"][0], im["layers"][1], im["composite"]]
+
+
+def predict(im):
+    return im["composite"]
+
+
+with gr.Blocks() as demo:
+    with gr.Row():
+        im = gr.ImageEditor(
+            type="numpy",
+        )
+        im_preview = gr.Image()
+    n_upload = gr.Number(0, label="Number of upload events", step=1)
+    n_change = gr.Number(0, label="Number of change events", step=1)
+    n_input = gr.Number(0, label="Number of input events", step=1)
+
+    im.upload(lambda x: x + 1, outputs=n_upload, inputs=n_upload)
+    im.change(lambda x: x + 1, outputs=n_change, inputs=n_change)
+    im.input(lambda x: x + 1, outputs=n_input, inputs=n_input)
+    im.change(predict, outputs=im_preview, inputs=im, show_progress="hidden")
+
+demo.launch()
+```
+
+## On Listener Decorator
+
+```python
+import gradio as gr
+
+with gr.Blocks() as demo:
+    name = gr.Textbox(label="Name")
+    output = gr.Textbox(label="Output Box")
+    greet_btn = gr.Button("Greet")
+
+    @gr.on(triggers=[name.submit, greet_btn.click], inputs=name, outputs=output)
+    def greet(name):
+        return "Hello " + name + "!"
+
+demo.launch()
+```
+
+## Render Merge
+
+```python
+import gradio as gr
+import time
+
+with gr.Blocks() as demo:
+    text_count = gr.Slider(1, 5, value=1, step=1, label="Textbox Count")
+
+    @gr.render(inputs=text_count)
+    def render_count(count):
+        boxes = []
+        for i in range(count):
+            box = gr.Textbox(label=f"Box {i}")
+            boxes.append(box)
+
+        def merge(*args):
+            time.sleep(0.2)  # simulate a delay
+            return " ".join(args)
+
+        merge_btn.click(merge, boxes, output)
+
+        def clear():
+            time.sleep(0.2)  # simulate a delay
+            return [" "] * count
+
+        clear_btn.click(clear, None, boxes)
+
+        def countup():
+            time.sleep(0.2)  # simulate a delay
+            return list(range(count))
+
+        count_btn.click(countup, None, boxes, queue=False)
+
+    with gr.Row():
+        merge_btn = gr.Button("Merge")
+        clear_btn = gr.Button("Clear")
+        count_btn = gr.Button("Count")
+
+    output = gr.Textbox()
+
+demo.launch()
+```
+
+## Reverse Audio 2
+
+```python
+import gradio as gr
+import numpy as np
+
+def reverse_audio(audio):
+    sr, data = audio
+    return (sr, np.flipud(data))
+
+demo = gr.Interface(fn=reverse_audio,
+                    inputs="microphone",
+                    outputs="audio", api_name="predict")
+
+demo.launch()
+```
+
+## Sepia Filter
+
+```python
+import numpy as np
+import gradio as gr
+
+def sepia(input_img):
+    sepia_filter = np.array([
+        [0.393, 0.769, 0.189],
+        [0.349, 0.686, 0.168],
+        [0.272, 0.534, 0.131]
+    ])
+    sepia_img = input_img.dot(sepia_filter.T)
+    sepia_img /= sepia_img.max()
+    return sepia_img
+
+demo = gr.Interface(sepia, gr.Image(), "image", api_name="predict")
+demo.launch()
+```
+
+## Sort Records
+
+```python
+import gradio as gr
+
+def sort_records(records):
+    return records.sort("Quantity")
+
+demo = gr.Interface(
+    sort_records,
+    gr.Dataframe(
+        headers=["Item", "Quantity"],
+        datatype=["str", "number"],  
+        row_count=3,
+        column_count=2,
+        column_limits=(2, 2),
+        type="polars"
+    ),
+    "dataframe",
+    description="Sort by Quantity"
+)
+
+demo.launch()
+```
+
+## Streaming Simple
+
+```python
+import gradio as gr
+
+with gr.Blocks() as demo:
+    with gr.Row():
+        with gr.Column():
+            input_img = gr.Image(label="Input", sources="webcam")
+        with gr.Column():
+            output_img = gr.Image(label="Output")
+        input_img.stream(lambda s: s, input_img, output_img, time_limit=15, stream_every=0.1, concurrency_limit=30)
+
+if __name__ == "__main__":
+
+    demo.launch()
+```
+
+## Tabbed Interface Lite
+
+```python
+import gradio as gr
+
+hello_world = gr.Interface(lambda name: "Hello " + name, "text", "text", api_name="predict")
+bye_world = gr.Interface(lambda name: "Bye " + name, "text", "text", api_name="predict")
+chat = gr.ChatInterface(lambda *args: "Hello " + args[0], api_name="chat")
+
+demo = gr.TabbedInterface([hello_world, bye_world, chat], ["Hello World", "Bye World", "Chat"])
+
+demo.launch()
+```
+
+## Tax Calculator
+
+```python
+import gradio as gr
+
+def tax_calculator(income, marital_status, assets):
+    tax_brackets = [(10, 0), (25, 8), (60, 12), (120, 20), (250, 30)]
+    total_deductible = sum(cost for cost, deductible in zip(assets["Cost"], assets["Deductible"]) if deductible)
+    taxable_income = income - total_deductible
+
+    total_tax = 0
+    for bracket, rate in tax_brackets:
+        if taxable_income > bracket:
+            total_tax += (taxable_income - bracket) * rate / 100
+
+    if marital_status == "Married":
+        total_tax *= 0.75
+    elif marital_status == "Divorced":
+        total_tax *= 0.8
+
+    return round(total_tax)
+
+demo = gr.Interface(
+    tax_calculator,
+    [
+        "number",
+        gr.Radio(["Single", "Married", "Divorced"]),
+        gr.Dataframe(
+            headers=["Item", "Cost", "Deductible"],
+            datatype=["str", "number", "bool"],  
+            label="Assets Purchased this Year",
+        ),
+    ],
+    gr.Number(label="Tax due"),
+    examples=[
+        [10000, "Married", [["Suit", 5000, True], ["Laptop (for work)", 800, False], ["Car", 1800, True]]],
+        [80000, "Single", [["Suit", 800, True], ["Watch", 1800, True], ["Food", 800, True]]],
+    ],
+    live=True,
+    api_name="predict"
+)
+
+demo.launch()
+```
+
+## Timer Simple
+
+```python
+import gradio as gr
+import random
+import time
+
+with gr.Blocks() as demo:
+  timer = gr.Timer(1)
+  timestamp = gr.Number(label="Time")
+  timer.tick(lambda: round(time.time()), outputs=timestamp, api_name="timestamp")
+
+  number = gr.Number(lambda: random.randint(1, 10), every=timer, label="Random Number")
+  with gr.Row():
+    gr.Button("Start").click(lambda: gr.Timer(active=True), None, timer)
+    gr.Button("Stop").click(lambda: gr.Timer(active=False), None, timer)
+    gr.Button("Go Fast").click(lambda: 0.2, None, timer)
+
+if __name__ == "__main__":
+  demo.launch()
+```
+
+## Variable Outputs
+
+```python
+import gradio as gr
+
+max_textboxes = 10
+
+def variable_outputs(k):
+    k = int(k)
+    return [gr.Textbox(visible=True)]*k + [gr.Textbox(visible=False)]*(max_textboxes-k)
+
+with gr.Blocks() as demo:
+    s = gr.Slider(1, max_textboxes, value=max_textboxes, step=1, label="How many textboxes to show:")
+    textboxes = []
+    for i in range(max_textboxes):
+        t = gr.Textbox(f"Textbox {i}")
+        textboxes.append(t)
+
+    s.change(variable_outputs, s, textboxes)
+
+if __name__ == "__main__":
+   demo.launch()
+```
+
+## Video Identity
+
+```python
+import gradio as gr
+from gradio.media import get_video
+
+def video_identity(video):
+    return video
+
+# get_video() returns file paths to sample media included with Gradio
+demo = gr.Interface(video_identity,
+                    gr.Video(),
+                    "playable_video",
+                    examples=[
+                        get_video("world.mp4")
+                    ],
+                    cache_examples=True,
+                    api_name="predict",)
+
+demo.launch()
+```

.agents/skills/huggingface-llm-trainer/.hf-skill-manifest.json

@@ -0,0 +1,4 @@
+{
+  "installed_revision": "d0d3f4301358fc1351d408a58596d5644b5a8114",
+  "schema_version": 1
+}

.agents/skills/huggingface-llm-trainer/SKILL.md

@@ -0,0 +1,738 @@
+---
+name: huggingface-llm-trainer
+description: Train or fine-tune language and vision models using TRL (Transformer Reinforcement Learning) or Unsloth with Hugging Face Jobs infrastructure. Covers SFT, DPO, GRPO and reward modeling training methods, plus GGUF conversion for local deployment. Includes guidance on the TRL Jobs package, UV scripts with PEP 723 format, dataset preparation and validation, hardware selection, cost estimation, Trackio monitoring, Hub authentication, model selection/leaderboards and model persistence. Use for tasks involving cloud GPU training, GGUF conversion, or when users mention training on Hugging Face Jobs without local GPU setup.
+license: Complete terms in LICENSE.txt
+---
+
+# TRL Training on Hugging Face Jobs
+
+## Overview
+
+Train language models using TRL (Transformer Reinforcement Learning) on fully managed Hugging Face infrastructure. No local GPU setup required—models train on cloud GPUs and results are automatically saved to the Hugging Face Hub.
+
+**TRL provides multiple training methods:**
+- **SFT** (Supervised Fine-Tuning) - Standard instruction tuning
+- **DPO** (Direct Preference Optimization) - Alignment from preference data
+- **GRPO** (Group Relative Policy Optimization) - Online RL training
+- **Reward Modeling** - Train reward models for RLHF
+
+**For detailed TRL method documentation:**
+```python
+hf_doc_search("your query", product="trl")
+hf_doc_fetch("https://huggingface.co/docs/trl/sft_trainer")  # SFT
+hf_doc_fetch("https://huggingface.co/docs/trl/dpo_trainer")  # DPO
+# etc.
+```
+
+**See also:** `references/training_methods.md` for method overviews and selection guidance
+
+## When to Use This Skill
+
+Use this skill when users want to:
+- Fine-tune language models on cloud GPUs without local infrastructure
+- Train with TRL methods (SFT, DPO, GRPO, etc.)
+- Run training jobs on Hugging Face Jobs infrastructure
+- Convert trained models to GGUF for local deployment (Ollama, LM Studio, llama.cpp)
+- Ensure trained models are permanently saved to the Hub
+- Use modern workflows with optimized defaults
+
+### When to Use Unsloth
+
+Use **Unsloth** (`references/unsloth.md`) instead of standard TRL when:
+- **Limited GPU memory** - Unsloth uses ~60% less VRAM
+- **Speed matters** - Unsloth is ~2x faster
+- Training **large models (>13B)** - memory efficiency is critical
+- Training **Vision-Language Models (VLMs)** - Unsloth has `FastVisionModel` support
+
+See `references/unsloth.md` for complete Unsloth documentation and `scripts/unsloth_sft_example.py` for a production-ready training script.
+
+## Key Directives
+
+When assisting with training jobs:
+
+1. **ALWAYS use `hf_jobs()` MCP tool** - Submit jobs using `hf_jobs("uv", {...})`, NOT bash `trl-jobs` commands. The `script` parameter accepts Python code directly. Do NOT save to local files unless the user explicitly requests it. Pass the script content as a string to `hf_jobs()`. If user asks to "train a model", "fine-tune", or similar requests, you MUST create the training script AND submit the job immediately using `hf_jobs()`.
+
+2. **Always include Trackio** - Every training script should include Trackio for real-time monitoring. Use example scripts in `scripts/` as templates.
+
+3. **Provide job details after submission** - After submitting, provide job ID, monitoring URL, estimated time, and note that the user can request status checks later.
+
+4. **Use example scripts as templates** - Reference `scripts/train_sft_example.py`, `scripts/train_dpo_example.py`, etc. as starting points.
+
+## Local Script Execution
+
+Repository scripts use PEP 723 inline dependencies. Run them with `uv run`:
+```bash
+uv run scripts/estimate_cost.py --help
+uv run scripts/dataset_inspector.py --help
+```
+
+## Prerequisites Checklist
+
+Before starting any training job, verify:
+
+### ✅ **Account & Authentication**
+- Hugging Face Account with [Pro](https://hf.co/pro), [Team](https://hf.co/enterprise), or [Enterprise](https://hf.co/enterprise) plan (Jobs require paid plan)
+- Authenticated login: Check with `hf_whoami()`
+- **HF_TOKEN for Hub Push** ⚠️ CRITICAL - Training environment is ephemeral, must push to Hub or ALL training results are lost
+- Token must have write permissions  
+- **MUST pass `secrets={"HF_TOKEN": "$HF_TOKEN"}` in job config** to make token available (the `$HF_TOKEN` syntax
+  references your actual token value)
+
+### ✅ **Dataset Requirements**
+- Dataset must exist on Hub or be loadable via `datasets.load_dataset()`
+- Format must match training method (SFT: "messages"/text/prompt-completion; DPO: chosen/rejected; GRPO: prompt-only)
+- **ALWAYS validate unknown datasets** before GPU training to prevent format failures (see Dataset Validation section below)
+- Size appropriate for hardware (Demo: 50-100 examples on t4-small; Production: 1K-10K+ on a10g-large/a100-large)
+
+### ⚠️ **Critical Settings**
+- **Timeout must exceed expected training time** - Default 30min is TOO SHORT for most training. Minimum recommended: 1-2 hours. Job fails and loses all progress if timeout is exceeded.
+- **Hub push must be enabled** - Config: `push_to_hub=True`, `hub_model_id="username/model-name"`; Job: `secrets={"HF_TOKEN": "$HF_TOKEN"}`
+
+## Asynchronous Job Guidelines
+
+**⚠️ IMPORTANT: Training jobs run asynchronously and can take hours**
+
+### Action Required
+
+**When user requests training:**
+1. **Create the training script** with Trackio included (use `scripts/train_sft_example.py` as template)
+2. **Submit immediately** using `hf_jobs()` MCP tool with script content inline - don't save to file unless user requests
+3. **Report submission** with job ID, monitoring URL, and estimated time
+4. **Wait for user** to request status checks - don't poll automatically
+
+### Ground Rules
+- **Jobs run in background** - Submission returns immediately; training continues independently
+- **Initial logs delayed** - Can take 30-60 seconds for logs to appear
+- **User checks status** - Wait for user to request status updates
+- **Avoid polling** - Check logs only on user request; provide monitoring links instead
+
+### After Submission
+
+**Provide to user:**
+- ✅ Job ID and monitoring URL
+- ✅ Expected completion time
+- ✅ Trackio dashboard URL
+- ✅ Note that user can request status checks later
+
+**Example Response:**
+```
+✅ Job submitted successfully!
+
+Job ID: abc123xyz
+Monitor: https://huggingface.co/jobs/username/abc123xyz
+
+Expected time: ~2 hours
+Estimated cost: ~$10
+
+The job is running in the background. Ask me to check status/logs when ready!
+```
+
+## Quick Start: Three Approaches
+
+**💡 Tip for Demos:** For quick demos on smaller GPUs (t4-small), omit `eval_dataset` and `eval_strategy` to save ~40% memory. You'll still see training loss and learning progress.
+
+### Sequence Length Configuration
+
+**TRL config classes use `max_length` (not `max_seq_length`)** to control tokenized sequence length:
+
+```python
+# ✅ CORRECT - If you need to set sequence length
+SFTConfig(max_length=512)   # Truncate sequences to 512 tokens
+DPOConfig(max_length=2048)  # Longer context (2048 tokens)
+
+# ❌ WRONG - This parameter doesn't exist
+SFTConfig(max_seq_length=512)  # TypeError!
+```
+
+**Default behavior:** `max_length=1024` (truncates from right). This works well for most training.
+
+**When to override:**
+- **Longer context**: Set higher (e.g., `max_length=2048`)
+- **Memory constraints**: Set lower (e.g., `max_length=512`)
+- **Vision models**: Set `max_length=None` (prevents cutting image tokens)
+
+**Usually you don't need to set this parameter at all** - the examples below use the sensible default.
+
+### Approach 1: UV Scripts (Recommended—Default Choice)
+
+UV scripts use PEP 723 inline dependencies for clean, self-contained training. **This is the primary approach for Claude Code.**
+
+```python
+hf_jobs("uv", {
+    "script": """
+# /// script
+# dependencies = ["trl>=0.12.0", "peft>=0.7.0", "trackio"]
+# ///
+
+from datasets import load_dataset
+from peft import LoraConfig
+from trl import SFTTrainer, SFTConfig
+import trackio
+
+dataset = load_dataset("trl-lib/Capybara", split="train")
+
+# Create train/eval split for monitoring
+dataset_split = dataset.train_test_split(test_size=0.1, seed=42)
+
+trainer = SFTTrainer(
+    model="Qwen/Qwen2.5-0.5B",
+    train_dataset=dataset_split["train"],
+    eval_dataset=dataset_split["test"],
+    peft_config=LoraConfig(r=16, lora_alpha=32),
+    args=SFTConfig(
+        output_dir="my-model",
+        push_to_hub=True,
+        hub_model_id="username/my-model",
+        num_train_epochs=3,
+        eval_strategy="steps",
+        eval_steps=50,
+        report_to="trackio",
+        project="meaningful_prject_name", # project name for the training name (trackio)
+        run_name="meaningful_run_name",   # descriptive name for the specific training run (trackio)
+    )
+)
+
+trainer.train()
+trainer.push_to_hub()
+""",
+    "flavor": "a10g-large",
+    "timeout": "2h",
+    "secrets": {"HF_TOKEN": "$HF_TOKEN"}
+})
+```
+
+**Benefits:** Direct MCP tool usage, clean code, dependencies declared inline (PEP 723), no file saving required, full control
+**When to use:** Default choice for all training tasks in Claude Code, custom training logic, any scenario requiring `hf_jobs()`
+
+#### Working with Scripts
+
+⚠️ **Important:** The `script` parameter accepts either inline code (as shown above) OR a URL. **Local file paths do NOT work.**
+
+**Why local paths don't work:**
+Jobs run in isolated Docker containers without access to your local filesystem. Scripts must be:
+- Inline code (recommended for custom training)
+- Publicly accessible URLs
+- Private repo URLs (with HF_TOKEN)
+
+**Common mistakes:**
+```python
+# ❌ These will all fail
+hf_jobs("uv", {"script": "train.py"})
+hf_jobs("uv", {"script": "./scripts/train.py"})
+hf_jobs("uv", {"script": "/path/to/train.py"})
+```
+
+**Correct approaches:**
+```python
+# ✅ Inline code (recommended)
+hf_jobs("uv", {"script": "# /// script\n# dependencies = [...]\n# ///\n\n<your code>"})
+
+# ✅ From Hugging Face Hub
+hf_jobs("uv", {"script": "https://huggingface.co/user/repo/resolve/main/train.py"})
+
+# ✅ From GitHub
+hf_jobs("uv", {"script": "https://raw.githubusercontent.com/user/repo/main/train.py"})
+
+# ✅ From Gist
+hf_jobs("uv", {"script": "https://gist.githubusercontent.com/user/id/raw/train.py"})
+```
+
+**To use local scripts:** Upload to HF Hub first:
+```bash
+hf repos create my-training-scripts --type model
+hf upload my-training-scripts ./train.py train.py
+# Use: https://huggingface.co/USERNAME/my-training-scripts/resolve/main/train.py
+```
+
+### Approach 2: TRL Maintained Scripts (Official Examples)
+
+TRL provides battle-tested scripts for all methods. Can be run from URLs:
+
+```python
+hf_jobs("uv", {
+    "script": "https://github.com/huggingface/trl/blob/main/trl/scripts/sft.py",
+    "script_args": [
+        "--model_name_or_path", "Qwen/Qwen2.5-0.5B",
+        "--dataset_name", "trl-lib/Capybara",
+        "--output_dir", "my-model",
+        "--push_to_hub",
+        "--hub_model_id", "username/my-model"
+    ],
+    "flavor": "a10g-large",
+    "timeout": "2h",
+    "secrets": {"HF_TOKEN": "$HF_TOKEN"}
+})
+```
+
+**Benefits:** No code to write, maintained by TRL team, production-tested
+**When to use:** Standard TRL training, quick experiments, don't need custom code
+**Available:** Scripts are available from https://github.com/huggingface/trl/tree/main/examples/scripts
+
+### Finding More UV Scripts on Hub
+
+The `uv-scripts` organization provides ready-to-use UV scripts stored as datasets on Hugging Face Hub:
+
+```python
+# Discover available UV script collections
+dataset_search({"author": "uv-scripts", "sort": "downloads", "limit": 20})
+
+# Explore a specific collection
+hub_repo_details(["uv-scripts/classification"], repo_type="dataset", include_readme=True)
+```
+
+**Popular collections:** ocr, classification, synthetic-data, vllm, dataset-creation
+
+### Approach 3: HF Jobs CLI (Direct Terminal Commands)
+
+When the `hf_jobs()` MCP tool is unavailable, use the `hf jobs` CLI directly.
+
+**⚠️ CRITICAL: CLI Syntax Rules**
+
+```bash
+# ✅ CORRECT syntax - flags BEFORE script URL
+hf jobs uv run --flavor a10g-large --timeout 2h --secrets HF_TOKEN "https://example.com/train.py"
+
+# ❌ WRONG - "run uv" instead of "uv run"
+hf jobs run uv "https://example.com/train.py" --flavor a10g-large
+
+# ❌ WRONG - flags AFTER script URL (will be ignored!)
+hf jobs uv run "https://example.com/train.py" --flavor a10g-large
+
+# ❌ WRONG - "--secret" instead of "--secrets" (plural)
+hf jobs uv run --secret HF_TOKEN "https://example.com/train.py"
+```
+
+**Key syntax rules:**
+1. Command order is `hf jobs uv run` (NOT `hf jobs run uv`)
+2. All flags (`--flavor`, `--timeout`, `--secrets`) must come BEFORE the script URL
+3. Use `--secrets` (plural), not `--secret`
+4. Script URL must be the last positional argument
+
+**Complete CLI example:**
+```bash
+hf jobs uv run \
+  --flavor a10g-large \
+  --timeout 2h \
+  --secrets HF_TOKEN \
+  "https://huggingface.co/user/repo/resolve/main/train.py"
+```
+
+**Check job status via CLI:**
+```bash
+hf jobs ps                        # List all jobs
+hf jobs logs <job-id>             # View logs
+hf jobs inspect <job-id>          # Job details
+hf jobs cancel <job-id>           # Cancel a job
+```
+
+### Approach 4: TRL Jobs Package (Simplified Training)
+
+The `trl-jobs` package provides optimized defaults and one-liner training.
+
+```bash
+uvx trl-jobs sft \
+  --model_name Qwen/Qwen2.5-0.5B \
+  --dataset_name trl-lib/Capybara
+
+```
+
+**Benefits:** Pre-configured settings, automatic Trackio integration, automatic Hub push, one-line commands
+**When to use:** User working in terminal directly (not Claude Code context), quick local experimentation
+**Repository:** https://github.com/huggingface/trl-jobs
+
+⚠️ **In Claude Code context, prefer using `hf_jobs()` MCP tool (Approach 1) when available.**
+
+## Hardware Selection
+
+| Model Size | Recommended Hardware | Cost (approx/hr) | Use Case |
+|------------|---------------------|------------------|----------|
+| <1B params | `t4-small` | ~$0.75 | Demos, quick tests only without eval steps |
+| 1-3B params | `t4-medium`, `l4x1` | ~$1.50-2.50 | Development |
+| 3-7B params | `a10g-small`, `a10g-large` | ~$3.50-5.00 | Production training |
+| 7-13B params | `a10g-large`, `a100-large` | ~$5-10 | Large models (use LoRA) |
+| 13B+ params | `a100-large`, `a10g-largex2` | ~$10-20 | Very large (use LoRA) |
+
+**GPU Flavors:** cpu-basic/upgrade/performance/xl, t4-small/medium, l4x1/x4, a10g-small/large/largex2/largex4, a100-large, h100/h100x8
+
+**Guidelines:**
+- Use **LoRA/PEFT** for models >7B to reduce memory
+- Multi-GPU automatically handled by TRL/Accelerate
+- Start with smaller hardware for testing
+
+**See:** `references/hardware_guide.md` for detailed specifications
+
+## Critical: Saving Results to Hub
+
+**⚠️ EPHEMERAL ENVIRONMENT—MUST PUSH TO HUB**
+
+The Jobs environment is temporary. All files are deleted when the job ends. If the model isn't pushed to Hub, **ALL TRAINING IS LOST**.
+
+### Required Configuration
+
+**In training script/config:**
+```python
+SFTConfig(
+    push_to_hub=True,
+    hub_model_id="username/model-name",  # MUST specify
+    hub_strategy="every_save",  # Optional: push checkpoints
+)
+```
+
+**In job submission:**
+```python
+{
+    "secrets": {"HF_TOKEN": "$HF_TOKEN"}  # Enables authentication
+}
+```
+
+### Verification Checklist
+
+Before submitting:
+- [ ] `push_to_hub=True` set in config
+- [ ] `hub_model_id` includes username/repo-name
+- [ ] `secrets` parameter includes HF_TOKEN
+- [ ] User has write access to target repo
+
+**See:** `references/hub_saving.md` for detailed troubleshooting
+
+## Timeout Management
+
+**⚠️ DEFAULT: 30 MINUTES—TOO SHORT FOR TRAINING**
+
+### Setting Timeouts
+
+```python
+{
+    "timeout": "2h"   # 2 hours (formats: "90m", "2h", "1.5h", or seconds as integer)
+}
+```
+
+### Timeout Guidelines
+
+| Scenario | Recommended | Notes |
+|----------|-------------|-------|
+| Quick demo (50-100 examples) | 10-30 min | Verify setup |
+| Development training | 1-2 hours | Small datasets |
+| Production (3-7B model) | 4-6 hours | Full datasets |
+| Large model with LoRA | 3-6 hours | Depends on dataset |
+
+**Always add 20-30% buffer** for model/dataset loading, checkpoint saving, Hub push operations, and network delays.
+
+**On timeout:** Job killed immediately, all unsaved progress lost, must restart from beginning
+
+## Choose a Base Model (Model Selection)
+
+**Identify models to train based on task type or benchmark results.**
+
+Use `scripts/hf_benchmarks.py` to identify top-performing models for specific tasks. This helps the user select a model as the base for training, whilst keeping size and hardware constraints in mind.
+
+```bash
+# Get help on the benchmarks command:
+uv run scripts/hf_benchmarks.py --help
+```
+
+### Example -- choosing an OCR base model
+```bash
+# Search for benchmarks containing whose name contains the text `ocr`
+uv run scripts/hf_benchmarks.py search --query ocr
+
+# Get the ranked leaderboard for the allenai/olmOCR-bench benchmark 
+uv run scripts/hf_benchmarks.py leaderboard allenai/olmOCR-bench
+```
+
+## Cost Estimation
+
+**Offer to estimate cost when planning jobs with known parameters.** Use `scripts/estimate_cost.py`:
+
+```bash
+uv run scripts/estimate_cost.py \
+  --model meta-llama/Llama-2-7b-hf \
+  --dataset trl-lib/Capybara \
+  --hardware a10g-large \
+  --dataset-size 16000 \
+  --epochs 3
+```
+
+Output includes estimated time, cost, recommended timeout (with buffer), and optimization suggestions.
+
+**When to offer:** User planning a job, asks about cost/time, choosing hardware, job will run >1 hour or cost >$5
+
+## Example Training Scripts
+
+**Production-ready templates with all best practices:**
+
+Load these scripts for correctly:
+
+- **`scripts/train_sft_example.py`** - Complete SFT training with Trackio, LoRA, checkpoints
+- **`scripts/train_dpo_example.py`** - DPO training for preference learning
+- **`scripts/train_grpo_example.py`** - GRPO training for online RL
+
+These scripts demonstrate proper Hub saving, Trackio integration, checkpoint management, and optimized parameters. Pass their content inline to `hf_jobs()` or use as templates for custom scripts.
+
+## Monitoring and Tracking
+
+**Trackio** provides real-time metrics visualization. See `references/trackio_guide.md` for complete setup guide.
+
+**Key points:**
+- Add `trackio` to dependencies
+- Configure trainer with `report_to="trackio" and run_name="meaningful_name"`
+
+### Trackio Configuration Defaults
+
+**Use sensible defaults unless user specifies otherwise.** When generating training scripts with Trackio:
+
+**Default Configuration:**
+- **Space ID**: `{username}/trackio` (use "trackio" as default space name)
+- **Run naming**: Unless otherwise specified, name the run in a way the user will recognize (e.g., descriptive of the task, model, or purpose)
+- **Config**: Keep minimal - only include hyperparameters and model/dataset info
+- **Project Name**: Use a Project Name to associate runs with a particular Project 
+
+**User overrides:** If user requests specific trackio configuration (custom space, run naming, grouping, or additional config), apply their preferences instead of defaults.
+
+
+This is useful for managing multiple jobs with the same configuration or keeping training scripts portable.
+
+See `references/trackio_guide.md` for complete documentation including grouping runs for experiments.
+
+### Check Job Status
+
+```python
+# List all jobs
+hf_jobs("ps")
+
+# Inspect specific job
+hf_jobs("inspect", {"job_id": "your-job-id"})
+
+# View logs
+hf_jobs("logs", {"job_id": "your-job-id"})
+```
+
+**Remember:** Wait for user to request status checks. Avoid polling repeatedly.
+
+## Dataset Validation
+
+**Validate dataset format BEFORE launching GPU training to prevent the #1 cause of training failures: format mismatches.**
+
+### Why Validate
+
+- 50%+ of training failures are due to dataset format issues
+- DPO especially strict: requires exact column names (`prompt`, `chosen`, `rejected`)
+- Failed GPU jobs waste $1-10 and 30-60 minutes
+- Validation on CPU costs ~$0.01 and takes <1 minute
+
+### When to Validate
+
+**ALWAYS validate for:**
+- Unknown or custom datasets
+- DPO training (CRITICAL - 90% of datasets need mapping)
+- Any dataset not explicitly TRL-compatible
+
+**Skip validation for known TRL datasets:**
+- `trl-lib/ultrachat_200k`, `trl-lib/Capybara`, `HuggingFaceH4/ultrachat_200k`, etc.
+
+### Usage
+
+```python
+hf_jobs("uv", {
+    "script": "https://huggingface.co/datasets/mcp-tools/skills/raw/main/dataset_inspector.py",
+    "script_args": ["--dataset", "username/dataset-name", "--split", "train"]
+})
+```
+
+The script is fast, and will usually complete synchronously.
+
+### Reading Results
+
+The output shows compatibility for each training method:
+
+- **`✓ READY`** - Dataset is compatible, use directly
+- **`✗ NEEDS MAPPING`** - Compatible but needs preprocessing (mapping code provided)
+- **`✗ INCOMPATIBLE`** - Cannot be used for this method
+
+When mapping is needed, the output includes a **"MAPPING CODE"** section with copy-paste ready Python code.
+
+### Example Workflow
+
+```python
+# 1. Inspect dataset (costs ~$0.01, <1 min on CPU)
+hf_jobs("uv", {
+    "script": "https://huggingface.co/datasets/mcp-tools/skills/raw/main/dataset_inspector.py",
+    "script_args": ["--dataset", "argilla/distilabel-math-preference-dpo", "--split", "train"]
+})
+
+# 2. Check output markers:
+#    ✓ READY → proceed with training
+#    ✗ NEEDS MAPPING → apply mapping code below
+#    ✗ INCOMPATIBLE → choose different method/dataset
+
+# 3. If mapping needed, apply before training:
+def format_for_dpo(example):
+    return {
+        'prompt': example['instruction'],
+        'chosen': example['chosen_response'],
+        'rejected': example['rejected_response'],
+    }
+dataset = dataset.map(format_for_dpo, remove_columns=dataset.column_names)
+
+# 4. Launch training job with confidence
+```
+
+### Common Scenario: DPO Format Mismatch
+
+Most DPO datasets use non-standard column names. Example:
+
+```
+Dataset has: instruction, chosen_response, rejected_response
+DPO expects: prompt, chosen, rejected
+```
+
+The validator detects this and provides exact mapping code to fix it.
+
+## Converting Models to GGUF
+
+After training, convert models to **GGUF format** for use with llama.cpp, Ollama, LM Studio, and other local inference tools.
+
+**What is GGUF:**
+- Optimized for CPU/GPU inference with llama.cpp
+- Supports quantization (4-bit, 5-bit, 8-bit) to reduce model size
+- Compatible with Ollama, LM Studio, Jan, GPT4All, llama.cpp
+- Typically 2-8GB for 7B models (vs 14GB unquantized)
+
+**When to convert:**
+- Running models locally with Ollama or LM Studio
+- Reducing model size with quantization
+- Deploying to edge devices
+- Sharing models for local-first use
+
+**See:** `references/gguf_conversion.md` for complete conversion guide, including production-ready conversion script, quantization options, hardware requirements, usage examples, and troubleshooting.
+
+**Quick conversion:**
+```python
+hf_jobs("uv", {
+    "script": "<see references/gguf_conversion.md for complete script>",
+    "flavor": "a10g-large",
+    "timeout": "45m",
+    "secrets": {"HF_TOKEN": "$HF_TOKEN"},
+    "env": {
+        "ADAPTER_MODEL": "username/my-finetuned-model",
+        "BASE_MODEL": "Qwen/Qwen2.5-0.5B",
+        "OUTPUT_REPO": "username/my-model-gguf"
+    }
+})
+```
+
+## Common Training Patterns
+
+See `references/training_patterns.md` for detailed examples including:
+- Quick demo (5-10 minutes)
+- Production with checkpoints
+- Multi-GPU training
+- DPO training (preference learning)
+- GRPO training (online RL)
+
+## Common Failure Modes
+
+### Out of Memory (OOM)
+
+**Fix (try in order):**
+1. Reduce batch size: `per_device_train_batch_size=1`, increase `gradient_accumulation_steps=8`. Effective batch size is `per_device_train_batch_size` x `gradient_accumulation_steps`. For best performance keep effective batch size close to 128. 
+2. Enable: `gradient_checkpointing=True`
+3. Upgrade hardware: t4-small → l4x1, a10g-small → a10g-large etc. 
+
+### Dataset Misformatted
+
+**Fix:**
+1. Validate first with dataset inspector:
+   ```bash
+   uv run https://huggingface.co/datasets/mcp-tools/skills/raw/main/dataset_inspector.py \
+     --dataset name --split train
+   ```
+2. Check output for compatibility markers (✓ READY, ✗ NEEDS MAPPING, ✗ INCOMPATIBLE)
+3. Apply mapping code from inspector output if needed
+
+### Job Timeout
+
+**Fix:**
+1. Check logs for actual runtime: `hf_jobs("logs", {"job_id": "..."})`
+2. Increase timeout with buffer: `"timeout": "3h"` (add 30% to estimated time)
+3. Or reduce training: lower `num_train_epochs`, use smaller dataset, enable `max_steps`
+4. Save checkpoints: `save_strategy="steps"`, `save_steps=500`, `hub_strategy="every_save"`
+
+**Note:** Default 30min is insufficient for real training. Minimum 1-2 hours.
+
+### Hub Push Failures
+
+**Fix:**
+1. Add to job: `secrets={"HF_TOKEN": "$HF_TOKEN"}`
+2. Add to config: `push_to_hub=True`, `hub_model_id="username/model-name"`
+3. Verify auth: `mcp__huggingface__hf_whoami()`
+4. Check token has write permissions and repo exists (or set `hub_private_repo=True`)
+
+### Missing Dependencies
+
+**Fix:**
+Add to PEP 723 header:
+```python
+# /// script
+# dependencies = ["trl>=0.12.0", "peft>=0.7.0", "trackio", "missing-package"]
+# ///
+```
+
+## Troubleshooting
+
+**Common issues:**
+- Job times out → Increase timeout, reduce epochs/dataset, use smaller model/LoRA
+- Model not saved to Hub → Check push_to_hub=True, hub_model_id, secrets=HF_TOKEN
+- Out of Memory (OOM) → Reduce batch size, increase gradient accumulation, enable LoRA, use larger GPU
+- Dataset format error → Validate with dataset inspector (see Dataset Validation section)
+- Import/module errors → Add PEP 723 header with dependencies, verify format
+- Authentication errors → Check `mcp__huggingface__hf_whoami()`, token permissions, secrets parameter
+
+**See:** `references/troubleshooting.md` for complete troubleshooting guide
+
+## Resources
+
+### References (In This Skill)
+- `references/training_methods.md` - Overview of SFT, DPO, GRPO, KTO, PPO, Reward Modeling
+- `references/training_patterns.md` - Common training patterns and examples
+- `references/unsloth.md` - Unsloth for fast VLM training (~2x speed, 60% less VRAM)
+- `references/gguf_conversion.md` - Complete GGUF conversion guide
+- `references/trackio_guide.md` - Trackio monitoring setup
+- `references/hardware_guide.md` - Hardware specs and selection
+- `references/hub_saving.md` - Hub authentication troubleshooting
+- `references/troubleshooting.md` - Common issues and solutions
+- `references/local_training_macos.md` - Local training on macOS
+
+### Scripts (In This Skill)
+- `scripts/train_sft_example.py` - Production SFT template
+- `scripts/train_dpo_example.py` - Production DPO template
+- `scripts/train_grpo_example.py` - Production GRPO template
+- `scripts/unsloth_sft_example.py` - Unsloth text LLM training template (faster, less VRAM)
+- `scripts/estimate_cost.py` - Estimate time and cost (offer when appropriate)
+- `scripts/convert_to_gguf.py` - Complete GGUF conversion script
+- `scripts/hf_benchmarks.py` - Search for benchmark results and leaderboards by task, alias or free text.
+
+### External Scripts
+- [Dataset Inspector](https://huggingface.co/datasets/mcp-tools/skills/raw/main/dataset_inspector.py) - Validate dataset format before training (use via `uv run` or `hf_jobs`)
+
+### External Links
+- [TRL Documentation](https://huggingface.co/docs/trl)
+- [TRL Jobs Training Guide](https://huggingface.co/docs/trl/en/jobs_training)
+- [TRL Jobs Package](https://github.com/huggingface/trl-jobs)
+- [HF Jobs Documentation](https://huggingface.co/docs/huggingface_hub/guides/jobs)
+- [TRL Example Scripts](https://github.com/huggingface/trl/tree/main/examples/scripts)
+- [UV Scripts Guide](https://docs.astral.sh/uv/guides/scripts/)
+- [UV Scripts Organization](https://huggingface.co/uv-scripts)
+
+## Key Takeaways
+
+1. **Submit scripts inline** - The `script` parameter accepts Python code directly; no file saving required unless user requests
+2. **Jobs are asynchronous** - Don't wait/poll; let user check when ready
+3. **Always set timeout** - Default 30 min is insufficient; minimum 1-2 hours recommended
+4. **Always enable Hub push** - Environment is ephemeral; without push, all results lost
+5. **Include Trackio** - Use example scripts as templates for real-time monitoring
+6. **Offer cost estimation** - When parameters are known, use `scripts/estimate_cost.py`
+7. **Use UV scripts (Approach 1)** - Default to `hf_jobs("uv", {...})` with inline scripts; TRL maintained scripts for standard training; avoid bash `trl-jobs` commands in Claude Code
+8. **Use hf_doc_fetch/hf_doc_search** for latest TRL documentation
+9. **Validate dataset format** before training with dataset inspector (see Dataset Validation section)
+10. **Choose appropriate hardware** for model size; use LoRA for models >7B

.agents/skills/huggingface-llm-trainer/references/gguf_conversion.md

@@ -0,0 +1,296 @@
+# GGUF Conversion Guide
+
+After training models with TRL on Hugging Face Jobs, convert them to **GGUF format** for use with llama.cpp, Ollama, LM Studio, and other local inference tools.
+
+**This guide provides production-ready, tested code based on successful conversions.** All critical dependencies and build steps are included.
+
+## What is GGUF?
+
+**GGUF** (GPT-Generated Unified Format):
+- Optimized format for CPU/GPU inference with llama.cpp
+- Supports quantization (4-bit, 5-bit, 8-bit) to reduce model size
+- Compatible with: Ollama, LM Studio, Jan, GPT4All, llama.cpp
+- Typically 2-8GB for 7B models (vs 14GB unquantized)
+
+## When to Convert to GGUF
+
+**Convert when:**
+- Running models locally with Ollama or LM Studio
+- Using CPU-optimized inference
+- Reducing model size with quantization
+- Deploying to edge devices
+- Sharing models for local-first use
+
+## Critical Success Factors
+
+Based on production testing, these are **essential** for reliable conversion:
+
+### 1. ✅ Install Build Tools FIRST
+**Before cloning llama.cpp**, install build dependencies:
+```python
+subprocess.run(["apt-get", "update", "-qq"], check=True, capture_output=True)
+subprocess.run(["apt-get", "install", "-y", "-qq", "build-essential", "cmake"], check=True, capture_output=True)
+```
+
+**Why:** The quantization tool requires gcc and cmake. Installing after cloning doesn't help.
+
+### 2. ✅ Use CMake (Not Make)
+**Build the quantize tool with CMake:**
+```python
+# Create build directory
+os.makedirs("/tmp/llama.cpp/build", exist_ok=True)
+
+# Configure
+subprocess.run([
+    "cmake", "-B", "/tmp/llama.cpp/build", "-S", "/tmp/llama.cpp",
+    "-DGGML_CUDA=OFF"  # Faster build, CUDA not needed for quantization
+], check=True, capture_output=True, text=True)
+
+# Build
+subprocess.run([
+    "cmake", "--build", "/tmp/llama.cpp/build",
+    "--target", "llama-quantize", "-j", "4"
+], check=True, capture_output=True, text=True)
+
+# Binary path
+quantize_bin = "/tmp/llama.cpp/build/bin/llama-quantize"
+```
+
+**Why:** CMake is more reliable than `make` and produces consistent binary paths.
+
+### 3. ✅ Include All Dependencies
+**PEP 723 header must include:**
+```python
+# /// script
+# dependencies = [
+#     "transformers>=4.36.0",
+#     "peft>=0.7.0",
+#     "torch>=2.0.0",
+#     "accelerate>=0.24.0",
+#     "huggingface_hub>=0.20.0",
+#     "sentencepiece>=0.1.99",  # Required for tokenizer
+#     "protobuf>=3.20.0",        # Required for tokenizer
+#     "numpy",
+#     "gguf",
+# ]
+# ///
+```
+
+**Why:** `sentencepiece` and `protobuf` are critical for tokenizer conversion. Missing them causes silent failures.
+
+### 4. ✅ Verify Names Before Use
+**Always verify repos exist:**
+```python
+# Before submitting job, verify:
+hub_repo_details([ADAPTER_MODEL], repo_type="model")
+hub_repo_details([BASE_MODEL], repo_type="model")
+```
+
+**Why:** Non-existent dataset/model names cause job failures that could be caught in seconds.
+
+## Complete Conversion Script
+
+See `scripts/convert_to_gguf.py` for the complete, production-ready script.
+
+**Key features:**
+- ✅ All dependencies in PEP 723 header
+- ✅ Build tools installed automatically
+- ✅ CMake build process (reliable)
+- ✅ Comprehensive error handling
+- ✅ Environment variable configuration
+- ✅ Automatic README generation
+
+## Quick Conversion Job
+
+```python
+# Before submitting: VERIFY MODELS EXIST
+hub_repo_details(["username/my-finetuned-model"], repo_type="model")
+hub_repo_details(["Qwen/Qwen2.5-0.5B"], repo_type="model")
+
+# Submit conversion job
+hf_jobs("uv", {
+    "script": open("trl/scripts/convert_to_gguf.py").read(),  # Or inline the script
+    "flavor": "a10g-large",
+    "timeout": "45m",
+    "secrets": {"HF_TOKEN": "$HF_TOKEN"},
+    "env": {
+        "ADAPTER_MODEL": "username/my-finetuned-model",
+        "BASE_MODEL": "Qwen/Qwen2.5-0.5B",
+        "OUTPUT_REPO": "username/my-model-gguf",
+        "HF_USERNAME": "username"  # Optional, for README
+    }
+})
+```
+
+## Conversion Process
+
+The script performs these steps:
+
+1. **Load and Merge** - Load base model and LoRA adapter, merge them
+2. **Install Build Tools** - Install gcc, cmake (CRITICAL: before cloning llama.cpp)
+3. **Setup llama.cpp** - Clone repo, install Python dependencies
+4. **Convert to GGUF** - Create FP16 GGUF using llama.cpp converter
+5. **Build Quantize Tool** - Use CMake to build `llama-quantize`
+6. **Quantize** - Create Q4_K_M, Q5_K_M, Q8_0 versions
+7. **Upload** - Upload all versions + README to Hub
+
+## Quantization Options
+
+Common quantization formats (from smallest to largest):
+
+| Format | Size | Quality | Use Case |
+|--------|------|---------|----------|
+| **Q4_K_M** | ~300MB | Good | **Recommended** - best balance of size/quality |
+| **Q5_K_M** | ~350MB | Better | Higher quality, slightly larger |
+| **Q8_0** | ~500MB | Very High | Near-original quality |
+| **F16** | ~1GB | Original | Full precision, largest file |
+
+**Recommendation:** Create Q4_K_M, Q5_K_M, and Q8_0 versions to give users options.
+
+## Hardware Requirements
+
+**For conversion:**
+- Small models (<1B): CPU-basic works, but slow
+- Medium models (1-7B): a10g-large recommended
+- Large models (7B+): a10g-large or a100-large
+
+**Time estimates:**
+- 0.5B model: ~15-25 minutes on A10G
+- 3B model: ~30-45 minutes on A10G
+- 7B model: ~45-60 minutes on A10G
+
+## Using GGUF Models
+
+**GGUF models work on both CPU and GPU.** They're optimized for CPU inference but can also leverage GPU acceleration when available.
+
+### With Ollama (auto-detects GPU)
+```bash
+# Download GGUF
+hf download username/my-model-gguf model-q4_k_m.gguf
+
+# Create Modelfile
+echo "FROM ./model-q4_k_m.gguf" > Modelfile
+
+# Create and run (uses GPU automatically if available)
+ollama create my-model -f Modelfile
+ollama run my-model
+```
+
+### With llama.cpp
+```bash
+# CPU only
+./llama-cli -m model-q4_k_m.gguf -p "Your prompt"
+
+# With GPU acceleration (offload 32 layers to GPU)
+./llama-cli -m model-q4_k_m.gguf -ngl 32 -p "Your prompt"
+```
+
+### With LM Studio
+1. Download the `.gguf` file
+2. Import into LM Studio
+3. Start chatting
+
+## Best Practices
+
+### ✅ DO:
+1. **Verify repos exist** before submitting jobs (use `hub_repo_details`)
+2. **Install build tools FIRST** before cloning llama.cpp
+3. **Use CMake** for building quantize tool (not make)
+4. **Include all dependencies** in PEP 723 header (especially sentencepiece, protobuf)
+5. **Create multiple quantizations** - Give users choice
+6. **Test on known models** before production use
+7. **Use A10G GPU** for faster conversion
+
+### ❌ DON'T:
+1. **Assume repos exist** - Always verify with hub tools
+2. **Use make** instead of CMake - Less reliable
+3. **Remove dependencies** to "simplify" - They're all needed
+4. **Skip build tools** - Quantization will fail silently
+5. **Use default paths** - CMake puts binaries in build/bin/
+
+## Common Issues
+
+### Out of memory during merge
+**Fix:**
+- Use larger GPU (a10g-large or a100-large)
+- Ensure `device_map="auto"` for automatic placement
+- Use `dtype=torch.float16` or `torch.bfloat16`
+
+### Conversion fails with architecture error
+**Fix:**
+- Ensure llama.cpp supports the model architecture
+- Check for standard architecture (Qwen, Llama, Mistral, etc.)
+- Update llama.cpp to latest: `git clone --depth 1 https://github.com/ggerganov/llama.cpp.git`
+- Check llama.cpp documentation for model support
+
+### Quantization fails
+**Fix:**
+- Verify build tools installed: `apt-get install build-essential cmake`
+- Use CMake (not make) to build quantize tool
+- Check binary path: `/tmp/llama.cpp/build/bin/llama-quantize`
+- Verify FP16 GGUF exists before quantizing
+
+### Missing sentencepiece error
+**Fix:**
+- Add to PEP 723 header: `"sentencepiece>=0.1.99", "protobuf>=3.20.0"`
+- Don't remove dependencies to "simplify" - all are required
+
+### Upload fails or times out
+**Fix:**
+- Large models (>2GB) need longer timeout: `"timeout": "1h"`
+- Upload quantized versions separately if needed
+- Check network/Hub status
+
+## Lessons Learned
+
+These are from production testing and real failures:
+
+### 1. Always Verify Before Use
+**Lesson:** Don't assume repos/datasets exist. Check first.
+```python
+# BEFORE submitting job
+hub_repo_details(["trl-lib/argilla-dpo-mix-7k"], repo_type="dataset")  # Would catch error
+```
+**Prevented failures:** Non-existent dataset names, typos in model names
+
+### 2. Prioritize Reliability Over Performance
+**Lesson:** Default to what's most likely to succeed.
+- Use CMake (not make) - more reliable
+- Disable CUDA in build - faster, not needed
+- Include all dependencies - don't "simplify"
+
+**Prevented failures:** Build failures, missing binaries
+
+### 3. Create Atomic, Self-Contained Scripts
+**Lesson:** Don't remove dependencies or steps. Scripts should work as a unit.
+- All dependencies in PEP 723 header
+- All build steps included
+- Clear error messages
+
+**Prevented failures:** Missing tokenizer libraries, build tool failures
+
+## References
+
+**In this skill:**
+- `scripts/convert_to_gguf.py` - Complete, production-ready script
+
+**External:**
+- [llama.cpp Repository](https://github.com/ggerganov/llama.cpp)
+- [GGUF Specification](https://github.com/ggerganov/ggml/blob/master/docs/gguf.md)
+- [Ollama Documentation](https://ollama.ai)
+- [LM Studio](https://lmstudio.ai)
+
+## Summary
+
+**Critical checklist for GGUF conversion:**
+- [ ] Verify adapter and base models exist on Hub
+- [ ] Use production script from `scripts/convert_to_gguf.py`
+- [ ] All dependencies in PEP 723 header (including sentencepiece, protobuf)
+- [ ] Build tools installed before cloning llama.cpp
+- [ ] CMake used for building quantize tool (not make)
+- [ ] Correct binary path: `/tmp/llama.cpp/build/bin/llama-quantize`
+- [ ] A10G GPU selected for reasonable conversion time
+- [ ] Timeout set to 45m minimum
+- [ ] HF_TOKEN in secrets for Hub upload
+
+**The script in `scripts/convert_to_gguf.py` incorporates all these lessons and has been tested successfully in production.**

.agents/skills/huggingface-llm-trainer/references/hardware_guide.md

@@ -0,0 +1,283 @@
+# Hardware Selection Guide
+
+Choosing the right hardware (flavor) is critical for cost-effective training.
+
+## Available Hardware
+
+### CPU
+- `cpu-basic` - Basic CPU, testing only
+- `cpu-upgrade` - Enhanced CPU
+
+**Use cases:** Dataset validation, preprocessing, testing scripts
+**Not recommended for training:** Too slow for any meaningful training
+
+### GPU Options
+
+| Flavor | GPU | Memory | Use Case | Cost/hour |
+|--------|-----|--------|----------|-----------|
+| `t4-small` | NVIDIA T4 | 16GB | <1B models, demos | ~$0.50-1 |
+| `t4-medium` | NVIDIA T4 | 16GB | 1-3B models, development | ~$1-2 |
+| `l4x1` | NVIDIA L4 | 24GB | 3-7B models, efficient training | ~$2-3 |
+| `l4x4` | 4x NVIDIA L4 | 96GB | Multi-GPU training | ~$8-12 |
+| `a10g-small` | NVIDIA A10G | 24GB | 3-7B models, production | ~$3-4 |
+| `a10g-large` | NVIDIA A10G | 24GB | 7-13B models | ~$4-6 |
+| `a10g-largex2` | 2x NVIDIA A10G | 48GB | Multi-GPU, large models | ~$8-12 |
+| `a10g-largex4` | 4x NVIDIA A10G | 96GB | Multi-GPU, very large models | ~$16-24 |
+| `a100-large` | NVIDIA A100 | 40GB | 13B+ models, fast training | ~$8-12 |
+
+### TPU Options
+
+| Flavor | Type | Use Case |
+|--------|------|----------|
+| `v5e-1x1` | TPU v5e | Small TPU workloads |
+| `v5e-2x2` | 4x TPU v5e | Medium TPU workloads |
+| `v5e-2x4` | 8x TPU v5e | Large TPU workloads |
+
+**Note:** TPUs require TPU-optimized code. Most TRL training uses GPUs.
+
+## Selection Guidelines
+
+### By Model Size
+
+**Tiny Models (<1B parameters)**
+- **Recommended:** `t4-small`
+- **Example:** Qwen2.5-0.5B, TinyLlama
+- **Batch size:** 4-8
+- **Training time:** 1-2 hours for 1K examples
+
+**Small Models (1-3B parameters)**
+- **Recommended:** `t4-medium` or `a10g-small`
+- **Example:** Qwen2.5-1.5B, Phi-2
+- **Batch size:** 2-4
+- **Training time:** 2-4 hours for 10K examples
+
+**Medium Models (3-7B parameters)**
+- **Recommended:** `a10g-small` or `a10g-large`
+- **Example:** Qwen2.5-7B, Mistral-7B
+- **Batch size:** 1-2 (or LoRA with 4-8)
+- **Training time:** 4-8 hours for 10K examples
+
+**Large Models (7-13B parameters)**
+- **Recommended:** `a10g-large` or `a100-large`
+- **Example:** Llama-3-8B, Mixtral-8x7B (with LoRA)
+- **Batch size:** 1 (full fine-tuning) or 2-4 (LoRA)
+- **Training time:** 6-12 hours for 10K examples
+- **Note:** Always use LoRA/PEFT
+
+**Very Large Models (13B+ parameters)**
+- **Recommended:** `a100-large` with LoRA
+- **Example:** Llama-3-13B, Llama-3-70B (LoRA only)
+- **Batch size:** 1-2 with LoRA
+- **Training time:** 8-24 hours for 10K examples
+- **Note:** Full fine-tuning not feasible, use LoRA/PEFT
+
+### By Budget
+
+**Minimal Budget (<$5 total)**
+- Use `t4-small`
+- Train on subset of data (100-500 examples)
+- Limit to 1-2 epochs
+- Use small model (<1B)
+
+**Small Budget ($5-20)**
+- Use `t4-medium` or `a10g-small`
+- Train on 1K-5K examples
+- 2-3 epochs
+- Model up to 3B parameters
+
+**Medium Budget ($20-50)**
+- Use `a10g-small` or `a10g-large`
+- Train on 5K-20K examples
+- 3-5 epochs
+- Model up to 7B parameters
+
+**Large Budget ($50-200)**
+- Use `a10g-large` or `a100-large`
+- Full dataset training
+- Multiple epochs
+- Model up to 13B parameters with LoRA
+
+### By Training Type
+
+**Quick Demo/Experiment**
+- `t4-small`
+- 50-100 examples
+- 5-10 steps
+- ~10-15 minutes
+
+**Development/Iteration**
+- `t4-medium` or `a10g-small`
+- 1K examples
+- 1 epoch
+- ~30-60 minutes
+
+**Production Training**
+- `a10g-large` or `a100-large`
+- Full dataset
+- 3-5 epochs
+- 4-12 hours
+
+**Research/Experimentation**
+- `a100-large`
+- Multiple runs
+- Various hyperparameters
+- Budget for 20-50 hours
+
+## Memory Considerations
+
+### Estimating Memory Requirements
+
+**Full fine-tuning:**
+```
+Memory (GB) ≈ (Model params in billions) × 20
+```
+
+**LoRA fine-tuning:**
+```
+Memory (GB) ≈ (Model params in billions) × 4
+```
+
+**Examples:**
+- Qwen2.5-0.5B full: ~10GB ✅ fits t4-small
+- Qwen2.5-1.5B full: ~30GB ❌ exceeds most GPUs
+- Qwen2.5-1.5B LoRA: ~6GB ✅ fits t4-small
+- Qwen2.5-7B full: ~140GB ❌ not feasible
+- Qwen2.5-7B LoRA: ~28GB ✅ fits a10g-large
+
+### Memory Optimization
+
+If hitting memory limits:
+
+1. **Use LoRA/PEFT**
+   ```python
+   peft_config=LoraConfig(r=16, lora_alpha=32)
+   ```
+
+2. **Reduce batch size**
+   ```python
+   per_device_train_batch_size=1
+   ```
+
+3. **Increase gradient accumulation**
+   ```python
+   gradient_accumulation_steps=8  # Effective batch size = 1×8
+   ```
+
+4. **Enable gradient checkpointing**
+   ```python
+   gradient_checkpointing=True
+   ```
+
+5. **Use mixed precision**
+   ```python
+   bf16=True  # or fp16=True
+   ```
+
+6. **Upgrade to larger GPU**
+   - t4 → a10g → a100
+
+## Cost Estimation
+
+### Formula
+
+```
+Total Cost = (Hours of training) × (Cost per hour)
+```
+
+### Example Calculations
+
+**Quick demo:**
+- Hardware: t4-small ($0.75/hour)
+- Time: 15 minutes (0.25 hours)
+- Cost: $0.19
+
+**Development training:**
+- Hardware: a10g-small ($3.50/hour)
+- Time: 2 hours
+- Cost: $7.00
+
+**Production training:**
+- Hardware: a10g-large ($5/hour)
+- Time: 6 hours
+- Cost: $30.00
+
+**Large model with LoRA:**
+- Hardware: a100-large ($10/hour)
+- Time: 8 hours
+- Cost: $80.00
+
+### Cost Optimization Tips
+
+1. **Start small:** Test on t4-small with subset
+2. **Use LoRA:** 4-5x cheaper than full fine-tuning
+3. **Optimize hyperparameters:** Fewer epochs if possible
+4. **Set appropriate timeout:** Don't waste compute on stalled jobs
+5. **Use checkpointing:** Resume if job fails
+6. **Monitor costs:** Check running jobs regularly
+
+## Multi-GPU Training
+
+TRL automatically handles multi-GPU training with Accelerate when using multi-GPU flavors.
+
+**Multi-GPU flavors:**
+- `l4x4` - 4x L4 GPUs
+- `a10g-largex2` - 2x A10G GPUs
+- `a10g-largex4` - 4x A10G GPUs
+
+**When to use:**
+- Models >13B parameters
+- Need faster training (linear speedup)
+- Large datasets (>50K examples)
+
+**Example:**
+```python
+hf_jobs("uv", {
+    "script": "train.py",
+    "flavor": "a10g-largex2",  # 2 GPUs
+    "timeout": "4h",
+    "secrets": {"HF_TOKEN": "$HF_TOKEN"}
+})
+```
+
+No code changes needed—TRL/Accelerate handles distribution automatically.
+
+## Choosing Between Options
+
+### a10g vs a100
+
+**Choose a10g when:**
+- Model <13B parameters
+- Budget conscious
+- Training time not critical
+
+**Choose a100 when:**
+- Model 13B+ parameters
+- Need fastest training
+- Memory requirements high
+- Budget allows
+
+### Single vs Multi-GPU
+
+**Choose single GPU when:**
+- Model <7B parameters
+- Budget constrained
+- Simpler debugging
+
+**Choose multi-GPU when:**
+- Model >13B parameters
+- Need faster training
+- Large batch sizes required
+- Cost-effective for large jobs
+
+## Quick Reference
+
+```python
+# Model size → Hardware selection
+HARDWARE_MAP = {
+    "<1B":     "t4-small",
+    "1-3B":    "a10g-small",
+    "3-7B":    "a10g-large",
+    "7-13B":   "a10g-large (LoRA) or a100-large",
+    ">13B":    "a100-large (LoRA required)"
+}
+```

.agents/skills/huggingface-llm-trainer/references/hub_saving.md

@@ -0,0 +1,364 @@
+# Saving Training Results to Hugging Face Hub
+
+**⚠️ CRITICAL:** Training environments are ephemeral. ALL results are lost when a job completes unless pushed to the Hub.
+
+## Why Hub Push is Required
+
+When running on Hugging Face Jobs:
+- Environment is temporary
+- All files deleted on job completion
+- No local disk persistence
+- Cannot access results after job ends
+
+**Without Hub push, training is completely wasted.**
+
+## Required Configuration
+
+### 1. Training Configuration
+
+In your SFTConfig or trainer config:
+
+```python
+SFTConfig(
+    push_to_hub=True,                    # Enable Hub push
+    hub_model_id="username/model-name",   # Target repository
+)
+```
+
+### 2. Job Configuration
+
+When submitting the job:
+
+```python
+hf_jobs("uv", {
+    "script": "train.py",
+    "secrets": {"HF_TOKEN": "$HF_TOKEN"}  # Provide authentication
+})
+```
+
+**The `$HF_TOKEN` placeholder is automatically replaced with your Hugging Face token.**
+
+## Complete Example
+
+```python
+# train.py
+# /// script
+# dependencies = ["trl"]
+# ///
+
+from trl import SFTTrainer, SFTConfig
+from datasets import load_dataset
+
+dataset = load_dataset("trl-lib/Capybara", split="train")
+
+# Configure with Hub push
+config = SFTConfig(
+    output_dir="my-model",
+    num_train_epochs=3,
+    
+    # ✅ CRITICAL: Hub push configuration
+    push_to_hub=True,
+    hub_model_id="myusername/my-trained-model",
+    
+    # Optional: Push strategy
+    push_to_hub_model_id="myusername/my-trained-model",
+    push_to_hub_organization=None,
+    push_to_hub_token=None,  # Uses environment token
+)
+
+trainer = SFTTrainer(
+    model="Qwen/Qwen2.5-0.5B",
+    train_dataset=dataset,
+    args=config,
+)
+
+trainer.train()
+
+# ✅ Push final model
+trainer.push_to_hub()
+
+print("✅ Model saved to: https://huggingface.co/myusername/my-trained-model")
+```
+
+**Submit with authentication:**
+
+```python
+hf_jobs("uv", {
+    "script": "train.py",
+    "flavor": "a10g-large",
+    "timeout": "2h",
+    "secrets": {"HF_TOKEN": "$HF_TOKEN"}  # ✅ Required!
+})
+```
+
+## What Gets Saved
+
+When `push_to_hub=True`:
+
+1. **Model weights** - Final trained parameters
+2. **Tokenizer** - Associated tokenizer
+3. **Configuration** - Model config (config.json)
+4. **Training arguments** - Hyperparameters used
+5. **Model card** - Auto-generated documentation
+6. **Checkpoints** - If `save_strategy="steps"` enabled
+
+## Checkpoint Saving
+
+Save intermediate checkpoints during training:
+
+```python
+SFTConfig(
+    output_dir="my-model",
+    push_to_hub=True,
+    hub_model_id="username/my-model",
+    
+    # Checkpoint configuration
+    save_strategy="steps",
+    save_steps=100,              # Save every 100 steps
+    save_total_limit=3,          # Keep only last 3 checkpoints
+)
+```
+
+**Benefits:**
+- Resume training if job fails
+- Compare checkpoint performance
+- Use intermediate models
+
+**Checkpoints are pushed to:** `username/my-model` (same repo)
+
+## Authentication Methods
+
+### Method 1: Automatic Token (Recommended)
+
+```python
+"secrets": {"HF_TOKEN": "$HF_TOKEN"}
+```
+
+Uses your logged-in Hugging Face token automatically.
+
+### Method 2: Explicit Token
+
+```python
+"secrets": {"HF_TOKEN": "hf_abc123..."}
+```
+
+Provide token explicitly (not recommended for security).
+
+### Method 3: Environment Variable
+
+```python
+"env": {"HF_TOKEN": "hf_abc123..."}
+```
+
+Pass as regular environment variable (less secure than secrets).
+
+**Always prefer Method 1** for security and convenience.
+
+## Verification Checklist
+
+Before submitting any training job, verify:
+
+- [ ] `push_to_hub=True` in training config
+- [ ] `hub_model_id` is specified (format: `username/model-name`)
+- [ ] `secrets={"HF_TOKEN": "$HF_TOKEN"}` in job config
+- [ ] Repository name doesn't conflict with existing repos
+- [ ] You have write access to the target namespace
+
+## Repository Setup
+
+### Automatic Creation
+
+If repository doesn't exist, it's created automatically when first pushing.
+
+### Manual Creation
+
+Create repository before training:
+
+```python
+from huggingface_hub import HfApi
+
+api = HfApi()
+api.create_repo(
+    repo_id="username/model-name",
+    repo_type="model",
+    private=False,  # or True for private repo
+)
+```
+
+### Repository Naming
+
+**Valid names:**
+- `username/my-model`
+- `username/model-name`
+- `organization/model-name`
+
+**Invalid names:**
+- `model-name` (missing username)
+- `username/model name` (spaces not allowed)
+- `username/MODEL` (uppercase discouraged)
+
+## Troubleshooting
+
+### Error: 401 Unauthorized
+
+**Cause:** HF_TOKEN not provided or invalid
+
+**Solutions:**
+1. Verify `secrets={"HF_TOKEN": "$HF_TOKEN"}` in job config
+2. Check you're logged in: `hf auth whoami`
+3. Re-login: `hf auth login`
+
+### Error: 403 Forbidden
+
+**Cause:** No write access to repository
+
+**Solutions:**
+1. Check repository namespace matches your username
+2. Verify you're a member of organization (if using org namespace)
+3. Check repository isn't private (if accessing org repo)
+
+### Error: Repository not found
+
+**Cause:** Repository doesn't exist and auto-creation failed
+
+**Solutions:**
+1. Manually create repository first
+2. Check repository name format
+3. Verify namespace exists
+
+### Error: Push failed during training
+
+**Cause:** Network issues or Hub unavailable
+
+**Solutions:**
+1. Training continues but final push fails
+2. Checkpoints may be saved
+3. Re-run push manually after job completes
+
+### Issue: Model saved but not visible
+
+**Possible causes:**
+1. Repository is private—check https://huggingface.co/username
+2. Wrong namespace—verify `hub_model_id` matches login
+3. Push still in progress—wait a few minutes
+
+## Manual Push After Training
+
+If training completes but push fails, push manually:
+
+```python
+from transformers import AutoModel, AutoTokenizer
+
+# Load from local checkpoint
+model = AutoModel.from_pretrained("./output_dir")
+tokenizer = AutoTokenizer.from_pretrained("./output_dir")
+
+# Push to Hub
+model.push_to_hub("username/model-name", token="hf_abc123...")
+tokenizer.push_to_hub("username/model-name", token="hf_abc123...")
+```
+
+**Note:** Only possible if job hasn't completed (files still exist).
+
+## Best Practices
+
+1. **Always enable `push_to_hub=True`**
+2. **Use checkpoint saving** for long training runs
+3. **Verify Hub push** in logs before job completes
+4. **Set appropriate `save_total_limit`** to avoid excessive checkpoints
+5. **Use descriptive repo names** (e.g., `qwen-capybara-sft` not `model1`)
+6. **Add model card** with training details
+7. **Tag models** with relevant tags (e.g., `text-generation`, `fine-tuned`)
+
+## Monitoring Push Progress
+
+Check logs for push progress:
+
+```python
+hf_jobs("logs", {"job_id": "your-job-id"})
+```
+
+**Look for:**
+```
+Pushing model to username/model-name...
+Upload file pytorch_model.bin: 100%
+✅ Model pushed successfully
+```
+
+## Example: Full Production Setup
+
+```python
+# production_train.py
+# /// script
+# dependencies = ["trl>=0.12.0", "peft>=0.7.0"]
+# ///
+
+from datasets import load_dataset
+from peft import LoraConfig
+from trl import SFTTrainer, SFTConfig
+import os
+
+# Verify token is available
+assert "HF_TOKEN" in os.environ, "HF_TOKEN not found in environment!"
+
+# Load dataset
+dataset = load_dataset("trl-lib/Capybara", split="train")
+print(f"✅ Dataset loaded: {len(dataset)} examples")
+
+# Configure with comprehensive Hub settings
+config = SFTConfig(
+    output_dir="qwen-capybara-sft",
+    
+    # Hub configuration
+    push_to_hub=True,
+    hub_model_id="myusername/qwen-capybara-sft",
+    hub_strategy="checkpoint",  # Push checkpoints
+    
+    # Checkpoint configuration
+    save_strategy="steps",
+    save_steps=100,
+    save_total_limit=3,
+    
+    # Training settings
+    num_train_epochs=3,
+    per_device_train_batch_size=4,
+    
+    # Logging
+    logging_steps=10,
+    logging_first_step=True,
+)
+
+# Train with LoRA
+trainer = SFTTrainer(
+    model="Qwen/Qwen2.5-0.5B",
+    train_dataset=dataset,
+    args=config,
+    peft_config=LoraConfig(r=16, lora_alpha=32),
+)
+
+print("🚀 Starting training...")
+trainer.train()
+
+print("💾 Pushing final model to Hub...")
+trainer.push_to_hub()
+
+print("✅ Training complete!")
+print(f"Model available at: https://huggingface.co/myusername/qwen-capybara-sft")
+```
+
+**Submit:**
+
+```python
+hf_jobs("uv", {
+    "script": "production_train.py",
+    "flavor": "a10g-large",
+    "timeout": "6h",
+    "secrets": {"HF_TOKEN": "$HF_TOKEN"}
+})
+```
+
+## Key Takeaway
+
+**Without `push_to_hub=True` and `secrets={"HF_TOKEN": "$HF_TOKEN"}`, all training results are permanently lost.**
+
+Always verify both are configured before submitting any training job.

.agents/skills/huggingface-llm-trainer/references/local_training_macos.md

@@ -0,0 +1,231 @@
+# Local Training on macOS (Apple Silicon)
+
+Run small LoRA fine-tuning jobs locally on Mac for smoke tests and quick iteration before submitting to HF Jobs.
+
+## When to Use Local Mac vs HF Jobs
+
+| Local Mac | HF Jobs / Cloud GPU |
+|-----------|-------------------|
+| Model ≤3B, text-only | Model 7B+ |
+| LoRA/PEFT only | QLoRA 4-bit (CUDA/bitsandbytes) |
+| Short context (≤1024) | Long context / full fine-tuning |
+| Smoke tests, dataset validation | Production runs, VLMs |
+
+**Typical workflow:** local smoke test → HF Jobs with same config → export/quantize ([gguf_conversion.md](gguf_conversion.md))
+
+## Recommended Defaults
+
+| Setting | Value | Notes |
+|---------|-------|-------|
+| Model size | 0.5B–1.5B first run | Scale up after verifying |
+| Max seq length | 512–1024 | Lower = less memory |
+| Batch size | 1 | Scale via gradient accumulation |
+| Gradient accumulation | 8–16 | Effective batch = 8–16 |
+| LoRA rank (r) | 8–16 | alpha = 2×r |
+| Dtype | float32 | fp16 causes NaN on MPS; bf16 only on M1 Pro+ and M2/M3/M4 |
+
+### Memory by hardware
+
+| Unified RAM | Max Model Size |
+|-------------|---------------|
+| 16 GB | ~0.5B–1.5B |
+| 32 GB | ~1.5B–3B |
+| 64 GB | ~3B (short context) |
+
+## Setup
+
+```bash
+xcode-select --install
+python3 -m venv .venv && source .venv/bin/activate
+pip install -U "torch>=2.2" "transformers>=4.40" "trl>=0.12" "peft>=0.10" \
+    datasets accelerate safetensors huggingface_hub
+```
+
+Verify MPS:
+```bash
+python -c "import torch; print(torch.__version__, '| MPS:', torch.backends.mps.is_available())"
+```
+
+Optional — configure Accelerate for local Mac (no distributed, no mixed precision, MPS device):
+```bash
+accelerate config
+```
+
+## Training Script
+
+<details>
+<summary><strong>train_lora_sft.py</strong></summary>
+
+```python
+import os
+from dataclasses import dataclass
+from typing import Optional
+import torch
+from datasets import load_dataset
+from transformers import AutoModelForCausalLM, AutoTokenizer, set_seed
+from peft import LoraConfig
+from trl import SFTTrainer, SFTConfig
+
+set_seed(42)
+
+@dataclass
+class Cfg:
+    model_id: str = os.environ.get("MODEL_ID", "Qwen/Qwen2.5-0.5B-Instruct")
+    dataset_id: str = os.environ.get("DATASET_ID", "HuggingFaceH4/ultrachat_200k")
+    dataset_split: str = os.environ.get("DATASET_SPLIT", "train_sft[:500]")
+    data_files: Optional[str] = os.environ.get("DATA_FILES", None)
+    text_field: str = os.environ.get("TEXT_FIELD", "")
+    messages_field: str = os.environ.get("MESSAGES_FIELD", "messages")
+    out_dir: str = os.environ.get("OUT_DIR", "outputs/local-lora")
+    max_seq_length: int = int(os.environ.get("MAX_SEQ_LENGTH", "512"))
+    max_steps: int = int(os.environ.get("MAX_STEPS", "-1"))
+
+cfg = Cfg()
+device = "mps" if torch.backends.mps.is_available() else "cpu"
+
+tokenizer = AutoTokenizer.from_pretrained(cfg.model_id, use_fast=True)
+if tokenizer.pad_token is None:
+    tokenizer.pad_token = tokenizer.eos_token
+tokenizer.padding_side = "right"
+
+model = AutoModelForCausalLM.from_pretrained(cfg.model_id, torch_dtype=torch.float32)
+model.to(device)
+model.config.use_cache = False
+
+if cfg.data_files:
+    ds = load_dataset("json", data_files=cfg.data_files, split="train")
+else:
+    ds = load_dataset(cfg.dataset_id, split=cfg.dataset_split)
+
+def format_example(ex):
+    if cfg.text_field and isinstance(ex.get(cfg.text_field), str):
+        ex["text"] = ex[cfg.text_field]
+        return ex
+    msgs = ex.get(cfg.messages_field)
+    if isinstance(msgs, list):
+        if hasattr(tokenizer, "apply_chat_template"):
+            try:
+                ex["text"] = tokenizer.apply_chat_template(msgs, tokenize=False, add_generation_prompt=False)
+                return ex
+            except Exception:
+                pass
+        ex["text"] = "\n".join([str(m) for m in msgs])
+        return ex
+    ex["text"] = str(ex)
+    return ex
+
+ds = ds.map(format_example)
+ds = ds.remove_columns([c for c in ds.column_names if c != "text"])
+
+lora = LoraConfig(r=16, lora_alpha=32, lora_dropout=0.05, bias="none",
+                  task_type="CAUSAL_LM", target_modules=["q_proj", "k_proj", "v_proj", "o_proj"])
+
+sft_kwargs = dict(
+    output_dir=cfg.out_dir, per_device_train_batch_size=1, gradient_accumulation_steps=8,
+    learning_rate=2e-4, logging_steps=10, save_steps=200, save_total_limit=2,
+    gradient_checkpointing=True, report_to="none", fp16=False, bf16=False,
+    max_seq_length=cfg.max_seq_length, dataset_text_field="text",
+)
+if cfg.max_steps > 0:
+    sft_kwargs["max_steps"] = cfg.max_steps
+else:
+    sft_kwargs["num_train_epochs"] = 1
+
+trainer = SFTTrainer(model=model, train_dataset=ds, peft_config=lora,
+                     args=SFTConfig(**sft_kwargs), processing_class=tokenizer)
+trainer.train()
+trainer.save_model(cfg.out_dir)
+print(f"✅ Saved to: {cfg.out_dir}")
+```
+
+</details>
+
+### Run
+
+```bash
+python train_lora_sft.py
+```
+
+**Env overrides:**
+
+```bash
+MODEL_ID="Qwen/Qwen2.5-1.5B-Instruct" python train_lora_sft.py   # different model
+MAX_STEPS=50 python train_lora_sft.py                              # quick 50-step test
+DATA_FILES="my_data.jsonl" python train_lora_sft.py                # local JSONL file
+PYTORCH_ENABLE_MPS_FALLBACK=1 python train_lora_sft.py             # MPS op fallback to CPU
+PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.0 python train_lora_sft.py      # disable MPS memory limit (use with caution)
+```
+
+**Local JSONL format** — chat messages or plain text:
+```jsonl
+{"messages": [{"role": "user", "content": "Hello"}, {"role": "assistant", "content": "Hi!"}]}
+```
+```jsonl
+{"text": "User: Hello\nAssistant: Hi!"}
+```
+For plain text: `DATA_FILES="file.jsonl" TEXT_FIELD="text" MESSAGES_FIELD="" python train_lora_sft.py`
+
+### Verify Success
+
+- Loss decreases over steps
+- `outputs/local-lora/` contains `adapter_config.json` + `*.safetensors`
+
+## Quick Evaluation
+
+<details>
+<summary><strong>eval_generate.py</strong></summary>
+
+```python
+import os, torch
+from transformers import AutoTokenizer, AutoModelForCausalLM
+from peft import PeftModel
+
+BASE = os.environ.get("MODEL_ID", "Qwen/Qwen2.5-0.5B-Instruct")
+ADAPTER = os.environ.get("ADAPTER_DIR", "outputs/local-lora")
+device = "mps" if torch.backends.mps.is_available() else "cpu"
+
+tokenizer = AutoTokenizer.from_pretrained(BASE, use_fast=True)
+model = AutoModelForCausalLM.from_pretrained(BASE, torch_dtype=torch.float32)
+model.to(device)
+model = PeftModel.from_pretrained(model, ADAPTER)
+
+prompt = os.environ.get("PROMPT", "Explain gradient accumulation in 3 bullet points.")
+inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
+with torch.no_grad():
+    out = model.generate(**inputs, max_new_tokens=120, do_sample=True, temperature=0.7, top_p=0.9)
+print(tokenizer.decode(out[0], skip_special_tokens=True))
+```
+
+</details>
+
+## Troubleshooting (macOS-Specific)
+
+For general training issues, see [troubleshooting.md](troubleshooting.md).
+
+| Problem | Fix |
+|---------|-----|
+| MPS unsupported op / crash | `PYTORCH_ENABLE_MPS_FALLBACK=1` |
+| OOM / system instability | Reduce `MAX_SEQ_LENGTH`, use smaller model, set `PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.0` (caution) |
+| fp16 NaN / loss explosion | Keep `fp16=False` (default), lower learning rate |
+| LoRA "module not found" | Print `model.named_modules()` to find correct target names |
+| TRL TypeError on args | Check TRL version; script uses `SFTConfig` + `processing_class` (TRL ≥0.12) |
+| Intel Mac | No MPS — use HF Jobs instead |
+
+**Common LoRA target modules by architecture:**
+
+| Architecture | target_modules |
+|-------------|---------------|
+| Llama/Qwen/Mistral | `q_proj`, `k_proj`, `v_proj`, `o_proj` |
+| GPT-2/GPT-J | `c_attn`, `c_proj` |
+| BLOOM | `query_key_value`, `dense` |
+
+## MLX Alternative
+
+[MLX](https://github.com/ml-explore/mlx) offers tighter Apple Silicon integration but has a smaller ecosystem and less mature training APIs. For this skill's workflow (local validation → HF Jobs), PyTorch + MPS is recommended for consistency. See [mlx-lm](https://github.com/ml-explore/mlx-lm) for MLX-based fine-tuning.
+
+## See Also
+
+- [troubleshooting.md](troubleshooting.md) — General TRL troubleshooting
+- [hardware_guide.md](hardware_guide.md) — GPU selection for HF Jobs
+- [gguf_conversion.md](gguf_conversion.md) — Export for on-device inference
+- [training_methods.md](training_methods.md) — SFT, DPO, GRPO overview

.agents/skills/huggingface-llm-trainer/references/reliability_principles.md

@@ -0,0 +1,371 @@
+# Reliability Principles for Training Jobs
+
+These principles are derived from real production failures and successful fixes. Following them prevents common failure modes and ensures reliable job execution.
+
+## Principle 1: Always Verify Before Use
+
+**Rule:** Never assume repos, datasets, or resources exist. Verify with tools first.
+
+### What It Prevents
+
+- **Non-existent datasets** - Jobs fail immediately when dataset doesn't exist
+- **Typos in names** - Simple mistakes like "argilla-dpo-mix-7k" vs "ultrafeedback_binarized"
+- **Incorrect paths** - Old or moved repos, renamed files
+- **Missing dependencies** - Undocumented requirements
+
+### How to Apply
+
+**Before submitting ANY job:**
+
+```python
+# Verify dataset exists
+dataset_search({"query": "dataset-name", "author": "author-name", "limit": 5})
+hub_repo_details(["author/dataset-name"], repo_type="dataset")
+
+# Verify model exists
+hub_repo_details(["org/model-name"], repo_type="model")
+
+# Check script/file paths (for URL-based scripts)
+# Verify before using: https://github.com/user/repo/blob/main/script.py
+```
+
+**Examples that would have caught errors:**
+
+```python
+# ❌ WRONG: Assumed dataset exists
+hf_jobs("uv", {
+    "script": """...""",
+    "env": {"DATASET": "trl-lib/argilla-dpo-mix-7k"}  # Doesn't exist!
+})
+
+# ✅ CORRECT: Verify first
+dataset_search({"query": "argilla dpo", "author": "trl-lib"})
+# Would show: "trl-lib/ultrafeedback_binarized" is the correct name
+
+hub_repo_details(["trl-lib/ultrafeedback_binarized"], repo_type="dataset")
+# Confirms it exists before using
+```
+
+### Implementation Checklist
+
+- [ ] Check dataset exists before training
+- [ ] Verify base model exists before fine-tuning
+- [ ] Confirm adapter model exists before GGUF conversion
+- [ ] Test script URLs are valid before submitting
+- [ ] Validate file paths in repositories
+- [ ] Check for recent updates/renames of resources
+
+**Time cost:** 5-10 seconds  
+**Time saved:** Hours of failed job time + debugging
+
+---
+
+## Principle 2: Prioritize Reliability Over Performance
+
+**Rule:** Default to what is most likely to succeed, not what is theoretically fastest.
+
+### What It Prevents
+
+- **Hardware incompatibilities** - Features that fail on certain GPUs
+- **Unstable optimizations** - Speed-ups that cause crashes
+- **Complex configurations** - More failure points
+- **Build system issues** - Unreliable compilation methods
+
+### How to Apply
+
+**Choose reliability:**
+
+```python
+# ❌ RISKY: Aggressive optimization that may fail
+SFTConfig(
+    torch_compile=True,  # Can fail on T4, A10G GPUs
+    optim="adamw_bnb_8bit",  # Requires specific setup
+    fp16=False,  # May cause training instability
+    ...
+)
+
+# ✅ SAFE: Proven defaults
+SFTConfig(
+    # torch_compile=True,  # Commented with note: "Enable on H100 for 20% speedup"
+    optim="adamw_torch",  # Standard, always works
+    fp16=True,  # Stable and fast
+    ...
+)
+```
+
+**For build processes:**
+
+```python
+# ❌ UNRELIABLE: Uses make (platform-dependent)
+subprocess.run(["make", "-C", "/tmp/llama.cpp", "llama-quantize"], check=True)
+
+# ✅ RELIABLE: Uses CMake (consistent, documented)
+subprocess.run([
+    "cmake", "-B", "/tmp/llama.cpp/build", "-S", "/tmp/llama.cpp",
+    "-DGGML_CUDA=OFF"  # Disable CUDA for faster, more reliable build
+], check=True)
+
+subprocess.run([
+    "cmake", "--build", "/tmp/llama.cpp/build",
+    "--target", "llama-quantize", "-j", "4"
+], check=True)
+```
+
+### Real-World Example
+
+**The `torch.compile` failure:**
+- Added for "20% speedup" on H100
+- **Failed fatally on T4-medium** with cryptic error
+- Misdiagnosed as dataset issue (cost hours)
+- **Fix:** Disable by default, add as optional comment
+
+**Result:** Reliability > 20% performance gain
+
+### Implementation Checklist
+
+- [ ] Use proven, standard configurations by default
+- [ ] Comment out performance optimizations with hardware notes
+- [ ] Use stable build systems (CMake > make)
+- [ ] Test on target hardware before production
+- [ ] Document known incompatibilities
+- [ ] Provide "safe" and "fast" variants when needed
+
+**Performance loss:** 10-20% in best case  
+**Reliability gain:** 95%+ success rate vs 60-70%
+
+---
+
+## Principle 3: Create Atomic, Self-Contained Scripts
+
+**Rule:** Scripts should work as complete, independent units. Don't remove parts to "simplify."
+
+### What It Prevents
+
+- **Missing dependencies** - Removed "unnecessary" packages that are actually required
+- **Incomplete processes** - Skipped steps that seem redundant
+- **Environment assumptions** - Scripts that need pre-setup
+- **Partial failures** - Some parts work, others fail silently
+
+### How to Apply
+
+**Complete dependency specifications:**
+
+```python
+# ❌ INCOMPLETE: "Simplified" by removing dependencies
+# /// script
+# dependencies = [
+#     "transformers",
+#     "peft",
+#     "torch",
+# ]
+# ///
+
+# ✅ COMPLETE: All dependencies explicit
+# /// script
+# dependencies = [
+#     "transformers>=4.36.0",
+#     "peft>=0.7.0",
+#     "torch>=2.0.0",
+#     "accelerate>=0.24.0",
+#     "huggingface_hub>=0.20.0",
+#     "sentencepiece>=0.1.99",  # Required for tokenizers
+#     "protobuf>=3.20.0",        # Required for tokenizers
+#     "numpy",
+#     "gguf",
+# ]
+# ///
+```
+
+**Complete build processes:**
+
+```python
+# ❌ INCOMPLETE: Assumes build tools exist
+subprocess.run(["git", "clone", "https://github.com/ggerganov/llama.cpp.git", "/tmp/llama.cpp"])
+subprocess.run(["make", "-C", "/tmp/llama.cpp", "llama-quantize"])  # FAILS: no gcc/make
+
+# ✅ COMPLETE: Installs all requirements
+subprocess.run(["apt-get", "update", "-qq"], check=True)
+subprocess.run(["apt-get", "install", "-y", "-qq", "build-essential", "cmake"], check=True)
+subprocess.run(["git", "clone", "https://github.com/ggerganov/llama.cpp.git", "/tmp/llama.cpp"])
+# ... then build
+```
+
+### Real-World Example
+
+**The `sentencepiece` failure:**
+- Original script had it: worked fine
+- "Simplified" version removed it: "doesn't look necessary"
+- **GGUF conversion failed silently** - tokenizer couldn't convert
+- Hard to debug: no obvious error message
+- **Fix:** Restore all original dependencies
+
+**Result:** Don't remove dependencies without thorough testing
+
+### Implementation Checklist
+
+- [ ] All dependencies in PEP 723 header with version pins
+- [ ] All system packages installed by script
+- [ ] No assumptions about pre-existing environment
+- [ ] No "optional" steps that are actually required
+- [ ] Test scripts in clean environment
+- [ ] Document why each dependency is needed
+
+**Complexity:** Slightly longer scripts  
+**Reliability:** Scripts "just work" every time
+
+---
+
+## Principle 4: Provide Clear Error Context
+
+**Rule:** When things fail, make it obvious what went wrong and how to fix it.
+
+### How to Apply
+
+**Wrap subprocess calls:**
+
+```python
+# ❌ UNCLEAR: Silent failure
+subprocess.run([...], check=True, capture_output=True)
+
+# ✅ CLEAR: Shows what failed
+try:
+    result = subprocess.run(
+        [...],
+        check=True,
+        capture_output=True,
+        text=True
+    )
+    print(result.stdout)
+    if result.stderr:
+        print("Warnings:", result.stderr)
+except subprocess.CalledProcessError as e:
+    print(f"❌ Command failed!")
+    print("STDOUT:", e.stdout)
+    print("STDERR:", e.stderr)
+    raise
+```
+
+**Validate inputs:**
+
+```python
+# ❌ UNCLEAR: Fails later with cryptic error
+model = load_model(MODEL_NAME)
+
+# ✅ CLEAR: Fails fast with clear message
+if not MODEL_NAME:
+    raise ValueError("MODEL_NAME environment variable not set!")
+
+print(f"Loading model: {MODEL_NAME}")
+try:
+    model = load_model(MODEL_NAME)
+    print(f"✅ Model loaded successfully")
+except Exception as e:
+    print(f"❌ Failed to load model: {MODEL_NAME}")
+    print(f"Error: {e}")
+    print("Hint: Check that model exists on Hub")
+    raise
+```
+
+### Implementation Checklist
+
+- [ ] Wrap external calls with try/except
+- [ ] Print stdout/stderr on failure
+- [ ] Validate environment variables early
+- [ ] Add progress indicators (✅, ❌, 🔄)
+- [ ] Include hints for common failures
+- [ ] Log configuration at start
+
+---
+
+## Principle 5: Test the Happy Path on Known-Good Inputs
+
+**Rule:** Before using new code in production, test with inputs you know work.
+
+### How to Apply
+
+**Known-good test inputs:**
+
+```python
+# For training
+TEST_DATASET = "trl-lib/Capybara"  # Small, well-formatted, widely used
+TEST_MODEL = "Qwen/Qwen2.5-0.5B"  # Small, fast, reliable
+
+# For GGUF conversion
+TEST_ADAPTER = "evalstate/qwen-capybara-medium"  # Known working model
+TEST_BASE = "Qwen/Qwen2.5-0.5B"  # Compatible base
+```
+
+**Testing workflow:**
+
+1. Test with known-good inputs first
+2. If that works, try production inputs
+3. If production fails, you know it's the inputs (not code)
+4. Isolate the difference
+
+### Implementation Checklist
+
+- [ ] Maintain list of known-good test models/datasets
+- [ ] Test new scripts with test inputs first
+- [ ] Document what makes inputs "good"
+- [ ] Keep test jobs cheap (small models, short timeouts)
+- [ ] Only move to production after test succeeds
+
+**Time cost:** 5-10 minutes for test run  
+**Debugging time saved:** Hours
+
+---
+
+## Summary: The Reliability Checklist
+
+Before submitting ANY job:
+
+### Pre-Flight Checks
+- [ ] **Verified** all repos/datasets exist (hub_repo_details)
+- [ ] **Tested** with known-good inputs if new code
+- [ ] **Using** proven hardware/configuration
+- [ ] **Included** all dependencies in PEP 723 header
+- [ ] **Installed** system requirements (build tools, etc.)
+- [ ] **Set** appropriate timeout (not default 30m)
+- [ ] **Configured** Hub push with HF_TOKEN
+- [ ] **Added** clear error handling
+
+### Script Quality
+- [ ] Self-contained (no external setup needed)
+- [ ] Complete dependencies listed
+- [ ] Build tools installed by script
+- [ ] Progress indicators included
+- [ ] Error messages are clear
+- [ ] Configuration logged at start
+
+### Job Configuration
+- [ ] Timeout > expected runtime + 30% buffer
+- [ ] Hardware appropriate for model size
+- [ ] Secrets include HF_TOKEN
+- [ ] Environment variables set correctly
+- [ ] Cost estimated and acceptable
+
+**Following these principles transforms job success rate from ~60-70% to ~95%+**
+
+---
+
+## When Principles Conflict
+
+Sometimes reliability and performance conflict. Here's how to choose:
+
+| Scenario | Choose | Rationale |
+|----------|--------|-----------|
+| Demo/test | Reliability | Fast failure is worse than slow success |
+| Production (first run) | Reliability | Prove it works before optimizing |
+| Production (proven) | Performance | Safe to optimize after validation |
+| Time-critical | Reliability | Failures cause more delay than slow runs |
+| Cost-critical | Balanced | Test with small model, then optimize |
+
+**General rule:** Reliability first, optimize second.
+
+---
+
+## Further Reading
+
+- `troubleshooting.md` - Common issues and fixes
+- `training_patterns.md` - Proven training configurations
+- `gguf_conversion.md` - Production GGUF workflow

.agents/skills/huggingface-llm-trainer/references/trackio_guide.md

@@ -0,0 +1,189 @@
+# Trackio Integration for TRL Training
+
+**Trackio** is an experiment tracking library that provides real-time metrics visualization for remote training on Hugging Face Jobs infrastructure.
+
+⚠️ **IMPORTANT**: For Jobs training (remote cloud GPUs):
+- Training happens on ephemeral cloud runners (not your local machine)
+- Trackio syncs metrics to a Hugging Face Space for real-time monitoring
+- Without a Space, metrics are lost when the job completes
+- The Space dashboard persists your training metrics permanently
+
+## Setting Up Trackio for Jobs
+
+**Step 1: Add trackio dependency**
+```python
+# /// script
+# dependencies = [
+#     "trl>=0.12.0",
+#     "trackio",  # Required!
+# ]
+# ///
+```
+
+**Step 2: Create a Trackio Space (one-time setup)**
+
+**Option A: Let Trackio auto-create (Recommended)**
+Pass a `space_id` to `trackio.init()` and Trackio will automatically create the Space if it doesn't exist.
+
+**Option B: Create manually**
+- Create Space via Hub UI at https://huggingface.co/new-space
+- Select Gradio SDK
+- OR use command: `hf repos create my-trackio-dashboard --type space --space-sdk gradio`
+
+**Step 3: Initialize Trackio with space_id**
+```python
+import trackio
+
+trackio.init(
+    project="my-training",
+    space_id="username/trackio",  # CRITICAL for Jobs! Replace 'username' with your HF username
+    config={
+        "model": "Qwen/Qwen2.5-0.5B",
+        "dataset": "trl-lib/Capybara",
+        "learning_rate": 2e-5,
+    }
+)
+```
+
+**Step 4: Configure TRL to use Trackio**
+```python
+SFTConfig(
+    report_to="trackio",
+    # ... other config
+)
+```
+
+**Step 5: Finish tracking**
+```python
+trainer.train()
+trackio.finish()  # Ensures final metrics are synced
+```
+
+## What Trackio Tracks
+
+Trackio automatically logs:
+- ✅ Training loss
+- ✅ Learning rate
+- ✅ GPU utilization
+- ✅ Memory usage
+- ✅ Training throughput
+- ✅ Custom metrics
+
+## How It Works with Jobs
+
+1. **Training runs** → Metrics logged to local SQLite DB
+2. **Every 5 minutes** → Trackio syncs DB to HF Dataset (Parquet)
+3. **Space dashboard** → Reads from Dataset, displays metrics in real-time
+4. **Job completes** → Final sync ensures all metrics persisted
+
+## Default Configuration Pattern
+
+**Use sensible defaults for trackio configuration unless user requests otherwise.**
+
+### Recommended Defaults
+
+```python
+import trackio
+
+trackio.init(
+    project="qwen-capybara-sft",
+    name="baseline-run",             # Descriptive name user will recognize
+    space_id="username/trackio",     # Default space: {username}/trackio
+    config={
+        # Keep config minimal - hyperparameters and model/dataset info only
+        "model": "Qwen/Qwen2.5-0.5B",
+        "dataset": "trl-lib/Capybara",
+        "learning_rate": 2e-5,
+        "num_epochs": 3,
+    }
+)
+```
+
+**Key principles:**
+- **Space ID**: Use `{username}/trackio` with "trackio" as default space name
+- **Run naming**: Unless otherwise specified, name the run in a way the user will recognize
+- **Config**: Keep minimal - don't automatically capture job metadata unless requested
+- **Grouping**: Optional - only use if user requests organizing related experiments
+
+## Grouping Runs (Optional)
+
+The `group` parameter helps organize related runs together in the dashboard sidebar. This is useful when user is running multiple experiments with different configurations but wants to compare them together:
+
+```python
+# Example: Group runs by experiment type
+trackio.init(project="my-project", run_name="baseline-run-1", group="baseline")
+trackio.init(project="my-project", run_name="augmented-run-1", group="augmented")
+trackio.init(project="my-project", run_name="tuned-run-1", group="tuned")
+```
+
+Runs with the same group name can be grouped together in the sidebar, making it easier to compare related experiments. You can group by any configuration parameter:
+
+```python
+# Hyperparameter sweep - group by learning rate
+trackio.init(project="hyperparam-sweep", run_name="lr-0.001-run", group="lr_0.001")
+trackio.init(project="hyperparam-sweep", run_name="lr-0.01-run", group="lr_0.01")
+```
+
+## Environment Variables for Jobs
+
+You can configure trackio using environment variables instead of passing parameters to `trackio.init()`. This is useful for managing configuration across multiple jobs.
+
+
+
+**`HF_TOKEN`**
+Required for creating Spaces and writing to datasets (passed via `secrets`):
+```python
+hf_jobs("uv", {
+    "script": "...",
+    "secrets": {
+        "HF_TOKEN": "$HF_TOKEN"  # Enables Space creation and Hub push
+    }
+})
+```
+
+### Example with Environment Variables
+
+```python
+hf_jobs("uv", {
+    "script": """
+# Training script - trackio config from environment
+import trackio
+from datetime import datetime
+
+# Auto-generate run name
+timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M")
+run_name = f"sft_qwen25_{timestamp}"
+
+# Project and space_id can come from environment variables
+trackio.init(run_name=run_name, group="SFT")
+
+# ... training code ...
+trackio.finish()
+""",
+    "flavor": "a10g-large",
+    "timeout": "2h",
+    "secrets": {"HF_TOKEN": "$HF_TOKEN"}
+})
+```
+
+**When to use environment variables:**
+- Managing multiple jobs with same configuration
+- Keeping training scripts portable across projects
+- Separating configuration from code
+
+**When to use direct parameters:**
+- Single job with specific configuration
+- When clarity in code is preferred
+- When each job has different project/space
+
+## Viewing the Dashboard
+
+After starting training:
+1. Navigate to the Space: `https://huggingface.co/spaces/username/trackio`
+2. The Gradio dashboard shows all tracked experiments
+3. Filter by project, compare runs, view charts with smoothing
+
+## Recommendation
+
+- **Trackio**: Best for real-time monitoring during long training runs
+- **Weights & Biases**: Best for team collaboration, requires account

.agents/skills/huggingface-llm-trainer/references/training_methods.md

@@ -0,0 +1,150 @@
+# TRL Training Methods Overview
+
+TRL (Transformer Reinforcement Learning) provides multiple training methods for fine-tuning and aligning language models. This reference provides a brief overview of each method.
+
+## Supervised Fine-Tuning (SFT)
+
+**What it is:** Standard instruction tuning with supervised learning on demonstration data.
+
+**When to use:**
+- Initial fine-tuning of base models on task-specific data
+- Teaching new capabilities or domains
+- Most common starting point for fine-tuning
+
+**Dataset format:** Conversational format with "messages" field, OR text field, OR prompt/completion pairs
+
+**Example:**
+```python
+from trl import SFTTrainer, SFTConfig
+
+trainer = SFTTrainer(
+    model="Qwen/Qwen2.5-0.5B",
+    train_dataset=dataset,
+    args=SFTConfig(
+        output_dir="my-model",
+        push_to_hub=True,
+        hub_model_id="username/my-model",
+        eval_strategy="no",  # Disable eval for simple example
+        # max_length=1024 is the default - only set if you need different length
+    )
+)
+trainer.train()
+```
+
+**Note:** For production training with evaluation monitoring, see `scripts/train_sft_example.py`
+
+**Documentation:** `hf_doc_fetch("https://huggingface.co/docs/trl/sft_trainer")`
+
+## Direct Preference Optimization (DPO)
+
+**What it is:** Alignment method that trains directly on preference pairs (chosen vs rejected responses) without requiring a reward model.
+
+**When to use:**
+- Aligning models to human preferences
+- Improving response quality after SFT
+- Have paired preference data (chosen/rejected responses)
+
+**Dataset format:** Preference pairs with "chosen" and "rejected" fields
+
+**Example:**
+```python
+from trl import DPOTrainer, DPOConfig
+
+trainer = DPOTrainer(
+    model="Qwen/Qwen2.5-0.5B-Instruct",  # Use instruct model
+    train_dataset=dataset,
+    args=DPOConfig(
+        output_dir="dpo-model",
+        beta=0.1,  # KL penalty coefficient
+        eval_strategy="no",  # Disable eval for simple example
+        # max_length=1024 is the default - only set if you need different length
+    )
+)
+trainer.train()
+```
+
+**Note:** For production training with evaluation monitoring, see `scripts/train_dpo_example.py`
+
+**Documentation:** `hf_doc_fetch("https://huggingface.co/docs/trl/dpo_trainer")`
+
+## Group Relative Policy Optimization (GRPO)
+
+**What it is:** Online RL method that optimizes relative to group performance, useful for tasks with verifiable rewards.
+
+**When to use:**
+- Tasks with automatic reward signals (code execution, math verification)
+- Online learning scenarios
+- When DPO offline data is insufficient
+
+**Dataset format:** Prompt-only format (model generates responses, reward computed online)
+
+**Example:**
+```python
+# Use TRL maintained script
+hf_jobs("uv", {
+    "script": "https://raw.githubusercontent.com/huggingface/trl/main/examples/scripts/grpo.py",
+    "script_args": [
+        "--model_name_or_path", "Qwen/Qwen2.5-0.5B-Instruct",
+        "--dataset_name", "trl-lib/math_shepherd",
+        "--output_dir", "grpo-model"
+    ],
+    "flavor": "a10g-large",
+    "timeout": "4h",
+    "secrets": {"HF_TOKEN": "$HF_TOKEN"}
+})
+```
+
+**Documentation:** `hf_doc_fetch("https://huggingface.co/docs/trl/grpo_trainer")`
+
+## Reward Modeling
+
+**What it is:** Train a reward model to score responses, used as a component in RLHF pipelines.
+
+**When to use:**
+- Building RLHF pipeline
+- Need automatic quality scoring
+- Creating reward signals for PPO training
+
+**Dataset format:** Preference pairs with "chosen" and "rejected" responses
+
+**Documentation:** `hf_doc_fetch("https://huggingface.co/docs/trl/reward_trainer")`
+
+## Method Selection Guide
+
+| Method | Complexity | Data Required | Use Case |
+|--------|-----------|---------------|----------|
+| **SFT** | Low | Demonstrations | Initial fine-tuning |
+| **DPO** | Medium | Paired preferences | Post-SFT alignment |
+| **GRPO** | Medium | Prompts + reward fn | Online RL with automatic rewards |
+| **Reward** | Medium | Paired preferences | Building RLHF pipeline |
+
+## Recommended Pipeline
+
+**For most use cases:**
+1. **Start with SFT** - Fine-tune base model on task data
+2. **Follow with DPO** - Align to preferences using paired data
+3. **Optional: GGUF conversion** - Deploy for local inference
+
+**For advanced RL scenarios:**
+1. **Start with SFT** - Fine-tune base model
+2. **Train reward model** - On preference data
+
+## Dataset Format Reference
+
+For complete dataset format specifications, use:
+```python
+hf_doc_fetch("https://huggingface.co/docs/trl/dataset_formats")
+```
+
+Or validate your dataset:
+```bash
+uv run https://huggingface.co/datasets/mcp-tools/skills/raw/main/dataset_inspector.py \
+  --dataset your/dataset --split train
+```
+
+## See Also
+
+- `references/training_patterns.md` - Common training patterns and examples
+- `scripts/train_sft_example.py` - Complete SFT template
+- `scripts/train_dpo_example.py` - Complete DPO template
+- [Dataset Inspector](https://huggingface.co/datasets/mcp-tools/skills/raw/main/dataset_inspector.py) - Dataset format validation tool

.agents/skills/huggingface-llm-trainer/references/training_patterns.md

@@ -0,0 +1,203 @@
+# Common Training Patterns
+
+This guide provides common training patterns and use cases for TRL on Hugging Face Jobs.
+
+## Multi-GPU Training
+
+Automatic distributed training across multiple GPUs. TRL/Accelerate handles distribution automatically:
+
+```python
+hf_jobs("uv", {
+    "script": """
+# Your training script here (same as single GPU)
+# No changes needed - Accelerate detects multiple GPUs
+""",
+    "flavor": "a10g-largex2",  # 2x A10G GPUs
+    "timeout": "4h",
+    "secrets": {"HF_TOKEN": "$HF_TOKEN"}
+})
+```
+
+**Tips for multi-GPU:**
+- No code changes needed
+- Use `per_device_train_batch_size` (per GPU, not total)
+- Effective batch size = `per_device_train_batch_size` × `num_gpus` × `gradient_accumulation_steps`
+- Monitor GPU utilization to ensure both GPUs are being used
+
+## DPO Training (Preference Learning)
+
+Train with preference data for alignment:
+
+```python
+hf_jobs("uv", {
+    "script": """
+# /// script
+# dependencies = ["trl>=0.12.0", "trackio"]
+# ///
+
+from datasets import load_dataset
+from trl import DPOTrainer, DPOConfig
+import trackio
+
+dataset = load_dataset("trl-lib/ultrafeedback_binarized", split="train")
+
+# Create train/eval split
+dataset_split = dataset.train_test_split(test_size=0.1, seed=42)
+
+config = DPOConfig(
+    output_dir="dpo-model",
+    push_to_hub=True,
+    hub_model_id="username/dpo-model",
+    num_train_epochs=1,
+    beta=0.1,  # KL penalty coefficient
+    eval_strategy="steps",
+    eval_steps=50,
+    report_to="trackio",
+    run_name="baseline_run", # use a meaningful run name
+    # max_length=1024,  # Default - only set if you need different sequence length
+)
+
+trainer = DPOTrainer(
+    model="Qwen/Qwen2.5-0.5B-Instruct",  # Use instruct model as base
+    train_dataset=dataset_split["train"],
+    eval_dataset=dataset_split["test"],  # IMPORTANT: Provide eval_dataset when eval_strategy is enabled
+    args=config,
+)
+
+trainer.train()
+trainer.push_to_hub()
+trackio.finish()
+""",
+    "flavor": "a10g-large",
+    "timeout": "3h",
+    "secrets": {"HF_TOKEN": "$HF_TOKEN"}
+})
+```
+
+**For DPO documentation:** Use `hf_doc_fetch("https://huggingface.co/docs/trl/dpo_trainer")`
+
+## GRPO Training (Online RL)
+
+Group Relative Policy Optimization for online reinforcement learning:
+
+```python
+hf_jobs("uv", {
+    "script": "https://raw.githubusercontent.com/huggingface/trl/main/examples/scripts/grpo.py",
+    "script_args": [
+        "--model_name_or_path", "Qwen/Qwen2.5-0.5B-Instruct",
+        "--dataset_name", "trl-lib/math_shepherd",
+        "--output_dir", "grpo-model",
+        "--push_to_hub",
+        "--hub_model_id", "username/grpo-model"
+    ],
+    "flavor": "a10g-large",
+    "timeout": "4h",
+    "secrets": {"HF_TOKEN": "$HF_TOKEN"}
+})
+```
+
+**For GRPO documentation:** Use `hf_doc_fetch("https://huggingface.co/docs/trl/grpo_trainer")`
+
+## Trackio Configuration
+
+**Use sensible defaults for trackio setup.** See `references/trackio_guide.md` for complete documentation including grouping runs for experiments.
+
+### Basic Pattern
+
+```python
+import trackio
+
+trackio.init(
+    project="my-training",
+    run_name="baseline-run",             # Descriptive name user will recognize
+    space_id="username/trackio",     # Default space: {username}/trackio
+    config={
+        # Keep config minimal - hyperparameters and model/dataset info only
+        "model": "Qwen/Qwen2.5-0.5B",
+        "dataset": "trl-lib/Capybara",
+        "learning_rate": 2e-5,
+    }
+)
+
+# Your training code...
+
+trackio.finish()
+```
+
+### Grouping for Experiments (Optional)
+
+When user wants to compare related runs, use the `group` parameter:
+
+```python
+# Hyperparameter sweep
+trackio.init(project="hyperparam-sweep", run_name="lr-0.001", group="lr_0.001")
+trackio.init(project="hyperparam-sweep", run_name="lr-0.01", group="lr_0.01")
+```
+
+## Pattern Selection Guide
+
+| Use Case | Pattern | Hardware | Time |
+|----------|---------|----------|------|
+| SFT training | `scripts/train_sft_example.py` | a10g-large | 2-6 hours |
+| Large dataset (>10K) | Multi-GPU | a10g-largex2 | 4-12 hours |
+| Preference learning | DPO Training | a10g-large | 2-4 hours |
+| Online RL | GRPO Training | a10g-large | 3-6 hours |
+
+## Critical: Evaluation Dataset Requirements
+
+**⚠️ IMPORTANT**: If you set `eval_strategy="steps"` or `eval_strategy="epoch"`, you **MUST** provide an `eval_dataset` to the trainer, or the training will hang.
+
+### ✅ CORRECT - With eval dataset:
+```python
+dataset_split = dataset.train_test_split(test_size=0.1, seed=42)
+
+trainer = SFTTrainer(
+    model="Qwen/Qwen2.5-0.5B",
+    train_dataset=dataset_split["train"],
+    eval_dataset=dataset_split["test"],  # ← MUST provide when eval_strategy is enabled
+    args=SFTConfig(eval_strategy="steps", ...),
+)
+```
+
+### ❌ WRONG - Will hang:
+```python
+trainer = SFTTrainer(
+    model="Qwen/Qwen2.5-0.5B",
+    train_dataset=dataset,
+    # NO eval_dataset but eval_strategy="steps" ← WILL HANG
+    args=SFTConfig(eval_strategy="steps", ...),
+)
+```
+
+### Option: Disable evaluation if no eval dataset
+```python
+config = SFTConfig(
+    eval_strategy="no",  # ← Explicitly disable evaluation
+    # ... other config
+)
+
+trainer = SFTTrainer(
+    model="Qwen/Qwen2.5-0.5B",
+    train_dataset=dataset,
+    # No eval_dataset needed
+    args=config,
+)
+```
+
+## Best Practices
+
+1. **Use train/eval splits** - Create evaluation split for monitoring progress
+2. **Enable Trackio** - Monitor progress in real-time
+3. **Add 20-30% buffer to timeout** - Account for loading/saving overhead
+4. **Test with TRL official scripts first** - Use maintained examples before custom code
+5. **Always provide eval_dataset** - When using eval_strategy, or set to "no"
+6. **Use multi-GPU for large models** - 7B+ models benefit significantly
+
+## See Also
+
+- `scripts/train_sft_example.py` - Complete SFT template with Trackio and eval split
+- `scripts/train_dpo_example.py` - Complete DPO template
+- `scripts/train_grpo_example.py` - Complete GRPO template
+- `references/hardware_guide.md` - Detailed hardware specifications
+- `references/training_methods.md` - Overview of all TRL training methods
+- `references/troubleshooting.md` - Common issues and solutions

.agents/skills/huggingface-llm-trainer/references/troubleshooting.md

@@ -0,0 +1,282 @@
+# Troubleshooting TRL Training Jobs
+
+Common issues and solutions when training with TRL on Hugging Face Jobs.
+
+## Training Hangs at "Starting training..." Step
+
+**Problem:** Job starts but hangs at the training step - never progresses, never times out, just sits there.
+
+**Root Cause:** Using `eval_strategy="steps"` or `eval_strategy="epoch"` without providing an `eval_dataset` to the trainer.
+
+**Solution:**
+
+**Option A: Provide eval_dataset (recommended)**
+```python
+# Create train/eval split
+dataset_split = dataset.train_test_split(test_size=0.1, seed=42)
+
+trainer = SFTTrainer(
+    model="Qwen/Qwen2.5-0.5B",
+    train_dataset=dataset_split["train"],
+    eval_dataset=dataset_split["test"],  # ← MUST provide when eval_strategy is enabled
+    args=SFTConfig(
+        eval_strategy="steps",
+        eval_steps=50,
+        ...
+    ),
+)
+```
+
+**Option B: Disable evaluation**
+```python
+trainer = SFTTrainer(
+    model="Qwen/Qwen2.5-0.5B",
+    train_dataset=dataset,
+    # No eval_dataset
+    args=SFTConfig(
+        eval_strategy="no",  # ← Explicitly disable
+        ...
+    ),
+)
+```
+
+**Prevention:**
+- Always create train/eval split for better monitoring
+- Use `dataset.train_test_split(test_size=0.1, seed=42)`
+- Check example scripts: `scripts/train_sft_example.py` includes proper eval setup
+
+## Job Times Out
+
+**Problem:** Job terminates before training completes, all progress lost.
+
+**Solutions:**
+- Increase timeout parameter (e.g., `"timeout": "4h"`)
+- Reduce `num_train_epochs` or use smaller dataset slice
+- Use smaller model or enable LoRA/PEFT to speed up training
+- Add 20-30% buffer to estimated time for loading/saving overhead
+
+**Prevention:**
+- Always start with a quick demo run to estimate timing
+- Use `scripts/estimate_cost.py` to get time estimates
+- Monitor first runs closely via Trackio or logs
+
+## Model Not Saved to Hub
+
+**Problem:** Training completes but model doesn't appear on Hub - all work lost.
+
+**Check:**
+- [ ] `push_to_hub=True` in training config
+- [ ] `hub_model_id` specified with username (e.g., `"username/model-name"`)
+- [ ] `secrets={"HF_TOKEN": "$HF_TOKEN"}` in job submission
+- [ ] User has write access to target repo
+- [ ] Token has write permissions (check at https://huggingface.co/settings/tokens)
+- [ ] Training script calls `trainer.push_to_hub()` at the end
+
+**See:** `references/hub_saving.md` for detailed Hub authentication troubleshooting
+
+## Out of Memory (OOM)
+
+**Problem:** Job fails with CUDA out of memory error.
+
+**Solutions (in order of preference):**
+1. **Reduce batch size:** Lower `per_device_train_batch_size` (try 4 → 2 → 1)
+2. **Increase gradient accumulation:** Raise `gradient_accumulation_steps` to maintain effective batch size
+3. **Disable evaluation:** Remove `eval_dataset` and `eval_strategy` (saves ~40% memory, good for demos)
+4. **Enable LoRA/PEFT:** Use `peft_config=LoraConfig(r=8, lora_alpha=16)` to train adapters only (smaller rank = less memory)
+5. **Use larger GPU:** Switch from `t4-small` → `l4x1` → `a10g-large` → `a100-large`
+6. **Enable gradient checkpointing:** Set `gradient_checkpointing=True` in config (slower but saves memory)
+7. **Use smaller model:** Try a smaller variant (e.g., 0.5B instead of 3B)
+
+**Memory guidelines:**
+- T4 (16GB): <1B models with LoRA
+- A10G (24GB): 1-3B models with LoRA, <1B full fine-tune
+- A100 (40GB/80GB): 7B+ models with LoRA, 3B full fine-tune
+
+## Parameter Naming Issues
+
+**Problem:** `TypeError: SFTConfig.__init__() got an unexpected keyword argument 'max_seq_length'`
+
+**Cause:** TRL config classes use `max_length`, not `max_seq_length`.
+
+**Solution:**
+```python
+# ✅ CORRECT - TRL uses max_length
+SFTConfig(max_length=512)
+DPOConfig(max_length=512)
+
+# ❌ WRONG - This will fail
+SFTConfig(max_seq_length=512)
+```
+
+**Note:** Most TRL configs don't require explicit max_length - the default (1024) works well. Only set if you need a specific value.
+
+## Dataset Format Error
+
+**Problem:** Training fails with dataset format errors or missing fields.
+
+**Solutions:**
+1. **Check format documentation:**
+   ```python
+   hf_doc_fetch("https://huggingface.co/docs/trl/dataset_formats")
+   ```
+
+2. **Validate dataset before training:**
+   ```bash
+   uv run https://huggingface.co/datasets/mcp-tools/skills/raw/main/dataset_inspector.py \
+     --dataset <dataset-name> --split train
+   ```
+   Or via hf_jobs:
+   ```python
+   hf_jobs("uv", {
+       "script": "https://huggingface.co/datasets/mcp-tools/skills/raw/main/dataset_inspector.py",
+       "script_args": ["--dataset", "dataset-name", "--split", "train"]
+   })
+   ```
+
+3. **Verify field names:**
+   - **SFT:** Needs "messages" field (conversational), OR "text" field, OR "prompt"/"completion"
+   - **DPO:** Needs "chosen" and "rejected" fields
+   - **GRPO:** Needs prompt-only format
+
+4. **Check dataset split:**
+   - Ensure split exists (e.g., `split="train"`)
+   - Preview dataset: `load_dataset("name", split="train[:5]")`
+
+## Import/Module Errors
+
+**Problem:** Job fails with "ModuleNotFoundError" or import errors.
+
+**Solutions:**
+1. **Add PEP 723 header with dependencies:**
+   ```python
+   # /// script
+   # dependencies = [
+   #     "trl>=0.12.0",
+   #     "peft>=0.7.0",
+   #     "transformers>=4.36.0",
+   # ]
+   # ///
+   ```
+
+2. **Verify exact format:**
+   - Must have `# ///` delimiters (with space after `#`)
+   - Dependencies must be valid PyPI package names
+   - Check spelling and version constraints
+
+3. **Test locally first:**
+   ```bash
+   uv run train.py  # Tests if dependencies are correct
+   ```
+
+## Authentication Errors
+
+**Problem:** Job fails with authentication or permission errors when pushing to Hub.
+
+**Solutions:**
+1. **Verify authentication:**
+   ```python
+   mcp__huggingface__hf_whoami()  # Check who's authenticated
+   ```
+
+2. **Check token permissions:**
+   - Go to https://huggingface.co/settings/tokens
+   - Ensure token has "write" permission
+   - Token must not be "read-only"
+
+3. **Verify token in job:**
+   ```python
+   "secrets": {"HF_TOKEN": "$HF_TOKEN"}  # Must be in job config
+   ```
+
+4. **Check repo permissions:**
+   - User must have write access to target repo
+   - If org repo, user must be member with write access
+   - Repo must exist or user must have permission to create
+
+## Job Stuck or Not Starting
+
+**Problem:** Job shows "pending" or "starting" for extended period.
+
+**Solutions:**
+- Check Jobs dashboard for status: https://huggingface.co/jobs
+- Verify hardware availability (some GPU types may have queues)
+- Try different hardware flavor if one is heavily utilized
+- Check for account billing issues (Jobs requires paid plan)
+
+**Typical startup times:**
+- CPU jobs: 10-30 seconds
+- GPU jobs: 30-90 seconds
+- If >3 minutes: likely queued or stuck
+
+## Training Loss Not Decreasing
+
+**Problem:** Training runs but loss stays flat or doesn't improve.
+
+**Solutions:**
+1. **Check learning rate:** May be too low (try 2e-5 to 5e-5) or too high (try 1e-6)
+2. **Verify dataset quality:** Inspect examples to ensure they're reasonable
+3. **Check model size:** Very small models may not have capacity for task
+4. **Increase training steps:** May need more epochs or larger dataset
+5. **Verify dataset format:** Wrong format may cause degraded training
+
+## Logs Not Appearing
+
+**Problem:** Cannot see training logs or progress.
+
+**Solutions:**
+1. **Wait 30-60 seconds:** Initial logs can be delayed
+2. **Check logs via MCP tool:**
+   ```python
+   hf_jobs("logs", {"job_id": "your-job-id"})
+   ```
+3. **Use Trackio for real-time monitoring:** See `references/trackio_guide.md`
+4. **Verify job is actually running:**
+   ```python
+   hf_jobs("inspect", {"job_id": "your-job-id"})
+   ```
+
+## Checkpoint/Resume Issues
+
+**Problem:** Cannot resume from checkpoint or checkpoint not saved.
+
+**Solutions:**
+1. **Enable checkpoint saving:**
+   ```python
+   SFTConfig(
+       save_strategy="steps",
+       save_steps=100,
+       hub_strategy="every_save",  # Push each checkpoint
+   )
+   ```
+
+2. **Verify checkpoints pushed to Hub:** Check model repo for checkpoint folders
+
+3. **Resume from checkpoint:**
+   ```python
+   trainer = SFTTrainer(
+       model="username/model-name",  # Can be checkpoint path
+       resume_from_checkpoint="username/model-name/checkpoint-1000",
+   )
+   ```
+
+## Getting Help
+
+If issues persist:
+
+1. **Check TRL documentation:**
+   ```python
+   hf_doc_search("your issue", product="trl")
+   ```
+
+2. **Check Jobs documentation:**
+   ```python
+   hf_doc_fetch("https://huggingface.co/docs/huggingface_hub/guides/jobs")
+   ```
+
+3. **Review related guides:**
+   - `references/hub_saving.md` - Hub authentication issues
+   - `references/hardware_guide.md` - Hardware selection and specs
+   - `references/training_patterns.md` - Eval dataset requirements
+   - SKILL.md "Working with Scripts" section - Script format and URL issues
+
+4. **Ask in HF forums:** https://discuss.huggingface.co/

.agents/skills/huggingface-llm-trainer/references/unsloth.md

@@ -0,0 +1,313 @@
+# Unsloth: Fast Fine-Tuning with Memory Optimization
+
+**Unsloth** is a fine-tuning library that provides ~2x faster training and ~60% less VRAM usage for LLM training. It's particularly useful when working with limited GPU memory or when speed is critical.
+
+- **GitHub**: [unslothai/unsloth](https://github.com/unslothai/unsloth)
+- **Docs**: [unsloth.ai/docs](https://unsloth.ai/docs)
+
+## When to Use Unsloth
+
+Use Unsloth if instructed to do so, or one of the following use cases applies:
+
+| Use Case | Recommendation |
+|----------|----------------|
+| Standard text LLM fine-tuning | TRL is sufficient, but Unsloth is faster |
+| Limited GPU memory | **Use Unsloth** - 60% less VRAM |
+| Need maximum speed | **Use Unsloth** - 2x faster |
+| Large models (>13B) | **Use Unsloth** - memory efficiency critical |
+
+## Supported Models
+
+Unsloth supports many popular models including:
+- **Text LLMs**: Llama 3/3.1/3.2/3.3, Qwen 2.5/3, Mistral, Phi-4, Gemma 2/3, LFM2/2.5
+- **Vision LLMs**: Qwen3-VL, Gemma 3, Llama 3.2 Vision, Pixtral
+
+Use Unsloth's pre-optimized model variants when available:
+```python
+# Unsloth-optimized models load faster and use less memory
+model_id = "unsloth/LFM2.5-1.2B-Instruct"      # 4-bit quantized
+model_id = "unsloth/gemma-3-4b-pt"            # Vision model
+model_id = "unsloth/Qwen3-VL-8B-Instruct"     # Vision model
+```
+
+## Installation
+
+```python
+# /// script
+# dependencies = [
+#     "unsloth",
+#     "trl",
+#     "datasets",
+#     "trackio",
+# ]
+# ///
+```
+
+## Basic Usage: Text LLM
+
+```python
+from unsloth import FastLanguageModel
+from trl import SFTTrainer, SFTConfig
+from datasets import load_dataset
+
+# Load model with Unsloth optimizations
+model, tokenizer = FastLanguageModel.from_pretrained(
+    model_name="LiquidAI/LFM2.5-1.2B-Instruct",
+    max_seq_length=4096,
+)
+
+# Add LoRA adapters
+model = FastLanguageModel.get_peft_model(
+    model,
+    r=16,
+    lora_alpha=16,
+    target_modules=["q_proj", "k_proj", "v_proj", "out_proj", "in_proj", "w1", "w2", "w3"],
+    lora_dropout=0,
+    bias="none",
+    use_gradient_checkpointing="unsloth",
+    random_state=3407,
+)
+
+# Load dataset
+dataset = load_dataset("trl-lib/Capybara", split="train")
+
+# Train with TRL
+trainer = SFTTrainer(
+    model=model,
+    tokenizer=tokenizer,
+    train_dataset=dataset,
+    args=SFTConfig(
+        output_dir="./output",
+        per_device_train_batch_size=2,
+        gradient_accumulation_steps=4,
+        max_steps=500,
+        learning_rate=2e-4,
+        report_to="trackio",
+    ),
+)
+
+trainer.train()
+```
+
+## LFM2.5 Specific Settings
+
+For LFM2.5 inference, use these recommended generation parameters:
+
+**Instruct models:**
+```python
+temperature = 0.1
+top_k = 50
+top_p = 0.1
+repetition_penalty = 1.05
+```
+
+**Thinking models:**
+```python
+temperature = 0.05
+top_k = 50
+repetition_penalty = 1.05
+```
+
+## Vision-Language Models (VLMs)
+
+Unsloth provides specialized support for VLMs with `FastVisionModel`:
+
+```python
+from unsloth import FastVisionModel, get_chat_template
+from unsloth.trainer import UnslothVisionDataCollator
+from trl import SFTTrainer, SFTConfig
+from datasets import load_dataset
+
+# Load VLM with Unsloth
+model, processor = FastVisionModel.from_pretrained(
+    "unsloth/gemma-3-4b-pt",  # or "unsloth/Qwen3-VL-8B-Instruct"
+    load_in_4bit=True,
+    use_gradient_checkpointing="unsloth",
+)
+
+# Add LoRA for all modalities
+model = FastVisionModel.get_peft_model(
+    model,
+    finetune_vision_layers=True,      # Train vision encoder
+    finetune_language_layers=True,    # Train language model
+    finetune_attention_modules=True,  # Train attention
+    finetune_mlp_modules=True,        # Train MLPs
+    r=16,
+    lora_alpha=32,
+    target_modules="all-linear",
+)
+
+# Apply chat template (required for base models)
+processor = get_chat_template(processor, "gemma-3")
+
+# Load VLM dataset (with images and messages)
+dataset = load_dataset("your-vlm-dataset", split="train", streaming=True)
+
+# Enable training mode
+FastVisionModel.for_training(model)
+
+# Train with VLM-specific collator
+trainer = SFTTrainer(
+    model=model,
+    train_dataset=dataset,
+    processing_class=processor.tokenizer,
+    data_collator=UnslothVisionDataCollator(model, processor),
+    args=SFTConfig(
+        output_dir="./vlm-output",
+        per_device_train_batch_size=2,
+        gradient_accumulation_steps=4,
+        max_steps=500,
+        learning_rate=2e-4,
+        # VLM-specific settings
+        remove_unused_columns=False,
+        dataset_text_field="",
+        dataset_kwargs={"skip_prepare_dataset": True},
+        report_to="trackio",
+    ),
+)
+
+trainer.train()
+```
+
+## Key Differences from Standard TRL
+
+| Aspect | Standard TRL | Unsloth |
+|--------|--------------|---------|
+| Model loading | `AutoModelForCausalLM.from_pretrained()` | `FastLanguageModel.from_pretrained()` |
+| LoRA setup | `PeftModel` / `LoraConfig` | `FastLanguageModel.get_peft_model()` |
+| VLM loading | Limited support | `FastVisionModel.from_pretrained()` |
+| VLM collator | Manual | `UnslothVisionDataCollator` |
+| Memory usage | Standard | ~60% less |
+| Training speed | Standard | ~2x faster |
+
+## VLM Dataset Format
+
+VLM datasets should have:
+- `images`: List of PIL images or image paths
+- `messages`: Conversation format with image references
+
+```python
+{
+    "images": [<PIL.Image>, ...],
+    "messages": [
+        {"role": "user", "content": [
+            {"type": "image"},
+            {"type": "text", "text": "Describe this image"}
+        ]},
+        {"role": "assistant", "content": "This image shows..."}
+    ]
+}
+```
+
+## Streaming Datasets
+
+For large VLM datasets, use streaming to avoid disk space issues:
+
+```python
+dataset = load_dataset(
+    "your-vlm-dataset",
+    split="train",
+    streaming=True,  # Stream from Hub
+)
+
+# Must use max_steps with streaming (no epoch-based training)
+SFTConfig(max_steps=500, ...)
+```
+
+## Saving Models
+
+### Save LoRA Adapter
+
+```python
+model.save_pretrained("./adapter")
+processor.save_pretrained("./adapter")
+
+# Push to Hub
+model.push_to_hub("username/my-vlm-adapter")
+processor.push_to_hub("username/my-vlm-adapter")
+```
+
+### Merge and Save Full Model
+
+```python
+# Merge LoRA weights into base model
+model = model.merge_and_unload()
+
+# Save merged model
+model.save_pretrained("./merged")
+tokenizer.save_pretrained("./merged")
+```
+
+### Convert to GGUF
+
+Unsloth models can be converted to GGUF for llama.cpp/Ollama:
+
+```python
+# Save in 16-bit for GGUF conversion
+model.save_pretrained_gguf("./gguf", tokenizer, quantization_method="f16")
+
+# Or directly quantize
+model.save_pretrained_gguf("./gguf", tokenizer, quantization_method="q4_k_m")
+```
+
+## Qwen3-VL Specific Settings
+
+For Qwen3-VL models, use these recommended settings:
+
+**Instruct models:**
+```python
+temperature = 0.7
+top_p = 0.8
+presence_penalty = 1.5
+```
+
+**Thinking models:**
+```python
+temperature = 1.0
+top_p = 0.95
+presence_penalty = 0.0
+```
+
+## Hardware Requirements
+
+| Model | Min VRAM (Unsloth 4-bit) | Recommended GPU |
+|-------|--------------------------|-----------------|
+| 2B-4B | 8GB | T4, L4 |
+| 7B-8B | 16GB | A10G, L4x4 |
+| 13B | 24GB | A10G-large |
+| 30B+ | 48GB+ | A100 |
+
+## Example: Full VLM Training Script
+
+See `scripts/unsloth_sft_example.py` for a complete production-ready example that includes:
+- Unsloth VLM setup
+- Streaming dataset support
+- Trackio monitoring
+- Hub push
+- CLI arguments
+
+Run locally:
+```bash
+uv run scripts/unsloth_sft_example.py \
+    --dataset trl-lib/Capybara \
+    --max-steps 500 \
+    --output-repo username/my-model
+```
+
+Run on HF Jobs:
+```python
+hf_jobs("uv", {
+    "script": "<script content>",
+    "flavor": "a10g-large",
+    "timeout": "2h",
+    "secrets": {"HF_TOKEN": "$HF_TOKEN"}
+})
+```
+
+## See Also
+
+- `scripts/unsloth_sft_example.py` - Complete text LLM training example
+- [Unsloth Documentation](https://unsloth.ai/docs)
+- [LFM2.5 Guide](https://unsloth.ai/docs/models/tutorials/lfm2.5)
+- [Qwen3-VL Guide](https://unsloth.ai/docs/models/qwen3-vl-how-to-run-and-fine-tune)
+- [Unsloth GitHub](https://github.com/unslothai/unsloth)

.agents/skills/huggingface-llm-trainer/scripts/convert_to_gguf.py

@@ -0,0 +1,424 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "transformers>=4.36.0",
+#     "peft>=0.7.0",
+#     "torch>=2.0.0",
+#     "accelerate>=0.24.0",
+#     "huggingface_hub>=0.20.0",
+#     "sentencepiece>=0.1.99",
+#     "protobuf>=3.20.0",
+#     "numpy",
+#     "gguf",
+# ]
+# ///
+
+"""
+GGUF Conversion Script - Production Ready
+
+This script converts a LoRA fine-tuned model to GGUF format for use with:
+- llama.cpp
+- Ollama
+- LM Studio
+- Other GGUF-compatible tools
+
+PREREQUISITES (install these FIRST):
+- Ubuntu/Debian: sudo apt-get update && sudo apt-get install -y build-essential cmake
+- RHEL/CentOS: sudo yum groupinstall -y "Development Tools" && sudo yum install -y cmake
+- macOS: xcode-select --install && brew install cmake
+
+Usage:
+    Set environment variables:
+    - ADAPTER_MODEL: Your fine-tuned model (e.g., "username/my-finetuned-model")
+    - BASE_MODEL: Base model used for fine-tuning (e.g., "Qwen/Qwen2.5-0.5B")
+    - OUTPUT_REPO: Where to upload GGUF files (e.g., "username/my-model-gguf")
+    - HF_USERNAME: Your Hugging Face username (optional, for README)
+
+Dependencies: All required packages are declared in PEP 723 header above.
+"""
+
+import os
+import sys
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel
+from huggingface_hub import HfApi
+import subprocess
+
+
+def check_system_dependencies():
+    """Check if required system packages are available."""
+    print("🔍 Checking system dependencies...")
+    
+    # Check for git
+    if subprocess.run(["which", "git"], capture_output=True).returncode != 0:
+        print("  ❌ git is not installed. Please install it:")
+        print("     Ubuntu/Debian: sudo apt-get install git")
+        print("     RHEL/CentOS: sudo yum install git")
+        print("     macOS: brew install git")
+        return False
+    
+    # Check for make or cmake
+    has_make = subprocess.run(["which", "make"], capture_output=True).returncode == 0
+    has_cmake = subprocess.run(["which", "cmake"], capture_output=True).returncode == 0
+    
+    if not has_make and not has_cmake:
+        print("  ❌ Neither make nor cmake found. Please install build tools:")
+        print("     Ubuntu/Debian: sudo apt-get install build-essential cmake")
+        print("     RHEL/CentOS: sudo yum groupinstall 'Development Tools' && sudo yum install cmake")
+        print("     macOS: xcode-select --install && brew install cmake")
+        return False
+    
+    print("  ✅ System dependencies found")
+    return True
+
+
+def run_command(cmd, description):
+    """Run a command with error handling."""
+    print(f"   {description}...")
+    try:
+        result = subprocess.run(
+            cmd,
+            check=True,
+            capture_output=True,
+            text=True
+        )
+        if result.stdout:
+            print(f"   {result.stdout[:200]}")  # Show first 200 chars
+        return True
+    except subprocess.CalledProcessError as e:
+        print(f"   ❌ Command failed: {' '.join(cmd)}")
+        if e.stdout:
+            print(f"   STDOUT: {e.stdout[:500]}")
+        if e.stderr:
+            print(f"   STDERR: {e.stderr[:500]}")
+        return False
+    except FileNotFoundError:
+        print(f"   ❌ Command not found: {cmd[0]}")
+        return False
+
+
+print("🔄 GGUF Conversion Script")
+print("=" * 60)
+
+# Check system dependencies first
+if not check_system_dependencies():
+    print("\n❌ Please install the missing system dependencies and try again.")
+    sys.exit(1)
+
+# Configuration from environment variables
+ADAPTER_MODEL = os.environ.get("ADAPTER_MODEL", "evalstate/qwen-capybara-medium")
+BASE_MODEL = os.environ.get("BASE_MODEL", "Qwen/Qwen2.5-0.5B")
+OUTPUT_REPO = os.environ.get("OUTPUT_REPO", "evalstate/qwen-capybara-medium-gguf")
+username = os.environ.get("HF_USERNAME", ADAPTER_MODEL.split('/')[0])
+
+print(f"\n📦 Configuration:")
+print(f"   Base model: {BASE_MODEL}")
+print(f"   Adapter model: {ADAPTER_MODEL}")
+print(f"   Output repo: {OUTPUT_REPO}")
+
+# Step 1: Load base model and adapter
+print("\n🔧 Step 1: Loading base model and LoRA adapter...")
+print("   (This may take a few minutes)")
+
+try:
+    base_model = AutoModelForCausalLM.from_pretrained(
+        BASE_MODEL,
+        dtype=torch.float16,
+        device_map="auto",
+        trust_remote_code=True,
+    )
+    print("   ✅ Base model loaded")
+except Exception as e:
+    print(f"   ❌ Failed to load base model: {e}")
+    sys.exit(1)
+
+try:
+    # Load and merge adapter
+    print("   Loading LoRA adapter...")
+    model = PeftModel.from_pretrained(base_model, ADAPTER_MODEL)
+    print("   ✅ Adapter loaded")
+
+    print("   Merging adapter with base model...")
+    merged_model = model.merge_and_unload()
+    print("   ✅ Models merged!")
+except Exception as e:
+    print(f"   ❌ Failed to merge models: {e}")
+    sys.exit(1)
+
+try:
+    # Load tokenizer
+    tokenizer = AutoTokenizer.from_pretrained(ADAPTER_MODEL, trust_remote_code=True)
+    print("   ✅ Tokenizer loaded")
+except Exception as e:
+    print(f"   ❌ Failed to load tokenizer: {e}")
+    sys.exit(1)
+
+# Step 2: Save merged model temporarily
+print("\n💾 Step 2: Saving merged model...")
+merged_dir = "/tmp/merged_model"
+try:
+    merged_model.save_pretrained(merged_dir, safe_serialization=True)
+    tokenizer.save_pretrained(merged_dir)
+    print(f"   ✅ Merged model saved to {merged_dir}")
+except Exception as e:
+    print(f"   ❌ Failed to save merged model: {e}")
+    sys.exit(1)
+
+# Step 3: Install llama.cpp for conversion
+print("\n📥 Step 3: Setting up llama.cpp for GGUF conversion...")
+
+# Clone llama.cpp repository
+if not run_command(
+    ["git", "clone", "https://github.com/ggerganov/llama.cpp.git", "/tmp/llama.cpp"],
+    "Cloning llama.cpp repository"
+):
+    print("   Trying alternative clone method...")
+    # Try shallow clone
+    if not run_command(
+        ["git", "clone", "--depth", "1", "https://github.com/ggerganov/llama.cpp.git", "/tmp/llama.cpp"],
+        "Cloning llama.cpp (shallow)"
+    ):
+        sys.exit(1)
+
+# Install Python dependencies
+print("   Installing Python dependencies...")
+if not run_command(
+    ["pip", "install", "-r", "/tmp/llama.cpp/requirements.txt"],
+    "Installing llama.cpp requirements"
+):
+    print("   ⚠️  Some requirements may already be installed")
+
+if not run_command(
+    ["pip", "install", "sentencepiece", "protobuf"],
+    "Installing tokenizer dependencies"
+):
+    print("   ⚠️  Tokenizer dependencies may already be installed")
+
+# Step 4: Convert to GGUF (FP16)
+print("\n🔄 Step 4: Converting to GGUF format (FP16)...")
+gguf_output_dir = "/tmp/gguf_output"
+os.makedirs(gguf_output_dir, exist_ok=True)
+
+convert_script = "/tmp/llama.cpp/convert_hf_to_gguf.py"
+model_name = ADAPTER_MODEL.split('/')[-1]
+gguf_file = f"{gguf_output_dir}/{model_name}-f16.gguf"
+
+print(f"   Running conversion...")
+if not run_command(
+    [
+        sys.executable, convert_script,
+        merged_dir,
+        "--outfile", gguf_file,
+        "--outtype", "f16"
+    ],
+    f"Converting to FP16"
+):
+    print("   ❌ Conversion failed!")
+    sys.exit(1)
+
+print(f"   ✅ FP16 GGUF created: {gguf_file}")
+
+# Step 5: Quantize to different formats
+print("\n⚙️  Step 5: Creating quantized versions...")
+
+# Build quantize tool using CMake (more reliable than make)
+print("   Building quantize tool with CMake...")
+os.makedirs("/tmp/llama.cpp/build", exist_ok=True)
+
+# Configure with CMake
+if not run_command(
+    ["cmake", "-B", "/tmp/llama.cpp/build", "-S", "/tmp/llama.cpp",
+     "-DGGML_CUDA=OFF"],
+    "Configuring with CMake"
+):
+    print("   ❌ CMake configuration failed")
+    sys.exit(1)
+
+# Build just the quantize tool
+if not run_command(
+    ["cmake", "--build", "/tmp/llama.cpp/build", "--target", "llama-quantize", "-j", "4"],
+    "Building llama-quantize"
+):
+    print("   ❌ Build failed!")
+    sys.exit(1)
+
+print("   ✅ Quantize tool built")
+
+# Use the CMake build output path
+quantize_bin = "/tmp/llama.cpp/build/bin/llama-quantize"
+
+# Common quantization formats
+quant_formats = [
+    ("Q4_K_M", "4-bit, medium quality (recommended)"),
+    ("Q5_K_M", "5-bit, higher quality"),
+    ("Q8_0", "8-bit, very high quality"),
+]
+
+quantized_files = []
+for quant_type, description in quant_formats:
+    print(f"   Creating {quant_type} quantization ({description})...")
+    quant_file = f"{gguf_output_dir}/{model_name}-{quant_type.lower()}.gguf"
+
+    if not run_command(
+        [quantize_bin, gguf_file, quant_file, quant_type],
+        f"Quantizing to {quant_type}"
+    ):
+        print(f"   ⚠️  Skipping {quant_type} due to error")
+        continue
+
+    quantized_files.append((quant_file, quant_type))
+    
+    # Get file size
+    size_mb = os.path.getsize(quant_file) / (1024 * 1024)
+    print(f"   ✅ {quant_type}: {size_mb:.1f} MB")
+
+if not quantized_files:
+    print("   ❌ No quantized versions were created successfully")
+    sys.exit(1)
+
+# Step 6: Upload to Hub
+print("\n☁️  Step 6: Uploading to Hugging Face Hub...")
+api = HfApi()
+
+# Create repo
+print(f"   Creating repository: {OUTPUT_REPO}")
+try:
+    api.create_repo(repo_id=OUTPUT_REPO, repo_type="model", exist_ok=True)
+    print("   ✅ Repository ready")
+except Exception as e:
+    print(f"   ℹ️  Repository may already exist: {e}")
+
+# Upload FP16 version
+print("   Uploading FP16 GGUF...")
+try:
+    api.upload_file(
+        path_or_fileobj=gguf_file,
+        path_in_repo=f"{model_name}-f16.gguf",
+        repo_id=OUTPUT_REPO,
+    )
+    print("   ✅ FP16 uploaded")
+except Exception as e:
+    print(f"   ❌ Upload failed: {e}")
+    sys.exit(1)
+
+# Upload quantized versions
+for quant_file, quant_type in quantized_files:
+    print(f"   Uploading {quant_type}...")
+    try:
+        api.upload_file(
+            path_or_fileobj=quant_file,
+            path_in_repo=f"{model_name}-{quant_type.lower()}.gguf",
+            repo_id=OUTPUT_REPO,
+        )
+        print(f"   �� {quant_type} uploaded")
+    except Exception as e:
+        print(f"   ❌ Upload failed for {quant_type}: {e}")
+        continue
+
+# Create README
+print("\n📝 Creating README...")
+readme_content = f"""---
+base_model: {BASE_MODEL}
+tags:
+- gguf
+- llama.cpp
+- quantized
+- trl
+- sft
+---
+
+# {OUTPUT_REPO.split('/')[-1]}
+
+This is a GGUF conversion of [{ADAPTER_MODEL}](https://huggingface.co/{ADAPTER_MODEL}), which is a LoRA fine-tuned version of [{BASE_MODEL}](https://huggingface.co/{BASE_MODEL}).
+
+## Model Details
+
+- **Base Model:** {BASE_MODEL}
+- **Fine-tuned Model:** {ADAPTER_MODEL}
+- **Training:** Supervised Fine-Tuning (SFT) with TRL
+- **Format:** GGUF (for llama.cpp, Ollama, LM Studio, etc.)
+
+## Available Quantizations
+
+| File | Quant | Size | Description | Use Case |
+|------|-------|------|-------------|----------|
+| {model_name}-f16.gguf | F16 | ~1GB | Full precision | Best quality, slower |
+| {model_name}-q8_0.gguf | Q8_0 | ~500MB | 8-bit | High quality |
+| {model_name}-q5_k_m.gguf | Q5_K_M | ~350MB | 5-bit medium | Good quality, smaller |
+| {model_name}-q4_k_m.gguf | Q4_K_M | ~300MB | 4-bit medium | Recommended - good balance |
+
+## Usage
+
+### With llama.cpp
+
+```bash
+# Download model
+hf download {OUTPUT_REPO} {model_name}-q4_k_m.gguf
+
+# Run with llama.cpp
+./llama-cli -m {model_name}-q4_k_m.gguf -p "Your prompt here"
+```
+
+### With Ollama
+
+1. Create a `Modelfile`:
+```
+FROM ./{model_name}-q4_k_m.gguf
+```
+
+2. Create the model:
+```bash
+ollama create my-model -f Modelfile
+ollama run my-model
+```
+
+### With LM Studio
+
+1. Download the `.gguf` file
+2. Import into LM Studio
+3. Start chatting!
+
+## License
+
+Inherits the license from the base model: {BASE_MODEL}
+
+## Citation
+
+```bibtex
+@misc{{{OUTPUT_REPO.split('/')[-1].replace('-', '_')},
+  author = {{{username}}},
+  title = {{{OUTPUT_REPO.split('/')[-1]}}},
+  year = {{2025}},
+  publisher = {{Hugging Face}},
+  url = {{https://huggingface.co/{OUTPUT_REPO}}}
+}}
+```
+
+---
+
+*Converted to GGUF format using llama.cpp*
+"""
+
+try:
+    api.upload_file(
+        path_or_fileobj=readme_content.encode(),
+        path_in_repo="README.md",
+        repo_id=OUTPUT_REPO,
+    )
+    print("   ✅ README uploaded")
+except Exception as e:
+    print(f"   ❌ README upload failed: {e}")
+
+print("\n" + "=" * 60)
+print("✅ GGUF Conversion Complete!")
+print(f"📦 Repository: https://huggingface.co/{OUTPUT_REPO}")
+print(f"\n📥 Download with:")
+print(f"   hf download {OUTPUT_REPO} {model_name}-q4_k_m.gguf")
+print(f"\n🚀 Use with Ollama:")
+print("   1. Download the GGUF file")
+print(f"   2. Create Modelfile: FROM ./{model_name}-q4_k_m.gguf")
+print("   3. ollama create my-model -f Modelfile")
+print("   4. ollama run my-model")
+print("=" * 60)

.agents/skills/huggingface-llm-trainer/scripts/dataset_inspector.py

@@ -0,0 +1,417 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""
+Dataset Format Inspector for TRL Training (LLM-Optimized Output)
+
+Inspects Hugging Face datasets to determine TRL training compatibility.
+Uses Datasets Server API for instant results - no dataset download needed!
+
+ULTRA-EFFICIENT: Uses HF Datasets Server API - completes in <2 seconds.
+
+Usage with HF Jobs:
+    hf_jobs("uv", {
+        "script": "https://huggingface.co/datasets/evalstate/trl-helpers/raw/main/dataset_inspector.py",
+        "script_args": ["--dataset", "your/dataset", "--split", "train"]
+    })
+"""
+
+import argparse
+import sys
+import json
+import urllib.request
+import urllib.parse
+from typing import List, Dict, Any
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="Inspect dataset format for TRL training")
+    parser.add_argument("--dataset", type=str, required=True, help="Dataset name")
+    parser.add_argument("--split", type=str, default="train", help="Dataset split (default: train)")
+    parser.add_argument("--config", type=str, default="default", help="Dataset config name (default: default)")
+    parser.add_argument("--preview", type=int, default=150, help="Max chars per field preview")
+    parser.add_argument("--samples", type=int, default=5, help="Number of samples to fetch (default: 5)")
+    parser.add_argument("--json-output", action="store_true", help="Output as JSON")
+    return parser.parse_args()
+
+
+def api_request(url: str) -> Dict:
+    """Make API request to Datasets Server"""
+    try:
+        with urllib.request.urlopen(url, timeout=10) as response:
+            return json.loads(response.read().decode())
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            return None
+        raise Exception(f"API request failed: {e.code} {e.reason}")
+    except Exception as e:
+        raise Exception(f"API request failed: {str(e)}")
+
+
+def get_splits(dataset: str) -> Dict:
+    """Get available splits for dataset"""
+    url = f"https://datasets-server.huggingface.co/splits?dataset={urllib.parse.quote(dataset)}"
+    return api_request(url)
+
+
+def get_rows(dataset: str, config: str, split: str, offset: int = 0, length: int = 5) -> Dict:
+    """Get rows from dataset"""
+    url = f"https://datasets-server.huggingface.co/rows?dataset={urllib.parse.quote(dataset)}&config={config}&split={split}&offset={offset}&length={length}"
+    return api_request(url)
+
+
+def find_columns(columns: List[str], patterns: List[str]) -> List[str]:
+    """Find columns matching patterns"""
+    return [c for c in columns if any(p in c.lower() for p in patterns)]
+
+
+def check_sft_compatibility(columns: List[str]) -> Dict[str, Any]:
+    """Check SFT compatibility"""
+    has_messages = "messages" in columns
+    has_text = "text" in columns
+    has_prompt_completion = "prompt" in columns and "completion" in columns
+    
+    ready = has_messages or has_text or has_prompt_completion
+    
+    possible_prompt = find_columns(columns, ["prompt", "instruction", "question", "input"])
+    possible_response = find_columns(columns, ["response", "completion", "output", "answer"])
+    
+    return {
+        "ready": ready,
+        "reason": "messages" if has_messages else "text" if has_text else "prompt+completion" if has_prompt_completion else None,
+        "possible_prompt": possible_prompt[0] if possible_prompt else None,
+        "possible_response": possible_response[0] if possible_response else None,
+        "has_context": "context" in columns,
+    }
+
+
+def check_dpo_compatibility(columns: List[str]) -> Dict[str, Any]:
+    """Check DPO compatibility"""
+    has_standard = "prompt" in columns and "chosen" in columns and "rejected" in columns
+    
+    possible_prompt = find_columns(columns, ["prompt", "instruction", "question", "input"])
+    possible_chosen = find_columns(columns, ["chosen", "preferred", "winner"])
+    possible_rejected = find_columns(columns, ["rejected", "dispreferred", "loser"])
+    
+    can_map = bool(possible_prompt and possible_chosen and possible_rejected)
+    
+    return {
+        "ready": has_standard,
+        "can_map": can_map,
+        "prompt_col": possible_prompt[0] if possible_prompt else None,
+        "chosen_col": possible_chosen[0] if possible_chosen else None,
+        "rejected_col": possible_rejected[0] if possible_rejected else None,
+    }
+
+
+def check_grpo_compatibility(columns: List[str]) -> Dict[str, Any]:
+    """Check GRPO compatibility"""
+    has_prompt = "prompt" in columns
+    has_no_responses = "chosen" not in columns and "rejected" not in columns
+    
+    possible_prompt = find_columns(columns, ["prompt", "instruction", "question", "input"])
+    
+    return {
+        "ready": has_prompt and has_no_responses,
+        "can_map": bool(possible_prompt) and has_no_responses,
+        "prompt_col": possible_prompt[0] if possible_prompt else None,
+    }
+
+
+def check_kto_compatibility(columns: List[str]) -> Dict[str, Any]:
+    """Check KTO compatibility"""
+    return {"ready": "prompt" in columns and "completion" in columns and "label" in columns}
+
+
+def generate_mapping_code(method: str, info: Dict[str, Any]) -> str:
+    """Generate mapping code for a training method"""
+    if method == "SFT":
+        if info["ready"]:
+            return None
+        
+        prompt_col = info.get("possible_prompt")
+        response_col = info.get("possible_response")
+        has_context = info.get("has_context", False)
+        
+        if not prompt_col:
+            return None
+        
+        if has_context and response_col:
+            return f"""def format_for_sft(example):
+    text = f"Instruction: {{example['{prompt_col}']}}\n\n"
+    if example.get('context'):
+        text += f"Context: {{example['context']}}\n\n"
+    text += f"Response: {{example['{response_col}']}}"
+    return {{'text': text}}
+
+dataset = dataset.map(format_for_sft, remove_columns=dataset.column_names)"""
+        elif response_col:
+            return f"""def format_for_sft(example):
+    return {{'text': f"{{example['{prompt_col}']}}\n\n{{example['{response_col}']}}}}
+
+dataset = dataset.map(format_for_sft, remove_columns=dataset.column_names)"""
+        else:
+            return f"""def format_for_sft(example):
+    return {{'text': example['{prompt_col}']}}
+
+dataset = dataset.map(format_for_sft, remove_columns=dataset.column_names)"""
+    
+    elif method == "DPO":
+        if info["ready"] or not info["can_map"]:
+            return None
+        
+        return f"""def format_for_dpo(example):
+    return {{
+        'prompt': example['{info['prompt_col']}'],
+        'chosen': example['{info['chosen_col']}'],
+        'rejected': example['{info['rejected_col']}'],
+    }}
+
+dataset = dataset.map(format_for_dpo, remove_columns=dataset.column_names)"""
+    
+    elif method == "GRPO":
+        if info["ready"] or not info["can_map"]:
+            return None
+        
+        return f"""def format_for_grpo(example):
+    return {{'prompt': example['{info['prompt_col']}']}}
+
+dataset = dataset.map(format_for_grpo, remove_columns=dataset.column_names)"""
+    
+    return None
+
+
+def format_value_preview(value: Any, max_chars: int) -> str:
+    """Format value for preview"""
+    if value is None:
+        return "None"
+    elif isinstance(value, str):
+        return value[:max_chars] + ("..." if len(value) > max_chars else "")
+    elif isinstance(value, list):
+        if len(value) > 0 and isinstance(value[0], dict):
+            return f"[{len(value)} items] Keys: {list(value[0].keys())}"
+        preview = str(value)
+        return preview[:max_chars] + ("..." if len(preview) > max_chars else "")
+    else:
+        preview = str(value)
+        return preview[:max_chars] + ("..." if len(preview) > max_chars else "")
+
+
+def main():
+    args = parse_args()
+    
+    print(f"Fetching dataset info via Datasets Server API...")
+    
+    try:
+        # Get splits info
+        splits_data = get_splits(args.dataset)
+        if not splits_data or "splits" not in splits_data:
+            print(f"ERROR: Could not fetch splits for dataset '{args.dataset}'")
+            print(f"       Dataset may not exist or is not accessible via Datasets Server API")
+            sys.exit(1)
+        
+        # Find the right config
+        available_configs = set()
+        split_found = False
+        config_to_use = args.config
+        
+        for split_info in splits_data["splits"]:
+            available_configs.add(split_info["config"])
+            if split_info["config"] == args.config and split_info["split"] == args.split:
+                split_found = True
+        
+        # If default config not found, try first available
+        if not split_found and available_configs:
+            config_to_use = list(available_configs)[0]
+            print(f"Config '{args.config}' not found, trying '{config_to_use}'...")
+        
+        # Get rows
+        rows_data = get_rows(args.dataset, config_to_use, args.split, offset=0, length=args.samples)
+        
+        if not rows_data or "rows" not in rows_data:
+            print(f"ERROR: Could not fetch rows for dataset '{args.dataset}'")
+            print(f"       Split '{args.split}' may not exist")
+            print(f"       Available configs: {', '.join(sorted(available_configs))}")
+            sys.exit(1)
+        
+        rows = rows_data["rows"]
+        if not rows:
+            print(f"ERROR: No rows found in split '{args.split}'")
+            sys.exit(1)
+        
+        # Extract column info from first row
+        first_row = rows[0]["row"]
+        columns = list(first_row.keys())
+        features = rows_data.get("features", [])
+        
+        # Get total count if available
+        total_examples = "Unknown"
+        for split_info in splits_data["splits"]:
+            if split_info["config"] == config_to_use and split_info["split"] == args.split:
+                total_examples = f"{split_info.get('num_examples', 'Unknown'):,}" if isinstance(split_info.get('num_examples'), int) else "Unknown"
+                break
+        
+    except Exception as e:
+        print(f"ERROR: {str(e)}")
+        sys.exit(1)
+    
+    # Run compatibility checks
+    sft_info = check_sft_compatibility(columns)
+    dpo_info = check_dpo_compatibility(columns)
+    grpo_info = check_grpo_compatibility(columns)
+    kto_info = check_kto_compatibility(columns)
+    
+    # Determine recommended methods
+    recommended = []
+    if sft_info["ready"]:
+        recommended.append("SFT")
+    elif sft_info["possible_prompt"]:
+        recommended.append("SFT (needs mapping)")
+    
+    if dpo_info["ready"]:
+        recommended.append("DPO")
+    elif dpo_info["can_map"]:
+        recommended.append("DPO (needs mapping)")
+    
+    if grpo_info["ready"]:
+        recommended.append("GRPO")
+    elif grpo_info["can_map"]:
+        recommended.append("GRPO (needs mapping)")
+    
+    if kto_info["ready"]:
+        recommended.append("KTO")
+    
+    # JSON output mode
+    if args.json_output:
+        result = {
+            "dataset": args.dataset,
+            "config": config_to_use,
+            "split": args.split,
+            "total_examples": total_examples,
+            "columns": columns,
+            "features": [{"name": f["name"], "type": f["type"]} for f in features] if features else [],
+            "compatibility": {
+                "SFT": sft_info,
+                "DPO": dpo_info,
+                "GRPO": grpo_info,
+                "KTO": kto_info,
+            },
+            "recommended_methods": recommended,
+        }
+        print(json.dumps(result, indent=2))
+        sys.exit(0)
+    
+    # Human-readable output optimized for LLM parsing
+    print("=" * 80)
+    print(f"DATASET INSPECTION RESULTS")
+    print("=" * 80)
+    
+    print(f"\nDataset: {args.dataset}")
+    print(f"Config: {config_to_use}")
+    print(f"Split: {args.split}")
+    print(f"Total examples: {total_examples}")
+    print(f"Samples fetched: {len(rows)}")
+    
+    print(f"\n{'COLUMNS':-<80}")
+    if features:
+        for feature in features:
+            print(f"  {feature['name']}: {feature['type']}")
+    else:
+        for col in columns:
+            print(f"  {col}: (type info not available)")
+    
+    print(f"\n{'EXAMPLE DATA':-<80}")
+    example = first_row
+    for col in columns:
+        value = example.get(col)
+        display = format_value_preview(value, args.preview)
+        print(f"\n{col}:")
+        print(f"  {display}")
+    
+    print(f"\n{'TRAINING METHOD COMPATIBILITY':-<80}")
+    
+    # SFT
+    print(f"\n[SFT] {'✓ READY' if sft_info['ready'] else '✗ NEEDS MAPPING'}")
+    if sft_info["ready"]:
+        print(f"  Reason: Dataset has '{sft_info['reason']}' field")
+        print(f"  Action: Use directly with SFTTrainer")
+    elif sft_info["possible_prompt"]:
+        print(f"  Detected: prompt='{sft_info['possible_prompt']}' response='{sft_info['possible_response']}'")
+        print(f"  Action: Apply mapping code (see below)")
+    else:
+        print(f"  Status: Cannot determine mapping - manual inspection needed")
+    
+    # DPO
+    print(f"\n[DPO] {'✓ READY' if dpo_info['ready'] else '✗ NEEDS MAPPING' if dpo_info['can_map'] else '✗ INCOMPATIBLE'}")
+    if dpo_info["ready"]:
+        print(f"  Reason: Dataset has 'prompt', 'chosen', 'rejected' fields")
+        print(f"  Action: Use directly with DPOTrainer")
+    elif dpo_info["can_map"]:
+        print(f"  Detected: prompt='{dpo_info['prompt_col']}' chosen='{dpo_info['chosen_col']}' rejected='{dpo_info['rejected_col']}'")
+        print(f"  Action: Apply mapping code (see below)")
+    else:
+        print(f"  Status: Missing required fields (prompt + chosen + rejected)")
+    
+    # GRPO
+    print(f"\n[GRPO] {'✓ READY' if grpo_info['ready'] else '✗ NEEDS MAPPING' if grpo_info['can_map'] else '✗ INCOMPATIBLE'}")
+    if grpo_info["ready"]:
+        print(f"  Reason: Dataset has 'prompt' field")
+        print(f"  Action: Use directly with GRPOTrainer")
+    elif grpo_info["can_map"]:
+        print(f"  Detected: prompt='{grpo_info['prompt_col']}'")
+        print(f"  Action: Apply mapping code (see below)")
+    else:
+        print(f"  Status: Missing prompt field")
+    
+    # KTO
+    print(f"\n[KTO] {'✓ READY' if kto_info['ready'] else '✗ INCOMPATIBLE'}")
+    if kto_info["ready"]:
+        print(f"  Reason: Dataset has 'prompt', 'completion', 'label' fields")
+        print(f"  Action: Use directly with KTOTrainer")
+    else:
+        print(f"  Status: Missing required fields (prompt + completion + label)")
+    
+    # Mapping code
+    print(f"\n{'MAPPING CODE (if needed)':-<80}")
+    
+    mapping_needed = False
+    
+    sft_mapping = generate_mapping_code("SFT", sft_info)
+    if sft_mapping:
+        print(f"\n# For SFT Training:")
+        print(sft_mapping)
+        mapping_needed = True
+    
+    dpo_mapping = generate_mapping_code("DPO", dpo_info)
+    if dpo_mapping:
+        print(f"\n# For DPO Training:")
+        print(dpo_mapping)
+        mapping_needed = True
+    
+    grpo_mapping = generate_mapping_code("GRPO", grpo_info)
+    if grpo_mapping:
+        print(f"\n# For GRPO Training:")
+        print(grpo_mapping)
+        mapping_needed = True
+    
+    if not mapping_needed:
+        print("\nNo mapping needed - dataset is ready for training!")
+    
+    print(f"\n{'SUMMARY':-<80}")
+    print(f"Recommended training methods: {', '.join(recommended) if recommended else 'None (dataset needs formatting)'}")
+    print(f"\nNote: Used Datasets Server API (instant, no download required)")
+    
+    print("\n" + "=" * 80)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except KeyboardInterrupt:
+        sys.exit(0)
+    except Exception as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        sys.exit(1)

.agents/skills/huggingface-llm-trainer/scripts/estimate_cost.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""
+Estimate training time and cost for TRL jobs.
+
+Usage with uv:
+    uv run estimate_cost.py --model <model> --dataset <dataset> --hardware <flavor>
+    
+Example:
+    uv run estimate_cost.py --model Qwen/Qwen2.5-0.5B --dataset trl-lib/Capybara --hardware a10g-large
+"""
+
+import argparse
+
+# Hardware costs per hour (approximate)
+HARDWARE_COSTS = {
+    "t4-small": 0.75,
+    "t4-medium": 1.50,
+    "l4x1": 2.50,
+    "a10g-small": 3.50,
+    "a10g-large": 5.00,
+    "a10g-largex2": 10.00,
+    "a10g-largex4": 20.00,
+    "a100-large": 10.00,
+}
+
+# Model sizes in billions of parameters
+MODEL_SIZES = {
+    "0.5B": 0.5,
+    "1.5B": 1.5,
+    "3B": 3,
+    "7B": 7,
+    "13B": 13,
+}
+
+def estimate_training_time(model_params, dataset_size, epochs, hardware):
+    """Estimate training time in hours."""
+    # Rough estimates based on empirical observations
+    # These are approximations and actual times will vary
+    
+    base_time_per_1k_examples = 0.1  # hours for 1B model on a10g-large
+    
+    # Adjust for model size
+    time = base_time_per_1k_examples * model_params * (dataset_size / 1000) * epochs
+    
+    # Adjust for hardware (relative to a10g-large baseline)
+    hardware_multipliers = {
+        "t4-small": 2.0,
+        "t4-medium": 1.5,
+        "l4x1": 1.2,
+        "a10g-small": 1.3,
+        "a10g-large": 1.0,
+        "a10g-largex2": 0.6,
+        "a10g-largex4": 0.4,
+        "a100-large": 0.7,
+    }
+    
+    multiplier = hardware_multipliers.get(hardware, 1.0)
+    time *= multiplier
+    
+    return time
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="Estimate training cost for TRL jobs")
+    parser.add_argument("--model", required=True, help="Model name or size (e.g., 'Qwen/Qwen2.5-0.5B' or '0.5B')")
+    parser.add_argument("--dataset", required=True, help="Dataset name")
+    parser.add_argument("--hardware", required=True, choices=HARDWARE_COSTS.keys(), help="Hardware flavor")
+    parser.add_argument("--dataset-size", type=int, help="Override dataset size (number of examples)")
+    parser.add_argument("--epochs", type=int, default=3, help="Number of training epochs")
+    return parser.parse_args()
+
+def extract_model_size(model_name):
+    """Extract model size from name or return parsed value."""
+    for size_str, size_val in MODEL_SIZES.items():
+        if size_str in model_name:
+            return size_val
+    
+    # Try to parse directly
+    try:
+        if "B" in model_name:
+            return float(model_name.replace("B", ""))
+    except:
+        pass
+    
+    return 1.0  # Default to 1B if can't determine
+
+def main():
+    args = parse_args()
+    
+    # Extract model parameters
+    model_params = extract_model_size(args.model)
+    print(f"📊 Model: {args.model} (~{model_params}B parameters)")
+    
+    # Estimate dataset size (would need to load to get real size)
+    if args.dataset_size:
+        dataset_size = args.dataset_size
+    else:
+        # Common dataset sizes (approximations)
+        dataset_sizes = {
+            "trl-lib/Capybara": 16000,
+            "Anthropic/hh-rlhf": 160000,
+        }
+        dataset_size = dataset_sizes.get(args.dataset, 10000)
+    
+    print(f"📦 Dataset: {args.dataset} (~{dataset_size} examples)")
+    print(f"🔄 Epochs: {args.epochs}")
+    print(f"💻 Hardware: {args.hardware}")
+    print()
+    
+    # Estimate training time
+    estimated_hours = estimate_training_time(model_params, dataset_size, args.epochs, args.hardware)
+    estimated_cost = estimated_hours * HARDWARE_COSTS[args.hardware]
+    
+    # Recommend timeout with buffer
+    recommended_timeout_hours = estimated_hours * 1.3  # 30% buffer
+    
+    print(f"⏱️  Estimated training time: {estimated_hours:.1f} hours")
+    print(f"💰 Estimated cost: ${estimated_cost:.2f}")
+    print(f"⏰ Recommended timeout: {recommended_timeout_hours:.1f}h (with 30% buffer)")
+    print()
+    
+    # Warnings and recommendations
+    if estimated_hours > 4:
+        print("⚠️  Long training time - consider:")
+        print("   - Using faster hardware")
+        print("   - Reducing epochs")
+        print("   - Using a smaller dataset subset for testing")
+    
+    if model_params >= 7 and args.hardware not in ["a10g-largex2", "a10g-largex4", "a100-large"]:
+        print("⚠️  Large model - consider using:")
+        print("   - Larger GPU (a100-large)")
+        print("   - Multi-GPU setup (a10g-largex2 or a10g-largex4)")
+        print("   - LoRA/PEFT for memory efficiency")
+    
+    print()
+    print("📋 Example job configuration:")
+    print(f"""
+hf_jobs("uv", {{
+    "script": "your_training_script.py",
+    "flavor": "{args.hardware}",
+    "timeout": "{recommended_timeout_hours:.0f}h",
+    "secrets": {{"HF_TOKEN": "$HF_TOKEN"}}
+}})
+""")
+
+if __name__ == "__main__":
+    main()

.agents/skills/huggingface-llm-trainer/scripts/hf_benchmarks.py

@@ -0,0 +1,659 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""
+Search Hugging Face benchmark datasets and fetch leaderboard results.
+
+This script is designed to be pipeline-friendly:
+  - search benchmark datasets by free text, alias, task, and modality
+  - fetch dataset leaderboards in normalized JSON / NDJSON / table form
+  - optionally read dataset ids from stdin for chaining
+
+It uses HF_TOKEN automatically when present.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import textwrap
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Iterable
+
+
+BASE_URL = "https://huggingface.co"
+DEFAULT_TIMEOUT = 30
+
+ALIASES: dict[str, list[str]] = {
+    "ocr": [
+        "ocr",
+        "olmocr",
+        "pdf",
+        "image-to-text",
+        "screen",
+        "screenspot",
+        "markdown",
+        "text recognition",
+    ],
+    "coding": [
+        "code",
+        "coding",
+        "software engineering",
+        "programming",
+        "swe",
+        "terminal",
+        "patch",
+        "bug",
+        "cuda",
+    ],
+    "math": [
+        "math",
+        "reasoning",
+        "gsm8k",
+        "mmlu",
+        "gpqa",
+        "aime",
+        "hmmt",
+    ],
+    "retrieval": [
+        "retrieval",
+        "search",
+        "mteb",
+        "arguana",
+        "bright",
+    ],
+    "agents": [
+        "agent",
+        "agents",
+        "terminal",
+        "screen",
+        "computer use",
+        "tool use",
+    ],
+    "asr": [
+        "asr",
+        "speech",
+        "audio",
+        "transcribe",
+        "transcription",
+    ],
+}
+
+
+class HfApiError(RuntimeError):
+    pass
+
+
+class FullHelpArgumentParser(argparse.ArgumentParser):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._search_parser: argparse.ArgumentParser | None = None
+        self._leaderboard_parser: argparse.ArgumentParser | None = None
+
+    def format_help(self) -> str:
+        text = super().format_help()
+        extra_sections: list[str] = []
+
+        if self._search_parser is not None:
+            extra_sections.append(
+                "\nsearch command options:\n"
+                + textwrap.indent(self._search_parser.format_help().strip(), "  ")
+            )
+
+        if self._leaderboard_parser is not None:
+            extra_sections.append(
+                "\nleaderboard command options:\n"
+                + textwrap.indent(self._leaderboard_parser.format_help().strip(), "  ")
+            )
+
+        if extra_sections:
+            text += "\n" + "\n".join(extra_sections) + "\n"
+        return text
+
+
+def auth_headers() -> dict[str, str]:
+    token = os.getenv("HF_TOKEN")
+    return {"Authorization": f"Bearer {token}"} if token else {}
+
+
+def http_get_json(path: str, params: dict[str, Any] | None = None) -> Any:
+    url = f"{BASE_URL}{path}"
+    if params:
+        pairs: list[tuple[str, str]] = []
+        for key, value in params.items():
+            if value is None:
+                continue
+            if isinstance(value, (list, tuple)):
+                for item in value:
+                    pairs.append((key, str(item)))
+            else:
+                pairs.append((key, str(value)))
+        if pairs:
+            url = f"{url}?{urllib.parse.urlencode(pairs)}"
+
+    req = urllib.request.Request(url, headers=auth_headers())
+    try:
+        with urllib.request.urlopen(req, timeout=DEFAULT_TIMEOUT) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")
+        raise HfApiError(f"{exc.code} {exc.reason} for {url}: {body[:500]}") from exc
+    except urllib.error.URLError as exc:
+        raise HfApiError(f"Request failed for {url}: {exc}") from exc
+
+
+def shorten(text: str, width: int) -> str:
+    text = " ".join((text or "").split())
+    if len(text) <= width:
+        return text
+    return text[: max(0, width - 1)] + "…"
+
+
+def first_text(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list):
+        return " ".join(first_text(v) for v in value)
+    if isinstance(value, dict):
+        return " ".join(first_text(v) for v in value.values())
+    return str(value)
+
+
+def benchmark_catalog(limit: int = 500) -> list[dict[str, Any]]:
+    data = http_get_json(
+        "/api/datasets",
+        params={"filter": "benchmark:official", "limit": limit, "full": "true"},
+    )
+    if not isinstance(data, list):
+        raise HfApiError("Unexpected response while listing benchmark datasets")
+    return data
+
+
+def dataset_search_blob(dataset: dict[str, Any]) -> str:
+    card = dataset.get("cardData") or {}
+    parts = [
+        dataset.get("id", ""),
+        dataset.get("description", ""),
+        first_text(dataset.get("tags")),
+        first_text(card.get("pretty_name")),
+        first_text(card.get("tags")),
+        first_text(card.get("task_categories")),
+        first_text(card.get("task_ids")),
+    ]
+    return " ".join(parts).lower()
+
+
+def dataset_search_fields(dataset: dict[str, Any]) -> dict[str, str]:
+    card = dataset.get("cardData") or {}
+    return {
+        "id": first_text(dataset.get("id")).lower(),
+        "pretty_name": first_text(card.get("pretty_name")).lower(),
+        "tags": " ".join(
+            [
+                first_text(dataset.get("tags")),
+                first_text(card.get("tags")),
+                first_text(card.get("task_categories")),
+                first_text(card.get("task_ids")),
+                first_text(card.get("modality")),
+            ]
+        ).lower(),
+        "description": first_text(dataset.get("description")).lower(),
+    }
+
+
+def collect_prefixed_tags(dataset: dict[str, Any], prefixes: Iterable[str]) -> list[str]:
+    prefixes = tuple(prefixes)
+    tags = dataset.get("tags") or []
+    card = dataset.get("cardData") or {}
+
+    out: list[str] = []
+    for tag in tags:
+        if isinstance(tag, str) and tag.startswith(prefixes):
+            out.append(tag)
+
+    for key, prefix in (
+        ("task_categories", "task_categories:"),
+        ("task_ids", "task_ids:"),
+        ("modality", "modality:"),
+    ):
+        values = card.get(key)
+        if isinstance(values, list):
+            for value in values:
+                full_tag = f"{prefix}{value}"
+                if full_tag.startswith(prefixes):
+                    out.append(full_tag)
+
+    deduped: list[str] = []
+    seen: set[str] = set()
+    for tag in out:
+        if tag not in seen:
+            deduped.append(tag)
+            seen.add(tag)
+    return deduped
+
+
+def expand_aliases(aliases: list[str]) -> dict[str, list[str]]:
+    expanded: dict[str, list[str]] = {}
+    for alias in aliases:
+        terms = ALIASES.get(alias.lower(), [alias])
+        expanded[alias] = terms
+    return expanded
+
+
+def matches_term(blob: str, term: str) -> bool:
+    candidate = term.lower().strip()
+    if not candidate:
+        return False
+    if re.fullmatch(r"[a-z0-9_]+", candidate):
+        return re.search(rf"(?<![a-z0-9_]){re.escape(candidate)}(?![a-z0-9_])", blob) is not None
+    return candidate in blob
+
+
+def score_dataset(
+    dataset: dict[str, Any],
+    queries: list[str],
+    aliases: dict[str, list[str]],
+    tasks: list[str],
+    modalities: list[str],
+) -> dict[str, Any]:
+    blob = dataset_search_blob(dataset)
+    fields = dataset_search_fields(dataset)
+    task_tags = collect_prefixed_tags(dataset, ["task_categories:", "task_ids:"])
+    modality_tags = collect_prefixed_tags(dataset, ["modality:"])
+
+    score = 0
+    reasons: list[str] = []
+
+    for query in queries:
+        q = query.lower().strip()
+        if q and any(matches_term(value, q) for value in fields.values()):
+            score += 3
+            reasons.append(f"query:{query}")
+
+    for alias_name, terms in aliases.items():
+        matched_terms: list[str] = []
+        alias_score = 0
+        for term in terms:
+            strong_match = any(
+                matches_term(fields[field_name], term)
+                for field_name in ("id", "pretty_name", "tags")
+            )
+            desc_match = matches_term(fields["description"], term)
+            if strong_match:
+                alias_score += 2
+                matched_terms.append(term)
+            elif desc_match:
+                alias_score += 1
+                matched_terms.append(term)
+        if matched_terms:
+            score += alias_score
+            reasons.append(f"alias:{alias_name}=" + ",".join(matched_terms[:5]))
+
+    lower_task_tags = [t.lower() for t in task_tags]
+    for task in tasks:
+        task = task.lower().strip()
+        if not task:
+            continue
+        exact = [
+            tag
+            for tag in lower_task_tags
+            if tag == f"task_categories:{task}" or tag == f"task_ids:{task}"
+        ]
+        fuzzy = matches_term(blob, task)
+        if exact:
+            score += 5
+            reasons.append(f"task:{task}")
+        elif fuzzy:
+            score += 2
+            reasons.append(f"task~:{task}")
+
+    lower_modality_tags = [m.lower() for m in modality_tags]
+    for modality in modalities:
+        modality = modality.lower().strip()
+        if not modality:
+            continue
+        if f"modality:{modality}" in lower_modality_tags:
+            score += 4
+            reasons.append(f"modality:{modality}")
+
+    return {
+        "dataset_id": dataset.get("id"),
+        "score": score,
+        "reasons": reasons,
+        "task_tags": task_tags,
+        "modality_tags": modality_tags,
+        "benchmark_tags": collect_prefixed_tags(dataset, ["benchmark:"]),
+        "pretty_name": (dataset.get("cardData") or {}).get("pretty_name"),
+        "downloads": dataset.get("downloads"),
+        "description": " ".join((dataset.get("description") or "").split()),
+    }
+
+
+def search_benchmarks(
+    queries: list[str],
+    aliases: list[str],
+    tasks: list[str],
+    modalities: list[str],
+    limit: int,
+) -> list[dict[str, Any]]:
+    datasets = benchmark_catalog(limit=500)
+    alias_map = expand_aliases(aliases)
+
+    results = [score_dataset(ds, queries, alias_map, tasks, modalities) for ds in datasets]
+
+    active_filters = bool(queries or aliases or tasks or modalities)
+    if active_filters:
+        results = [row for row in results if row["score"] >= 2]
+
+    results.sort(
+        key=lambda row: (
+            -row["score"],
+            -(row["downloads"] or 0),
+            row["dataset_id"] or "",
+        )
+    )
+    return results[:limit]
+
+
+def parse_repo_id(repo_id: str) -> tuple[str, str]:
+    if "/" not in repo_id:
+        raise ValueError(f"Expected <namespace>/<repo>, got: {repo_id}")
+    namespace, repo = repo_id.split("/", 1)
+    return namespace, repo
+
+
+def get_leaderboard(repo_id: str, task_id: str | None = None) -> list[dict[str, Any]]:
+    namespace, repo = parse_repo_id(repo_id)
+    params = {"task_id": task_id} if task_id else None
+    data = http_get_json(f"/api/datasets/{namespace}/{repo}/leaderboard", params=params)
+    if not isinstance(data, list):
+        raise HfApiError(f"Unexpected leaderboard response for {repo_id}")
+
+    normalized: list[dict[str, Any]] = []
+    for row in data:
+        source = row.get("source") or {}
+        normalized.append(
+            {
+                "dataset_id": repo_id,
+                "task_id": task_id,
+                "rank": row.get("rank"),
+                "model_id": row.get("modelId"),
+                "value": row.get("value"),
+                "verified": row.get("verified"),
+                "lower_is_better": row.get("lower_is_better"),
+                "filename": row.get("filename"),
+                "notes": row.get("notes"),
+                "pull_request": row.get("pullRequest"),
+                "source_name": source.get("name"),
+                "source_url": source.get("url"),
+                "source_is_external": source.get("isExternal"),
+            }
+        )
+    return normalized
+
+
+def read_repo_ids_from_stdin() -> list[str]:
+    if sys.stdin.isatty():
+        return []
+
+    repo_ids: list[str] = []
+    for raw_line in sys.stdin:
+        line = raw_line.strip()
+        if not line:
+            continue
+        if line.startswith("{"):
+            try:
+                obj = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            candidate = obj.get("dataset_id") or obj.get("id")
+            if isinstance(candidate, str) and "/" in candidate:
+                repo_ids.append(candidate)
+            continue
+        if "/" in line:
+            repo_ids.append(line)
+    return repo_ids
+
+
+def print_json(data: Any) -> None:
+    json.dump(data, sys.stdout, indent=2, ensure_ascii=False)
+    sys.stdout.write("\n")
+
+
+def print_ndjson(rows: list[dict[str, Any]]) -> None:
+    for row in rows:
+        sys.stdout.write(json.dumps(row, ensure_ascii=False) + "\n")
+
+
+def print_search_table(rows: list[dict[str, Any]]) -> None:
+    if not rows:
+        print("No benchmark datasets matched.")
+        return
+
+    headers = ["dataset_id", "score", "modalities", "tasks", "reasons", "description"]
+    widths = [34, 5, 18, 24, 30, 68]
+    print("  ".join(h.ljust(w) for h, w in zip(headers, widths)))
+    print("  ".join("-" * w for w in widths))
+    for row in rows:
+        values = [
+            shorten(row.get("dataset_id") or "", widths[0]),
+            str(row.get("score", "")),
+            shorten(", ".join(row.get("modality_tags") or []), widths[2]),
+            shorten(", ".join(row.get("task_tags") or []), widths[3]),
+            shorten(", ".join(row.get("reasons") or []), widths[4]),
+            shorten(row.get("description") or "", widths[5]),
+        ]
+        print("  ".join(v.ljust(w) for v, w in zip(values, widths)))
+
+
+def print_leaderboard_table(rows: list[dict[str, Any]]) -> None:
+    if not rows:
+        print("No leaderboard rows returned.")
+        return
+
+    headers = ["dataset_id", "rank", "model_id", "value", "verified", "source"]
+    widths = [30, 5, 38, 10, 8, 28]
+    print("  ".join(h.ljust(w) for h, w in zip(headers, widths)))
+    print("  ".join("-" * w for w in widths))
+    for row in rows:
+        values = [
+            shorten(str(row.get("dataset_id") or ""), widths[0]),
+            str(row.get("rank") or ""),
+            shorten(str(row.get("model_id") or ""), widths[2]),
+            shorten(str(row.get("value") or ""), widths[3]),
+            str(row.get("verified")),
+            shorten(str(row.get("source_name") or ""), widths[5]),
+        ]
+        print("  ".join(v.ljust(w) for v, w in zip(values, widths)))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = FullHelpArgumentParser(
+        prog="hf_benchmarks.py",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description=textwrap.dedent(
+            """
+            Search benchmark datasets and fetch leaderboard results from the Hugging Face Hub.
+
+            Workflow ideas:
+              1) Discover candidate benchmarks:
+                   hf_benchmarks.py search --alias ocr
+                   hf_benchmarks.py search --alias coding
+                   hf_benchmarks.py search --task image-to-text --modality document
+
+              2) Inspect a leaderboard:
+                   hf_benchmarks.py leaderboard allenai/olmOCR-bench --top 10
+
+              3) Chain search -> leaderboard:
+                   hf_benchmarks.py search --alias coding --format ndjson \\
+                     | hf_benchmarks.py leaderboard --stdin --top 5 --format table
+            """
+        ),
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    search_parser = subparsers.add_parser(
+        "search",
+        help="Search benchmark datasets by query, alias, task, and modality",
+    )
+    search_parser.add_argument(
+        "--query",
+        action="append",
+        default=[],
+        help="Free-text query to match against benchmark dataset metadata. Repeatable.",
+    )
+    search_parser.add_argument(
+        "--alias",
+        action="append",
+        default=[],
+        help=(
+            "Convenience alias for common benchmark domains. Known aliases: "
+            + ", ".join(sorted(ALIASES))
+            + ". Repeatable."
+        ),
+    )
+    search_parser.add_argument(
+        "--task",
+        action="append",
+        default=[],
+        help="Task to match, e.g. text-generation, image-to-text, question-answering. Repeatable.",
+    )
+    search_parser.add_argument(
+        "--modality",
+        action="append",
+        default=[],
+        help="Modality to match, e.g. text, image, document, audio. Repeatable.",
+    )
+    search_parser.add_argument(
+        "--limit",
+        type=int,
+        default=20,
+        help="Maximum number of rows to print (default: 20).",
+    )
+    search_parser.add_argument(
+        "--format",
+        choices=["table", "json", "ndjson"],
+        default="table",
+        help="Output format (default: table).",
+    )
+
+    leaderboard_parser = subparsers.add_parser(
+        "leaderboard",
+        help="Fetch normalized leaderboard rows for one or more benchmark datasets",
+    )
+    leaderboard_parser.add_argument(
+        "datasets",
+        nargs="*",
+        help="Dataset repo ids (<namespace>/<repo>). Can also be supplied via stdin with --stdin.",
+    )
+    leaderboard_parser.add_argument(
+        "--stdin",
+        action="store_true",
+        help="Read dataset ids from stdin. Accepts plain repo ids or NDJSON with dataset_id/id fields.",
+    )
+    leaderboard_parser.add_argument(
+        "--task-id",
+        default=None,
+        help="Optional leaderboard task_id query parameter.",
+    )
+    leaderboard_parser.add_argument(
+        "--top",
+        type=int,
+        default=None,
+        help="Only keep the top N results per leaderboard.",
+    )
+    leaderboard_parser.add_argument(
+        "--format",
+        choices=["table", "json", "ndjson"],
+        default="table",
+        help="Output format (default: table).",
+    )
+
+    parser._search_parser = search_parser
+    parser._leaderboard_parser = leaderboard_parser
+
+    return parser
+
+
+def run_search(args: argparse.Namespace) -> int:
+    rows = search_benchmarks(
+        queries=args.query,
+        aliases=args.alias,
+        tasks=args.task,
+        modalities=args.modality,
+        limit=args.limit,
+    )
+
+    if args.format == "json":
+        print_json(rows)
+    elif args.format == "ndjson":
+        print_ndjson(rows)
+    else:
+        print_search_table(rows)
+    return 0
+
+
+def run_leaderboard(args: argparse.Namespace) -> int:
+    repo_ids = list(args.datasets)
+    if args.stdin:
+        repo_ids.extend(read_repo_ids_from_stdin())
+
+    deduped: list[str] = []
+    seen: set[str] = set()
+    for repo_id in repo_ids:
+        if repo_id not in seen:
+            deduped.append(repo_id)
+            seen.add(repo_id)
+    repo_ids = deduped
+
+    if not repo_ids:
+        print("Error: provide dataset ids or use --stdin.", file=sys.stderr)
+        return 2
+
+    rows: list[dict[str, Any]] = []
+    for repo_id in repo_ids:
+        dataset_rows = get_leaderboard(repo_id, task_id=args.task_id)
+        if args.top is not None:
+            dataset_rows = dataset_rows[: args.top]
+        rows.extend(dataset_rows)
+
+    if args.format == "json":
+        print_json(rows)
+    elif args.format == "ndjson":
+        print_ndjson(rows)
+    else:
+        print_leaderboard_table(rows)
+    return 0
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    try:
+        if args.command == "search":
+            return run_search(args)
+        if args.command == "leaderboard":
+            return run_leaderboard(args)
+        parser.error(f"Unknown command: {args.command}")
+        return 2
+    except HfApiError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+    except ValueError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.agents/skills/huggingface-llm-trainer/scripts/train_dpo_example.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "trl>=0.12.0",
+#     "transformers>=4.36.0",
+#     "accelerate>=0.24.0",
+#     "trackio",
+# ]
+# ///
+
+"""
+Production-ready DPO training example for preference learning.
+
+DPO (Direct Preference Optimization) trains models on preference pairs
+(chosen vs rejected responses) without requiring a reward model.
+
+Usage with hf_jobs MCP tool:
+    hf_jobs("uv", {
+        "script": '''<paste this entire file>''',
+        "flavor": "a10g-large",
+        "timeout": "3h",
+        "secrets": {"HF_TOKEN": "$HF_TOKEN"},
+    })
+
+Or submit the script content directly inline without saving to a file.
+"""
+
+import trackio
+from datasets import load_dataset
+from trl import DPOTrainer, DPOConfig
+
+
+# Load preference dataset
+print("📦 Loading dataset...")
+dataset = load_dataset("trl-lib/ultrafeedback_binarized", split="train")
+print(f"✅ Dataset loaded: {len(dataset)} preference pairs")
+
+# Create train/eval split
+print("🔀 Creating train/eval split...")
+dataset_split = dataset.train_test_split(test_size=0.1, seed=42)
+train_dataset = dataset_split["train"]
+eval_dataset = dataset_split["test"]
+print(f"   Train: {len(train_dataset)} pairs")
+print(f"   Eval: {len(eval_dataset)} pairs")
+
+# Training configuration
+config = DPOConfig(
+    # CRITICAL: Hub settings
+    output_dir="qwen-dpo-aligned",
+    push_to_hub=True,
+    hub_model_id="username/qwen-dpo-aligned",
+    hub_strategy="every_save",
+
+    # DPO-specific parameters
+    beta=0.1,  # KL penalty coefficient (higher = stay closer to reference)
+
+    # Training parameters
+    num_train_epochs=1,  # DPO typically needs fewer epochs than SFT
+    per_device_train_batch_size=4,
+    gradient_accumulation_steps=4,
+    learning_rate=5e-7,  # DPO uses much lower LR than SFT
+    # max_length=1024,  # Default - only set if you need different sequence length
+
+    # Logging & checkpointing
+    logging_steps=10,
+    save_strategy="steps",
+    save_steps=100,
+    save_total_limit=2,
+
+    # Evaluation - IMPORTANT: Only enable if eval_dataset provided
+    eval_strategy="steps",
+    eval_steps=100,
+
+    # Optimization
+    warmup_ratio=0.1,
+    lr_scheduler_type="cosine",
+
+    # Monitoring
+    report_to="trackio",  # Integrate with Trackio
+    project="meaningful_project_name", # project name for the training name (trackio)
+    run_name="baseline-run", #Descriptive name for this training run
+
+)
+
+# Initialize and train
+# Note: DPO requires an instruct-tuned model as the base
+print("🎯 Initializing trainer...")
+trainer = DPOTrainer(
+    model="Qwen/Qwen2.5-0.5B-Instruct",  # Use instruct model, not base model
+    train_dataset=train_dataset,
+    eval_dataset=eval_dataset,  # CRITICAL: Must provide eval_dataset when eval_strategy is enabled
+    args=config,
+)
+
+print("🚀 Starting DPO training...")
+trainer.train()
+
+print("💾 Pushing to Hub...")
+trainer.push_to_hub()
+
+# Finish Trackio tracking
+trackio.finish()
+
+print("✅ Complete! Model at: https://huggingface.co/username/qwen-dpo-aligned")
+print("📊 View metrics at: https://huggingface.co/spaces/username/trackio")

.agents/skills/huggingface-llm-trainer/scripts/train_grpo_example.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "trl>=0.12.0",
+#     "transformers>=4.36.0",
+#     "accelerate>=0.24.0",
+#     "trackio",
+# ]
+# ///
+
+"""
+Production-ready GRPO training example for online RL.
+
+GRPO (Group Relative Policy Optimization) is an online RL method that
+optimizes relative to group performance. Best for tasks with automatic
+reward signals like code execution or math verification.
+
+Usage with hf_jobs MCP tool:
+    hf_jobs("uv", {
+        "script": '''<paste this entire file>''',
+        "flavor": "a10g-large",
+        "timeout": "4h",
+        "secrets": {"HF_TOKEN": "$HF_TOKEN"},
+    })
+
+Or submit the script content directly inline without saving to a file.
+
+Note: For most GRPO use cases, the TRL maintained script is recommended:
+    https://raw.githubusercontent.com/huggingface/trl/main/examples/scripts/grpo.py
+"""
+
+import trackio
+from datasets import load_dataset
+from trl import GRPOTrainer, GRPOConfig
+
+
+# Load dataset (GRPO uses prompt-only format)
+dataset = load_dataset("trl-lib/math_shepherd", split="train")
+print(f"✅ Dataset loaded: {len(dataset)} prompts")
+
+# Training configuration
+config = GRPOConfig(
+    # CRITICAL: Hub settings
+    output_dir="qwen-grpo-math",
+    push_to_hub=True,
+    hub_model_id="username/qwen-grpo-math",
+    hub_strategy="every_save",
+
+    # Training parameters
+    num_train_epochs=1,
+    per_device_train_batch_size=4,
+    gradient_accumulation_steps=4,
+    learning_rate=1e-6,
+
+    # Logging & checkpointing
+    logging_steps=10,
+    save_strategy="steps",
+    save_steps=100,
+    save_total_limit=2,
+
+    # Optimization
+    warmup_ratio=0.1,
+    lr_scheduler_type="cosine",
+
+    # Monitoring
+    report_to="trackio",  # Integrate with Trackio
+    project="meaningful_project_name", # project name for the training name (trackio)
+    run_name="baseline-run", #Descriptive name for this training run
+
+)
+
+# Initialize and train
+# Note: GRPO requires an instruct-tuned model as the base
+trainer = GRPOTrainer(
+    model="Qwen/Qwen2.5-0.5B-Instruct",
+    train_dataset=dataset,
+    args=config,
+)
+
+print("🚀 Starting GRPO training...")
+trainer.train()
+
+print("💾 Pushing to Hub...")
+trainer.push_to_hub()
+
+
+print("✅ Complete! Model at: https://huggingface.co/username/qwen-grpo-math")
+print("📊 View metrics at: https://huggingface.co/spaces/username/trackio")

.agents/skills/huggingface-llm-trainer/scripts/train_sft_example.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "trl>=0.12.0",
+#     "peft>=0.7.0",
+#     "transformers>=4.36.0",
+#     "accelerate>=0.24.0",
+#     "trackio",
+# ]
+# ///
+
+"""
+Production-ready SFT training example with all best practices.
+
+This script demonstrates:
+- Trackio integration for real-time monitoring
+- LoRA/PEFT for efficient training
+- Proper Hub saving configuration
+- Train/eval split for monitoring
+- Checkpoint management
+- Optimized training parameters
+
+Usage with hf_jobs MCP tool:
+    hf_jobs("uv", {
+        "script": '''<paste this entire file>''',
+        "flavor": "a10g-large",
+        "timeout": "3h",
+        "secrets": {"HF_TOKEN": "$HF_TOKEN"},
+    })
+
+Or submit the script content directly inline without saving to a file.
+"""
+
+import trackio
+from datasets import load_dataset
+from peft import LoraConfig
+from trl import SFTTrainer, SFTConfig
+
+
+# Load dataset
+print("📦 Loading dataset...")
+dataset = load_dataset("trl-lib/Capybara", split="train")
+print(f"✅ Dataset loaded: {len(dataset)} examples")
+
+# Create train/eval split
+print("🔀 Creating train/eval split...")
+dataset_split = dataset.train_test_split(test_size=0.1, seed=42)
+train_dataset = dataset_split["train"]
+eval_dataset = dataset_split["test"]
+print(f"   Train: {len(train_dataset)} examples")
+print(f"   Eval: {len(eval_dataset)} examples")
+
+# Note: For memory-constrained demos, skip eval by using full dataset as train_dataset
+# and removing eval_dataset, eval_strategy, and eval_steps from config below
+
+# Training configuration
+config = SFTConfig(
+    # CRITICAL: Hub settings
+    output_dir="qwen-capybara-sft",
+    push_to_hub=True,
+    hub_model_id="username/qwen-capybara-sft",
+    hub_strategy="every_save",  # Push checkpoints
+
+    # Training parameters
+    num_train_epochs=3,
+    per_device_train_batch_size=4,
+    gradient_accumulation_steps=4,
+    learning_rate=2e-5,
+    # max_length=1024,  # Default - only set if you need different sequence length
+
+    # Logging & checkpointing
+    logging_steps=10,
+    save_strategy="steps",
+    save_steps=100,
+    save_total_limit=2,
+
+    # Evaluation - IMPORTANT: Only enable if eval_dataset provided
+    eval_strategy="steps",
+    eval_steps=100,
+
+    # Optimization
+    warmup_ratio=0.1,
+    lr_scheduler_type="cosine",
+
+    # Monitoring
+    report_to="trackio",  # Integrate with Trackio
+    project="meaningful_project_name", # project name for the training name (trackio)
+    run_name="baseline-run", #Descriptive name for this training run
+)
+
+# LoRA configuration
+peft_config = LoraConfig(
+    r=16,
+    lora_alpha=32,
+    lora_dropout=0.05,
+    bias="none",
+    task_type="CAUSAL_LM",
+    target_modules=["q_proj", "v_proj"],
+)
+
+# Initialize and train
+print("🎯 Initializing trainer...")
+trainer = SFTTrainer(
+    model="Qwen/Qwen2.5-0.5B",
+    train_dataset=train_dataset,
+    eval_dataset=eval_dataset,  # CRITICAL: Must provide eval_dataset when eval_strategy is enabled
+    args=config,
+    peft_config=peft_config,
+)
+
+print("🚀 Starting training...")
+trainer.train()
+
+print("💾 Pushing to Hub...")
+trainer.push_to_hub()
+
+# Finish Trackio tracking
+trackio.finish()
+
+print("✅ Complete! Model at: https://huggingface.co/username/qwen-capybara-sft")
+print("📊 View metrics at: https://huggingface.co/spaces/username/trackio")

.agents/skills/huggingface-llm-trainer/scripts/unsloth_sft_example.py

@@ -0,0 +1,512 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "unsloth",
+#     "datasets",
+#     "trl==0.22.2",
+#     "huggingface_hub[hf_transfer]",
+#     "trackio",
+#     "tensorboard",
+#     "transformers==4.57.3",
+# ]
+# ///
+"""
+Fine-tune LLMs using Unsloth optimizations for ~60% less VRAM and 2x faster training.
+
+Supports epoch-based or step-based training with optional eval split.
+Default model: LFM2.5-1.2B-Instruct (Liquid Foundation Model).
+
+Epoch-based training (recommended for full datasets):
+    uv run unsloth_sft_example.py \
+        --dataset mlabonne/FineTome-100k \
+        --num-epochs 1 \
+        --eval-split 0.2 \
+        --output-repo your-username/model-finetuned
+
+Run on HF Jobs (1 epoch with eval):
+    hf jobs uv run unsloth_sft_example.py \
+        --flavor a10g-small --secrets HF_TOKEN --timeout 4h \
+        -- --dataset mlabonne/FineTome-100k \
+           --num-epochs 1 \
+           --eval-split 0.2 \
+           --output-repo your-username/model-finetuned
+
+Step-based training (for quick tests):
+    uv run unsloth_sft_example.py \
+        --dataset mlabonne/FineTome-100k \
+        --max-steps 500 \
+        --output-repo your-username/model-finetuned
+"""
+
+import argparse
+import logging
+import os
+import sys
+import time
+
+# Force unbuffered output for HF Jobs logs
+sys.stdout.reconfigure(line_buffering=True)
+sys.stderr.reconfigure(line_buffering=True)
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+def check_cuda():
+    """Check CUDA availability and exit if not available."""
+    import torch
+
+    if not torch.cuda.is_available():
+        logger.error("CUDA is not available. This script requires a GPU.")
+        logger.error("Run on a machine with a CUDA-capable GPU or use HF Jobs:")
+        logger.error(
+            "  hf jobs uv run unsloth_sft_example.py --flavor a10g-small ..."
+        )
+        sys.exit(1)
+    logger.info(f"CUDA available: {torch.cuda.get_device_name(0)}")
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        description="Fine-tune LLMs with Unsloth optimizations",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Quick test run
+  uv run unsloth_sft_example.py \\
+      --dataset mlabonne/FineTome-100k \\
+      --max-steps 50 \\
+      --output-repo username/model-test
+
+  # Full training with eval
+  uv run unsloth_sft_example.py \\
+      --dataset mlabonne/FineTome-100k \\
+      --num-epochs 1 \\
+      --eval-split 0.2 \\
+      --output-repo username/model-finetuned
+
+  # With Trackio monitoring
+  uv run unsloth_sft_example.py \\
+      --dataset mlabonne/FineTome-100k \\
+      --num-epochs 1 \\
+      --output-repo username/model-finetuned \\
+      --trackio-space username/trackio
+        """,
+    )
+
+    # Model and data
+    parser.add_argument(
+        "--base-model",
+        default="LiquidAI/LFM2.5-1.2B-Instruct",
+        help="Base model (default: LiquidAI/LFM2.5-1.2B-Instruct)",
+    )
+    parser.add_argument(
+        "--dataset",
+        required=True,
+        help="Dataset in ShareGPT/conversation format (e.g., mlabonne/FineTome-100k)",
+    )
+    parser.add_argument(
+        "--output-repo",
+        required=True,
+        help="HF Hub repo to push model to (e.g., 'username/model-finetuned')",
+    )
+
+    # Training config
+    parser.add_argument(
+        "--num-epochs",
+        type=float,
+        default=None,
+        help="Number of epochs (default: None). Use instead of --max-steps.",
+    )
+    parser.add_argument(
+        "--max-steps",
+        type=int,
+        default=None,
+        help="Training steps (default: None). Use for quick tests or streaming.",
+    )
+    parser.add_argument(
+        "--batch-size",
+        type=int,
+        default=2,
+        help="Per-device batch size (default: 2)",
+    )
+    parser.add_argument(
+        "--gradient-accumulation",
+        type=int,
+        default=4,
+        help="Gradient accumulation steps (default: 4). Effective batch = batch-size * this",
+    )
+    parser.add_argument(
+        "--learning-rate",
+        type=float,
+        default=2e-4,
+        help="Learning rate (default: 2e-4)",
+    )
+    parser.add_argument(
+        "--max-seq-length",
+        type=int,
+        default=2048,
+        help="Maximum sequence length (default: 2048)",
+    )
+
+    # LoRA config
+    parser.add_argument(
+        "--lora-r",
+        type=int,
+        default=16,
+        help="LoRA rank (default: 16). Higher = more capacity but more VRAM",
+    )
+    parser.add_argument(
+        "--lora-alpha",
+        type=int,
+        default=16,
+        help="LoRA alpha (default: 16). Same as r per Unsloth recommendation",
+    )
+
+    # Logging
+    parser.add_argument(
+        "--trackio-space",
+        default=None,
+        help="HF Space for Trackio dashboard (e.g., 'username/trackio')",
+    )
+    parser.add_argument(
+        "--run-name",
+        default=None,
+        help="Custom run name for Trackio (default: auto-generated)",
+    )
+    parser.add_argument(
+        "--save-local",
+        default="unsloth-output",
+        help="Local directory to save model (default: unsloth-output)",
+    )
+
+    # Evaluation and data control
+    parser.add_argument(
+        "--eval-split",
+        type=float,
+        default=0.0,
+        help="Fraction of data for evaluation (0.0-0.5). Default: 0.0 (no eval)",
+    )
+    parser.add_argument(
+        "--num-samples",
+        type=int,
+        default=None,
+        help="Limit samples (default: None = use all)",
+    )
+    parser.add_argument(
+        "--seed",
+        type=int,
+        default=3407,
+        help="Random seed for reproducibility (default: 3407)",
+    )
+    parser.add_argument(
+        "--merge-model",
+        action="store_true",
+        default=False,
+        help="Merge LoRA weights into base model before uploading (larger file, easier to use)",
+    )
+
+    return parser.parse_args()
+
+
+def main():
+    args = parse_args()
+
+    # Validate epochs/steps configuration
+    if not args.num_epochs and not args.max_steps:
+        args.num_epochs = 1
+        logger.info("Using default --num-epochs=1")
+
+    # Determine training duration display
+    if args.num_epochs:
+        duration_str = f"{args.num_epochs} epoch(s)"
+    else:
+        duration_str = f"{args.max_steps} steps"
+
+    print("=" * 70)
+    print("LLM Fine-tuning with Unsloth")
+    print("=" * 70)
+    print("\nConfiguration:")
+    print(f"  Base model:      {args.base_model}")
+    print(f"  Dataset:         {args.dataset}")
+    print(f"  Num samples:     {args.num_samples or 'all'}")
+    print(f"  Eval split:      {args.eval_split if args.eval_split > 0 else '(disabled)'}")
+    print(f"  Seed:            {args.seed}")
+    print(f"  Training:        {duration_str}")
+    print(f"  Batch size:      {args.batch_size} x {args.gradient_accumulation} = {args.batch_size * args.gradient_accumulation}")
+    print(f"  Learning rate:   {args.learning_rate}")
+    print(f"  LoRA rank:       {args.lora_r}")
+    print(f"  Max seq length:  {args.max_seq_length}")
+    print(f"  Output repo:     {args.output_repo}")
+    print(f"  Trackio space:   {args.trackio_space or '(not configured)'}")
+    print()
+
+    # Check CUDA before heavy imports
+    check_cuda()
+
+    # Enable fast transfers
+    os.environ["HF_HUB_ENABLE_HF_TRANSFER"] = "1"
+
+    # Set Trackio space if provided
+    if args.trackio_space:
+        os.environ["TRACKIO_SPACE_ID"] = args.trackio_space
+        logger.info(f"Trackio dashboard: https://huggingface.co/spaces/{args.trackio_space}")
+
+    # Import heavy dependencies
+    from unsloth import FastLanguageModel
+    from unsloth.chat_templates import standardize_data_formats, train_on_responses_only
+    from datasets import load_dataset
+    from trl import SFTTrainer, SFTConfig
+    from huggingface_hub import login
+
+    # Login to Hub
+    token = os.environ.get("HF_TOKEN") or os.environ.get("hfjob")
+    if token:
+        login(token=token)
+        logger.info("Logged in to Hugging Face Hub")
+    else:
+        logger.warning("HF_TOKEN not set - model upload may fail")
+
+    # 1. Load model
+    print("\n[1/5] Loading model...")
+    start = time.time()
+
+    model, tokenizer = FastLanguageModel.from_pretrained(
+        model_name=args.base_model,
+        max_seq_length=args.max_seq_length,
+        load_in_4bit=False,
+        load_in_8bit=False,
+        load_in_16bit=True,
+        full_finetuning=False,
+    )
+
+    # Add LoRA adapters
+    model = FastLanguageModel.get_peft_model(
+        model,
+        r=args.lora_r,
+        target_modules=["q_proj", "k_proj", "v_proj", "out_proj", "in_proj", "w1", "w2", "w3"],
+        lora_alpha=args.lora_alpha,
+        lora_dropout=0,
+        bias="none",
+        use_gradient_checkpointing="unsloth",
+        random_state=args.seed,
+        use_rslora=False,
+        loftq_config=None,
+    )
+    print(f"Model loaded in {time.time() - start:.1f}s")
+
+    # 2. Load and prepare dataset
+    print("\n[2/5] Loading dataset...")
+    start = time.time()
+
+    dataset = load_dataset(args.dataset, split="train")
+    print(f"  Dataset has {len(dataset)} total samples")
+
+    if args.num_samples:
+        dataset = dataset.select(range(min(args.num_samples, len(dataset))))
+        print(f"  Limited to {len(dataset)} samples")
+
+    # Auto-detect and normalize conversation column
+    for col in ["messages", "conversations", "conversation"]:
+        if col in dataset.column_names and isinstance(dataset[0][col], list):
+            if col != "conversations":
+                dataset = dataset.rename_column(col, "conversations")
+            break
+    dataset = standardize_data_formats(dataset)
+
+    # Apply chat template
+    def formatting_prompts_func(examples):
+        texts = tokenizer.apply_chat_template(
+            examples["conversations"],
+            tokenize=False,
+            add_generation_prompt=False,
+        )
+        # Remove BOS token to avoid duplicates
+        return {"text": [x.removeprefix(tokenizer.bos_token) for x in texts]}
+
+    dataset = dataset.map(formatting_prompts_func, batched=True)
+
+    # Split for evaluation if requested
+    if args.eval_split > 0:
+        split = dataset.train_test_split(test_size=args.eval_split, seed=args.seed)
+        train_data = split["train"]
+        eval_data = split["test"]
+        print(f"  Train: {len(train_data)} samples, Eval: {len(eval_data)} samples")
+    else:
+        train_data = dataset
+        eval_data = None
+
+    print(f"  Dataset ready in {time.time() - start:.1f}s")
+
+    # 3. Configure trainer
+    print("\n[3/5] Configuring trainer...")
+
+    # Calculate steps per epoch for logging/eval intervals
+    effective_batch = args.batch_size * args.gradient_accumulation
+    num_samples = len(train_data)
+    steps_per_epoch = num_samples // effective_batch
+
+    # Determine run name and logging steps
+    if args.run_name:
+        run_name = args.run_name
+    elif args.num_epochs:
+        run_name = f"unsloth-sft-{args.num_epochs}ep"
+    else:
+        run_name = f"unsloth-sft-{args.max_steps}steps"
+
+    if args.num_epochs:
+        logging_steps = max(1, steps_per_epoch // 10)
+        save_steps = max(1, steps_per_epoch // 4)
+    else:
+        logging_steps = max(1, args.max_steps // 20)
+        save_steps = max(1, args.max_steps // 4)
+
+    # Determine reporting backend
+    if args.trackio_space:
+        report_to = ["tensorboard", "trackio"]
+    else:
+        report_to = ["tensorboard"]
+
+    training_config = SFTConfig(
+        output_dir=args.save_local,
+        dataset_text_field="text",
+        per_device_train_batch_size=args.batch_size,
+        gradient_accumulation_steps=args.gradient_accumulation,
+        warmup_steps=5,
+        num_train_epochs=args.num_epochs if args.num_epochs else 1,
+        max_steps=args.max_steps if args.max_steps else -1,
+        learning_rate=args.learning_rate,
+        logging_steps=logging_steps,
+        optim="adamw_8bit",
+        weight_decay=0.01,
+        lr_scheduler_type="linear",
+        seed=args.seed,
+        max_length=args.max_seq_length,
+        report_to=report_to,
+        run_name=run_name,
+        push_to_hub=True,
+        hub_model_id=args.output_repo,
+        save_steps=save_steps,
+        save_total_limit=3,
+    )
+
+    # Add evaluation config if eval is enabled
+    if eval_data:
+        if args.num_epochs:
+            training_config.eval_strategy = "epoch"
+            print("  Evaluation enabled: every epoch")
+        else:
+            training_config.eval_strategy = "steps"
+            training_config.eval_steps = max(1, args.max_steps // 5)
+            print(f"  Evaluation enabled: every {training_config.eval_steps} steps")
+
+    trainer = SFTTrainer(
+        model=model,
+        tokenizer=tokenizer,
+        train_dataset=train_data,
+        eval_dataset=eval_data,
+        args=training_config,
+    )
+
+    # Train on responses only (mask user inputs)
+    trainer = train_on_responses_only(
+        trainer,
+        instruction_part="<|im_start|>user\n",
+        response_part="<|im_start|>assistant\n",
+    )
+
+    # 4. Train
+    print(f"\n[4/5] Training for {duration_str}...")
+    if args.num_epochs:
+        print(f"  (~{steps_per_epoch} steps/epoch, {int(steps_per_epoch * args.num_epochs)} total steps)")
+    start = time.time()
+
+    train_result = trainer.train()
+
+    train_time = time.time() - start
+    total_steps = train_result.metrics.get("train_steps", args.max_steps or steps_per_epoch * args.num_epochs)
+    print(f"\nTraining completed in {train_time / 60:.1f} minutes")
+    print(f"  Speed: {total_steps / train_time:.2f} steps/s")
+
+    # Print training metrics
+    train_loss = train_result.metrics.get("train_loss")
+    if train_loss:
+        print(f"  Final train loss: {train_loss:.4f}")
+
+    # Print eval results if eval was enabled
+    if eval_data:
+        print("\nRunning final evaluation...")
+        try:
+            eval_results = trainer.evaluate()
+            eval_loss = eval_results.get("eval_loss")
+            if eval_loss:
+                print(f"  Final eval loss: {eval_loss:.4f}")
+                if train_loss:
+                    ratio = eval_loss / train_loss
+                    if ratio > 1.5:
+                        print(f"  Warning: Eval loss is {ratio:.1f}x train loss - possible overfitting")
+                    else:
+                        print(f"  Eval/train ratio: {ratio:.2f} - model generalizes well")
+        except Exception as e:
+            print(f"  Warning: Final evaluation failed: {e}")
+            print("  Continuing to save model...")
+
+    # 5. Save and push
+    print("\n[5/5] Saving model...")
+
+    if args.merge_model:
+        print("Merging LoRA weights into base model...")
+        print(f"\nPushing merged model to {args.output_repo}...")
+        model.push_to_hub_merged(
+            args.output_repo,
+            tokenizer=tokenizer,
+            save_method="merged_16bit",
+        )
+        print(f"Merged model available at: https://huggingface.co/{args.output_repo}")
+    else:
+        model.save_pretrained(args.save_local)
+        tokenizer.save_pretrained(args.save_local)
+        print(f"Saved locally to {args.save_local}/")
+
+        print(f"\nPushing adapter to {args.output_repo}...")
+        model.push_to_hub(args.output_repo, tokenizer=tokenizer)
+        print(f"Adapter available at: https://huggingface.co/{args.output_repo}")
+
+    print("\n" + "=" * 70)
+    print("Done!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) == 1:
+        print("=" * 70)
+        print("LLM Fine-tuning with Unsloth")
+        print("=" * 70)
+        print("\nFine-tune language models with optional train/eval split.")
+        print("\nFeatures:")
+        print("  - ~60% less VRAM with Unsloth optimizations")
+        print("  - 2x faster training vs standard methods")
+        print("  - Epoch-based or step-based training")
+        print("  - Optional evaluation to detect overfitting")
+        print("  - Trains only on assistant responses (masked user inputs)")
+        print("\nEpoch-based training:")
+        print("\n  uv run unsloth_sft_example.py \\")
+        print("      --dataset mlabonne/FineTome-100k \\")
+        print("      --num-epochs 1 \\")
+        print("      --eval-split 0.2 \\")
+        print("      --output-repo your-username/model-finetuned")
+        print("\nHF Jobs example:")
+        print("\n  hf jobs uv run unsloth_sft_example.py \\")
+        print("      --flavor a10g-small --secrets HF_TOKEN --timeout 4h \\")
+        print("      -- --dataset mlabonne/FineTome-100k \\")
+        print("         --num-epochs 1 \\")
+        print("         --eval-split 0.2 \\")
+        print("         --output-repo your-username/model-finetuned")
+        print("\nFor full help: uv run unsloth_sft_example.py --help")
+        print("=" * 70)
+        sys.exit(0)
+
+    main()

.agents/skills/huggingface-local-models/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: huggingface-local-models
+description: "Use to select models to run locally with llama.cpp and GGUF on CPU, Mac Metal, CUDA, or ROCm. Covers finding GGUFs, quant selection, running servers, exact GGUF file lookup, conversion, and OpenAI-compatible local serving."
+---
+
+# Hugging Face Local Models
+
+Search the Hugging Face Hub for llama.cpp-compatible GGUF repos, choose the right quant, and launch the model with `llama-cli` or `llama-server`.
+
+## Default Workflow
+
+1. Search the Hub with `apps=llama.cpp`.
+2. Open `https://huggingface.co/<repo>?local-app=llama.cpp`.
+3. Prefer the exact HF local-app snippet and quant recommendation when it is visible.
+4. Confirm exact `.gguf` filenames with `https://huggingface.co/api/models/<repo>/tree/main?recursive=true`.
+5. Launch with `llama-cli -hf <repo>:<QUANT>` or `llama-server -hf <repo>:<QUANT>`.
+6. Fall back to `--hf-repo` plus `--hf-file` when the repo uses custom file naming.
+7. Convert from Transformers weights only if the repo does not already expose GGUF files.
+
+## Quick Start
+
+### Install llama.cpp
+
+```bash
+brew install llama.cpp
+winget install llama.cpp
+```
+
+```bash
+git clone https://github.com/ggml-org/llama.cpp
+cd llama.cpp
+make
+```
+
+### Authenticate for gated repos
+
+```bash
+hf auth login
+```
+
+### Search the Hub
+
+```text
+https://huggingface.co/models?apps=llama.cpp&sort=trending
+https://huggingface.co/models?search=Qwen3.6&apps=llama.cpp&sort=trending
+https://huggingface.co/models?search=<term>&apps=llama.cpp&num_parameters=min:0,max:24B&sort=trending
+```
+
+### Run directly from the Hub
+
+```bash
+llama-cli -hf unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q4_K_M
+llama-server -hf unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q4_K_M
+```
+
+### Run an exact GGUF file
+
+```bash
+llama-server \
+    --hf-repo unsloth/Qwen3.6-35B-A3B-GGUF \
+    --hf-file Qwen3.6-35B-A3B-UD-Q4_K_M.gguf \
+    -c 4096
+```
+
+### Convert only when no GGUF is available
+
+```bash
+hf download <repo-without-gguf> --local-dir ./model-src
+python convert_hf_to_gguf.py ./model-src \
+    --outfile model-f16.gguf \
+    --outtype f16
+llama-quantize model-f16.gguf model-q4_k_m.gguf Q4_K_M
+```
+
+### Smoke test a local server
+
+```bash
+llama-server -hf unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q4_K_M
+```
+
+```bash
+curl http://localhost:8080/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer no-key" \
+  -d '{
+    "messages": [
+      {"role": "user", "content": "Write a limerick about exception handling"}
+    ]
+  }'
+```
+
+## Quant Choice
+
+- Prefer the exact quant that HF marks as compatible on the `?local-app=llama.cpp` page.
+- Keep repo-native labels such as `UD-Q4_K_M` instead of normalizing them.
+- Default to `Q4_K_M` unless the repo page or hardware profile suggests otherwise.
+- Prefer `Q5_K_M` or `Q6_K` for code or technical workloads when memory allows.
+- Consider `Q3_K_M`, `Q4_K_S`, or repo-specific `IQ` / `UD-*` variants for tighter RAM or VRAM budgets.
+- Treat `mmproj-*.gguf` files as projector weights, not the main checkpoint.
+
+## Load References
+
+- Read [hub-discovery.md](references/hub-discovery.md) for URL-first workflows, model search, tree API extraction, and command reconstruction.
+- Read [quantization.md](references/quantization.md) for format tables, model scaling, quality tradeoffs, and `imatrix`.
+- Read [hardware.md](references/hardware.md) for Metal, CUDA, ROCm, or CPU build and acceleration details.
+
+## Resources
+
+- llama.cpp: `https://github.com/ggml-org/llama.cpp`
+- Hugging Face GGUF + llama.cpp docs: `https://huggingface.co/docs/hub/gguf-llamacpp`
+- Hugging Face Local Apps docs: `https://huggingface.co/docs/hub/main/local-apps`
+- Hugging Face Local Agents docs: `https://huggingface.co/docs/hub/agents-local`
+- GGUF converter Space: `https://huggingface.co/spaces/ggml-org/gguf-my-repo`

.agents/skills/huggingface-local-models/references/hardware.md

@@ -0,0 +1,38 @@
+## Hardware Acceleration
+
+### Apple Silicon (Metal)
+
+```bash
+make clean && make GGML_METAL=1
+llama-cli -m model.gguf -ngl 99 -p "Hello"
+```
+
+### NVIDIA (CUDA)
+
+```bash
+make clean && make GGML_CUDA=1
+llama-cli -m model.gguf -ngl 35 -p "Hello"
+
+# Hybrid for large models
+llama-cli -m llama-70b.Q4_K_M.gguf -ngl 20
+
+# Multi-GPU split
+llama-cli -m large-model.gguf --tensor-split 0.5,0.5 -ngl 60
+```
+
+### AMD (ROCm)
+
+```bash
+make LLAMA_HIP=1
+llama-cli -m model.gguf -ngl 999
+```
+
+### CPU
+
+```bash
+# Match physical cores, not logical threads
+llama-cli -m model.gguf -t 8 -p "Hello"
+
+# BLAS acceleration
+make LLAMA_OPENBLAS=1
+```

.agents/skills/huggingface-local-models/references/hub-discovery.md

@@ -0,0 +1,178 @@
+# Hugging Face URL Workflows for llama.cpp
+
+Use URL-only workflows first. Do not require `hf` or API clients just to find GGUF files, choose a quant, or build a `llama-server` command.
+
+## Contents
+
+- Core URLs
+- Search for llama.cpp-compatible models
+- Use the local-app page for the recommended quant
+- Confirm exact files from the tree API
+- Build the command
+- Example: `unsloth/Qwen3.6-35B-A3B-GGUF`
+- Notes
+
+## Core URLs
+
+```text
+Search:
+https://huggingface.co/models?apps=llama.cpp&sort=trending
+
+Search with text:
+https://huggingface.co/models?search=<term>&apps=llama.cpp&sort=trending
+
+Search with size bounds:
+https://huggingface.co/models?search=<term>&apps=llama.cpp&num_parameters=min:0,max:24B&sort=trending
+
+Repo local-app view:
+https://huggingface.co/<repo>?local-app=llama.cpp
+
+Repo tree API:
+https://huggingface.co/api/models/<repo>/tree/main?recursive=true
+
+Repo file tree:
+https://huggingface.co/<repo>/tree/main
+```
+
+## 1. Search for llama.cpp-compatible models
+
+Start from the models page with `apps=llama.cpp`.
+
+Use:
+
+- `search=<term>` for model family names such as `Qwen`, `Gemma`, `Phi`, or `Mistral`
+- `num_parameters=min:0,max:24B` or similar if the user has hardware limits
+- `sort=trending` when the user wants popular repos right now
+
+Do not start with random GGUF repos if the user has not chosen a model family yet. Search first, shortlist second.
+
+Example: https://huggingface.co/models?search=Qwen&apps=llama.cpp&num_parameters=min:0,max:24B&sort=trending
+
+## 2. Use the local-app page for the recommended quant
+
+Open:
+
+```text
+https://huggingface.co/<repo>?local-app=llama.cpp
+```
+
+Extract, in order:
+
+1. The exact `Use this model` snippet, if it is visible as text
+2. The `Hardware compatibility` section from the fetched page text or HTML:
+   - quant label
+   - file size
+   - bit-depth grouping
+3. Any extra launch flags shown in the snippet, such as `--jinja`
+
+Treat the HF local-app snippet as the source of truth when it is visible.
+
+Do this by reading the URL itself, not by assuming the UI rendered in a browser. If the fetched page source does not expose `Hardware compatibility`, say that the section was not text-visible and fall back to the tree API plus generic guidance from `quantization.md`.
+
+## 3. Confirm exact files from the tree API
+
+Open:
+
+```text
+https://huggingface.co/api/models/<repo>/tree/main?recursive=true
+```
+
+Treat the JSON response as the source of truth for repo inventory.
+
+Keep entries where:
+
+- `type` is `file`
+- `path` ends with `.gguf`
+
+Use these fields:
+
+- `path` for the filename and subdirectory
+- `size` for the byte size
+- optionally `lfs.size` to confirm the LFS payload size
+
+Separate files into:
+
+- quantized single-file checkpoints, for example `Qwen3.6-35B-A3B-UD-Q4_K_M.gguf`
+- projector weights, usually `mmproj-*.gguf`
+- BF16 shard files, usually under `BF16/`
+- everything else
+
+Ignore unless the user asks:
+
+- `README.md`
+- imatrix or calibration blobs
+
+Use `https://huggingface.co/<repo>/tree/main` only as a human fallback if the API endpoint fails or the user wants the web view.
+
+## 4. Build the command
+
+Preferred order:
+
+1. Copy the exact HF snippet from the local-app page
+2. If the page gives a clean quant label, use shorthand selection:
+
+```bash
+llama-server -hf <repo>:<QUANT>
+```
+
+3. If you need an exact file from the tree API, use the file-specific form:
+
+```bash
+llama-server --hf-repo <repo> --hf-file <filename.gguf>
+```
+
+4. For CLI usage instead of a server, use:
+
+```bash
+llama-cli -hf <repo>:<QUANT>
+```
+
+Use the exact-file form when the repo uses custom labels or nonstandard naming that could make `:<QUANT>` ambiguous.
+
+## 5. Example: `unsloth/Qwen3.6-35B-A3B-GGUF`
+
+Use these URLs:
+
+```text
+https://huggingface.co/unsloth/Qwen3.6-35B-A3B-GGUF?local-app=llama.cpp
+https://huggingface.co/api/models/unsloth/Qwen3.6-35B-A3B-GGUF/tree/main?recursive=true
+https://huggingface.co/unsloth/Qwen3.6-35B-A3B-GGUF/tree/main
+```
+
+On the local-app page, the hardware compatibility section can expose entries such as:
+
+- `UD-IQ4_XS` - 17.7 GB
+- `UD-Q4_K_S` - 20.9 GB
+- `UD-Q4_K_M` - 22.1 GB
+- `UD-Q5_K_M` - 26.5 GB
+- `UD-Q6_K` - 29.3 GB
+- `Q8_0` - 36.9 GB
+
+On the tree API, you can confirm exact filenames such as:
+
+- `Qwen3.6-35B-A3B-UD-Q4_K_M.gguf`
+- `Qwen3.6-35B-A3B-UD-Q5_K_M.gguf`
+- `Qwen3.6-35B-A3B-UD-Q6_K.gguf`
+- `Qwen3.6-35B-A3B-Q8_0.gguf`
+- `mmproj-F16.gguf`
+
+Good final output for this repo:
+
+```text
+Repo: unsloth/Qwen3.6-35B-A3B-GGUF
+Recommended quant from HF: UD-Q4_K_M (22.1 GB)
+llama-server: llama-server --hf-repo unsloth/Qwen3.6-35B-A3B-GGUF --hf-file Qwen3.6-35B-A3B-UD-Q4_K_M.gguf
+Other GGUFs:
+- Qwen3.6-35B-A3B-UD-Q5_K_M.gguf - 26.5 GB
+- Qwen3.6-35B-A3B-UD-Q6_K.gguf - 29.3 GB
+- Qwen3.6-35B-A3B-Q8_0.gguf - 36.9 GB
+Projector:
+- mmproj-F16.gguf - 899 MB
+```
+
+## Notes
+
+- Repo-specific quant labels matter. Do not rewrite `UD-Q4_K_M` to `Q4_K_M` unless the page itself does.
+- `mmproj` files are projector weights for multimodal models, not the main language model checkpoint.
+- If the HF hardware compatibility panel is missing because the user has no hardware profile configured, or because the fetched page source did not expose it, still use the tree API plus generic quant guidance from `quantization.md`.
+- If the repo already has GGUFs, do not jump straight to conversion workflows.

.agents/skills/huggingface-local-models/references/quantization.md

@@ -0,0 +1,256 @@
+# GGUF Quantization Guide
+
+Complete guide to GGUF quantization formats and model conversion.
+
+## Contents
+
+- Hub-first quant selection
+- Quantization Formats
+- Converting Models
+- K-Quantization Methods
+- Quality Testing
+- Use Case Guide
+- Model Size Scaling
+- Finding Pre-Quantized Models
+- Importance Matrices (`imatrix`)
+- Troubleshooting
+
+## Hub-first quant selection
+
+Before using generic tables, open the model repo with:
+
+```text
+https://huggingface.co/<repo>?local-app=llama.cpp
+```
+
+Prefer the exact quant labels and sizes shown in the `Hardware compatibility` section of the fetched `?local-app=llama.cpp` page text or HTML. Then confirm the matching filenames in:
+
+```text
+https://huggingface.co/api/models/<repo>/tree/main?recursive=true
+```
+
+Use the Hub page first, and only fall back to the generic heuristics below when the repo page does not expose a clear recommendation.
+
+## Quantization Formats
+
+**GGUF** (GPT-Generated Unified Format) - Standard format for llama.cpp models.
+
+### Format Comparison
+
+| Format | Perplexity | Size (7B) | Tokens/sec | Notes |
+|--------|------------|-----------|------------|-------|
+| FP16 | 5.9565 (baseline) | 13.0 GB | 15 tok/s | Original quality |
+| Q8_0 | 5.9584 (+0.03%) | 7.0 GB | 25 tok/s | Nearly lossless |
+| **Q6_K** | 5.9642 (+0.13%) | 5.5 GB | 30 tok/s | Best quality/size |
+| **Q5_K_M** | 5.9796 (+0.39%) | 4.8 GB | 35 tok/s | Balanced |
+| **Q4_K_M** | 6.0565 (+1.68%) | 4.1 GB | 40 tok/s | **Recommended** |
+| Q4_K_S | 6.1125 (+2.62%) | 3.9 GB | 42 tok/s | Faster, lower quality |
+| Q3_K_M | 6.3184 (+6.07%) | 3.3 GB | 45 tok/s | Small models only |
+| Q2_K | 6.8673 (+15.3%) | 2.7 GB | 50 tok/s | Not recommended |
+
+**Recommendation**: Use **Q4_K_M** for best balance of quality and speed.
+
+## Converting Models
+
+### Hugging Face to GGUF
+
+```bash
+# 1. Download Hugging Face model
+hf download meta-llama/Llama-2-7b-chat-hf \
+    --local-dir models/llama-2-7b-chat/
+
+# 2. Convert to FP16 GGUF
+python convert_hf_to_gguf.py \
+    models/llama-2-7b-chat/ \
+    --outtype f16 \
+    --outfile models/llama-2-7b-chat-f16.gguf
+
+# 3. Quantize to Q4_K_M
+./llama-quantize \
+    models/llama-2-7b-chat-f16.gguf \
+    models/llama-2-7b-chat-Q4_K_M.gguf \
+    Q4_K_M
+```
+
+### Batch quantization
+
+```bash
+# Quantize to multiple formats
+for quant in Q4_K_M Q5_K_M Q6_K Q8_0; do
+    ./llama-quantize \
+        model-f16.gguf \
+        model-${quant}.gguf \
+        $quant
+done
+```
+
+## K-Quantization Methods
+
+**K-quants** use mixed precision for better quality:
+- Attention weights: Higher precision
+- Feed-forward weights: Lower precision
+
+**Variants**:
+- `_S` (Small): Faster, lower quality
+- `_M` (Medium): Balanced (recommended)
+- `_L` (Large): Better quality, larger size
+
+**Example**: `Q4_K_M`
+- `Q4`: 4-bit quantization
+- `K`: Mixed precision method
+- `M`: Medium quality
+
+## Quality Testing
+
+```bash
+# Calculate perplexity (quality metric)
+./llama-perplexity \
+    -m model.gguf \
+    -f wikitext-2-raw/wiki.test.raw \
+    -c 512
+
+# Lower perplexity = better quality
+# Baseline (FP16): ~5.96
+# Q4_K_M: ~6.06 (+1.7%)
+# Q2_K: ~6.87 (+15.3% - too much degradation)
+```
+
+## Use Case Guide
+
+### General purpose (chatbots, assistants)
+```
+Q4_K_M - Best balance
+Q5_K_M - If you have extra RAM
+```
+
+### Code generation
+```
+Q5_K_M or Q6_K - Higher precision helps with code
+```
+
+### Creative writing
+```
+Q4_K_M - Sufficient quality
+Q3_K_M - Acceptable for draft generation
+```
+
+### Technical/medical
+```
+Q6_K or Q8_0 - Maximum accuracy
+```
+
+### Edge devices (Raspberry Pi)
+```
+Q2_K or Q3_K_S - Fit in limited RAM
+```
+
+## Model Size Scaling
+
+### 7B parameter models
+
+| Format | Size | RAM needed |
+|--------|------|------------|
+| Q2_K | 2.7 GB | 5 GB |
+| Q3_K_M | 3.3 GB | 6 GB |
+| Q4_K_M | 4.1 GB | 7 GB |
+| Q5_K_M | 4.8 GB | 8 GB |
+| Q6_K | 5.5 GB | 9 GB |
+| Q8_0 | 7.0 GB | 11 GB |
+
+### 13B parameter models
+
+| Format | Size | RAM needed |
+|--------|------|------------|
+| Q2_K | 5.1 GB | 8 GB |
+| Q3_K_M | 6.2 GB | 10 GB |
+| Q4_K_M | 7.9 GB | 12 GB |
+| Q5_K_M | 9.2 GB | 14 GB |
+| Q6_K | 10.7 GB | 16 GB |
+
+### 70B parameter models
+
+| Format | Size | RAM needed |
+|--------|------|------------|
+| Q2_K | 26 GB | 32 GB |
+| Q3_K_M | 32 GB | 40 GB |
+| Q4_K_M | 41 GB | 48 GB |
+| Q4_K_S | 39 GB | 46 GB |
+| Q5_K_M | 48 GB | 56 GB |
+
+**Recommendation for 70B**: Use Q3_K_M or Q4_K_S to fit in consumer hardware.
+
+## Finding Pre-Quantized Models
+
+Use the Hub search with the llama.cpp app filter:
+
+```text
+https://huggingface.co/models?apps=llama.cpp&sort=trending
+https://huggingface.co/models?search=<term>&apps=llama.cpp&sort=trending
+https://huggingface.co/models?search=<term>&apps=llama.cpp&num_parameters=min:0,max:24B&sort=trending
+```
+
+For a specific repo, open:
+
+```text
+https://huggingface.co/<repo>?local-app=llama.cpp
+https://huggingface.co/api/models/<repo>/tree/main?recursive=true
+```
+
+Then launch directly from the Hub without extra Hub tooling:
+
+```bash
+llama-cli -hf <repo>:Q4_K_M
+llama-server -hf <repo>:Q4_K_M
+```
+
+If you need the exact file name from the tree API:
+
+```bash
+llama-server --hf-repo <repo> --hf-file <filename.gguf>
+```
+
+## Importance Matrices (imatrix)
+
+**What**: Calibration data to improve quantization quality.
+
+**Benefits**:
+- 10-20% perplexity improvement with Q4
+- Essential for Q3 and below
+
+**Usage**:
+```bash
+# 1. Generate importance matrix
+./llama-imatrix \
+    -m model-f16.gguf \
+    -f calibration-data.txt \
+    -o model.imatrix
+
+# 2. Quantize with imatrix
+./llama-quantize \
+    --imatrix model.imatrix \
+    model-f16.gguf \
+    model-Q4_K_M.gguf \
+    Q4_K_M
+```
+
+**Calibration data**:
+- Use domain-specific text (e.g., code for code models)
+- ~100MB of representative text
+- Higher quality data = better quantization
+
+## Troubleshooting
+
+**Model outputs gibberish**:
+- Quantization too aggressive (Q2_K)
+- Try Q4_K_M or Q5_K_M
+- Verify model converted correctly
+
+**Out of memory**:
+- Use lower quantization (Q4_K_S instead of Q5_K_M)
+- Offload fewer layers to GPU (`-ngl`)
+- Use smaller context (`-c 2048`)
+
+**Slow inference**:
+- Higher quantization uses more compute
+- Q8_0 much slower than Q4_K_M
+- Consider speed vs quality trade-off

.agents/skills/huggingface-lora-space-builder/SKILL.md

@@ -0,0 +1,391 @@
+---
+name: huggingface-lora-space-builder
+description: Build and publish a Gradio demo on Hugging Face Spaces for a user-provided LoRA. Use when someone asks to create, generate, ship, or publish a Space, demo, Gradio app, or playground for a LoRA — including LoRAs for Qwen-Image, Qwen-Image-Edit, LTX-Video, Wan, FLUX, SDXL, or other diffusion base models. Also triggers when someone describes a LoRA they trained or hosts on the Hub and wants to share it. Covers picking the right base pipeline and `diffusers` inference recipe, designing a UI tailored to the LoRA's task and inputs (Union/multi-task control, edit, video, image, etc.), respecting model-card recommendations (trigger words, steps, guidance, LoRA scale, example inputs), and shipping to ZeroGPU hardware as a private Space by default.
+---
+
+# Gradio LoRA Space Builder
+
+Build and publish a Gradio demo on Hugging Face Spaces that runs inference with a user-provided LoRA. Use whenever someone asks to create, generate, ship, or publish "a Space", "a demo", "a Gradio app", or "a playground" for a LoRA — whether the base model is Qwen-Image, Qwen-Image-Edit, LTX, or another diffusion model. Also use when someone describes a LoRA they trained or hosts on the Hub and wants to share it. The default target is ZeroGPU hardware and the default inference library is `diffusers` when the base model supports it.
+
+The output is a real, published Space (private by default) that the user can try in the browser, not a local script.
+
+## What "good" looks like for these demos
+
+The demo should feel handcrafted for this specific LoRA, not a generic template with the LoRA bolted on. Two LoRAs that share a task can still need different demos: a pose-control video LoRA and an outpainting video LoRA both take video in and produce video out, but the inputs the user provides, the preprocessing, and the controls are completely different. Recognizing that is the central job here.
+
+Concretely, a good demo:
+
+- Loads fast and runs fast — minimal model loading, sensible step count, no wasted computation per call.
+- Has a UI with exactly the controls this LoRA needs and nothing else. Excess sliders are a cost, not a feature.
+- Shows the user what's happening — progress, intermediate outputs where useful, the seed used, a clear error when input is missing.
+- Honors the LoRA's own recommendations from its model card: trigger words, recommended step count, recommended guidance scale, recommended LoRA scale, example inputs.
+- Is creative where creativity helps — interactive canvases, before/after sliders, side-by-side previews of intermediate processing — and plain where plainness is right.
+
+## Workflow
+
+Work through these phases in order. Information gathered in one phase decides the next.
+
+1. Gather the LoRA info needed to pick a pipeline and design a UI.
+2. Pick the base pipeline and inference recipe.
+3. Design the UI for this specific LoRA's task and inputs.
+4. Write `app.py`, `requirements.txt`, and `README.md` together; show all three to the user for one batched approval.
+5. Publish the Space (private).
+
+Don't drip-feed questions across multiple turns. Batch them.
+
+---
+
+## Phase 1 — Gather LoRA info
+
+Required: a LoRA repo on the Hub (e.g. `username/my-lora`).
+
+**First, try to read the repo without a token.** If it succeeds, the repo is public — proceed. If it fails with 401/403, the repo is private/gated and you need an authenticated session to read it. **Don't immediately ask for a token.** Check first whether the user is already authenticated.
+
+```python
+from huggingface_hub import HfApi, get_token
+
+cached_token = get_token()  # picks up HF_TOKEN env var or cached CLI login
+if cached_token:
+    try:
+        info = HfApi().whoami(token=cached_token)
+        username = info["name"]
+        # info also has fine-grained token scope info if applicable
+    except Exception:
+        cached_token = None  # token exists but is invalid/expired
+```
+
+Then:
+
+- If a valid cached token exists *and* it can read the repo, use it. No prompt needed.
+- If no cached token, or the cached token can't read this private repo, ask the user for a token — once, with the explanation below.
+
+When asking for a token (and only when you actually need to ask):
+
+> I need a Hugging Face access token with **write** scope (to read the LoRA if it's private/gated, and to publish the Space). Create one at https://huggingface.co/settings/tokens. Paste it here.
+
+The same token will be reused for publishing in the final phase, so this is a one-time ask.
+
+**Then read what's in the repo:**
+
+- List the repo files (`huggingface_hub.HfApi().list_repo_files(repo_id)`). Look for `.safetensors`, `README.md`, example images/videos, multiple checkpoints.
+- Fetch the model card (`huggingface_hub.ModelCard.load(repo_id)`). The `data` dict has structured fields; the `text` has the README body.
+- If multiple `.safetensors` files exist, pick the right one — see "Picking the LoRA weights file" in `references/zerogpu-and-publishing.md`. Briefly: README-recommended file wins, then `pytorch_lora_weights.safetensors`, then latest training checkpoint, otherwise ask.
+
+**From the model card, try to determine:**
+
+- **Base model** — the `base_model` field, or text mentions in the README. Usually present. Use it to pick the pipeline reference file (see Phase 2).
+- **Task** — `pipeline_tag` if set, otherwise inferred from the base model and README text. The five tasks this skill handles: `text-to-image`, `image-to-image`, `text-to-video`, `image-to-video`, `video-to-video`.
+- **Trigger words** — often called "trigger word", "instance prompt", "activation word"; sometimes embedded in example prompts.
+- **Recommended inference recipe** — step count, guidance scale, true CFG scale, LoRA scale, resolution. Many LoRA cards include a Python snippet; trust its *parameters* (steps, guidance, CFG, LoRA scale, dtype). For *loading mechanics*, see `adapting-to-the-lora.md` — prefer `pipe.load_lora_weights(...)` over whatever loading approach the snippet uses.
+- **Example prompts and example media** — use these as Gradio examples in the UI.
+- **Sub-task / specific use case** — for image edits and video LoRAs, "what does this LoRA actually do" matters as much as the task category. A relighting LoRA, a face-swap LoRA, and a style LoRA all might be image-to-image, but the UI for each is different.
+
+**When something can't be inferred, ask the user — once, in a single batched message.** Format the question to make answering trivial. For task category, list the five options as a numbered choice. For sub-task, give a one-line description ("what does this LoRA do? e.g. 'relight portraits', 'apply manga style', 'extend videos to wider aspect ratios'"). Don't ask if you can already infer it confidently from the base model or README.
+
+If the model card has nothing helpful at all — no base model, no task, no example — surface that clearly: "The model card has no usable info. I'll need you to tell me: (1) base model, (2) what this LoRA does, (3) recommended step count and guidance scale if you know them."
+
+---
+
+## Phase 2 — Pick the base pipeline
+
+Two things to decide here: which reference file to load, and which pipeline class to use. They're not the same question — a base-model family file (e.g. `qwen-image.md`) covers multiple variants, and variants in the same family don't always share a pipeline class. Get this wrong and the Space loads but produces wrong output, or fails at startup.
+
+**Step 1 — Load the reference file for this base model family.**
+
+- `references/base-models/qwen-image.md` — covers Qwen-Image and Qwen-Image-Edit family (text-to-image and image-to-image).
+- `references/base-models/ltx.md` — covers LTX family (text-to-video, image-to-video, video-to-video, including IC-LoRAs).
+
+If the base model isn't in one of these files, this skill doesn't have first-class support yet. Tell the user, and ask whether they want to proceed by analogy (use the closest model's recipe and adjust) or stop. Don't guess silently.
+
+**Step 2 — Verify the pipeline class against the base model's own card. This step is mandatory, not optional.**
+
+A new base model variant might use the same pipeline class with a different repo path, or a new pipeline class entirely. Don't trust the reference file's table alone — it's best-effort and can lag a recent release. Verify before committing:
+
+```python
+from huggingface_hub import ModelCard
+base_card = ModelCard.load(base_model_id)
+# Read base_card.text — find the diffusers inference snippet, note the pipeline class it imports.
+```
+
+The class imported in the base model card's diffusers snippet is the source of truth. Real examples where this matters:
+
+- `Qwen-Image-Edit` uses `QwenImageEditPipeline`. `Qwen-Image-Edit-2509` and `Qwen-Image-Edit-2511` use `QwenImageEditPlusPipeline` — different class, different default parameters, takes a list of images instead of one. A LoRA targeting 2511 loaded onto `QwenImageEditPipeline` produces broken output.
+- LTX-Video uses `LTXPipeline`/`LTXImageToVideoPipeline`/`LTXConditionPipeline`. LTX-2 uses `LTX2Pipeline` from a different module path. LTX-2.3 sometimes needs a native pipeline outside diffusers.
+
+If the base model card has no diffusers snippet at all, fall back to the reference file's table — and tell the user you're falling back, in case they know something the table doesn't.
+
+The cost of this verification is one Hub fetch and a few seconds of reading. The cost of skipping it is the failure mode the previous bullet describes — a "working" Space that's quietly using the wrong class.
+
+**Step 3 — Diffusers vs native pipeline.** Default to `diffusers` when the base model has a diffusers pipeline class. That's the case for Qwen-Image and Qwen-Image-Edit and most of LTX. Some LTX variants (notably LTX-2.3 with certain IC-LoRAs) need a native pipeline; the LTX reference says when. Diffusers gives standard `load_lora_weights` / `set_adapters` semantics; the native path needs LoRA-specific glue.
+
+---
+
+## Phase 3 — Design the UI for this LoRA
+
+Don't reach for a template. Reason from the LoRA's task and inputs to a UI.
+
+Read `references/tasks.md` for the per-task baseline UI patterns (what the standard inputs/outputs look like for T2I, I2I, T2V, I2V, V2V).
+
+Then read `references/adapting-to-the-lora.md`, which is about *thinking through what this specific LoRA needs* — beyond the task category. That file is the most important one in this skill. The same task can need very different UIs: a pose-control LTX LoRA needs a video input and a pose-extraction preview; an outpaint LTX LoRA needs an aspect-ratio picker and a black-margin preview; a relighting Flux LoRA needs an image and a brush canvas for indicating where to add light. None of those reduce to "the V2V template" or "the I2I template".
+
+**Self-check before writing the UI.** Write one sentence describing what a user does with this Space in 10 seconds. If that sentence doesn't distinguish this LoRA from any other LoRA of the same task, the UI isn't shaped enough yet.
+
+Examples that pass the self-check:
+
+- "Upload a video, pick a target aspect ratio, click Generate; the model fills the empty margins."
+- "Draw colored brush strokes where you want light, pick an illumination style, click Generate; the model relights the photo."
+- "Upload a video of someone moving and an image of a different character; the model produces a video of the character doing the motion."
+
+Examples that fail:
+
+- "Type a prompt and click generate." (Generic T2I — say more.)
+- "Upload an image and an instruction." (Generic edit — what kind of edit?)
+
+**Gradio component freshness.** Gradio's component set evolves. Before defaulting to plain components, consider whether something newer fits better — for example `gr.ImageSlider` for before/after on edit LoRAs, `gr.BrowserState` for persistent prefs, `@gr.render` for UIs that change based on input. If you're unsure whether a component exists or what its signature is, web-fetch the current Gradio docs at https://www.gradio.app/docs rather than guessing.
+
+**When stock and Hub custom components aren't enough — creative mode.** If the LoRA's natural input is a shape no Gradio component (built-in or on the Hub) expresses well — point sets, strokes, trajectories, multi-region annotations with metadata, 3D rotation gizmos, timeline scrubbers, anything where the user manipulates a thing on top of media — drop down to custom HTML/JS via `gr.HTML`. See `references/creative-mode.md` for the Gradio primitives (`gr.HTML`, `head=` injection, `elem_id` addressing, the two JS↔Python state-sync approaches), the discipline around defining a JSON wire format, and the pitfalls. Don't reach for creative mode just because it would be cool — reach for it when the LoRA's input shape demands it. And don't skip the Hub custom components rung above (e.g. `gradio_image_annotation`) before going fully bespoke.
+
+**`gr.Examples` for media-input Spaces.** When no fitting example media is available from the model's own repo, pull from the shared input pools — split by modality so the HF dataset viewer can render proper thumbnails: images at [`linoyts/repo-to-space-example-inputs`](https://huggingface.co/datasets/linoyts/repo-to-space-example-inputs), videos at [`linoyts/repo-to-space-example-videos`](https://huggingface.co/datasets/linoyts/repo-to-space-example-videos). Both are CC0 with `categories` + natural-language `caption` metadata and the same filter/rank recipe in each dataset README. Pick 2–3 that fit the task, preprocess to the shapes the model expects, and bake the copies into the Space. Set `cache_examples=True, cache_mode="lazy"` so the first click caches without running examples at build time (see `references/zerogpu-and-publishing.md`).
+
+---
+
+## Phase 4 — Write the Space files
+
+Before writing, tell the user concretely what's about to happen — name the actual files. Not "I'll write the three files" but something like:
+
+> "Now I'll write the three files needed to publish a Space: **`app.py`** (the Gradio demo and inference code), **`requirements.txt`** (Python dependencies), and **`README.md`** (Space configuration including ZeroGPU hardware setting). Then I'll show all three for your review before publishing."
+
+This anchors the user in what's being produced. Don't say "three files" without naming them — it's vague and signals lack of commitment to the deliverable.
+
+The three files are tightly coupled: `requirements.txt` is determined by what `app.py` imports, and the `README.md` YAML frontmatter sets the SDK version, hardware, and Space title that have to match. Write them together, then show all three to the user for approval in **one batched message** before publishing.
+
+Read `references/zerogpu-and-publishing.md` for the ZeroGPU rules. The non-obvious ones:
+
+- Models go on `cuda` at module level (not lazy-loaded inside the GPU function). ZeroGPU has a CUDA emulation that makes this work pre-allocation, and module-level placement is significantly faster than deferred placement.
+- The function that runs inference is decorated with `@spaces.GPU(duration=...)`. Pick a duration appropriate for the task — short for image generation, longer for video.
+- Don't use `torch.compile` — it's incompatible with ZeroGPU's process model.
+
+### `app.py`
+
+Compose from the pieces decided in Phases 1–3. Don't paste from a template. Each section should be there because it's needed:
+
+- Imports — `gradio as gr`, `torch`, `spaces`, the pipeline class, anything the preprocessing needs.
+- Constants — `LORA_REPO`, `BASE_MODEL`, recommended step count, guidance, LoRA scale, trigger word.
+- Module-level model load — pipeline `from_pretrained`, `.to("cuda")`, `load_lora_weights`. If the LoRA repo is private, pass `token=os.environ["HF_TOKEN"]`.
+- Preprocessing functions (if any) — pose extraction, padding, mask building, etc. CPU code can run at module level; GPU code needs to be inside a `@spaces.GPU` function.
+- The inference function — decorated with `@spaces.GPU(duration=...)`. Validates inputs, applies trigger word, builds the pipeline kwargs, returns outputs.
+- The Gradio Blocks — the UI from Phase 3, wired to the inference function.
+
+Common things to get right:
+
+- Return the actually-used seed alongside the result so the user can reproduce.
+- `gr.Progress(track_tqdm=True)` on the inference function surfaces diffusers' internal progress bar.
+- Validate inputs — raise `gr.Error("Please upload an image first.")` when a required input is missing, rather than letting the pipeline fail with a cryptic error.
+- On `gr.Examples`, use `cache_examples=True, cache_mode="lazy"` — plain `cache_examples=True` runs examples at build time and fails on ZeroGPU; lazy mode defers caching to the first user click.
+
+### `requirements.txt`
+
+Don't ship a fixed minimal list and hope for the best. The "minimal" list works for plain T2I LoRAs and breaks the moment the base model has a vision-language text encoder, video output, or any non-trivial preprocessing. **Derive `requirements.txt` from what the Space actually needs**, in this order:
+
+1. **Every top-level non-stdlib import in `app.py`.** If `app.py` does `import cv2`, `requirements.txt` has `opencv-python`. If it does `from controlnet_aux import OpenposeDetector`, `requirements.txt` has `controlnet-aux`. Walk the imports mechanically. (Note the exclusions in the next paragraph — some imports are runtime built-ins and don't need to be listed.)
+2. **What the base-model reference's "Required dependencies" subsection says.** Each base-model file lists the non-obvious extras the pipeline pulls in — `torchvision` for Qwen-Image (Qwen 2.5-VL text encoder), `imageio[ffmpeg]` for LTX (video export), etc. Include all of them. These are the deps that aren't picked up from imports because the pipeline's components import them transitively at load time.
+3. **What the LoRA's own model card explicitly mentions installing.** If the LoRA README has its own `pip install` block, lift the deps from there.
+4. **The diffusers/ML stack:** `diffusers`, `transformers`, `accelerate`, `peft`, `safetensors`. Default to plain (unpinned). Switch `diffusers` to `git+https://github.com/huggingface/diffusers` if the base-model reference says the model needs it (recent releases often do — Qwen-Image-Edit-2511 is a current example).
+
+**What *not* to list in `requirements.txt`:**
+
+- **`gradio`** — controlled by the `sdk_version:` field in `README.md`'s YAML frontmatter, not by `requirements.txt`. Listing it in requirements is at best ignored, at worst causes a version conflict with the SDK. Set the version in the README only.
+- **`torch`** — provided by the Space runtime. Only add if you need a specific version pinned (rare, and usually a sign something else is wrong).
+- **`spaces`** — provided by the Space runtime. Only add if you need a specific version pinned.
+- **`huggingface_hub`** — provided by the Space runtime. Only add if you need a specific version pinned.
+
+These four come pre-installed in the ZeroGPU container. Listing them anyway is the kind of "include rather than skip" instinct that's right for non-baseline deps but wrong for baseline ones, because pinning conflicts with the runtime's managed versions.
+
+**Bias for everything else: include rather than skip when uncertain.** A package the Space doesn't actually use causes a slightly slower build. A missing required package causes a startup-time crash that's much harder for the user to diagnose. These costs aren't symmetric — the test failure that prompted this rule was exactly the second kind.
+
+**But two specific deps are *not* safe to add reflexively** because they routinely cause more problems than they solve on ZeroGPU:
+
+- `xformers` — pinned to specific torch versions, frequent source of conflicts. The ZeroGPU runtime ships torch 2.8+, so any pinned `xformers` version must support that. Additional gotcha on Blackwell: xformers' FA3 dispatch mis-gates the hardware (FA3 kernels are Hopper-only at `sm_90a`, but the dispatcher gates on `device_capability >= (9, 0)`, which also matches Blackwell) and crashes at kernel launch with `CUDA invalid argument`. If a Space using xformers attention hits this, disable FA3 dispatch at module load:
+
+  ```python
+  try:
+      from xformers.ops.fmha import _set_use_fa3
+      _set_use_fa3(False)
+  except Exception:
+      pass
+  ```
+
+  Only include `xformers` if `app.py` actually uses it.
+- `flash-attn` — needs a build step, often fails to install. Same torch 2.8+ alignment caveat as `xformers`. Only include if `app.py` actually uses it.
+
+**Pin other versions only when you have a reason** (e.g. a known incompatibility, or matching a recipe from the model card).
+
+### `README.md`
+
+Spaces are configured by the YAML frontmatter at the top of `README.md`. This frontmatter is what selects ZeroGPU.
+
+```
+---
+title: <human-readable title>
+emoji: 🎨
+colorFrom: pink
+colorTo: purple
+sdk: gradio
+sdk_version: <current Gradio version>
+app_file: app.py
+pinned: false
+hardware: zero-a10g
+short_description: <one short line for the Space tile, ~60 chars max>
+models:
+  - <base model repo>
+  - <lora repo>
+---
+
+# <title>
+
+A short description with links to the LoRA and base model.
+```
+
+Key fields:
+
+- `sdk: gradio` — required for ZeroGPU.
+- `sdk_version` — match the Gradio version you wrote against. Look up the current version (`pip index versions gradio`, or check https://www.gradio.app) rather than guessing.
+- `hardware: zero-a10g` — the legacy string for ZeroGPU. The actual hardware is NVIDIA RTX Pro 6000 Blackwell, but the identifier is `zero-a10g`. ZeroGPU is available to PRO, Team, and Enterprise accounts; if the user isn't subscribed, the Space will fall back to CPU. Mention this if you suspect they aren't on PRO.
+- `models:` — list base and LoRA repos. This enables Hub caching and discovery.
+- `short_description` — appears on the Space tile. **Keep it short (~60 characters or less).** The Hub's YAML validator rejects long values with a 400 from `https://huggingface.co/api/validate-yaml`, which surfaces as an `HfHubHTTPError` during `create_repo` or `upload_file`. The exact server-side limit isn't documented and may change, so target the visible-tile-length range rather than pushing right up to a cap. If you do hit the 400, the fix is almost always to shorten this field. One sentence describing what the Space does is plenty — the README body below the YAML is where you put longer prose.
+
+### Single batched approval — order of operations matters
+
+The discipline here is **write all three files first, then show them all together in one message**. Not "write app.py → talk about it → write requirements → talk about it → write README → talk about it." That rhythm produces three approval moments even if you don't explicitly ask for approval, because the user is being asked to react after each file.
+
+Concretely:
+
+1. **Write `app.py`, `requirements.txt`, and `README.md` in succession with no intervening prose.** No commentary between files. No "Now I'll write the next one." No description of what each file does as you produce it. Just the three files, back to back.
+2. **Then, in a single message, ask for approval covering all three at once.** Something like: "Here's the Space — `app.py` (N lines), `requirements.txt`, and `README.md`. Review and confirm to publish, or tell me what to change."
+3. The user responds once, covering whatever they want changed across any of the three files.
+
+What to avoid:
+
+- Walking through `app.py`'s structure or design choices after writing it but before writing the others. Save commentary for either the pre-writing announcement (Phase 4 opening) or the single approval message after all three exist.
+- Asking "ready for the next one?" or "want me to continue with requirements?" — those are implicit per-file approvals.
+- Showing one file inline and offering to "show the next when you're ready" — same trap.
+- Treating any of the three files as optional or as a follow-up. They are produced together as one deliverable.
+
+If the user interrupts after seeing the first file with feedback or a question, that's fine — engage with it — but the rule still applies: the next time you produce code, produce all remaining files together, not one at a time.
+
+---
+
+## Phase 5 — Publish the Space
+
+Use the authenticated session from Phase 1. Default to **private**, so the user can vet the Space before flipping it public. Confirm the target username with the user before creating: "I'll publish to `{username}/{space_name}` — confirm?"
+
+```python
+from huggingface_hub import HfApi, SpaceHardware
+
+api = HfApi(token=hf_token)
+username = api.whoami()["name"]
+repo_id = f"{username}/{space_name}"
+
+api.create_repo(
+    repo_id=repo_id,
+    repo_type="space",
+    space_sdk="gradio",
+    space_hardware=SpaceHardware.ZERO_A10G,
+    private=True,
+    exist_ok=True,
+)
+
+# Upload files
+for path in ["app.py", "requirements.txt", "README.md"]:
+    api.upload_file(path_or_fileobj=path, path_in_repo=path,
+                    repo_id=repo_id, repo_type="space")
+```
+
+If the LoRA repo itself is private/gated, the Space needs the token at runtime to download the LoRA. Set it as a Space secret:
+
+```python
+api.add_space_secret(repo_id=repo_id, key="HF_TOKEN", value=HF_TOKEN)
+```
+
+…and in `app.py`, load the LoRA with `token=os.environ["HF_TOKEN"]`.
+
+**After upload**, run the smoke-test below before sharing — the build runs asynchronously and silent failures (wrong `weight_name`, missing dep, wrong pipeline class) only surface at first inference. **Once the smoke-test passes**, share the Space URL (`https://huggingface.co/spaces/{repo_id}`) and tell the user the Space is private — they'll need to be logged in to view it. Note that the build takes a few minutes; the logs are at `https://huggingface.co/spaces/{repo_id}/logs/container` if anything fails.
+
+**Publish-time failures (before the build starts):**
+
+- **`HfHubHTTPError: 400 Bad Request` from `https://huggingface.co/api/validate-yaml`** during `create_repo` or `upload_file`. The README YAML failed server-side validation. By far the most common cause is a `short_description` that's too long; sometimes a stray field or malformed value. Fix: shorten `short_description` to ~60 characters and retry. If shortening doesn't fix it, look for typos in field names or invalid values (e.g. unsupported colors in `colorFrom`/`colorTo`, an invalid `hardware` string).
+- **403 on `create_repo`** with `space_hardware="zero-a10g"`: user isn't on PRO/Team/Enterprise, so they can't request ZeroGPU at creation time. Fix: retry `create_repo` without `space_hardware`, leave `hardware: zero-a10g` in the README YAML — the Space gets created on CPU. The user can then either upgrade to PRO (auto-promotes to ZeroGPU) or apply for a [community GPU grant](https://huggingface.co/docs/hub/spaces-gpus#community-gpu-grants) (request via the Space's hardware settings).
+- **401/403 on `upload_file`**: token doesn't have write scope. Fix: ask the user for a write-scoped token.
+
+**Common build failures (after the build starts):**
+
+- LoRA `weight_name` mismatch in `load_lora_weights` → check the actual filename via `list_repo_files`.
+- Base model is gated and the token wasn't set as a Space secret.
+- ZeroGPU not allocated (user not on PRO) → Space falls back to CPU and is unusably slow.
+- Diffusers version doesn't recognize the pipeline class → pin to git diffusers in `requirements.txt`.
+- Missing dependency at module load → see `requirements.txt` derivation rules above; the most common case is a transitive dep like `torchvision` for Qwen-Image's text encoder.
+
+If a build fails, offer to read the logs and propose a fix.
+
+---
+
+## Phase 6 — Smoke-test the Space
+
+Before declaring the Space done and handing the URL to the user, exercise it once end-to-end. Several failure modes (wrong `weight_name`, wrong pipeline class, missing transitive dep, gated-base-model token issue) build cleanly and only surface at first inference. The `gradio` Python package ships a CLI that does exactly this — `gradio info` returns the endpoint signature, `gradio predict` runs an actual inference. Both ship with the `gradio` pip dependency the Space already needs, so they're available in any environment where this skill ran.
+
+**Step 1 — Wait for the build.** `create_repo` returns immediately, but the container image is still building. Poll `HfApi().get_space_runtime(repo_id).stage` until it reaches `RUNNING`:
+
+```python
+import time
+from huggingface_hub import HfApi
+api = HfApi(token=hf_token)
+while True:
+    stage = api.get_space_runtime(repo_id).stage
+    if stage == "RUNNING": break
+    if stage in {"BUILD_ERROR", "RUNTIME_ERROR", "CONFIG_ERROR"}:
+        raise RuntimeError(f"Build failed: {stage}. Logs: https://huggingface.co/spaces/{repo_id}/logs/container")
+    time.sleep(15)
+```
+
+If the build fails, fetch the container logs (`https://huggingface.co/spaces/{repo_id}/logs/container`), read the traceback, and propose a fix. Don't run `gradio info` against a Space that isn't running — it'll hang or 503.
+
+**Step 2 — Verify the endpoint signature.** `gradio info {repo_id} --token {hf_token}` returns the exposed endpoints and their parameter types. Read the output and confirm: (a) the endpoint exists (default is `/predict`, but Blocks Spaces often have a custom name from the Python function name), (b) the parameters in order match what `app.py` declares, (c) file-typed params show `"type": "filepath"` as expected. If any of this is off, the user-facing UI may still appear correct but API calls will fail — fix and re-upload.
+
+**Step 3 — Run one real inference.** Pick the lightest viable input — the simplest example from the LoRA card, or one of the `gr.Examples` entries. Pass `--token` for private Spaces. For file inputs, the payload uses `{"path": "...", "meta": {"_type": "gradio.FileData"}}`.
+
+```bash
+# Text-to-image:
+gradio predict {repo_id} /predict '{"prompt": "...", "aspect_ratio": "1:1", ...}' --token $HF_TOKEN
+
+# Image-to-image (file input):
+gradio predict {repo_id} /predict '{"input_image": {"path": "/tmp/sample.jpg", "meta": {"_type": "gradio.FileData"}}, "prompt": "..."}' --token $HF_TOKEN
+```
+
+If you don't have a local sample image for I2I, lift one from the LoRA repo (`hf_hub_download(repo_id, filename="example.png")`) or the base model card.
+
+**Caveat for creative-mode Spaces.** `gradio info` and `gradio predict` only exercise the Python endpoint — they tell you nothing about whether custom JS in a `gr.HTML` widget works. If the Space uses creative mode (see `references/creative-mode.md`), after the API smoke-test passes, **open the Space URL in a browser and verify the interaction once** before sharing. Server-side green plus broken JS is the most common failure mode for these.
+
+**Step 4 — Interpret the result.**
+
+- **Returns successfully and the output looks plausible** → done. Share the URL.
+- **HTTPError 503 / "Space is sleeping"** → the Space spun down between steps 1 and 3. Wake it (`api.restart_space(repo_id)`) and retry.
+- **Inference error mentioning `weight_name` / `safetensors`** → the LoRA filename in `app.py` doesn't match the actual file in the LoRA repo. Re-check `list_repo_files`, fix `weight_name=`, re-upload `app.py`.
+- **Inference error mentioning a missing pipeline class or attribute** → diffusers version too old. Switch `requirements.txt` to `git+https://github.com/huggingface/diffusers` and re-upload.
+- **`ImportError` at module load** → missing dep. Add it to `requirements.txt` and re-upload. The runtime logs (`/logs/run`) name the missing package.
+- **OOM** → reduce default resolution or step count, or pick a smaller base variant.
+- **Timeout / hangs** → bump `@spaces.GPU(duration=...)` and re-upload.
+
+The smoke-test exists to convert these from "user discovers it and reports back" to "you discover it and fix it before sharing." Don't skip it because the build went green — green-build-broken-inference is the most common failure mode for Spaces with a non-trivial pipeline.
+
+---
+
+## What to avoid
+
+- A generic "one demo for all LoRAs" template. The whole point of this skill is to tailor.
+- Lazy-loading the model inside the GPU function. Slow on ZeroGPU, and hides startup errors until first request.
+- `torch.compile`. Not supported on ZeroGPU.
+- `cache_examples=True` without `cache_mode="lazy"` on ZeroGPU.
+- Uploading the LoRA weights into the Space repo. Pull from the LoRA's own Hub repo at runtime.
+- Asking for the HF token only at the end, then discovering the LoRA was private all along and you couldn't read the model card.
+- Exposing every diffusers knob. Pick the 1–3 controls that matter for this LoRA.
+- Long preambles in the chat reply once the Space is published. The Space URL is the deliverable; keep the wrap-up brief.